Connect a UDP encoder to Wowza Streaming Cloud using the Wowza Streaming Cloud REST API

The Wowza Streaming Cloud™ service can connect to any H.264 encoder that supports the User Datagram Protocol (UDP). UDP is a connectionless protocol that makes it easier to transmit information quickly, but is also more prone to network issues, packet loss, and packets arriving out of order.

You'll need to choose which workflow you'll use, live stream or transcoder, before you begin this task. See Decide between a live stream or transcoder workflow for more information about these workflows.

Note: Source authentication isn't available for UDP.

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.

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.

Live Stream Workflow

1. Create a live stream

Create a live stream that receives a UDP 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_upd.
  • Set delivery_method to push. Wowza Streaming Cloud doesn't support pull or cdn connections for UDP.
  • 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 "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "live_stream": {
     "aspect_ratio_height": 720,
     "aspect_ratio_width": 1280,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "delivery_method": "push",
     "encoder": "other_udp",
     "name": "MyUDPStream",
     "transcoder_type": "transcoded"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/live_streams"

Sample response

The response includes:

  • An id for the live stream that you'll use in step 3.
  • source_connection_information you'll use in the next step to configure an UDP source encoder for the live stream.
    • primary_server and host_port
{
   "live_stream": {
     "id": "1234abcd",
     "name": "MyUDPStream",
     ...
     "encoder": "other_udp",
     ...
     "source_connection_information": {
       "primary_server": "udp://[subdomain].entrypoint.cloud.wowza.com",
       "host_port": "10000",
       "stream_name": "54g2813p"
       "disable_authentication": "true"
     },
     ...
   }
}

2. Configure your video source


Use the source_connection_information from the live stream response to configure your UDP 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.

  • Address is the primary_server value:
    udp://[wowza.subdomain].entrypoint.cloud.wowza.com
  • Destination Port is the host_port value, such as 10000.

Authentication is disabled by default for UDP streams. Different encoders might use different names in their user interface, like URL instead of Address. 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 your live stream.

    Endpoint Reference

    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/start"

     
  2. Check the state to make sure the live stream started.

    Endpoint Reference

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/state"

     
  3. Start the stream in the UDP 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 "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/thumbnail_url"

     
  5. Stop the live stream.

    Endpoint Reference

    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/stop"
  6. Stop the stream in the source camera or encoder.

Related API requests

Transcoder Workflow

1. Create a transcoder

In the transcoder workflow, you'll manually configure the transcoder, output renditions, and stream targets to fit your specific streaming solution.

Create a transcoder that receives a UDP source by sending a POST request to the /transcoders endpoint.

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

  • Set protocol to udp.
  • 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 "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{    
  "transcoder": { 
    "billing_mode": "pay_as_you_go",      
    "broadcast_location": "us_west_california",      
    "delivery_method": "push",      
    "name": "MyUDPTranscoder",      
    "protocol": "udp",      
    "transcoder_type": "transcoded"
  } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

The response includes:

  • An id for the transcoder that you'll use throughout the rest of this task
  • Source connection information you'll use in step 3 to configure an UDP source for the stream.
    • domain_name and source_port
{ 
  "transcoder": { 
    "id": "tmd8ybp2", 
    "name": "MyUDPTranscoder", 
    "transcoder_type": "transcoded", 
    "billing_mode": "pay_as_you_go", 
    "broadcast_location": "us_west_california", 
    ... 
    "protocol": "udp", 
    "delivery_method": "push", 
    "source_port": 10000, 
    "domain_name": "[hostname].entrypoint.cloud.wowza.com", 
    ...
    "outputs": []
  } 
} 

2. 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:

Note: You'll need the transcoder ID from step 1.

3. Configure the source of your transcoder


Use the the domain_name and source_port values returned when you created the transcoder to configure your UDP encoder. You'll need to refer to documentation for your specific encoder to determine where to input the stream settings and user credentials for authentication.

  • Address is the domain_name value:
    [hostname_name]:entrypoint.cloud.wowza.com
  • Destination Port is the source_port value:
    10000

Authentication is disabled by default for UDP streams. Different encoders might use different names in their user interface, like URL instead of Address. Make sure to refer to your encoder's documentation to determine the correct locations.

4. Test the transcoder connection


Now that you have configured your source, you can test your transcoder. You'll need the [transcoder_id] returned in step 1.

  1. Start the transcoder.

    Endpoint Reference

    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/start"
    
    

     
  2. Check the state to make sure the transcoder started.

    Endpoint Reference

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/state"

     
  3. Start the stream in the encoder. How you start the encoder varies by device.
     
  4. Fetch a thumbnail that shows a frame of the playing stream to visually confirm the stream is playing.

    Endpoint Reference

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/thumbnail_url"

     
  5. Stop the transcoder.

    Endpoint Reference

    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/stop"

     
  6. Stop the stream in the source camera or encoder.

Related Transcoder API requests