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

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 use the Wowza Streaming Cloud REST API and the Wowza Streaming Engine REST API to set up a live application in Wowza Streaming Engine to send a stream to Wowza Streaming Cloud for transcoding.

Notes:

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:
    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 -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", 
       "encoder": "wowza_streaming_engine",
       "delivery_type": "single-bitrate",
       "transcoder_type": "transcoded", 
       "name": "Mylivestream"
     } 
    }' "${WSC_HOST}/api/${WSC_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",
            "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 \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/"

    Delete a live stream:

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

    Regenerate a target's connection code:

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

Create a live application in Wowza Streaming Engine


Next, 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 
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \ 
-d '{
  "publisherName": "myRTMPencoder"
}' \
"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/publishers/myRTMPencoder" 

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

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

Enable push publishing in the Wowza Streaming Engine REST API


Before you can create or use stream targets with the Wowza Streaming Engine REST API, you must enable the push publishing module. To do so, you need to add an advanced property to the application's configuration and add the push publish module to the application.

Start by retrieving the details of the application's advanced settings and a list of the modules the application is using. Retrieve the information by sending a GET call to the endpoint /v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]/adv.

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.

Example request:

curl -X GET \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/adv"

The request returns an object (advancedSettings) that shows the application's advanced settings and a modules list of the modules in use. The response looks something like this:

{
  "version": "1543353224014",
  "serverName": "_defaultServer_",
  "advancedSettings": [
    {
      "enabled": false,
      "canRemove": true,
      "name": "debugAACTimecodes",
      "value": "false",
      "defaultValue": "false",
      "type": "Boolean",
      "sectionName": "cupertinostreamingpacketizer",
      "section": "/Root/Application/LiveStreamPacketizer",
      "documented": true
    },
    {
      "enabled": false,
      "canRemove": true,
      "name": "debugMP3Timecodes",
      "value": "false",
      "defaultValue": "false",
      "type": "Boolean",
      "sectionName": "cupertinostreamingpacketizer",
      "section": "/Root/Application/LiveStreamPacketizer",
      "documented": true
    },
    ...
  ],
  "modules": [
    {
      "order": 0,
      "name": "base",
      "description": "Base",
      "class": "com.wowza.wms.module.ModuleCore"
    },
    {
      "order": 1,
      "name": "logging",
      "description": "Client Logging",
      "class": "com.wowza.wms.module.ModuleClientLogging"
    },
    {
      "order": 2,
      "name": "flvplayback",
      "description": "FLVPlayback",
      "class": "com.wowza.wms.module.ModuleFLVPlayback"
    },
    {
      "order": 3,
      "name": "ModuleCoreSecurity",
      "description": "Core Security Module for Applications",
      "class": "com.wowza.wms.security.ModuleCoreSecurity"
    },
  ]
}

Now, execute a PUT command to accomplish two tasks:

  1. Add the pushPublishMapPath property to the application's configuration and
  2. Append the ModulePushPublish to the complete list of modules in use.

Note: The PUT command must include all of the existing modules in use by the application as well as the push publish module; use the response from the GET call to enumerate the modules that precede ModulePushPublish in the PUT call.

The command calls the same endpoint, /v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]/adv, and looks like this:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \ 
"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/adv"
{
  "version": "1543353224014",
  "serverName": "_defaultServer_",
  "advancedSettings": [
    {
      "enabled": true,
      "canRemove": false,
      "name": "pushPublishMapPath",
      "value": "${com.wowza.wms.context.VHostConfigHome}/conf/${com.wowza.wms.context.Application}/PushPublishMap.txt",
      "defaultValue": null,
      "type": "String",
      "sectionName": "Application",
      "section": "/Root/Application",
      "documented": false
    }
  ],
  "modules": [
    {
      "order": 0,
      "name": "base",
      "description": "Base",
      "class": "com.wowza.wms.module.ModuleCore"
    },
    {
      "order": 1,
      "name": "logging",
      "description": "Client Logging",
      "class": "com.wowza.wms.module.ModuleClientLogging"
    },
    {
      "order": 2,
      "name": "flvplayback",
      "description": "FLVPlayback",
      "class": "com.wowza.wms.module.ModuleFLVPlayback"
    },
    {
      "order": 3,
      "name": "ModuleCoreSecurity",
      "description": "Core Security Module for Applications",
      "class": "com.wowza.wms.security.ModuleCoreSecurity"
    },
    {
      "order": 4,
      "name": "ModulePushPublish",
      "description": "ModulePushPublish",
      "class": "com.wowza.wms.pushpublish.module.ModulePushPublish"
    }
  ]
}

Finally, restart the application, and then you can create and edit stream targets using the Wowza Streaming Engine REST API.

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \ 
"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/actions/restart"

Create a stream target in Wowza Streaming Engine


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

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
}

Test the connection


With the live application in Wowza Streaming Engine configured to ingest source stream and deliver it to Wowza Streaming Cloud, you're ready to test your workflow.

  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:
     
    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"
  3. Fetch the state of the live stream to make sure it’s started:
     
    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"
  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. Confirm that the stream is playing.
    1. Fetch a video thumbnail of the stream using the Wowza Streaming Cloud REST API:
       
      curl -X GET \
      -H "wsc-api-key: ${WSC_API_KEY}" \
      -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
      "${WSC_HOST}/api/${WSC_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.
  6. 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 \
    -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"
  7. Stop the stream in the source camera or encoder.