Stream a file with the Wowza Video REST API

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

    Info

    • 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

Endpoint Reference

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

    Info

    • 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

Endpoint Reference

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:

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