How to deliver a low-latency stream by using the Wowza Streaming Cloud REST API

The Wowza Streaming Cloud™ service allows you to deliver live streams to viewers over three protocols: RTMP and RTSP directly from the transcoder, and Apple HLS from a CDN endpoint. If latency is your primary concern, direct RTMP and RTSP playback is the faster option, but the number of concurrent viewers who can watch your stream this way is limited. Apple HLS delivery from a CDN endpoint, on the other hand, allows you to reach more viewers--and more geographically dispersed viewers--but the latency is greater.

This article explains how to use the Wowza Streaming Cloud REST API to deliver output using a hybrid RTMP-HLS workflow to achieve the lowest possible latency and the most scalable deployment. The delivery methods used in this article provide an example. You can choose to just use one, or customize the destinations and settings in whatever way makes sense for your streaming needs.

Contents


About latency over RTMP and Apple HLS
Create a low-latency transcoder and passthrough output for direct RTMP playback
Add a Wowza CDN - HLS stream target
Reduce the chunk size of the HLS stream target
Assign the HLS target to the output
Get the playback URLs
More resources

About latency over RTMP and Apple HLS


The lowest latency workflow is to deliver a stream directly from the Wowza Streaming Cloud transcoder (the origin server) to your audience over RTMP or RTSP playback URLs. Under optimal conditions--the viewer is close to your broadcast location, network conditions are good, and your source encoding settings are optimal--delivering a stream directly from the Wowza Streaming Cloud transcoder to viewers offers latency as low as 1 second. The advantage of such extremely low latency, however, may be offset by the facts that the transcoder is limited to 100 maximum connections and latency increases the farther the viewer is located from the transcoder.

The second option for low-latency stream delivery is to use a Wowza CDN - HLS stream target that parses the stream into small chunks, or short segments. By reducing the Apple HLS chunk size from the default 10 seconds to 2 seconds, you can achieve a latency of as low as 5 seconds. Apple HLS targets in Wowza Streaming Cloud have no restrictions on the number of viewers who can access the stream and they are widely distributed, with servers that are close to viewers wherever they watch. And because Apple HLS is based on HTTP, it performs well on all kinds of networks.

Create a low-latency transcoder and a passthrough output for direct RTMP playback


Start by using the Wowza Streaming Cloud REST API to create a transcoder that receives video from a source encoder and delivers a passthrough stream to your targets. Use the following transcoder parameters for your low-latency workflow.

Low-latency transcoder parameters

Parameter Data Type Description
broadcast_location string Specify a location as close as possible to your video source, for example, eu_belgium.
 
Note: 4K streaming (3840x2160 aspect ratio) is not supported at asia_pacific_taiwan, eu_belgium, us_central_iowa, or us_east_s_carolina.
buffer_size integer Specify 0.
low_latency Boolean Speeds the time it takes to decode and deliver video data to the player by turning off the sort packet buffer. Specify true.
play_maximum_connections integer The number of connections that can access the transcoder's RTMP playback URL. Use the maximum value, 100.
stream_smoother Boolean Use the default, false. (Stream smoothing is not available when the buffer is 0.)
transcoder_type string Specify passthrough.
 
Note: For information on other transcoder parameters, see the Wowza Streaming Cloud REST API Reference Documentation.

Example request and response

Note: In all 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.
Create the transcoder:
 
curl --header  'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "eu_belgium",
     "buffer_size": 0,
     "delivery_method": "push",
     "low_latency": true,
     "name": "MyLowLatencyTranscoder",
     "play_maximum_connections": 100,
     "protocol": "rtmp",
     "stream_smoother": false,
     "transcoder_type": "passthrough"
   }
}' "https://api.cloud.wowza.com/api/v1/transcoders/"
The command creates a passthrough transcoder with an id parameter (1234abcd in this example) but no outputs ("outputs": []). The details of the configured transcoder are listed in the response, which should look something like this:
 
{
  "transcoder": {
    "application_name": "app-1234",
    "billing_mode": "pay_as_you_go",
    "broadcast_location": "eu_belgium",
    "buffer_size": 0,
    "closed_caption_type": none,
    "created_at": "2016-04-22T13:33:16.575",
    "delivery_method": "push",
    "delivery_protocols": [
	"rtmp",
	"rtsp",
	"wowz"
    ],
    "direct_playback_urls": [],
    "disable_authentication": false,
    "domain_name": "1234567.entrypoint.cloud.wowza.com",
    "id": "1234abcd",
    "idle_timeout": 1200,
    "low_latency": true,
    "name": "MyLowLatencyTranscoder",
    "outputs": [],
    "password": "12345678",
    "play_maximum_connections": 100,
    "protocol": "rtmp",
    "recording": false,
    "source_port": 1935,
    "stream_name": "1a2a3a4a",
    "stream_smoother": false,
    "suppress_stream_target_start": false,
    "transcoder_type": "passthrough",
    "updated_at": "2016-04-22T13:33:16.575",
    "username": "client1",
    "video_fallback": false,
    "watermark": false
   }
}
Create the passthrough output:
 
Note: For more information on passthrough output parameters, see Create an output for the transcoder.
curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "output": {
     "passthrough_audio": true,
     "passthrough_video": true,
     "stream_format": "audiovideo"
   }
}' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_ID]/outputs"
The command creates the output with an id parameter (5678efgh in this example) but no targets ("targets": []). The details of the configured output are listed in the response, which should look something like this:
 
{
   "output": {
     "bitrate_audio": 0,
     "bitrate_video": 0,
     "created_at": "2016-04-28T11:01:26.044",
     "framerate_reduction": 0,
     "h264_profile": null,
     "id": "5678efgh",
     "keyframes": "follow_source",
     "name": "Video+Audio=Passthrough+Passthrough",
     "passthrough_audio": true,
     "passthrough_video": true,
     "stream_format": "audiovideo",
     "targets": [],
     "transcoder_id": "1234abcd",
     "updated_at": "2016-04-28T11:01:26.044"
   }
}

Add a Wowza CDN - HLS stream target


Next, add a Wowza CDN stream target that delivers the stream to geographically distributed endpoints over Apple HLS.

Wowza CDN - HLS stream target parameters

Parameter Data Type Description
name string A descriptive name for the stream target such as MyLowLatencyHLStarget.
provider string Specify akamai_cupertino.
type string Specify WowzaStreamTarget for a Wowza CDN destination.
use_cors Boolean (Optional) CORS, or cross-origin resource sharing, allows streams to be sent to providers such as Peer5, Viblast, and Streamroot, which implement a peer-to-peer grid delivery system. Specify true to enable CORS. The default is false.
use_https Boolean (Optional) Specify true to deliver the HLS stream from the target to viewers over SSL. The default is false.
use_secure_ingest Boolean (Optional) Specify true to deliver the HLS stream securely between the transcoder and the target. The default is false.

Example request and response

Create the target:
 
curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
   "stream_target": {
     "name": "MyLowLatencyHLStarget",
     "provider": "akamai_cupertino",
     "type": "WowzaStreamTarget"
   }
}' "https://api.cloud.wowza.com/api/v1/stream_targets/"
The command creates the target with an id parameter (3456mnop in this example). The details of the configured target are listed in the response, which should look something like this:
 
{
   "stream_target": {
     "chunk_size": "10,"
     "created_at": "2016-04-28T11:01:45.044",
     "hls_playback_url": "http://[wowzasubdomain]-i.akamaihd.net/hls/live/123456/29e0a1/playlist.m3u8",
     "id": "3456mnop",
     "name": "MyLowLatencyHLStarget",
     "primary_url": "rtmp://entrypoint.server.net/EntryPoint",
     "provider": "akamai_cupertino",
     "stream_name": "6f86005b",
     "type": "WowzaStreamTarget",
     "updated_at": "2016-04-28T11:01:45.044",
     "use_cors": false,
     "use_https": false,
     "use_secure_ingest": false
   }
}

Reduce the chunk size of the HLS stream target


Reduce the duration of the stream's HLS segments by specifying a low chunk size property for the target:
 
curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": "2"
  }
}' "https://api.cloud.wowza.com/api/v1/stream_targets/[stream_target_ID]/properties/"
The command assigns a chunk size of 2 to the target (3456mnop in this example). The details of the target's property are listed in the response, which should look something like this:
 
{
   "property": {
     "key": "chunkSize",
     "section": "hls",
     "value": "2"
   }
}

Assign the HLS stream target to the output


Assign the Apple HLS target to the output:
 
curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
   "output_stream_targets": {
     "stream_target_id": "3456mnop",
     "use_stream_target_backup_url": false
   }
}' "https://api.cloud.wowza.com/api/v1/transcoders/[transcoder_ID]/outputs/[output_ID]/output_stream_targets/"

Get the stream target's playback URLs


Get the Apple HLS and RTMP playback URLs:
 
curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' https://api.cloud.wowza.com/api/v1/stream_targets/[stream_target_ID]/

More resources



Originally Published: 07-20-2016.
Updated: 01-16-2017
 

If you're having problems or want to discuss this article, post in our forum.