Send a stream from Wowza Streaming Engine to an ultra low latency stream target in Wowza Streaming Cloud using Wowza APIs

With Wowza Streaming Engine™ media server software version 4.2 and later and a Wowza Streaming Cloud™ with Ultra Low Latency subscription, you can use the Stream Targets feature in Wowza Streaming Engine to send a single stream to an ultra low latency target in Wowza Streaming Cloud. This allows you to use an existing Wowza Streaming Engine configuration to deliver an ultra low latency stream to viewers through Wowza Streaming Cloud.

This article explains how to use the Wowza Streaming Cloud REST API and the Wowza Streaming Engine REST API to send a live stream from Wowza Streaming Engine to a Wowza Streaming Cloud ultra low latency stream target for delivery to viewers. It also points to information about configuring playback with Wowza Player for Ultra Low Latency and information on playback with a mobile app created with Wowza GoCoder SDK.

Note: For instructions on executing this workflow using the Wowza Streaming Engine Manager and the Wowza Streaming Cloud web manager intead of Wowza REST APIs, see Send a stream from Wowza Streaming Engine to an ultra low latency stream target in Wowza Streaming Cloud.

Video tutorial: Sending a stream from Wowza Streaming Engine to an ultra low latency stream target in Wowza Streaming Cloud


Create an ultra low latency stream target in Wowza Streaming Cloud


If you don't have an ultra low latency stream target already created, start by creating one using the Wowza Streaming Cloud REST API. See Create an ultra low latency stream target for detailed information about available parameters.

Notes:
  • To authenticate API requests, use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
  • The curl examples below use environment variables. See Using cURL for more information on how to set these up.
  • Ultra low latency stream targets are not available in the sandbox environment, so be sure to use https://api.cloud.wowza.com not https://api-sandbox.cloud.wowza.com when setting up environment variables for your API request.

Example request and response

Create an ultra low latency stream target:

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_ull": { 
    "name": "My Ultra Low Latency Push Target from Wowza Streaming Engine", 
    "source_delivery_method": "push", 
    "enable_hls": true 
  } 
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/ull" 

The request creates an ultra low latency stream target with an id parameter, ingest connection details, and playback details. You will need the primary_url from this response to configure Wowza Streaming Engine to send the stream. The response should look something like this:

{ 
    "stream_target_ull": { 
      "id": "abcx2y5v",  
      "name": "My Ultra Low Latency Push Target from Wowza Streaming Engine", 
      "provider": "wowza", 
      "enabled": true, 
      "state": "stopped", 
      "stream_name": "0I0p2SU9SanfhCaxBz3MWKdZUbmq592a", 
      "primary_url": "rtmp://origin.cdn.wowza.com:1935/live/0I0p2SU9SanfhCaxBz3MWKdZUbmq592a", 
      "source_delivery_method": "push", 
      "playback_urls": { 
        "ws": [
            "ws://edge.cdn.wowza.com/live/_definst_/0P0p2SU9SanNzZGZmWVQvc2RTRGR5844/stream.ws",
            "wss://edge.cdn.wowza.com/live/_definst_/0P0p2SU9SanNzZGZmWVQvc2RTRGR5844/stream.ws"
        ], 
        "wowz": [
            "wowz://edge.cdn.wowza.com/live/_definst_/0P0p2SU9SanNzZGZmWVQvc2RTRGR5844",
            "wowzs://edge.cdn.wowza.com/live/_definst_/0P0p2SU9SanNzZGZmWVQvc2RTRGR5844" 
         ], 
        "hls": [
            "https://[wowzasubdomain]/hls/live/687317/0P0p2SU9SanNzZGZmWVQvc2RTRGR5844/playlist.m3u8"
         ] 
      }, 
      "enable_hls": true, 
      "connection_code": "2abXlJ", 
      "connection_code_expires_at": "2018-07-31T19:17:05.000Z", 
      "created_at": "2018-07-27T19:20:58.000Z", 
      "updated_at": "2018-07-30T19:17:05.000Z", 
   } 
} 

Tip:  If you have already created an ultra low latency stream target, you can view source configuration details using a GET query.  
curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
"${WSC_HOST}/api/${WSC_VERSION}/stream_targets/ull/[ull_stream_target_id]"

Configure a live application in Wowza Streaming Engine


Next, using the Wowza Streaming Engine REST API, configure the live application that ships with Wowza Streaming Engine to ingest a source stream (publisher) that will receive the live stream from an H.264 encoder or camera.

Wowza Streaming Engine stream source (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
}

Related requests

Get a list of applications:

curl -X GET \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \ 
"http://localhost:8087/v2/servers/[serverName]/vhosts/[vhostName]/applications"

View the details of an application:

curl -X GET \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \ 
"http://localhost:8087/v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]"

View a list of stream sources (publishers) connected to an application:

curl -X GET \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \ 
"http://localhost:8087/v2/servers/[serverName]/vhosts/[vhostName]/applications/[appName]/publishers"

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


Next, use the Wowza Streaming Engine REST API to create a stream target for the live application in Wowza Streaming Engine that will deliver the stream from Wowza Streaming Engine to the Wowza Streaming Cloud ultra low latency stream target over RTMP.

You will need the ultra low latency stream target’s primary_url to determine the configuration values. For the following example configuration, we'll use the primary_url from the example POST response above:

rtmp://origin.cdn.wowza.com:1935/live/0I0p2SU9SanfhCaxBz3MWKdZUbmq592a

Wowza Streaming Engine map entries parameters

Parameter Data Type Description
application String The Wowza Streaming Engine application name. For example, live.
enabled Boolean 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, wowza_streaming_cloud_ull_target.
host String The host URL of the origin ingest location for the ultra low latency stream. This is the destination entry point that the stream is sent to. It's part of the primary_url in the POST response. For example,  origin.cdn.wowza.com.
 
Note: If you want to ingest the stream into a different origin location than the one Wowza Streaming Cloud assigns to you automatically, see Override the origin or edge server location used by an ultra low latency stream target with the Wowza Streaming Cloud REST API to determine the Destination Host value.
port Integer The port number from the primary_url in the POST response. Specify 1935.
profile String Specify rtmp.
sourceStreamName String The name of the incoming stream for the live application, for example, myStream.
streamName String The destination stream name. It's the stream_name value or the final part of the primary_url in the POST response. For example: 0I0p2SU9SanfhCaxBz3MWKdZUbmq592a

Example request and response

curl -X POST \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \ 
-d '{
   "application": "live",
   "enabled": true,
   "entryName": "wowza_streaming_cloud_ull_target",
   "host": "origin.cdn.wowza.com",
   "port": 1935,
   "profile": "rtmp",
   "streamName": "0I0p2SU9SanfhCaxBz3MWKdZUbmq592a",
   "sourceStreamName": "myStream"
}' \ 
"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/pushpublish/mapentries/wowza_streaming_cloud_ull_target" 

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

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

Related request

Enable a single stream target (push publishing map entry):

curl -X PUT \
-H "Accept:application/json" \
-H "charset=utf-8" \
-H "Content-Type:application/json" \ 
"http://localhost:8087/v2/servers/[server_name]/vhosts/[vhostName]/applications/[appname]/pushpublish/mapentries/[entryname]/actions/enable"

Test the ultra low latency stream


  1. Start the stream in the H.264 camera or encoder that's sending the stream to the live application in Wowza Streaming Engine.

    The live application ingests the live stream and sends it to the Wowza Streaming Cloud ultra low latency stream target.
  2. In Wowza Streaming Engine Manager, verify that the stream is published by clicking Incoming Streams for the live application, 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 published stream.
  3. Configure playback:
  4. Stop the stream in the source camera or encoder to end your test stream.