How to pass a stream through the transcoder to a target by using the Wowza Streaming Cloud REST API

Originally Published on 11/08/2016 | Updated on 07/11/2017 7:15 pm PDT

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. Then, learn how to programmatically start and stop the transcoder.

Contents

Create a passthrough transcoder Create an output for the transcoder Create a stream target for the output Add the stream target to the passthrough output 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

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: asia_pacific_taiwan, eu_belgium, us_central_iowa, or us_east_s_carolina.

4K streaming (3840x2160 aspect ratio) is not supported at these broadcast locations.
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.
name string The name of the transcoder. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyPassthrutranscoder.
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 (/).
transcoder_type string Specify the value passthrough.
 
Note: For information on other transcoder parameters, see the Wowza Streaming Cloud REST API Reference 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 passthrough 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_central_iowa",
     "delivery_method": "push",
     "name": " MyPassthruTranscoder",
     "protocol": "rtmp",
     "transcoder_type": "passthrough"
   } 
}' "https://api.cloud.wowza.com/api/v1/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": "1234567.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",
    "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 an output for the transcoder

Next, define a passthrough output rendition 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 workflows. For information on other output parameters, see the Wowza Streaming Cloud REST API Reference 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 a stream target for the output

Next, define a custom stream target--an RTMP destination--for the passthrough output rendition.

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. Specify 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 Wowza Streaming Cloud REST API Reference Documentation.

Example request and response

Create a custom stream target:
  
curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "stream_target": {
     "backup_url": "rtmp://backuptargetdomain.com/application",
     "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 target 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 the passthrough output

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

Parameters

Parameter Data Type Description
id string The unique alphanumeric string that identifies the passthrough output rendition that will deliver content to the stream target. You can find the ID in the details of the passthrough output 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 passthrough transcoder that will generate the output rendition. 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

Add 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 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 --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]/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 --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.

Was this article helpful?
Thank you for your feedback!

Thank you for providing feedback to help us improve our documentation!

If you need immediate help for an urgent issue, open a support ticket to get help from one of our technical support engineers. (You must have a valid Maintenance and Support contract to get technical support.)

© 2005–2017 Wowza Media Systems, LLC. All rights reserved.   Terms Privacy Trademarks Legal