This page demonstrates how to record a call by using the command line. You can also record calls by calling the API methods. For the detailed API reference, see Recording 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.

View the Recording Parameters

Open a command-line tool and run the ./recorder_local command under the samples/cpp directory. You can see the recording parameters and options as follows:

Usage: 
  ./recorder_local --appId STRING --uid UINTEGER32 --channel STRING --appliteDir STRING --channelKey STRING --channelProfile UINTEGER32 --isAudioOnly --isVideoOnly --isMixingEnabled --mixResolution STRING --mixedVideoAudio UINTEGER32 --decryptionMode STRING --secret STRING --idle INTEGER32 --recordFileRootDir STRING --lowUdpPort INTEGER32 --highUdpPort INTEGER32 --getAudioFrame UINTEGER32 --getVideoFrame UINTEGER32 --captureInterval INTEGER32 --cfgFilePath STRING --streamType UINTEGER32 --triggerMode INTEGER32 --proxyServer STRING --audioProfile UINTEGER32 --audioIndicationInterval INTEGER32 --defaultVideoBg STRING --defaultUserBg STRING --logLevel INTEGER32 --layoutMode INTEGER32 --maxResolutionUid INTEGER32 
                   --appId     (App Id / mandatory)
                   --uid     (User Id / default is 0 / mandatory)
                   --channel     (Channel Id / mandatory)
                   --appliteDir     (directory of app lite 'AgoraCoreService', must point to the 'Agora_Recording_SDK_for_Linux_FULL/bin/' folder / mandatory)
                   --channelKey     (channelKey / optional)
                   --channelProfile     (channel_profile: (0:COMMUNICATION),(1:broadcast) default is 0 / optional)
                   --isAudioOnly     (Default 0:A/V, 1:AudioOnly (0:1) / optional)
                   --isVideoOnly     (Default 0:A/V, 1:VideoOnly (0:1) / optional)
                   --isMixingEnabled     (Mixing Enable? (0:1) / optional)
                   --mixResolution     (change the default resolution for the video mixing mode / optional)
                   --mixedVideoAudio     (mixVideoAudio: (0:seperated Audio,Video) (1:mixed Audio & Video with legacy codec) (2:mixed Audio & Video with new codec), default is 0 / optional)
                   --decryptionMode     (decryption Mode, default is NULL / optional)
                   --secret     (input secret when enable decryptionMode / optional)
                   --idle     (Default 300 s, should be above 3 s / optional)
                   --recordFileRootDir     (recording file root dir / optional)
                   --lowUdpPort     (default is random value / optional)
                   --highUdpPort     (default is random value / optional)
                   --getAudioFrame     (default 0 (0:save as file, 1:aac frame, 2:pcm frame, 3:mixed pcm frame) (Can't combine with isMixingEnabled) / optional)
                   --getVideoFrame     (default 0 (0:save as file, 1:h.264, 2:yuv, 3:jpg buffer, 4:jpg file, 5:jpg file and video file) (Can't combine with isMixingEnabled) / optional)
                   --captureInterval     (default 5 (Video snapshot interval (second)))
                   --cfgFilePath     (config file path / optional)
                   --streamType     (remote video stream type(0:STREAM_HIGH,1:STREAM_LOW), default is 0 / optional)
                   --triggerMode     (triggerMode:(0: automatically mode, 1: manually mode) default is 0 / optional)
                   --proxyServer     (proxyServer:format ip:port, eg,"127.0.0.1:1080" / optional)
                   --audioProfile     (audio quality: (0: single channelstandard 1: single channel high quality 2:multiple channel high quality)
                   --audioIndicationInterval     (audioIndicationInterval:(0: no indication, audio indication interval(ms)) default is 0 / optional)
                   --defaultVideoBg     (default video background / optional)
                   --defaultUserBg     (default user background / optional)
                   --logLevel     (log level default INFO / optional)
                   --layoutMode     (layoutMode:(0: default layout, 1:bestFit Layout mode, 2:vertical presentation Layout mode) default is 0 / optional)
                   --maxResolutionUid     (uid with maximum resolution under vertical presentation layout mode / default is -1 / optional)

Set the Recording Parameters

Set the following parameters to start recording.

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

Parameters Description
appId The App ID must be the same as the Agora Native/Web SDK. For details, see Getting an App ID.
uid User ID. A 32-bit unsigned integer ranging from 1 to (232-1) that is unique in a channel. If the uid is set as 0, the SDK assigns a uid.
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/.
channelKey Users with higher security requirements can use a token or Channel Key. For details, see Use Security Keys.
channelProfile Sets the channel profile:
  • 0: (Default) Communication profile is used in one-on-one or group calls, where all users in the channel can talk freely.
  • 1: Live broadcast profile includes two roles, host and audience. The host sends and receives audio/video, while the audience only receives audio/video.
    The On-premise Recording SDK must use the same channel profile as the Agora Native/Web SDK. Otherwise, issues may occur.
  • isAudioOnly
  • 0: (Default) Enables both audio and video recording.
  • 1: Enables audio recording and disables video recording.
    isAudioOnly and isVideoOnly cannot be set as 1 at the same time.
  • isVideoOnly
  • 0: (Default) Enables both audio and video recording.
  • 1: Enables video recording and disable audio recording.
    isAudioOnly and isVideoOnly cannot be set as 1 at the same time.
  • isMixingEnabled Sets whether or not to enable the audio- or video-composite mode.
  • 0: (Default) Enables the individual mode, which means one audio or video file for a uid. The bitrate and audio channel number of the recording file are the same as those of the original audio stream.
  • 1: Enables the composite mode, which means the audio of all uids is mixed in an audio file and the video of all uids is mixed in a video file. The sample rate, bitrate, and number of audio channels of the recording file are the same as the highest level of those of the original audio streams.
  • mixResolution If you set isMixingEnabled as 1, mixResolution allows you to set the video profile, including the width, height, frame rate, and bitrate. For details on the recommended resolution, see mixResolution.
    mixedVideoAudio If you set isMixingEnabled as 1, mixedVideoAudio allows you to mix the audio and video in real time:
  • 0: (Default) Do not mix the audio and video.
  • 1: Mix the audio and video in real time into an MPEG-4 file. Supports limited players.
  • 2: Mix the audio and video in real time into an MPEG-4 file. Supports more players.
    For the supported players, see MIXED_AV_CODEC_TYPE.
  • 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. The following decryption methods are supported:
  • "aes-128-xts": AES-128, XTS mode
  • "aes-128-ecb": AES-128, ECB mode
  • "aes-256-xts":AES-256, XTS mode
  • secret The decryption password when decryption mode is enabled.
    idle The Agora On-premise Recording SDK automatically stops recording when there is no user in the recording channel 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.
    recordFileRootDir The root directory of the recording files. The sub-path is generated automatically according to the recording date to save the recording file.
    lowUdpPort The lowest UDP port. Ensure that the value is a positive integer and the value of highUdpPort - lowUdpPort ≥ 4.
    highUdpPort The highest UDP port. Ensure that the value is a positive integer and the value of highUdpPort - lowUdpPort ≥ 4.
    getAudioFrame Audio decoding format.
  • 0: Default audio format.
  • 1: Audio frame in AAC format.
  • 2: Audio frame in PCM format.
  • 3: Audio frame in PCM audio-mixing format.
    When getAudioFrame = 1, 2, or 3, isMixingEnabled cannot be set as 1.
  • getVideoFrame Video decoding format.
  • 0: Default video format.
  • 1: Video frame in H.264 format.
  • 2: Video frame in YUV format.
  • 3: Video frame in JPEG format.
  • 4: JPEG file format.
  • 5: Video frame in JPEG format + MPEG-4 video.
    Limitations:
  • When VIDEO_FORMAT_TYPE = 1, 2, 3, or 4, isMixingEnabled cannot be set as 1.
  • When VIDEO_FORMAT_TYPE = 1, 2, 3, or 5, raw video data in YUV format for the Web SDK is supported while H.264 format is not supported.
  • captureInterval Time interval of the screen capture. The value ranges between one second and five seconds. captureInterval takes effect only when getVideoFrame = 3, 4, or 5.
    cfgFilePath The path of the configuration file. The default value is NULL. In the configuration file, you can set the absolute path of the recorded file, but the subpath is not generated automatically. The content in the configuration file must be in JSON format, such as {“Recording_Dir” : “recording path”}. Do not modify “Recording_Dir”.
    streamType Sets the type of video stream. streamType takes effect only when the Agora Native/Web SDK enables the dual-stream mode。
  • 0: (Default) Records the high-stream video.
  • 1: Records the low-stream video.
  • 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.
      • Start: killall -s 10 recorder_local
      • Stop: killall -s 12 recorder_local
    proxyServer Sets the IP address and port number of the proxy server. For example, "127.0.0.1:1080".
    audioProfile Audio profile of the recording file. Sets the sample rate, bitrate, encode mode, and the number of channels.
  • 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.
    The high-fidelity audio takes effect only when isMixingEnabled is set as 1.
    The stereo audio profile does not support the raw audio data.
  • audioIndicationInterval Whether or not to detect speakers. Disabled by default.
  • 0: (Default) Disables the function of detecting the speakers.
  • > 0: The time interval (ms) of detecting the speakers. Agora recommends setting the time interval to be longer than 200 ms. When a speaker is found, the uid of the speaker is printed in the command line.
  • defaultVideoBg The default background image of the canvas.
    defaultUserBg The default background image of the user.
    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.
  • layoutMode Sets the video mixing layout.
  • 0: Default layout.
  • 1: Best fit. This layout automatically scales according to the number of video streams. The number of columns and rows varies depending on the number of video streams. Supports up to 17 video streams.
  • 2: Vertical presentation. A specified uid displays a large video window on the left of the screen, while video streams from other users are arranged vertically on the right in small video windows. A maximum of two columns with eight windows in each column are supported.
  • maxResolutionUid When layoutMode is set as 2 (vertical presentation), you can specify the uid of the large video window by this parameter.

    Next Steps

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

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