Skip to main content

Agora Developer Center

Docs

Start Broadcast Streaming using Agora domain

This page shows how to start Broadcast Streaming using the default Agora domain. With a simple API call, you get everything you need to push a live stream and play it back.

Prerequisites​

Before proceeding, ensure that you meet the following requirements:

Project setup​

Get an App ID​

Agora automatically assigns each project an App ID as a unique identifier.

To copy this App ID, find your project on the Project Management page in Agora Console, and click the copy icon in the App ID column.

Get a Customer ID and Customer Secret​

Broadcast Streaming servers use a Customer ID/Customer Secret pair for authentication.

To generate a set of Customer ID and Customer Secret, do the following:

  1. In Agora Console, click the account name in the top right corner, and click RESTful API from the drop-down list to enter the RESTful API page. 1637661003647
  2. Click Add a secret, and click OK. A set of Customer ID and Customer Secret is generated.
  3. Click Download in the Customer Secret column. Read the pop-up window carefully, and save the downloaded key_and_secret.txt file in a secure location.
This quickstart uses the curl -u command to generate the Authorization parameter in the HTTP request header. Alternatively, you can use the sample code for other programming languages in Pass the basic HTTP authentication.

Implement Broadcast Streaming​

Step 1: Create a live stream ​

To create a live stream, send a request to the Broadcast Streaming endpoint:

  1. Copy the following code into your command-line tool:


    _7
    appid=<Your_App_ID>
    _7
    key=<Your_Customer_ID>
    _7
    secret=<Your_Customer_Secret>
    _7
    _7
    curl https://api.agora.io/${region}/v1/projects/${appid}/cfls/live-streams \
    _7
    -u "${key}:${secret}" \
    _7
    -X POST

  2. Replace <Your_App_ID>, <Your_Customer_ID>, and <Your_Customer_Secret> with your values from Agora Console.

  3. Replace ${region} with the value for your business region:

    • na: North America.
    • ap: Southeast Asia.
    • eu: Europe.

If the request is successful, the response includes a Stream Key and a Playback ID, which are used in subsequent steps:

  • Stream Key: A secret used to configure streaming software.
  • Playback ID: A string used to create the playback URL.
The Broadcast Streaming servers automatically delete all the information about a live stream if the Stream Key or Playback ID is inactive for 30 days.

_25
{
_25
"status": "success",
_25
"data": {
_25
"id": "v2xxxxxxO5",
_25
// Your Stream Key
_25
"streamKey": "M3xxxxxxWb",
_25
"playbackIds": [
_25
{
_25
// Your Playback ID
_25
"id": "vgxxxxxxQy",
_25
"policy": "public"
_25
}
_25
],
_25
"transcodings": {
_25
"id": "default",
_25
"standardTemps": [
_25
"fhd",
_25
"sd1",
_25
"ld"
_25
],
_25
"createdAt": "1640995200"
_25
},
_25
"createdAt": "1650017833"
_25
}
_25
}

The detailed description of the response body fields is as follows:

  • status: Whether the request is successful. Possible values include:
    • "success": The request is successful. Detailed information is returned in data.
    • "fail": The request failed because of invalid arguments.
    • "error": The request failed because of a server error.
  • data: A JSON Object which contains the following fields:
    • id: The unique identifier of the stream.
    • streamKey: The Stream Key, a secret used to configure streaming software.
    • playbackIds: A JSON Array of Playback ID objects. Each Playback ID object contains the following fields:
      • id: The Playback ID, a string used to create the playback URL.
      • policy: The playback policy. Possible values include:
        • "public": The Playback ID alone can be used to play the live stream.
        • "private": The Playback ID must be used with a JSON Web Token (JWT) to play the live stream.
    • transcodings: A JSON Object which contains the following fields:
      • id: The unique identifier of the transcoding configuration. "default" stands for the default configuration.
      • standardTemps: A JSON Array of the standard transcoding templates you want to use. For details about standard transcoding templates, see Transcoding Configuration API Reference.
      • createdAt: The time (Unix timestamp) when the transcoding configuration is created.
    • createdAt: The time (Unix timestamp) when the live stream is created.

Step 2: Push the live stream​

Broadcast Streaming supports pushing streams using the RTMP or RTMPS protocol. To push an RTMP or RTMPS stream, you need to configure streaming software. The following example uses OBS:

  1. Open OBS, and click the Settings button in the widget list in the bottom right corner. open obs setting

  2. Click Stream in the left navigation menu in the Settings window, and choose Custom... in Service.

  3. Fill in the Server and Stream key:

    • Server: rtmps://stream-in.agoramdn.com/live
    • Stream key: The streamKey that is returned when you create a live stream.

  4. Click OK to save the settings.

Step 3: Play the live stream​

To play the live stream, create an HTTP Live Streaming (HLS) playback URL using the Playback ID returned when you create the live stream:


_1
https://stream.agoramdn.com/${playbackId}.m3u8

For each live stream to be played, Broadcast Streaming automatically transcodes the stream into three resolutions. The URLs of these three stream versions are provided in the Master Playlist:


_8
#EXTM3U
_8
#EXT-X-VERSION:6
_8
#EXT-X-STREAM-INF:BANDWIDTH=2150400,CODECS=mp4a.40.2,avc1.640020,RESOLUTION=1920x1080
_8
https://global.manifest.a2.agoramdn.com/S3hLV2o3bUFrYWhwaUpmbWFLWmVaWmtkcVZ1WlB4TUhhQ3NSOmZoZA/rendition.m3u8?token=NjIzNDM2M2ZfYjA2NzEyZWJjMWMxNmEzNjA2NGVkNTcyMmQzYjE4ZTExZDE3YmU3NDM4YzYyNjc4NzU1MjE5MDk0NWJhMmUzYQ%3D%3D
_8
#EXT-X-STREAM-INF:BANDWIDTH=655360,CODECS=mp4a.40.2,avc1.640020,RESOLUTION=640x360
_8
https://global.manifest.a2.agoramdn.com/S3hLV2o3bUFrYWhwaUpmbWFLWmVaWmtkcVZ1WlB4TUhhQ3NSOnNkMQ/rendition.m3u8?token=NjIzNDM2M2ZfZWVlMzZjNGU0MjdiMDgzYTEwZGFjYWFlMGY0YmNhMjk4YzkxODllYTBhOGI3NjJjOWMzNmVkMmE1N2Q5MmMxYw%3D%3D
_8
#EXT-X-STREAM-INF:BANDWIDTH=409600,CODECS=mp4a.40.2,avc1.640020,RESOLUTION=360x240
_8
https://global.manifest.a2.agoramdn.com/S3hLV2o3bUFrYWhwaUpmbWFLWmVaWmtkcVZ1WlB4TUhhQ3NSOmxk/rendition.m3u8?token=NjIzNDM2M2ZfNDc4ZDRlYzk2MzkzMDBkYTA3MDE5NjRlMTg0NmYxMzdjNWI2MGJlNzJlMzA3MmU0MzRlNWU5MDM3MTYzYzM5Yw%3D%3D

If you want to access the original stream (which is not transcoded), use the following playback URL instead:


_1
https://stream.agoramdn.com/${playbackId}_original.m3u8

Step 4: Stop streaming​

Stop the streaming software to disconnect from the Broadcast Streaming servers.

Next steps​

After implementing Broadcast Streaming, you can try the following functions.

Use transcoding templates​

  1. Get a transcodingsId by sending the following request:


    _18
    appid=<Your_App_ID>
    _18
    key=<Your_Customer_ID>
    _18
    secret=<Your_Customer_Secret>
    _18
    _18
    curl https://api.agora.io/${region}/v1/projects/${appid}/cfls/live-transcodings\
    _18
    -u "${key}:${secret}" \
    _18
    -H "Content-Type: application/json" \
    _18
    -X POST \
    _18
    -d '{
    _18
    "settings": {
    _18
    "standardTemps": [
    _18
    # Specify transcoding templates here
    _18
    "hd",
    _18
    "sd1",
    _18
    "ld"
    _18
    ]
    _18
    }
    _18
    }'

    1. Replace <Your_App_ID>, <Your_Customer_ID>, <Your_Customer_Secret>, and ${region} with your values.
    2. Specify the transcoding templates you want to use in standardTemps. For details about the supported templates, see Transcoding Configuration API Reference.

    If the request is successful, the response looks like this:


    _13
    {
    _13
    "status": "success",
    _13
    "data": {
    _13
    // Your transcodingsId
    _13
    "id": "zFxxxxxxmk",
    _13
    "standardTemps": [
    _13
    "hd",
    _13
    "sd1",
    _13
    "ld"
    _13
    ],
    _13
    "createdAt": "1650018546"
    _13
    }
    _13
    }

  2. Pass in the transcodingsId when creating a live stream:


    _9
    curl https://api.agora.io/${region}/v1/projects/${appid}/cfls/live-streams \
    _9
    -u "${key}:${secret}" \
    _9
    -H "Content-Type: application/json" \
    _9
    -X POST \
    _9
    -d '{
    _9
    "settings":{
    _9
    "transcodingsId": "zFxxxxxxmk"
    _9
    }
    _9
    }'

  3. When playing the live stream, Broadcast Streaming automatically transcodes the stream using the specified templates. You can find the corresponding URLs in the Master Playlist.

Page Content