Whip and Whep Configuration

Enabling WHIP / WHEP

Update the webapp wherein WHIP/WHEP will be enabled within its web.xml file (typically red5pro/webapps/live/WEB-INF/web.xml); there are few sections to add to the webapp.

First, is the filter to prevent processing by other filters in the chain, especially the WebSocket filter; so this one must be placed ahead of the others (Exception is any CORS filter):

    <!-- WHIP/WHEP filter -->
    <filter>
        <filter-name>WHRequestFilter</filter-name>
        <filter-class>com.red5pro.whip.servlet.WHFilter</filter-class>
        <async-supported>false</async-supported>
    </filter>
    <filter-mapping>
        <filter-name>WHRequestFilter</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
    </filter-mapping>

Note: Do not include FORWARD in the filter mapping section

Secondly, the WHIP/WHEP request handlers must be added:

    <!-- WHIP (publisher) endpoint -->
    <servlet>
        <servlet-name>whip</servlet-name>
        <servlet-class>com.red5pro.whip.servlet.WhipEndpoint</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>whip</servlet-name>
        <url-pattern>/whip/endpoint/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>whip</servlet-name>
        <url-pattern>/whip/resource/*</url-pattern>
    </servlet-mapping>
    <!-- WHEP (subscriber) endpoint -->
    <servlet>
        <servlet-name>whep</servlet-name>
        <servlet-class>com.red5pro.whip.servlet.WhepEndpoint</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>whep</servlet-name>
        <url-pattern>/whep/endpoint/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>whep</servlet-name>
        <url-pattern>/whep/resource/*</url-pattern>
    </servlet-mapping>

A reason for WHIP and WHEP using two different servlets, would be separation of functional areas (publish and playback); it also allows a node to support one or both.

Lastly, if using TURN vs STUN, context parameters are required and they reside near the top of the file below display-name or any other context-param nodes:

    <!-- Context level parameters for use in the servlets -->
    <!-- Stun server defaults to enabled with a google stun value
    <context-param>
        <param-name>stun-server</param-name>
        <param-value>stun3.l.google.com:19302</param-value>
    </context-param>
    -->
    <context-param>
        <param-name>turn-server</param-name>
        <param-value>coturn.example.com:3478?transport=udp</param-value>
    </context-param>

Additional details are below for TURN credentials.

Testing may be accomplished with the WHIP/WHEP testbed examples for the plugin, or any other implementations such as simple-whip-client or simple-whep-client (both use GStreamers webrtcbin) which follow the published draft specifications.

Stream Manager Configuration

Update the webapp wherein WHIP/WHEP will be enabled within its web.xml file (typically red5pro/webapps/live/WEB-INF/web.xml)

Replace both servlet-class entries WhipEndpoint and WhepEndpoint with com.red5pro.whip.servlet.WHProxy;

Example:

    <!-- WHIP (publisher) endpoint -->
    <servlet>
        <servlet-name>whip</servlet-name>
        <servlet-class>com.red5pro.whip.servlet.WHProxy</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>whip</servlet-name>
        <url-pattern>/whip/endpoint/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>whip</servlet-name>
        <url-pattern>/whip/resource/*</url-pattern>
    </servlet-mapping>
    <!-- WHEP (subscriber) endpoint -->
    <servlet>
        <servlet-name>whep</servlet-name>
        <servlet-class>com.red5pro.whip.servlet.WHProxy</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>whep</servlet-name>
        <url-pattern>/whep/endpoint/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>whep</servlet-name>
        <url-pattern>/whep/resource/*</url-pattern>
    </servlet-mapping>

In addition to the removal of the webrtc-plugin jar, the inspector plugin jar and webapp should also be removed.

Requests

The initial request for publish or playback would be in this form: http://siteurl/[app]/[whip|whep]/endpoint/[stream name]?[querystring entries]. Follow-up or PATCH requests would use resource like so: http://siteurl/[app]/[whip|whep]/resource/[stream name]; when resource is used, depending on the type of request, there may be headers present useful for lookup such as: If-Match.

Room scopes are supported within the application scope and may be specified in the URL pattern just after [app] in the example above for the POST requests. Example publishing mystream using a room and subscope: https://example.com/live/myroom/desk/whip/endpoint/mystream. In the example live is the application, myroom is the room scope within live and desk is a subscope within myroom.

To provide the fastest negotation and response, TCP candidates are excluded and require the tcp request param as an indication that the server should process TCP candidates along with UDP. The UDP candidate processing alone is the quickest and the default.

In addition, we have a means to request a signaling channel via param in the request keyed as signal; values allow for signal=[0|1] or signal=[false|true] (default value is false).

Simple WHEP Client

Uses mode 1, empty offer SDP.

Cloudflare JS SDK

The WebRTC Hacks crew has a great write-up here: https://webrtchacks.com/how-cloudflare-glares-at-webrtc-with-whip-and-whep/

WHIP

Draft standard WHIP requests, sometimes reording the audio and video m-lines.

WHEP

Uses mode 2, full offer SDP.

The html pages must be updated to reflect the endpoint urls in-use; in addition, the browser must include the matching IP or fqdn used in the endpoint to avoid CORS errors. So an endpoint of http://10.0.0.35:5080/live/whep/endpoint/stream1?requestId=cloudflare will need this in the browsers navbar: http://10.0.0.35:5080/live/cloudflare/whep.html. The examples use stream1 and the request id need only be unique per scope/stream.

First test throws this because we provide the actpass.

negotiateConnectionWithClientOffer.js:59 Uncaught (in promise) DOMException: Failed to execute 'setRemoteDescription' on 'RTCPeerConnection': Failed to set remote answer sdp: Failed to apply the description for m= section with mid='0': Answerer must use either active or passive value for setup attribute.

Credentials for TURN servers

Credentials are configured in the applications web.xml or via request parameters in the OPTIONS fetch; include this section to configure them for the entire webapp:

<context-param>
    <param-name>username</param-name>
    <param-value>testuser</param-value>
</context-param>
<context-param>
    <param-name>credential</param-name>
    <param-value>testpass</param-value>
</context-param>
<context-param>
    <param-name>credential-type</param-name>
    <param-value>password</param-value>
</context-param>

Note for HTTP/S request parameters, use the same names, but with ice- prefixes; such as ice-username=testuser&ice-credential=foo

The STUN and TURN server url entries are not "currently" supported for override via request parameters; they are expected at init via the context param configuration.

<context-param>
    <param-name>stun-server</param-name>
    <param-value>stun2.l.google.com:19302</param-value>
</context-param>
<context-param>
    <param-name>turn-server</param-name>
    <param-value>coturn.example.net:3478?transport=udp</param-value>
</context-param>

Note one, both, or neither may be provided; the defaults are shown in the example

Status Codes

Since WHIP and WHEP are HTTP-based, the HTTP status code system is used; below are the codes used for each situation.

WHIP

200 - Ice fragment on PATCH is okay
201 - Successful request to publish
400 - Invalid offer SDP
400 - Publish failed due to an exception during creation
401 - Not authorized
404 - Scope resolver failed for the publish name and / or scope
406 - Scope connection rejected
409 - Stream is not available to publish
409 - Session already initialized
412 - Invalid request body
417 - Session lookup or creation failure

WHEP

201 - Successful request to playback
204 - Answer SDP or ICE fragment on PATCH is okay
400 - Offer already sent, double POST assumed
401 - Not authorized
404 - Scope resolver failed for the playback name and / or scope
404 - Session not found for PATCH
406 - Scope connection rejected
406 - Playback failed due to an exception during creation
409 - Stream is not available to playback

Whip and Whep Configuration

Enabling WHIP / WHEP

Stream Manager Configuration

Requests

Simple WHEP Client

Cloudflare JS SDK

WHIP

WHEP

Credentials for TURN servers

Status Codes

WHIP

WHEP

Red5 Pro Platform