Recording SDK Guide¶
Agora Recording SDK for Linux (Recording SDK for short) supports:
- Communication and Live Broadcast scenario
- Recording audio and video of all participants in a channel
- Recording audio and video of all participants in multiple channels simultaneously
- Recording audio of all participants in a channel or in multiple channels simultaneously
- Recording an encrypted channel if the application has integrated Agora built-in encryption
Agora Recording SDK for Linux is integrated on your Linux Server instead of your App:
The following table lists the basic hardware requirements and recommended configurations:
Physical or Virtual
Ubuntu Linux 14.04 LTS 64-bit
|Network||The Linux Server needs public IP, called ARS IP|
The recording is the data transferring via the network, and the bandwidth affects the number of channels that can be recorded simultaneously. Refer to the following criteria: assuming the resolution is 640x480 and one person requires 500 kbps.
For a channel with two people, the bandwidth needs 1M. If you want to ensure that 100 channels are recording at the same time, then the bandwidth required is 100M.
|DNS||The server allows to access qos.agoralab.co, otherwise SDK cannot report the required statistics.|
The following configuration is recommended:
1U rack-mounted SYS-6017R-TDF
Dual Intel® Xeon® E5-2600 Series Processor
(440W high-efficiency redundant power supply w/ PMBus)
Intel Xeon E5-2620V2 2.1G, L3:15M, 6C
(8GB DDR3-1600 2Rx8 1.35v ECC REG RoHS)
|Hard Disk||250G 3.5 SATA Enterprise (HDD-T0250-WD2503ABYZ)||2|
The following assumptions are based on the recommended configuration and one channel with 2 people:
- Each channel writes to disk at the speed of 60 KB/s.
- Each channel uses 25 MB memory.
- The speed in each channel is 900 Kbps with each person using 450 Kbps, but actual speed depends on the resolution and bitrate of the user device.
- Each CPU can have 9 to 10 channels recording simultaneously. A twelve-core CPU running under a 24-thread machine can have 110 channels running simultaneously. CPU is a performance bottleneck.
This Recording SDK is compatible with the following Native SDKs:
|Agora Native SDK||The Recording SDK is compatible with all-platform Agora Native SDK(v1.7.0 or later) . If any participant in the channel uses v1.6 Agora SDK, the whole channel cannot record anything.|
|Agora Web SDK||The Recording SDK is compatible with Agora Web SDK(v1.12.0 or later) |
|||Currently we only tested based on Agora Web SDK v1.12.0, thus it is recommended that you use Agora Web SDK 1.12.0.|
Step 1: Download the Package¶
Download the latest Agora Recording SDK for Linux package. The package structure is listed as follows:
Step 2: Prepare the Environment¶
Be sure that the following Operating System requirements are satisfied:
- Ubuntu 12.04 x64 or later
- CentOS 6.5 x64 or later
Be sure that the following UDP ports are open: 4001 to 4010, 1080, 8000, and 25000 to communicate with the Agora servers.
Be sure that the local ports are not limited by the firewalls.
Prepare the following libraries:
- Put include folder in the package to your project
- Put lib folder in the package to your project, and ensure that libRecordEngine.a is connected to the project
Prepare a Channel Key or an App ID, refer to Agora Keys User Guide .
Step 3: Recording¶
Select either of the following methods to start recording:
Both methods implement the same functions, select one of them according to your actual needs. The Recording SDK joins the channel like a dumb client, and it must joins the same channel as the Agora Native SDK with the same App ID, but you have two ways to set the parameter uid:
- Set it as 0, then the system will assign a UID randomly
- Set it as a unique User ID different from any of the existing UIDs in the same channel
Step 4: Manage the Recording Files¶
Manage the Recording Files¶
The recordFileRootDir in config specifies the top-level recording directory with the following structure:
- yyyy_mm_dd(Date): A new date directory is created every day if the recording operation is performed that day. All files and directories created on the corresponding date will be stored under this directory.
- ChannelName_HHMMSS: Recording files are stored in the directory created on the same date as the recordings. Each recording file is with channel name, hour, minute, and second timestamp. The timestamp is the time when the server starts recording.
All individual files related to the recording are under the ChannelName_HHMMSS directory:
A text file that contains metadata about the recording. The metadata includes a number of text fields with each field separated by a Linux new line. The text lines consist of the following value pairs:
<channel name>xxxx</channel name>
<error status> <status> No error status implemented yet
|UID_HHMMSSMS.aac||Recording files that contain the audio data for users with UID no matter you record the content at the web client side or native side. Each user writes its own aac file. The file contains audio only related to this specific user.|
|UID_HHMMSSMS.mp4||Recording files that contain the video data for users with UID when you record the content at the native client side. Each user writes its own mp4 file. The file contains video only related to this specific user. |
|UID_HHMMSSMS.webm||Recording files that contain the video data for users with UID when you record the content at the web client side. Each user writes its own mp4 file. The file contains video only related to this specific user. |
|recording2-done.txt||It indicates the recording in this channel is finished|
|||(1, 2) Whenever the user exits and re-joins the same channel, a new and separate mp4 file is generated for the user.|
Play the Recording Files¶
The transcoding tool is required to transcode the recorded files:
If the generated recording files are all audio files, the format after transcoding is UID_HHMMSSMS.m4a ;
If the generated recording files include both audio and video files, the format after transcoding is UID_HHMMSSMS_av.mp4 which is generated based on “one session, one file”:
- If the UID exits and re-joins the same channel with the interval shorter than 15 seconds, which is considered as one session. It will generate new video files and be merged as one UID_HHMMSSMS_av.mp4 file together with the previsouly generated files in the session.
- If the UID exits and re-joins the same channel with the interval longer than 15 seconds, which is considered as different sessions. It will generate new audio and video files which will be merged as one UID_HHMMSSMS_av.mp4 for the new session;
The transcoding tool includes video_convert.py and ffmpeg . The python script can merge the separated audio and video recording files into one mp4 file and the script relies on ffmpeg. Be sure that the directory where ffmpeg is located is included in PATH. Execute the following command to run the transcoding tool:
python video_convert.py PATH_TO_RECORDING_FOLDER
The recording file after the transcoding supports almost all the mainstream players, for example:
|Windows||Windows Media Player, KM Player, VLC Player|
|Mac||Mac Quick Time Player, Movist, MPlayerX, KMPlayer|
|iOS||iOS Default Player, VLC, KMPlayer|
|Android||Android Default Player, MXPlayer, VLC for Android, KMPlayer|
- Only when a recording2-done.txt file is generated under ChannelName_HHMMSS directory can the transcoding start.
- A convert-done.txt file will be generated after the transcoding is finished, which means once the file is available, you do not need to do the transcoding again.
Contact the support team for any transcoding failure.
Secure the Recording File¶
The recording file is stored only in your server, and Agora cannot access it. Deploy the recording services yourself or consult security experts. Secure the file just as you do the other files in your server.
Step 5: Troubleshooting¶
Under the ChannelName_HHMMSS directory, check the possible failure reasons in recording.log for each recording file.