Create an ABR stream and send it to a target with 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.

Before you start


You should be familiar with the following concepts:

  • An API authentication method. Use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
  • We use environment variables for the API version and your API and access keys 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.
     

1. Create a transcoder


Create a transcoder that receives the stream from a source encoder or file by sending a POST request to the /transcoders endpoint. 

You can use the following sample request, making sure to:

  • Set protocol to rtsp.
  • Set delivery_method to push
  • Set low_latency to true to speed up the time it takes to decode and deliver video data to the player by turning off the sort packet buffer. This is set to false by default.
  • 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 "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",
     "buffer_size": 4000,
     "delivery_method": "push",
     "low_latency": true,
     "name": "MyABRtranscoder",
     "protocol": "rtsp",
     "transcoder_type": "transcoded"
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

Sample response

The response includes:

  • An id for the transcoder that you'll use for various requests, including starting and stopping the stream.
  • The details of the transcoder. There are currently no outputs ("outputs": []).
     
{
  "transcoder": {
    "application_name": "app-B8P6K226",
    "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",
      "webrtc"
    ],
    "direct_playback_urls": {...},
    "disable_authentication": false,
    "domain_name": "[subdomain].entrypoint.cloud.wowza.com",
    "id": "1234abcd",
    "idle_timeout": 1200,
    "low_latency": true,
    "name": "MyABRtranscoder",
    "outputs": [],
    "password": "12345678",
    "playback_stream_name": "f8758cd3",
    "play_maximum_connections": 10,
    "protocol": "rtsp",
    "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",
    "watermark": false
  }
}

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

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "output": {
     "video_codec": "passthrough",
     "audio_codec": "passthrough"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/outputs"

The response includes:

  • An id for the output, which you will need to use if you would like to update an output.
  • The details of the output. There are currently no targets ("output_stream_targets": []).

Sample response

{
   "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",
    "video_codec": "passthrough",
    "audio_codec": "passthrough",
    "output_stream_targets": [],
    "transcoder_id": "1234abcd",
    "updated_at": "2015-07-28T11:01:26.044"
   }
}

3. Create additional, lower bitrate outputs for the transcoder


Now that you have created one output, you can create up to 9 additional outputs for the transcoder to generate for a total of 10 outputs.

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.

You can use the following sample requests, making sure to:

  • Set specify the aspect_ratio_height, aspect_ratio_width, bitrate_video, and profile you want to for your unique broadcast.
  • Change any additional values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.

Create a 480x848 output:

Endpoint Reference

curl -X POST 
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "output": {
     "audio_codec": "aac",
     "video_codec": "h264",
     "aspect_ratio_height": 480,
     "aspect_ratio_width": 848,
     "bitrate_audio": 128,
     "bitrate_video": 1700,
     "framerate_reduction": 0,
     "h264_profile": "main",
     "keyframes": "follow_source"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/outputs"

Create a 640x360 output:

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "output": {
     "audio_codec": "aac",
     "video_codec": "h264",
     "aspect_ratio_height": 360,
     "aspect_ratio_width": 640,
     "bitrate_audio": 128,
     "bitrate_video": 1024,
     "framerate_reduction": 0,
     "h264_profile": "main",
     "keyframes": "follow_source"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/outputs"

Create a 512x288 output:

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "output": {
     "audio_codec": "aac",
     "video_codec": "h264",
     "aspect_ratio_height": 288,
     "aspect_ratio_width": 512,
     "bitrate_audio": 128,
     "bitrate_video": 512,
     "framerate_reduction": 0,
     "h264_profile": "baseline",
     "keyframes": "follow_source"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/outputs"

Create a 320x188 output:

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "output": {
     "audio_codec": "aac",
     "video_codec": "h264",
     "aspect_ratio_height": 188,
     "aspect_ratio_width": 320,
     "bitrate_audio": 128,
     "bitrate_video": 320,
     "framerate_reduction": 0,
     "h264_profile": "baseline",
     "keyframes": "follow_source"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/outputs"

4. Create a stream target for the outputs


Next, configure a stream target to define the destination for the output renditions. You can use one of the following stream targets:

Custom stream target

A custom stream target is a destination that allows you to leverage a third-party CDN. Advanced properties are available for stream targets that use the akamai_cupertino provider.

You can use the following sample request, making sure to:

  • Set primary_url to the primary RTMP ingest URL of the destination, for example targetdomain.com/application.
  • Set username and password to the username/ID and password associated with the target username for RTMP authentication.
  • Set provider to the value for the CDN you're using. Valid values are akamai, akamai_cupertino, akamai_legacy_rtmp.
  • Set stream_name to the name of the stream as defined in the target's ingestion settings.
  • 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 "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "stream_target_custom": {
     "name": "MyCustomTarget",
     "password": "secret",
     "primary_url": "rtmp://[targetdomain].com/application",
     "provider": "rtmp",
     "stream_name": "1a2b3c4d",
     "username": "123456"
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/custom"

Sample response
 

{
   "stream_target_custom": {
     "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",
     "updated_at": "2015-07-28T11:01:45.044",
     "username": "123456"
   }
}

Wowza CDN on Fastly stream target

A Wowza CDN on Fastly stream target is a destination that uses Wowza CDN to deliver the stream to players. We recommend using Wowza CDN on Fastly stream targets for new stream configurations. Advanced properties are available for Wowza CDN on Fastly stream targets.

You can use the following sample request, making sure to:

  • 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 "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "stream_target_fastly": {
     "name": "My first Wowza CDN on Fastly target"
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/fastly"

Sample response

The response includes:

  • An ID for the stream target that you'll use in step 3 to assign the stream target to the transcoder.
{
    "stream_target_fastly": {
        "id": "lwzgrj9r",
        "name": "My first Wowza CDN on Fastly target",
        "state": "activated",
        "stream_name": "ZmYxSXRrTERrUlk9",          
        "playback_urls": {
          "hls": [
            {
	      "name": "default",
              "url": "https://[subdomain].wowza.com/1/[stream_id]/[stream_name]/hls/live/playlist.m3u8"
            }
          ]
        },
        "token_auth_enabled": false,
        "token_auth_playlist_only": false,
        "geoblock_enabled": false,
        "geoblock_by_location": "disabled",
        "geoblock_ip_override": "disabled",
        "force_ssl_playback": false,
        "created_at": "2021-07-22T16:38:21.000Z",
        "updated_at": "2021-07-22T16:38:21.000Z"
    }
}

Wowza CDN on Akamai stream target

A Wowza CDN on Akamai stream target is a destination that uses Wowza CDN to deliver the stream to players. Advanced properties are available for stream targets that use the akamai_cupertino provider.

You can use the following sample request, making sure to:

  • Set provider to the value for the CDN you're using. Valid values are akamai, akamai_cupertino, akamai_legacy_rtmp.
  • Set location as close as possible to your video source if your provider is not akamai_cupertino.
  • Set use_secure_ingest to true if your provider is akamai_cupertino and you would like to generate a secure_ingest_query_param
  • Set use_cors to true if your provider is akamai_cupertino and you would like to allow streams to be safely delivered across all domains.

Sample request

Endpoint Reference

curl -X POST 
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
  "stream_target_akamai": {
    "provider": "akamai_cupertino",
    "name": "MyWowzaTarget",
    "use_secure_ingest": true
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/akamai"

Sample response

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_akamai": {
        "id": "abcp30wb",
        "name": "MyWowzaTarget",
        "provider": "akamai_cupertino",
        "use_secure_ingest": true,
        "secure_ingest_query_param": "[ingest query parameter string]",
        "use_cors": false,
        "stream_name": "1dee3a1f",
        "primary_url": "http://[wowzasubdomain]-i.akamaihd.net/687319/1dee3a1f",
        "hls_playback_url": "https://[wowzasubdomain]-i.akamaihd.net/hls/live/687319/1dee3a1f/playlist.m3u8",
        "connection_code": "1ZfOn3",
        "connection_code_expires_at": "2018-08-31T16:35:38.000Z",
        "created_at": "2018-08-30T16:35:38.000Z",
        "updated_at": "2018-08-30T16:35:38.000Z"
    }
}

5. Add the stream target to each output


Now that you have created a stream target for each output, you can add the stream target to each output rendition.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "output_stream_target": {
     "stream_target_id": "9123wxyz",
     "use_stream_target_backup_url": false
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/outputs/[output_id]/output_stream_targets"

Sample response

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

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

1. Start the transcoder:

Endpoint Reference

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/start"

2. Stop the transcoder.

Endpoint Reference

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/stop"

Related transcoder API requests