Agora RTC Objective-C API Reference  Refactor
Public Member Functions
IRtcEngineEx Class Referenceabstract

Inherits IRtcEngine.

Public Member Functions

virtual int joinChannelEx (const char *token, const RtcConnection &connection, const ChannelMediaOptions &options, IRtcEngineEventHandler *eventHandler)=0
 
virtual int leaveChannelEx (const RtcConnection &connection)=0
 
virtual int updateChannelMediaOptionsEx (const ChannelMediaOptions &options, const RtcConnection &connection)=0
 
virtual int getUserInfoByUserAccountEx (const char *userAccount, rtc::UserInfo *userInfo, const RtcConnection &connection)=0
 
virtual int getUserInfoByUidEx (uid_t uid, rtc::UserInfo *userInfo, const RtcConnection &connection)=0
 
virtual int setVideoProfileEx (int width, int height, int frameRate, int bitrate)=0
 
virtual int enableDualStreamModeEx (VIDEO_SOURCE_TYPE sourceType, bool enabled, const SimulcastStreamConfig &streamConfig, const RtcConnection &connection)=0
 
virtual void release (bool sync=false)=0
 
virtual int initialize (const RtcEngineContext &context)=0
 
virtual const char * getVersion (int *build)=0
 
virtual const char * getErrorDescription (int code)=0
 
virtual int joinChannel (const char *token, const char *channelId, const char *info, uid_t uid)=0
 
virtual int joinChannel (const char *token, const char *channelId, uid_t uid, const ChannelMediaOptions &options)=0
 
virtual int updateChannelMediaOptions (const ChannelMediaOptions &options)=0
 
virtual int leaveChannel ()=0
 
virtual int leaveChannel (const LeaveChannelOptions &options)=0
 
virtual int renewToken (const char *token)=0
 
virtual int setChannelProfile (CHANNEL_PROFILE_TYPE profile)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role, const ClientRoleOptions &options)=0
 
virtual int startEchoTest ()=0
 
virtual int startEchoTest (int intervalInSeconds)=0
 
virtual int enableVideo ()=0
 
virtual int disableVideo ()=0
 
virtual int startPreview ()=0
 
virtual int startPreview (VIDEO_SOURCE_TYPE sourceType)=0
 
virtual int stopPreview ()=0
 
virtual int stopPreview (VIDEO_SOURCE_TYPE sourceType)=0
 
virtual int startLastmileProbeTest (const LastmileProbeConfig &config)=0
 
virtual int stopLastmileProbeTest ()=0
 
virtual int setVideoEncoderConfiguration (const VideoEncoderConfiguration &config)=0
 
virtual int enableVirtualBackground (bool enabled, VirtualBackgroundSource backgroundSource)=0
 
virtual int enableRemoteSuperResolution (uid_t userId, bool enable)=0
 
virtual int setupRemoteVideo (const VideoCanvas &canvas)=0
 
virtual int setupLocalVideo (const VideoCanvas &canvas)=0
 
virtual int enableAudio ()=0
 
virtual int disableAudio ()=0
 
virtual int setAudioProfile (AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) 1=0
 
virtual int setAudioProfile (AUDIO_PROFILE_TYPE profile)=0
 
virtual int enableLocalAudio (bool enabled)=0
 
virtual int muteLocalAudioStream (bool mute)=0
 
virtual int muteAllRemoteAudioStreams (bool mute)=0
 
virtual int setDefaultMuteAllRemoteAudioStreams (bool mute) 1=0
 
virtual int muteRemoteAudioStream (uid_t uid, bool mute)=0
 
virtual int muteLocalVideoStream (bool mute)=0
 
virtual int enableLocalVideo (bool enabled)=0
 
virtual int muteAllRemoteVideoStreams (bool mute)=0
 
virtual int setDefaultMuteAllRemoteVideoStreams (bool mute) 1=0
 
virtual int muteRemoteVideoStream (uid_t uid, bool mute)=0
 
virtual int setRemoteVideoStreamType (uid_t uid, VIDEO_STREAM_TYPE streamType)=0
 
virtual int setRemoteDefaultVideoStreamType (VIDEO_STREAM_TYPE streamType)=0
 
virtual int enableAudioVolumeIndication (int interval, int smooth, bool reportVad)=0
 
virtual int startAudioRecording (const char *filePath, AUDIO_RECORDING_QUALITY_TYPE quality)=0
 
virtual int startAudioRecording (const char *filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality)=0
 
virtual int startAudioRecording (const AudioRecordingConfiguration &config)=0
 
virtual int registerAudioEncodedFrameObserver (const AudioEncodedFrameObserverConfig &config, IAudioEncodedFrameObserver *observer)=0
 
virtual int enableSoundPositionIndication (bool enabled)=0
 
virtual int setRemoteVoicePosition (uid_t uid, double pan, double gain)=0
 
virtual int enableSpatialAudio (bool enabled)=0
 
virtual int setVoiceBeautifierPreset (VOICE_BEAUTIFIER_PRESET preset)=0
 
virtual int setVoiceConversionPreset (VOICE_CONVERSION_PRESET preset)=0
 
virtual int setVoiceBeautifierParameters (VOICE_BEAUTIFIER_PRESET preset, int param1, int param2)=0
 
virtual int setVoiceConversionParameters (VOICE_CONVERSION_PRESET preset, int param1, int param2)=0
 
virtual int setLogFile (const char *filePath)=0
 
virtual int setLogFilter (unsigned int filter)=0
 
virtual int setLogLevel (commons::LOG_LEVEL level)=0
 
virtual int setLogFileSize (unsigned int fileSizeInKBytes)=0
 
virtual int uploadLogFile (agora::util::AString &requestId)=0
 
virtual int setLocalRenderMode (media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setLocalRenderMode (media::base::RENDER_MODE_TYPE renderMode)=0
 
virtual int setRemoteRenderMode (uid_t uid, media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setLocalVideoMirrorMode (VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int enableDualStreamMode (bool enabled)=0
 
virtual int enableDualStreamMode (VIDEO_SOURCE_TYPE sourceType, bool enabled)=0
 
virtual int enableDualStreamMode (VIDEO_SOURCE_TYPE sourceType, bool enabled, const SimulcastStreamConfig &streamConfig)=0
 
virtual int enableCustomAudioLocalPlayback (int sourceId, bool enabled)=0
 
virtual int startPrimaryCustomAudioTrack (const AudioTrackConfig &config)=0
 
virtual int stopPrimaryCustomAudioTrack ()=0
 
virtual int startSecondaryCustomAudioTrack (const AudioTrackConfig &config)=0
 
virtual int stopSecondaryCustomAudioTrack ()=0
 
virtual int setRecordingAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
 
virtual int setPlaybackAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
 
virtual int setMixedAudioFrameParameters (int sampleRate, int channel, int samplesPerCall)=0
 
virtual int setPlaybackAudioFrameBeforeMixingParameters (int sampleRate, int channel)=0
 
virtual int enableAudioSpectrumMonitor (int intervalInMS=100)=0
 
virtual int disableAudioSpectrumMonitor ()=0
 
virtual int registerAudioSpectrumObserver (agora::media::IAudioSpectrumObserver *observer)=0
 
virtual int unregisterAudioSpectrumObserver (agora::media::IAudioSpectrumObserver *observer)=0
 
virtual int adjustRecordingSignalVolume (int volume)=0
 
virtual int muteRecordingSignal (bool mute)=0
 
virtual int adjustPlaybackSignalVolume (int volume)=0
 
virtual int setLocalPublishFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
 
virtual int setRemoteSubscribeFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
 
virtual int enableLoopbackRecording (bool enabled, const char *deviceName=NULL)=0
 
virtual int adjustLoopbackRecordingVolume (int volume)=0
 
virtual int getLoopbackRecordingVolume ()=0
 
virtual int enableInEarMonitoring (bool enabled, int includeAudioFilters)=0
 
virtual int setInEarMonitoringVolume (int volume)=0
 
virtual int setExtensionProviderProperty (const char *provider, const char *key, const char *value)=0
 
virtual int enableExtension (const char *provider, const char *extension, bool enable=true, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
 
virtual int setExtensionProperty (const char *provider, const char *extension, const char *key, const char *value, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
 
virtual int getExtensionProperty (const char *provider, const char *extension, const char *key, char *value, int buf_len, agora::media::MEDIA_SOURCE_TYPE type=agora::media::UNKNOWN_MEDIA_SOURCE)=0
 
virtual int getCallId (agora::util::AString &callId)=0
 
virtual int rate (const char *callId, int rating, const char *description)=0
 
virtual int complain (const char *callId, const char *description)=0
 
virtual int setLiveTranscoding (const LiveTranscoding &transcoding)=0
 
virtual int startRtmpStreamWithoutTranscoding (const char *url)=0
 
virtual int startRtmpStreamWithTranscoding (const char *url, const LiveTranscoding &transcoding)=0
 
virtual int updateRtmpTranscoding (const LiveTranscoding &transcoding)=0
 
virtual int stopRtmpStream (const char *url)=0
 
virtual CONNECTION_STATE_TYPE getConnectionState ()=0
 
virtual int registerPacketObserver (IPacketObserver *observer)=0
 
virtual int enableEncryption (bool enabled, const EncryptionConfig &config)=0
 
virtual int createDataStream (int *streamId, bool reliable, bool ordered)=0
 
virtual int createDataStream (int *streamId, DataStreamConfig &config)=0
 
virtual int sendStreamMessage (int streamId, const char *data, size_t length)=0
 
virtual int addVideoWatermark (const RtcImage &watermark)=0
 
virtual int addVideoWatermark (const char *watermarkUrl, const WatermarkOptions &options)=0
 
virtual int clearVideoWatermark ()=0
 
virtual int enableWebSdkInteroperability (bool enabled) 1=0
 
virtual int sendCustomReportMessage (const char *id, const char *category, const char *event, const char *label, int value)=0
 
virtual int registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
 
virtual int unregisterMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
 
virtual int startAudioFrameDump (const char *channel_id, uid_t user_id, const char *location, const char *uuid, const char *passwd, long duration_ms, bool auto_upload)=0
 
virtual int registerLocalUserAccount (const char *appId, const char *userAccount)=0
 
virtual int joinChannelWithUserAccount (const char *token, const char *channelId, const char *userAccount)=0
 
virtual int joinChannelWithUserAccount (const char *token, const char *channelId, const char *userAccount, const ChannelMediaOptions &options)=0
 
virtual int joinChannelWithUserAccountEx (const char *token, const char *channelId, const char *userAccount, const ChannelMediaOptions &options, IRtcEngineEventHandler *eventHandler)=0
 
virtual int getUserInfoByUserAccount (const char *userAccount, rtc::UserInfo *userInfo)=0
 
virtual int getUserInfoByUid (uid_t uid, rtc::UserInfo *userInfo)=0
 
virtual int startChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int updateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int stopChannelMediaRelay ()=0
 
virtual int pauseAllChannelMediaRelay ()=0
 
virtual int resumeAllChannelMediaRelay ()=0
 
virtual int setDirectCdnStreamingAudioConfiguration (AUDIO_PROFILE_TYPE profile)=0
 
virtual int setDirectCdnStreamingVideoConfiguration (const VideoEncoderConfiguration &config)=0
 
virtual int startDirectCdnStreaming (IDirectCdnStreamingEventHandler *eventHandler, const char *publishUrl, const DirectCdnStreamingMediaOptions &options)=0
 
virtual int stopDirectCdnStreaming ()=0
 
virtual int updateDirectCdnStreamingMediaOptions (const DirectCdnStreamingMediaOptions &options)=0
 
virtual int pushDirectCdnStreamingCustomVideoFrame (media::base::ExternalVideoFrame *frame)=0
 
virtual int takeSnapshot (media::SnapShotConfig &config, media::ISnapshotCallback *callback)=0
 
virtual int SetContentInspect (media::ContentInspectConfig &config)=0
 
virtual int switchChannel (const char *token, const char *channel)=0
 
virtual int startRhythmPlayer (const char *sound1, const char *sound2, const AgoraRhythmPlayerConfig &config)=0
 
virtual int stopRhythmPlayer ()=0
 
virtual int configRhythmPlayer (const AgoraRhythmPlayerConfig &config)=0
 
virtual int setCloudProxy (CLOUD_PROXY_TYPE proxyType)=0
 
virtual int setLocalAccessPoint (const LocalAccessPointConfiguration &config)=0
 
virtual int enableFishCorrection (bool enabled, const FishCorrectionParams &params)=0
 
virtual int setAdvancedAudioOptions (media::base::AdvancedAudioOptions &options)=0
 
virtual int setAVSyncSource (const char *channelId, uid_t uid)=0
 

Member Function Documentation

◆ joinChannelEx()

virtual int joinChannelEx ( const char *  token,
const RtcConnection connection,
const ChannelMediaOptions options,
IRtcEngineEventHandler eventHandler 
)
pure virtual

Joins a channel with the connection ID.

You can call this method multiple times to join more than one channels at a time.

Note
  • If you are already in a channel, you cannot rejoin it with the same uid.
  • We recommend using different user IDs for different channels.
  • If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.
  • Ensure that the app ID you use to generate the token is the same with the app ID used when creating the RtcEngine instance.
Parameters
connectionRtcConnection
optionsThe channel media options: ChannelMediaOptions.
eventHandlerThe pointer to the IRtcEngine event handler: IRtcEngineEventHandler. you join the same channel multiple times.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ leaveChannelEx()

virtual int leaveChannelEx ( const RtcConnection connection)
pure virtual

Leaves the channel with the connection ID.

Parameters
connectionconnection.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ updateChannelMediaOptionsEx()

virtual int updateChannelMediaOptionsEx ( const ChannelMediaOptions options,
const RtcConnection connection 
)
pure virtual

Updates the channel media options after joining the channel.

Parameters
optionsThe channel media options: ChannelMediaOptions.
connectionRtcConnection.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ setVideoEncoderConfigurationEx()

virtual int setVideoEncoderConfigurationEx ( const VideoEncoderConfiguration config,
const RtcConnection connection 
)
pure virtual

◆ setupRemoteVideoEx()

virtual int setupRemoteVideoEx ( const VideoCanvas canvas,
const RtcConnection connection 
)
pure virtual

◆ muteRemoteAudioStreamEx()

virtual int muteRemoteAudioStreamEx ( uid_t  uid,
bool  mute,
const RtcConnection connection 
)
pure virtual

◆ muteRemoteVideoStreamEx()

virtual int muteRemoteVideoStreamEx ( uid_t  uid,
bool  mute,
const RtcConnection connection 
)
pure virtual

◆ setRemoteVideoStreamTypeEx()

virtual int setRemoteVideoStreamTypeEx ( uid_t  uid,
VIDEO_STREAM_TYPE  streamType,
const RtcConnection connection 
)
pure virtual

◆ setRemoteVoicePositionEx()

virtual int setRemoteVoicePositionEx ( uid_t  uid,
double  pan,
double  gain,
const RtcConnection connection 
)
pure virtual

◆ setRemoteRenderModeEx()

virtual int setRemoteRenderModeEx ( uid_t  uid,
media::base::RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode,
const RtcConnection connection 
)
pure virtual

◆ enableLoopbackRecordingEx()

virtual int enableLoopbackRecordingEx ( const RtcConnection connection,
bool  enabled,
const char *  deviceName = NULL 
)
pure virtual

◆ getConnectionStateEx()

virtual CONNECTION_STATE_TYPE getConnectionStateEx ( const RtcConnection connection)
pure virtual

◆ enableEncryptionEx()

virtual int enableEncryptionEx ( const RtcConnection connection,
bool  enabled,
const EncryptionConfig config 
)
pure virtual

◆ createDataStreamEx() [1/2]

virtual int createDataStreamEx ( int *  streamId,
bool  reliable,
bool  ordered,
const RtcConnection connection 
)
pure virtual

◆ createDataStreamEx() [2/2]

virtual int createDataStreamEx ( int *  streamId,
DataStreamConfig config,
const RtcConnection connection 
)
pure virtual

◆ sendStreamMessageEx()

virtual int sendStreamMessageEx ( int  streamId,
const char *  data,
size_t  length,
const RtcConnection connection 
)
pure virtual

◆ addVideoWatermarkEx()

virtual int addVideoWatermarkEx ( const char *  watermarkUrl,
const WatermarkOptions options,
const RtcConnection connection 
)
pure virtual

◆ clearVideoWatermarkEx()

virtual int clearVideoWatermarkEx ( const RtcConnection connection)
pure virtual

◆ sendCustomReportMessageEx()

virtual int sendCustomReportMessageEx ( const char *  id,
const char *  category,
const char *  event,
const char *  label,
int  value,
const RtcConnection connection 
)
pure virtual

◆ enableAudioVolumeIndicationEx()

virtual int enableAudioVolumeIndicationEx ( int  interval,
int  smooth,
bool  reportVad,
const RtcConnection connection 
)
pure virtual

◆ getUserInfoByUserAccountEx()

virtual int getUserInfoByUserAccountEx ( const char *  userAccount,
rtc::UserInfo userInfo,
const RtcConnection connection 
)
pure virtual

Gets the user information by passing in the user account. It is same as agora::rtc::IRtcEngine::getUserInfoByUserAccount.

Parameters
userAccountThe user account of the user. Ensure that you set this parameter.
[in,out]userInfoA userInfo object that identifies the user:
  • Input: A userInfo object.
  • Output: A userInfo object that contains the user account and user ID of the user.
connectionThe connection of the remote user account
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUidEx()

virtual int getUserInfoByUidEx ( uid_t  uid,
rtc::UserInfo userInfo,
const RtcConnection connection 
)
pure virtual

Gets the user information by passing in the user ID. It is same as agora::rtc::IRtcEngine::getUserInfoByUid.

Parameters
uidThe user ID of the remote user. Ensure that you set this parameter.
[in,out]userInfoA userInfo object that identifies the user:
  • Input: A userInfo object.
  • Output: A userInfo object that contains the user account and user ID of the user.
connectionThe connection of the remote user ID
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoProfileEx()

virtual int setVideoProfileEx ( int  width,
int  height,
int  frameRate,
int  bitrate 
)
pure virtual

Specify video stream parameters based on video profile

Parameters
[in]widthwidth of video resolution in pixel
[in]heightheight of video resolution in pixel
[in]frameRateframe rate in fps
[in]bitratebit rate in kbps
Returns
return 0 if success or an error code

◆ enableDualStreamModeEx()

virtual int enableDualStreamModeEx ( VIDEO_SOURCE_TYPE  sourceType,
bool  enabled,
const SimulcastStreamConfig streamConfig,
const RtcConnection connection 
)
pure virtual

Enables or disables the dual video stream mode.

If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) video using setRemoteVideoStreamType.

Parameters
sourceTypeThe video source type.
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
streamConfigThe minor stream config
connectionAn output parameter which is used to control different connection instances.

◆ release()

virtual void release ( bool  sync = false)
pure virtualinherited

Releases the IRtcEngine object.

Parameters
syncDetermines whether this method is a synchronous call.
  • true: This method is a synchronous call, which means that the result of this method call returns after the IRtcEngine object resources are released. Do not call this method in any callback generated by the SDK, or it may result in a deadlock. The SDK automatically detects the deadlock and turns this method into an asynchronous call, but the test itself takes extra time.
  • false: This method is an asynchronous call. The result returns immediately even when the IRtcEngine object resources are not released.
Note
  • Do not immediately uninstall the SDK's dynamic library after the call, or it may crash because the SDK clean-up thread has not quit.
  • Call this method in the sub-thread.
  • Once the app destroys the created IRtcEngine instance, you cannot use any method or callback in the SDK.

◆ initialize()

virtual int initialize ( const RtcEngineContext context)
pure virtualinherited

Initializes the Agora SDK service.

In this method, you need to enter the issued Agora App ID to start initialization. After creating an IRtcEngine object, call this method to initialize the service before calling any other methods. After the initialization, the service is set to enable audio by default.

Parameters
contextThe RtcEngineContext object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ queryInterface()

virtual int queryInterface ( INTERFACE_ID_TYPE  iid,
void **  inter 
)
pure virtualinherited

Implements IEngineBase.

◆ getVersion()

virtual const char* getVersion ( int *  build)
pure virtualinherited

Gets the SDK version.

Parameters
buildThe build number.
Returns
The version of the current SDK in the string format.

◆ getErrorDescription()

virtual const char* getErrorDescription ( int  code)
pure virtualinherited

Gets the warning or error description.

Parameters
codeThe warning or error code.
Returns
The detailed warning or error description.

◆ joinChannel() [1/2]

virtual int joinChannel ( const char *  token,
const char *  channelId,
const char *  info,
uid_t  uid 
)
pure virtualinherited

Joins a channel.

Users in the same channel can talk to each other; and multiple users in the same channel can start a group chat. Note that users using different App IDs cannot call each other.

Note
  • This method allows you to join only one channel at a time.
  • A channel does not accept duplicate uids, that is, two users with the same uid. If you set uid as 0, the system automatically assigns a user ID.
  • Ensure that the app ID you use to generate the token is the same app ID that you pass in the initialize method.
Parameters
tokenThe token for authentication.
  • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at you server. For details, see Generate a token.
channelIdThe unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
info(Optional) Additional information about the channel that you want to add. It can be set as a NULL string or channel related information. Other users in the channel will not receive this message.
uid(Optional) User ID: A 32-bit unsigned integer ranging from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK assigns one and reports it in the onJoinChannelSuccess callback. Your app must record and maintain the returned value as the SDK does not maintain it.
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannel() [2/2]

virtual int joinChannel ( const char *  token,
const char *  channelId,
uid_t  uid,
const ChannelMediaOptions options 
)
pure virtualinherited

Joins a channel with media options.

Users in the same channel can talk to each other; and multiple users in the same channel can start a group chat. Note that users using different App IDs cannot call each other.

Note
  • This method allows you to join only one channel at a time.
  • A channel does not accept duplicate uids, that is, two users with the same uid. If you set uid as 0, the system automatically assigns a user ID.
  • Ensure that the app ID you use to generate the token is the same app ID that you pass in the initialize method.
Parameters
tokenThe token for authentication.
  • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at you server. For details, see Generate a token.
channelIdThe unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
uid(Optional) User ID: A 32-bit unsigned integer ranging from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK assigns one and reports it in the onJoinChannelSuccess callback. Your app must record and maintain the returned value as the SDK does not maintain it.
optionsThe channel media options: ChannelMediaOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateChannelMediaOptions()

virtual int updateChannelMediaOptions ( const ChannelMediaOptions options)
pure virtualinherited

Updates the channel media options after joining the channel.

Parameters
optionsThe channel media options: ChannelMediaOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ leaveChannel() [1/2]

virtual int leaveChannel ( )
pure virtualinherited

Leaves the channel.

This method allows a user to leave the channel, for example, by hanging up or exiting a call.

This method is an asynchronous call, which means that the result of this method returns even before the user has not actually left the channel. Once the user successfully leaves the channel, the SDK triggers the onLeaveChannel callback.

Note
If you call release immediately after this method, the leaveChannel process will be interrupted, and the SDK will not trigger the onLeaveChannel callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ leaveChannel() [2/2]

virtual int leaveChannel ( const LeaveChannelOptions options)
pure virtualinherited

Leaves the channel.

Parameters
optionsThe leave channel options.

This method allows a user to leave the channel, for example, by hanging up or exiting a call.

This method is an asynchronous call, which means that the result of this method returns even before the user has not actually left the channel. Once the user successfully leaves the channel, the SDK triggers the onLeaveChannel callback.

Note
If you call release immediately after this method, the leaveChannel process will be interrupted, and the SDK will not trigger the onLeaveChannel callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ renewToken()

virtual int renewToken ( const char *  token)
pure virtualinherited

Renews the token.

Once a token is enabled and used, it expires after a certain period of time.

Under the following circumstances, generate a new token on your server, and then call this method to renew it. Failure to do so results in the SDK disconnecting from the server.

  • The IRtcEngineEventHandler onTokenPrivilegeWillExpire "onTokenPrivilegeWillExpire" callback is triggered;
  • The onRequestToken callback is triggered;
  • The ERR_TOKEN_EXPIRED(-109) error is reported.
Parameters
tokenThe new token.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setChannelProfile()

virtual int setChannelProfile ( CHANNEL_PROFILE_TYPE  profile)
pure virtualinherited

Sets the channel profile.

The IRtcEngine differentiates channel profiles and applies different optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for a video broadcast.

Note
  • To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile.
  • Call this method before calling joinChannel. You cannot set the channel profile once you have joined the channel.
Parameters
profileThe channel profile: CHANNEL_PROFILE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setClientRole() [1/2]

virtual int setClientRole ( CLIENT_ROLE_TYPE  role)
pure virtualinherited

Sets the role of a user.

This method sets the user role as either BROADCASTER or AUDIENCE (default).

  • The broadcaster sends and receives streams.
  • The audience receives streams only.

By default, all users are audience regardless of the channel profile. Call this method to change the user role to BROADCASTER so that the user can send a stream.

Note
After calling the setClientRole() method to CLIENT_ROLE_AUDIENCE, the SDK stops audio recording. However, CLIENT_ROLE_AUDIENCE will keep audio recording with AUDIO_SCENARIO_CHATROOM(5). Normally, app developer can also use mute api to achieve the same result, and we implement this 'non-orthogonal' behavior only to make API backward compatible.
Parameters
roleThe role of the client: CLIENT_ROLE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setClientRole() [2/2]

virtual int setClientRole ( CLIENT_ROLE_TYPE  role,
const ClientRoleOptions options 
)
pure virtualinherited

Sets the role of the user, such as a host or an audience (default), before joining a channel in the live interactive streaming.

This method can be used to switch the user role in the live interactive streaming after the user joins a channel.

In the LIVE_BROADCASTING profile, when a user switches user roles after joining a channel, a successful setClientRole method call triggers the following callbacks:

Note
This method applies only to the LIVE_BROADCASTING profile.
Parameters
roleSets the role of the user. See CLIENT_ROLE_TYPE.
optionsSets the audience latency level of the user. See #ClientRoleOptions.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ startEchoTest() [1/2]

virtual int startEchoTest ( )
pure virtualinherited

Starts an audio call test.

This method launches an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

In the test, the user first speaks, and the recording is played back in 10 seconds. If the user can hear the recording in 10 seconds, it indicates that the audio devices and network connection work properly.

Note
After calling the startEchoTest() method, always call stopEchoTest() to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannel() method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startEchoTest() [2/2]

virtual int startEchoTest ( int  intervalInSeconds)
pure virtualinherited

Starts an audio call test.

This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

In the audio call test, you record your voice. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.

Note
  • Call this method before joining a channel.
  • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or call the joinChannel method.
  • In the LIVE_BROADCASTING profile, only a host can call this method.
Parameters
intervalInSecondsThe time interval (s) between when you speak and when the recording plays back.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableVideo()

virtual int enableVideo ( )
pure virtualinherited

Enables the video.

You can call this method either before joining a channel or during a call. If you call this method before entering a channel, the service starts the video; if you call it during a call, the audio call switches to a video call.

Note
This method controls the underlying states of the Engine. It is still valid after one leaves the channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableVideo()

virtual int disableVideo ( )
pure virtualinherited

Disables the video.

This method stops capturing the local video and receiving any remote video. To enable the local preview function, call enableLocalVideo (true).

Returns
int
  • 0: Success.
  • < 0: Failure.

◆ startPreview() [1/2]

virtual int startPreview ( )
pure virtualinherited

Starts the local video preview before joining a channel.

Once you call this method to start the local video preview, if you leave the channel by calling leaveChannel, the local video preview remains until you call stopPreview to disable it.

Returns
  • 0: Success.
  • < 0: Failure.

◆ startPreview() [2/2]

virtual int startPreview ( VIDEO_SOURCE_TYPE  sourceType)
pure virtualinherited

Starts the local video preview for specific source type.

Parameters
sourceType- The video source type.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPreview() [1/2]

virtual int stopPreview ( )
pure virtualinherited

Stops the local video preview and the video.

Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPreview() [2/2]

virtual int stopPreview ( VIDEO_SOURCE_TYPE  sourceType)
pure virtualinherited

Stops the local video preview for specific source type.

Parameters
sourceType- The video source type.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startLastmileProbeTest()

virtual int startLastmileProbeTest ( const LastmileProbeConfig config)
pure virtualinherited

Starts the last-mile network probe test.

This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

Call this method to check the uplink network quality before users join a channel or before an audience switches to a host. Once this method is enabled, the SDK returns the following callbacks:

  • onLastmileQuality: the SDK triggers this callback depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
  • onLastmileProbeResult: the SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.
Note
  • Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
  • In the Live-broadcast profile, a host should not call this method after joining a channel.
Parameters
configSets the configurations of the last-mile network probe test. See LastmileProbeConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopLastmileProbeTest()

virtual int stopLastmileProbeTest ( )
pure virtualinherited

Stops the last-mile network probe test.

◆ setVideoEncoderConfiguration()

virtual int setVideoEncoderConfiguration ( const VideoEncoderConfiguration config)
pure virtualinherited

Sets the video encoder configuration.

Each configuration profile corresponds to a set of video parameters, including the resolution, frame rate, and bitrate.

The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

Parameters
configThe local video encoder configuration: VideoEncoderConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableVirtualBackground()

virtual int enableVirtualBackground ( bool  enabled,
VirtualBackgroundSource  backgroundSource 
)
pure virtualinherited

Enables/Disables the virtual background. (beta function)

Since
v3.7.200

After enabling the virtual background function, you can replace the original background image of the local user with a custom background image. After the replacement, all users in the channel can see the custom background image.

Note
  • Before calling this method, ensure that you have integrated the libagora_segmentation_extension.dll (Windows)/AgoraVideoSegmentationExtension.framework (macOS) dynamic library into the project folder.
  • Call this method after enableVideo.
  • This function requires a high-performance device. Agora recommends that you use this function on devices with an i5 CPU and better.
  • Agora recommends that you use this function in scenarios that meet the following conditions:
    • A high-definition camera device is used, and the environment is uniformly lit.
    • The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.
Parameters
enabledSets whether to enable the virtual background:
  • true: Enable.
  • false: Disable.
backgroundSourceThe custom background image. See VirtualBackgroundSource. Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableRemoteSuperResolution()

virtual int enableRemoteSuperResolution ( uid_t  userId,
bool  enable 
)
pure virtualinherited

Enables/Disables the super resolution feature for a remote user's video. (beta feature)

Since
v4.0.0

This feature effectively boosts the resolution of a remote user's video seen by the local user. If the original resolution of a remote user's video is a × b, the local user's device can render the remote video at a resolution of 2a × 2b after you enable this feature.

Warning
The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions:
  • This feature can only be enabled for a single remote user.
  • The original resolution of the remote user's video cannot exceed a certain range. If the local user use super resolution on Android, the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use super resolution on iOS, the original resolution of the remote user's video cannot exceed 640 × 480 pixels.
Note
  • This method is for Android and iOS only.
  • Before calling this method, ensure that you have integrated the following dynamic library into your project:
    • Android: libagora_super_resolution_extension.so
    • iOS: AgoraSuperResolutionExtension.xcframework
  • Because this method has certain system performance requirements, Agora recommends that you use the following devices or better:
    • Android:
      • VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro
      • OPPO: PCCM00, Find X3
      • OnePlus: A6000
      • Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro
      • SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21
      • HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8
    • iOS (iOS 12.0 or later):
      • iPhone XR
      • iPhone XS
      • iPhone XS Max
      • iPhone 11
      • iPhone 11 Pro
      • iPhone 11 Pro Max
      • iPhone 12
      • iPhone 12 mini
      • iPhone 12 Pro
      • iPhone 12 Pro Max
      • iPhone 12 SE (2nd generation)
      • iPad Pro 11-inch (3rd generation)
      • iPad Pro 12.9-inch (3rd generation)
      • iPad Air (3rd generation)
      • iPad Air (4th generation)
Parameters
userIdThe user ID of the remote user.
enableDetermines whether to enable super resolution for the remote user's video:
  • true: Enable super resolution.
  • false: Disable super resolution.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setupRemoteVideo()

virtual int setupRemoteVideo ( const VideoCanvas canvas)
pure virtualinherited

Initializes the video view of a remote user.

This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees.

Usually the app should specify the uid of the remote video in the method call before the remote user joins the channel. If the remote uid is unknown to the app, set it later when the app receives the onUserJoined callback.

To unbind the remote user from the view, set view in VideoCanvas as null.

Note
Ensure that you call this method in the UI thread.
Parameters
canvasThe remote video view settings: VideoCanvas.
Returns
int VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_SUCCESS = 0, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_IMAGE_NOT_EXIST = -1, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED = -2, VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_DEVICE_NOT_SUPPORTED = -3,

◆ setupLocalVideo()

virtual int setupLocalVideo ( const VideoCanvas canvas)
pure virtualinherited

Initializes the local video view.

This method initializes the video view of the local stream on the local device. It affects only the video view that the local user sees, not the published local video stream.

To unbind the local video from the view, set view in VideoCanvas as null.

Note
Call this method before joining a channel.
Parameters
canvasThe local video view setting: VideoCanvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudio()

virtual int enableAudio ( )
pure virtualinherited

Enables the audio.

The audio is enabled by default.

Note
This method controls the underlying states of the Engine. It is still valid after one leaves channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableAudio()

virtual int disableAudio ( )
pure virtualinherited

Disables the audio.

Note
This method controls the underlying states of the Engine. It is still valid after one leaves channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioProfile() [1/2]

virtual int setAudioProfile ( AUDIO_PROFILE_TYPE  profile,
AUDIO_SCENARIO_TYPE  scenario 
)
pure virtualinherited

Sets the audio parameters and application scenarios.

Deprecated:
This method is deprecated. You can use the setAudioProfile method instead. To set the audio scenario, call the initialize method and pass value in the audioScenario member in the RtcEngineContext struct.
Note
  • Call this method before calling the joinChannel method.
  • In scenarios requiring high-quality audio, we recommend setting profile as MUSIC_HIGH_QUALITY(4) and scenario as AUDIO_SCENARIO_GAME_STREAMING(3).
Parameters
profileSets the sample rate, bitrate, encoding mode, and the number of channels: AUDIO_PROFILE_TYPE.
scenarioSets the audio application scenarios: AUDIO_SCENARIO_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioProfile() [2/2]

virtual int setAudioProfile ( AUDIO_PROFILE_TYPE  profile)
pure virtualinherited

Sets the audio profile.

Note
  • Call this method before calling the joinChannel method.
  • In scenarios requiring high-quality audio, Agora recommends setting profile as MUSIC_HIGH_QUALITY(4).
  • To set the audio scenario, call the initialize method and pass value in the audioScenario member in the RtcEngineContext struct.
Parameters
profileThe audio profile, such as the sample rate, bitrate and codec type: AUDIO_PROFILE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLocalAudio()

virtual int enableLocalAudio ( bool  enabled)
pure virtualinherited

Enables or disables the local audio capture.

The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capture and processing.

This method does not affect receiving or playing the remote audio streams, and enableLocalAudio (false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel.

Parameters
enabledDetermines whether to disable or re-enable the local audio function:
  • true: (Default) Re-enable the local audio function, that is, to start local audio capture and processing.
  • false: Disable the local audio function, that is, to stop local audio capture and processing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalAudioStream()

virtual int muteLocalAudioStream ( bool  mute)
pure virtualinherited

Stops or resumes sending the local audio stream.

After calling this method successfully, the SDK triggers the onRemoteAudioStateChanged callback with the following parameters:

  • REMOTE_AUDIO_STATE_STOPPED(0) and REMOTE_AUDIO_REASON_REMOTE_MUTED(5).
  • REMOTE_AUDIO_STATE_DECODING(2) and REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6).
Note
  • When mute is set as true, this method does not disable the microphone, which does not affect any ongoing recording.
  • If you call setChannelProfile after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.
Parameters
muteDetermines whether to send or stop sending the local audio stream:
  • true: Stop sending the local audio stream.
  • false: (Default) Send the local audio stream.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteAudioStreams()

virtual int muteAllRemoteAudioStreams ( bool  mute)
pure virtualinherited

Stops or resumes receiving all remote audio stream.

This method works for all remote users that join or will join a channel using the joinChannel method. It is equivalent to the autoSubscribeAudio member in the ChannelMediaOptions class. You can call this method before, during, or after a call.

  • If you call muteAllRemoteAudioStreams(true) before joining a channel, the local user does not receive any audio stream after joining the channel.
  • If you call muteAllRemoteAudioStreams(true) after joining a channel, the local use stops receiving any audio stream from any user in the channel, including any user who joins the channel after you call this method.
  • If you call muteAllRemoteAudioStreams(true) after leaving a channel, the local user does not receive any audio stream the next time the user joins a channel.

After you successfully call muteAllRemoteAudioStreams(true), you can take the following actions:

  • To resume receiving all remote audio streams, call muteAllRemoteAudioStreams(false).
  • To resume receiving the audio stream of a specified user, call muteRemoteAudioStream(uid, false), where uid is the ID of the user whose audio stream you want to resume receiving.
Note
  • The result of calling this method is affected by calling enableAudio and disableAudio. Settings in muteAllRemoteAudioStreams stop taking effect if either of the following occurs:
    • Calling enableAudio after muteAllRemoteAudioStreams(true).
    • Calling disableAudio after muteAllRemoteAudioStreams(false).
  • This method only works for the channel created by calling joinChannel. To set whether to receive remote audio streams for a specific channel, Agora recommends using autoSubscribeAudio in the ChannelMediaOptions class.
Parameters
muteWhether to stop receiving remote audio streams:
  • true: Stop receiving any remote audio stream.
  • false: (Default) Resume receiving all remote audio streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteAudioStreams()

virtual int setDefaultMuteAllRemoteAudioStreams ( bool  mute)
pure virtualinherited

Determines whether to receive all remote audio streams by default.

Deprecated:
This method is deprecated. To set whether to receive remote audio streams by default, call muteAllRemoteAudioStreams before calling joinChannel

Use this method to set whether to receive audio streams of subsequent peer users. Agora recommends calling it before joining a channel.

A successful call of setDefaultMuteAllRemoteAudioStreams(true) results in that the local user not receiving any audio stream after joining a channel.

Parameters
muteWhether to receive remote audio streams by default:
  • true: Do not receive any remote audio stream by default.
  • false: (Default) Receive remote audio streams by default.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteAudioStream()

virtual int muteRemoteAudioStream ( uid_t  uid,
bool  mute 
)
pure virtualinherited

Stops or resumes receiving the audio stream of a specified user.

Note
You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.
Parameters
uidThe ID of the specified user.
muteWhether to stop receiving the audio stream of the specified user:
  • true: Stop receiving the audio stream of the specified user.
  • false: (Default) Resume receiving the audio stream of the specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteLocalVideoStream()

virtual int muteLocalVideoStream ( bool  mute)
pure virtualinherited

Stops or resumes sending the local video stream.

Parameters
muteDetermines whether to send or stop sending the local video stream:
  • true: Stop sending the local video stream.
  • false: (Default) Send the local video stream.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLocalVideo()

virtual int enableLocalVideo ( bool  enabled)
pure virtualinherited

Disables or re-enables the local video capture.

Once you enable the video using enableVideo, the local video is enabled by default. This method disables or re-enables the local video capture.

enableLocalVideo(false) applies to scenarios when the user wants to watch the remote video without sending any video stream to the other user.

Note
Call this method after enableVideo. Otherwise, this method may not work properly.
Parameters
enabledDetermines whether to disable or re-enable the local video, including the capturer, renderer, and sender:
  • true: (Default) Re-enable the local video.
  • false: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of other remote users. When you set enabled as false, this method does not require a local camera.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteVideoStreams()

virtual int muteAllRemoteVideoStreams ( bool  mute)
pure virtualinherited

Stops or resumes receiving all remote video streams.

This method works for all remote users that join or will join a channel using the joinChannel method. It is equivalent to the autoSubscribeVideo member in the ChannelMediaOptions class. You can call this method before, during, or after a call.

  • If you call muteAllRemoteVideoStreams(true) before joining a channel, the local user does not receive any video stream after joining the channel.
  • If you call muteAllRemoteVideoStreams(true) after joining a channel, the local use stops receiving any video stream from any user in the channel, including any user who joins the channel after you call this method.
  • If you call muteAllRemoteVideoStreams(true) after leaving a channel, the local user does not receive any video stream the next time the user joins a channel.

After you successfully call muteAllRemoteVideoStreams(true), you can take the following actions:

  • To resume receiving all remote video streams, call muteAllRemoteVideoStreams(false).
  • To resume receiving the video stream of a specified user, call muteRemoteVideoStream(uid, false), where uid is the ID of the user whose video stream you want to resume receiving.
Note
  • The result of calling this method is affected by calling enableVideo and disableVideo. Settings in muteAllRemoteVideoStreams stop taking effect if either of the following occurs:
    • Calling enableVideo after muteAllRemoteVideoStreams(true).
    • Calling disableVideo after muteAllRemoteVideoStreams(false).
  • This method only works for the channel created by calling joinChannel. To set whether to receive remote audio streams for a specific channel, Agora recommends using autoSubscribeVideo in the ChannelMediaOptions class.
Parameters
muteWhether to stop receiving remote video streams:
  • true: Stop receiving any remote video stream.
  • false: (Default) Resume receiving all remote video streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteVideoStreams()

virtual int setDefaultMuteAllRemoteVideoStreams ( bool  mute)
pure virtualinherited

Determines whether to receive all remote video streams by default.

Deprecated:
This method is deprecated. To set whether to receive remote video streams by default, call muteAllRemoteVideoStreams before calling joinChannel.

Use this method to set whether to receive video streams of subsequent peer users. Agora recommends calling it before joining a channel.

A successful call of setDefaultMuteAllRemoteVideoStreams(true) results in that the local user not receiving any video stream after joining a channel.

Parameters
muteWhether to receive remote video streams by default:
  • true: Do not receive any remote video stream by default.
  • false: (Default) Receive remote video streams by default.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteVideoStream()

virtual int muteRemoteVideoStream ( uid_t  uid,
bool  mute 
)
pure virtualinherited

Stops or resumes receiving the video stream of a specified user.

Note
You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.
Parameters
uidThe ID of the specified user.
muteWhether to stop receiving the video stream of the specified user:
  • true: Stop receiving the video stream of the specified user.
  • false: (Default) Resume receiving the video stream of the specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVideoStreamType()

virtual int setRemoteVideoStreamType ( uid_t  uid,
VIDEO_STREAM_TYPE  streamType 
)
pure virtualinherited

Sets the remote video stream type.

If the remote user has enabled the dual-stream mode, by default the SDK receives the high-stream video by Call this method to switch to the low-stream video.

Note
This method applies to scenarios where the remote user has enabled the dual-stream mode using enableDualStreamMode(true) before joining the channel.
Parameters
uidID of the remote user sending the video stream.
streamTypeSets the video stream type: VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteDefaultVideoStreamType()

virtual int setRemoteDefaultVideoStreamType ( VIDEO_STREAM_TYPE  streamType)
pure virtualinherited

Sets the default stream type of the remote video if the remote user has enabled dual-stream.

Parameters
streamTypeSets the default video stream type: VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudioVolumeIndication()

virtual int enableAudioVolumeIndication ( int  interval,
int  smooth,
bool  reportVad 
)
pure virtualinherited

Enables the onAudioVolumeIndication callback to report on which users are speaking and the speakers' volume.

Once the onAudioVolumeIndication callback is enabled, the SDK returns the volume indication in the at the time interval set in enableAudioVolumeIndication, regardless of whether any user is speaking in the channel.

Parameters
intervalSets the time interval between two consecutive volume indications:
  • ≤ 0: Disables the volume indication.
  • > 0: Time interval (ms) between two consecutive volume indications, and should be integral multiple of 200 (less than 200 will be set to 200).
smoothThe smoothing factor that sets the sensitivity of the audio volume indicator. The value range is [0, 10]. The greater the value, the more sensitive the indicator. The recommended value is 3.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [1/3]

virtual int startAudioRecording ( const char *  filePath,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)
pure virtualinherited

Starts an audio recording.

The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity
  • .aac: Small file size with low sound fidelity

Ensure that the directory to save the recording file exists and is writable. This method is usually called after the joinChannel() method. The recording automatically stops when the leaveChannel() method is called.

Parameters
filePathFull file path of the recording file. The string of the file name is in UTF-8 code.
qualitySets the audio recording quality: AUDIO_RECORDING_QUALITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [2/3]

virtual int startAudioRecording ( const char *  filePath,
int  sampleRate,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)
pure virtualinherited

Starts an audio recording.

The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity
  • .aac: Small file size with low sound fidelity

Ensure that the directory to save the recording file exists and is writable. This method is usually called after the joinChannel() method. The recording automatically stops when the leaveChannel() method is called.

Parameters
filePathFull file path of the recording file. The string of the file name is in UTF-8 code.
sampleRateSample rate, value should be 16000, 32000, 44100, or 48000.
qualitySets the audio recording quality: AUDIO_RECORDING_QUALITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioRecording() [3/3]

virtual int startAudioRecording ( const AudioRecordingConfiguration config)
pure virtualinherited

Starts an audio recording.

The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity
  • .aac: Small file size with low sound fidelity

Ensure that the directory to save the recording file exists and is writable. This method is usually called after the joinChannel() method. The recording automatically stops when the leaveChannel() method is called.

Parameters
configAudio recording config.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerAudioEncodedFrameObserver()

virtual int registerAudioEncodedFrameObserver ( const AudioEncodedFrameObserverConfig config,
IAudioEncodedFrameObserver observer 
)
pure virtualinherited

register encoded audio frame observer

Returns
  • 0: Success.
  • < 0: Failure.

◆ destroyMediaPlayer()

virtual int destroyMediaPlayer ( agora_refptr< IMediaPlayer >  media_player)
pure virtualinherited

◆ enableSoundPositionIndication()

virtual int enableSoundPositionIndication ( bool  enabled)
pure virtualinherited

Enables/Disables stereo panning for remote users.

Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition.

Parameters
enabledSets whether or not to enable stereo panning for remote users:
  • true: enables stereo panning.
  • false: disables stereo panning.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVoicePosition()

virtual int setRemoteVoicePosition ( uid_t  uid,
double  pan,
double  gain 
)
pure virtualinherited

Sets the sound position and gain of a remote user.

When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.

Note
  • For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
  • This method requires hardware support. For the best sound positioning, we recommend using a wired headset.
  • Ensure that you call this method after joining a channel.
Parameters
uidThe ID of the remote user.
panThe sound position of the remote user. The value ranges from -1.0 to 1.0:
  • 0.0: the remote sound comes from the front.
  • -1.0: the remote sound comes from the left.
  • 1.0: the remote sound comes from the right.
gainGain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableSpatialAudio()

virtual int enableSpatialAudio ( bool  enabled)
pure virtualinherited

enable spatial audio

Parameters
enabledenable/disable spatial audio:
  • true: enable spatial audio.
  • false: disable spatial audio.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceBeautifierPreset()

virtual int setVoiceBeautifierPreset ( VOICE_BEAUTIFIER_PRESET  preset)
pure virtualinherited

Sets an SDK preset voice beautifier effect.

Call this method to set an SDK preset voice beautifier effect for the local user who sends an audio stream. After setting a voice beautifier effect, all users in the channel can hear the effect.

You can set different voice beautifier effects for different scenarios. See Set the Voice Beautifier and Audio Effects.

To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.

Note
  • You can call this method either before or after joining a channel.
  • Do not set the profile parameter of setAudioProfile to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6); otherwise, this method call fails.
  • This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  • After calling this method, Agora recommends not calling the following methods, because they can override setAudioEffectParameters:
Parameters
presetThe options for SDK preset voice beautifier effects: VOICE_BEAUTIFIER_PRESET.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceConversionPreset()

virtual int setVoiceConversionPreset ( VOICE_CONVERSION_PRESET  preset)
pure virtualinherited

Sets an SDK preset voice conversion.

Call this method to set an SDK preset voice conversion for the local user who sends an audio stream. After setting an voice conversion, all users in the channel can hear the effect.

You can set different voice conversion for different scenarios. See Set the Voice Beautifier and Audio Effects.

To achieve better voice conversion quality, Agora recommends calling setAudioProfile and setting the scenario parameter to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.

Note
  • You can call this method either before or after joining a channel.
  • Do not set the profile parameter of setAudioProfile to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6); otherwise, this method call fails.
  • This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  • If you call this method and set the preset parameter to enumerators,
  • After calling this method, Agora recommends not calling the following methods, because they can override setVoiceConversionPreset:
Parameters
presetThe options for SDK preset voice conversion. See VOICE_CONVERSION_PRESET.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceBeautifierParameters()

virtual int setVoiceBeautifierParameters ( VOICE_BEAUTIFIER_PRESET  preset,
int  param1,
int  param2 
)
pure virtualinherited

Sets parameters for SDK preset voice beautifier effects.

Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream.

After you call this method successfully, all users in the channel can hear the relevant effect.

To achieve better audio effect quality, before you call this method, Agora recommends calling setAudioProfile, and setting the scenario parameter as AUDIO_SCENARIO_GAME_STREAMING(3) and the profile parameter as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).

Note
  • You can call this method either before or after joining a channel.
  • Do not set the profile parameter of setAudioProfile as AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6); otherwise, this method call does not take effect.
  • This method works best with the human voice. Agora does not recommend using this method for audio containing music.
  • After you call this method, Agora recommends not calling the following methods, because they can override setVoiceBeautifierParameters:
    • setAudioEffectPreset
    • setAudioEffectParameters
    • setVoiceBeautifierPreset
    • setLocalVoicePitch
    • setLocalVoiceEqualization
    • setLocalVoiceReverb
Parameters
presetThe options for SDK preset voice beautifier effects:
  • SINGING_BEAUTIFIER: Singing beautifier effect.
param1The gender characteristics options for the singing voice:
  • 1: A male-sounding voice.
  • 2: A female-sounding voice.
param2The reverberation effects options:
  • 1: The reverberation effect sounds like singing in a small room.
  • 2: The reverberation effect sounds like singing in a large room.
  • 3: The reverberation effect sounds like singing in a hall.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVoiceConversionParameters()

virtual int setVoiceConversionParameters ( VOICE_CONVERSION_PRESET  preset,
int  param1,
int  param2 
)
pure virtualinherited

Set parameters for SDK preset voice conversion.

Note
  • reserved interface
Parameters
presetThe options for SDK preset audio effects. See VOICE_CONVERSION_PRESET.
param1reserved.
param2reserved.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFile()

virtual int setLogFile ( const char *  filePath)
pure virtualinherited

DEPRECATED Specifies an SDK output log file.

The log file records all log data for the SDK’s operation. Ensure that the directory for the log file exists and is writable.

Note
Ensure that you call this method immediately after initialize, or the output log may not be complete.
Parameters
filePathFile path of the log file. The string of the log file is in UTF-8.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFilter()

virtual int setLogFilter ( unsigned int  filter)
pure virtualinherited

Sets the output log filter level of the SDK.

You can use one or a combination of the filters. The log filter level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a filter level and you will see logs preceding that filter level. For example, if you set the log filter level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Parameters
filterThe log filter level:
  • LOG_FILTER_DEBUG(0x80f): Output all API logs. Set your log filter as DEBUG if you want to get the most complete log file.
  • LOG_FILTER_INFO(0x0f): Output logs of the CRITICAL, ERROR, WARNING, and INFO level. We recommend setting your log filter as this level.
  • LOG_FILTER_WARNING(0x0e): Output logs of the CRITICAL, ERROR, and WARNING level.
  • LOG_FILTER_ERROR(0x0c): Output logs of the CRITICAL and ERROR level.
  • LOG_FILTER_CRITICAL(0x08): Output logs of the CRITICAL level.
  • LOG_FILTER_OFF(0): Do not output any log.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogLevel()

virtual int setLogLevel ( commons::LOG_LEVEL  level)
pure virtualinherited

Sets the output log level of the SDK.

You can set the SDK to ouput the log files of the specified level.

Parameters
levelThe log level:
  • LOG_LEVEL_NONE (0x0000): Do not output any log file.
  • LOG_LEVEL_INFO (0x0001): (Recommended) Output log files of the INFO level.
  • LOG_LEVEL_WARN (0x0002): Output log files of the WARN level.
  • LOG_LEVEL_ERROR (0x0004): Output log files of the ERROR level.
  • LOG_LEVEL_FATAL (0x0008): Output log files of the FATAL level.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFileSize()

virtual int setLogFileSize ( unsigned int  fileSizeInKBytes)
pure virtualinherited

Sets the log file size (KB).

The SDK has two log files, each with a default size of 512 KB. If you set fileSizeInBytes as 1024 KB, the SDK outputs log files with a total maximum size of 2 MB. If the total size of the log files exceed the set value, the new output log files overwrite the old output log files.

Parameters
fileSizeInKBytesThe SDK log file size (KB).
Returns
  • 0: Success.
  • < 0: Failure.

◆ uploadLogFile()

virtual int uploadLogFile ( agora::util::AString requestId)
pure virtualinherited

Upload current log file immediately to server. only use this when an error occurs block before log file upload success or timeout.

Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalRenderMode() [1/2]

virtual int setLocalRenderMode ( media::base::RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode 
)
pure virtualinherited

Updates the display mode of the local video view.

After initializing the local video view, you can call this method to update its rendering mode. It affects only the video view that the local user sees, not the published local video stream.

Note
  • Ensure that you have called setupLocalVideo to initialize the local video view before this method.
  • During a call, you can call this method as many times as necessary to update the local video view.
Parameters
renderModeSets the local display mode. See #RENDER_MODE_TYPE.
mirrorModeSets the local mirror mode. See VIDEO_MIRROR_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalRenderMode() [2/2]

virtual int setLocalRenderMode ( media::base::RENDER_MODE_TYPE  renderMode)
pure virtualinherited

Updates the display mode of the local video view.

After initializing the local video view, you can call this method to update its rendering mode. It affects only the video view that the local user sees, not the published local video stream.

Note
  • Ensure that you have called setupLocalVideo to initialize the local video view before this method.
  • During a call, you can call this method as many times as necessary to update the local video view.
Parameters
renderModeSets the local display mode. See #RENDER_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteRenderMode()

virtual int setRemoteRenderMode ( uid_t  uid,
media::base::RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode 
)
pure virtualinherited

Updates the display mode of the video view of a remote user.

After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.

Note
  • Ensure that you have called setupRemoteVideo to initialize the remote video view before calling this method.
  • During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.
Parameters
uidID of the remote user.
renderModeSets the remote display mode. See #RENDER_MODE_TYPE.
mirrorModeSets the mirror type. See VIDEO_MIRROR_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLocalVideoMirrorMode()

virtual int setLocalVideoMirrorMode ( VIDEO_MIRROR_MODE_TYPE  mirrorMode)
pure virtualinherited

Sets the local video mirror mode.

Use this method before calling the startPreview method, or the mirror mode does not take effect until you call the startPreview method again.

Parameters
mirrorModeSets the local video mirror mode. See VIDEO_MIRROR_MODE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDualStreamMode() [1/3]

virtual int enableDualStreamMode ( bool  enabled)
pure virtualinherited

Enables or disables the dual video stream mode.

If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) video using setRemoteVideoStreamType.

Parameters
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDualStreamMode() [2/3]

virtual int enableDualStreamMode ( VIDEO_SOURCE_TYPE  sourceType,
bool  enabled 
)
pure virtualinherited

Enables or disables the dual video stream mode.

If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) video using setRemoteVideoStreamType.

Parameters
sourceType
  • The video source type.
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableDualStreamMode() [3/3]

virtual int enableDualStreamMode ( VIDEO_SOURCE_TYPE  sourceType,
bool  enabled,
const SimulcastStreamConfig streamConfig 
)
pure virtualinherited

Enables or disables the dual video stream mode.

If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) video using setRemoteVideoStreamType.

Parameters
sourceType
  • The video source type.
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
streamConfig
  • The minor stream config
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableEchoCancellationExternal()

virtual int enableEchoCancellationExternal ( bool  enabled,
int  audioSourceDelay 
)
pure virtualinherited

◆ enableCustomAudioLocalPlayback()

virtual int enableCustomAudioLocalPlayback ( int  sourceId,
bool  enabled 
)
pure virtualinherited

Sets the external audio source.

Note
Ensure that you call this method before joining the channel.
Parameters
sourceIdcustom audio source id.
enabledDetermines whether to local playback the external audio source:
  • true: Local playback the external audio source.
  • false: Local don`t playback the external audio source.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startPrimaryCustomAudioTrack()

virtual int startPrimaryCustomAudioTrack ( const AudioTrackConfig config)
pure virtualinherited

Start primary custom audio track local playback.

Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPrimaryCustomAudioTrack()

virtual int stopPrimaryCustomAudioTrack ( )
pure virtualinherited

Stop primary custom audio track local playback.

Returns
  • 0: Success.
  • < 0: Failure.

◆ startSecondaryCustomAudioTrack()

virtual int startSecondaryCustomAudioTrack ( const AudioTrackConfig config)
pure virtualinherited

Start secondary custom audio track local playback.

Returns
  • 0: Success.
  • < 0: Failure.

◆ stopSecondaryCustomAudioTrack()

virtual int stopSecondaryCustomAudioTrack ( )
pure virtualinherited

Stop secondary custom audio track local playback.

Returns
  • 0: Success.
  • < 0: Failure.

◆ setRecordingAudioFrameParameters()

virtual int setRecordingAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
pure virtualinherited

Sets the audio recording format for the onRecordAudioFrame callback.

Parameters
sampleRateThe sample rate (Hz) of the audio data returned in the onRecordAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelThe number of audio channels of the audio data returned in the onRecordAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono.
  • 2: Stereo.
modeThis mode is deprecated.
samplesPerCallnot support. Sampling points in the called data returned in onRecordAudioFrame(). For example, it is usually set as 1024 for stream pushing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setPlaybackAudioFrameParameters()

virtual int setPlaybackAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
pure virtualinherited

Sets the audio playback format for the onPlaybackAudioFrame callback.

Parameters
sampleRateSets the sample rate (Hz) of the audio data returned in the onPlaybackAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelThe number of channels of the audio data returned in the onPlaybackAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
modeDeprecated. The use mode of the onPlaybackAudioFrame() callback: agora::rtc::RAW_AUDIO_FRAME_OP_MODE_TYPE.
samplesPerCallnot support. Sampling points in the called data returned in onPlaybackAudioFrame(). For example, it is usually set as 1024 for stream pushing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setMixedAudioFrameParameters()

virtual int setMixedAudioFrameParameters ( int  sampleRate,
int  channel,
int  samplesPerCall 
)
pure virtualinherited

Sets the mixed audio format for the onMixedAudioFrame callback.

Parameters
sampleRateThe sample rate (Hz) of the audio data returned in the onMixedAudioFrame callback, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelThe number of channels of the audio data in onMixedAudioFrame callback, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
samplesPerCallnot support. Sampling points in the called data returned in onMixedAudioFrame. For example, it is usually set as 1024 for stream pushing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setPlaybackAudioFrameBeforeMixingParameters()

virtual int setPlaybackAudioFrameBeforeMixingParameters ( int  sampleRate,
int  channel 
)
pure virtualinherited

Sets the audio playback format before mixing in the onPlaybackAudioFrameBeforeMixing callback.

Parameters
sampleRateThe sample rate (Hz) of the audio data returned in onPlaybackAudioFrameBeforeMixing, which can set be as 8000, 16000, 32000, 44100, or 48000.
channelNumber of channels of the audio data returned in onPlaybackAudioFrameBeforeMixing, which can be set as 1 or 2:
  • 1: Mono
  • 2: Stereo
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudioSpectrumMonitor()

virtual int enableAudioSpectrumMonitor ( int  intervalInMS = 100)
pure virtualinherited

Enable the audio spectrum monitor.

Parameters
intervalInMSSets the time interval(ms) between two consecutive audio spectrum callback. The default value is 100. This param should be larger than 10.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableAudioSpectrumMonitor()

virtual int disableAudioSpectrumMonitor ( )
pure virtualinherited

Disalbe the audio spectrum monitor.

Returns
  • 0: Success.
  • < 0: Failure.

◆ registerAudioSpectrumObserver()

virtual int registerAudioSpectrumObserver ( agora::media::IAudioSpectrumObserver observer)
pure virtualinherited

Registers an audio spectrum observer.

You need to implement the IAudioSpectrumObserver class in this method, and register the following callbacks according to your scenario:

  • onAudioSpectrumComputed: Occurs when the SDK receives the audio data and at set intervals.
Parameters
observerA pointer to the audio spectrum observer: IAudioSpectrumObserver.
Returns
  • 0: Success.
  • < 0: Failure.

◆ unregisterAudioSpectrumObserver()

virtual int unregisterAudioSpectrumObserver ( agora::media::IAudioSpectrumObserver observer)
pure virtualinherited

Releases the audio spectrum observer.

Parameters
observerThe pointer to the audio spectrum observer: IAudioSpectrumObserver.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustRecordingSignalVolume()

virtual int adjustRecordingSignalVolume ( int  volume)
pure virtualinherited

Adjusts the recording volume.

Parameters
volumeThe recording volume, which ranges from 0 to 400:
  • 0: Mute the recording volume.
  • 100: The Original volume.
  • 400: (Maximum) Four times the original volume with signal clipping protection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRecordingSignal()

virtual int muteRecordingSignal ( bool  mute)
pure virtualinherited

Mute or resume recording signal volume.

Parameters
muteDetermines whether to mute or resume the recording signal volume.
  • true: Mute the recording signal volume.
  • false: (Default) Resume the recording signal volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustPlaybackSignalVolume()

virtual int adjustPlaybackSignalVolume ( int  volume)
pure virtualinherited

Adjusts the playback volume.

Parameters
volumeThe playback volume, which ranges from 0 to 400:
  • 0: Mute the recoridng volume.
  • 100: The Original volume.
  • 400: (Maximum) Four times the original volume with signal clipping protection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustUserPlaybackSignalVolume()

virtual int adjustUserPlaybackSignalVolume ( unsigned int  uid,
int  volume 
)
pure virtualinherited

◆ setLocalPublishFallbackOption()

virtual int setLocalPublishFallbackOption ( STREAM_FALLBACK_OPTIONS  option)
pure virtualinherited

Sets the fallback option for the published video stream based on the network conditions.

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), the SDK will:

  • Disable the upstream video but enable audio only when the network conditions deteriorate and cannot support both video and audio.
  • Re-enable the video when the network conditions improve.

When the published video stream falls back to audio only or when the audio-only stream switches back to the video, the SDK triggers the onLocalPublishFallbackToAudioOnly callback.

Note
  • Agora does not recommend using this method for CDN live streaming, because the remote CDN live user will have a noticeable lag when the published video stream falls back to audio only.
  • Ensure that you call this method before joining a channel.
Parameters
optionSets the fallback option for the published video stream:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteSubscribeFallbackOption()

virtual int setRemoteSubscribeFallbackOption ( STREAM_FALLBACK_OPTIONS  option)
pure virtualinherited

Sets the fallback option for the remotely subscribed video stream based on the network conditions.

The default setting for option is STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1), where the remotely subscribed video stream falls back to the low-stream video (low resolution and low bitrate) under poor downlink network conditions.

If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), the SDK automatically switches the video from a high-stream to a low-stream, or disables the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and restores the video stream when the network conditions improve.

When the remotely subscribed video stream falls back to audio only or when the audio-only stream switches back to the video stream, the SDK triggers the onRemoteSubscribeFallbackToAudioOnly callback.

Note
Ensure that you call this method before joining a channel.
Parameters
optionSets the fallback option for the remotely subscribed video stream. See STREAM_FALLBACK_OPTIONS.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLoopbackRecording()

virtual int enableLoopbackRecording ( bool  enabled,
const char *  deviceName = NULL 
)
pure virtualinherited

Enables loopback recording.

If you enable loopback recording, the output of the default sound card is mixed into the audio stream sent to the other end.

Note
This method is for Windows only.
Parameters
enabledSets whether to enable/disable loopback recording.
  • true: Enable loopback recording.
  • false: (Default) Disable loopback recording.
deviceNamePointer to the device name of the sound card. The default value is NULL (the default sound card).
  • This method is for macOS and Windows only.
  • macOS does not support loopback capturing of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustLoopbackRecordingVolume()

virtual int adjustLoopbackRecordingVolume ( int  volume)
pure virtualinherited

Adjusts the loopback recording volume.

Parameters
volumeThe loopback volume, which ranges from 0 to 100:
  • 0: Mute the recoridng volume.
  • 100: The Original volume. protection.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getLoopbackRecordingVolume()

virtual int getLoopbackRecordingVolume ( )
pure virtualinherited

Retrieves the audio volume for recording loopback.

Note
Call this method when you are in a channel.
Returns
  • ≥ 0: The audio volume for loopback, if this method call succeeds. The value range is [0,100].
  • < 0: Failure.

◆ enableInEarMonitoring()

virtual int enableInEarMonitoring ( bool  enabled,
int  includeAudioFilters 
)
pure virtualinherited

Enables in-ear monitoring (for Android and iOS only).

Parameters
enabledDetermines whether to enable in-ear monitoring.
  • true: Enable.
  • false: (Default) Disable.
includeAudioFiltersThe type of the ear monitoring: EAR_MONITORING_FILTER_TYPE
Returns
  • 0: Success.
  • < 0: Failure.

◆ setInEarMonitoringVolume()

virtual int setInEarMonitoringVolume ( int  volume)
pure virtualinherited

Sets the volume of the in-ear monitor (for Android and iOS only).

Parameters
volumeSets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExtensionProviderProperty()

virtual int setExtensionProviderProperty ( const char *  provider,
const char *  key,
const char *  value 
)
pure virtualinherited

Set extension provider specific property.

Parameters
providername for provider, e.g. agora.io.
keykey for the property.
valueproperty value of json format.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableExtension()

virtual int enableExtension ( const char *  provider,
const char *  extension,
bool  enable = true,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::UNKNOWN_MEDIA_SOURCE 
)
pure virtualinherited

Enable/Disable extension.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
enableenable or disable.
  • true: enable.
  • false: disable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExtensionProperty()

virtual int setExtensionProperty ( const char *  provider,
const char *  extension,
const char *  key,
const char *  value,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::UNKNOWN_MEDIA_SOURCE 
)
pure virtualinherited

Set extension specific property.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
keykey for the property.
valueproperty value of json format.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getExtensionProperty()

virtual int getExtensionProperty ( const char *  provider,
const char *  extension,
const char *  key,
char *  value,
int  buf_len,
agora::media::MEDIA_SOURCE_TYPE  type = agora::media::UNKNOWN_MEDIA_SOURCE 
)
pure virtualinherited

Get extension specific property.

Parameters
providername for provider, e.g. agora.io.
extensionname for extension, e.g. agora.beauty.
keykey for the property.
valueproperty value of json format.
buf_lenmax length of the json value buffer
Returns
  • 0: Success.
  • < 0: Failure.

◆ getCallId()

virtual int getCallId ( agora::util::AString callId)
pure virtualinherited

Gets the current call ID.

When a user joins a channel on a client, a callId is generated to identify the call.

After a call ends, you can call rate or complain to gather feedback from the customer. These methods require a callId parameter. To use these feedback methods, call the this method first to retrieve the callId during the call, and then pass the value as an argument in the rate or complain method after the call ends.

Parameters
callIdThe reference to the call ID.
Returns
  • The call ID if the method call is successful.
  • < 0: Failure.

◆ rate()

virtual int rate ( const char *  callId,
int  rating,
const char *  description 
)
pure virtualinherited

Allows a user to rate the call.

It is usually called after the call ends.

Parameters
callIdThe call ID retrieved from the getCallId method.
ratingThe rating of the call between 1 (the lowest score) to 5 (the highest score).
description(Optional) The description of the rating. The string length must be less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ complain()

virtual int complain ( const char *  callId,
const char *  description 
)
pure virtualinherited

Allows a user to complain about the call quality.

This method is usually called after the call ends.

Parameters
callIdThe call ID retrieved from the getCallId method.
description(Optional) The description of the complaint. The string length must be less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLiveTranscoding()

virtual int setLiveTranscoding ( const LiveTranscoding transcoding)
pure virtualinherited

Sets the video layout and audio settings for CDN live.

The SDK triggers the onTranscodingUpdated callback when you call this method to update the LiveTranscodingclass. If you call this method to set the LiveTranscoding class for the first time, the SDK does not trigger the onTranscodingUpdated callback.

Note
Before calling the methods listed in this section:
  • This method applies to Live Broadcast only.
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • Ensure that you call the setClientRole method and set the user role as the host.
  • Ensure that you call the setLiveTranscoding method before addPublishStreamUrl method.
Parameters
transcodingSets the CDN live audio and video transcoding settings: LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startRtmpStreamWithoutTranscoding()

virtual int startRtmpStreamWithoutTranscoding ( const char *  url)
pure virtualinherited

Publishes the local stream without transcoding to a specified CDN live RTMP address. (CDN live only.)

The SDK returns the result of this method call in the onStreamPublished callback.

The startRtmpStreamWithoutTranscoding method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

Note
  • Ensure that the user joins the channel before calling this method.
  • This method adds only one stream RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
  • This method applies to Live Broadcast only.
Parameters
urlThe CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
Returns
  • 0: Success.
  • < 0: Failure.
  • ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0.
  • ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream.

◆ startRtmpStreamWithTranscoding()

virtual int startRtmpStreamWithTranscoding ( const char *  url,
const LiveTranscoding transcoding 
)
pure virtualinherited

Publishes the local stream with transcoding to a specified CDN live RTMP address. (CDN live only.)

The SDK returns the result of this method call in the onStreamPublished callback.

The startRtmpStreamWithTranscoding method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

Note
  • Ensure that the user joins the channel before calling this method.
  • This method adds only one stream RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
  • This method applies to Live Broadcast only.
Parameters
urlThe CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateRtmpTranscoding()

virtual int updateRtmpTranscoding ( const LiveTranscoding transcoding)
pure virtualinherited

Update the video layout and audio settings for CDN live. (CDN live only.)

Note
This method applies to Live Broadcast only.
Parameters
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopRtmpStream()

virtual int stopRtmpStream ( const char *  url)
pure virtualinherited

Stop an RTMP stream with transcoding or without transcoding from the CDN. (CDN live only.)

This method removes the RTMP URL address (added by the startRtmpStreamWithoutTranscoding method or IRtcEngine::startRtmpStreamWithTranscoding "startRtmpStreamWithTranscoding" method) from a CDN live stream. The SDK returns the result of this method call in the onStreamUnpublished callback.

The stopRtmpStream method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of removing an RTMP stream from the CDN.

Note
  • This method removes only one RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
  • This method applies to Live Broadcast only.
Parameters
urlThe RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startLocalVideoTranscoder()

virtual int startLocalVideoTranscoder ( const LocalTranscoderConfiguration config)
pure virtualinherited

◆ updateLocalTranscoderConfiguration()

virtual int updateLocalTranscoderConfiguration ( const LocalTranscoderConfiguration config)
pure virtualinherited

◆ stopLocalVideoTranscoder()

virtual int stopLocalVideoTranscoder ( )
pure virtualinherited

◆ startPrimaryCameraCapture()

virtual int startPrimaryCameraCapture ( const CameraCapturerConfiguration config)
pure virtualinherited

◆ startSecondaryCameraCapture()

virtual int startSecondaryCameraCapture ( const CameraCapturerConfiguration config)
pure virtualinherited

◆ stopPrimaryCameraCapture()

virtual int stopPrimaryCameraCapture ( )
pure virtualinherited

◆ stopSecondaryCameraCapture()

virtual int stopSecondaryCameraCapture ( )
pure virtualinherited

◆ setScreenCaptureOrientation()

virtual int setScreenCaptureOrientation ( VIDEO_SOURCE_TYPE  type,
VIDEO_ORIENTATION  orientation 
)
pure virtualinherited

◆ startPrimaryScreenCapture()

virtual int startPrimaryScreenCapture ( const ScreenCaptureConfiguration config)
pure virtualinherited

◆ startSecondaryScreenCapture()

virtual int startSecondaryScreenCapture ( const ScreenCaptureConfiguration config)
pure virtualinherited

◆ stopPrimaryScreenCapture()

virtual int stopPrimaryScreenCapture ( )
pure virtualinherited

◆ stopSecondaryScreenCapture()

virtual int stopSecondaryScreenCapture ( )
pure virtualinherited

◆ getConnectionState()

virtual CONNECTION_STATE_TYPE getConnectionState ( )
pure virtualinherited

Gets the current connection state of the SDK.

Returns
#CONNECTION_STATE_TYPE.

◆ registerEventHandler()

virtual bool registerEventHandler ( IRtcEngineEventHandler eventHandler)
pure virtualinherited

◆ unregisterEventHandler()

virtual bool unregisterEventHandler ( IRtcEngineEventHandler eventHandler)
pure virtualinherited

◆ setRemoteUserPriority()

virtual int setRemoteUserPriority ( uid_t  uid,
PRIORITY_TYPE  userPriority 
)
pure virtualinherited

◆ registerPacketObserver()

virtual int registerPacketObserver ( IPacketObserver observer)
pure virtualinherited

Registers a packet observer.

The Agora Native SDK allows your app to register a packet observer to receive events whenever a voice or video packet is transmitting.

Parameters
observerThe IPacketObserver object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableEncryption()

virtual int enableEncryption ( bool  enabled,
const EncryptionConfig config 
)
pure virtualinherited

Enables/Disables the built-in encryption.

In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel.

All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared.

Note
  • If you enable the built-in encryption, you cannot use the RTMP streaming function.
Parameters
enabledWhether to enable the built-in encryption:
  • true: Enable the built-in encryption.
  • false: Disable the built-in encryption.
configConfigurations of built-in encryption schemas. See EncryptionConfig.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
    • -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the IRtcEngine instance before calling this method.

◆ createDataStream() [1/2]

virtual int createDataStream ( int *  streamId,
bool  reliable,
bool  ordered 
)
pure virtualinherited

Creates a data stream.

You can call this method to create a data stream and improve the reliability and ordering of data tranmission.

Note
  • Ensure that you set the same value for reliable and ordered.
  • Each user can only create a maximum of 5 data streams during a RtcEngine lifecycle.
  • The data channel allows a data delay of up to 5 seconds. If the receiver does not receive the data stream within 5 seconds, the data channel reports an error.
Parameters
[out]streamIdThe ID of the stream data.
reliableSets whether the recipients are guaranteed to receive the data stream from the sender within five seconds:
  • true: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the application.
  • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
orderedSets whether the recipients receive the data stream in the sent order:
  • true: The recipients receive the data stream in the sent order.
  • false: The recipients do not receive the data stream in the sent order.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream() [2/2]

virtual int createDataStream ( int *  streamId,
DataStreamConfig config 
)
pure virtualinherited

Creates a data stream.

Each user can create up to five data streams during the lifecycle of the IChannel.

Parameters
streamIdThe ID of the created data stream.
configThe config of data stream.
Returns
int
  • Returns 0: Success.
  • < 0: Failure.

◆ sendStreamMessage()

virtual int sendStreamMessage ( int  streamId,
const char *  data,
size_t  length 
)
pure virtualinherited

Sends a data stream.

After calling createDataStream, you can call this method to send a data stream to all users in the channel.

The SDK has the following restrictions on this method:

  • Up to 60 packets can be sent per second in a channel with each packet having a maximum size of 1 KB.
  • Each client can send up to 30 KB of data per second.
  • Each user can have up to five data streams simultaneously.

After the remote user receives the data stream within 5 seconds, the SDK triggers the onStreamMessage callback on the remote client. After the remote user does not receive the data stream within 5 seconds, the SDK triggers the onStreamMessageError callback on the remote client.

Note
  • Call this method after calling createDataStream.
  • This method applies only to the COMMUNICATION profile or to the hosts in the LIVE_BROADCASTING profile. If an audience in the LIVE_BROADCASTING profile calls this method, the audience may be switched to a host.
Parameters
streamIdThe ID of the stream data.
dataThe data stream.
lengthThe length (byte) of the data stream.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ addVideoWatermark() [1/2]

virtual int addVideoWatermark ( const RtcImage watermark)
pure virtualinherited

DEPRECATED Adds a watermark image to the local video or CDN live stream.

This method is not recommend, Use addVideoWatermark2 instead.

This method adds a PNG watermark image to the local video stream for the recording device, channel audience, and CDN live audience to view and capture.

To add the PNG file to the CDN live publishing stream, see the setLiveTranscoding method.

Parameters
watermarkPointer to the watermark image to be added to the local video stream. See RtcImage.
Note
  • The URL descriptions are different for the local video and CDN live streams:
    • In a local video stream, url in RtcImage refers to the absolute path of the added watermark image file in the local video stream.
    • In a CDN live stream, url in RtcImage refers to the URL address of the added watermark image in the CDN live broadcast.
  • The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file will be cropped to conform to your settings.
  • The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addVideoWatermark() [2/2]

virtual int addVideoWatermark ( const char *  watermarkUrl,
const WatermarkOptions options 
)
pure virtualinherited

Adds a watermark image to the local video.

This method adds a PNG watermark image to the local video in a live broadcast. Once the watermark image is added, all the audience in the channel (CDN audience included), and the recording device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one.

The watermark position depends on the settings in the setVideoEncoderConfiguration method:

Note
  • Ensure that you have called the enableVideo method to enable the video module before calling this method.
  • If you only want to add a watermark image to the local video for the audience in the CDN live broadcast channel to see and capture, you can call this method or the setLiveTranscoding method.
  • This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
  • If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
  • If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
  • If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.
Parameters
watermarkUrlThe local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path.
optionsPointer to the watermark's options to be added. See WatermarkOptions for more infomation.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ clearVideoWatermark()

virtual int clearVideoWatermark ( )
pure virtualinherited

Removes the watermark image on the video stream added by addVideoWatermark().

Returns
int
  • 0: Success.
  • < 0: Failure.

◆ enableWebSdkInteroperability()

virtual int enableWebSdkInteroperability ( bool  enabled)
pure virtualinherited

Enables interoperability with the Agora Web SDK (Live Broadcast only).

Deprecated:
The Agora NG SDK enables the interoperablity with the Web SDK.

Use this method when the channel profile is Live Broadcast. Interoperability with the Agora Web SDK is enabled by default when the channel profile is Communication.

Parameters
enabledDetermines whether to enable interoperability with the Agora Web SDK.
  • true: (Default) Enable interoperability with the Agora Native SDK.
  • false: Disable interoperability with the Agora Native SDK.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ sendCustomReportMessage()

virtual int sendCustomReportMessage ( const char *  id,
const char *  category,
const char *  event,
const char *  label,
int  value 
)
pure virtualinherited

Agora supports reporting and analyzing customized messages.

This function is in the beta stage with a free trial. The ability provided in its beta test version is reporting a maximum of 10 message pieces within 6 seconds, with each message piece not exceeding 256 bytes.

To try out this function, contact support@agora.io and discuss the format of customized messages with us.

◆ registerMediaMetadataObserver()

virtual int registerMediaMetadataObserver ( IMetadataObserver observer,
IMetadataObserver::METADATA_TYPE  type 
)
pure virtualinherited

Registers the metadata observer.

You need to implement the IMetadataObserver class and specify the metadata type in this method. This method enables you to add synchronized metadata in the video stream for more diversified live interactive streaming, such as sending shopping links, digital coupons, and online quizzes.

A successful call of this method triggers the getMaxMetadataSize callback.

Note
  • Call this method before the joinChannel method.
  • This method applies to the LIVE_BROADCASTING channel profile.
Parameters
observerIMetadataObserver.
typeThe metadata type. See METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.
Returns
  • 0: Success.
  • < 0: Failure.

◆ unregisterMediaMetadataObserver()

virtual int unregisterMediaMetadataObserver ( IMetadataObserver observer,
IMetadataObserver::METADATA_TYPE  type 
)
pure virtualinherited

Unregisters the metadata observer.

Parameters
observerIMetadataObserver.
typeThe metadata type. See METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioFrameDump()

virtual int startAudioFrameDump ( const char *  channel_id,
uid_t  user_id,
const char *  location,
const char *  uuid,
const char *  passwd,
long  duration_ms,
bool  auto_upload 
)
pure virtualinherited

Start audio frame dump.

Optional location is: "pre_apm_proc", "apm", "pre_send_proc", "filter", "enc", "tx_mixer", "at_record", "atw_record" for audio sending. "dec", "mixed", "play", "rx_mixer", "playback_mixer", "pcm_source_playback_mixer", "pre_play_proc", "at_playout", "atw_playout" for audio receiving.

◆ stopAudioFrameDump()

virtual int stopAudioFrameDump ( const char *  channel_id,
uid_t  user_id,
const char *  location 
)
pure virtualinherited

◆ registerLocalUserAccount()

virtual int registerLocalUserAccount ( const char *  appId,
const char *  userAccount 
)
pure virtualinherited

Registers a user account.

Once registered, the user account can be used to identify the local user when the user joins the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and user account of the local user.

To join a channel with a user account, you can choose either of the following:

The difference between the two is that for the former, the time elapsed between calling the joinChannelWithUserAccount method and joining the channel is shorter than the latter.

Note
  • Ensure that you set the userAccount parameter. Otherwise, this method does not take effect.
  • Ensure that the value of the userAccount parameter is unique in the channel.
  • To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
appIdThe App ID of your project.
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannelWithUserAccount() [1/2]

virtual int joinChannelWithUserAccount ( const char *  token,
const char *  channelId,
const char *  userAccount 
)
pure virtualinherited

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelIdThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannelWithUserAccount() [2/2]

virtual int joinChannelWithUserAccount ( const char *  token,
const char *  channelId,
const char *  userAccount,
const ChannelMediaOptions options 
)
pure virtualinherited

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelIdThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: ChannelMediaOptions
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannelWithUserAccountEx()

virtual int joinChannelWithUserAccountEx ( const char *  token,
const char *  channelId,
const char *  userAccount,
const ChannelMediaOptions options,
IRtcEngineEventHandler eventHandler 
)
pure virtualinherited

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelIdThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: ChannelMediaOptions
eventHandlerThe pointer to the IRtcEngine event handler: IRtcEngineEventHandler.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUserAccount()

virtual int getUserInfoByUserAccount ( const char *  userAccount,
rtc::UserInfo userInfo 
)
pure virtualinherited

Gets the user information by passing in the user account.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the onUserInfoUpdated callback on the local client.

After receiving the oonUserInfoUpdated callback, you can call this method to get the user ID of the remote user from the userInfo object by passing in the user account.

Parameters
userAccountThe user account of the user. Ensure that you set this parameter.
[in,out]userInfoA userInfo object that identifies the user:
  • Input: A userInfo object.
  • Output: A userInfo object that contains the user account and user ID of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUid()

virtual int getUserInfoByUid ( uid_t  uid,
rtc::UserInfo userInfo 
)
pure virtualinherited

Gets the user information by passing in the user ID.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the onUserInfoUpdated callback on the local client.

After receiving the onUserInfoUpdated callback, you can call this method to get the user account of the remote user from the userInfo object by passing in the user ID.

Parameters
uidThe user ID of the remote user. Ensure that you set this parameter.
[in,out]userInfoA userInfo object that identifies the user:
  • Input: A userInfo object.
  • Output: A userInfo object that contains the user account and user ID of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startChannelMediaRelay()

virtual int startChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtualinherited

Starts to relay media streams across channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.

Note
  • Call this method after the joinChannel method.
  • This method takes effect only when you are a host in a LIVE_BROADCASTING channel.
  • After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
  • Contact sales.nosp@m.-us@.nosp@m.agora.nosp@m..io before implementing this function.
  • We do not support string user accounts in this API.
Parameters
configurationThe configuration of the media stream relay: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateChannelMediaRelay()

virtual int updateChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtualinherited

Updates the channels for media stream relay. After a successful startChannelMediaRelay method call, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code.

Note
Call this method after the startChannelMediaRelay method to update the destination channel.
Parameters
configurationThe media stream relay configuration: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopChannelMediaRelay()

virtual int stopChannelMediaRelay ( )
pure virtualinherited

Stops the media stream relay.

Once the relay stops, the host quits all the destination channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback returns RELAY_STATE_IDLE (0) and RELAY_OK (0), the host successfully stops the relay.

Note
If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback with the RELAY_ERROR_SERVER_NO_RESPONSE (2) or RELAY_ERROR_SERVER_CONNECTION_LOST (8) state code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAllChannelMediaRelay()

virtual int pauseAllChannelMediaRelay ( )
pure virtualinherited

pause the channels for media stream relay.

Returns
  • 0: Success.
  • < 0: Failure.

◆ resumeAllChannelMediaRelay()

virtual int resumeAllChannelMediaRelay ( )
pure virtualinherited

resume the channels for media stream relay.

Returns
  • 0: Success.
  • < 0: Failure.

◆ setDirectCdnStreamingAudioConfiguration()

virtual int setDirectCdnStreamingAudioConfiguration ( AUDIO_PROFILE_TYPE  profile)
pure virtualinherited

Set audio parameters for direct streaming to CDN

Note
Must call this api before "startDirectCdnStreaming"
Parameters
profileSets the sample rate, bitrate, encoding mode, and the number of channels: AUDIO_PROFILE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDirectCdnStreamingVideoConfiguration()

virtual int setDirectCdnStreamingVideoConfiguration ( const VideoEncoderConfiguration config)
pure virtualinherited

Set video parameters for direct streaming to CDN

Each configuration profile corresponds to a set of video parameters, including the resolution, frame rate, and bitrate.

Note
Must call this api before "startDirectCdnStreaming"
Parameters
configThe local video encoder configuration: VideoEncoderConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startDirectCdnStreaming()

virtual int startDirectCdnStreaming ( IDirectCdnStreamingEventHandler eventHandler,
const char *  publishUrl,
const DirectCdnStreamingMediaOptions options 
)
pure virtualinherited

Start direct cdn streaming

Parameters
eventHandlerA pointer to the direct cdn streaming event handler: IDirectCdnStreamingEventHandler.
publishUrlThe url of the cdn used to publish the stream.
optionsThe direct cdn streaming media options: DirectCdnStreamingMediaOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopDirectCdnStreaming()

virtual int stopDirectCdnStreaming ( )
pure virtualinherited

Stop direct cdn streaming

Note
This method is synchronous.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateDirectCdnStreamingMediaOptions()

virtual int updateDirectCdnStreamingMediaOptions ( const DirectCdnStreamingMediaOptions options)
pure virtualinherited

Change the media source during the pushing

Note
This method is temporarily not supported.
Parameters
optionsThe direct cdn streaming media options: DirectCdnStreamingMediaOptions.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pushDirectCdnStreamingCustomVideoFrame()

virtual int pushDirectCdnStreamingCustomVideoFrame ( media::base::ExternalVideoFrame frame)
pure virtualinherited

Push external video data

Parameters
frameThe reference to the video frame to send.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ takeSnapshot()

virtual int takeSnapshot ( media::SnapShotConfig config,
media::ISnapshotCallback callback 
)
pure virtualinherited

save current time video frame to jpeg and write as a jpeg

Parameters
configSnapShotConfig
callbackISnapshotCallback
Returns
int
  • 0 : Success.
  • <0 : Failure.

◆ SetContentInspect()

virtual int SetContentInspect ( media::ContentInspectConfig config)
pure virtualinherited

Enable the content inspect.

Parameters
configContentInspectConfig
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ switchChannel()

virtual int switchChannel ( const char *  token,
const char *  channel 
)
pure virtualinherited

switch to another channel.

Returns
  • 0: Success.
  • < 0: Failure.

◆ startRhythmPlayer()

virtual int startRhythmPlayer ( const char *  sound1,
const char *  sound2,
const AgoraRhythmPlayerConfig config 
)
pure virtualinherited

Enables the rhythm player.

Parameters
sound1The absolute path or URL address (including the filename extensions) of the file for the downbeat.
sound2The absolute path or URL address (including the filename extensions) of the file for the upbeats.
configThe configuration of rhythm player.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ stopRhythmPlayer()

virtual int stopRhythmPlayer ( )
pure virtualinherited

Disables the rhythm player.

Returns
  • 0: Success.
  • < 0: Failure.

◆ configRhythmPlayer()

virtual int configRhythmPlayer ( const AgoraRhythmPlayerConfig config)
pure virtualinherited

Configures the rhythm player.

Parameters
configThe configuration of rhythm player.
Returns
int
  • 0: Success.
  • < 0: Failure.

◆ adjustCustomAudioPublishVolume()

virtual int adjustCustomAudioPublishVolume ( int32_t  sourceId,
int  volume 
)
pure virtualinherited

◆ adjustCustomAudioPlayoutVolume()

virtual int adjustCustomAudioPlayoutVolume ( int32_t  sourceId,
int  volume 
)
pure virtualinherited

◆ setCloudProxy()

virtual int setCloudProxy ( CLOUD_PROXY_TYPE  proxyType)
pure virtualinherited

Sets the Agora cloud proxy service.

Since
v3.3.0

When the user's firewall restricts the IP address and port, refer to Use Cloud Proxy to add the specific IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set the proxyType parameter as UDP_PROXY(1), which is the cloud proxy for the UDP protocol.

After a successfully cloud proxy connection, the SDK triggers the onConnectionStateChanged (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback.

To disable the cloud proxy that has been set, call setCloudProxy(NONE_PROXY). To change the cloud proxy type that has been set, call setCloudProxy(NONE_PROXY) first, and then call setCloudProxy, and pass the value that you expect in proxyType.

Note
  • Agora recommends that you call this method before joining the channel or after leaving the channel.
  • For the SDK v3.3.x, the services for pushing streams to CDN and co-hosting across channels are not available when you use the cloud proxy for the UDP protocol. For the SDK v3.4.0 and later, the services for pushing streams to CDN and co-hosting across channels are not available when the user is in a network environment with a firewall and uses the cloud proxy for the UDP protocol.
Parameters
proxyTypeThe cloud proxy type, see CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ setLocalAccessPoint()

virtual int setLocalAccessPoint ( const LocalAccessPointConfiguration config)
pure virtualinherited

set local access point addresses in local proxy mode. use this method before join channel.

Parameters
configThe LocalAccessPointConfiguration class, See the definition of LocalAccessPointConfiguration for details.
Returns
  • 0: Success
  • < 0: Failure

◆ enableFishCorrection()

virtual int enableFishCorrection ( bool  enabled,
const FishCorrectionParams params 
)
pure virtualinherited

enable fish correction. use this method before join channel.

Parameters
enabledbool
paramsThe FishCorrectionParams struct, See the definition of FishCorrectionParams for details.
Returns
  • 0: Success
  • < 0: Failure

◆ setAdvancedAudioOptions()

virtual int setAdvancedAudioOptions ( media::base::AdvancedAudioOptions options)
pure virtualinherited

set advanced audio options. use this method before join channel.

Parameters
optionsThe AdvancedAudioOptions class, See the definition of AdvancedAudioOptions for details.
Returns
  • 0: Success
  • < 0: Failure

◆ setAVSyncSource()

virtual int setAVSyncSource ( const char *  channelId,
uid_t  uid 
)
pure virtualinherited

Bind local user and a remote user as an audio&video sync group. The remote user is defined by cid and uid. There’s a usage limit that local user must be a video stream sender. On the receiver side, media streams from same sync group will be time-synced

Parameters
channelIdThe channel id
uidThe user ID of the remote user to be bound with (local user)
Returns
  • 0: Success.
  • < 0: Failure.