Recording API

The APIs included in this document are only applicable to the recording solution mentioned in Recording SDK Guide . Use C++ language.

Basic Methods(IRecordingEngine)

Create Recording Engine(createAgoraRecordingEngine)

public static IRecordingEngine* createAgoraRecordingEngine(const char * appId, IRecordingEngineEventHandler *eventHandler);

This method creates the Agora recording engine object.

Name Description
appId App ID. For details, see app_id
eventHandler Agora Recording SDK notifies the application of its triggered events according to Callback Methods(IRecordingEngineEventHandler)

Join Channel (joinChannel)

public int joinChannel(const char * channelKey, const char *channelId, uid_t uid, const RecordingConfig &config)

This method lets the recording application join the channel and start recording.

Description Description
channelKey
  • For low-security requirement, set it as NULL
  • For high-security requirement, set it as Channel Key. If an App Certificate is enabled, you must use a Channel Key. For details, refer to Obtaining and Using a Dynamic Key
channelId A string providing the unique channel name. The length must be within 64 bytes.
uid User ID: a 32-bit unsigned integer ranges from 1 to (2^32-1). It must be unique.
config See the definition in the following table for details.

config Definition:

Name Description
channelProfile

It sets the channel mode:

  • CHANNEL_PROFILE_COMMUNICATION: Communication(default). Anyone in the channel can talk freely
  • CHANNEL_PROFILE _LIVE_BROADCASTING: Live Broadcast
isAudioOnly

It disables video recording and only enables audio recording:

  • true: enable audio recording only
  • false: record both audio and video
isMixingEnabled

Whether to record audio mixing or/and video mixing. The parameter is disabled by default:

  • If isAudioOnly is enabled, this parameter sets whether to enable the audio mixing function
  • If isAudioOnly is disabled, this parameter sets whether to enable audio mixing and video mixing respectively
decryptionMode

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 The decryption password after enabling the decryotion mode
idleLimitSec 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 for this parameter.
appliteDir It sets the directory to store the Linux SDK built-in applite application
recordFileRootDir It sets the root directory to store the recording files
lowUdpPort [1] It sets the lowest UDP port
highUdpPort [1] It sets the highest UDP port

Footnotes

[1](1, 2) All the ports being set must be positive integers, and the value of highUdpPort - lowUdpPort must be no less than 4.

Set Video Mixing Layout(setVideoMixingLayout)

public virtual int setVideoMixingLayout(const VideoMixingLayout &layout);

This method sets the video mixing layout.

typedef struct VideoMixingLayout
{
 struct Region {
     uid_t uid;
     double x;
     double y;
     double width;
     double height;
     int zOrder;
     double alpha;
     int renderMode;


 };
 int canvasWidth;
 int canvasHeight;
 const char* backgroundColor;//e.g. "#C0C0C0" in RGB
 int regionCount;
 const Region* regions;
 const char* appData;
 int appDataLength;
Name Description
canvasWidth The width of the entire canvas(The display window or screen)
canvasHeight The height of the entire canvas(The display window or screen)
backgroundColor Enter any of the 6-digit symbols defined in RGB
regions

The array of AgoraRtcVideoCompositingRegion. Each host in the channel can have a region to display the video on the screen with the following parameters to be set:

  • uid: The user id of the user with the video to be displayed on the region.

    • x[0.0,1.0]: the horizontal position of the region on the screen.
    • y[0.0,1.0]: the vertical position of the region on the screen.
    • width[0.0, 1.0]: the actual width of the region.
    • height[0.0, 1.0]: the actual height of the region.
  • zOrder[0, 100]: 0 means the region is on the bottom, and 100 means the region is on the top.

  • alpha[0.0, 1.0]: 0 means the region is transparent, and 1 means the region is opaque.

  • renderMode:

    • RENDER_MODE_HIDDEN(1): Cropped
    • RENDER_MODE_FIT(2): Zoom to fit
appData The application defined data

Here is an example used to describe the position and size of the region:

../../_images/sei_overview.png

Leave Channel (leaveChannel)

public virtual int leaveChannel();

The recording application leaves the channel and releases the occpuied thread resources.

Release IRecordingEngine Object(release)

public virtual int release();

This method destroys the IRecordingEngine object.

Callback Methods(IRecordingEngineEventHandler)

Error Reported Callback(onError)

public virtual void onError(int error);

This callback indicates that an error occurred during the runtime of the SDK.

In most cases reporting an error means that the SDK cannot fix the issue and resume running, and therefore requires actions from the application or simply informs the user on the issue.

Name Description
err

Error codes:

  • ERR_OK = 0: No Error
  • ERR_FAILED = 1: General error(the reason is not classified specifically)
  • ERR_INVALID_ARGUMENT = 2: Invalid parameter called. For example, the specific channel name includes illegal characters
  • ERR_INTERNAL_FAILED = 3: SDK module is not ready. For example, if some API relies on a specific module, but the module is not ready to provide service yet.

Warning Reported Callback(onWarning)

public virtual void onWarning(int warn);

This callback indicates that some warning occurred during the runtime of the SDK. In most cases the application can ignore the warnings reported by the SDK because the SDK usually can fix the issue and resume running.

Name Description
warn

Warning codes:

  • WARN_NO_AVAILABLE_CHANNEL = 103: No channel resources are available. Maybe because the server cannot allocate channel resources
  • WARN_LOOKUP_CHANNEL_TIMEOUT = 104: Timed-out when looking up the channel. When joining a channel, the SDK looks up the specified channel. The warning usually occurs when the network condition is too bad to connect to the server.
  • WARN_LOOKUP_CHANNEL_REJECTED = 105: The server rejected the request to look up the channel. The server cannot process this request or request is illegal.
  • WARN_OPEN_CHANNEL_TIMEOUT = 106: Timed-out when opening the channel. Once the specific channel is found, the SDK opens the channel. The warning usually occurs when the network condition is too bad to connect to the server.
  • WARN_OPEN_CHANNEL_TIMEOUT = 107: The server rejected the request to open the channel. The server cannot process this request or request is illegal.

Join Channel Callback (onJoinChannelSuccess)

public virtual void onJoinChannelSuccess(const char * channelId, uid_t uid);

This callback indicates that the user has successfully joined the specified channel.

Name Description
channelId The channel ID is assigned based on the channel name specified in joinChannel() API.
uid User ID. If the uid is specified in the joinChannel method, returns the specified ID; if not, returns an ID that is automatically allocated by the Agora server.

Leave Channel Callback (onLeaveChannel)

public virtual void onLeaveChannel();

When the recording application calls the leaveChannel() method, the SDK uses this callback to notify the application that the user has successfully left the channel.

Other User Joined Channel Callback (onUserJoined)

public virtual void onUserJoined(uid_t uid, UserJoinInfos &infos)

This callback method notifies the application that another user has joined the channel. If there are other users in the channel when that user joins, the SDK also reports to the application on the existing users who are already in the channel.

typedef struct UserJoinInfos {
 const char* recordingDir;
}
Name Description
uid The User ID
recordingDir The directory of the recorded files

The following is an example of a returned directory:

root@ubuntu:/home/workspace/7-21/samples# ./Recorder_local --appId 74a0b7bb5d3e47c7abca0533d17b0afa --uid 333 --channel video --appliteDir `pwd`/../bin

User 63720491 joined, RecordingDir:./20170721/video_085747/

Other User Offline Callback (onUserOffline)

public virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason)

This callback notifies the application that a user has left the channel or gone offline.

The SDK reads the timeout data to determine if a user has left the channel (or has gone offline) or not. If no data package is received from the user in 15 seconds, the SDK takes it as the user being offline. Sometimes a weak network connection may lead to false detection, therefore we recommend using signaling for reliable offline detection.

Name Description
uid User ID
reason

Reasons for user going offline:

  • USER_OFFLINE_QUIT = 0: User has quit the call.
  • USER_OFFLINE_DROPPED = 1: The SDK is timeout and dropped offline because it hasn’t received data package for too long [2]
  • USER_OFFLINE_BECOME_AUDIENCE = 2: It is triggered when the host is switched to the audience role. It is only applicable when you set the channel profile as live broadcast scenario when calling the joinChannel() method

Footnotes

[2]Sometimes when the other user quits the call but the message is not passed to the SDK due to unreliable channel, the SDK may mistake it as the other user is timeout and dropped offline.