Record a Call

Last updated 2020/04/29 16:45:34

This page demonstrates how to record a call by using the command line. You can also record calls by calling the API methods, see Record by API. The command line and API methods implement the same recording functions.

Ensure that you integrate the On-premise Recording SDK before proceeding, see Integrate the SDK.

The On-premise Recording SDK joining a channel is equivalent to a dummy client joining a channel. The On-premise Recording SDK needs to join the same channel and use the same App ID and channel profile as the Agora Native/Web SDK.

Compile the sample code

Open a command-line tool and run the following command to compile the sample code under the samples/cpp directory.

make

After the compilation, an executable record_local file is generated in this directory as shown in the following figure.

Start recording

Open a command-line tool and run the following command under the samples/cpp directory.

./recorder_local --appId <your App ID> --channel <channel name> --uid 0 --channelProfile <0 Communication, 1 Live broadcast> --appliteDir Agora_Recording_SDK_for_Linux_FULL/bin

appId, channel, and channelProfile must be the same as the Agora Native/Web SDK.
appliteDir must be the path to the AgoraCoreService file.

Set recording options

Apart from the parameters in the above example, the demo provides other parameters and options. Run ./recorder_local to view all the parameters and options.

The appId, uid, channel, and appliteDir parameters are mandatory to start a recording. Other parameters can be set as needed.

Mandatory parameters

appId: The App ID must be the same as that of the Agora RTC SDK. For details, see Getting an App ID.
uid: User ID. A 32-bit unsigned integer ranging from 1 to (2³²-1) that is unique in a channel. If the user ID is set as 0, the SDK assigns a user ID.
channel: Name of the channel to be recorded.
appliteDir: The directory of AgoraCoreServices. The default path for AgoraCoreServices in the SDK package is: Agora_Recording_SDK_for_Linux_FULL/bin/.

The following parameters are not mandatory, but they depend on the settings of the recording channel.

channelKey: The dynamic key used in the channel to be recorded. Ensure that you set this parameter if the recording channel uses a token.
channelProfile: Sets the channel profile. The On-premise Recording SDK must use the same channel profile as the Agora RTC SDK. Otherwise, issues may occur.
- 0: (Default) The communication profile.
- 1: The LiveBroadcasting profile.
decryptionMode: When the whole channel is encrypted, the On-premise Recording SDK uses decryptionMode to enable the built-in decryption function. The decryption mode must be the same as the encryption mode set by the Native/Web SDK.
secret: The decryption password when decryption mode is enabled.

Range of ports

We recommend that you specify the range of ports for the recording processes. Configure a large range for all recording processes (Agora recommends 40000 to 41000 or larger). If so, the On-premise Recording SDK assigns ports to each recording process within the specified range and avoids port conflicts automatically.

If the lowUdpPort and highUdpPort parameters are not specified, the ports used by the recording processes are at random, which may cause port conflicts.

lowUdpPort: Sets the lowest UDP port. Ensure that the value of highUdpPort - lowUdpPort is greater than 6. The default value is 0.
highUdpPort: Sets the highest UDP port. Ensure that the value of highUdpPort - lowUdpPort is greater than 6. The default value is 0.

Recording session control

triggerMode: Sets whether to start recording automatically or manually.
- 0: Automatically. The recording SDK automatically starts recording when joining a channel and stops recording when leaving a channel.
- 1: Manually. Start and stop recording by commands. See FAQ for details.
idle: The Agora On-premise Recording SDK automatically stops recording when the recording channel is idle after a time period set by this parameter. The value must be greater than three seconds. The default value is 300 seconds.

The idle time is also charged as usage. A channel is idle in the following situations:
- In a communication channel, no user of the Native SDK is in the channel, and no user of the Web SDK publishes a stream.
- In a live-broadcast channel, no host is in the channel.

Selective recording

isAudioOnly: Sets whether or not to record audio only.
- 0: (Default) Enables both audio and video recording.
- 1: Enables audio recording and disables video recording.
isVideoOnly: Sets whether or not to record video only.
- 0: (Default) Enables both audio and video recording.
- 1: Enables video recording and disables audio recording.
streamType: Sets the type of stream to be recorded. Takes effect only when the recording channel enables the dual-stream mode.
- 0: (Default) Record the high-video stream.
- 1: Record the low-video stream.

isAudioOnly and is VideoOnly cannot be set to 1 at the same time.

autoSubscribe：Sets whether to record the streams of all users or specified users:
- 0: Record the streams of specified users. If you set autoSubscribe as false, you should set subscribeVideoUids or subscribeAudioUids to specify users whose video or audio you want to record.
- 1: (Default) Record the streams of all users.
subscribeVideoUids：Record the vedio streams of specified users. It only takes effect when autoSubscribe is 0. Fill in the user ID of the user who needs to record the video, separated by commas and don’t add spaces. For example --subscribeVideoUids 123,456,789.
subscribeAudioUids：Record the audio streams of specified users. It only takes effect when autoSubscribe is 0. Fill in the user ID of the user who needs to record the audio, separated by commas and don’t add spaces. For example --subscribeAudioUids 123,456,789.

Recording format

getAudioFrame: Sets the recording audio format. Do not set isMixingEnabled as 1 when this parameter is set as 1, 2, or 3.
- 0: Default audio format.
- 1: Audio frame in AAC format.
- 2: Audio frame in PCM format.
- 3: Audio-mixing frame in PCM format.
  
  You can set the sample rate for recording original audio data in PCM format (getAudioFrame is 2 or 3). Set the path of the configuration file in the cfgFilePath parameter. The content in the configuration file must be in JSON format, such as: {"Pcm_Sample_Rate":16000}.
  Pcm_Sample_Rate can be set to 8000Hz, 16000Hz, 32000Hz. If the sample rate you set is not within the above range, the configuration does not take effect.
getVideoFrame: Sets the recording video format. Do not set isMixingEnabled as 1 when this parameter is set as 1, 2, 3, or 4.
- 0: Default video format.
- 1: Video frame in H.264 format.
- 2: Video frame in YUV format.
- 3: Video frame in JPEG format.
- 4: Screenshots in JPEG format.
- 5: Screenshots in JPEG format + MP4 video files.
  - Individual Mode (isMixingEnabled is 0): One MP4 video file and multiple JPEG screenshots for each user.
  - Composite Mode (isMixingEnabled is 1): One MP4 video file for all the users.
captureInterval: Sets the interval of the screen capture. The interval must be longer than one second and the default value is five seconds. Takes effect only when getVideoFrame is set as 3, 4, or 5 (Individual Mode).

Composite recording mode

isMixingEnabled: Sets whether or not to enable composite recording mode.
- 0: (Default) Enables individual recording mode, which means recording one audio or video file for each user. The sample rate of the recording file is 48 kHz, and the bitrate and audio channel number of the recording file are the same as those of the original audio stream. The video profile is the same as that of the original video.
- 1: Enables composite recording mode, which means the audio of all the users is mixed in an audio file and the video of all the users is mixed in a video file. You can set the audio profile of the recording file by the audioProfile parameter and set the video profile by the mixResolution parameter.
mixedVideoAudio：When isMixingEnabled is 1, you can set this parameter to mix the audio and video in an MP4 file in real time.
- 0: (Default) Mixes the audio and video respectively.
- 1: Mixes the audio and video in real time into an MP4 file. Supports limited players.
- 2: Mixes the audio and video in real time into an MP4 file. Supports more players.
- 6: Mixes the audio and video in real time into a TS file.
- 7: Mixes the audio and video in real time into an MP4 file and a TS file. The SDK deletes the TS file after recording. See FAQ for the supported players.
layoutMode：Sets the video mixing layout. See Set Video Layout for details.
- 0: (Default) Floating layout. The first user in the channel occupies the full canvas. The other users occupy the small regions on top of the canvas, starting from the bottom left corner. The small regions are arranged in the order of the users joining the channel. This layout supports one full-size region and up to four rows of small regions on top with four regions per row, comprising 17 users.
- 1: Best Fit Layout. This is a grid layout. The number of columns and rows and the grid size vary depending on the number of users in the channel. This layout supports up to 17 users.
- 2: Vertical Layout. One large region is displayed on the left edge of the canvas, and several smaller regions are displayed along the right edge of the canvas. The space on the right supports up to 2 columns of small regions with 8 regions per column. This layout supports up to 17 users.
maxResolutionUid: When layoutMode is set as 2 (vertical layout), you can specify the user ID of the large video window by this parameter.
audioProfile: Sets the audio profile (sample rate, bitrate, encode mode, and the number of channels) of the recording file. Takes effect only when isMixingEnabled is 1.
- 0: (Default) Sample rate of 48 kHz, communication encoding, mono, and a bitrate of up to 48 Kbps.
- 1: Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.
- 2: Sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.
mixResolution: When isMixingEnabled is set as 1, you can use this parameter to set the video profile, including the width, height, frame rate, and bitrate. The default setting is 360 x 640, 15 fps, and 500 Kbps. We recommend you set the video profile according to the Video Profile Table.
defaultVideoBg: Sets the directory of the default background image of the canvas in composite recording mode. Only supports local images in JPEG format. If defaultVideoBg is not set, the background image is black by default.
defaultUserBg: Sets the directory of the default background image of the users in composite recording mode. The background image is displayed when a user is online and does not send any video stream. Only supports local images in JPEG format. If defaultVideoBg is not set, the background image is black by default.

This setting does not work for users of the Agora Web SDK.
keepLastFrame: Sets whether or not to show the last frame of a user in the region after the user leaves the channel:
- 0: (Default) The user's last frame does not show in the region.
- 1: The user's last frame shows in the region.
cfgFilePath：When recording audio files(isAudioOnly(1), isMixingEnabled(1)), you can get a MP3 file after recording. Set the path of the configuration file in the cfgFilePath parameter. The content in the configuration file must be in JSON format, such as:
- Records audio files in AAC and MP3 formats
```
{
"Secondary_Recorder":"mp3",  // Adds MP3 format
"Audio_Sample_Rate":16000   // Sets the audio sample rate
}
```
- Records audio files only in MP3 format
```
{
"Audio_Only_Record":"mp3",  // Records audio files only in MP3 format
"Audio_Sample_Rate":16000   // Sets the audio sample rate
}
```
Audio_Sample_Rate can be set to 16000Hz, 32000Hz, 44100Hz, 48000Hz. If the sample rate you set is not within the above range, the default sample rate is 16000Hz.

Path of the recorded files

Use either of the following parameters to set the path of the recorded files.

recordFileRootDir：Sets the path of the recorded files. After setting recordFileRootDir, the subdirectory will be automatically generated according to the date of the recording.
cfgFilePath: Sets the path of the configuration file. In the configuration file, you can set the absolute directory of the recorded files, but the subdirectory will not be automatically generated. The content in the configuration file must be in JSON format, such as {"Recording_Dir" : "<recording path>"}. Do not modify "Recording_Dir".

Other settings

proxyServer: Sets the proxy server, which allows recording with the Intranet server. For example 127.0.0.1:1080.
audioIndicationInterval: Sets whether or not to detect the users who speak. Disabled by default.
- 0: (Default) Disables the function of detecting the users who speak.
- > 0: The interval (ms) of detecting the users who speak. Agora recommends setting the interval to be longer than 200 ms. When the SDK detects the users who speak, the SDK returns the user ID of the user who speaks loudest and the user IDs of all the users who speak and their voice volumes.
logLevel: Sets the log level. Only log levels preceding the selected level are generated. The default value of the log level is 5.
- 1: The log level is Fatal.
- 2: The log level is Error.
- 3: The log level is Warn.
- 4: The log level is Notice.
- 5: The log level is Info.
- 6: The log level is Debug.
enableIntraRequest: Sets whether to enable the keyframe request. The default value is 1, which can improve the audio and video quality under poor network conditions. To play the video file recorded in individual recording mode from a specified position, you must set enableIntraRequest as 0.
- 1: (Default) Leave it to the sender to decide whether to enable the keyframe request. After the keyframe request is enabled, you cannot play a video file, which is recorded in individual recording mode, from a specified position.
- 0: Disable the keyframe request. All senders in the channel send the keyframe at an interval of 2 seconds. After the keyframe request is disabled, you can play a video file, which is recorded in individual recording mode, from a specified position.
If the sender uses Agora RTC SDK v2.9.2 or earlier, this parameter is valid only in the interactive streaming scenario.
enableH265Support: Sets whether to enable recording video stream in H.265 format:
- 1: Enable recording video stream in H.265 format.
- 0: (Default) Disable recording stream in H.265 format. Other remote users in the channel can no longer send video stream in H.265 format.

Next steps

After the recording is complete, use the transcoding script to merge the recorded files. See Use the Transcoding Script .

If any error or warning occurs during the recording, see Error codes and Warning codes.

References

Is this page helpful?

Yes