Send a stream directly to an external, third-party destination or to the Wowza CDN without performing transcoding using the Wowza Streaming Cloud REST API. Passthrough transcoders are useful when you want lower latency and your source stream is already optimally encoded for playback that most of your audience would be watching the stream at. For more information comparing passthrough and adaptive bitrate transcoders, see Transcoding best practices in Wowza Streaming Cloud.
Before you start
You should be familiar with the following concepts:
- API authentication methods. Use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
- Environment variables. We use environment variables for the API version and your API and access keys 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 passthrough transcoder with a passthrough output rendition
Create a transcoder that receives the stream from a source encoder or file but doesn't perform any transcoding by sending a POST request to the /transcoders endpoint.
You can use the following sample request, making sure to:
- Set protocol to the protocol you want to use. Valid values are rtmp, rtsp, srt, udp, or webrtc.
- Set transcoder_type to passthrough.
- 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
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"Sample response
The response includes:
- An ID for the transcoder that you'll use to complete other actions on the transcoder.
- An outputs array that contains the passthrough output rendition. You'll use the ID for the output rendition in the next step to assign a stream target.
{
"transcoder": {
"application_name": "app-B8P6K226",
"billing_mode": "pay_as_you_go",
"broadcast_location": "us_central_iowa",
"buffer_size": 4000,
"closed_caption_type": none,
"created_at": "2021-07-22T13:33:16.575",
"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": false,
"name": "MyPassthruTranscoder",
"outputs": [
{
"id": "qnqnjfmp",
"name": "Standard Output: Video + Audio",
"transcoder_id": "bpfvfxz9",
"video_codec": "passthrough",
"audio_codec": "passthrough",
"aspect_ratio_width": 1024,
"aspect_ratio_height": 768,
"bitrate_video": 0,
"bitrate_audio": 0,
"h264_profile": "high",
"framerate_reduction": "0",
"keyframes": "follow_source",
"created_at": "2021-07-22T13:33:16.575Z",
"updated_at": "2021-07-22T13:33:16.575Z",
"output_stream_targets": []
}
],
"password": "12345678",
"playback_stream_name": "f8758cd3",
"play_maximum_connections": 10,
"protocol": "rtmp",
"source_port": 1935,
"stream_name": "1a2a3a4a",
"stream_smoother": false,
"suppress_stream_target_start": false,
"transcoder_type": "passthrough",
"updated_at": "2021-07-22T13:33:16.575",
"username": "client1",
"watermark": false
}
}2. Create a stream target for the output
Configure a stream target to define the destination for the passthrough output rendition. You can use one of the following stream targets:
- Custom stream target — Delivers the stream to a third-party CDN.
- Wowza CDN on Fastly stream target — Delivers the stream to Wowza CDN using Fastly.
- Wowza CDN on Akamai stream target — Delivers the stream to Wowza CDN using Akamai.
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.
You can use the following sample request, making sure to:
- Set provider to the third-party CDN that you're using. Valid values are akamai, akamai_cupertino, akamai_rtmp, limelight, ustream, and, for all other destinations, rtmp or rtmps.
- Set primary_url to the primary RTMP ingest URL (domain name or IP address) of the destination, entered without any protocol and without a trailing slash (/). Example: targetdomain.com/application.
- Set username to the username or ID that the target uses for RTMP authentication.
- Set password to the password associated with the target username for RTMP authentication.
- Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.
Sample request
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"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.
{
"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": "2021-07-22T11: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
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_fastly": {
"name": "My first Wowza CDN on Fastly target"
}
}' "${WSC_HOST}/api/${WSC_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.
{
"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"
}
}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.
You can use the following sample request, making sure to:
- Set provider to akamai_cupertino.
- Set use_secure_ingest to true. This generates a secure_ingest_query_param to securely deliver the stream from the transcoder to the provider.
- Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.
Sample request
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"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.
{
"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": "2021-07-23T16:35:38.000Z",
"created_at": "2021-07-22T16:35:38.000Z",
"updated_at": "2021-07-22T16:35:38.000Z"
}
}3. Add the stream target to the passthrough output
Add the custom stream target to the passthrough output rendition by sending a POST request to /transcoders/[transcoder_id]/outputs/[output_id]/output_stream_targets.
You can use the following sample request, making sure to:
- Set transcoder_id in the request path to the ID returned when you created the transcoder.
- Set output_id in the request path to the ID returned when you created the transcoder.
- Set output_stream_id to the ID returned when you created the stream target.
- Set protocol to rtmp.
- 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
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"Sample response
{
"output_stream_target": {
"stream_target_id": "9123wxyz",
"use_stream_target_backup_url": false
}
}Next steps
- You'll need to configure your video source so it's connected to Wowza Streaming Cloud. The transcoder workflow sections of these articles can help you: Connect a source.
- With the passthrough transcoder, output, and target created and the video source configured, 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.
Related API requests
- GET /transcoders — View all transcoders for an account.
- GET /transcoders/[ID] — View the details of a transcoder.
- PATCH /transcoders/[ID] — Update a transcoder's configuration.
- GET /transcoders/[ID]/state — View the state of the transcoder.
- GET /transcoders/[ID]/stats — View the details of a running transcoder.
- PUT /transcoders/[ID]/enable_all_stream_targets — Start all of a transcoder's stream targets.
- PUT /transcoders/[ID]/disable_all_stream_targets — Stop all of a transcoder's stream targets.
- DELETE /transcoders/[transcoder_id]/outputs/[output_id]/output_stream_targets/[output_stream_targets_id] — Remove a target from an output.
- DELETE /transcoders/[transcoder_id] — Delete a transcoder and all of it's assigned output renditions and stream targets.
