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

Learn how to use the Wowza Streaming Cloud REST API to send a stream directly to an external, third-party destination or to the Wowza CDN without performing transcoding. 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 or file 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 CDN on Akamai 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

 

Note: For information on other custom stream target parameters, see the Wowza Streaming Cloud REST API Reference Documentation.

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

Wowza CDN on Akamai stream target parameters

 

Example request and response

Create a Wowza CDN on Akamai 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_akamai": {
    "provider": "akamai_cupertino",
    "name": "MyWowzaTarget",
    "use_secure_ingest": true
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/akamai"

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

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