Stream a file with the Wowza Streaming Cloud REST API

Learn how to use the Wowza Streaming Cloud REST API to stream a file in a live stream broadcast.

About file streaming


Wowza Streaming Cloud allows you to stream .mp3 and H.264-encoded .mp4 and .flv files. Files must be hosted on a web server, Google Storage, or Amazon S3 bucket.

Note: 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 consider the fact that Wowza Streaming Cloud 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).

File streaming can be configured through the live stream or transcoder workflow. After you start the live stream or transcoder, Wowza Streaming Cloud downloads the file from the specified URL, and then starts the stream. Depending on the location of the file, the file size, and network conditions there may be a delay between when the live stream or transcoder starts and when the file actually begins to play.

By default, files play once and then stop. To play a file on a continuous loop, see Play the file on a loop.

Schedules

You can schedule a file to automatically start streaming at a specific date and time. Then, prior to the scheduled start time, start the live stream or transcoder manually or use a schedule to automatically start it. This ensures that Wowza Streaming Cloud has enough time to download the file. For more information, see Schedule the stream.

Notes:
  • This feature is available in v1.5 of the REST API and later.
  • 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.
  • Passthrough transcoding isn’t supported for HLS playback of .mp3 files.
  • 4k video files with a video bitrate greater than 6000 Kbps may cause performance issues when streaming.

Live stream workflow


Live stream parameters

Parameter Data Type Description
aspect_ratio_height integer The height, in pixels, of the output rendition.

This value should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8.
aspect_ratio_width integer The width, in pixels, of the output rendition.

This value should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8.
billing_mode string The billing mode for the stream. The default is pay_as_you_go.
broadcast_location string The region that's closest to where your stream originates. For a list of valid regions, see the API reference documentation.
delivery_method string The method you're using to deliver the source stream to the transcoder. Specify pull.
encoder string The source for the live stream. Specify file.
name string The name of the live stream. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyLiveStream.
source_url string The source file URL, including the protocol. Supported protocols are http, https, gs, and s3.
 
Note: The filename and path cannot contain spaces.
transcoder_type string The type of transcoder. Valid values are transcoded, for streams that are transcoded into adaptive bitrate renditions, or passthrough, for streams that aren't processed by the transcoder.
 
Note: For information on other live stream parameters, see the Wowza Streaming Cloud REST API Reference Documentation.

Example request and response

Notes:

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": 1080,
     "aspect_ratio_width": 1920,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "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"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/live_streams"

The command creates a live stream with an id parameter, an associated player, and a hosted page. The details of the live stream's configuration are listed in the response.

{
    "live_stream": {
        "id": "abcntjvl",
        "name": "MyLiveStream",
        "transcoder_type": "transcoded",
        "billing_mode": "pay_as_you_go",
        "broadcast_location": "us_west_california",
        "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,
        ...
    }
}

Transcoder workflow


Transcoder parameters

Parameter Data Type Description
billing_mode string The billing mode for the stream. The default is pay_as_you_go. If you have a 24x7 subscription, choose pay_as_you_go or twentyfour_seven.
broadcast_location string The region that's closest to where your stream originates. For a list of valid regions, see the API reference documentation.
delivery_method string The method you're using to deliver the source stream to the transcoder. Specify pull.
name string The name of the transcoder. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyTranscoder.
protocol string The transport protocol for the source video. Specify file.
source_url string The source file URL, including the protocol. Supported protocols are http, https, gs, and s3.
 
Note: The filename and path cannot contain spaces.
transcoder_type string Specify the default value, transcoded. You can alternatively use passthrough, depending on your needs and the functionality available at your broadcast location.
 
Note: For information on other transcoder parameters, see the Wowza Streaming Cloud REST API Reference Documentation.

Example request and response

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",
     "delivery_method": "pull",
     "name": "MyTranscoder",
     "protocol": "file",
     "source_url": "https://example.com/file.mp4",
     "transcoder_type": "transcoded"
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

This command creates a transcoder with an id parameter but no outputs ("outputs": []). The details of the configured transcoder are listed in the response, which should look something like this:

{
    "transcoder": {
        "id": "lq7rb1qn",
        "name": "MyTranscoder",
        "transcoder_type": "transcoded",
        "billing_mode": "pay_as_you_go",
        "broadcast_location": "us_west_california",
        "closed_caption_type": "none",
        "delivery_method": "pull",
        "source_url": "https://example.com/file.mp4",
        ...
  }
}

Next, complete the transcoder by creating output renditions and stream targets. For more information, see the following articles:

Configure advanced properties


You can use advanced transcoder properties to play the file on a continuous loop and schedule the file to start streaming at a specific date and time.

Transcoder properties

Section Key Value Description
file repeat boolean If True plays the file on a continuous loop. The default is False.
 
Notes:
  • Enabling this property overrides the idle timeout value for the transcoder. The transcoder will continue to run and accrue charges until manually stopped.
  • You can use a schedule to automatically stop the transcoder at a specific date and time. For more information, see Schedule a transcoder with the Wowza Streaming Cloud REST API.
file start_streaming_at string The month, day, year, and time of day that the file should start streaming. Express the value by using the ISO 8601 standard of YYYY-MM-DDTHH:MM:SSZ where HH is a 24-hour clock in UTC.

Example requests

Play the file on a loop

To play the file on a continuous loop:

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

Schedule the stream

You can schedule a file to automatically start streaming at a specific date and time. Then, prior to the scheduled start time, start the transcoder manually or a use a schedule to automatically start it. For more information on scheduling transcoders, see Schedule a transcoder with the Wowza Streaming Cloud REST API.

For best results, start the transcoder at least 5-15 minutes before the scheduled start time.

Note: Wowza Streaming Cloud allows you to specify an idle timeout value to automatically stop the transcoder if no video is received after a specified length of time. The default value is 20 minutes. If you start the transcoder early to allow time for the file to download, make sure that the idle timeout isn’t set to occur before the scheduled start time. Otherwise, the transcoder will stop and the file won’t stream.

To schedule the stream:

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "property": {
     "key": "start_streaming_at",
     "section": "file",
     "value": "2020-04-30 04:00:00 -06:00"
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/properties"