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
| 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
Notes:Create a passthrough transcoder:
- For [key], substitute your Wowza Streaming Cloud API key or your access key as appropriate. For more information, see Locating and using API and access keys.
- For [version], substitute the version number of the API that you're using. For the current version, use v1.2.
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/[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 --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/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/[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
| 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/[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
| 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. |
| stream_name | string | The name of the stream as defined in the target's ingestion settings. The protocol, host name, and path components of the stream name URL must be 255 characters or less. The query strings and parameter components of the stream name URL must be 1024 characters or less. |
| username | string | The username or ID that the target uses for RTMP authentication. |
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 --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
"custom_stream_target": {
"name": "MyCustomTarget",
"password": "secret",
"primary_url": "rtmp://[targetdomain].com/application",
"provider": "rtmp",
"stream_name": "1a2b3c4d",
"username": "123456"
}
}' "https://api.cloud.wowza.com/api/[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:
{
"custom_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",
"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
| Parameter | Data Type | Description |
| name | string | A descriptive name for the stream target. Maximum 255 characters. |
| location | string | Only for Wowza stream targets whose provider is not akamai_cupertino—a location as close as possible to your video source. |
| provider | string | The options for Wowza CDN that you're using. Valid values are akamai, akamai_cupertino, akamai_legacy_rtmp. |
| use_cors | boolean | Only for Wowza stream targets whose provider is akamai_cupertino. CORS, or cross-origin resource sharing, allows streams to be safely delivered across domains. |
| use_secure_ingest | boolean | Only for Wowza stream targets whose provider is akamai_cupertino. If true, generates a secure_ingest_query_param to securely deliver the stream from the transcoder to the provider. |
Example request and response
Create a Wowza stream target:
curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
"wowza_stream_target": {
"provider": "akamai_cupertino",
"name": "MyWowzaTarget",
"use_secure_ingest": true
}
}' "https://api.cloud.wowza.com/api/[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:
{
"wowza_stream_target": {
"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
| 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 custom stream 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/[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 --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[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 --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/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/[version]/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/[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 --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/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/[version]/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/[version]/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/[version]/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/[version]/transcoders/[transcoder_id]"
