Set up WebRTC streaming with Wowza Streaming Engine
Originally Published on 06/01/2017 | Updated on 04/08/2021 9:53 am PDT
Wowza Streaming Engine™ media server software version 4.7.7 and later supports WebRTC streaming, however, we recommend that you update to version 4.8.5 and later to capitalize on expanded functionality and enhancements to publisher reliability. WebRTC is a free, open-source project that enables real-time communication of audio, video, and data in web browsers and mobile applications. Wowza Streaming Engine can ingest source WebRTC audio and video content and deliver it to supporting players. It can also transmux or transcode WebRTC to other streaming protocols, including HLS, MPEG-DASH, RTMP, and RTSP. In addition, Wowza Streaming Engine can ingest a non-WebRTC source stream and play it back with WebRTC or WebRTC plus other scalable HTTP-based streaming protocols like HLS.
In this article, learn how to set up WebRTC streaming using Wowza Streaming Engine XML configuration files. For instructions using Wowza Streaming Engine Manager to configure WebRTC instead, see Set up WebRTC streaming with Wowza Streaming Engine Manager.
Note: This article assumes a new installation of Wowza Streaming Engine 4.7.7 or later. If you've updated from an earlier version, you must copy and paste content from the sample WebRTC Application.xml file into your Application.xml file.
About WebRTC in Wowza Streaming Engine
Wowza Streaming Engine can ingest WebRTC content from mobile and desktop browsers that support the WebRTC APIs. Supported browsers include the latest versions of Chrome, Firefox, and Safari, as well as Edge version 79 and later. SSL/TLS encryption is required for the WebRTC workflow.
When ingesting source content as WebRTC, Wowza Streaming Engine uses a WebSocket connection to the browser to retrieve the Session Description Protocol (SDP) information. This signaling exchange requires that you set up a Wowza Streaming Engine HTTP provider for the connection.
Once it's in Wowza Streaming Engine, the WebRTC content can be delivered to viewers as is, or it can be transcoded or transmuxed to other formats for delivery.
Configure SSL/TLS encryption for Wowza Streaming Engine
Encryption is required for all components of the WebRTC workflow. You must have a secure HTTP (HTTPS) connection to a web camera for WebRTC publishing and playback. As a result, due to cross-domain issues, you'll need to configure an SSL certificate to secure the connection between the browser and Wowza Streaming Engine for the SDP data exchange.
We recommend the free Wowza StreamLock certificate to secure this connection. The instructions in this article assume you've configured port 443 with an SSL certificate.
If you plan to use your own SSL certificate, the following resources may help you convert your SSL certificate to the Java KeyStore (JKS) format that's required by Wowza Streaming Engine. Although it's possible to use self-signed certificates with WebRTC, note that you must ensure the browser you're using to test accepts traffic encrypted with any self-signed certificates in use.
Configure WebRTC with Wowza Streaming Engine XML
You can configure WebRTC streaming in XML files at the VHost and application level.
Note: For instructions using Wowza Streaming Engine Manager to configure WebRTC instead, see Set up WebRTC streaming with Wowza Streaming Engine Manager.
Configure the HTTP provider
You must configure the HTTPWebRTCExchangeSessionInfo HTTP provider to support an SDP exchange for the WebRTC session. This is equivalent to selecting Use WebRTC for host port 443 in Wowza Streaming Engine Manager. If you have already done this, continue to Configure a live application.
- Navigate to [install-dir]/conf/ and open VHost.xml in a text editor.
- Locate the <HostPort> container for port 443 with SSL and add the following XML snippet as the second-to-last entry in the container of <HTTPProviders>. The new HTTP provider must be the second-to-last provider in the section.
<HTTPProvider>
<BaseClass>com.wowza.wms.webrtc.http.HTTPWebRTCExchangeSessionInfo</BaseClass>
<RequestFilters>*webrtc-session.json</RequestFilters>
<AuthenticationMethod>none</AuthenticationMethod>
</HTTPProvider>
- Save your changes to VHost.xml.
Note: The 443 host port with SSL is commented out by default in VHost.xml. When you're ready to stream over WebRTC, comment it back in by removing the lines <!-- 443 with SSL -->, <!--, and --> from around the <HostPort> container.
Configure a live application
After the HTTP provider is added to your VHost.xml file, configure a live application for WebRTC streaming. This example uses the live application that's included in the default Wowza Streaming Engine installation.
Note: These instructions assume a new installation of Wowza Streaming Engine 4.7.7 or later. If you've updated from an earlier version, you must copy and paste the <WebRTC> container from the sample WebRTC Application.xml file into your [install-dir]/conf/[applicationName]/Application.xml file.
- Open [install-dir]/conf/[applicationName]/Application.xml in a text editor, and configure the following properties in the <WebRTC> container.
Name |
Type |
Description |
EnablePublish |
Boolean |
Set to true to enable WebRTC publishing to this application. |
EnablePlay |
Boolean |
Set to true to enable WebRTC playback from this application. |
EnableQuery |
Boolean |
Set to true to enable querying of published stream names for this application. |
IceCandidateIpAddresses |
String |
The IP address, transport, and port to use for WebRTC streaming.
For the user datagram protocol (UDP), the value should be [wowza-streaming-engine-external-ip-address],udp where [wowza-streaming-engine-external-ip-address] is the external IP address of the Wowza Streaming Engine instance. The port is dynamically assigned for UDP delivery.
For Transmission Control Protocol (TCP), the value should be set to [wowza-streaming-engine-external-ip-address],tcp,[port] where [wowza-streaming-engine-external-ip-address] is the external IP address of the Wowza Streaming Engine instance and [port] is one of the non-SSL-protected streaming HostPort entries defined in [install-dir]/conf/VHost.xml. For example, to stream over port 1935, the entry would be 66.175.168.127,tcp,1935.
For multiple IP addresses, use a pipe character to separate the lists.
Notes:
- Firefox requires UDP. TCP is not supported.
- Port 554 isn't supported for TCP ICE candidates.
- If you use UDP ICE candidates, enabling NACK messages is recommended to allow for retransmission of lost packets. See the optional RTP properties for information about how to enable NACK.
- At this time, full session traversal utilities for NAT (STUN) negotiation aren't supported. Currently, Wowza Streaming Engine only supports traversal of symmetric NATs. A single STUN transport configuration (TCP or UDP) must be supplied using IceCandidateIpAddresses. TURN servers are not supported at this time.
|
UDPBindAddress |
String |
The local IP address of the network card you want to use for WebRTC UDP traffic. (This value is not used if streaming WebRTC over TCP.) For UDP delivery in general, it's okay to leave this property blank. The property is only needed if the server has multiple network interfaces. For some network situations, like running on a cloud instance, a value of 0.0.0.0 would be best instead of the local IP address of the network card to prevent connection problems. |
PreferredCodecsAudio |
String |
A comma-separated list of audio codecs, in order of preference, for stream ingestion. The default is opus,pcmu,pcma. |
PreferredCodecsVideo |
String |
A comma-separated list of video codecs, in order of preference, for stream ingestion. The default is vp8,h264. Valid values are vp8, vp9, and h264. If you want to stream in Chrome using VP9, use vp9,vp8,h264. If no value is specified, the WebRTC stream will not be ingested. |
DebugLog |
Boolean |
Set to true to enable WebRTC debug logging. |
- If needed, in the [install-dir]/conf/[applicationName]/Application.xml file, add the following optional <Property> definitions, including the Name, Type, and Value, to the <WebRTC>/<Properties> container.
Name |
Type |
Description |
webrtcCodecUpdates |
Boolean |
Set to true to allow codec updates for WebRTC connections to pass through the system. The default value is true. Enabling this property can lead to frequent calls to the onCodecInfoVideo method of the IMediaStreamActionNotify3 interface, depending on the publishing client's source encoder. See Listen for stream events and codec information with the Wowza Streaming Engine Java API. |
webrtcFIRMessageInterval |
Integer |
The interval between Full Intra Request (FIR) messages. If webrtcFIRMessageScheme is set to time, the value is in milliseconds and the default is 1000 (1 second). If webrtcFIRMessageScheme is set to frame, the value is in frames and the default is 30. |
webrtcFIRMessageScheme |
String |
The scheme for the FIR message interval. Use time to send a FIR message after a specified period of time, or use frame to send a FIR message after a specified number of frames are received. The default is time. FIR messages, which are enabled by default, provide resiliency for packet loss while publishing WebRTC streams to Wowza Streaming Engine. |
webrtcIdleTimeout |
Integer |
The length of time, in milliseconds, after which a WebRTC session closes if there is no publish or playback activity. The default and recommended value is 10000 (10 seconds). |
Finally, configure the live application's optional RTP properties.
- To handle out of order and retransmitted packets for WebRTC publishing, add the following optional RTP <Property> definitions, including Name, Type (where applicable), and Value, to the <RTP>/<Properties> container in the [install-dir]/conf/[applicationName]/Application.xml file.
Name |
Type |
Description |
jitterBufferDebug |
Boolean |
Set to true to log information about out of order packets that are received and inserted in time. Logged information includes the length of time to recover a packet, which can help determine an appropriate value for jitterBufferDelay. The default is false. |
jitterBufferDelay |
Integer |
Configures the delay, in milliseconds, added by the jitter buffer. This delay allows for retransmitted packets and out of order packets to be played into the system in order, provided they are received in time. If useNack is true, the recommended jitter buffer delay is 2 times the round trip time (RTT) plus overhead for processing. If useNack is false, the recommended jitter buffer delay is 100. The default is 500. |
logPacketLoss |
Boolean |
Set to true to log when packets are lost and not recovered at the time when they should have been played into the system. The default is false. |
rtpDePacketizerWrapper |
— |
Set to com.wowza.wms.rtp.depacketizer.JitterBuffer to enable a jitter buffer for WebRTC that allows handling out of order and retransmitted packets. The jitter buffer is recommended for UDP-based WebRTC streams and adds a delay to the stream. The jitter buffer must be enabled for useNack to work when useNack is enabled. |
useNack |
Boolean |
Set to true to send Negative Acknowledgement (NACK) messages to publishing clients to allow for retransmission of lost packets. This property is for WebRTC streams only. The default is false. Using NACK messages is recommended for UDP-based WebRTC streams and adds a delay to the stream. The jitter buffer must also be enabled for this property to work when enabled. |
- If you have known issues with playback compatibility related to SDP information, add the following optional RTP <Property> definitions, including Name, Type, and Value, to the <RTP>/<Properties> container in the [install-dir]/conf/[applicationName]/Application.xml file. The properties affect WebRTC streams only.
Name |
Type |
Description |
rtpForceH264Constraint |
Boolean |
Set to true to allow the SDP information that is returned to contain different H.264 constraints than the stream contains. The default value is false. |
rtpForceH264ConstraintValue |
Integer |
Sets the H.264 constraint fields in the SDP information if rtpForceH264Constraint is true. The default value, 192, works in most circumstances. Other valid values are 128, 224, and 240. |
rtpUseLowestH264Constraint |
Boolean |
Set to true to compare the initial codec data and the first video unit to the profile data and use the lowest value to determine the H.264 video profile in the SDP information. Use this or rtpUseHighestH264Constraint to help play the stream when an encoder doesn't send consistent codec information for the stream. |
rtpUseHighestH264Constraint |
Boolean |
Set to true to compare the initial codec data and the first video unit to the profile data and use the highest value to determine the H.264 profile in the SDP information. Use this or rtpUseLowestH264Constraint to help play the stream when an encoder doesn't send consistent codec information for the stream. |
Note: The rtpUseLowestH264Constraint and rtpUseHighestH264Constraint properties can't be used simultaneously. If both are set to true, rtpUseHighestH264Constraint is used.
Test the WebRTC workflow
In production environments, WebRTC playback and publishing pages must be hosted on a web server utilizing SSL/TLS encryption. For testing and learning purposes, Wowza provides hosted WebRTC test pages for publish and playback so you can see WebRTC in action more quickly.
Notes:
- Wowza Streaming Engine 4.8.5 or later is required for the hosted WebRTC test pages.
- You can use the the Wowza hosted WebRTC test pages with the latest version of Chrome, Firefox, Safari, and Microsoft Edge version 79 and later.
- Screen share functionality for the hosted WebRTC publish and composite test page is not available on mobile devices or Safari.
Publish a test stream to Wowza Streaming Engine
- Go to the hosted WebRTC publish test page.
- In the Signaling URL field, enter the secure WebSocket URL to connect to the Wowza Streaming Engine WebRTC sessions listener:
wss://[ssl-certificate-domain-name]/webrtc-session.json
where ssl-certificate-domain-name is the secure domain name for your Wowza Streaming Engine instance.
If using Wowza StreamLock, for example, the Signaling URL looks something like this:
wss://5ab4321c0d123.streamlock.net/webrtc-session.json
If you are connecting WebRTC sessions using a port other than the standard SSL/TLS port 443, you must include that non-standard port in the Signaling URL:
wss://5ab4321c0d123.streamlock.net:[SSL-port-number]/webrtc-session.json
- Enter an Application Name that matches the WebRTC live application you configured.
- For Stream Name, enter a name for the stream, such as myStream.
- Configure the remaining settings selections, as needed.
Note: The frame rate and frame size settings constrain the camera and microphone input and aren't included in the SDP provided to Wowza Streaming Engine. The browser may adjust the frame rate to accommodate changes in network conditions.
- To publish an example WebRTC stream from this page into Wowza Streaming Engine, click Publish.
- To share your screen, click the arrow next to the video camera icon, select Screen Share, and then select which content to share. To toggle back to video, click Stop sharing or select a different option under Input Camera.
- To test publishing from a different browser or with a different device, click Copy config (
) to copy the configuration settings and share them.
Publish a test composite stream to Wowza Streaming Engine
- In a new browser tab, go to the hosted WebRTC composite test page.
- Configure the settings for the composite page:
- In the Signaling URL field, enter the secure WebSocket URL to connect to the Wowza Streaming Engine WebRTC sessions listener:
wss://[ssl-certificate-domain-name]/webrtc-session.json
where ssl-certificate-domain-name is the secure domain name for your Wowza Streaming Engine instance.
If using Wowza StreamLock, for example, the Signaling URL looks something like this:
wss://5ab4321c0d123.streamlock.net/webrtc-session.json
If you are connecting WebRTC sessions using a port other than the standard SSL/TLS port 443, you must include that non-standard port in the Signaling URL:
wss://5ab4321c0d123.streamlock.net:[SSL-port-number]/webrtc-session.json
- Enter an Application Name that matches the WebRTC live application you configured.
- For Stream Name, enter a unique name for the stream, such as myStream.
- Configure the remaining settings selections, as needed.
- Select the video sources for the test stream.
- To share your screen, under Video Input 1, select Screen Share, and then select which content to share.
- Select a video layout for the test stream.
- To publish an example WebRTC composite stream from this page into Wowza Streaming Engine, click Publish.
- To test publishing from a different browser or with a different device, click Copy config (
) to copy the configuration settings and share them.
Publish a test meeting stream to Wowza Streaming Engine
- In a new browser tab, go to the hosted WebRTC meeting test page.
- Configure the settings for the meeting page:
- In the Signaling URL field, enter the secure WebSocket URL to connect to the Wowza Streaming Engine WebRTC sessions listener:
wss://[ssl-certificate-domain-name]/webrtc-session.json
where ssl-certificate-domain-name is the secure domain name for your Wowza Streaming Engine instance.
If using Wowza StreamLock, for example, the Signaling URL looks something like this:
wss://5ab4321c0d123.streamlock.net/webrtc-session.json
If you are connecting WebRTC sessions using a port other than the standard SSL/TLS port 443, you must include that non-standard port in the Signaling URL:
wss://5ab4321c0d123.streamlock.net:[SSL-port-number]/webrtc-session.json
- Enter an Application Name that matches the WebRTC live application you configured.
- For Stream Name, enter a unique name for the stream, such as myStream.
- Configure the remaining settings selections, as needed.
- To publish an example WebRTC meeting stream from this page into Wowza Streaming Engine, click Join.
- To add additional participants, click Copy config (
) to copy the configuration settings and share them.
Note: Participants must specify a unique Stream Name before joining the meeting.
Play a test stream from Wowza Streaming Engine
- In a new browser tab, go to the hosted WebRTC play test page.
- Enter the same Signaling URL, Application Name, and Stream Name that you entered on the Publish page.
- To play the example WebRTC stream from Wowza Streaming Engine, click Play.
- To test playback in a different browser or with a different device, click Copy config (
) to copy the configuration settings and share them.
For more advanced learning and testing, Wowza Media Systems provides WebRTC examples on GitHub that demonstrate how to publish and play WebRTC streams with Wowza Streaming Engine. See Use WebRTC example pages with Wowza Streaming Engine.
About port configuration for WebRTC
When configuring Wowza Streaming Engine to ingest or play streams with WebRTC, you must ensure that certain ports are accessible for client connections.
Note: Publishing or playing WebRTC streams on a device with an endpoint security platform enabled may result in decreased video performance. During a deep packet inspection (DPI) process, the endpoint protection platform de-encrypts and then re-encrypts each AES-encrypted packet, which can cause packet delays and stuttering. To address this issue, configure your endpoint security platform to ensure that traffic over the following ports is available without deep packet inspection.
See Troubleshoot network errors for information about troubleshooting port configurations.
Port |
Type |
Description |
443 |
TCP |
During the WebRTC signaling process, Wowza Streaming Engine uses a secure WebSocket connection to establish a connection between peers. This requires a port for encrypted connections using SSL/TLS. By default, port 443 is used. The SSL/TLS port is defined in a HostPort entry in [install-dir]/conf/VHost.xml. |
6970 to 9999 |
UDP |
For WebRTC over UDP, Wowza Streaming Engine uses a default port range of 6970 to 9999. UDP ports are assigned dynamically, and each additional peer WebRTC connection increments the port number used. The starting port number is controlled by the DatagramStartingPort value specified in [install-dir]/conf/Server.xml. |
1935 |
TCP |
For WebRTC over TCP, Wowza Streaming Engine uses a non-SSL-protected streaming port for TCP-level connections. The TCP port is defined in a HostPort entry in [install-dir]/conf/VHost.xml. By default, port 1935 is used. TCP ports are referenced in the IceCandidateIpAddresses property in [install-dir]/conf/[applicationName]/Application.xml.
Note: Port 554 isn't supported for TCP ICE candidates.
|
More resources