Skip to main content

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.

Understand the tech

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

Process of constructing urls

Construct the URL for pushing a live stream

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

example url of stream pushing

Description of each part:

URL segmentRequiredDescription
Domain nameYesThe domain name for pushing the stream. Ensure that the CNAME records point to the agora domain.
Entry pointYesThe default entry point is live, and each entry point has its own live streaming configuration.
Stream nameYesThe name of the live streaming. One stream name identifies one live streaming, so please ensure each live streaming has a unique stream name.
Authentication stringNoIf 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.

Construct the URL for playing a live stream

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 protocolURL pathURL sample

Calculate the authentication string

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.

Step 2: Calculate the expiration timestamp

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.

Sample code

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

import time
from urllib.parse import urlparse
import hashlib
key = 'test_key'
play_url_str = ''
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()
play_url_str += "?ts={}&sign={}".format(now, md5.hexdigest())