Override the origin or edge server location used by an ultra low latency stream target with the Wowza Streaming Cloud REST API

The Wowza Streaming Cloud™ service automatically selects the optimal location for the origin and edge servers used by Wowza ultra low latency stream targets. You can, however, override these defaults and choose a region you want use as the origin server, or force the player to pull from an edge server in a specific region.

For the most efficient ultra low latency streaming, it's important to use the origin (ingest) server that's closest to your encoder. If you can determine that better than the Wowza Streaming Cloud REST API's own DNS query, then you can override the location of the origin server chosen by the API.

For playback, it can be useful to force the player to pull from a specific region for debugging or testing purposes.

Note: Ultra low latency streaming is available through Wowza Streaming Cloud with Ultra Low Latency. For more information see About ultra low latency streaming with the Wowza Streaming Cloud REST API.

Contents


About regions
Specify a region for a pull target origin server
Specify a region for a push target origin server
Specify a region for an edge (playback) server
More resources

About regions


The Wowza Streaming Cloud ultra low latency service uses servers on multiple continents to receive and deliver streams. 

Region Location
nl-central1 West Europe
us-central1 Central United States
in-west1 Central India
hk-central1 East Asia
jp-east1 East Japan

Specify a region for a pull target origin server


For an ultra low latency stream target whose source delivery method is pull, you can control the region used for the origin server by using the region_override parameter when you create or update the stream target in the Wowza Streaming Cloud REST API.

Parameter Data Type Description
region_override string

For ultra low latency stream targets whose source delivery method (source_delivery_method) is pull. The location of the stream target's origin (ingest) server. 

Valid values:
origin-nl-central1.cdn.wowza.com
origin-us-central1.cdn.wowza.com
origin-in-west1.cdn.wowza.com
origin-hk-central1.cdn.wowza.com
origin-jp-east1.cdn.wowza.com

If you don't specify a region, the service determines the optimal location based on the DNS location of the request.


Example request and response

Create an ultra low latency pull stream target whose origin server uses the nl-central1 (West Europe) region:

Notes:

  • In the Wowza Streaming Cloud REST API version 1.2 and later, use the /stream_targets/ull endpoint instead of the /stream_targets endpoint to create an ultra low latency stream target.
  • 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.2.
curl -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" -H "Content-Type: application/json" -X POST -d '{
    "ull_stream_target": {
        "name": "My West Europe Ultra Low Latency Pull Target",
        "source_delivery_method": "pull",
        "source_url": "rtsp://example.com/live",
        "region_override": "origin-nl-central1.cdn.wowza.com",
        "enabled": true
    }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/ull"

The command creates an ultra low latency stream target whose origin server uses the specified region_override. The details of the stream target's configuration are provided in the response, which should look something like this:

{
    "ull_stream_target": {
        "id": "ptr299dv",
        "name": "My West Europe Ultra Low Latency Pull Target",
        "enabled": true,
        "state": "stopped",
        "source_delivery_method": "pull",
        "source_url": "rtsp://example.com/video",
        "region_override": "origin-nl-central1.cdn.wowza.com",
        "playback_urls": {
            "ws": [
                "ws://edge.cdn.wowza.com/live/_definst_/0P1p1U1FzUzJOTkQ4N29SRlFaTkZ5d13/stream.ws",
                "wss://edge.cdn.wowza.com/live/_definst_/0P1p1U1FzUzJOTkQ4N29SRlFaTkZ5d13/stream.ws"
            ],
            "wowz": [
                "wowz://edge.cdn.wowza.com/live/_definst_/0P1p1U1FzUzJOTkQ4N29SRlFaTkZ5d13",
                "wowzs://edge.cdn.wowza.com/live/_definst_/0P1p1U1FzUzJOTkQ4N29SRlFaTkZ5d13"
            ]
        },
        "enable_hls": false,
        ...
    }
}

Related requests

Update an ultra low latency stream target

curl -H "wsc-api-key: [key]" -H "wsc-access-key: [key]" -H "Content-Type: application/json" -X PATCH -d '{
    "ull_stream_target": {
        "name": "My East Japan Ultra Low Latency Pull Target",
        "region_override": "origin-jp-east1.cdn.wowza.com"
    }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/ull"

Specify a region for a push target origin server


For an ultra low latency stream target whose source delivery method is push, you can manually specify the region used for the origin server after you create the stream target in the Wowza Streaming Cloud REST API.

The regions available to push stream targets are the same as those used by the region_override parameter for pull streams:
origin-nl-central1.cdn.wowza.com
origin-us-central1.cdn.wowza.com
origin-in-west1.cdn.wowza.com
origin-hk-central1.cdn.wowza.com
origin-jp-east1.cdn.wowza.com

Primary ingest URLs look like this:

rtmp://origin.cdn.wowza.com

but you can add a region to the hostname of the URL, like this:

rtmp://origin-nl-central1.cdn.wowza.com

In this example, the stream ingests into the n1-central1 (West Europe) region.

Simply enter the modified URL into your source instead of entering the default URL.

To view the complete, default primary URL for a push target, run a GET request:

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

The request returns the target's details, including the primary_url, and looks something like this:

{
    "ull_stream_target": {
        "id": "n79qfppb",
        "name": "My Eastern US Ultra Low Latency Push Target",
        "enabled": true,
        "state": "stopped",
        "stream_name": "0I0q1bjZhRzZtfSdv4TpCnlmwQT16236",
        "primary_url": "rtmp://origin.cdn.wowza.com:1935/live/0I0q1bjZhRzZtfSdv4TpCnlmwQT16236",
        "source_delivery_method": "push",
        "playback_urls": {
            "ws": [
                "ws://edge.cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160/stream.ws",
                "wss://edge.cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160/stream.ws"
            ],
            "wowz": [
                "wowz://edge.cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160",
                "wowzs://edge.cdn.wowza.com/live/_definst_/0P0q1bjZhRzJxaE80b3lremtKSnZ6160"
            ],
            "hls": [
                "https://[wowzasubdomain]-i.akamaihd.net/hls/live/268548/0P0q1bjZhRzJxaE80b3lremtKSnZ6160/playlist.m3u8"
            ]
        },
        "enable_hls": true,
        "connection_code": "already_used",
        "connection_code_expires_at": "2017-10-26T18:23:24.000Z",
        ...
    }
}

Specify a region for an edge (playback) server


You can also use the override regions in an ultra low latency stream's playback URL to force the stream to use an edge server in that region.

Note: You can't specify the region for backup Apple HLS playback URLs. You can only specify a region for WebSocket and WOWZ playback URLs.

Playback URLs look like this:

[ws or wowz prefix]://edge.cdn.wowza.com/

but you can add a region to the hostname of the URL, like this:

[ws or wowz prefix]://edge-n1-central1.cdn.wowza.com/

In this example, the stream plays from an edge server in the nl-central1 (West Europe) region.

Available region override values for forcing a stream to play from a particular region:
edge-nl-central1.cdn.wowza.com
edge-us-central1.cdn.wowza.com
edge-in-west1.cdn.wowza.com
edge-hk-central1.cdn.wowza.com
edge-jp-east1.cdn.wowza.com

To view the complete, default playback URL for any target, run a GET request:

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

The request returns the target's details, including a hash of playback URLs, which looks something like this:

"playback_urls": {
    "ws": [
        "ws://edge.cdn.wowza.com/live/_definst_/0P1q1bGo4YmR1bGNKWW9nWVVodHJ6010/stream.ws",
        "wss://edge.cdn.wowza.com/live/_definst_/0P1q1bGo4YmR1bGNKWW9nWVVodHJ6010/stream.ws"
    ],
    "wowz": [
        "wowz://edge.cdn.wowza.com/live/_definst_/0P1q1bGo4YmR1bGNKWW9nWVVodHJ6010",
        "wowzs://edge.cdn.wowza.com/live/_definst_/0P1q1bGo4YmR1bGNKWW9nWVVodHJ6010"
    ]
}

Simply include the hostname in playback URL in your embed code so that it includes the region, for example:

ws://edge-n1-central1.cdn.wowza.com/live/_definst_/0P1q1bGo4YmR1bGNKWW9nWVVodHJ6010/stream.ws

More resources