Recording Voice and Video

Recording Voice and Video

Introduction

The Agora Recording SDK for Linux (Recording SDK) supports:

  • Communication and Live Broadcast
  • Recording the voice and video of all users in a channel
  • Recording the voice and video of all users in multiple channels simultaneously
  • Recording the voice of all users in a channel or in multiple channels simultaneously
  • Recording an encrypted channel if the application has integrated Agora built-in encryption

Recording Architecture

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

../_images/recording_linux_en.png

Hardware Requirements

The following table lists the hardware requirements and recommended configurations:

Hardware Requirements
Server

Physical or Virtual

Ubuntu Linux 14.04 LTS 64-bit

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

The recording data transfers through the network, and the bandwidth affects the number of channels that can be recorded simultaneously. Refer to the following criteria: Assume the resolution is 640 x 480 and one user requires 500 kbps.

For a channel with two users, the bandwidth required is 1 MB. If you want to ensure that 100 channels are recording at the same time, then the bandwidth required is 100 MB.

DNS The server allows access to qos.agoralab.co, otherwise the 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

(440 W 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 250 G 3.5 SATA Enterprise (HDD-T0250-WD2503ABYZ) 2

The following assumptions are based on the recommended configuration and one channel with two users:

  • Each channel writes to the disk at the speed of 60 kB/s.
  • Each channel uses 25 MB of memory.
  • The speed in each channel is 900 kbps with each user using 450 kbps, but actual speed depends on the resolution and bitrate of the user’s 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. The CPU is a performance bottleneck.

Compatibility

The Recording SDK is compatible with the following Agora SDKs:

SDK Description
Agora Native SDK The Recording SDK is compatible with the Agora Native SDK v1.7.0 or later for all platforms. If any user in the channel uses Agora SDK v1.6, the whole channel cannot record anything.
Agora Web SDK The Recording SDK is compatible with the Agora Web SDK v1.12.0 or later [1].

footnotes

[1]It is recommended that you use Agora Web SDK v1.12.0 or later.

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 : Required header files for developing the recording applicaiton
  • libs : Required libraries for developing the recording application
  • samples : Sample code main.cpp and one recording application to launch recording with the command line.
  • tools : Transcoding tools ffmeg.tar.gz and video_convert.py

Step 2: Prepare the Environment

  1. Ensure your Linux server meets the following requirements: (Agora recommends that you upgrade your Linux kernal to 2.9.35 or later, which has kernal performance optimization)

    • Ubuntu 12.04 x64 or later
    • CentOS 6.5 x64 or later (Agora recommends CentOS version 7 or later)
  2. Ensure the following UDP ports are open: 4001 to 4030, 1080, 8000, and 25000 to communicate with the Agora servers.

  3. Ensure the local ports are not limited by the firewalls. If there is any port conflict or firewall limitation, it is recommended that you enable 4000 - 41000 as the server receive port and set –lowUdpPort 40000 –highUdpPort 41000 with the command line.

    Note

    Use the command line iptables -L to check the UDP port.

  4. Prepare the following libraries:

    • Put the include folder in the package to your project.
    • Put the 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 ../Product Overview/key.

Step 3: Recording

Select either one of the following methods to start recording:

Both methods implement the same functions. Select one of them according to your needs. The Recording SDK joins the channel like a dummy client, and it must join the same channel as the Agora Native SDK with the same App ID. There are two ways to set the parameter uid:

  • Set as 0, then the system will assign a UID randomly.
  • Set 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 directory with the date is created every day if the recording operation is performed on 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 contains a 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 new Linux 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 voice data for users with UIDs no matter if you record the content at the web client side or native side. Each user writes its own aac file. The file contains voice only related to this specific user.
UID_HHMMSSMS.mp4 Recording files that contain the video data for users with UIDs 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 UIDs 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 Recording in this channel is finished
UID_HHMMSSMS.txt Records when the recording starts and ends, video file information, for example, width/height and rotation

Footnotes

[2](1, 2) When a user exits and rejoins 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 voice files, the format after transcoding is UID_HHMMSSMS.m4a;

  • If the generated recording files include both voice 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 rejoins 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 rejoins the same channel with the interval longer than 15 seconds, which is considered as different sessions, it will generate new voice 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 voice and video recording files into one mp4 file and the script relies on FFmpeg. Ensure the directory where ffmpeg is located is included in PATH. Execute the following command to run the transcoding tool:

Mix Voice and Video of the Same Session

Execute the following command to mix the voice and video file of the same session:

python video_convert.py PATH_TO_RECORDING_FOLDER

Mix Voice and Video of the Same UID

Execute the following command to mix the voice and video file of the same UID:

python video_convert.py session_folder [-m/-am/-vm]

-m: Mix the voice/video files of the same user (UID) as one in chronological order
-am: Mix the voice files of the same user (UID) as one in chronological order
-vm: Mix the video files of the same user (UID) as one in chronological order

The recording file after transcoding supports almost all mainstream players, such as:

Operating System Player
Windows Windows Media Player, KM Player, VLC Player
Mac Mac QuickTime 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 the ChannelName_HHMMSS directory can transcoding start.
  • A convert-done.txt file will be generated after transcoding is finished, which means once the file is available, you do not need to transcode again.
  • A convert.log file will be generated in the same directory of the voice and video files once transcoding is complete by using the transcoding script.

Contact the Agora support 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 other files in your server.

Step 5: Troubleshooting

Under the ChannelName_HHMMSS directory, check the possible failure reasons in recording.log and recording_sys.log for each recording file.