Start live streaming using the Wowza Streaming Cloud REST API

With only a few API calls and within a matter of minutes, you can set up and play your first stream on a customizable webpage hosted by Wowza Streaming Cloud™.

This tutorial walks you through using the Wowza Streaming Cloud REST API to deliver a stream from a video source to a player on a hosted page. You'll use a camera to capture a video stream that's pushed to the Wowza Streaming Cloud service for processing, and then the highest quality stream for each viewer's bandwidth is delivered to the player. Wowza Streaming Cloud handles the entire streaming and viewing experience.

And so you can integrate the full streaming workflow into your code-based solution, you'll learn how to programmatically start and stop your stream.

Before you start


This tutorial uses:

  • API and access keys for a Wowza Streaming Cloud account. If you don't have an account and want to use the free trial, see Wowza Streaming Cloud free trial for more information including trial limitations.
  • cURL, Postman, or another REST API client to make calls to the Wowza Streaming Cloud REST API. For information about installing and using your REST API client, refer to their documentation.

Tips for working through this tutorial:

  • Sample code — We use environment variables for your API and access keys in the cURL API request examples in this tutorial to make it easier for you to copy, paste, and run commands in your Terminal or Command Prompt window. After you get your API and access keys in step 1, you can set the environment variables on your computer so you don't have to manually replace the variables in the sample code. See Tools for testing the API for instructions.


    If you don't set environment variables for these values, you'll need to manually enter the correct values in the code samples throughout this tutorial.
  • Learning more about the API — We've provided working code samples throughout this tutorial that you can execute as presented. However, you should explore the full API reference documentation to learn about the other objects and values you can use to customize requests. 


    We've made it easy for you to do that exploration by providing a link to the API reference documentation before each request sample.

1. Get your API access key


You'll use an API key and access token to authenticate yourself when you make calls to the REST API. The API key identifies the Wowza Streaming Cloud account and the access key identifies a specific user.

Locate the API key and the access key in the Wowza Streaming Cloud user interface.

  1. In the menu bar, click your user name and choose Account Settings.
  2. Select API Access from the navigation on the left-hand side of the page.

The keys are located in the API Key and Access Keys sections of the page.

Access the API page in Wowza Streaming Cloud

  1. To generate a new access key, click Add Access Key.
  2. In the dialog box that opens:
    • Leave Enabled selected so you can use the key immediately.
    • Provide a Description. This description helps you differentiate between access keys when multiple appear on the API access page.
    • Click Add.

Wowza Streaming Cloud displays the generated access key on the API access page. Make note of both the API key and the access key values because you'll use them in the next steps.

Tip: While using the API/access key authentication method works for this tutorial, in your production environment we recommend that you use the more secure hash-based message authentication code (HMAC) to you make calls to the REST API. To learn more, see HMAC Authentication.

Learn more

2. Create a live stream


The quickest way to your first broadcast is with a live stream. In Wowza Streaming Cloud, a live stream automatically handles a lot of the configuration and processing necessary to provide your stream to a global audience.

In a single API call, you'll:

  • specify how the video connects with Wowza Streaming Cloud
  • set up a webpage hosted by Wowza that you'll send your viewers to
  • configure the generated player, embedded in the hosted page, that viewers will use to watch the stream

To create a live stream that receives a WebRTC source, generates a player, and configures a hosted page, copy the following sample code and send it as a POST request, using cURL or Postman, to the /live_streams endpoint.

Tip: See Tools for testing the API for more information about using a REST API client to send requests.

For the purpose of this tutorial, you can use the sample code below as it is, with the following changes:

  • Replace ${WSC_API_KEY} and ${WSC_ACCESS_KEY} with the values you noted in the previous step. If you've set your environment variables for these values, as suggested in the Before you start section, you don't have to make any changes.

Sample request

API endpoint: POST /live_streams

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": "MyLiveStream",
     "transcoder_type": "transcoded"
   }
}' "https://api.cloud.wowza.com/api/v1.6/live_streams"
 

Sample response

The response includes:

  • An ID that identifies the live stream. You'll use this ID in later steps to complete actions on the live stream.
  • Source connection information that you'll use to configure the WebRTC publish page as the source for the live stream. You'll complete this configuration in the next step.
  • Information about the hosted page and player that will be generated. We didn't explicitly include configuration details for the hosted page or the player in the request, instead we relied on the default values. If unspecified, the default value for hosted_page is true and for player_type it's original_html5.
  • Other details of the live stream's configuration. 
{
   "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"
     },
     "player_id": "rjlwfsvl",
     "player_type": "original_html5",
     "player_responsive": false,
     "player_width": 640,
     ...
     "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,
     ...
   }
}

Now that you've created a live stream in Wowza Streaming Cloud to receive and process the WebRTC video source, you can configure your video source and connect it to Wowza Streaming Cloud.

3. Configure your video source


Use the source_connection_information from the live stream response to configure the WebRTC publish page as your video source. WebRTC lets you capture video from your browser without installing plug-ins or downloading third-party software.

  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. Using the source_connection_information from the response returned when you created the live stream, as seen below, enter the following information:

    Example from REST API response
    "source_connection_information": {
             "sdp_url": "wss://[subdomain].entrypoint.cloud.wowza.com/webrtc-session.json",
             "application_name": "app-30zl5349",
             "stream_name": "32a5814b"
         }
     
    • Enter the sdp_url value in the SDP URL field.
    • Enter the application_name value in the Application Name field.
    • Enter the stream_name value in the Stream Name field.
    • Leave Audio Bitrate and Video Bitrate set to the default values.
  4. Close the Settings dialog box to apply your changes.

Now that you've configured your video source, you'll start the live stream in Wowza Streaming Cloud first so it's ready to process the incoming video, then you'll start the stream on the WebRTC publish page. 

4. Start the live stream


After the live stream is created and the source is configured, start the stream in Wowza Streaming Cloud and on the WebRTC publish page. Wowza Streaming Cloud processes the stream coming from the publish page and sends it to the player for viewing on the hosted page.

Note: For active subscriptions, charges start accruing when you start the stream in Wowza Streaming Cloud. See Wowza Streaming Cloud free trial for trial subscription features and limitations.

4a. Start in Wowza Streaming Cloud

To start the live stream in Wowza Streaming Cloud, copy the following sample code and send it as a PUT request to the /live_streams/[live_stream_id]/start endpoint with the following change:

  • Replace [live_stream_id] with the ID returned in step 2.

Sample request

API endpoint: PUT /live_streams/[live_stream_id]/start

curl -X PUT \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"https://api.cloud.wowza.com/api/v1.6/live_streams/[live_stream_id]/start"

The response displays the state of the live stream. In this case, starting.

4b. Start on the WebRTC publish page

To make sure the live stream has time to complete the start up process, wait 20 seconds and then click Publish on the WebRTC publish page.

The stream has started at your video source and Wowza Streaming Cloud is receiving, processing, and delivering the stream to the player on your hosted page. In the next step, you'll retrieve the URL for the hosted page and see the stream playing on it. 

5. View the stream


When you created the live stream in step 2, the response showed the hosted_page_url parameter value as in_progress, instead of providing a URL to the hosted page. The hosted page and player aren't instantly available because Wowza Streaming Cloud generates them after receiving the POST live_stream request. 

To retrieve the hosted page URL now, copy the following sample code and send it as a GET request to the /live_streams/[live_stream_id] endpoint with the following change:

  • Replace [live_stream_id] with the ID returned in step 2.

Sample request

API endpoint: GET /live_streams/[live_stream_id]

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"https://api.cloud.wowza.com/api/v1.6/live_streams/[live_stream_id]"

The response includes hosted_page_url, formatted similar to https://player.cloud.wowza.com/hosted/[page_id]/player.html. This is the URL that you'll distribute to your viewers.

Enter the URL into a browser to open the hosted page, click the play button, and view the live stream. While you're the only one viewing your stream now, this same URL could be used by hundreds or hundreds of thousands of viewers.

6. Stop the live stream


After viewing the live stream on the hosted page, stop the stream. Make sure you stop both the video source and the stream in Wowza Streaming Cloud. If you forget to stop the stream in Wowza Streaming Cloud, you'll continue to accrue charges.

Note: When you have an active subscription, transcoding charges accrue for started live streams even if they aren't actively streaming content. Wowza Streaming Cloud automatically stops idle live streams after 20 minutes, but you should stop your stream as soon as your event ends to avoid accruing unnecessary charges.

See Wowza Streaming Cloud free trial for trial subscription features and limitations.

6a. Stop on the WebRTC publish page

On the WebRTC publish page, click Stop.

6b. Stop in Wowza Streaming Cloud

To stop the live stream, copy the following sample code and send it as a PUT request to the /live_streams/[live_stream_id]/stop endpoint with the following change:

  • Replace [live_stream_id] with the ID returned in step 2.

Sample request

API endpoint: GET /live_streams/[live_stream_id]/stop

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"https://api.cloud.wowza.com/api/v1.6/live_streams/[live_stream_id]/stop"

The response displays the state of the live stream. In this case, stopped.

Next steps

You've completed your first live stream! You used an encoder (WebRTC) to send video to Wowza Streaming Cloud where it was processed and then delivered to your viewers. 

You can now move on to learn how to query a live stream and get useful information about one or more live streams that you can use to build a robust code-based streaming solution. Or you can explore the articles in the General examples section of the navigation to move on to advanced REST API tasks.    

More resources