Create a VOD stream with the Wowza Video REST API

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

Before you start

You should be familiar with the following concepts:

API authentication methods . We use JSON web tokens for API authentication. See Authentication for more information.
Environment variables . We use environment variables for the API version and your JWT 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 .

Info

If you're a Wowza Video subscriber, VOD streams created using the vod_stream parameter will not be available on the Asset Management page. If you want to manage your VOD stream through asset management, set the save_asset parameter to true when creating a live stream. This will generate both a VOD stream and a recording.

You should choose between the following two workflows:

Decide between the live stream or transcoder workflow.
See Decide between a live stream or transcoder workflow for more information about these workflows.

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

Copy

Copied

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${WV_JWT}" \
    -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
       }
    }' "${WV_HOST}/api/${WV_VERSION}/live_streams"

Sample response

The response includes:

The details of your live stream.

Copy

Copied

{
   "live_stream": {
     "id": "1234abcd",
     "name": "MyLiveStream",
     ...
     "vod_stream":true,
     ...
     "encoder": "other_rtmp",
     ...
     "source_connection_information": {
       "primary_server": "[subdomain].entrypoint.video.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 Video 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 Video 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 too so the VOD playlist replaces the live playlist after the event and viewers can re-use the live URL to access the recording.

Info

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:

Get the ID for your VOD stream.

Endpoint Reference

Copy

Copied

curl -X GET \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_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.

Copy

Copied

      ...
      {
            "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"
       }
      ...

Get the playback URL for the VOD stream, using the ID from the previous step.
Endpoint Reference
Copy

Copied
```
curl -X GET \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_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.
Info
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

Copy

Copied

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${WV_JWT}" \
    -d '{
       "property": {
         "section": "vod_stream",
         "key": "live2vod",
         "value": true
       }
    }' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/properties"

When the live stream ends, Wowza Video 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

Set advanced properties with the Wowza Video REST API

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 a VOD stream after the broadcast by POST request to the /transcoders endpoint.

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

Define the transcoder property that enables the VOD stream. Transcoder properties consist of a key/value pair and the section of the configuration table where the property is stored. In this case, you'll define hls as true in the vod_stream section of the configuration table.
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

Copy

Copied

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${WV_JWT}" \
    -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
            }
         ]
       }
    }' "${WV_HOST}/api/${WV_VERSION}/transcoders"

Sample response

The response includes:

An ID for the transcoder that you'll use throughout the rest of this task.

Copy

Copied

{ 
  "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.video.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:

Info

You'll need the transcoder ID from step 1.

Adaptive bitrate transcoder — Create an ABR stream and send it to a target with the Wowza Video REST API
Passthrough transcoder — Pass a stream through the transcoder to a target with the Wowza Video REST API

3. Determine the playback URL

After the event ends, Wowza Video 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 Video 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 so the VOD playlist replaces the live playlist after the event and viewers can re-use the live URL to access the recording.

Info

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:

Get the ID for your VOD stream.

Endpoint Reference

Copy

Copied

curl -X GET \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_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.

Copy

Copied

      ...
      {
            "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"
       }
      ...

Get the playback URL for the VOD stream, using the ID from the previous step.
Endpoint Reference
Copy

Copied
```
curl -X GET \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_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

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.

Copy

Copied

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${WV_JWT}" \
    -d '{
       "property": {
         "section": "vod_stream",
         "key": "live2vod",
         "value": true
       }
    }' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/properties"

When the event ends, Wowza Video 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

PATCH/vod_streams/ID — Update a VOD stream. VOD stream playback is enabled by default. To prevent viewers from playing a VOD stream, set the playback_enabled parameter to false .
DELETE/vod_streams/ID —Deletes a VOD stream.

More transcoder resources

Set advanced properties with the Wowza Video REST API