Basic: Enabling Recording

Basic: Enabling Recording

This page demonstrates how to enable recording with the Agora Recording SDK for Linux.

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 internet and the bandwidth is directly related to the number of channels recording simultaneously. Assume the resolution is 640 x 480 and one user requires 500 kbps. A channel with two users should have a bandwidth of no less than 1 MB. The minimum bandwidth is 100 MB when 100 channels are recording at the same time
DNS the SDK may fail to report necessary data if the access to qos.agoralab.co is not granted to the server

Agora recommends the following configurations:

Product Description Number
SUPERMICRO SYS-6017R-TDF 1U rack-mounted SYS-6017R-TDF 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.1 G, L3:15M, 6C (P4X-DPE52620V2-SR1AN) 2
Memory MEM-DR380L-HL06-ER16 (8-GB DDR3-1600 2Rx8 1.35-V 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 a 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 the actual speed depends on the resolution and bitrate of the user’s device.
  • Each CPU can have 9 to 10 channels recording simultaneously. A 12-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
The 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
The Agora Web SDK The Recording SDK is compatible with the Agora Web SDK v1.12.0 or later [1]

Footnote

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

Step 1: Download the Package

  1. Ensure that you have compiled the sample code for your communication or live broadcast project.

  2. Download the Agora Recording SDK for Linux package. The package structure is listed as follows:

    ../_images/linux_structure.png

Where

Folder Description
bin The recording application
include
  • base: Required header files for developing the recording application
  • IAgoraLinuxSdkCommon.h: Public structure and enumeration
  • IAgoraRecordingEngine.h: Interface of the recording engine and its config information
libs Required libraries for developing the recording application
samples

Sample code

  • agorasdk: Demo that implements the C++ interface and callbacks
  • base: Public sample code
  • cpp: C++ sample code
    • release/bin/recorder: Parent process that can be run
  • java: Java sample code
    • native: Native code
    • native/jni: JNI delegate
Tools Transcoding tools
  1. Ensure that your Linux server meets the following requirements: (Agora recommends using Linux kernel 2.9.35 or later with kernel 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 to 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.

6.Ensure that your compiler is later than gcc 4.4.

  1. Prepare the following libraries:
    • Put the include folder in the package of your project.
    • Put the lib folder in the package of your project, and ensure that libRecordEngine.a is connected to the project.
  2. Prepare a Channel Key or an App ID, refer to Getting an App ID.

Step 2: Compile the Sample Code

Run the following command under the samples/cpp directory to compile the sample code:

make

After the compilation, a record_local application is generated in the directory.

Step 3: Enable Recording

This part shows how to enable recording command line. See Recording API if you prefer starting recording by using the API methods.

Run ./record_local to check the related usage, for example,

./recorder_local --appId STRING --uid UINTEGER32 --channel STRING --appliteDir STRING --channelKey STRING --channelProfile UINTEGER32 --isAudioOnly --isVideoOnly --isMixingEnabled --mixResolution STRING --mixedVideoAudio --decryptionMode STRING --secret STRING --idle INTEGER32 --recordFileRootDir STRING --lowUdpPort INTEGER32 --highUdpPort INTEGER32 --getAudioFrame UINTEGER32 --getVideoFrame UINTEGER32 --captureInterval INTEGER32 --cfgFilePath STRING --streamType UINTEGER32 --triggerMode INTEGER32
                   --appId     (App ID/must)
                   --uid     (User ID default is 0/must)
                   --channel     (Channel ID/must)
                   --appliteDir     (Directory of applite 'AgoraCoreService', Must point to 'Agora_Recording_SDK_for_Linux_FULL/bin/' folder/must)
                   --channelKey     (channelKey/option)
                   --channelProfile     (channel_profile:(0:COMMUNICATION),(1:broadcast) default is 0/option)
                   --isAudioOnly     (Default 0:A/V, 1:AudioOnly (0:1)/option)
                   --isVideoOnly     (Default 0:A/V, 1:VideoOnly (0:1)/option)
                   --isMixingEnabled     (Mixing Enable? (0:1)/option)
                   --mixResolution     (Change the default resolution for the video mix mode/option)
                   --mixedVideoAudio     (mixVideoAudio:(0:separated Audio,Video) (1:mixed Audio & Video), default is 0 /option)
                   --decryptionMode     (Decryption Mode, default is NULL/option)
                   --secret     (Input secret when enable decryption Mode/option)
                   --idle     (Default 300 s, should be above 3 s/option)
                   --recordFileRootDir     (Recording file root dir/option)
                   --lowUdpPort     (Default is a random value/option)
                   --highUdpPort     (Default is a random value/option)
                   --getAudioFrame     (Default 0 (0:save as file, 1:aac frame, 2:pcm frame, 3:mixed pcm frame) (Cannot combine with isMixingEnabled) /option)
                   --getVideoFrame     (Default 0 (0:save as file, 1:h.264, 2:yuv, 3.jpg buffer, 4,jpg file, 5:jpg file and video file) (Cannot combine with isMixingEnabled) /option)
                   --captureInterval     (Default 5 (Video snapshot interval (second)))
                   --cfgFilePath     (Config file path / option)
                   --streamType     (Remote video stream type(0:STREAM_HIGH,1:STREAM_LOW), default is 0/option)
                   --triggerMode     (TriggerMode:(0: automatically mode, 1: manually mode) default is 0/option)
Parameter Mandatory Description
appID Yes App ID. See Getting an App ID
uid Yes User ID: A 32-bit unsigned integer ranging from 1 to (2^32-1), that is different from any other ID
channel Yes Name of the channel: A string within 64 bytes that works as the only identifier of the channel
appliteDir Yes Sets the directory to store the Linux SDK built-in applite application
channelKey Optional
  • For low-security requirements, set it as NULL
  • For high-security requirements, set it as the Channel Key. If an App Certificate is enabled, use a Channel Key. For details, refer to Security Keys
channelProfile Optional

Sets the channel mode:

  • CHANNEL_PROFILE_COMMUNICATION: Communication (default) mode, including one-to-one and group chat where any user in the channel can talk
  • CHANNEL_PROFILE_LIVE_BROADCAST: Live broadcast mode with two roles - host and viewer (enabled by calling setClientRole)
isAudioOnly [2] Optional

Sets whether to record voice only:

  • true: Enable voice recording only
  • false: Record both voice and video (default)
isVideoOnly [2] Optional

Sets whether to record video only:

  • true: Enable video recording only
  • false: Record both voice and video (default)
mixResolution [3] Optional If video mixing mode is enabled, this parameter sets the resolution in the format of width, high, fps, and kbps; corresponding to the width, height, frame rate, and bitrate of the video stream
isMixingEnabled Optional

Sets whether to enable audio-mixing or/and video-mixing mode. The parameters are disabled by default:

  • If isAudioOnly is true (false by default) and isVideoOnly is false, this parameter sets to record audio only;
  • If both isAudioOnly and isVideoOnly are false, this parameter sets to enable voice mixing and video mixing, that is, to record respecrtively the audio and video of all uids; if mixedVideoAudio is enabled, the audio file and video file will be merged into an audio-video file;
  • If both isVideoOnly and isVideoOnly are true, this parameter sets to record video only
decryptionMode Optional

When the whole channel is encrypted, the recording SDK uses this parameter to enable the built-in decryption function:

  • “aes-128-xts”: AES-128, XTS mode
  • “aes-128-ecb”: AES-128, ECB mode
  • “aes-256-xts”: AES-256, XTS mode
secret Optional The decryption password when decryption mode is enabled
mixedVideoAudio Optional

If isMixingEnabled set as true, this parameter allows mixing voice and video in real time:

  • false: Mix voice and video respectively (default)
  • true: Mix voice and video in real time into an mp4 file. See the table below for supporting players
idle [4] Optional If the user calls leaveChannel() to stop recording, then the recording file ends with a period of silence which is decided by the value set by this parameter. The value must be no less than three seconds, and the default value is 300 seconds.
captureInterval Optional The time interval for screen capture that ranges from one to five seconds. Need to be used with decodeVideo = 3/4 when joining the channel. See details at Joining a Channel (joinChannel).
streamType Optional This parameter takes effect only when the Agora Native SDK has enabled the dual-stream mode (high stream by default)
triggerMode Optional

Choose to record automatically or manually upon joining the channel. If you want to call startSerivce and stopService, choose manually.

  • 0: automatically
  • 1: manually
appliteDir Optional Sets the directory to store the Linux SDK built-in applite application.
recordFileRootDir [5] Optional Sets the root directory to store the recording files.
cfgFilePath [5] Optional Sets the path of the configuration file. In this configuration file, the absolute path of the recording file can be set, and the content in the configuration file must be in Json format. For example, {“Recording_Dir” :”<recording path>”}, where Recording_Dir is fixed.
lowUdpPort [6] Optional Sets the lowest UDP port.
highUdpPort [6] Optional Sets the highest UDP port.
getAudioFrame [6] Optional
  • AUDIO_FORMAT_DEFAULT_TYPE = 0: default audio format
  • AUDIO_FORMAT_AAC_FRAME_TYPE = 1: AAC format
  • AUDIO_FORMAT_PCM_FRAME_TYPE = 2: PCM format
  • AUDIO_FORMAT_MIXED_PCM_FRAME_TYPE = 3: PCM audio-mixing format
getVideoFrame [7] Optional
  • VIDEO_FORMAT_DEFAULT_TYPE = 0: default video format
  • VIDEO_FORMAT_H264_FRAME_TYPE = 1: H.264 format
  • VIDEO_FORMAT_YUV_FRAME_TYPE = 2: YUV format
  • VIDEO_FORMAT_JPG_FRAME_TYPE = 3: JPG format
  • VIDEO_FORMAT_JPG_FILE_TYPE = 4: JPG file format
  • VIDEO_FORMAT_JPG_VIDEO_FILE_TYPE = 5: JPG + video file format

Footnote

[2](1, 2) Parameters isAudioOnly and isVideoOnly are disabled by default, and do not set isAudioOnly and isVideoOnly as true at the same time.
[3]For recommended mixed resolutions, see the table below.
[4]Parameter idleLimitSec is 300 seconds by default. Set this value to no less than three seconds.
[5](1, 2) Do not set recordFileRootDir and cfgFilePath at the same time.
[6](1, 2, 3) Make sure that all ports are positive integers, and the value of highUdpPort - lowUdpPort be no less than 4.
[7]Once raw data is enabled, video mixing is not supported. The web currently supports raw voice data but not video.

Supporting Players for the Recorded Files

Operation System Players
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

Either the command line or API implements the same function, and you can choose either one according to your actual needs. The recording SDK joins the channel as a dumb client and shares the same channel and app ID with the Agora Native SDK. There are two ways for setting the UID:

  • Set as 0, and the system assigns a uid automatically
  • Set as a unique ID that is different from any other UID in the channel

After the recording is complete, use the transcoding script to merge the recorded file. For how to use the transcoding script, see Using the Transcoding Script. If error or warning occurs during the recording, see Error Reported Callback (onError) and Warning Reported Callback (onWarning) for detailed information.