Send a stream from Wowza Streaming Engine to a Wowza CDN HLS target using Wowza REST APIs

Wowza Streaming Engine™ media server software can broadcast a live stream to a target in the Wowza Streaming Cloud™ service. This workflow allows you to bypass transcoding in Wowza Streaming Cloud and just use the Wowza Streaming Cloud edge network to deliver the stream to viewers.

You can achieve this workflow programmatically: First, use the Wowza Streaming Cloud REST API to create the HLS target to deliver the final stream to viewers. Then, use the Wowza Streaming Engine REST API to configure a live application to send a single- or multi-bitrate stream to the Wowza Streaming Cloud HLS target.

Note: This workflow requires Wowza Streaming Engine 4.5 or later and a Wowza Streaming Cloud or Wowza CDN subscription.

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.

Create the HLS stream target in Wowza Streaming Cloud


Using the Wowza Streaming Cloud REST API, create a Wowza CDN on Akamai stream target that receives the stream from Wowza Streaming Engine and delivers it to viewers using geographically distributed endpoints over HLS.

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

  • Set provider to akami_cupertino.
  • 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 '{
   "stream_target_akamai": {
     "name": "MyCloudHLStarget",
     "provider": "akamai_cupertino"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/akamai"

Sample response

{
  "stream_target_akamai": {
    "id": "1234hjkl",
    "name": "MyCloudHLStarget",
    "provider": "akamai_cupertino",
    "use_secure_ingest": false,
    "use_cors": false,
    "stream_name": "46d95e9d",
    "primary_url": "http://post.[domain]-i.akamaihd.net/253398/46d95e9d",
    "delivery_protocols": [
        "hls"
    ],
    "playback_urls": {
        "hls": [
            {
                "name": "default",
                "url": "https://[domain]-i.akamaihd.net/hls/live/253398/46d95e9d/playlist.m3u8"
            }
        ]
    },  
    "connection_code": "1effa1",
    "connection_code_expires_at": "2017-05-16T21:44:49.000Z",
    ...
  }
}

Create the stream source for a live application in Wowza Streaming Engine


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

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.

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
}

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"

Create the stream target for a live application in Wowza Streaming Engine


Still in the Wowza Streaming Engine REST API, create a stream target for the testlive application. The target will deliver the stream from Wowza Streaming Engine to the Wowza Streaming Cloud HLS target over HLS.

You can use the following sample request, making sure to:
  • Set connectionCode to the six-character connection_code from the Wowza Streaming Cloud HLS target, for example 1effa1.
  • Set profile to wowza-streaming-cloud.
  • Set sourceStreamName to the name of the incoming stream for the application, for example, myStream.
  • Set wowzaCloud.adaptiveStreaming to false to send a single bitrate stream or true to send an adaptive bitrate stream as a group of stream renditions.
  • 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 '{
   "connectionCode": "1effa1",
   "enabled": true,
   "entryName": "cloudHLStarget",
   "profile": "wowza-streaming-cloud",
   "sourceStreamName": "myStream",
   "wowzaCloud.adaptiveStreaming": "false",
   "extraOptions": {
    "wowzaCloudDestinationType": "streamTarget",
    "destinationName": "wowzastreamingcloud"
  }
}'
"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/testlive/pushpublish/mapentries/cloudHLStarget" 

Sample response

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

Start streaming


Make sure your source is configured and connected to Wowza Streaming Engine (see Connect a live source to Wowza Streaming Engine). Then, start the source encoder or camera.

Related API requests

  • GET /stream_targets/akamai/[stream_target_id] — View the details of a stream target, including its HLS playback URL.
  • DELETE /stream_targets/akamai/[stream_target_id] — Delete a stream target.
  • PUT  /stream_targets/akamai/[stream_target_id]/regenerate_connection_code — Regenerate a target's connection code.
  • GET /v2/servers/[serverName]/vhosts/[vhostName]/applications — Get a list of applications.
  • GET /v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName] — View the details of an application.
  • GET /v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]/publishers — View a list of source streams (publishers) connected to an application.
  • GET /v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]/pushpublish/mapentries — View a list of stream targets (push publishing map entries):
  • GET /v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]/pushpublish/mapentries/[entryName] — View the details of a target (push publishing map entry) for an application on a local instance of Wowza Streaming Engine.
  • DELETE /v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]/pushpublish/mapentries/[entryName] — Delete a stream target (push publishing map entry).
  • PUT /v2/servers/[server_name]/vhosts/[vhostName]/applications/[appname]/pushpublish/mapentries/[entryname]/actions/enable — Enable a single stream target (push publishing map entry).