Agora Cloud Recording Overview
Agora Cloud Recording is based on the RESTful API. It is configured with API calls in Bubble.
Prerequisites
Create an account with Agora.IO
You must have an account with Agora.IO to interact with the API. Create your development account at: https://docs.agora.io/en
How to find the Agora Console
Where to create a project or find settings for existing projects?
How to setup cloud recording for streaming
To use the recording functionality, you need an Agora account and a storage account (for example, Amazon S3). Here is the guide that will help you set up the Agora cloud recording for your app:
You need to create or use an existing Agora application
How to create a new project?
If you want to create a new project, use the "Create" button. This button can be found on the Projects page of the Agora Console.
How to use an existing project?
If you want to use an existing project, use the "Config" button. This button can be found in the row with the corresponding project.
Enable cloud recording
- Go to the project settings ("Config" button).
- Find "Cloud Recording" in Extensions.
- Press "Enable" button for Cloud Recording
Enable App Certificate
Scroll to the top and find "Primary Certificate" block
Enable it using the toggle
And confirm action
Copy the App ID and Certificate into the plugin settings
Place App ID and Certificate to the corresponding fields in the plugin tab of your app
Get Authorization header
To use Agora's RESTful API you need to get a Customer ID and Customer Secret
Go to RESTful API page.
Use "Add a secret" button
Download Customer Secret
Open downloaded file with any text editor
Now using Customer Key and Customer Secret we can generate Authorization header
These credentials (Customer Key and Secret) must be base64 encoded using the following formula:
customerKey:customerSecret - (https://www.base64encode.org/ here you can do it).Take the resulting code and paste it into the plugin field for authorization with the word “
Basic ” Example:
Basic NTM0YzU0ZWU0M2MxNDMyNGJkZqa2YjhhMzVlNGI4YmY6MWJhOTc2MGM4MDYyNGRhNWIyOWMzOGVkZGVhOMmU1
Setup Cloud Recording in your Bubble App
On page load create 2 states for Room Name and Unique ID.
Now, create button. This button will be used to start cloud recording.
And setup it workflow:
1) Need to generate token for recording. Use plugin action "Generate recording token".
2) Use API Call named "Get resource ID"
You can find detailed description of action "Get resource ID" in Common API Calls part of this document
3) Store resourceId returned by "Get resource ID" in state
4) Use API Call "Start stream cloud recording" to start cloud recording.
You can find detailed description of action "Start stream cloud recording" in Streaming API Calls part of this document
5) Save returned by "Start stream cloud recording" sid in state
Add another button. This button will be used to stop cloud recording.
Setup workflow of this button:
1) Use API Call "Stop stream cloud recording" to stop recording
You can find detailed description of action "Stop stream cloud recording" in Streaming API Calls part of this document
Full setup of stream cloud recording you can see on our demo page.
How to set up cloud recording for a conference
You need to create or use an existing Agora application
How to create a new project?
If you want to create a new project, use the "Create" button. This button can be found on the Projects page of the Agora Console.
How to use an existing project?
If you want to use an existing project, use the "Config" button. This button can be found in the row with the corresponding project.
Enable cloud recording
- Go to the project settings ("Config" button).
- Find "Cloud Recording" in Extensions.
- Press "Enable" button for Cloud Recording
Copy the App ID into the plugin settings
Place App ID in the plugin tab of your app
Setup cloud recording in your Bubble App
Place the button on the page. Clicking this button recording will be started.
And setup it workflow:
1) Create state with unique id generation
2) Generate *resourceId *using API Call "Get resource ID"
You can find detailed description of action "Get resource ID" in Common API Calls part of this document
3) Start recording using API Call "Start composite cloud recording"
You can find detailed description of action "Start composite cloud recording" in Conference API Calls part of this document
4) Store in states resourceId and sid
Add another button to the page. This button will be used to stop cloud recording.
And setup it workflow:
1) Use API Call "Stop composite cloud recording"
You can find detailed description of action "Stop composite cloud recording" in Conference API Calls part of this document
Full setup of conference cloud recording can be seen on our demo page: https://zeroqode-demo-19.bubbleapps.io/agora_rtc_streaming . This functionality is disabled on the Demo, however, you can check the setup in the Editor.
Common API Сalls
Common API Calls is used for both conference and streaming recordings
Get resource ID
Title | Description |
appid | Your App ID |
unicID | A string that contains the UID of the recording client, for example "527841". |
resourceExpiredHour | Time limit (in hours) for the Cloud Recording RESTful API calls. It must be between 1 and 720 |
channel_name | Set the name of the channel to be recorded |
Returned value:
resourceId - String. The resource ID for cloud recording. The resource ID is valid for five minutes.
Query status
Query status method works only with an ongoing recording session. If you call query after a recording ends or after, it starts with an error, you get a 404 (Not Found) error.
Title | Description |
appID | Your App ID |
resourceID | The resource ID is returned by the Get resource ID method. |
sID | The recording ID created by the Start composite cloud recording or one of Start stream cloud recording methods. |
mode | The recording mode. Supports individual mode ( individual) or composite mode (mix).individual - is used for stream (individual) recording
mix- is used for conferece (composite) recording |
Returned values:
resourceId- String. The resource ID for cloud recording. The resource ID is valid for five minutes.
sid- String. The recording ID. The unique identification of the current recording.
serverResponse status- Number. The status of the cloud service.
serverResponse fileList- WhenfileListModeis "string",fileListis a string that represents the filename of the M3U8 file. WhenfileListModeis "json",fileListis a JSONArray that contains the details of each recorded file.
serverResponse fileListMode- String. The data type offileList
serverResponse sliceStartTime- Number. The Unix time (ms) when the recording starts.
serverResponse status** codes and descriptions:**0: The cloud service has not started.
1: The initialization is complete.
2: The cloud service is starting.
3: The cloud service is partially ready.
4: The cloud service is ready.
5: The cloud service is in progress.
6: The cloud service receives the request to stop.
7: The cloud service stops.
8: The cloud service exits.
20: The cloud service exits abnormally.
Streaming API Calls
Individual Recording - Records the audio and video of each user ID in separate files and uploads the recorded files to a third-party cloud storage service.
Start stream cloud recording
Start audio and video recording in a channel
Title | Description |
appID | Your App ID |
resourceID | The resource ID returned by the Get resource ID method |
channel_name | Set the name of the channel to be recorded |
token | String. The dinamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application. |
storage_accessKey | String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key. |
storage_region | Number. The region information is specified for the third-party cloud storage. The recording service only supports regions in the following lists:-unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type- |
storage_bucket | String. The bucket name of the third-party cloud storage. |
storage_secretKey | String. The secret key of the third-party cloud storage. |
Directory_1 | Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", Agora Cloud Recording will add the prefix "directory1/" before the name of the recorded file, that is, directory1/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z |
- The 26 uppercase English letters: A to Z
- The 10 numbers: 0 to 9 |
- 1: Amazon S3
- 6: Google Cloud
- 7: Huawei Cloud
- 8: Baidu AI Cloud |
| unicID | A string containing the user ID of the recording client. Must be the same uid used in the
Get resource ID method. |
| Directory_2 | Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", and Directory_2 = "directory2", Agora Cloud Recording will add the prefix "directory1/directory2/" before the name of the recorded file, that is, directory1/directory2/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z- The 26 uppercase English letters: A to Z
- The 10 numbers: 0 to 9 |
Returned values:
resourceId- String. The resource ID for cloud recording.
sid- String. The recording ID. The unique identification of the current recording.
Start stream cloud recording (video only)
Start video recording in a channel
Title | Description |
appID | Your App ID |
resourceID | The resource ID returned by the Get resource ID method |
channel_name | Set the name of the channel to be recorded |
token | String. The dinamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application. |
storage_accessKey | String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key. |
storage_region | Number. The region information specified for the third-party cloud storage. The recording service only supports regions in the following lists:-unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type- |
storage_bucket | String. The bucket name of the third-party cloud storage. |
storage_secretKey | String. The secret key of the third-party cloud storage. |
Directory_1 | Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", Agora Cloud Recording will add the prefix "directory1/" before the name of the recorded file, that is, directory1/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z |
- The 26 uppercase English letters: A to Z
- The 10 numbers: 0 to 9 |
- 1: Amazon S3
- 6: Google Cloud
- 7: Huawei Cloud
- 8: Baidu AI Cloud |
| unicID | A string containing the user ID of the recording client. Must be the same uid used in the
Get resource ID method. |Returned values:
resourceId- String. The resource ID for cloud recording.
sid- String. The recording ID. The unique identification of the current recording.
Start stream cloud recording (audio only)
Start audio recording in a channel
Title | Description |
appID | Your App ID |
resourceID | The resource ID returned by the Get resource ID method |
channel_name | Set the name of the channel to be recorded |
token | String. The dinamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application. |
storage_accessKey | String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key. |
storage_region | Number. The region information specified for the third-party cloud storage. The recording service only supports regions in the following lists:-unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type- |
storage_bucket | String. The bucket name of the third-party cloud storage. |
storage_secretKey | String. The secret key of the third-party cloud storage. |
Directory_1 | Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", Agora Cloud Recording will add the prefix "directory1/" before the name of the recorded file, that is, directory1/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z |
- The 26 uppercase English letters: A to Z
- The 10 numbers: 0 to 9 |
- 1: Amazon S3
- 6: Google Cloud
- 7: Huawei Cloud
- 8: Baidu AI Cloud |
| unicID | A string containing the user ID of the recording client. Must be the same uid used in the
Get resource ID method. |
Returned values:
resourceId- String. The resource ID for cloud recording.
sid- String. The recording ID. The unique identification of the current recording.
Stop stream cloud recording
Stop recording on the channel
Title | Description |
appID | Your App ID |
resourceID | The resource ID returned by the Get resource ID method. |
sID | The recording ID created by the start method. |
unicID | A string that contains the user ID of the recording client. Must be the same uid used in the Get resource ID method. |
channel_name | Name of the channel to be recorded. |
resourceId- String. The resource ID for cloud recording.
sid- String. The recording ID. The unique identification of the current recording.
Conference API Calls
Composite recording - Records the audio and video of multiple user IDs in a single file and uploads the recorded file to a third-party cloud storage service.
Start composite cloud recording
Title | Description |
appID | Your App ID |
resourceID | The resource ID returned by the Get resource ID method |
channel_name | Set the name of the channel to be recorded |
token | String. The dynamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application. |
storage_accessKey | String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key. |
storage_region | Number. The region information is specified for the third-party cloud storage. The recording service only supports regions in the following lists:-unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type- |
storage_bucket | String. The bucket name of the third-party cloud storage. |
storage_secretKey | String. The secret key of the third-party cloud storage. |
Directory_1 | Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", Agora Cloud Recording will add the prefix "directory1/" before the name of the recorded file, that is, directory1/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z |
- The 26 uppercase English letters: A to Z
- The 10 numbers: 0 to 9 |
- 1: Amazon S3
- 6: Google Cloud
- 7: Huawei Cloud
- 8: Baidu AI Cloud |
| unicID | A string containing the user ID of the recording client. Must be the same uid used in the
Get resource ID method. |
| Directory_1 | Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", and Directory_2 = "directory2", Agora Cloud Recording will add the prefix "directory1/directory2/" before the name of the recorded file, that is, directory1/directory2/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z- The 26 uppercase English letters: A to Z
- The 10 numbers: 0 to 9 |
Returned values:
resourceId- String. The resource ID for cloud recording.
sid- String. The recording ID. The unique identification of the current recording.
Stop composite cloud recording
Title | Description |
appID | Your App ID |
resourceID | The resource ID is returned by the Get resource ID method. |
sID | The recording ID is created by the start method. |
unicID | A string that contains the user ID of the recording client. Must be the same uid used in the Get resource ID method. |
channel_name | Name of the channel to be recorded. |
resourceId- String. The resource ID for cloud recording.
sid- String. The recording ID. The unique identification of the current recording.
serverResponse fileListMode- String. The data type offileList
serverResponse fileList- WhenfileListModeis "string",fileListis a string that represents the filename of the M3U8 file. WhenfileListModeis "json",fileListis a list that contains the details of each recorded file.
serverResponse uploadingStatusString. The upload status.- "
uploaded": All the recorded files are uploaded to the third-party cloud storage. - "
backuped": Some of the recorded files fail to upload to the third-party cloud storage and upload to Agora Cloud Backup instead. Agora Cloud Backup automatically uploads these files to your cloud storage. - "
unknow": Unknown status.