Recording SDK Guide

Introduction

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

Recording Architecture

Agora Recording SDK for Linux is integrated on your Linux Server instead of your App:

../../_images/recording_linux_en.png

Hardware Requirement

The following table lists the basic hardware requirements and recommended configurations:

Hardware Requirements
Server

Physical or Virtual

Ubuntu Linux 14.04 LTS 64-bit

Network The Linux Server needs public IP, called ARS IP
Bandwidth

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:

Product Description Number
SUPERMICRO SYS-6017R-TDF

1U rack-mounted SYS-6017R-TDF

Dual Intel® Xeon® E5-2600 Series Processor

1
Case

1U Rackmountable

(440W high-efficiency redundant power supply w/ PMBus)

1
Processor

Intel Xeon E5-2620V2 2.1G, L3:15M, 6C

(P4X-DPE52620V2-SR1AN)

2
Memory

MEM-DR380L-HL06-ER16

(8GB DDR3-1600 2Rx8 1.35v ECC REG RoHS)

1
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.

Compability

This Recording SDK is compatible with the following Native SDKs:

SDK Description
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) [1]

footnotes

[1]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:

../../_images/linux_structure1.png

Where:

  • bin: applite application video_recorder
  • include :the required header files for developing the recording applicaiton
  • libs : the required libraries for developing the recording application
  • samples : one sample code main.cpp and one recording application to launch recording with command line.
  • tools : the transcoding tools ffmeg.zip and video_convert.py

Step 2: Prepare the Environment

  1. Be sure that the following Operating System requirements are satisfied:

    • Ubuntu 12.04 x64 or later
    • CentOS 6.5 x64 or later
  2. Be sure that the following UDP ports are open: 4001 to 4010, 1080, 8000, and 25000 to communicate with the Agora servers.

  3. Be sure that the local ports are not limited by the firewalls.

  4. 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
  5. 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:

File Description
Metadata.txt

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:

<version>1.0</version>

<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. [2]
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. [2]
recording2-done.txt It indicates the recording in this channel is finished

Footnotes

[2](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:

Operating System Player
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

Note

  • 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.