Create an ABR stream and send it to a target with the Wowza Video 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:

  • API authentication methods . We use JSON web tokens for API authentication. See Authentication for more information.
  • Environment variables . We use environment variables for the API version and your JWT 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 the ingest protocol you'll use.
  • 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

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-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"
    } 
}' "${WV_HOST}/api/${WV_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": [ ] ); you'll create and configure these in a later step.
Copy
Copied
{
  "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

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
    "output": {
     "video_codec": "passthrough",
     "audio_codec": "passthrough"
    }
}' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs"

The response includes:

  • An id for the output rendition, which you will need to use if you would like to update an output rendition.
  • The details of the output. There are currently no targets ( "output_stream_targets": [ ] ); you'll create and configure these in a later step.

Sample response

Copy
Copied
{
  "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. The maximum number of outputs you can add to a single transcoder is 10.

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:

  • Specify the aspect_ratio_height , aspect_ratio_width , bitrate_video , and profile you want 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

Copy
Copied
curl -X POST 
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-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"
    }
}' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs"

Create a 640x360 output:

Endpoint Reference

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-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"
    }
}' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs"

Create a 512x288 output:

Endpoint Reference

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-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"
    }
}' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs"

Create a 320x188 output:

Endpoint Reference

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
 -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"
    }
}' "${WV_HOST}/api/${WV_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.

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

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
 -H "Authorization: Bearer ${WV_JWT}" \
-d '{
    "stream_target_custom": {
     "name": "MyCustomTarget",
     "password": "secret",
     "primary_url": "rtmp://[targetdomain].com/application",
     "provider": "rtmp",
     "stream_name": "1a2b3c4d",
     "username": "123456"
    } 
}' "${WV_HOST}/api/${WV_VERSION}/stream_targets/custom"

Sample response

Copy
Copied
    {
       "stream_target_custom": {
         "backup_url": "rtmp://[backuptargetdomain].com/application",
         "created_at": "2015-07-28T11:01:45.044",
         "id": "9123wxyz",
         "name": "MyCustomTarget",
         "password": "secret",
         "delivery_protocols": [
          "rtmp"
         ],
         "playback_urls": {},
         "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

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "stream_target_fastly": {
    "name": "My first Wowza CDN on Fastly target"
   } 
}' "${WV_HOST}/api/${WV_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.
Copy
Copied
{
    "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"
    }
}

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

Copy
Copied
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
    "output_stream_target": {
     "stream_target_id": "9123wxyz",
     "use_stream_target_backup_url": false
    } 
}' "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/outputs/[output_id]/output_stream_targets"

Sample response

Copy
Copied
    {
       "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 Video 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

Copy
Copied
curl -X PUT \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/start"

2. Stop the transcoder.

Endpoint Reference

Copy
Copied
curl -X PUT \
-H "Authorization: Bearer ${WV_JWT}" \
   "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/stop"

Related transcoder API requests

© 2007-2024 Wowza Media Systems, ™ LLC. All rights reserved.   Security & Privacy Policy | Legal | System Status