Pass a stream through the transcoder to a target with the Wowza Streaming Cloud REST API

Learn how to use the REST API to send a stream through the Wowza Streaming Cloud™ service without processing (how to create a passthrough stream) and deliver the stream to an external, third-party destination or to the Wowza CDN. Then, learn how to programmatically start and stop the transcoder.

Create a passthrough transcoder

---

Start by creating a transcoder that receives the stream from a source encoder but doesn't perform any transcoding.

Transcoder parameters

 

Example request and response

Notes:

• To authenticate API requests, use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
• The curl examples below use environment variables. See Using cURL for more information on how to set these up.

Create a passthrough 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_central_iowa",
     "delivery_method": "push",
     "name": " MyPassthruTranscoder",
     "protocol": "rtmp",
     "transcoder_type": "passthrough"
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

The command creates a passthrough 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_central_iowa",
    "buffer_size": 4000,
    "closed_caption_type": none,
    "created_at": "2015-07-22T13:33:16.575",
    "delivery_method": "push",
    "delivery_protocols": [
	"rtmp",
	"rtsp",
	"wowz"
    ],
    "direct_playback_urls": [],
    "disable_authentication": false,
    "domain_name": "[subdomain].entrypoint.cloud.wowza.com",
    "id": "1234abcd",
    "idle_timeout": 1200,
    "low_latency": false,
    "name": "MyPassthruTranscoder",
    "outputs": [],
    "password": "12345678",
    "play_maximum_connections": 10,
    "protocol": "rtmp",
    "recording": false,
    "source_port": 1935,
    "stream_name": "1a2a3a4a",
    "stream_smoother": false,
    "suppress_stream_target_start": false,
    "transcoder_type": "passthrough",
    "updated_at": "2015-07-22T13:33:16.575",
    "username": "client1",
    "watermark": false
  }
}

Related requests

View the details of a configured transcoder:
 

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

Update a transcoder's configuration:
 

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

Create an output for the transcoder

---

Next, define a passthrough output rendition that uses the source encoder's settings.

Passthrough rendition parameters

 

Example request and response

Create a passthrough output:
 

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "output": {
     "passthrough_audio": true.
     "passthrough_video": true,
     "stream_format": "audiovideo"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/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 a stream target for the output

---

Next, configure a stream target to define the destination for the passthrough output rendition. You can use a custom stream target to deliver the stream to a third-party CDN or a use a Wowza stream target to deliver the stream to Wowza CDN.

Note: Ultra low latency stream targets aren't compatible with the transcoder workflow. To learn more about ultra low latency streaming, see the Get started with ultra low latency streaming using the Wowza Streaming Cloud REST API.

Use a custom stream target

A custom stream target is a destination that allows you to leverage a third-party CDN. You can configure advanced properties for custom stream targets that use the akamai_cupertino provider.

Custom stream target parameters

 

Example request and response

Create a custom stream target:
 

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"

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_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"
   }
}

Use a Wowza stream target

A Wowza stream target is a destination that uses Wowza CDN to deliver the stream to players. With Wowza stream targets, you can use geo-blocking to control locations where your stream can be viewed, and you can use token authorization to restrict access to streams. Advanced properties are available for Wowza stream targets that use the akamai_cupertino provider.

Wowza stream target parameters

 

Example request and response

Create a Wowza stream target:
 

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_wowza": {
    "provider": "akamai_cupertino",
    "name": "MyWowzaTarget",
    "use_secure_ingest": true
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/wowza"

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_wowza": {
        "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"
    }
}

Add the stream target to the passthrough output

---

Finally, add the custom stream target to the passthrough output rendition.

Parameters

Example request and response

Add a target to an output:
 

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"

The details of the configured 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

Remove a target from an output:
 

curl -X DELETE \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/outputs/[output_id]/output_stream_targets/[output_stream_targets_id]"

Start and stop the transcoder

---

When the passthrough transcoder, output, and target are created, use the PUT method to start and stop the transcoder. Wowza Streaming Cloud will pass the stream through the transcoder and send the output to the target address.

Example requests

Start the transcoder:
 

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"

Stop the transcoder:
 

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 requests

View a transcoder's state:
 

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

Possible transcoder states are starting, stopping, started, stopped, and resetting.

View the details of a running transcoder:
 

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

Start all of a transcoder's stream targets:
 

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]/enable_all_stream_targets"

Stop all of a transcoder's stream targets:
 

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]/disable_all_stream_targets"

View a transcoder's preview image:
 

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

Delete a transcoder:
 

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