URL construction

Agora has a set of rules for you to follow when constructing URLs for pushing and playing live streams. This page introduces these rules.

As the URL could contain authentication information, Agora recommends constructing the URL in your business server. The following diagram shows the process:

The URL for pushing a live stream includes four parts as shown in the following example:

Description of each part:

URL segment	Required	Description
Domain name	Yes	The domain name for pushing the stream. Ensure that the CNAME records point to the agora domain.
Entry point	Yes	The default entry point is live, and each entry point has its own live streaming configuration.
Stream name	Yes	The name of the live streaming. One stream name identifies one live streaming, so please ensure each live streaming has a unique stream name.
Authentication string	No	If the live streaming authentication is not set, the "?" and the content behind it are not required in the URL address. The authentication string consists the following parameters: ts: The Unix timestamp (s) when the URL expires. This value shows the time that the authentication string expires. For example, ts=1635004800 means the authentication string is valid before October 23th, 2021 (CST). sign: The hotlink protection signature. For more details, see Calculate the Authentication String.

The rules for constructing the URL for playing a live stream are similar to those of the stream-pushing URL, but the URL paths of different stream-playing protocols vary slightly.

The domain name in the URL must be a stream-playing domain name.

Playback protocol	URL path	URL sample
RTMP	/{entry-point}/{stream}	rtmp(s)://domain/live/stream?ts=1635004800&sign=95b0a9970c593819
HTTP-FLV	/{entry-point}/{stream}.flv	http(s)://domain/live/stream**.flv**?ts=1635004800&sign=337f185b6571cd42
HLS	/{entry-point}/{stream}/playlist.m3u8	http(s)://domain/live/stream/playlist.m3u8?ts=1635004800&sign=a1d2d3bcce31c9fe

This section introduces how to generate the URL authentication strings.

The authentication key is used to generate the signature in the business server and to verify the signature during the Agora Broadcast Streaming.

The authentication key is a string of no more than 128 bytes, and you need to set it yourself. For setting the authentication key for each stream-pushing and stream-playing domain name, see Stream Authentication Configuration.

Do not use the authentication key on the client side or leak it to any third party, or your URLs could be hotlinked.

The ts parameter in the stream-pushing or stream-playing URL determines the valid time of the URL.

If the current time is October 23, 2021 10:00:00 CST, its Unix timestamp is 1634954400. If you expect the valid time to be 10 minutes, that is, being valid before October 23, 2021 10:10:00 CST, the Unix timestamp is 1634955000 (ts=1634955000).

The valid time of a URL must neither be too short nor too long. Agora recommends setting it between 5 and 10 minutes.

• If the valid time is too short, the client side could fail to push or play the stream when it tries to reconnect to the server.
• If the valid time is too long, your URL could be at risk.

The signature (sign) is the MD5 value calculated by the constructed strings of the authentication key, the path of the URL pushing or playing the stream, and the expiration timestamp (ts).

For example, if the URL is http://domain/live/stream.flv, the authentication key is z2tn3uiny0aasebz, and ts is 1634955000, the sign is MD5(z2tn3uiny0aasebz/live/stream.flv1634955000)=b6ceec4cf7c1bd88e911b72cf39e4715.

The following sample code shows how to calculate the authentication string by using Python 3:

_14

#!/usr/bin/python3

_14

import time

_14

from urllib.parse import urlparse

_14

import hashlib

_14

key = 'test_key'

_14

play_url_str = 'http://push.test.com/live/test.flv'

_14

key_expire_time = 60*15

_14

url = urlparse(play_url_str)

_14

now = int(time.time()) + key_expire_time

_14

sign = key + url.path + str(now)

_14

md5 = hashlib.md5()

_14

md5.update(sign.encode('utf-8'))

_14

play_url_str += "?ts={}&sign={}".format(now, md5.hexdigest())

_14

print(play_url_str)