• How to create an ABR stream and send it to a target by using the Wowza Streaming Cloud REST API

    Learn how to use the REST API to ingest a single video encode into the Wowza Streaming Cloud™ service, transcode it to multiple adaptive bitrate renditions, and deliver the ABR output to a target, or destination. Then, learn how to programmatically start and stop the transcoder.

    Contents


    Create a transcoderCreate the highest bitrate output for the transcoderCreate additional, lower bitrate outputs for the transcoderCreate a stream target for the outputsAdd the stream target to each outputStart and stop the transcoder

    Create a transcoder


    Start by creating a transcoder that receives the stream from a source encoder.

    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 Specify the region that's closest to where your stream originates.

    For pay-as-you-go subscriptions, specify asia_pacific_australia, asia_pacific_india, asia_pacific_japan, asia_pacific_s_korea, asia_pacific_singapore, asia_pacific_taiwan, eu_belgium, eu_germany, eu_ireland, south_america_brazil, us_central_iowa, us_east_s_carolina, us_east_virginia, us_west_california, or us_west_oregon.

    For 24x7 subscriptions, specify asia_pacific_taiwan, eu_belgium, us_central_iowa, or us_east_s_carolina.

    4K streaming (3840x2160 aspect ratio) is not supported at asia_pacific_taiwan, eu_belgium, us_central_iowa, or us_east_s_carolina.
    buffer_size integer The size, in milliseconds, of the incoming buffer, which stores packets before they're processed to enable efficient transcoding. Valid values are 0, 1000, 2000, 3000, 4000, 5000, 6000, 7000, and 8000. The default is 4000.
    delivery_method string The method you're using to deliver the source stream to the transcoder. Use one of the following valid values:

    pull – (Default) Instructs Wowza Streaming Cloud to pull the stream from the RTMP or RTSP source.

    push – Instructs the RTMP or RTSP source to push the stream directly to Wowza Streaming Cloud.
    low_latency Boolean Speeds the time it takes to decode and deliver video data to the player by turning off the sort packet buffer. The default is false. Specify true to enable low latency.
    name string The name of the transcoder. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyABRtranscoder.
    protocol string The transport protocol you're using to send the encoded stream to the transcoder. Valid values are rtmp or rtsp.
    source_url string Required for RTMP and RTSP pull connections. Enter the source encoder's web address, without the preceding protocol or trailing slash (/).
    stream_extension string Optional for RTMP and RTSP push connections. Some encoders automatically append an extension to their stream names. If the device you're using does this, enter the extension.
    stream_smoother Boolean A dynamic buffer that helps stabilize streams in rough network conditions but adds latency. Recommended when pulling Akamai legacy RTMP streams or from a stream source. The default is false. Specify true to enable stream smoothing.
    transcoder_type string Specify the default, transcoded.

    Note: For information on other transcoder parameters, see the interactive Wowza Streaming Cloud API documentation.

    Example request and response

    Note: In all code examples, for [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
    Create a transcoder:

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "transcoder": {
         "billing_mode": "pay_as_you_go",
         "broadcast_location": "us_west_california",
         "buffer_size": 4000,
         "delivery_method": "push",
         "low_latency": true,
         "name": "MyABRtranscoder",
         "protocol": "rtsp",
         "transcoder_type": "transcoded"
       } 
    }' "https://api.cloud.wowza.com/api/v1/transcoders"
    The 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": {
        "application_name": "app-1234",
        "billing_mode": "pay_as_you_go",
        "broadcast_location": "us_west_california",
        "buffer_size": 4000,
        "closed_caption_type": none,
        "created_at": "2015-07-22T13:43:56.989",
        "delivery_method": "push",
        "delivery_protocols": [
          "rtmp",
          "rtsp",
          "wowz"
        ],
        "direct_playback_urls": [],
        "disable_authentication": false,
        "domain_name": "1234567.entrypoint.cloud.wowza.com",
        "id": "1234abcd",
        "idle_timeout": 1200,
        "low_latency": true,
        "name": "MyABRtranscoder",
        "outputs": [],
        "password": "12345678",
        "play_maximum_connections": 10,
        "protocol": "rtsp",
        "recording": false,
        "source_port": 1935,
        "stream_name": "1a2a3a4a",
        "stream_smoother": false,
        "suppress_stream_target_start": false,
        "transcoder_type": "transcoded",
        "updated_at": "2015-07-22T13:43:56.989",
        "username": "client1",
        "video_fallback": false,
        "watermark": false
      }
    }

    Related requests

    View the details of a configured transcoder:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]"
    Update a transcoder's configuration:

    curl -X PATCH --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "transcoder": {
         "name": "MyDifferentTranscoderName"
       }
    }' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]"

    Create the highest bitrate output for the transcoder


    Next, define the output renditions you want the transcoder to generate, starting with the highest bitrate rendition: a passthrough output that uses the source encoder's settings.

    Passthrough rendition parameters

    Parameter Data Type Description
    passthrough_audio Boolean Specify true to create the output from the highest bitrate received by the transcoder from the encoder.
    passthrough_video Boolean Specify true to create the output from the highest bitrate received by the transcoder from the encoder.
    stream_format string The contents of the stream. Valid values are audiovideo (both audio and video), videoonly, or audioonly.
    transcoder_id string The unique alphanumeric string that identifies the transcoder to which you want to add the output. You can find the ID in the details of the transcoder you just created.

    Note: Additional parameters are available for outputs, but they don't apply to passthrough output. For information on other output parameters, see the interactive Wowza Streaming Cloud API documentation.

    Example request and response

    Create a passthrough output:

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "output": {
         "passthrough_audio": true,
         "passthrough_video": true,
         "stream_format": "audiovideo"
       }
    }' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/outputs"
    The command creates the output with an id parameter but no targets ("targets": []). The details of the configured output are listed in the response, which should look something like this:

    {
       "output": {
        "bitrate_audio": 0,
        "bitrate_video": 0,
        "created_at": "2015-07-28T11:01:26.044",
        "framerate_reduction": 0,
        "h264_profile": null,
        "id": "5678efgh",
        "keyframes": "follow_source",
        "name": "Video+Audio=Passthrough+Passthrough",
        "passthrough_audio": true,
        "passthrough_video": true,
        "stream_format": "audiovideo",
        "targets": [],
        "transcoder_id": "1234abcd",
        "updated_at": "2015-07-28T11:01:26.044"
       }
    }

    Create additional, lower bitrate outputs for the transcoder


    Create as many additional outputs as you want the transcoder to generate. Additional outputs should be transcoded to create lower-quality renditions than the passthrough output. Depending on the resolution of the passthrough, you might want to create three to five additional outputs. For each additional output, specify the aspect ratio, bitrate, and profile you want to use.

    Additional output rendition parameters

    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. The default is 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. The default is 1920.
    bitrate_audio integer The audio bitrate, in kilobits per second (Kbps). Must be between 0 (for passthrough) and 1000. The default is 128.
    bitrate_video integer The video bitrate, in kilobits per second (Kbps). Must be between 0 (for passthrough) and 10240. The default is 4000.
    framerate_reduction string Reduce the frame rate of the transcoded output rendition when streaming in 4K at high frame rates. The default, 0, uses the encoded stream's frame rate without reduction.
    h264_profile string The encoding method. Specify main for desktop streaming, baseline for playback on mobile devices, or high for HD playback. The default is high.
    keyframes string Specify follow_source.
    passthrough_audio Boolean Specify false.
    passthrough_video Boolean Specify false.

    Example requests

    If your passthrough rendition is 1280x720, you might want to create four additional outputs.

    Create an 848x480 output:

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "output": {
         "aspect_ratio_height": 480,
         "aspect_ratio_width": 848,
         "bitrate_audio": 128,
         "bitrate_video": 1700,
         "framerate_reduction": 0,
         "h264_profile": "main",
         "keyframes": "follow_source",
         "passthrough_audio": false,
         "passthrough_video": false,
         "stream_format": "audiovideo"
       }
    }' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/outputs"
    Create a 640x360 output:

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "output": {
         "aspect_ratio_height": 360,
         "aspect_ratio_width": 640,
         "bitrate_audio": 128,
         "bitrate_video": 1024,
         "framerate_reduction": 0,
         "h264_profile": "main",
         "keyframes": "follow_source",
         "passthrough_audio": false,
         "passthrough_video": false,
         "stream_format": "audiovideo"
       }
    }' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/outputs"
    Create a 512x288 output:

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "output": {
         "aspect_ratio_height": 288,
         "aspect_ratio_width": 512,
         "bitrate_audio": 128,
         "bitrate_video": 512,
         "framerate_reduction": 0,
         "h264_profile": "baseline",
         "keyframes": "follow_source",
         "passthrough_audio": false,
         "passthrough_video": false,
         "stream_format": "audiovideo"
       }
    }' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/outputs"
    Create a 320x188 output:

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "output": {
         "aspect_ratio_height": 188,
         "aspect_ratio_width": 320,
         "bitrate_audio": 128,
         "bitrate_video": 320,
         "framerate_reduction": 0,
         "h264_profile": "baseline",
         "keyframes": "follow_source",
         "passthrough_audio": false,
         "passthrough_video": false,
         "stream_format": "audiovideo"
       }
    }' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/outputs"

    Related request

    Update an output configuration:

    curl -X PATCH --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "output": {
         "keyframes": 30
       }
    }' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/outputs/[output_id]"

    Create a stream target for the outputs


    Next, define a custom stream target—an RTMP destination—for the output renditions.

    Stream target parameters

    Parameter Data Type Description
    backup_url string Optional. The backup RTMP ingest URL (domain name or IP address) of the destination, entered without any protocol and without a trailing slash (/).
    name string A descriptive name for the stream target. Maximum 255 characters.
    password string The password associated with the target username for RTMP authentication.
    primary_url string The primary RTMP ingest URL (domain name or IP address) of the destination, entered without any protocol and without a trailing slash (/), for example, targetdomain.com/application.
    provider string The third-party CDN that you're using. Valid values are akamai, akamai_cupertino, akamai_rtmp, limelight, ustream, and, for all other destinations, rtmp.
    stream_name string The name of the stream as defined in the target's ingestion settings.
    type string Specify CustomStreamTarget for an external, third-party destination.
    username string The username or ID that the target uses for RTMP authentication.

    Note: For information on other stream target parameters, see the interactive Wowza Streaming Cloud API documentation.

    Example request and response

    Create a target:

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "stream_target": {
         "name": "MyCustomTarget",
         "password": "secret",
         "primary_url": "rtmp://targetdomain.com/application",
         "provider": "rtmp",
         "stream_name": "1a2b3c4d",
         "type": "CustomStreamTarget",
         "username": "123456"
       } 
    }' "https://api.cloud.wowza.com/api/v1/stream_targets"
    The command creates the target with an id parameter. The details of the configured output are listed in the response, which should look something like this:

    {
       "stream_target": {
         "backup_url": "rtmp://backuptargetdomain.com/application",
         "created_at": "2015-07-28T11:01:45.044",
         "id": "9123wxyz",
         "name": "MyCustomTarget",
         "password": "secret",
         "primary_url": "rtmp://targetdomain.com/application",
         "provider": "rtmp",
         "stream_name": "1a2b3c4d",
         "type": "CustomStreamTarget",
         "updated_at": "2015-07-28T11:01:45.044",
         "username": "123456"
       }
    }

    Add the stream target to each output


    Finally, add the stream target to each output rendition.

    Parameters

    Parameter Data Type Description
    id string The unique alphanumeric string that identifies the output rendition. You can find the ID in the details of each of the outputs you just created.
    stream_target_id string The unique alphanumeric string that identifies the stream target that will deliver the stream to viewers. You can find the ID in the details of the target you just created.
    transcoder_id string The unique alphanumeric string that identifies the transcoder that will generate the output renditions. You can find the ID in the details of the transcoder you just created.
    use_stream_target_backup_url Boolean Optional. Specify true to use the target's backup URL, if one is specified. The default is false.

    Example request and response

    Assign a target to an output:

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "output_stream_target": {
         "stream_target_id": "9123wxyz",
         "use_stream_target_backup_url": false
       } 
    }' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/outputs/[output_id]/output_stream_targets"
    The details of the assigned target are listed in the response, which should look something like this:

    {
       "output_stream_target": {
        "stream_target_id": "9123wxyz"
        "use_stream_target_backup_url": false
       }
    }

    Related request

    Update a target configuration:

    curl -X PATCH --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "stream_target": {
         "name": "MyNewTargetName"
       }
    }' "https://api.cloud.wowza.com/api/v1/stream_targets/[stream_target_id]"

    Start and stop the transcoder


    When the transcoder, outputs, and targets are created, use the PUT method to start and stop the transcoder. Wowza Streaming Cloud will ingest the stream from the source, create the passthrough output and the lower-quality transcoded output renditions, and send all of the outputs to the target address.

    Example requests

    Start the transcoder:

    curl -X PUT --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/start"
    Stop the transcoder:

     curl -X PUT --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/stop"

    Related requests

    View a transcoder's state:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/state"
    Possible transcoder states are starting, stopping, started, stopped, and resetting.

    View the details of a running transcoder:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/stats"
    Start all of a transcoder's stream targets:

    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/enable_all_stream_targets"
    Stop all of a transcoder's stream targets:

    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/disable_all_stream_targets"
    View a transcoder's preview image:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]/thumbnail_url"
    Delete a transcoder:

    curl -X DELETE --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_id]"

    Originally Published: 01-21-2016.
    Updated: 11-28-2016.

    If you're having problems or want to discuss this article, post in our forum.