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

Learn how to use the Wowza Streaming Cloud REST API to deliver WebRTC streams to viewers through a CDN for playback over HLS.

Live stream workflow

Contents


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

About HLS playback


With Wowza Streaming Cloud, you can ingest a single-bitrate WebRTC source stream, transcode the stream into multiple output renditions, and then deliver the stream to viewers through a CDN for playback over HLS. WebRTC lets you capture video from your browser without installing plug-ins or downloading third-party software.

Note: As an alternative, Wowza Streaming Cloud also 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. For more information, see WebRTC workflows in Wowza Streaming Cloud.

To deliver a WebRTC stream to viewers for playback over HLS, create an adaptive bitrate live stream using the POST /live_streams operation, give the hosted_page_url to your viewers, and then publish the stream using the WebRTC hosted publish page.

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 setting the aspect_ratio_height to 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 setting the aspect_ratio_width to 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 the default value, transcoded. passthrough isn't available for WebRTC streams created through the live stream workflow.
delivery_method string The method you're using to deliver the source stream to the transcoder. Specify the default value, push. pull and cdn connections aren't available 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

Notes:

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 WebRTC live stream. The details of the live stream's configuration are listed in the response, including the live stream id and hosted_page_url.

{
   "live_stream": {
     "id": "1234abcd",
     "name": "MyWebRTCStream",
     ...
     "encoder": "other_webrtc",
     ...
     "hosted_page": true,
     "hosted_page_title": "Hosted player page",
     "hosted_page_url": "https://player.cloud.wowza.com/qa/g7xr79xw/player.html",
     "hosted_page_description": "",
     "hosted_page_sharing_icons": true,
     ...
   }
}

Also included in the response is a source_connection_information object containing values that you'll use in the next step to configure the WebRTC publish page.

"source_connection_information": {
  "sdp_url": "wss://[subdomain].entrypoint.cloud.wowza.com/webrtc-session.json",
  "application_name": "app-30zl5349",
  "stream_name": "32a5814b"
},

Test the connection


To test the connection, start the live stream, configure the WebRTC hosted publish page, and then use the HLS hosted player 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 live stream

You can give the hosted_page_url to your viewers so they can watch the live stream. This page can also be used for testing purposes. To test the connection using the hosted player, do the following:

  1. Open the hosted_page_url in a new browser tab.

  2. Click the Play button.

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 HLS playback
Create a transcoder
Test the connection
More resources

About HLS playback


With Wowza Streaming Cloud, you can ingest a single-bitrate WebRTC source stream, transcode the stream into multiple output renditions, and then deliver the stream to viewers through a CDN for playback over HLS. WebRTC lets you capture video from your browser without installing plug-ins or downloading third-party software.

Note: As an alternative, Wowza Streaming Cloud also 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. For more information, see WebRTC workflows in Wowza Streaming Cloud.

To deliver a WebRTC stream to viewers for playback over HLS, create an adaptive bitrate transcoder using the POST /transcoders operation, add stream targets and output renditions, configure the stream for playback in an HLS-compatible player, and then publish the stream using the WebRTC hosted publish page.

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.
delivery_method string The method you're using to deliver the source stream to the transcoder. Specify push. pull and cdn connections aren't available 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. You can alternatively use passthrough, depending on your needs and the functionality available at your broadcast location.
 
Notes:
  • To include audio in recordings and VOD streams, the transcoder_type must be set to transcoded.
  • 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",      
    "delivery_method": "push",      
    "name": "MyWebRTCTranscoder",      
    "protocol": "webrtc",      
    "transcoder_type": "transcoded"
  } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

This request creates a WebRTC transcoder. The details of the transcoder's configuration are listed in the response, including the transcoder id. An output for WebRTC playback is created automatically, but you'll create additional output renditions to use for HLS playback.

{ 
  "transcoder": { 
    "id": "tmd8ybp2", 
    "name": "MyWebRTCTranscoder", 
    "transcoder_type": "passthrough", 
    "billing_mode": "pay_as_you_go", 
    "broadcast_location": "us_west_california", 
    ...
    "protocol": "webrtc", 
    "delivery_method": "push", 
    "source_port": 443,
    ...
    "outputs": [
      {
        "id": "bdnvb0l",
        "name": WebRTC Output: Video + Audio",
        "transcoder_id": "tmd8ybp2",
        ...
        "output_stream_targets": [] 
      }
    ]
  }
} 

Also included in the response is the domain_name, application_name, and stream_name. You'll use these values in the next step to configure the WebRTC publish page.

"domain_name": "[hostname].entrypoint.cloud.wowza.com",
"application_name": "app-V5840271",
"stream_name": "R1gxG3Ja",

Complete the transcoder by adding output renditions and stream targets. When you create the stream target, make note of the stream target's playback_url for testing playback in the next step. For more information, see Create an ABR stream and send it to a target with the Wowza Streaming Cloud REST API.

Test the connection


To test the connection, start the transcoder, configure the WebRTC hosted publish page, and confirm the live stream is running with the GET /transcoders/[transcoder_id]/thumbnail_url operation.

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.
    • 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.

Confirm the live stream is running

The following request uses the GET /transcoders/[transcoder_id]/thumbnail_url operation to fetch the thumbnail URL of the transcoder, where transcoder_id is the id returned in the response when you created the transcoder.

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

Open the thumbnail_url in a new browser tab. If the stream is running successfully, a preview image from the stream is displayed.

Alternatively, you can use the playback_url to configure the stream for playback in an HLS-compatible player. The URL is returned in a request to fetch stream target details. See the API reference for more information about these endpoints.

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