Media Pull RESTful API

The RESTful API for Media Pull enables you to inject an online media stream into the Agora channel as a live video source. After the injection succeeds, the online media stream automatically plays in the Agora channel, and remote users can see the content of the media stream.

Working principle

Injecting an online media stream into the Agora channel creates a Media Pull task (shown as "cloud player" in the rest of the article) in the Agora channel. You can control the cloud player through the RESTful API and accomplish the following functions for Media:

• Create: Creates a cloud player in the project.
• Delete: Destroys the cloud player in the project.
• List: Queries and lists all the cloud players in the project.

The Media Pull service supports the following formats:

• Video codec formats: H.264, H.265, and VP8
• Audio codec formats: AAC and OPUS
• Protocols: HTTP, HTTPS, and RTMP
• Container formats: FLV, MP4, MPEG-TS, Matroska (MKV), and HLS

Enable the service

Follow these steps to enable the Media Pull service in Agora Console:

1. Log in to Agora Console, and click the Project Management icon on the left navigation panel.

2. On the Project Management page, find the project for which you want to enable the Media Pull service, and click Config.

   

3. Under Real-time engagement extensions, find Media Pull, and click Enable.

4. Click Enable Media Pull.

5. Click Apply.

Now, you can use Media Pull service and see the usage statistics in the Usage page.

Pass the basic HTTP authentication

The RESTful APIs require basic HTTP authentication. You need to set the Authorization parameter in every HTTP request header. For how to get the value for Authorization, see basic HTTP authentication.

Create API

This API creates a cloud player in the project.

HTTP request

POST https://api.agora.io/{region}/v1/projects/{appId}/cloud-player/players

Path parameters

• appId: (Required) String. Agora provides the App ID when you create a project in Agora Console. The App ID identifies each project.
• region: (Required) String. The region that the cloud player was created in. Agora supports the creation of cloud players in different regions. Currently, it supports four regions:
  • cn: China Mainland
  • ap: Asia Pacific
  • na: North America
  • eu: Europe
    Please ensure that the region you set is the same region as where your media stream originates is located.

Query parameters

A sample request URL when using query parameters:

https://api.agora.io/{region}/v1/projects/{appId}/cloud-player/players?streamIp={streamIp} 

streamIp: (Optional) String. The IP address of the media stream's origin server. Must be a valid IPv4 address. Use this parameter to ensure the transmission quality of the media stream when the media stream is only available in some regions. Otherwise, ignore this parameter.

Request header

The request header contains the following fields:

• Content-Type: application/json

• Authorization: See Authentication.

• X-Request-ID: UUID (Universally Unique Identifier) to identify this request. After passing in the field, Agora's server returns it in the response header.

  Agora recommends using this field. If you do not pass in any value, Agora's server automatically generates a UUID to pass in.

Request body

If the status code is 2XX, the request succeeds. The response body is a JSON Object called player, containing the following fields:

• You must set the cloud player's username, which can be Number type or String type. Otherwise, the cloud player cannot be created, and Agora's server returns the 400(Bad Request) status code. Ensure that you have read How can I use a username in string type? when using a username in String type.
• To avoid the failed request, do not pass null or "" in the required fields.

• audioOptions: (Optional) JSON Object. The audio transcoding configuration of the cloud player. Setting this field to empty or not set means that the audio is not transcoded.

  • Profile：Number. Audio profile. Sets the audio profile sample rate, bitrate, encoding mode, and the number of channels.
    • 0: Default audio profile.
      • In the communication profile, the default audio profile represents a sample rate of 32 kHz, audio encoding, mono, and a bitrate of up to 18 Kbps.
      • In the live broadcasting profile, the default audio profile represents a sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps.
    • 1: SPEECH_STANDARD. A sample rate of 32 kHz, audio encoding, mono, and a bitrate of up to 18 Kbps.
    • 2: MUSIC_STANDARD. A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps.
    • 3: MUSIC_STANDARD_STEREO. A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 80 Kbps.
    • 4: MUSIC_HIGH_QUALITY. A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 96 Kbps.
    • 5: MUSIC_HIGH_QUALITY_STEREO. A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 128 Kbps.

• videoOptions: (Optional) JSON Object. The video transcoding configuration of the cloud player. Setting this field to empty or not set means that the video is not transcoded.

  • width: Number. The width (px) of the output video. The value range is [66,1920].
  • height: Number. The height (px) of the output video. The value range is [66,1080].
  • widthHeightAdaption: Bool. Whether to enable horizontal and vertical screen adaptive mode:
    • true: Enable portrait and landscape adaptive mode. After you enable the adaptive mode, if the source media stream is in landscape mode, the output video width and height are 1280 × 720; if the source media stream is in portrait mode, the output video width and height are 720 × 1280.
    • false: (Default) Do not enable portrait and landscape adaptive mode.
  • frameRate: The frameRate (fps) of the output video. The value range is [1,30]. The default value is 15. For details, see Video profile table.
  • bitrate: Number. The bitrate (Kbps) of the output video. The value range is [1,10000]. For details, see Video profile table.
  • fillMode: String. The fill mode of the output video:
    • fit: (Default) Scales the video proportionally until it is fully displayed in the viewport.
    • fill: Scales the video proportionally until it fills the viewport.

• streamUrl: (Required) String. The RTMP/HTTP/HTTPS URL of the online media stream. The maximum length of this field is 1024 bytes.

  To inject an image to the Agora channel, set streamUrl to the URL of the image you want to inject, and the cloud player will convert the image to a video and inject it to the Agora channel. Images in JPEG and PNG formats are currently supported. You can set video transcoding parameters through videoOptions.

• channelName: (Required) String. The channel name. The maximum length of this field is 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

• uid: (Optional) Number. The User ID of the cloud player in the channel. The value ranges from 0 to (2³²-1). When passing in 0, Agora's server automatically assigns a User ID to the player.

  Ensure that the value is different from any other User IDs of other users and players in the channel.

• account: (Optional) String. The User Account of the cloud player in the channel. The maximum length of this field is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

  Ensure that the value is different from any other User Accounts of other users and players in the channel.

• token: (Optional) String. The authentication token used by the cloud player in the channel. If you do not enable the App Certificate in Agora Console, ignore this field. If you enable the App Certificate in Agora Console, you must pass a value in this field:

  • For low-security requirements: Use the temporary token generated in Agora Console. For details, see Generate an RTC temporary token.

  • For high-security requirements: Use the token generated at your server. For details, see Authenticate Your Users with Tokens.

    When generating a token at your server, the value of uid or account must be the same as the User ID or User Account of the cloud player, and privilegeExpiredTs is recommended to be 0 to ensure that the token is valid for 24 hours at most.

• idleTimeout: (Optional) Number. The maximum length of time (in seconds) that the cloud player is idle. The "idle" state means that the media stream is not playing. When the idle state exceeds idleTimeout, the cloud player is automatically destroyed. The value ranges from 5 to 600. The default value is 300. If the value is less than 5, Agora's server automatically adjusts it to 5; if the value is greater than 600, Agora's server automatically adjusts it to 600.

• playTs: (Optional) Number. The Unix timestamp (in seconds) when the cloud player starts playing the online media stream. The value range of playTs is [createTs-86400, createTs+300]. The default value is 0, which means the cloud player starts playing the online media stream when the cloud player is successfully created. If the value of playTs is not 0, the following behavior occurs:

  • playTs > createTs: The cloud player starts playing the online media stream when the time is in [playTs-5,playTs]. This is suitable for timing playback with other elements.
  • playTs < createTs: If the online media stream is a live stream, the cloud player starts playing the live stream when the cloud player is successfully created. If the online media stream is an on-demand stream, the cloud player starts playing the online media stream at the specified time in the stream prior to the creation of the cloud player. This is suitable for error recovery. For example, if the cloud player experiences an error during operation, you can create a new cloud player and set the playTs field of new cloud player to the unix timestamp when the old cloud player started to play the online media stream.

• name: (Optional) String. The name of the cloud player. The maximum length of this parameter is 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • "-", "_".
    name is null if you do not pass any value. Multiple cloud players using null name parameters can exist in one project at the same time; multiple cloud players with the same name cannot exist in one project at the same time. When trying to create a cloud player with the same name as an existing cloud player in the project, you will receive the 409(Conflict) status code.

    To avoid repeatedly creating multiple cloud players to inject the same online media stream into the same channel, use the name parameter to manage all the cloud players in your specified project. Agora recommends that you pass a value in name using a combination of the channel name (channelName) and the username (uid or account) of the cloud player, such as class32_101 and class33_teacher101 in the sample code.

• encryptMode: (Optional) String. Encryption mode. Agora recommends using either the aes-128-gcm2 or aes-256-gcm2 encryption mode, both of which support adding a salt and are more secure.

  • aes-128-xts: 128-bit AES encryption, XTS mode.
  • aes-256-xts: 256-bit AES encryption, XTS mode.
  • aes-128-ecb: 128-bit AES encryption, ECB mode.
  • sm4-128-ecb: 128-bit SM4 encryption, ECB mode.
  • aes-128-gcm: 128-bit AES encryption, GCM mode.
  • aes-256-gcm: 256-bit AES encryption, GCM mode.
  • aes-128-gcm2: 128-bit AES encryption, GCM mode. Compared to aes-128-gcm encryption mode, aes-128-gcm2 encryption mode is more secure and requires you to set the salt (encryptKdfSalt).
  • aes-256-gcm2: 256-bit AES encryption, GCM mode. Compared to aes-256-gcm encryption mode, aes-256-gcm2 encryption mode is more secure and requires you to set the salt (encryptKdfSalt).

• encryptKey: (Optional) String. Encryption key with unlimited length. Agora recommends using a 32-byte key.

  If you do not set an encryption key or set it as null, you cannot use the built-in encryption.

• encryptKdfSalt: (Optional) String. The salt with the length of 32 bytes. Agora recommends using OpenSSL to generate the salt on your server. For details, see Media Stream Encryption.

  This parameter is only valid when you set the encryption mode as aes-128-gcm2 or aes-256-gcm2. In this case, ensure that this parameter is not 0.

• repeatTime: (Optional) Int. Number of media streams played. This parameter applies only to on-demand streams. It can be set to:

  • 1: (Default) Plays a media resource once.
  • -1: Plays media resources in a loop.
  • N: User-defined number of media resources to be played. It is an integer and cannot be set to 0.

• seekPosition: (Optional) Number. Specifies the playback position (seconds) of the on-demand file. The default value is 0, which means play from the beginning of the on-demand file. It must be less than the media resource duration.

• dataStreamOptions: (Optional) JSON Object. The data stream configuration, which is used to set the SEI information carried by the video frame. This parameter applies only to on-demand streams.

  • enable: Set whether to inject the SEI information of DataStream type.

    • true: Inject the SEI information of DataStream type.

    • false: (Default) Do not inject the SEI information of DataStream type.
      DataStream is a data stream format of protobuf type, the example is as follows:

      message PositionData {
        # The length of the on-demand file (seconds), 1 means that the field display order is 1
      int32 duration = 1;
        # The playback position of the on-demand file (seconds), 2 means that the field display order is 2
      int32 position = 2;
        # The user ID of the host playing the on-demand file, 3 means that the field display order is 3
      int32 uid = 3;
      }

HTTP response

For all possible response status codes, see Status codes.

Response header

The response header contains the following fields:

• X-Request-ID: UUID (Universally Unique Identifier) to identify this request. It is the same as the X-Request-ID field in the request header. If the request fails, print out this value in the log for troubleshooting.

If you receive the 401(Unauthorized) status code for this request, the response header does not contain the field.

• X-Resource-ID: UUID (Universally Unique Identifier) to identify the cloud player created by this request:
  • When the status code is 2XX, this value is the ID of the cloud player created by this request.
  • When the status code is 409(Conflict), the name of the cloud player created by this request is duplicate with the name of other existing players in the project. This value is the ID of that existing player. Please check and modify the name of the cloud player created by this request.
  • When the status code is another value, this field is null and this request fails.

Response body

If the status code is 2XX, the request succeeds. The response body contains the following fields:

• player: JSON Object. Contains the following fields:
  • uid: Number. The User ID of the cloud player in the channel.
  • account: String. The User Account of the cloud player in the channel.
  • id: String. The ID of the cloud player. It is a UUID (Universally Unique Identifier) generated by Agora's server to identify the ID of the cloud player created.
  • createTs: Number. The Unix timestamp (in seconds) when creating the cloud player.
  • status: String. The state of the cloud player at runtime:
    • "idle": The playback is not started.
    • "connecting": Agora's server is connecting to the address of the media stream or detecting the audio and video data.
    • "running": Playing.
    • "failed": Agora's server cannot connect to the address of the media stream, or the media stream cannot be played.
  • fields: String. The field mask to represent a set of symbolic field paths. The field mask is encoded as a single string where paths are separated by a comma. It specifies a subset of fields that should be returned by this request. In the sample code using uid, fields specifies that Agora's server returns the uid, id, createTs, and status fields. For details, see Google protobuf FieldMask.

If the status code is not 2XX, the request fails. The response body contains the message field, which describes the detailed reason for the failure.

Request example

Media Pull without transcoding

{
    "player": {
    "streamUrl": "rtmp://example.agora.io/live/class32/101",
    "channelName": "class32",
    "token": "2a784467d6",
    "uid": 101,
    "idleTimeout": 300,
    "playTs": 1575508644,
    "name": "test"
    }
}

Media Pull with transcoding

{
    "player": {
        "audioOptions": {
            "profile": 1
        },
        "videoOptions": {
            "width": 1920,
            "height": 1080,
            "frameRate": 15,
            "bitrate": 400,
            "codec": "H.264",
            "gop": 30,
            "fillMode": "fill"
        },
    "streamUrl": "rtmp://example.agora.io/live/class32/101",
    "channelName": "class32",
    "token": "2a784467d6",
    "uid": 101,
    "idleTimeout": 300,
    "playTs": 1575508644,
    "name": "test"
    }
}

Response example

{
    "player": {
        "uid": 101,
        "id": "2a784467d647bb87b60b719f6fa56317",
        "createTs": 1575508644,
        "status": "running"
    },
    "fields": "player.uid,player.id,player.createTs,player.status"
}

Delete API

This API destroys the cloud player in the project.

HTTP request

DELETE https://api.agora.io/{region}/v1/projects/{appId}/cloud-player/players/{id}

Path parameters

• appId: (Required) String. Agora provides the App ID when you create a project in Agora Console. The App ID identifies each project.
• id: (Required) String. The ID of the cloud player.
• region: (Required) String. The region where the Player is created in.

Request header

• Authorization: See Authentication.

• X-Request-ID: UUID (Universally Unique Identifier) to identify this request. After passing in the field, Agora's server returns it in the response header.

  Agora recommends using this field. If you do not pass in any value, Agora's server automatically generates a UUID to pass in.

HTTP response

For all possible response status codes, see Status codes.

Response header

The response header contains the following fields:

• X-Request-ID: UUID (Universally Unique Identifier) to identify this request. It is the same as the X-Request-ID field in the request header. If the request fails, print out this value in the log for troubleshooting.

If you receive the 401(Unauthorized) status code for this request, the response header does not contain the field.

• X-Resource-ID: UUID (Universally Unique Identifier) to identify the ID of the cloud player created by this request. The UUID is the same as the value in the id path parameter.

Response body

• If the status code is 2XX, the request succeeds. The response body is empty.

• If the status code is not 2XX, the request fails. The response body contains the message field, which describes the detailed reason for the failure.

List API

This API queries and lists all the cloud players in the project.

HTTP request

GET https://api.agora.io/v1/projects/{appId}/cloud-player/players

Path parameters

appId: (Required) String. Agora provides the App ID when you create a project in Agora Console. The App ID identifies each project.

Query parameters

A sample request URL when using query parameters:

https://api.agora.io/v1/projects/{appId}/cloud-player/players?filter={filter}&pageSize={pageSize}&pageToken={pageToken}

• filter: (Optional) String. The filter. Agora's server only lists the cloud players that meet the filter criteria in the project. The current filter is the value of channelName when creating the cloud player.

  Assuming the channel name is class32, replace filter={filter} in the sample request URL with filter=channelName eq class32; Assuming the channel name is bigclass, replace filter={filter} in the sample request URL with filter=channelName eq bigclass.

  Spaces exist before and after eq and require URL encoding.

• pageSize: (Optional) Number. The maximum number of cloud players to return on one page. The value ranges from 1 to 500. The default value is 200, which means that for a single page, Agora's server lists up to 200 cloud players if you do not pass in any value.

• pageToken: (Optional) String. The page number to indicate the order of the pages. If you do not pass in any value, Agora's server returns to the first page.

  Recommended usage: When using the List API for the first time, do not pass any value in the pageToken query parameter. You can get the query results of the first page and the value of the nextPageToken field. The next time you use the List API, pass this value in the pageToken query parameter to query the cloud players on the next page.

After using the above parameters, Agora's server queries and lists the cloud players according to the following steps:

1. Query the cloud players that meet the filter criteria in the specified project.
2. Set the space size of each page.
3. List the cloud players in the specified page.

Agora's server lists the cloud players in ascending order by createTs.

Request header

The request header contains the following fields:

• Authorization: See Authentication.

• X-Request-ID: UUID (Universally Unique Identifier) to identify this request. After passing in the field, Agora's server returns it in the response header.

  Agora recommends using this field. If you do not pass in any value, Agora's server automatically generates a UUID to pass in.

HTTP response

For all possible response status codes, see Status codes.

Response header

• X-Request-ID: UUID (Universally Unique Identifier) to identify this request. It is the same as the X-Request-ID field in the request header. If the request fails, print out this value in the log for troubleshooting.

  If you receive the 401(Unauthorized) status code for this request, the response header does not contain the field.

Response body

If the status code is 2XX, the request succeeds. The response body contains the following fields:

• totalSize: Number. The number of cloud players that meet the filter criteria.

• players: JSON Array. Contains the following fields:

  • name: String. The name of the cloud player.
  • streamUrl: String. The RTMP/HTTP/HTTPS URL of the online media stream.
  • channelName: String. The name of the Agora channel.
  • uid: Number. The User ID of the cloud player in the Agora channel.
  • account: String. The User Account of the cloud player in the Agora channel.
  • id: String. UUID (Universally Unique Identifier) to identify the cloud player created. It is the ID of the cloud player.
  • createTs: Number. The Unix timestamp (in seconds) when creating the cloud player.
  • status: String. The state of the cloud player at runtime:
    • "idle": The playback is not started.
    • "connecting": Agora's server is connecting to the address of the media stream or detecting the audio and video data.
    • "running": Playing.
    • "failed": Agora's server cannot connect to the address of the media stream, or the media stream cannot be played.

• fields: String. The field mask to represent a set of symbolic field paths. The field mask is encoded as a single string where paths are separated by a comma. It specifies that Agora's server returns a subset of fields in each player in the players array. In the sample code using uid, fields specifies that Agora's server returns the name, streamUrl, channelName, uid, id, createTs, and status fields in each player in the players array.

• nextPageToken: String. The next page number of pageToken. You can pass the value of the nextPageToken field in the pageToken query parameter when using the List API next time. When nextPageToken is an empty string, there are no more players that match the request.

If the status code is not 2XX, the request fails. The response body contains the message field, which describes the detailed reason for the failure.

Response example

{
    "totalSize": 10,
    "players": [{
        "name": "class32_101",
        "streamUrl": "rtmp://example.agora.io/live/class32/101",
        "channelName": "class32",
        "uid": 101,
        "id": "2a784467d647bb87b60b719f6fa56317",
        "createTs": 1575508644,
        "status": "running"
   }, {
        "name": "class68_422",
        "streamUrl": "rtmp://example.agora.io/live/class68/422",
        "channelName": "class68",
        "uid": 422,
        "id": "0b719f6fa563172a784467d647bb87b6",
        "createTs": 1575588644,
        "status": "connecting"     
   }],
    "fields": "player.name,player.streamUrl,player.channelName,player.uid,player.id,player.createTs,player.status",
    "nextPageToken": "7b60b719f"
}

Rate limits

Do not exceed the API rate limits, otherwise you receive the 429(Too Many Requests) status code.

Status codes

• If the status code is 2XX, the request succeeds.
• If the status code is not 2XX, the request fails. Use the message field in the response body for troubleshooting.

RESTful API callback service

After using these RESTful APIs, Agora's notification server sends the callback notification to your server through HTTP or HTTPS request.
For details, see Message Notification Service.

Considerations

This section summarizes some important considerations when using the Media Pull RESTful API.