Stream .mp3 and H.264-encoded .mp4 and .flv files in a live broadcast using the Wowza Video REST API.
Important: After you start the live stream or transcoder, Wowza Video downloads the file from the specified storage URL, and then starts the stream. Because the transcoder has to start, which can take a few minutes, and the file has to download to the transcoder before playback can begin, there will be a delay between when the stream starts and when the file actually begins to play. Factors that also affect the delay include the location of the file, the file size, and network conditions.
You can minimize this start-up delay using the file:start_streaming_at property. See Schedule the start of a file with the Wowza Video REST API after you complete this topic for more information.
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.
- File streams and their requirements. See About file streams in the Wowza Video REST API for more information about file streams, their requirements, and additional configurations for a file stream.
Live stream workflow
1. Create a live stream
Create a live stream that streams a file by sending a POST request to the /live_streams endpoint.
You can use the following sample request, making sure to:
- Set encoder to file.
- Set source_url to the URL for the source file. Consider these requirements for the file and the URL
- Files must be hosted on a web server, Google Storage, or Amazon S3 bucket and the supported protocols are http, https, gs, and s3.
- The filename and path cannot contain spaces and must be 765 characters or less.
- You can use presigned URLs to provide secure, time-limited access to files in Google Storage and Amazon S3 buckets. When setting the time limit restriction, you will need to take into consideration that Wowza Video only downloads files after the live stream or transcoder starts. If the presigned URL expires before the file is downloaded, the stream will not start. For more information, see documentation for Google Cloud Storage and Amazon Simple Storage Service (S3).
Tips:
- For best results, consider adding a buffer of 10 to 15 seconds to the end of the video. This ensures that the stream doesn't cut off prematurely.
- 4k video files with a video bitrate greater than 6000 Kbps may cause performance issues when streaming.
- 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 button below.
Sample request
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
"live_stream": {
"aspect_ratio_height": 1080,
"aspect_ratio_width": 1920,
"billing_mode": "pay_as_you_go",
"broadcast_location": "us_central_iowa",
"delivery_method": "pull",
"encoder": "file",
"hosted_page": true,
"hosted_page_sharing_icons": true,
"name": "MyLiveStream",
"player_responsive": true,
"source_url": "https://example.com/file.mp4",
"transcoder_type": "transcoded"
}
}' "${WV_HOST}/api/${WV_VERSION}/live_streams"
Sample response
The response includes:
- The details of your live stream.
{
"live_stream": {
"id": "abcntjvl",
"name": "MyLiveStream",
"transcoder_type": "transcoded",
"billing_mode": "pay_as_you_go",
"broadcast_location": "us_central_iowa",
"recording": false,
"closed_caption_type": "none",
"low_latency": false,
"encoder": "file",
"delivery_method": "pull",
"target_delivery_protocol": "hls-https",
"use_stream_source": false,
"aspect_ratio_width": 1920,
"aspect_ratio_height": 1080,
...
}
}
After you start the live stream, Wowza Video downloads the file from the specified storage URL, and then starts the stream.
Next Steps
After you create a file stream, you can further configure it with transcoder properties:
- Play the file on a loop — By default, files play once and then stop.
- Schedule the start of the file — Break the start-up process into two discrete steps: 1) start the transcoder and download the file and 2) start streaming the file. This allows you to front load start-up time and stream the file at specific time.
Transcoder workflow
1. Create a transcoder
Create a transcoder that streams a file by sending a POST request to the /transcoders endpoint.
You can use the following sample request, making sure to:
- Set protocol to file.
- Set source_url to the URL for the source file. Consider these requirements for the file and the URL:
- Files must be hosted on a web server, Google Storage, or Amazon S3 bucket and the supported protocols are http, https, gs, and s3.
- The filename and path cannot contain spaces and must be 765 characters or less.
- You can use presigned URLs to provide secure, time-limited access to files in Google Storage and Amazon S3 buckets. When setting the time limit restriction, you will need to take into consideration that Wowza Video only downloads files after the live stream or transcoder starts. If the presigned URL expires before the file is downloaded, the stream will not start. For more information, see documentation for Google Cloud Storage and Amazon Simple Storage Service (S3).
Tips:
- For best results, consider adding a buffer of 10 to 15 seconds to the end of the video. This ensures that the stream doesn't cut off prematurely.
- 4k video files with a video bitrate greater than 6000 Kbps may cause performance issues when streaming.
- 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_central_iowa",
"delivery_method": "pull",
"name": "MyTranscoder",
"protocol": "file",
"source_url": "https://example.com/file.mp4",
"transcoder_type": "transcoded"
}
}' "${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.
- An empty outputs array that you'll configure in the next step.
{
"transcoder": {
"id": "lq7rb1qn",
"name": "MyTranscoder",
"transcoder_type": "transcoded",
"billing_mode": "pay_as_you_go",
"broadcast_location": "us_central_iowa",
"closed_caption_type": "none",
"delivery_method": "pull",
"source_url": "https://example.com/file.mp4",
...
}
}
2. Add output renditions and stream targets
Complete the transcoder by adding output renditions and 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
After you start the transcoder, Wowza Video downloads the file from the specified storage URL, and then starts the stream.
Next Steps
After you create a file stream, you can further configure it with transcoder properties:
- Play the file on a loop — By default, files play once and then stop.
- Schedule the start of the file — Break the start-up process into two discrete steps: 1) start the transcoder and download the file and 2) start streaming the file. This allows you to front load start-up time and stream the file at specific time.
