# Control a transcoder with a Wowza stream source using the Wowza Video REST API Learn how to use the Wowza Video™ REST API to set up a Wowza stream source with a live stream or transcoder. This allows Wowza Video to automatically detect broadcast location, automatically start a stream when the video source starts, and automatically stop a stream after the video source disconnects. Info For information about stream sources and their benefits see About Stream Sources. ## Before you start You should be familiar with the following concepts: - **API authentication** **methods**. We use JSON web tokens for API authentication. See [Authentication](/docs/wowza-video/about-the-rest-api/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](/docs/wowza-video/about-the-rest-api/api-overview#tools-for-testing-the-api) for instructions. You should complete the following tasks: - Install the **latest firmware installed** for your encoder. You should have access to the following items: - The **encoder's user guide** for details about how to operate the device or software and how to specify settings such as resolution, bitrate, and frame rate. You should choose between the following two workflows: - Decide between the **live stream** or **transcoder** workflow. See Decide between a live stream or transcoder workflow for more information about these workflows. details summary Live stream workflow ## Live stream workflow ### 1. Create a live stream Create a live stream that receives a RTMP source, generates a player, and configures a hosted page by sending a `POST` request to the `/live_streams` endpoint. You can use the following sample request, making sure to: - Set `encoder` to `other_rtmp`. - Set `broadcast_location`. This is a required parameter, so you'll have to set it even though it will be overriden by `use_stream_source`. To test the stream source automatically determining your **Broadcast Location**, we recommend you set this to a location on another continent. For example: set the location to Asia if you are primarily streaming from North America. - Set `use_stream_source` to `true`. - 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 '{ "live_stream": { "aspect_ratio_height": 1080, "aspect_ratio_width": 1920, "billing_mode": "pay_as_you_go", "broadcast_location": "us_west_oregon", "encoder": "other_rtmp", "delivery_method": "cdn", "name": "Live stream for Wowza Stream Source", "transcoder_type": "transcoded", "use_stream_source": "true" } }' "${WV_HOST}/api/${WV_VERSION}/live_streams" ``` #### Sample response The response includes: - An `ID` for the live stream that you can use to perform various operations. - Outputs, a stream source, and a stream target that have been automatically associated with a Wowza stream source. - `source_connection_information` you can use to configure a source encoder for the live stream. - `primary_server`, `host_port`, `application`, `stream_name`, `username`, and `password`. Wowza stream sources don't allow source authentication so both `username` and `password` are returned as `null`. ``` { "live_stream": { "id": "abcwksvr", "name": "Live Stream for Wowza Stream Source", "transcoder_type": "transcoded", "billing_mode": "pay_as_you_go", "broadcast_location": "us_west_california", "recording": false, "closed_caption_type": "none", "low_latency": false, "encoder": "other_rtmp", "delivery_method": "cdn", "target_delivery_protocol": "hls-https", "use_stream_source": true, "aspect_ratio_width": 1920, "aspect_ratio_height": 1080, "delivery_protocols": [ "rtmp", "rtsp", "wowz" ], "source_connection_information": { "primary_server": "rtmp://origin.cdn.wowza.com:1935/live", "host_port": 1935, "stream_name": "0I3q1ZXVEYX9nMDhmVGMUK0SZqXt6026", "username": "null", "password": "null" }, ... "stream_source_id":ab9cidkp, "stream_targets": [ { "id": "htwtwqxv" } ], "direct_playback_urls": {...}, "created_at": "2019-01-22T20:14:41.000Z", "updated_at": "2019-01-22T20:14:42.000Z" } } ``` ### 2. Configure your video source Use the `primary_url` and `stream_name` from the live stream response to configure your encoder. You'll need to refer to documentation for your specific encoder to determine where to input the `source_connection_information` settings, which include the stream and user credentials for authentication. If you were configuring OBS as the encoder, you'd enter the following stream settings in OBS: - **URL** is formatted as: rtmp://[*primary_server*]:[*host_port*]/[*application*] Where: - **[*primary_server*]** is the ingest location of the server. - **[*host_port*]** is the port (by default **1935**). - **[*application*]** is the application name for the stream assigned by Wowza Video. - **Stream key** is the `stream_name` value, such as b01bda67. Other encoders might use different names in their user interface, like **Address** instead of **URL** and **Stream** instead of **Stream key**. Make sure to refer to your encoder's documentation to determine the correct locations. ### 3. Test the connection Now that you have configured your source, you can test your live stream. You'll need the `[live_stream_id]` returned in step 1. 1. Start the stream in the RTMP encoder and the live stream in Wowza Video will also start. How you start the encoder varies by device. 2. Check the state to make sure the live stream started. Endpoint Reference ``` curl -X GET \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/live_streams/[live_stream_id]/state" ``` 3. Fetch a URL to a thumbnail that you can enter into a browser and visually confirm the stream is playing. Endpoint Reference ``` curl -X GET \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/live_streams/[live_stream_id]/thumbnail_url" ``` 4. In order to confirm that your current broadcast location was correctly identified, check the **Broadcast Location** for the live stream. If you created your stream source using the Wowza Video REST API, the `GET/live_stream/{id}` call will return the specific details. Endpoint Reference "live_stream": { "id": "z17fzfsb", "name": "Mystreamsource", "transcoder_type": "transcoded", "billing_mode": "pay_as_you_go", "broadcast_location": "asia_pacific_australia", 5. Stop the stream in the source camera or encoder, which will also stop the live stream in Wowza Video. ### Related API requests - GET/live_streams — View all live streams for an account. - GET/live_streams/ID — View the details of a live stream, including the player embed code and hosted page URL. - PATCH/live_streams/ID — Update a live stream's configuration. details summary Transcoder workflow ## Transcoder workflow ### 1. Create a Wowza stream source In the transcoder workflow, you'll first add the stream source and then manually configure the transcoder to use it. Create a Wowza stream source by sending a `POST` request to the `/stream_sources/wowza` endpoint. You can use the following sample request, making sure to: - Set `name` to a short, descriptive, alphanumeric string for your Wowza stream 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 '{ "stream_source_wowza": { "name": "Auto-starting stream source" } }' "${WV_HOST}/api/${WV_VERSION}/stream_sources/wowza" ``` #### Sample response The response includes: - An *id* for the stream source that you'll use throughout the rest of this task. ``` { "stream_source_wowza": { "id": "def0vjqv", "name": "Auto-starting stream source", "primary_url": "rtmp://origin.cdn.wowza.com:1935/live", "stream_name": "012p2abcKS3Vq93MGJIF6V5tIYS9560a", "state": "stopped", "created_at": "2018-12-12T15:37:55.000Z", "updated_at": "2018-12-12T15:37:55.000Z" } } ``` Info Wowza stream sources don't allow source authentication. ### 2. Create a transcoder Create a transcoder with a `delivery_method` of `cdn` and associate it with the stream source by sending a `POST` request to the `/transcoders` endpoint. You can use the following sample request, making sure to: - Set* `delivery_method` to `cdn`. - Set `broadcast_location`. This is a required parameter, so you'll have to set it even though it will be overriden by the stream source. To test the stream source automatically determining your **Broadcast Location**, we recommend you set this to a location on another continent. For example: set the location to Asia if you are primarily streaming from North America. - Set `stream_source_id` to the ID returned in step 1. - 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_west_oregon", "delivery_method": "cdn", "name": "Transcoder for Wowza Stream Source", "protocol": "rtmp", "stream_source_id": "def0vjqv", "transcoder_type": "transcoded" } }' "${WV_HOST}/api/${WV_VERSION}/transcoders" ``` The response includes: - An ID for the transcoder that you'll use throughout the rest of this task. - An empty `outputs` array that you'll configure in step 3. - *Source connection information* you'll use in step 4 to configure a source for the stream. - `domain_name`, `source_port`, `application_name`, `stream_name`, `username`, and `password`. ``` { "transcoder": { "id": "bgl4f37t", "name": "Transcoder for Wowza Stream Source", "transcoder_type": "transcoded", "billing_mode": "pay_as_you_go", "broadcast_location": "us_west_oregon", "recording": false, "closed_caption_type": "none", "protocol": "rtmp", "delivery_method": "cdn", "source_port": 1935, "stream_source_id": "def0vjqv", "domain_name": "rtmp://origin.cdn.wowza.com", "application_name": "live", "stream_name": "012p2abcKS3Vq93MGJIF6V5tIYS9560a", ... "idle_timeout": 1200, ... "outputs": [] } } ``` ### 3. Add output renditions and stream targets Complete the transcoder by adding output renditions and stream targets. For instructions, see one of the following articles, depending on whether you're creating an adaptive bitrate or passthrough transcoder: Info You'll need the transcoder ID from step 1. - **Adaptive bitrate transcoder** — [Create an ABR stream and send it to a target with the Wowza Video REST API](/docs/wowza-video/guides/more-tasks/create-an-abr-stream-and-send-to-a-target) - **Passthrough transcoder** — [Pass a stream through the transcoder to a target with the Wowza Video REST API](/docs/wowza-video/guides/more-tasks/pass-a-stream-through-the-transcoder-to-a-target) ### 4. Configure your video source Use the `primary_url` and `stream_name` from the live stream response to configure your encoder. You'll need to refer to documentation for your specific encoder to determine where to input the `source_connection_information` settings, which include the stream and user credentials for authentication. If you were configuring OBS as the encoder, you'd enter the following stream settings in OBS: - **URL** is formatted as: rtmp://[*primary_server*]:[*host_port*]/[*application*] Example: rtmp://origin.cdn.wowza.com:1935/live Where: - **[*primary_server*]** is the ingest location of the server - **[*host_port*]** is the port (by default **1935**) - **[*application*]** is the application name for the stream assigned by Wowza Video - **Stream key** is the `stream_name` value, such as 12p2abcKS3Vq93MGJIF6V5tIYS9560a. Other encoders might use different names in their user interface, like **Address** instead of **URL** and **Stream** instead of **Stream key**. Make sure to refer to your encoder's documentation to determine the correct locations. ### 5. Test the connection Now that you have configured your source, you can test your transcoder. You'll need the `[transcoder_id]` returned in step 2. 1. Start the stream in the RTMP encoder and the live stream in Wowza Video will also start. How you start the encoder varies by device. 2. Check the state to make sure the transcoder started. Endpoint Reference ``` curl -X GET \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/state" ``` 3. Start the stream in the encoder. How you start the encoder varies by device. 4. Fetch a URL to a thumbnail that you can enter into a browser and visually confirm the stream is playing. Endpoint Reference ``` curl -X GET \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id]/thumbnail_url" ``` 5. In order to confirm your correct broadcast location was picked up: Endpoint Reference ``` curl -X GET \ -H "Authorization: Bearer ${WV_JWT}" \ "${WV_HOST}/api/${WV_VERSION}/transcoders/[transcoder_id] ``` Which will return a result similar to: ``` { "transcoder": { "id": "z17fzfsb", "name": "Mystreamsource", "transcoder_type": "transcoded", "billing_mode": "pay_as_you_go", "broadcast_location": "asia_pacific_australia", "closed_caption_type": "none", "protocol": "webrtc", "delivery_method": "push", "source_port": 443, ``` 6. Stop the stream in the source camera or encoder, which will also stop the live stream in Wowza Video. ### 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. ### More resources - [Speed up the connection to a transcoder with the Wowza Video REST API](/docs/wowza-video/guides/more-tasks/speed-up-the-connection-to-a-transcoder)