The WebRTC Content Delivery Network (CDN) refers to geographically distributed clusters of servers which work together to provide real-time streaming worldwide at scale. Dolby.io distributes streaming content across multiple regions through a network of cloud hosting providers.

A traditional CDN needs to cache live stream segments on a network before they are able to be delivered to viewers over HTTP. This operation would generally add many seconds of latency to a live stream. The intelligent scaling provided by Dolby.io over global infrastructure is what enables increasingly large audiences with concurrent streams to experience ultra low latency.

This guide covers a few examples:

Multi-region Support

A publishing token is configured with a specific cluster region. This value indicates which data center should be used as the origin when broadcasting. It can be explicitly set independently for each discrete token or be automatically assigned from the account's overall configuration.

Auto will use geo-detection to choose a region

When creating a publishing token, selecting the region that is closest to the broadcast location will improve latency and quality. The publishing cluster region setting can be configured to one of the following specific regions:

Cluster Code	Region Location
ams-1	Amsterdam
blr-1	Bangalore
phx-1	Phoenix
sgp-1	Singapore

🚧
Blocking Regions
See Geo-blocking for gating techniques to precisely prohibit and restrict access of content distribution.

Cluster Regions in the Dashboard

You can manage cluster regions by changing settings from user interface of the Streaming Dashboard.

👍
Getting Started
If you haven't already, begin by following the Getting Started tutorial to create a Dolby.io application and start your first broadcast. You will need to have a publishing token. See Managing Your Tokens for more details about tokens.

How-to Set the Cluster Region Using the Dashboard

Open the Streaming section of the Dolby.io Dashboard. Select the publishing token you want to modify. Within the Settings section you can choose the Cluster Region from the dropdown.

How-to Identify the Cluster Region for an Active Stream

When using the Dolby.io Dashboard publisher to broadcast or the viewer to playback you can select the gear setting to view the Media Stats.

This will display a modal overlaying the stream with details about resolution, bitrate, etc. and will also display the Cluster value using one of the region codes.

REST APIs

When working with clusters you can automate workflows using available REST APIs.

The /api/cluster endpoint allows you to query available cluster regions or change the default cluster for your account
The /api/publish_token endpoint allows you to update the cluster for an existing publish token or to define a value when creating a new token

👍
Using the REST APIs
Review the REST API platform guide for more details on generating an API secret for authentication. You will need an API Secret from the dashboard in order to make requests.

How-to Get the Available Cluster Regions

You make a GET request with the /api/cluster endpoint to fetch details about the defaultCluster and a list of the availableClusters to find the list of available cluster regions.

The results may look like this:

{
    "status": "success",
    "data": {
        "defaultCluster": "auto",
        "availableClusters": [
            {
                "id": "ams-1",
                "name": "Amsterdam",
                "rtmp": "rtmp-ams-1.millicast.com",
                "srt": "srt-ams-1.millicast.com"
            },
            {
                "id": "auto",
                "name": "Auto",
                "rtmp": "rtmp-auto.millicast.com",
                "srt": "srt-auto.millicast.com"
            },
            {
                "id": "blr-1",
                "name": "Bangalore",
                "rtmp": "rtmp-blr-1.millicast.com",
                "srt": "srt-blr-1.millicast.com"
            },
            {
                "id": "phx-1",
                "name": "Phoenix",
                "rtmp": "rtmp-phx-1.millicast.com",
                "srt": "srt-phx-1.millicast.com"
            },
            {
                "id": "sgp-1",
                "name": "Singapore",
                "rtmp": "rtmp-sgp-1.millicast.com",
                "srt": "srt-sgp-1.millicast.com"
            }
        ]
    }
}

How-to Set the Cluster Region Default

You make a PUT request with the /api/cluster endpoint to update the default account cluster that is used when creating new publishing tokens.

For example, you can use curl to set the default cluster for any new tokens to Amsterdam.

curl --request PUT \
  --url https://api.millicast.com/api/cluster \
  --header "Authorization: Bearer $DOLBYIO_API_SECRET"
  --data '{
    "defaultCluster": "ams-1"
  }'

How-to Set the Cluster Region for a Publish Token

You make a POST request to /api/publish_token in order to create a new token. The originCluster parameter specifies the cluster to use. This should be specified using the abbreviated code. You can make a PUT request to /api/publish_token/{tokenId} to change the cluster region for an existing token.

For example, you can create a new token for Amsterdam.

curl --request POST \
  --url https://api.millicast.com/api/publish_token \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DOLBYIO_API_SECRET" \
  --data '{
      "label": "amsterdam-token",
      "streams": [{"streamName": "myStream"}],
      "originCluster": "ams-1"
    }'

Troubleshooting

Unauthorized

If you receive an Unauthorized error make sure that you are specifying an Authorization header and that it is passing in a valid API Secret from your Streaming dashboard.

{"status":"fail","data":{"message":"Unauthorized"}}

Unsupported Media Type

If you receive an Unsupported Media Type error make sure you are specifying the Content-Type header.

{"status":"fail","data":{"message":"Unsupported Media Type"}}%

Validation error - CreateStreamNameModel

If you receive Validation errors from a REST request make sure you are providing all of the required parameters. For example, you may see this error if you don't specify the streams parameter as a list of dictionaries.

{"status":"fail","data":{"errors":{"$.streams[0]":["The JSON value could not be converted to Millicast.CustomerApi.Models.Tokens.Request.CreateStreamNameModel. Path: $.streams[0] | LineNumber: 2 | BytePositionInLine: 28."]},"message":"Validation errors"}}%

Learn More

Learn more by exploring the developer blog and code samples.