Agora.io recently launched the Cloud Recording API to make it easier for developers using Agora SDK’s to enable recording within their apps.
Agora.io recently launched the Cloud Recording API to make it easier for developers using Agora SDK’s to enable recording within their apps.
The goal of this QuickStart guide is to walk through all the setup steps for enabling Cloud Recording via the Agora.io Dashboard as well as review all API endpoints and configuration options available.
Pre-Requisites
An Agora Developer Account — Sign up here
An app (native or web) that has the Agora.io SDK embedded
- sample web apps: live streaming or communication
An Amazon S3 bucket, Alibaba Cloud OSS, or Qiniu Cloud Kodo
- Agora does not handle storage of the recordings
Postman API client installed and a basic understanding of how to use it
Once you have registered for an Agora.io account and have created a new project, make sure to note the AppID for later.
Also make sure to take note of your Cloud Storage credentials, specificallyBucket name, AccessKey, and SecretKey, as you’ll need them to let Agora’s Cloud Recording service know where to write the audio and video files from your recordings.
Getting Started
To enable Cloud Recording on your project, you’ll need to click into the Products Usage section of the Agora.io Dashboard and select the Project name from the drop-down in the upper left-hand corner, click the Duration link below Cloud Recording.
After you click Enable Cloud Recording, you will be prompted to confirm the concurrent channels settings which defaults to 50, but you can contact sales@agora.io if you need more.
Now that you have your AppID and Cloud Recording is enabled on your project, the only other credentials you need are your CustomerID and CustomerCertificate. Both are accessible by clicking your name in the upper right-hand corner and selecting RESTful API from the drop-down menu.
Testing the API
To do the initial testing of the Agora Cloud Recording API I be using Postman. Agora offers a Postman Collection which allows you to easily import the endpoints into your project.
Use the Run in Postman button in the upper right-hand corner to open the Agora Collection within the Postman API Client.
After opening the collection in Postman, set up your environment and environment variables.
The Agora Collection uses the following environment variables:
- APPID
- CustomerID
- CustomerCertificate
- resourceId
- AccessChannel
- RecordingUID
- StorageVendor
- StorageRegion
- Bucket
- AccessKey
- SecretKey
- sid
For each of the variables, use the credentials we collected earlier in the guide. It’s important to setup resourceId and sid as variables, but don’t worry about setting their values because they are automatically populated using the response from calling the acquire and start endpoints (respectively).
Before we can begin recording we need to make sure we have an active channel and stream. I will use the Group Chat Web App that I built in a previous blog post, you’re more than welcome to use it too, there’s a Github hosted demo.
Once your environment with variables are set up and your live stream running, use the acquire endpoint to get your resourceId
Note the resourceId is akin to a token in the sense that it has a lifetime of 5 minutes, afterwards it expires and you have to call acquire for a new resourceId
Now that you have your resourceID, you can call the start endpoint to begin recording and stop endpoint to end recording.
There are two endpoints (query and adjustLayout) that can be called during a call; query acceptsGET requests and allows you to get stats and info about the recording; adjustLayout accepts POST requests allows you to change the layout configuration of the recording.
For a full explanation of each endpoint and the configuration settings available, please take a look at the official API reference.
Considerations
Call acquire to get a resourceID before calling start.
Use one resourceID for only one start request.
Do not call query after calling stop.
Recording stops in the following situations:
When you call stop.
When no user is in the channel for the idle time (30 seconds by default).
When the asynchronous parameter check finds errors. This means that some parameters of transcodingConfig or storageConfig in the start request are invalid.
Common errors
Calling endpoints with sequence: acquire ➡ start ➡ start
— Repeating the start request with the same resourceID returns the HTTP 201 status code and error code: 7
Calling endpoints with sequence: acquire ➡ start ➡ acquire ➡ start
— Repeating the acquire ➡ start requests with the same parameters returns the `HTTP 400` status code and error `code: 53`
Calling endpoints with sequence: acquire ➡ start ➡ stop query.
— Calling stop together with query affects the response of stop and produces an HTTP 206 status code and the response does not have the fileList field.
Calling endpoints with sequence: acquire ➡ start ➡ Recording stops ➡ query
— Calling query after the recording stops returns the HTTP 404 status code and error code: 404
Create Stronger Connection & Collaboration
