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:
|
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 FLS.
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.
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.
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:
#!/usr/bin/python3
import time
from urllib.parse import urlparse
import hashlib
key = 'test_key'
play_url_str = 'http://push.test.com/live/test.flv'
key_expire_time = 60*15
url = urlparse(play_url_str)
now = int(time.time()) + key_expire_time
sign = key + url.path + str(now)
md5 = hashlib.md5()
md5.update(sign.encode('utf-8'))
play_url_str += "?ts={}&sign={}".format(now, md5.hexdigest())
print(play_url_str)