Create a VOD stream with the Wowza Streaming Cloud REST API

Create a video-on-demand (VOD) stream, a recording viewers can replay at a later date, using the Wowza Streaming Cloud™ REST API. After the broadcast is over and the live stream or transcoder is stopped, Wowza Streaming Cloud creates the VOD stream and generates a URL that you can use to configure playback in an HLS compatible player or device.

You'll need to choose which workflow you'll use, live stream or transcoder, before you begin this task. See Decide between a live stream or transcoder workflow for more information about these workflows.

Before you start


You should be familiar with the following concepts:

  • API authentication methods. Use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
  • Environment variables. We use environment variables for the API version and your API and access keys in the cURL API request examples in this topic to make it easier for you to copy, paste, and run commands in your Terminal or Command Prompt window. 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. See Tools for testing the API for instructions.
  • VOD streams and their requirements. See About video-on-demand streams (Wowza Streaming Cloud REST API) for more information about VODs, their requirements, storage costs, and security features available.

Live stream workflow

1. Create a live stream

Create a live stream that creates a VOD stream after the broadcast by sending a POST request to the /live_streams endpoint.

You can use the following sample request, making sure to:

  • Set vod_stream to true.
  • Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.

Sample request

Endpoint Reference

    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_rtmp",
         "name": "MyVODLiveStream",
         "transcoder_type": "transcoded",
         "vod_stream": true
       }
    }' "${WSC_HOST}/api/${WSC_VERSION}/live_streams"

Sample response

The response includes:

  • The details of your live stream.
{
   "live_stream": {
     "id": "1234abcd",
     "name": "MyLiveStream",
     ...
     "vod_stream":true,
     ...
     "encoder": "other_rtmp",
     ...
     "source_connection_information": {
       "primary_server": "[subdomain].entrypoint.cloud.wowza.com",
       "application": "app-464B8PK6",
       "host_port": 1935,
       "stream_name": "32a5814b",
       "disable_authentication": false,
       "username": "client2",
       "password": "1234abcd"
     },
     ...
   }
}

2. Determine the playback URL

After the event ends, Wowza Streaming Cloud creates a VOD stream and automatically assigns a name to it. The VOD stream name includes the name of the live stream and the date and time the live stream was started.

By default, Wowza Streaming Cloud creates a separate VOD playback URL that can be used to play a VOD stream in an HLS compatible player or device. You can also set the live2vod property to so the VOD playlist replaces the live playlist after the event and viewers can re-use the live URL to access the recording.

Note: You have to set the live2vod property before the stream begins.

2a. Separate VOD playback URL

After the event, retrieve the VOD playback URL by following these steps:

  1. Get the ID for your VOD stream.

    Endpoint Reference

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/vod_streams"

    To find the VOD for your event in the response, locate the name object that has the live stream name, date, and time that corresponds to your event.
          ...
          {
                "id": "v95jhfc2",
                "name": "MyVODLiveStream on Jul 14, 2021 @ 07:51am PDT",
                "created_at": "2021-07-14T14:51:55.000Z",
                "updated_at": "2021-07-14T14:53:02.000Z"
           }
          ... 
    
  2. Get the playback URL for the VOD stream, using the ID from the previous step.

    Endpoint Reference

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

    The playback URL appears similar to this in the response: "playback_url": "https://cdn3.wowza.com/2/by9oaWlyLyt0UTgy/d09rOGdv/hls/v95jhfc2/playlist.m3u8".

The URL can be used in an HLS compatible player or device.

2b. Reuse the live playback URL for VOD playback

If you want to your viewers to access the VOD stream using the same playback URL they used to view the original stream instead, set the live2vod transcoder property to true. You need to set this property before the stream begins.

You can use the following sample request, making sure to:

  • Set the transcoder_id in the request path to the transcoder for your live stream.
    Note: If you don't know your transcoder ID, send a separate request to GET /transcoders and look for your live stream as the transcoder name.

Endpoint Reference

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    -d '{
       "property": {
         "section": "vod_stream",
         "key": "live2vod",
         "value": true
       }
    }' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/properties"

When the live stream ends, Wowza Streaming Cloud replaces the live playlist with the VOD playlist. Viewers can watch the VOD stream without modifying the URL the player used for the live stream.

More live stream resources

Transcoder workflow

1. Create a transcoder

In the transcoder workflow, you'll manually configure the transcoder, output renditions, and stream targets to fit your specific streaming solution.

Create a transcoder that creates VOD stream after the broadcast by sending a POST request to the /transcoders endpoint.

You can use the following sample request, making sure to:

  • Set vod_stream to true. vod_stream is a transcoder property.
  • Set broadcast_location to the region that's closest to your video source.
  • Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference link below.

Sample request

Endpoint Reference

    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": 4000,
         "delivery_method": "push",
         "low_latency": true,
         "name": "MyVODTranscoder",
         "protocol": "rtmp",
         "transcoder_type": "transcoded",
         "properties": [
            {
              "key": "hls",
              "section": "vod_stream",
              "value": true
            }
         ]
       }
    }' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

Sample response

The response includes:

  • An ID for the transcoder that you'll use throughout the rest of this task.
{ 
  "transcoder": { 
    "id": "tmd8ybp2", 
    "name": "MyTranscoder", 
    "transcoder_type": "transcoded", 
    "billing_mode": "pay_as_you_go", 
    "broadcast_location": "us_west_california", 
    ... 
    "protocol": "rtmp", 
    "delivery_method": "push", 
    "source_port": 1935, 
    "domain_name": "[wowzasubdomain].entrypoint.cloud.wowza.com", 
    "application_name": "app-B8P6K226", 
    "stream_name": "b40618d9", 
    ...
    "disable_authentication": false, 
    "username": "user123", 
    "password": "abcPassword", 
    ...
    "outputs": []
  } 
} 

2. Add output renditions and stream targets

Complete the transcoder by adding output renditions and Fastly stream targets. For instructions, see one of the following articles, depending on whether you're creating an adaptive bitrate or passthrough transcoder:

Note: You'll need the transcoder ID from step 1.

3. Determine the playback URL

After the event ends, Wowza Streaming Cloud creates a VOD stream and automatically assigns a name to it. The VOD stream name includes the name of the transcoder and the date and time the live stream was started.

By default, Wowza Streaming Cloud creates a separate VOD playback URL that can be used to play a VOD stream in an HLS compatible player or device. You can also set the live2vod property to so the VOD playlist replaces the live playlist after the event and viewers can re-use the live URL to access the recording.

Note: You have to set the live2vod property before the stream begins.

3a. Separate VOD playback URL

After the event, retrieve the VOD playback URL by following these steps:

  1. Get the ID for your VOD stream.

    Endpoint Reference

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/vod_streams"

    To find the VOD for your event in the response, locate the name object that has the transcoder name, date, and time that corresponds to your event, similar to the following example response.
          ...
          {
                "id": "v95jhfc2",
                "name": "MyVODStream on Jul 14, 2021 @ 07:51am PDT",
                "created_at": "2021-07-14T14:51:55.000Z",
                "updated_at": "2021-07-14T14:53:02.000Z"
           }
          ... 
    
  2. Get the playback URL for the VOD stream, using the ID from the previous step.

    Endpoint Reference

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

    The playback URL appears similar to this in the response: "playback_url": "https://cdn3.wowza.com/2/by9oaWlyLyt0UTgy/d09rOGdv/hls/v95jhfc2/playlist.m3u8".

The URL can be used in an HLS compatible player or device.

3b. Reuse the live playback URL for VOD playback

If you want to your viewers to access the VOD stream using the same playback URL they used to view the original stream instead, set the live2vod transcoder property to true. You need to set this property before the stream begins.

You can use the following sample request, making sure to:

  • Set the transcoder_id in the request path to the ID returned when you created the transcoder.

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    -d '{
       "property": {
         "section": "vod_stream",
         "key": "live2vod",
         "value": true
       }
    }' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/properties"

When the event ends, Wowza Streaming Cloud replaces the live playlist with the VOD playlist. Viewers can watch the VOD stream without modifying the URL the player used for the stream.

Related API requests

More transcoder resources