Quickly start live streaming in Wowza Video using the Wowza Video 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 Video™.

This tutorial walks you through using the Wowza Video 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 Video service for processing, and then the highest quality stream for each viewer's bandwidth is delivered to the player. Wowza Video 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.

Info

This topic only applies to version 2.0 and later of the REST API.

Before you start

This tutorial uses:

  • A JSON Web Token (JWT) for a Wowza Video account. If you don't have an account and want to use the free trial, see Wowza Video free trial for more information, including trial limitations.
  • cURL , Postman , or another REST API client to make calls to the Wowza Video 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 JWT 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 JWT in Step 1, you can set the environment variable 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 variable for these values, you'll need to manually enter the correct value 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 access token

You'll use an access token, also called a JSON Web Token, to authenticate yourself when you make calls to the REST API. The token identifies the Wowza Video account and specific user making the API requests.

There are two types of access tokens:

  • Personal access tokens — Available to all users with a Wowza Video license. These tokens are specific to a user and can be used in API calls to do quick tests or manual actions that don't need to persist if the user leaves the organization.
  • System access tokens — Available to organization owners. These tokens are specific to the organization and transcend individual users who come into and leave an organization. For this reason, system access tokens are best used for integrations that go into production environments and need to persist after specific users leave an organization.

Generate the token in the Wowza Video user interface.

  1. In the left-hand navigation, click your user name and choose Token Management .

    Video Account Settings Updated

  2. In the Token Management portal, add a new token. Choose a personal access token or, if you're an organization owner, a system token. If you're an organization member who needs a system-level token that needs to persists, reach out to your organization owner.

    Make sure you copy the token and store it in a safe location; you won't see the token again later.

    Token Management Personal System

Learn more

2. Create a live stream

The quickest way to your first broadcast is with a live stream. In Wowza Video, 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 Video
  • generate a webpage hosted by Wowza that you'll send your viewers to
  • specify a player configuration to use for the styling and branding of the player used with this stream

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

Info

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 ${WV_JWT} with the value you noted in the previous step. If you've set your environment variables for this value, as suggested in the Before you start section, you don't have to make any changes.
  • (Optional) By default, a live stream will use the default player configuration for the account. If you want to use a player that's branded for your event, create a new player configuration in the Wowza Video user interface ( Players >> Configurations ). Then send the player configuration ID from the user interface (example: affaa6b7-aeb0-4961-92a0-5319423867fd ) in the player_id field in the request. For this tutorial, we'll rely on the default player configuration so we won't send player_id .

Sample request
Endpoint Reference

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "live_stream": {
     "broadcast_location": "us_west_california",
     "delivery_method": "push",
     "encoder": "other_webrtc",
     "name": "My Live Stream"
   }
}' "${WV_HOST}/api/${WV_VERSION}/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.
  • Other details of the live stream's configuration.
Copy
Copied
{
   "live_stream": {
     "id": "1234abcd",
     "name": "MyWebRTCStream",
     ...
     "encoder": "other_webrtc",
     ...
     "source_connection_information": {
         "sdp_url": "wss://[subdomain].entrypoint.video.wowza.com/webrtc-session.json",
         "application_name": "app-30zl5349",
         "stream_name": "32a5814b"
     }
     ...
   }
}

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

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

    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

Copy
Copied
"source_connection_information": {
    "sdp_url": "wss://[subdomain].entrypoint.video.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.
  • 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 Video 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 Video and on the WebRTC publish page. Wowza Video processes the stream coming from the publish page and sends it to the player for viewing on the hosted page.

Info

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

4a. Start in Wowza Video

To start the live stream in Wowza Video, 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
Endpoint Reference

Copy
Copied
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
"https://api.video.wowza.com/api/${WV_VERSION}/live_streams/[live_stream_id]/start"

The response displays the state of the live stream. In this case, start (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 Video 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

Use the source_connection_information from the live stream response to configure the WebRTC playback page that is configured to take advantage of the low-latency of WebRTC.

  1. In a new browser tab, go to wowza.com/webrtc/play .
    Info

    The WebRTC hosted playback page is supported on the latest versions of Chrome and Safari, as well as Edge version 79 and later.

WebRTC playback page

  1. Click the Settings button on the upper-right corner of the page.
  2. 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

Copy
Copied
"source_connection_information": {
    "sdp_url": "wss://[subdomain].entrypoint.video.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.
  • Close the Settings dialog box to apply your changes.

Now that you've configured your playback page, click play to view the stream.

6. Stop the live stream

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

Info

When you have an active subscription, transcoding charges accrue for started live streams even if they aren't actively streaming content. Wowza Video 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 Video 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 Video

To stop the live stream, copy the following sample code and send it as a PUTrequest 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

Endpoint Reference

Copy
Copied
curl -X PUT \
-H "Authorization: Bearer ${WV_JWT}" \
"https://api.video.wowza.com/api/${WV_VERSION}/live_streams/[live_stream_id]/stop"

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

Next steps

You've completed your first live stream! You used an encoder (WebRTC) to send video to Wowza Video 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 Guides section of the navigation to move on to advanced REST API tasks.

More resources