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

Updated on 05/25/2022 7:29 pm PDT

Send a stream directly to an external, third-party destination or to the Wowza CDN without performing transcoding using the Wowza Video 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 Video.

Before you start

You should be familiar with the following concepts:

  • API authentication methods. We use JSON web tokens for API authentication. See Authentication for more information.
  • Environment variables. We use environment variables for the API version and your JWT 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

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_central_iowa",
     "delivery_method": "push",
     "name": " MyPassthruTranscoder",
     "protocol": "rtmp",
     "transcoder_type": "passthrough"
   } 
}' "${WV_HOST}/api/${WV_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.video.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

A custom stream target is a destination that allows you to leverage a third-party CDN. 

You can use the following sample request, making sure to:

  • Set provider to the third-party CDN that you're using. Valid values are 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

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "stream_target_custom": {
     "name": "MyCustomTarget",
     "password": "secret",
     "primary_url": "rtmp://[targetdomain].com/application",
     "provider": "rtmp",
     "stream_name": "1a2b3c4d",
     "username": "123456"
   } 
}' "${WV_HOST}/api/${WV_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

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "stream_target_fastly": {
     "name": "My first Wowza CDN on Fastly target"
   } 
}' "${WV_HOST}/api/${WV_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"
    }
}

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

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "output_stream_target": {
     "stream_target_id": "9123wxyz",
     "use_stream_target_backup_url": false
   } 
}' "${WV_HOST}/api/${WV_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 Video. 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 Video will pass the stream through the transcoder and send the output to the target address.

Related API requests

Was this article helpful?
Thank you for your feedback!
User Icon

<p align="left">Thank you for providing feedback to help us improve our documentati

© 2007–2023 Wowza Media Systems™, LLC. All rights reserved.   Security & Privacy PolicyLegalSystem Status