Deliver WebRTC streams to viewers using the Wowza Streaming Cloud REST API

Learn how to use the Wowza Streaming Cloud™ service to deliver WebRTC streams to viewers.

Live stream workflow

Contents


About WebRTC playback
Create a live stream
Test the connection
More resources

About WebRTC playback


Wowza Streaming Cloud provides direct playback URLs for RTMP, RTSP, WebRTC, and WOWZ that you can use to deliver live streams to viewers or other video services directly from the transcoder. Egress costs for direct playback are typically greater than the costs associated with delivering streams to viewers through a CDN. For more information about cost, audience size, and other workflow considerations, see WebRTC workflows in Wowza Streaming Cloud.

WebRTC lets you capture video from your browser without installing plug-ins or downloading third-party software. To deliver a WebRTC stream to viewers for direct playback, create a live stream using the POST /live_streams operation, and then use the WebRTC hosted publish and playback pages to test the connection.

Create a live stream


Live stream parameters

Parameter Data Type Description
aspect_ratio_height integer

The height, in pixels, of the output rendition.

This value should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Set the aspect ratio of the live stream to match the aspect ratio in your encoder settings.

For WebRTC, we recommend using an aspect_ratio_height of 1280.

aspect_ratio_width integer

The width, in pixels, of the output rendition.

This value should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Set the aspect ratio of the live stream to match the aspect ratio in your encoder settings.

For WebRTC, we recommend using an aspect_ratio_width of 720.

billing_mode string The billing mode for the stream. Specify the default value, pay_as_you_go.
broadcast_location string The region that's closest to where your stream originates. For a list of valid regions, see the API reference documentation.
encoder string The video source for the live stream. Specify other_webrtc.
name string The name of the live stream. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyWebRTCStream.
transcoder_type string The type of transcoder. Specify transcoded. passthrough isn't available for streams created through the /live_streams endpoint.
delivery_method string The method you're using to deliver the source stream to the transcoder. Specify the default value, push. Wowza Streaming Cloud doesn't support pull or cdn connections for WebRTC.
   
Note: For a full list of live stream parameters, see Live Streams in the Wowza Streaming Cloud API reference.

Example request and response

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "live_stream": {
     "aspect_ratio_height": 720,
     "aspect_ratio_width": 1280,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "push",
     "encoder": "other_webrtc",
     "name": "MyWebRTCStream",
     "transcoder_type": "transcoded"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/live_streams"

This request creates a live stream with an id property. The details of the live stream's configuration are listed in the response. You'll use sdp_url, application_name, and stream_name from source_connection_information in the next step to configure the WebRTC publish page.

{
   "live_stream": {
     "id": "1234abcd",
     "name": "MyWebRTCStream",
     ...
     "encoder": "other_webrtc",
     ...
     "source_connection_information": {
       "sdp_url": "wss://[subdomain].entrypoint.cloud.wowza.com/webrtc-session.json",
       "application_name": "app-30zl5349",
       "stream_name": "32a5814b",
     },
     ...
   }
}

Also included in the response is an array of direct_playback_urls for WebRTC. While URLs for multiple protocols and renditions are available, you'll use the URL for the webrtc rendition in the WebRTC direct_playback_urls object for playback.

"direct_playback_urls": {
    ...
    "webrtc": [
        {
            "name": "source",
            "url": "wss://[subdomain].entrypoint.cloud.wowza.com/webrtc-session.json",
            "application_name": "app-1880020Q",
            "stream_name": "3f8f1889"
        },
        {
            "name": "webrtc",
            "url": "wss://[subdomain].entrypoint.cloud.wowza.com/webrtc-session.json",
            "application_name": "app-1880020Q",
            "stream_name": "3f8f1889_stream1",
            "output_id": "wpdlffwf"
        }
    ]
},

(Optional) Decrease latency

The default buffer size for a live stream is 4 seconds. To decrease the latency of the stream and get closer to real-time, you can change the buffer to 0.

  1. Send a request to GET /transcoders to get the transcoder ID for your live stream. See the API reference for more information about this endpoint. 
  2. Send a request to PATCH /transcoders/[ID], where ID is the transcoder ID returned in the previous step, and set the buffer_size to 0. See the API reference for more information about this endpoint.

Test the connection


To test the live stream connection, start the live stream, configure the WebRTC hosted publish page, and then use the WebRTC hosted playback page to play back the stream.

Start the live stream

The following request uses the PUT /live_streams/[live_stream_id]/start operation to start the live stream, where live_stream_id is the id returned in the response when you created the live stream.

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/start"

Publish the WebRTC stream

  1. In a new browser tab, go to wowza.com/webrtc/publish. Grant access to your camera and microphone when prompted.
     
    Note: The WebRTC hosted publish page is supported on the latest versions of Chrome and Safari, as well as Edge version 79 and later.

  2. Click the Settings button on the upper-right corner of the page.
  3. Specify the following settings:
     
    • SDP URL – The sdp_url from the WebRTC source_connection_information object.
    • Application Name – The application_name from the WebRTC source_connection_information object.
    • Stream Name – The stream_name from the WebRTC source_connection_information object.
    • Audio Bitrate – You can leave Audio Bitrate set to the default value, 64.
    • Video Bitrate – You can leave Video Bitrate set to the default value, 3500.
  4. Close the Settings dialog box to apply your changes.
  5. To change which microphone to use, click the arrow next to the microphone icon.
  6. To change the video source, click the arrow next to the video camera icon. To share your screen, select Screen Share.
     
    Notes:
    • The video source can’t be changed after the broadcast is started.
    • Screen share functionality isn't supported on mobile devices or Safari.
  7. Click Publish.

Play the WebRTC stream

  1. In a new browser tab, go to wowza.com/webrtc/play.
     
    Note: The WebRTC hosted playback page is supported on the latest versions of Chrome and Safari, as well as Edge version 79 and later.

  2. Click the Settings button on the upper-right corner of the page.
  3. Specify the following settings:
     
    • SDP URL – The url from the webrtc rendition of the WebRTC direct_playback_urls object.
    • Application Name – The application_name from the webrtc rendition of the WebRTC direct_playback_urls object.
    • Stream Name – The stream_name from the webrtc rendition of the WebRTC direct_playback_urls object.
      Make sure you don't use the stream_name from source_connection_information. That object should not be distributed to viewers.
  4. Close the Settings dialog box to apply your changes.
  5. Click Play.

You can get a URL to distribute to your viewers so they can watch the WebRTC stream on a preconfigured, hosted page in one of two ways:

  • Log into Wowza Streaming Cloud and use the WebRTC Playback Page URL on the Overview page for the live stream.
  • Using the information in step 3, build the URL with the following format:
    https://wowza.com/webrtc/play?playApplicationName=[application_name]&playSdpURL=[sdp_url]&playStreamName=[stream_name]&title=[title]

    Where sdp_url is escaped as in this example: wss%3A%2F%2F[subdomain].entrypoint.cloud.wowza.com%2Fwebrtc-session.json

Stop the live stream

To avoid incurring additional billing charges, remember to stop the live stream after the stream broadcast is over. The following request uses the PUT /live_streams/[live_stream_id]/stop operation, where live_stream_id is the id returned in the response when you created the live stream.

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
"${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/stop"

More resources


Transcoder workflow

Contents


About WebRTC playback
Create a transcoder
Test the connection
More resources

About WebRTC playback


Wowza Streaming Cloud provides direct playback URLs for RTMP, RTSP, WebRTC, and WOWZ that you can use to deliver live streams to viewers or other video services directly from the transcoder. Egress costs for direct playback are typically greater than the costs associated with delivering streams to viewers through a CDN. For more information about cost, audience size, and other workflow considerations, see WebRTC workflows in Wowza Streaming Cloud

WebRTC lets you capture video from your browser without installing plug-ins or downloading third-party software. To deliver a WebRTC stream to viewers for direct playback, create a transcoder using the POST /transcoders operation, and then use the WebRTC hosted publish and playback pages to test the connection.

Create a transcoder


Transcoder parameters

Parameter Data Type Description
billing_mode string The billing mode for the stream. Specify the default value, pay_as_you_go.
broadcast_location string Specify the region that's closest to where your stream originates. For a list of valid regions, see the API reference documentation.
buffer_size integer

The size, in milliseconds, of the incoming buffer. The default is 4000.

Note: To decrease the latency of the stream and get closer to real-time, you can change the buffer to 0.
delivery_method string The method you're using to deliver the source stream to the transcoder. Specify push. Wowza Streaming Cloud doesn't support pull or cdn connections for WebRTC.
name string The name of the transcoder. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyWebRTCTranscoder.
protocol string The transport protocol you're using to send the encoded stream to the transcoder. Specify webrtc.
transcoder_type string

The type of transcoder. Specify transcoded.

Although we recommend that you use an adaptive bitrate transcoder when performing direct playback of a WebRTC stream for maximum viewer connections and a larger feature set, the transcoder workflow allows you to select passthrough. The transcoder type affects how many viewers can connect to your stream directly through the transcoder:
  • transcoded results in a larger transcoder that can handle more viewer connections.
  • passthrough results in a smaller transcoder which can result in lower overall costs, but also means fewer viewer connections and other limitations. If you choose passthrough, make sure you do sufficient testing to ensure your streaming goals are met.
 
Note: For a full list of transcoder parameters, see Transcoders in the Wowza Streaming Cloud API reference.

Example request and response

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{    
  "transcoder": { 
    "billing_mode": "pay_as_you_go",      
    "broadcast_location": "us_west_california",
    "buffer_size": 0,
    "delivery_method": "push",      
    "name": "MyWebRTCTranscoder",      
    "protocol": "webrtc",      
    "transcoder_type": "transcoded"
  } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

This request creates a WebRTC transcoder with a WebRTC output. The details of the transcoder's configuration are listed in the response. You'll use application_name and stream_name in the next step to configure the WebRTC publish page.

{ 
  "transcoder": { 
    "id": "tmd8ybp2", 
    "name": "MyWebRTCTranscoder", 
    "transcoder_type": "transcoded", 
    "billing_mode": "pay_as_you_go", 
    "broadcast_location": "us_west_california", 
    ... 
    "protocol": "webrtc", 
    "delivery_method": "push", 
    "source_port": 443, 
    "domain_name": "[hostname].entrypoint.cloud.wowza.com",
    "application_name": "app-V5840271",
    "stream_name": "R1gxG3Ja",
    ...
    "outputs": [
      {
        "id": "bdnvb0l",
        "name": WebRTC Output: Video + Audio",
        "transcoder_id": "tmd8ybp2",
        ...
        "output_stream_targets": [] 
      }
    ]
  }
} 

Also included in the response is an array of direct_playback_urls for the WebRTC output. While URLs for multiple protocols and renditions are available, you'll use the URL for the webrtc rendition in the WebRTC direct_playback_urls object for playback.

"direct_playback_urls": {
    ...
    "webrtc": [
        {
            "name": "source",
            "url": "wss://[subdomain].entrypoint.cloud.wowza.com/webrtc-session.json",
            "application_name": "app-1880020Q",
            "stream_name": "3f8f1889"
        },
        {
            "name": "webrtc",
            "url": "wss://[subdomain].entrypoint.cloud.wowza.com/webrtc-session.json",
            "application_name": "app-1880020Q",
            "stream_name": "3f8f1889_stream1",
            "output_id": "wdplffwf"
        }
    ]
},

Test the connection


To test the connection, start the transcoder, configure the WebRTC hosted publish page, and then use the WebRTC hosted playback page to play back the stream.

Start the transcoder

The following request uses the PUT /transcoders/[transcoder_id]/start operation to start the transcoder, where transcoder_id is the id returned in the response when you created the transcoder.

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/start"

Publish the WebRTC stream

  1. In a new browser tab, go to wowza.com/webrtc/publish. Grant access to your camera and microphone when prompted.
     
    Note: The WebRTC hosted publish page is supported on the latest versions of Chrome and Safari, as well as Edge version 79 and later.

  2. Click the Settings button on the upper-right corner of the page.
  3. Specify the following settings:
     
    • SDP URL – Enter wss://[address]/webrtc-session.json where address is the domain_name in the API response.
    • Application Name – The application_name in the API response.
    • Stream Name – The stream_name in the API response. This is not the object in the direct playback object.
    • Audio Bitrate – You can leave Audio Bitrate set to the default value, 64.
    • Video Bitrate – You can leave Video Bitrate set to the default value, 3500.
  4. Close the Settings dialog box to apply your changes.
  5. To change which microphone to use, click the arrow next to the microphone icon.
  6. To change the video source, click the arrow next to the video camera icon. To share your screen, select Screen Share.
     
    Notes:
    • The video source can’t be changed after the broadcast is started.
    • Screen share functionality isn't supported on mobile devices or Safari.
  7. Click Publish.

Play the WebRTC stream

  1. In a new browser tab, go to wowza.com/webrtc/play.
     
    Note: The WebRTC hosted playback page is supported on the latest versions of Chrome and Safari, as well as Edge version 79 and later.

  2. Click the Settings button on the upper-right corner of the page.
  3. Specify the following settings:
     
    • SDP URL – The url from the webrtc rendition of the WebRTC direct_playback_urls object.
    • Application Name – The application_name from the webrtc rendition of the WebRTC direct_playback_urls object.
    • Stream Name – The stream_name from the webrtc rendition of the WebRTC direct_playback_urls object.
  4. Close the Settings dialog box to apply your changes.
  5. Click Play.

You can get a URL to distribute to your viewers so they can watch the WebRTC stream on a preconfigured, hosted page in one of two ways:

  • Log into Wowza Streaming Cloud and use the WebRTC Playback Page URL on the Overview page for the transcoder.
  • Using the information in step 3, build the URL with the following format:
    https://wowza.com/webrtc/play?playApplicationName=[application_name]&playSdpURL=[sdp_url]&playStreamName=[stream_name]&title=[title]

    Where sdp_url is escaped as in this example: wss%3A%2F%2F[subdomain].entrypoint.cloud.wowza.com%2Fwebrtc-session.json

Stop the transcoder

To avoid incurring additional billing charges, remember to stop the transcoder after the stream broadcast is over. The following request uses the PUT /transcoders/[transcoder_id]/stop operation, where transcoder_id is the id returned in the response when you created the transcoder.

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/stop"

More resources