Wowza Streaming Cloud ultra low latency REST API quick start guide

Learn how to use the Wowza Streaming Cloud™ service's REST API to send an encoded live stream from the Wowza GoCoderTM app or GoCoder SDK to an ultra low latency stream target for browser-based playback with Wowza Player.

Note: The Wowza ultra low latency REST API is in private preview release. For information see Ultra Low Latency with Wowza.

Contents


Video tutorial: How to set up an low latency stream
About ultra low latency stream targets
Create an ultra low latency stream target
Configure the source
Configure playback
Start streaming
View ultra low latency stream analytics, usage, and viewer data
View ultra low latency target details, usage, and viewer data in Wowza Streaming Cloud
More resources

Video tutorial: How to set up an ultra low latency stream


Tip: See our Wowza ultra low latency playlist on YouTube for more video tutorials about using the Wowza ultra low latency REST API.

About ultra low latency stream targets


Wowza Streaming Cloud offers a stream target that combines a scalable live streaming infrastructure with high availability and ultra low latency. Available through the Wowza Streaming Cloud REST API and currently in preview release, the target allows you to broadcast live streams with end-to-end latency of under three seconds.

Using the Wowza Streaming Cloud REST API, you can send a single bitrate live stream from any H.264 IP camera or encoder to geographically distributed cloud-based servers over RTMP or RTSP. The servers then deliver the stream to players that support WebSocket-based playback URLs. Usage endpoints in the API allow you to analyze stream target connection metrics and to see the details of who watched your stream and where.

The ultra low latency API preview supports:

  • Any H.264 encoder or camera, including the Wowza GoCoder app and the Wowza GoCoder SDK
  • AAC audio
  • Playback using Wowza Player

Limitations of the API preview include:

  • No adaptive bitrate streaming
  • Servers in North America and Europe, but not on other continents

For information on the API's structure, endpoints, and query requirements, see the Wowza Streaming Cloud REST API reference documentation.

Create an ultra low latency stream target


Start by creating an ultra low latency stream target.

Wowza ultra low latency stream target parameters

Parameter Data Type Description
enable_hls Boolean If true, creates an Apple HLS playback URL that can be used to view the stream on iOS devices. The default is false.
enabled Boolean If true (the default), allows the source stream to be ingested by the target's origin server.
ingest_ip_whitelist string Optional, if the source delivery method is push. A list of IP addresses for the stream source. Only whitelisted IP addresses can connect to the target's origin server. Wildcard (*) characters are supported.
name string The name of the stream target. Enter a descriptive alphanumeric string that is under 200 characters.
region_override string Optional, if the source delivery method is pull. The location of the stream target's origin server. Valid values are us-west1, us-east2, and ie-central1. If you don't specify a region, the service determines the optimal location.
source_delivery_method string The method being used to deliver the source stream to the origin server. Valid values are pull, which instructs the stream target to pull the stream from the source, or push, which instructs the source to push the stream to the target.
source_url string Required when the source delivery method is pull. The URL of a source IP camera or encoder. Consult the camera or encoder documentation for the URL syntax.
type string Specify UltraLowLatencyStreamTarget.

Example requests and responses

Notes:

  • For [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
  • For [version], substitute the version number of the API that you're using. For the current version, use v1.1.

Create an ultra low latency stream target for a push stream:

curl -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" -H "Content-Type: application/json" -X POST -d '{
    "stream_target": {
	"type": "UltraLowLatencyStreamTarget",
	"name": "My Ultra Low Latency Push Target",
	"source_delivery_method": "push",
	"enabled": true
    }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/"

The command creates a stream target with an id parameter, ingest connection details, and playback details, including a hash of playback URLs. The details of the stream target's configuration are provided in the response, which should look something like this:

{
    "stream_target": {
        "id": "cetkpl5i",
        "type": "UltraLowLatencyStreamTarget",
        "name": "My Ultra Low Latency Push Target",
        "provider": "wowza",
        "enabled": true,
        "stream_name": "0I0q1NXZhMnvjUVWWHaW3SM8LfhN5d03",
        "primary_url": "rtmp://origin.wowza.com:1935/live/0I0q1NXZhMnvjUVWWHaW3SM8LfhN5d03",
        "source_delivery_method": "push",
        "playback_urls": {
           "ws": [
               "ws://[edge-subdomain].cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160/stream.ws",
               "wss://[edge-subdomain].cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160/stream.ws"
            ],
            "wowz": [
               "wowz://[edge-subdomain].cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160",
               "wowzs://[edge-subdomain].cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160"
            ]
        },
        "connection_code": "295903",
        "connection_code_expires_at": "2017-10-26T20:46:20.000Z",
        "enable_hls": false,
        "created_at": "2017-10-25T20:46:20.000Z",
        "updated_at": "2017-10-25T20:46:20.000Z",
        "links": [...]
    }
}

Create an ultra low latency stream target for a pull stream from an RTSP encoder:

curl -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" -H "Content-Type: application/json" -X POST -d '{
    "stream_target": {
	"type": "UltraLowLatencyStreamTarget",
	"name": "My Ultra Low Latency Pull Target",
	"source_delivery_method": "pull",
	"enabled": true,
	"source_url": "rtsp://example.com/video"
    }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/"

The details of the new stream target are provided in the response, which should look something like this:

{
    "stream_target": {
        "id": "vpxfks4v",
        "type": "UltraLowLatencyStreamTarget",
        "name": "My Ultra Low Latency Pull Target",
        "provider": "wowza",
        "enabled": true,
        "source_delivery_method": "pull",
        "source_url": "rtsp://sample.com/video",
        "playback_urls": {
           "ws": [
               "ws://[edge-subdomain].cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160/stream.ws",
               "wss://[edge-subdomain].cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160/stream.ws"
            ],
            "wowz": [
               "wowz://[edge-subdomain].cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160",
               "wowzs://[edge-subdomain].cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160"
            ]
        },
        "enable_hls": false,
        "created_at": "2017-10-19T18:47:35.000Z",
        "updated_at": "2017-10-19T18:47:35.000Z",
        "links": [...]
    }
}

Related requests

View all stream targets:

curl -X GET -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets"

View the details of a stream target:

curl -X GET -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]"

Update a stream target's configuration:

Note: The enable_hls, region_override, and source_delivery_method parameters can't be updated.

curl -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" -H "Content-Type: application/json" -X POST -d '{
	"stream_target": {
		"name": "My Awesome Ultra Low Latency Pull Stream Target",
		"type": "UltraLowLatencyStreamTarget"
	}
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]"

Delete a stream target:

curl -X DELETE -H "wsc-api-key: [key]" -H " wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]"

Configure the source


Use the details of the ultra low latency stream target you created to configure a source, such as the Wowza GoCoder encoding app or the Wowza GoCoder SDK, to send a live stream to the Wowza Streaming Cloud ultra low latency stream target. Connect Wowza GoCoder to the ultra low latency target by using the source information returned from the API. For more information, see How to configure Wowza GoCoder to stream to an ultra low latency stream target.

Configure playback


Use the GoCoder SDK to develop an app with playback functionality. For more information, see How to play an ultra low latency live stream with Wowza GoCoder SDK for iOS or How to play an ultra low latency live stream with Wowza GoCoder SDK for Android.

Alternatively, you can also use Wowza Ultra Low Latency Test Player Builder to preview the stream and to get the embed code so that viewers can watch the stream from your webpage. For more information, see How to configure Wowza Ultra Low Latency Test Player to play ultra low latency streams.

Note: The Wowza Ultra Low Latency Test Player Builder can only be used with the latest version of the Google Chrome browser. Other browsers may not work.

Start streaming


  • Push source delivery method: Start sending video from Wowza GoCoder, and the live steam starts.
  • Pull source delivery method: When someone requests the stream by accessing the playback URL, the ultra low latency target will ingest the stream and it will start playing. After about a minute of no requests, Wowza Streaming Cloud stops ingesting the stream.

View ultra low latency stream analytics, usage, and viewer data


Stream metrics, usage, and viewer data endpoints allow you to view data that will help you understand how your stream was processed and viewed.

Stream metrics show connection data for the stream target's origin server, including the average inbound bitrate of the stream and the number of dropped connections.

Usage data shows the amount of bandwidth used and billed by a target.

Viewer data includes the locations where the ultra low latency stream was requested and how many requests were made to the edge server.

Example requests

Get connection metrics for an ultra low latency stream target for the most recent 10 minutes that it ran:

curl -X GET -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/metrics/historic"

Get viewer data for an ultra low latency for the current billing period:

curl -X GET -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/usage/viewer_data/stream_targets/[stream_target_id]"

Get a snapshot of connection and processing metrics for an active ultra low latency stream target:

curl -X GET -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/metrics/current"

Get network usage (bandwidth) used and billed for all stream targets:

Note: The network usage query returns bandwidth for all targets in the account, not just ultra low latency stream targets.

curl -X GET -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/usage/network/stream_targets/"

View ultra low latency target details, usage, and viewer data in Wowza Streaming Cloud


You can view (but not edit) details about ultra low latency stream targets in the Wowza Streaming Cloud web manager.

  1. In Wowza Streaming Cloud, click Advanced on the menu bar and then click Stream Targets.
  2. Find an ultra low latency stream target and click its name.

The stream target detail page shows the target's setup as it was configured in the REST API. To edit the ultra low latency stream target, use the REST API.

Note: Only secure WebSocket and Apple HLS playback URLs are shown on the ultra low latency stream target detail page. Additional WebSocket, WOWZ, and HLS playback URLs are available through the REST API.

  1. (Optional) Click Usage to see bandwidth usage and viewer data for the ultra low latency stream target.

More resources



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