Connect an RTSP 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 RTSP network protocol. This article describes how to use the Wowza Streaming Cloud REST API to create a live stream or transcoder and configure an RTSP-based encoder as the video source.

Create a live stream


You can use a live stream workflow or a transcoder workflow in Wowza Streaming Cloud. The live stream workflow allows you to configure more settings in one API request, while the transcoder workflow allows more modular, custom configuration of settings using multiple API requests. Start with this section if you choose the live stream workflow.

  1. Using the Wowza Streaming Cloud REST API, create a live stream.

    Live stream parameters

    Parameter Data Type Description
    aspect_ratio_height integer The height, in pixels, of the output rendition. Should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Set the aspect ratio of the live stream to match the aspect ratio in your encoder settings.
    aspect_ratio_width integer The width, in pixels, of the output rendition. Should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Set the aspect ratio of the live stream to match the aspect ratio in your encoder settings.
    billing_mode string The billing mode for the stream. Use the default, pay_as_you_go.
    broadcast_location string Specify the region that's closest to where your stream originates. For a list of valid regions, see the API reference documentation.
    delivery_method string The method you're using to deliver the source stream to the transcoder. Use push so the RTSP video source pushes the stream to Wowza Streaming Cloud.

    You can alternatively set the delivery_method to pull. Pull streams require a source_url value.
    encoder string The video source for the live stream. Use other_rtsp.
    name string The name of the live stream. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyIPCameraLiveStream.
    source_url string Required for a pull stream only. The URL of an RTSP video encoder. Consult the encoder documentation for the URL syntax.

    The hostname or IP address used in the source_url must be publicly accessible. If authentication information, such as username and password, is included in the source_url, it can only contain alphanumeric, period (.), underscore (_), and hyphen (-) characters. By default, Wowza Streaming Cloud uses TCP port 554 for RTSP streaming. If you don't use the default port, be sure to indicate that in the source URL.
    transcoder_type string Specify the default, transcoded. You can alternatively use passthrough, depending on your needs and the functionality available at your broadcast location.

    For a full list of live stream parameters, see Live Streams in the Wowza Streaming Cloud API reference.

    Example request and response

    Notes:
    • For [key], substitute your 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 '{
       "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_rtsp",
         "name": "MyLiveStream",
         "transcoder_type": "transcoded"
       }
    }' "https://api.cloud.wowza.com/api/[version]/live_streams"

    The command creates a live stream with an id parameter, an associated player, and a hosted page. The details of live stream's configuration are listed in the response. For a push connection, you'll use the source connection information to configure an RTSP source encoder for the live stream.

    {
       "live_stream": {
         "id": "1234abcd",
         "name": "MyLiveStream",
         ...
         "encoder": "other_rtsp",
         ...
         "source_connection_information": {
           "primary_server": "rtsp://[subdomain].entrypoint.cloud.wowza.com/app-16d7",
           "host_port": 1935,
           "stream_name": "32a5814b",
           "disable_authentication": false,
           "username": "client2",
           "password": "1234abcd"
         },
         ...
       }
    }

    Related API requests

    View all live streams for the account:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams"

    View the details of a live stream, including the player embed code and hosted page URL:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]"

    Update a live stream's configuration:

    curl -X PATCH --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "live_stream": {
         "name": "MyDifferentLiveStreamName"
       }
    }' "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]"
  2. After creating the live stream, configure the source encoder. See Configure the source for next steps.

Create a transcoder


The transcoder workflow allows more modular, custom configuration of settings using multiple API requests. Start with this section if you choose the transcoder workflow.

  1. Using the Wowza Streaming Cloud REST API, create a transcoder.

    Transcoder parameters

    Parameter Data Type Description
    billing_mode string The billing mode for the stream. Use the default, pay_as_you_go.
    broadcast_location string Specify the region that's closest to where your stream originates. For a list of valid regions, see the API reference documentation.
    delivery_method string The method you're using to deliver the source stream to the transcoder. Use push so the RTSP video source pushes the stream to Wowza Streaming Cloud.

    You can alternatively set the delivery_method to pull. Pull streams require a source_url value.
    name string The name of the transcoder. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyIPCameraTranscoder.
    protocol string The transport protocol you're using to send the encoded stream to the transcoder. Use rstp.
    source_url string Required for a pull stream only. The URL of an RTSP video encoder. Consult the encoder documentation for the URL syntax.

    The hostname or IP address used in the source_url must be publicly accessible. If authentication information, such as username and password, is included in the source_url, it can only contain alphanumeric, period (.), underscore (_), and hyphen (-) characters. By default, Wowza Streaming Cloud uses TCP port 554 for RTSP streaming. If you don't use the default port, be sure to indicate that in the source URL.
    transcoder_type string Specify the default, transcoded. You can alternatively use passthrough, depending on your needs and the functionality available at your broadcast location.

    For a full list of transcoder parameters, see Transcoders in the Wowza Streaming Cloud API reference.

    Example request and response

        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_west_california",      
        "delivery_method": "push",      
        "name": "MyTranscoder",      
        "protocol": "rtsp",      
        "transcoder_type": "transcoded"
      } 
    }' "https://api.cloud.wowza.com/api/[version]/transcoders" 

    This request creates a transcoder with an id parameter, but no outputs or stream targets. The details of the transcoder's configuration are listed in the response, which should look something like this:

    { 
      "transcoder": { 
        "id": "tmd8ybp2", 
        "name": "MyTranscoder", 
        "transcoder_type": "transcoded", 
        "billing_mode": "pay_as_you_go", 
        "broadcast_location": "us_west_california", 
        ... 
        "protocol": "rtsp", 
        "delivery_method": "push", 
        "source_port": 1935, 
        "domain_name": "[wowzasubdomain].entrypoint.cloud.wowza.com", 
        "application_name": "app-ca51", 
        "stream_name": "b40618d9", 
        ...
        "disable_authentication": false, 
        "username": "user123", 
        "password": "abcPassword", 
        ...
        "outputs": []
      } 
    } 
  2. 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:
  3. Next, configure the source encoder. See Configure the source for next steps.

Configure the source


Make sure you have the latest firmware installed for your RTSP encoder. See the encoder's user guide for details about how to operate the device and how to specify settings such as resolution, bitrate, and frame rate.

Push delivery method

  1. For an RTSP encoder delivering a stream into Wowza Streaming Cloud over a push connection, use the source_connection_information details returned when you created the live stream to configure the source.

    Alternatively, use the domain_name, source_port, application_name, stream_name, username and password values returned when you created the transcoder.

  2. Refer to documentation for your specific encoder to note where to input the stream settings and user credentials for authentication.

    For example, Address or URL from a live stream might be:
    rtsp://[primary_server]:[host_port]/[application]

    Where [primary_server] is the ingest location of the server, [host_port] is the port (by default 1935), and [application] is the application name for the stream assigned by Wowza Streaming Cloud.

    And Address or URL from a transcoder might be:
    rtsp://[domain_name]:[source_port]/[application_name]

    Where [domain_name] is the ingest location of the server, [source_port] is the port (by default 1935), and [application_name] is the application name for the stream assigned by Wowza Streaming Cloud.

    While Stream or Stream key is the stream_name value, such as:
    b01bda67

Pull delivery method

For an RTSP encoder delivering a stream with a pull connection, you configure the source by determining and providing the source_url value when creating the live stream or transcoder. The source_url must be an RTSP URL with a publicly accessible hostname or IP address.

Note: Wowza Streaming Cloud accepts streams over RTSPS on port 443, if your camera or encoder can deliver over it.

Test the connection


  1. Start the live stream or transcoder using the Wowza Streaming Cloud REST API.

    Start the live stream:
    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]/start"
    Start the transcoder:
    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/start"
    Alternatively, click Start Live Stream at the top of the live stream detail page or Start Transcoder at the top of the transcoder detail page in the Wowza Streaming Cloud web manager.
  2. If you’re using the Wowza Streaming Cloud REST API to start the live stream or transcoder, fetch the state of the live stream or transcoder to make sure it’s started.

    Fetch the state of the live stream:
    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]"  "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]/state"
    Fetch the state of the transcoder:
    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]"  "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/state"
  3. Start the stream in the RTSP encoder.
  4. Confirm that the stream is playing.
    1. Fetch a video thumbnail of the stream using the Wowza Streaming Cloud REST API.

      Fetch the thumbnail URL of a live stream:
      curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/livestreams/[live_stream_id]/thumbnail_url"
      Fetch the thumbnail URL of a transcoder:
      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"
    2. View the thumbnail URL in a browser.
    3. Alternatively, in the Wowza Streaming Cloud web manager, confirm that the live stream or transcoder is playing by looking at the Video Thumbnail in the Overview tab of the live stream detail page or transcoder detail page.
  5. Use the Wowza Streaming Cloud REST API to stop the live stream or transcoder.

    Stop the live stream:
    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]/stop"
    Stop the transcoder:
    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/stop"
    Alternatively, click Stop Stream at the top of the live stream detail page in the Wowza Streaming Cloud web manager.
  6. Stop the stream in the source camera or encoder.

More Resources