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: 

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.

1. Create a live stream in Wowza Streaming Cloud


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.

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", 
   "encoder": "wowza_streaming_engine",
   "delivery_type": "single-bitrate",
   "transcoder_type": "transcoded", 
   "name": "Mylivestream"
 } 
}' "${WSC_HOST}/api/${WSC_VERSION}/live_streams"

Sample response

The response includes:

  • A connection code you’ll need to configure Wowza Streaming Engine to send the stream to Wowza Streaming Cloud.
     
{
    "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"
        ],
        "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://cdn3.wowza.com/1/OSt5VlYxM0FRbTNh/eU5WVVFu/hls/live/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"
    }
}

2. Create a live application in Wowza Streaming Engine


Next, use the Wowza Streaming Engine REST API to configure a live application to ingest a source stream (publisher).

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

  • Set publisherNamer to a descriptive name for the publisher.
  • 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

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/testlive/publishers/myRTMPencoder" 

Sample response

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

3. 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/testlive/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/testlive/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/testlive/actions/restart"

4. Create a stream target in Wowza Streaming Engine


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

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

  • Set connectionCode to the connection_code from the Wowza Streaming Cloud live stream
  • Set enabled to true
  • Set profile to wowza-streaming-cloud
  • Set sourceStreamName to the name of the incoming stream for the application
  • Set wowzaCloudDestinationType to transcoder
  • Set wowzaCloud.adaptiveStreaming to false

Sample request

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/testlive/pushpublish/mapentries/cloudLiveStream" 

Sample response

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

5. Test the connection


With the test 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 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"
  3. 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"
  4. Start the stream in the H.264 camera or encoder that's sending the stream to the testlive application in Wowza Streaming Engine.
  5. 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}/livestreams/[live_stream_id]/thumbnail_url"
  6. 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"
  7. Stop the stream in the source camera or encoder.

Related API requests