Version: v2.2.2

C++ Interface Class Description
IRecordingEngine The IRecordingEngine class provides the main methods that can be invoked by your application.
IRecordingEngineEventHandler The IRecordingEngineEventHandler class enables callbacks to your application.

IRecordingEngine

The IRecordingEngine class provides the following main methods that can be invoked by your application:

Creates a Recording Engine (createAgoraRecordingEngine)

This method creates the Agora recording engine object.

public static IRecordingEngine* createAgoraRecordingEngine(const char * appId, IRecordingEngineEventHandler *eventHandler);
Name Description
appId The App ID used in the communication to be recorded. For more information, see Getting an App ID.
eventHandler The Agora Recording SDK notifies the application of the triggered callbacks found in IRecordingEngineEventHandler.

Allows the Recording Application to Join a Channel (joinChannel)

This method allows the recording application to join a channel and start recording.

virtual int joinChannel(const char * token, const char *channelId, uid_t uid, const RecordingConfig &config) = 0;
Name Description
token The token used in the communications to be recorded. For more information, see Use Security Keys.
channelId Name of the channel to be recorded. The length must be within 64 bytes.
The following is the supported scope:
  • The 26 lowercase English letters from a to z
  • The 26 uppercase English letters from A to Z
  • The 10 numbers from 0 to 9
  • The space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
  • uid User ID. A 32-bit unsigned integer ranging from 1 to (232-1) that is unique in a channel.
    config Detailed recording configuration. See the definition in the table below.
    Returns:
    • 0: Success.
    • < 0: Failure.
    • In the Recording SDK, requestToken and renewToken are private methods. Make sure that you set expireTimestamp as 0 when generating a token, which means that the privilege, once generated, never expires.

    • A channel does not accept duplicate uids. Otherwise, there will be unpredictable behaviors.

    The structure of RecordingConfig:

    typedef struct RecordingConfig {
        bool isAudioOnly;
        bool isVideoOnly;
        bool isMixingEnabled;
        agora::linuxsdk::MIXED_AV_CODEC_TYPE mixedVideoAudio;
        char * mixResolution;
        char * decryptionMode;
        char * secret;
        char * appliteDir;
        char * recordFileRootDir;
        char * cfgFilePath;
        agora::linuxsdk::VIDEO_FORMAT_TYPE decodeVideo;
        agora::linuxsdk::AUDIO_FORMAT_TYPE decodeAudio;
        int lowUdpPort;
        int highUdpPort;
        int idleLimitSec;
        int captureInterval;
        int audioIndicationInterval;
        agora::linuxsdk::CHANNEL_PROFILE_TYPE channelProfile;
        agora::linuxsdk::REMOTE_VIDEO_STREAM_TYPE streamType;
        agora::linuxsdk::TRIGGER_MODE_TYPE triggerMode;
        agora::linuxsdk::LANGUAGE_TYPE lang;
        char * proxyServer;
        agora::linuxsdk::AUDIO_PROFILE_TYPE audioProfile;
        char * defaultVideoBg;
        char * defaultUserBg;
        agora::linuxsdk::avsyncType avSyncMode;
    
        RecordingConfig(): channelProfile(agora::linuxsdk::CHANNEL_PROFILE_COMMUNICATION),
            isAudioOnly(false),
            isVideoOnly(false),
            isMixingEnabled(false),
            mixResolution(NULL),
            decryptionMode(NULL),
            secret(NULL),
            idleLimitSec(300),
            appliteDir(NULL),
            recordFileRootDir(NULL),
            cfgFilePath(NULL),
            lowUdpPort(0),
            highUdpPort(0),
            captureInterval(5),
            audioIndicationInterval(0),
            decodeAudio(agora::linuxsdk::AUDIO_FORMAT_DEFAULT_TYPE),
            decodeVideo(agora::linuxsdk::VIDEO_FORMAT_DEFAULT_TYPE),
            mixedVideoAudio(agora::linuxsdk::MIXED_AV_DEFAULT),
            streamType(agora::linuxsdk::REMOTE_VIDEO_STREAM_HIGH),
            triggerMode(agora::linuxsdk::AUTOMATICALLY_MODE),
            lang(agora::linuxsdk::CPP_LANG),
            proxyServer(NULL),
            audioProfile(agora::linuxsdk::AUDIO_PROFILE_DEFAULT),
            defaultVideoBg(NULL),
            defaultUserBg(NULL),
            avSyncMode(agora::linuxsdk::avsyncType::AVSYNC_V0)
        {}
    
        virtual ~RecordingConfig() {}
     } RecordingConfig;
    Name Description
    channelProfile

    Sets the channel mode.

    • CHANNEL_PROFILE_COMMUNICATION (0): (Default) Communication mode. This is used in one-on-one or group calls, where all users in the channel can talk freely.
    • CHANNEL_PROFILE_LIVE_BROADCAST (1): Live broadcast mode. The host sends and receives voice/video, while the audience only receives voice/video. Host and audience roles can be set by calling setClientRole.
    The Recording SDK must use the same channel profile as the Agora Native/Web SDK, otherwise issues may occur.
    isAudioOnly

    Sets whether or not to record audio only.

    • true: Enables audio recording and disables video recording.
    • false: (Default) Enables both audio and video recording.

    Used together with isVideoOnly

    • If isAudioOnly is true and isVideoOnly is false, only records audio;
    • If isAudioOnly is false and isVideoOnly is true, only records video;
    • If isAudioOnly is false and isVideoOnly is false, records both audio and video;
    • isAudioOnly and isVideoOnly can not be set as true at the same time.
    isVideoOnly

    Sets whether or not to record video only.

    • true: Enables video recording and disables audio recording.
    • false: (Default) Enables both audio and video recording.

    Used together with isAudioOnly

    • If isAudioOnly is true and isVideoOnly is false, only records audio;
    • If isAudioOnly is false and isVideoOnly is true, only records video;
    • If isAudioOnly is false and isVideoOnly is false, records both audio and video;
    • isAudioOnly and isVideoOnly can not be set as true at the same time.
    isMixingEnabled

    Sets whether or not to enable the audio- or video-mixing mode.

    • true: 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 audio channel number of the recorded file are the same as the highest level of those of the original audio streams.
    • false: (Default) Enables the individual mode, which means one audio or video file for an uid. The bitrate and audio channel number of the recording file are the same as those of the original audio stream.
    mixResolution If you set isMixingEnabled as true and enable the composite mode, mixResolution allows you to set the video profile, including the width, height, frame rate, and bitrate. For the recommended bitrates, see the tables below.
    decryptionMode

    When the whole channel is encrypted, the recording SDK uses decryptionMode to enable the built-in decryption function. 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 the decryptionMode is enabled. The default value is NULL.
    idleLimitSec The Agora Recording SDK automatically stops recording when there is no user in the channel after a time period of idleLimitSec. The value must be ≥ 3 seconds. The default value is 300 seconds.
    appliteDir The directory of AgoraCoreService. The default value is NULL.
    recordFileRootDir The root directory of the recorded files. The default value is NULL. The sub-path will be generated automatically.
    cfgFilePath The path of the configuration file. The default value is NULL. The content in the configuration file must be in JSON format. In the configuration file, you can set the absolute path of the recorded file, such as {“Recording_Dir” : “”}. “Recording_Dir” can not be changed. But the sub-path will not be generated automatically.
    lowUdpPort The lowest UDP port. Ensure that the value of highUdpPort - lowUdpPort is ≥ 4. The default value is 0.
    highUdpPort The highest UDP port. Ensure that the value of highUdpPort - lowUdpPort is ≥ 4. The default value is 0.
    captureInterval The time interval of the screen capture. The time interval must be longer than 1 second and the default value is 5 seconds. captureInterval is only valid when the VIDEO_FORMAT_TYPE = 3, 4 or 5.
    audioIndicationInterval

    Whether or not to detect speakers. It is disabled by default.

    • <= 0: Disables the function of detecting speakers.
    • > 0: The time interval (ms) of detecting speakers. Agora recommends setting the time interval to be longer than 200ms. When a speaker is found, the SDK returns the UID of the speaker in the onActiveSpeaker callback.
    decodeAudio Audio decoding format.
    • AUDIO_FORMAT_DEFAULT_TYPE = 0: Default audio format.
    • AUDIO_FORMAT_AAC_FRAME_TYPE = 1: Audio frame in AAC format.
    • AUDIO_FORMAT_PCM_FRAME_TYPE = 2: Audio frame in PCM format.
    • AUDIO_FORMAT_MIXED_PCM_FRAME_TYPE = 3: Audio-mixing frame in PCM format. isMixingEnabled cannot be set as true.
    decodeVideo Video decoding format.
    • VIDEO_FORMAT_DEFAULT_TYPE = 0: Default video format.
    • VIDEO_FORMAT_H264_FRAME_TYPE = 1: Video frame in H.264 format.
    • VIDEO_FORMAT_YUV_FRAME_TYPE = 2: Video frame in YUV format.
    • VIDEO_FORMAT_JPG_FRAME_TYPE = 3: Video frame in JPEG format.
    • VIDEO_FORMAT_JPG_FILE_TYPE = 4: JPEG file format.
    • VIDEO_FORMAT_JPG_VIDEO_FILE_TYPE = 5:Video frame in JPEG format + MPEG-4 video.
      • Individual Mode (isMixingEnabled is set as false): MPEG-4 video and JPEG files.
      • Composite Mode (isMixingEnabled is set as true): MPEG-4 video file for mixed streams and JPEG files for individual streams.
    When the video is decoded into raw video data, that is VIDEO_FORMAT_TYPE = 1, 2, 3 or 5:
    • Video mixing is not supported.
    • Raw video data in YUV format for the Web SDK is supported while H.264 format is not supported.
    mixedVideoAudio

    f you set isMixingEnabled as true and enable the composite mode, mixedVideoAudio allows you to mix the audio and video in a file in real time.

    • 0: (Default) Mixes the audio and video respectively.
    • 1: Mixes the audio and video in real time into an MPEG-4 file. Supports limited players.
    streamType

    Takes effect only when the Agora Native SDK or Web SDK has enabled the dual-stream mode (high stream by default).

    • 0: (Default) High stream.
    • 1: Low stream.
    triggerMode

    Sets whether to record automatically or manually upon joining the channel.

    • 0: Automatically.
    • 1: Manually. To start and stop recording, call startService and stopService respectively.
    lang Sets the programming language (C++ or Java).
    proxyServer Sets the proxy server, which allows recording with the Intranet server. For more information, please contact sales@agora.io .
    audioProfile

    Audio profile of the recording file. Sets the sampling rate, bitrate, encode mode, and the number of channels. Takes effect only when isMixingEnabled is set as true.

    • AUDIO_PROFILE_DEFAULT = 0: (Default) Sampling rate of 48 kHz, communication encoding, mono, and a bitrate of up to 18 Kbps.
    • AUDIO_PROFILE_MUSIC_HIGH_QUALITY = 1: Sampling rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.
    • AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO = 2: Sampling rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.
    defaultVideoBg The default background image of the canvas.
    defaultUserBg The default background image of the user.
    avSyncMode

    Audio and video synchronization mode.

    • UNKNOWN_AVSYNC = -1: Synchronization error (UNKNOWN_AVSYNC).
    • AVSYNC_V0 = 0: Compatible with older versions (AVSYNC_V0).
    • AVSYNC_V1 = 1: New audio and video synchronization mode (AVSYNC_V1).

    Video Profile for the Communication Mode:

    Resolution Frame Rate (fps) Minimum Bitrate (Kbps) Maximum Bitrate (Kbps) Recommended Bitrate (Kbps)
    3840 × 2160 15 3000 9000 6000
    2560 × 1440 15 1600 4800 3200
    1920 × 1080 15 1000 3000 2000
    1280 × 720 15 600 1800 1200
    960 × 720 15 480 1440 960
    848 × 480 15 300 900 600
    640 × 480 15 250 750 500
    480 × 480 15 200 600 400
    640 × 360 15 200 600 400
    360 × 360 15 130 390 260
    424 × 240 15 110 330 220
    320 × 240 15 90 270 180
    240 × 240 15 70 210 140
    320 × 180 15 70 210 140
    240 × 180 15 60 180 120
    180 × 180 15 50 150 100
    160 × 120 15 30 90 60
    120 × 120 15 25 75 50

    Video Profile for the Live Broadcast Mode:

    Resolution Frame Rate (fps) Minimum Bitrate (Kbps) Maximum Bitrate (Kbps) Recommended Bitrate (Kbps)
    3840 × 2160 15 6000 18000 12000
    2560 × 1440 15 3200 9600 6400
    1920 × 1080 15 2000 6000 4000
    1280 × 720 15 1200 3600 2400
    960 × 720 15 960 2880 1920
    848 × 480 15 600 1800 1200
    640 × 480 15 500 1500 1000
    480 × 480 15 400 1200 800
    640 × 360 15 400 1200 800
    360 × 360 15 260 780 520
    424 × 240 15 220 660 440
    320 × 240 15 180 540 360
    240 × 240 15 140 420 280
    320 × 180 15 140 420 280
    240 × 180 15 120 360 240
    180 × 180 15 100 300 200
    160 × 120 15 60 180 120
    120 × 120 15 50 150 100

    Supported Players:

    Platform Player/Explorer mixedVideoAudio = 0 mixedVideoAudio = 1
    Linux VLC Media Playerr Supported Supported
    Linux ffplayer Supported Supported
    Linux Chrome Not Supported Not Supported
    Windows Media Player Supported Supported
    Windows KM Player Supported Supported
    Windows VLC Player Supported Supported
    Windows Chrome (49.0.2623+) Supported Supported
    macOS QuickTime Player Supported Supported
    macOS VLC Not Supported Not Supported
    macOS Movist Supported Supported
    macOS MPlayerX Supported Supported
    macOS KM Player Not Supported Not Supported
    macOS Chrome (47.0.2526.111+) Supported Supported
    macOS Safari (11.0.3+) Supported Supported
    iOS Default Player Supported Supported
    iOS VLC for Mobile Not Supported Not Supportedd
    iOS KM Player Supported Supported
    iOS Safari (9.0+) Supported Supported
    Android Default Player Supported Supported
    Android MX Player Supported Supported
    Android VLC for Android Supported Supported
    Android KM Player Supported Supported
    Android Chrome (49.0.2623+) Supported Supported

    Sets the Video Mixing Layout (setVideoMixingLayout)

    This method sets the video mixing layout.

    virtual int setVideoMixingLayout(const agora::linuxsdk::VideoMixingLayout &layout) = 0;

    The structure of VideoMixingLayout:

     typedef struct VideoMixingLayout
     {
         struct Region {
           uid_t uid;
           double x;//[0,1]
           double y;//[0,1]
           double width;//[0,1]
           double height;//[0,1]
           int zOrder; //optional, [0, 100] //0 (default): bottom most, 100: top most
    
           //  Optional
           //  [0, 1.0] where 0 means transparent, 1.0 means opaque
           double alpha;
    
           int renderMode;//RENDER_MODE_HIDDEN: Crop, RENDER_MODE_FIT: Zoom to fit
           Region()
               :uid(0)
                , x(0)
                , y(0)
                , width(0)
                , height(0)
                , zOrder(0)
                , alpha(1.0)
                , renderMode(1)
          {}
    
       };
       int canvasWidth;
       int canvasHeight;
       const char* backgroundColor;//e.g. "#C0C0C0" in RGB
       uint32_t regionCount;
       const Region* regions;
       const char* appData;
       int appDataLength;
       VideoMixingLayout()
           :canvasWidth(0)
            , canvasHeight(0)
            , backgroundColor(NULL)
            , regionCount(0)
            , regions(NULL)
            , appData(NULL)
            , appDataLength(0)
       {}
    } VideoMixingLayout;
    Name Description
    canvasWidth Width of the canvas (the display window or screen).
    canvasHeight Height of the canvas (the display window or screen).
    backgroundColor The background color of the canvas (the display window or screen) in RGB hex value.
    regionCount The number of the users (communication mode)/hosts (live broadcast mode) in the channel.
    regions

    The user (communication mode)/host (live broadcast mode) list of VideoMixingLayout. Each user (communication mode)/host (live broadcast mode) in the channel has a region to display the video on the screen with the following parameters to be set:

    • uid: UID of the user (communication mode)/host (live broadcast mode) displaying the video in the region.
    • x: Relative horizontal position of the top-left corner of the region. The value is between 0.0 and 1.0.
    • y: Relative vertical position of the top-left corner of the region. The value is between 0.0 and 1.0.
    • width: Relative width of the region. The value is between 0.0 and 1.0.
    • height: Relative height of the region. The value is between 0.0 and 1.0.
    • zOrder: The index of the layer. The value is between 1 (bottom layer) and 100 (top layer).
    • alpha: The transparency of the image. The value is between 0.0 (transparent) and 1.0 (opaque).
    • renderMode: Render mode
      • RENDER_MODE_HIDDEN(1): Cropped mode. Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.
      • 2RENDER_MODE_FIT(2): Fit mode. Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.
    appData User-defined data.
    appDataLength The length of the user-defined data.
    Returns
    • 0: Success.
    • < 0: Failure.

    Here is an example to show the position and size of the host’s head portrait. x, y, width, and height are 0.5, 0.4, 0.2, and 0.3 respectively.

    ../_images/sei_overview.png

    Allows the Recording Application to Leave the Channel (leaveChannel)

    This method allows the recording application to leave the channel and release the thread resources.

    virtual int leaveChannel() = 0;
    Returns
    • 0: Success.
    • < 0: Failure.

    Releases the IRecordingEngine Object (release)

    This method destroys the IRecordingEngine object.

    virtual int release() = 0;
    Returns
    • 0: Success.
    • < 0: Failure.

    Retrieves the Recording Properties (getProperties)

    This method allows you to retrieve the recording properties without joining a channel.

    • The recording properties only include the information of the path where the recording files are stored.

    • This method is different from onUserJoined. You must call onUserJoined after joining the channel.

    virtual const RecordingEngineProperties* getProperties() = 0;

    Starts the Recording (startService)

    This method manually starts recording.

    The method is only valid when you set triggerMode to 1 (manually) when joining the channel. For more information, see Allows an Application to Join a Channel (joinChannel) on triggerMode.

    virtual int startService() = 0;
    Returns
    • 0: Success.
    • < 0: Failure.

    Stops the Recording (stopService)

    This method manually stops recording.

    The method is only valid when you set triggerMode to 1 (manually) when joining the channel. For more information, see Allows an Application to Join a Channel (joinChannel) on triggerMode.

    virtual int stopService() = 0;
    Returns
    • 0: Success.
    • < 0: Failure.

    Sets the User Background Image (setUserBackground)

    This method sets the background image of a specified user. The backgrouds for different users can be different.

    virtual int setUserBackground(uid_t uid, const char* img_path) = 0;
    Name Description
    uid The UID of the user for the background image to be set.
    image_path The path of the image file.
    Returns
    • 0: Success.
    • < 0: Failure.

    Sets the Log Level (setLogLevel)

    virtual int setLogLevel(agora::linuxsdk::agora_log_level level) = 0;

    This method sets the log level. Only log levels preceding the selected level are generated. The default value of the log level is 6.

    Enables the Module Log (enableModuleLog)

    virtual int enableModuleLog(uint32_t module, bool enable) = 0;

    This method enables/disables generating logs for specified modules.

    IRecordingEngineEventHandler Class

    The IRecordingEngineEventHandler class provides the following callbacks for the recording engine:

    An Error Occurs During SDK Runtime (onError)

    This callback is triggered when an error occurs during SDK runtime.

    The SDK cannot fix the issue or resume running, which requires intervention from the application and informs the user on the issue.

    virtual void onError(int error, agora::linuxsdk::STAT_CODE_TYPE stat_code) = 0;
    Name Description
    error_code

    Error codes:

    • 0: No error (ERR_OK).
    • 1: General error with no classified reason (ERR_FAILED).
    • 2: Invalid parameter is called (ERR_INVALID_ARGUMENT). For example, the specific channel name contains illegal characters.
    • 3: The SDK module is not ready (ERR_NOT_READY). Agora recommends the following methods to solve this error:
      • Check the audio device.
      • Check the completeness of the app.
      • Re-initialize the SDK.
    stat_code

    State codes:

    • 0: Everything is normal (STAT_OK).
    • 1: Error from the engine (STAT_ERR_FROM_ENGINE).
    • 2: Failure to join the channel (STAT_ERR_ARS_JOIN_CHANNEL).
    • 3: Failure to create a process (STAT_ERR_CREATE_PROCESS).
    • 4: Failure to mix the video (STAT_ERR_MIXED_INVALID_VIDEO_PARAM).
    • 5: Null pointer (STAT_ERR_NULL_POINTER ).
    • 6: Invalid parameters of the proxy server (STAT_ERR_PROXY_SERVER_INVALID_PARAM).
    • 0x8: Error in polling (STAT_POLL_ERR).
    • 0x10: Polling hangs up (STAT_POLL_HANG_UP).
    • 0x20: Invalid polling request (STAT_POLL_NVAL).

    A Warning Occurs During SDK Runtime (onWarning)

    This callback is triggered when a warning occurs during SDK runtime.

    In most cases, the application can ignore the warnings reported by the SDK because the SDK can usually fix the issue and resume running.

    virtual void onWarning(int warn) = 0;
    Name Description
    warn_code

    Warning codes:

    • 103: No channel resources are available (WARN_NO_AVAILABLE_CHANNEL). Maybe because the server cannot allocate any channel resource.
    • 104: A timeout when looking up the channel (WARN_LOOKUP_CHANNEL_TIMEOUT). When joining a channel, the SDK looks up the specified channel. This warning usually occurs when the network conditions are too poor to connect to the server.
    • 105: The server rejected the request to look up the channel (WARN_LOOKUP_CHANNEL_REJECTED). The server cannot process this request or the request is illegal.
    • 106: A timeout occurred when opening the channel (WARN_OPEN_CHANNEL_TIMEOUT). Once the specific channel is found, the SDK opens the channel. This warning usually occurs when the network conditions are too poor to connect to the server.
    • 107: The server rejected the request to open the channel (WARN_OPEN_CHANNEL_REJECTED). The server cannot process this request or the request is illegal.

    The Recording Application Joins the Specified Channel (onJoinChannelSuccess)

    This callback is triggered when the recording application has successfully joined the specified channel with an assigned Channel ID and UID.

    virtual void onJoinChannelSuccess(const char * channelId, uid_t uid) = 0;
    Name Description
    channelId Channel ID assigned based on the channel name specified in joinChannel.
    uid UID of the user.

    The Recording Application Leaves the Channel (onLeaveChannel)

    This callback is triggered when the recording application leaves the channel.

    virtual void onLeaveChannel(agora::linuxsdk::LEAVE_PATH_CODE code) = 0;
    Name Description
    code
    The reasons why the recording application leaves the channel.
    • 0: Initialization failure (LEAVE_CODE_INIT).
    • 1: Signal triggered exit (LEAVE_CODE_SIG).
    • 2: There is no user in the channel except for the recording application (LEAVE_CODE_NO_USERS).
    • 3: Timer catch exit (LEAVE_CODE_TIMER_CATCH).
    • 4: The client leaves the channel (LEAVE_CODE_CLIENT_LEAVE).

    A User Joins the Channel (onUserJoined)

    This callback is triggered when a user joins the channel and returns the UID of the new user.

    If there are users in the channel before the recording app joins the channel, the SDK will also reports on the UIDs of the existing users. This callback is triggered as many times as the number of the users in the channel.

    virtual void onUserJoined(uid_t uid, agora::linuxsdk::UserJoinInfos &infos) = 0;
    Name Description
    uid UID of the user.
    infos Information about the user.

    The structure of UserJoinInfos:

    typedef struct UserJoinInfos {
        const char* storageDir;
        //add information about the user below
    
        UserJoinInfos():
            storageDir(NULL)
        {}
    }UserJoinInfos;
    Name Description
    storageDir Directory of the recorded files.

    A User Leaves the Channel or Goes Offline (onUserOffline)

    This callback is triggered when a user leaves the channel or goes offline.

    When no data package of a user is received for a certain period of time (15 seconds), the SDK assumes that the user has goes offline. Weak network connections may lead to misinformation, so Agora recommends using the signaling system for offline event detection.

    virtual void onUserOffline(uid_t uid, agora::linuxsdk::USER_OFFLINE_REASON_TYPE reason) = 0;
    Name Description
    uid UID of the user
    reason

    The reasons why the user leaves the channel or goes offline.

    • 0: The user has quit the call (USER_OFFLINE_QUIT).
    • 1: The SDK timed out and the user dropped offline because it has not received any data packet for a period of time (USER_OFFLINE_DROPPED). If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user has dropped offline.
    • 2: The client role has changed from the host to the audience (USER_OFFLINE_BECOME_AUDIENCE ). The option is only valid when you set the channel profile as live broadcast when calling joinChannel.

    The Raw Audio Data has Been Received (audioFrameReceived)

    This callback is triggered when the raw audio data is received.

    virtual void audioFrameReceived(unsigned int uid, const agora::linuxsdk::AudioFrame *frame) const = 0;
    Name Description
    uid UID of the user.
    frame Received raw audio data in PCM or AAC format.

    The structure of AudioFrame:

    struct AudioFrame {
        AUDIO_FRAME_TYPE type;
        union {
            AudioPcmFrame *pcm;
            AudioAacFrame *aac;
        } frame;
    
        AudioFrame();
        ~AudioFrame();
        avsyncType avsync_type_;
        MEMORY_TYPE mType;
    };

    AudioPcmFrame

    The structure of AudioPcmFrame is as follows:

    class AudioPcmFrame {
        public:
        AudioPcmFrame(u64_t frame_ms, uint_t sample_rates, uint_t samples);
        ~AudioPcmFrame();
        public:
        u64_t frame_ms_;
        uint_t channels_; // 1
        uint_t sample_bits_; // 16
        uint_t sample_rates_; // 8k, 16k, 32k
        uint_t samples_;
    
        const uchar_t *pcmBuf_;
        uint_t pcmBufSize_;
    };
    Name Description
    frame_ms Timestamp of the frame.
    channels Number of audio channels.
    sample_bits Bitrate of the sampling data.
    sample_rates Sampling rate.
    samples Number of samples of the frame.
    pcmBuf Audio frame buffer.
    pcmBufSize Size of the audio frame buffer.

    AudioAacFrame

    The structure of AudioAacFrame:

    class AudioAacFrame {
        public:
        explicit AudioAacFrame(u64_t frame_ms);
        ~AudioAacFrame();
    
        const uchar_t *aacBuf_;
        u64_t frame_ms_;
        uint_t aacBufSize_;
    
    };
    Name Description
    frame_ms Timestamp of the frame.
    aacBuf Audio frame buffer.
    aacBufSize Size of the audio frame buffer.

    The Raw Video Data has Been Received (videoFrameReceived)

    This callback is triggered when the raw video data has been received.

    This callback is triggered for every received raw video frame and can be used to detect sexually explicit content, if necessary.

    Agora recommends capturing the i frame only and neglecting the others.

    virtual void videoFrameReceived(unsigned int uid, const agora::linuxsdk::VideoFrame *frame) const = 0;
    Name Description
    uid UID of the user.
    frame Received raw video data in YUV, H.264 or JPG format.

    The structure of VideoFrame:

    struct VideoFrame {
        VIDEO_FRAME_TYPE type;
        union {
            VideoYuvFrame *yuv;
            VideoH264Frame *h264;
            VideoJpgFrame *jpg;
        } frame;
    
        int rotation_; // 0, 90, 180, 270
        VideoFrame();
        ~VideoFrame();
    
        MEMORY_TYPE mType;
    };

    VideoYuvFrame

    The structure of VideoYuvFrame:

    class VideoYuvFrame {
        public:
        VideoYuvFrame(u64_t frame_ms, uint_t width, uint_t height, uint_t ystride,
                uint_t ustride, uint_t vstride);
        ~VideoYuvFrame();
    
        u64_t frame_ms_;
    
        const uchar_t *ybuf_;
        const uchar_t *ubuf_;
        const uchar_t *vbuf_;
    
        uint_t width_;
        uint_t height_;
    
        uint_t ystride_;
        uint_t ustride_;
        uint_t vstride_;
    
        //all
        const uchar_t *buf_;
        uint_t bufSize_;
    };
    Name Description
    frame_ms Timestamp of the frame.
    ybuf Y buffer pointer.
    ubuf U buffer pointer.
    vbuf V buffer pointer.
    width Width of the video in the number of pixels.
    height Height of the video in the number of pixels.
    ystride Line span of the Y buffer.
    ustride Line span of the U buffer.
    vstride Line span of the V buffer.
    buf Video frame buffer.
    bufSize Size of the video frame buffer.

    VideoH264Frame

    The structure of VideoH264Frame:

    struct VideoH264Frame {
        public:
        VideoH264Frame():
            frame_ms_(0),
            frame_num_(0),
            buf_(NULL),
            bufSize_(0)
        {}
    
        ~VideoH264Frame(){}
        u64_t frame_ms_;
        uint_t frame_num_;
    
        //all
        const uchar_t *buf_;
        uint_t bufSize_;
    };
    Name Description
    frame_ms Timestamp of the frame.
    frame_num Index of the frame.
    buf Video frame buffer.
    bufSize Size of the video frame buffer.

    VideoJpgFrame

    The structure of VideoJpgFrame:

    struct VideoJpgFrame {
        public:
        VideoJpgFrame():
            frame_ms_(0),
            buf_(NULL),
            bufSize_(0){}
    
       ~VideoJpgFrame() {}
        u64_t frame_ms_;
    
        //all
        const uchar_t *buf_;
        uint_t bufSize_;
    };
    Name Description
    frame_ms Timestamp of the frame.
    buf Video frame buffer.
    bufSize Size of the video frame buffer.

    Indicates the Speaker in the Channel (onActiveSpeaker)

    virtual void onActiveSpeaker(uid_t uid);

    This callback returns the user ID of the active speaker.

    Name Description
    uid The UID of the active speaker.

    Error Codes and Warning Codes

    See Error Codes and Warning Codes.