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.
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. 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. See About video-on-demand streams (Wowza Video REST API) for more information about VODs, their requirements, storage costs, and security features available.
Note: 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 mange 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.
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
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.
{
"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 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:
- Get the ID for your VOD stream.
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.... { "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.
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.
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.
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
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:
- 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
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.
{
"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:
Note: 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.
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:
- Get the ID for your VOD stream.
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.... { "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.
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
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 "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/[vod_stream_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/[vod_stream_id] —Deletes a VOD stream.
