Send a stream from Wowza Streaming Engine to Wowza Streaming Cloud for transcoding using Wowza APIs or Wowza Streaming Engine Manager

With Wowza Streaming Engine™ media server software version 4.2 and later and the Wowza Streaming Cloud™ service, you can send single-bitrate streams from Wowza Streaming Engine to Wowza Streaming Cloud for adaptive-bitrate transcoding and delivery to viewers over the Wowza CDN edge network. This workflow allows you to use Wowza Streaming Cloud's high-performance servers and high-bandwidth networks for the heavy lifting of transcoding before delivering the stream to viewers.

In this article, learn how to set up a live application in Wowza Streaming Engine to send a stream to Wowza Streaming Cloud for transcoding. Use the Wowza Streaming Cloud REST API as well as the Wowza Streaming Engine REST API or the Wowza Streaming Engine Manager.

Note: Wowza Streaming Engine 4.7.4 has a known error that may break the stream target functionality for sending streams to Wowza Streaming Cloud for transcoding. We recommend updating to Wowza Streaming Engine 4.7.5 or later. For more information, see Wowza Streaming Engine 4.7.4 may experience problems sending streams to Wowza Streaming Cloud for transcoding.

Create a live stream in Wowza Streaming Cloud


  1. Create a live stream using the Wowza Streaming Cloud REST API that will receive the stream from Wowza Streaming Engine, transcode it, and deliver it to viewers using the Wowza CDN.

    Example request and response
     

     
    Notes: In Wowza Streaming Cloud REST API code examples:
    • 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.
    The following request creates a live stream that uses Wowza Streaming Engine as the source. Set the delivery_type to single-bitrate to send a single-bitrate stream to Wowza Streaming Cloud for transcoding. For information about available parameters, see the Wowza Streaming Cloud REST API reference documentation.
     
    curl -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" -H "Content-Type: application/json" -X POST -d '{   
      "live_stream": { 
       "aspect_ratio_height": 720,
       "aspect_ratio_width": 1280,
       "billing_mode": "pay_as_you_go", 
       "broadcast_location": "us_west_california", 
       "encoder": "wowza_streaming_engine",
       "delivery_type": "single-bitrate",
       "transcoder_type": "transcoded", 
       "name": "Mylivestream"
     } 
    }' "https://api.cloud.wowza.com/api/[version]/live_streams"
    The response includes information about the live stream, including the connection code, which you’ll need to configure Wowza Streaming Engine to send the stream to Wowza Streaming Cloud. The response should look something like this:
     
    {
        "live_stream": {
            "id": "abcrl8v5",
            "name": "Mylivestream",
            "transcoder_type": "transcoded",
            "billing_mode": "pay_as_you_go",
            "broadcast_location": "us_west_california",
            …
            "encoder": "wowza_streaming_engine",
            "delivery_method": "push",
            "delivery_type": "single-bitrate",
            "delivery_protocol": "hls-https",
            "target_delivery_protocol": "hls-https",
            "use_stream_source": false,
            "aspect_ratio_width": 1280,
            "aspect_ratio_height": 720,
            "connection_code": "0oUm9G",
            "connection_code_expires_at": "2018-09-01T17:47:58.000Z",
            "delivery_protocols": [
                "rtmp",
                "rtsp",
                "wowz",
                "hls"
            ],
            "player_id": "sfjy5pvk",
            "player_type": "original_html5",
            "player_responsive": false,
            "player_width": 640,
            "player_countdown": false,
            "player_embed_code": "in_progress",
            "player_hls_playback_url": "https://[wowzasubdomain]-i.akamaihd.net/hls/live/687320/983e9700/playlist.m3u8",
            "hosted_page": true,
            "hosted_page_title": "Mylivestream",
            "hosted_page_url": "in_progress",
            "hosted_page_sharing_icons": true,
            "stream_targets": [
                {
                    "id": "p63jrlqj"
                }
            ],
            "direct_playback_urls": {...},
            "created_at": "2018-08-31T17:47:58.000Z",
            "updated_at": "2018-08-31T17:47:59.000Z"
        }
    }

    Related requests

    View the details of a 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]/"

    Delete a live stream:

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

    Regenerate a target's connection code:

    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]/regenerate_connection_code"

Create a live application in Wowza Streaming Engine


Next, create a live application in Wowza Streaming Engine that will receive the live stream from an H.264 encoder or camera and send it to Wowza Streaming Cloud for distributed delivery.

You can do this through the Wowza Streaming Engine REST API workflow or the Wowza Streaming Engine Manager workflow.

Wowza Streaming Engine REST API live application workflow

Use the Wowza Streaming Engine REST API to configure the live application that ships with Wowza Streaming Engine to ingest a source stream (publisher).

Wowza Streaming Engine source stream (publisher) parameters

Parameter Data Type Description
publisherName String A descriptive name for the publisher, for example, MyRTMPencoder.

Example request and response

Note: Wowza Streaming Engine REST API requests must include three headers: Accept:application/json, Content-Type:application/json, and charset=utf-8. For more information, see Query the Wowza Streaming Engine REST API.

Create an RTMP source (publisher) for the live application on a local instance of Wowza Streaming Engine:

curl -X POST --header "Accept:application/json" --header "charset=utf-8" --header "Content-Type:application/json" "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/publishers/myRTMPencoder" -d '{
  "publisherName": "myRTMPencoder"
}'

The command creates the publisher and returns a response that looks something like this:

{
  "success": true,
  "message": "",
  "data": null
}

Wowza Streaming Engine Manager live application workflow

Create a live application in Wowza Streaming Engine that will receive the live stream from an H.264 encoder or camera and send it to Wowza Streaming Cloud for distributed delivery.

  1. Sign in to the Wowza Streaming Engine Manager, click the Applications tab at the top of the page, and then click live in the contents panel.
     
    Note: This article uses the live application that installs with Wowza Streaming Engine. If you want to use a different live application, select it instead from the contents panel.
  2. In the contents panel, click Sources (Live).
  3. Select the camera or encoder that you want to use as your video source, and complete the process of connecting the source to Wowza Streaming Engine. For more information, see Managing live source authentication settings.
     
    Note: By default, Wowza Streaming Engine requires RTMP and RTSP sources to provide a user name and password to connect to a live application. For information on how to turn off authentication, see Managing live source authentication settings.

Create a stream target in Wowza Streaming Engine


Next, create a stream target that will deliver the stream from Wowza Streaming Engine to Wowza Streaming Cloud for transcoding.

You can do this through the Wowza Streaming Engine REST API workflow or the Wowza Streaming Engine Manager workflow.

Wowza Streaming Engine REST API stream target workflow

Still in the Wowza Streaming Engine REST API, create a stream target for the live application.

Wowza Streaming Engine map entries parameters

Parameter Data Type Description
connectionCode String The six-character connection_code from the Wowza Streaming Cloud live stream, for example, 0oUm9G.
enabled Boolean Determines whether the stream target is enabled when it's created. Specify true so that the target is ready to run as soon as you create it. If you don't include this parameter, you’ll need a separate API request to enable the stream target.
entryName String A descriptive name for the map entry, for example, cloudLiveStream.
profile String A map entry in the PushPublishMap.txt map file that defines how the stream is sent to its destination and determines which additional configurable parameters are available. Specify wowza-streaming-cloud.
sourceStreamName String The name of the incoming stream for the live application, for example, myStream.
wowzaCloudDestinationType String Specify transcoder.
wowzaCloud.adaptiveStreaming Boolean Determines whether Wowza Streaming Engine sends a single bitrate stream or a group of stream renditions to Wowza Streaming Cloud. Specify false to send a single bitrate stream.

Example request and response

curl -X POST --header "Accept:application/json" --header "charset=utf-8" --header "Content-Type:application/json" "http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/pushpublish/mapentries/cloudLiveStream" -d '{
   "connectionCode": "0oUm9G ",
   "enabled": true,
   "entryName": "cloudLiveStream",
   "profile": "wowza-streaming-cloud",
   "sourceStreamName": "myStream",
   "wowzaCloud.adaptiveStreaming": "false",
   "extraOptions": {
    "wowzaCloudDestinationType": "transcoder",
    "destinationName": "wowzastreamingcloud"
  }
}'

The command creates the target (map entry) and returns a response that looks something like this:

{
  "success": true,
  "message": "Entry (cloudLiveStream) saved successfully",
  "data": null
}

Wowza Streaming Engine Manager stream target workflow

After the live application is created in Wowza Streaming Engine, it must be configured to send the stream to Wowza Streaming Cloud.

  1. In the contents panel, click Stream Targets and then click Add Stream Target.
  2. On the Add Stream Target page under Wowza Target Destinations, select Wowza Streaming Cloud.
  3. On the Wowza Streaming Cloud Configuration page, provide the following:
     
    • Stream Target Name - A descriptive name for this target setup in Wowza Streaming Engine. The name must be unique and can't contain less-than (<), greater-than (>), colon (:), quotation (' and "), forward slash (/), backslash (), pipe (|), question mark (?), asterisk (*), double-dot (..), or tilde (~) characters.
    • Connection Code - The six-digit code generated by Wowza Streaming Cloud that's available on the Overview tab of the live stream detail page in Wowza Streaming Cloud.
  4. After entering the Connection Code, click Check Code and then specify the following:
     
    • Source Stream Name - The name of the incoming stream that you specified in Wowza Streaming Engine when you set up the video source.
    • Start Wowza Streaming Cloud service automatically - If you want Wowza Streaming Engine to try to start the transcoder in Wowza Streaming Cloud immediately and publish the source stream, select the Start Wowza Streaming Cloud service automatically check box. If it isn't selected, you must start the transcoder manually in the web-based Wowza Streaming Cloud manager before the source stream is published.
  5. Click Add this target

Enable the Wowza Streaming Engine stream targets feature


Follow these steps for both the REST API and Wowza Streaming Manager workflows. For information about manual configuration of the Application.xml file to enable the stream targets feature, see Use CDNs and services to distribute live streams from Wowza Streaming Engine.

Before you stream, you must enable the Stream Targets feature for the Wowza Streaming Engine application and the stream target you created.

If you don't see a checkmark next to Stream Targets in the contents panel of the application, click Stream Targets in the contents panel and then click Enable Stream Targets. When prompted, click Restart Now so your change takes effect. When Stream Targets is enabled, a checkmark appears next to Stream Targets in the contents panel and the Stream Targets page shows Status is Enabled.

If the Status of an individual stream target is Disabled, click the Enable icon for the stream in the Actions column.

When a stream target is enabled, its status on the Stream Targets page is one of the following:

  • Starting. Wowza Streaming Engine is trying to start the transcoder in Wowza Streaming Cloud and publish the source stream.
  • Waiting. The target is enabled but is not yet pushing the stream to the Wowza Streaming Cloud destination because the target's configured source stream is not connected to the Wowza Streaming Engine input, Wowza Streaming Engine has not completed initialization of the connection to the Wowza Streaming Cloud destination, or the transcoder needs to be manually started in the web-based Wowza Streaming Cloud manager.
  • Active. The Wowza Streaming Cloud target configuration has been successfully retrieved and the stream is being pushed to the Wowza Streaming Cloud destination with the appropriate streaming protocol.
  • Error. Wowza Streaming Engine unsuccessfully tried to retrieve the Wowza Streaming Cloud target configuration and initiate streaming to the target destination. Errors might be due to an issue with the Wowza Streaming Cloud service, general connectivity issues, or an invalid target configuration such as an invalid Connection Code.

The status of each stream target updates automatically if your Wowza Streaming Engine application has fewer than 100 stream targets. If your application has more than 100 stream targets, you can click Refresh to update the status.

Test the connection


  1. Configure your source encoder or camera. See Connect a live source to Wowza Streaming Engine for more information.
  2. Start the live stream using the Wowza Streaming Cloud REST API. Alternatively, click Start Stream at the top of the live stream detail page in the Wowza Streaming Cloud web manager.

    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"
  3. If you’re using the Wowza Streaming Cloud REST API to start the live stream, fetch the state of the live stream 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"
  4. Start the stream in the H.264 camera or encoder that's sending the stream to the live application in Wowza Streaming Engine.
  5. In Wowza Streaming Engine Manager, verify that the stream is working by clicking Incoming Streams, and then clicking the stream name.

    The stream detail page displays the Status of the stream (Active) as well as details about connections, uptime, and throughput for the live stream.
  6. 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"
    2. View the thumbnail URL in a browser.
    3. Alternatively, in the Wowza Streaming Cloud web manager, confirm that the live stream is playing by looking at the Video Thumbnail in the Overview tab of the live stream detail page.
  7. Use the Wowza Streaming Cloud REST API to stop the live stream. Alternatively, click Stop Stream at the top of the live stream detail page in the Wowza Streaming Cloud web manager.

    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"
  8. Stop the stream in the source camera or encoder.