Control a transcoder with a Wowza stream source using the Wowza Streaming Cloud REST API

Learn how to use the Wowza Streaming Cloud™ REST API to set up a Wowza stream source with a live stream or transcoder. This allows Wowza Streaming Cloud to automatically detect broadcast location, automatically start a stream when the video source starts, and automatically stop a stream after the video source disconnects.

Notes:
  • Wowza stream sources are available in private preview. Participation is by invitation only and is subject to the terms of the Wowza Preview End User License Agreement. To be considered for preview participation, contact cloud-preview@wowza.com.
  • Wowza stream sources are available in the Wowza Streaming Cloud REST API in version 1.4 and later.

About Wowza stream sources


Wowza stream sources simplify the process of configuring and managing transcoders to make it faster and easier for you to stream live video. They automatically detect the broadcast location and automatically start and stop an associated transcoder, providing an instant connection between your source encoder and a Wowza Streaming Cloud transcoder.

The Wowza Streaming Cloud service uses servers on multiple continents to receive source video and deliver transcoded streams. A Wowza stream source provides an entry point into Wowza Streaming Cloud that automatically detects the broadcast location of your source encoder or camera and uses the closest ingest point based on a DNS query.

A transcoder connected to a Wowza stream source starts automatically when your video source begins pushing a stream to Wowza Streaming Cloud. There’s no need to click in the user interface or perform any API requests in order to start streaming. The connection is instantaneous, meaning there's no wait for the transcoder to start. The transcoder also stops automatically after the video source stops pushing a stream. The idle timeout value you set for the transcoder determines how quickly the transcoder stops after the video source ends.

To configure a Wowza stream source for a live stream or transcoder, you'll need to:

  • Create a Wowza stream source.
  • (Live stream workflow) Create a live stream, then associate its corresponding transcoder with the Wowza stream source.
  • (Transcoder workflow) While creating a transcoder, associate it with the Wowza stream source.

Create a Wowza stream source


  1. Create a Wowza stream source with the Wowza Streaming Cloud REST API. Wowza stream sources are in private preview and are available in version 1.4 and later.

    Wowza stream source parameter

    Parameter Data Type Description
    name string The name of the Wowza stream source. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive.

    Example request and response

    Notes:

    Create a Wowza stream source:

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    -d '{
    "stream_source_wowza": {
      "name": "Auto-starting stream source"
      }
    }' "${WSC_HOST}/api/${WSC_VERSION}/stream_sources/wowza"

    This creates a Wowza stream source with source connection details. Note the stream source ID. The response should look something like this:

    { 
      "stream_source_wowza": { 
         "id": "def0vjqv", 
         "name": "Auto-starting stream source", 
         "primary_url": "rtmp://origin.cdn.wowza.com:1935/live", 
         "stream_name": "012p2abcKS3Vq93MGJIF6V5tIYS9560a",
         "state": "stopped",
         "created_at": "2018-12-12T15:37:55.000Z", 
         "updated_at": "2018-12-12T15:37:55.000Z" 
      } 
    }
    Note: Wowza stream sources don't allow source authentication.

Associate a Wowza stream source with a live stream


If you prefer the live stream workflow, which automatically creates output renditions and a stream target for you, first create a live stream. Then associate the transcoder that corresponds to the live stream with the Wowza stream source.

  1. Create a live stream.
     
    Note: When creating the live stream, don't set use_stream_source to true, as this will cause Wowza Streaming Cloud to create an Akamai stream source and associate it with the live stream.

    Live stream properties

    Parameter Data Type Description
    aspect_ratio_height integer The height, in pixels, of the output rendition. Should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Use the default, 1080.
    aspect_ratio_width integer The width, in pixels, of the output rendition. Should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Use the default, 1920.
    billing_mode string The billing mode for the stream. Use the default, pay_as_you_go.
    broadcast_location string Enter any valid broadcast location value. Wowza Streaming Cloud will override this value to use the closest ingest point based on a DNS query. For a list of valid values, see the REST API reference documentation.
    delivery_method string The method you’re using to deliver the video stream to the transcoder. Use push to initially create the live stream. You'll update this value in a later API request.
    encoder string Specify the video source for your live stream. For a list of valid values, see the REST API reference documentation.
    name string The name of the live stream. Enter an alphanumeric string (maximum 200 characters).
    protocol string The transport protocol you're using to send the encoded stream to the transcoder. Use rtmp.
    transcoder_type string Specify the default, transcoded. You can alternatively use passthrough, depending on your needs and the functionality available at your broadcast location.
     
    Note: For a full list of live stream properties, see the live stream API reference documentation.

    Example request and response

    Create a live stream:

    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_oregon",     
            "encoder": "other_rtmp",
            "delivery_method": "push",     
            "name": "Live stream for Wowza Stream Source",          
            "transcoder_type": "transcoded" 
        } 
       }' "${WSC_HOST}/api/${WSC_VERSION}/live_streams"
    

    This creates a live stream with outputs and a stream target. After you associate the live stream's transcoder with a Wowza stream source, Wowza Streaming Cloud will override the broadcast_location value. The response should look something like this:

    {
        "live_stream": {
            "id": "abcwksvr",
            "name": "Live Stream for Wowza Stream Source",
            "transcoder_type": "transcoded",
            "billing_mode": "pay_as_you_go",
            "broadcast_location": "us_west_california",
            "recording": false,
            "closed_caption_type": "none",
            "low_latency": false,
            "encoder": "other_rtmp",
            "delivery_method": "push",
            "target_delivery_protocol": "hls-https",
            "use_stream_source": false,
            "aspect_ratio_width": 1920,
            "aspect_ratio_height": 1080,
            "delivery_protocols": [
                "rtmp",
                "rtsp",
                "wowz",
                "hls"
            ],
            "source_connection_information": {
                "primary_server": "rtmp://6d3e06.dev.entrypoint.cloud.wowza.com/app-a61e",
                "host_port": 1935,
                "stream_name": "241b5fcf",
                "disable_authentication": false,
                "username": "client2",
                "password": "8ea686ba"
            },
            ...
            "stream_targets": [
                {
                    "id": "htwtwqxv"
                }
            ],
            "direct_playback_urls": {...},
            "created_at": "2019-01-22T20:14:41.000Z",
            "updated_at": "2019-01-22T20:14:42.000Z"
        }
    }
  2. Update the transcoder associated with the live stream you just created to associate it with the Wowza stream source. The transcoder has the same ID as the live stream.

    Set delivery_method to cdn, and set stream_source_id to the ID of the Wowza stream source you created previously. Optionally, you can set idle_timeout to determine a specific amount of idle time, in seconds, before the transcoder automatically shuts down. 

    Example request and response

    Update a transcoder:

    curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    -d '{   
        "transcoder": { 
            "delivery_method": "cdn",     
            "stream_source_id": "def0vjqv"
        } 
       }' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]"

    The response should look something like this:

    {
      "transcoder": { 
         "id": "abcwksvr", 
         "name": "Live stream for Wowza Stream Source", 
         "transcoder_type": "transcoded", 
         "billing_mode": "pay_as_you_go", 
         "broadcast_location": "us_west_oregon", 
         "recording": false, 
         "closed_caption_type": "none", 
         "protocol": "rtmp", 
         "delivery_method": "cdn", 
         "source_port": 1935, 
         "stream_source_id": "def0vjqv", 
         "domain_name": "rtmp://origin.cdn.wowza.com", 
         "application_name": "live",
         "stream_name": "012p2abcKS3Vq93MGJIF6V5tIYS9560a", 
         ...
         "idle_timeout": 1200, 
         ...
         "outputs": [...] 
      } 
    }

Associate a Wowza stream source with a transcoder


If you prefer the transcoder workflow, which is more modular, you can create a transcoder at the same time as you associate it with a Wowza stream source.

  1. Create a transcoder with a delivery_method of cdn, and associate it with the stream source ID.

    Transcoder properties

    Parameter Data Type Description
    billing_mode string The billing mode for the stream. Use the default, pay_as_you_go.
    broadcast_location string Enter any valid broadcast location value. Wowza Streaming Cloud will override this value to use the closest ingest point based on a DNS query. For a list of valid values, see the REST API reference documentation.
    delivery_method string The method you’re using to deliver the video stream to the transcoder. Use cdn so the video stream will push to a stream source.
    idle_timeout integer Set an idle_timeout value that determines the amount of idle time, in seconds, before the transcoder automatically shuts down. Idle time begins after the video source is disconnected at the end of the live broadcast. The default is 1200 (20 minutes).
    name string The name of the transcoder. Enter an alphanumeric string (maximum 200 characters).
    protocol string The transport protocol you're using to send the encoded stream to the transcoder. Use rtmp.
    stream_source_id string The alphanumeric string that identifies the stream source that you want to use to deliver the stream to the transcoder. Use the ID of the Wowza stream source you just created.
    transcoder_type string Specify the default, transcoded. You can alternatively use passthrough, depending on your needs and the functionality available at your broadcast location.

    Example request and response

    Create a transcoder:

    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_oregon",     
            "delivery_method": "cdn",     
            "name": "Transcoder for Wowza Stream Source",     
            "protocol": "rtmp",     
            "stream_source_id": "def0vjqv",     
            "transcoder_type": "transcoded" 
        } 
       }' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

    This creates a transcoder without outputs or stream targets. The transcoder is associated with the existing Wowza stream source, and Wowza Streaming Cloud will override the broadcast_location value. The response should look something like this:

    {
      "transcoder": { 
         "id": "bgl4f37t", 
         "name": "Transcoder for Wowza Stream Source", 
         "transcoder_type": "transcoded", 
         "billing_mode": "pay_as_you_go", 
         "broadcast_location": "us_west_oregon", 
         "recording": false, 
         "closed_caption_type": "none", 
         "protocol": "rtmp", 
         "delivery_method": "cdn", 
         "source_port": 1935, 
         "stream_source_id": "def0vjqv", 
         "domain_name": "rtmp://origin.cdn.wowza.com",
         "application_name": "live", 
         "stream_name": "012p2abcKS3Vq93MGJIF6V5tIYS9560a", 
         ...
         "idle_timeout": 1200, 
         ...
         "outputs": [] 
      } 
    } 
  2. Complete the transcoder by adding outputs and stream targets. For instructions, see one of the following articles, depending on whether you're creating an adaptive bitrate stream or passthrough stream:

Test your connection


  1. Set up your video source using the primary_url and stream_name from the Wowza stream source details. The primary URL is the ingest location. For example:
    rtmp://origin.cdn.wowza.com:1935/live

    The stream_name is the alphanumeric stream name generated by Wowza Streaming Cloud to identify the specific stream. For example:
    012p2abcKS3Vq93MGJIF6V5tIYS9560a

    Refer to documentation for your specific encoder to note where to input the stream settings. 

    For example, Address or URL might be:
    rtmp://origin.cdn.wowza.com:1935/live

    While Stream or Stream key might be:
    012p2abcKS3Vq93MGJIF6V5tIYS9560a
  2. Start your video source.


    Wowza Streaming Cloud receives the stream from the source, starts transcoding, creates output renditions for the stream, and sends each output rendition to the stream target assigned to it.
  3. Using the Wowza Streaming Cloud REST API, fetch the state of the transcoder or live stream to confirm that it’s started.

    Fetch the state of the transcoder:

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/state"

    Fetch the state of the live stream:

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]/state"
  4. (Optional) In the Wowza Streaming Cloud user interface, confirm that the stream is working by looking at the Video Thumbnail on the Overview tab of the transcoder detail page or live stream detail page.
     
    Note: The API request to fetch a thumbnail URL of a transcoder or live stream does not work for a transcoder with a Wowza stream source.
  5. To end your test stream, stop the video source.

    Once you disable the video source, the transcoder or live stream continues to run and accrue charges until it reaches the default idle timeout value of 20 minutes. It then stops automatically. You can set the idle timeout value when you create or update the transcoder so that the transcoder stops sooner.

    Alternatively, you can use the REST API to stop the transcoder programmatically.

    Stop the transcoder:

    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/stop"

More resources