agora::rtc::IRtcEngine2 继承.

Public 类型

typedef unsigned int WindowIDType
 
typedef HWND WindowIDType
 

Public 成员函数

virtual int initialize (const RtcEngineContext &context)=0
 
virtual int setChannelProfile (CHANNEL_PROFILE_TYPE profile)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role)=0
 
virtual int joinChannel (const char *token, const char *channelId, const char *info, uid_t uid)=0
 
virtual int switchChannel (const char *token, const char *channelId)=0
 
virtual int leaveChannel ()=0
 
virtual int renewToken (const char *token)=0
 
virtual int queryInterface (INTERFACE_ID_TYPE iid, void **inter)=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 getUserInfoByUserAccount (const char *userAccount, UserInfo *userInfo)=0
 
virtual int getUserInfoByUid (uid_t uid, UserInfo *userInfo)=0
 
virtual int startEchoTest ()=0
 
virtual int startEchoTest (int intervalInSeconds)=0
 
virtual int stopEchoTest ()=0
 
virtual int enableVideo ()=0
 
virtual int disableVideo ()=0
 
virtual int setVideoProfile (VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight)=0
 
virtual int setVideoEncoderConfiguration (const VideoEncoderConfiguration &config)=0
 
virtual int setCameraCapturerConfiguration (const CameraCapturerConfiguration &config)=0
 
virtual int setupLocalVideo (const VideoCanvas &canvas)=0
 
virtual int setupRemoteVideo (const VideoCanvas &canvas)=0
 
virtual int startPreview ()=0
 
virtual int setRemoteUserPriority (uid_t uid, PRIORITY_TYPE userPriority)=0
 
virtual int stopPreview ()=0
 
virtual int enableAudio ()=0
 
virtual int enableLocalAudio (bool enabled)=0
 
virtual int disableAudio ()=0
 
virtual int setAudioProfile (AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario)=0
 
virtual int muteLocalAudioStream (bool mute)=0
 
virtual int muteAllRemoteAudioStreams (bool mute)=0
 
virtual int setDefaultMuteAllRemoteAudioStreams (bool mute)=0
 
virtual int adjustUserPlaybackSignalVolume (unsigned int uid, int volume)=0
 
virtual int muteRemoteAudioStream (uid_t userId, 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)=0
 
virtual int muteRemoteVideoStream (uid_t userId, bool mute)=0
 
virtual int setRemoteVideoStreamType (uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType)=0
 
virtual int setRemoteDefaultVideoStreamType (REMOTE_VIDEO_STREAM_TYPE streamType)=0
 
virtual int enableAudioVolumeIndication (int interval, int smooth, bool report_vad)=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 stopAudioRecording ()=0
 
virtual int startAudioMixing (const char *filePath, bool loopback, bool replace, int cycle)=0
 
virtual int stopAudioMixing ()=0
 
virtual int pauseAudioMixing ()=0
 
virtual int resumeAudioMixing ()=0
 
virtual int setHighQualityAudioParameters (bool fullband, bool stereo, bool fullBitrate)=0
 
virtual int adjustAudioMixingVolume (int volume)=0
 
virtual int adjustAudioMixingPlayoutVolume (int volume)=0
 
virtual int getAudioMixingPlayoutVolume ()=0
 
virtual int adjustAudioMixingPublishVolume (int volume)=0
 
virtual int getAudioMixingPublishVolume ()=0
 
virtual int getAudioMixingDuration ()=0
 
virtual int getAudioMixingCurrentPosition ()=0
 
virtual int setAudioMixingPosition (int pos)=0
 
virtual int setAudioMixingPitch (int pitch)=0
 
virtual int getEffectsVolume ()=0
 
virtual int setEffectsVolume (int volume)=0
 
virtual int setVolumeOfEffect (int soundId, int volume)=0
 
virtual int enableFaceDetection (bool enable)=0
 
virtual int playEffect (int soundId, const char *filePath, int loopCount, double pitch, double pan, int gain, bool publish=false)=0
 
virtual int stopEffect (int soundId)=0
 
virtual int stopAllEffects ()=0
 
virtual int preloadEffect (int soundId, const char *filePath)=0
 
virtual int unloadEffect (int soundId)=0
 
virtual int pauseEffect (int soundId)=0
 
virtual int pauseAllEffects ()=0
 
virtual int resumeEffect (int soundId)=0
 
virtual int resumeAllEffects ()=0
 
virtual int enableSoundPositionIndication (bool enabled)=0
 
virtual int setRemoteVoicePosition (int uid, double pan, double gain)=0
 
virtual int setLocalVoicePitch (double pitch)=0
 
virtual int setLocalVoiceEqualization (AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain)=0
 
virtual int setLocalVoiceReverb (AUDIO_REVERB_TYPE reverbKey, int value)=0
 
virtual int setLocalVoiceChanger (VOICE_CHANGER_PRESET voiceChanger)=0
 
virtual int setLocalVoiceReverbPreset (AUDIO_REVERB_PRESET reverbPreset)=0
 
virtual int setLogFile (const char *filePath)=0
 
virtual int setLogFilter (unsigned int filter)=0
 
virtual int setLogFileSize (unsigned int fileSizeInKBytes)=0
 
virtual int setLocalRenderMode (RENDER_MODE_TYPE renderMode)=0
 
virtual int setLocalRenderMode (RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setRemoteRenderMode (uid_t userId, RENDER_MODE_TYPE renderMode)=0
 
virtual int setRemoteRenderMode (uid_t userId, 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 setExternalAudioSource (bool enabled, int sampleRate, int channels)=0
 
virtual int setExternalAudioSink (bool enabled, int sampleRate, int channels)=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 samplesPerCall)=0
 
virtual int adjustRecordingSignalVolume (int volume)=0
 
virtual int adjustPlaybackSignalVolume (int volume)=0
 
virtual int enableWebSdkInteroperability (bool enabled)=0
 
virtual int setVideoQualityParameters (bool preferFrameRateOverImageQuality)=0
 
virtual int setLocalPublishFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
 
virtual int setRemoteSubscribeFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
 
virtual int switchCamera ()=0
 
virtual int setDefaultAudioRouteToSpeakerphone (bool defaultToSpeaker)=0
 
virtual int setEnableSpeakerphone (bool speakerOn)=0
 
virtual int enableInEarMonitoring (bool enabled)=0
 
virtual int setInEarMonitoringVolume (int volume)=0
 
virtual bool isSpeakerphoneEnabled ()=0
 
virtual int setAudioSessionOperationRestriction (AUDIO_SESSION_OPERATION_RESTRICTION restriction)=0
 
virtual int enableLoopbackRecording (bool enabled, const char *deviceName=NULL)=0
 
virtual int startScreenCaptureByDisplayId (unsigned int displayId, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int startScreenCaptureByScreenRect (const Rectangle &screenRect, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int startScreenCaptureByWindowId (view_t windowId, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int setScreenCaptureContentHint (VideoContentHint contentHint)=0
 
virtual int updateScreenCaptureParameters (const ScreenCaptureParameters &captureParams)=0
 
virtual int updateScreenCaptureRegion (const Rectangle &regionRect)=0
 
virtual int stopScreenCapture ()=0
 
virtual int startScreenCapture (WindowIDType windowId, int captureFreq, const Rect *rect, int bitrate)=0
 
virtual int updateScreenCaptureRegion (const Rect *rect)=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 const char * getVersion (int *build)=0
 
virtual int enableLastmileTest ()=0
 
virtual int disableLastmileTest ()=0
 
virtual int startLastmileProbeTest (const LastmileProbeConfig &config)=0
 
virtual int stopLastmileProbeTest ()=0
 
virtual const char * getErrorDescription (int code)=0
 
virtual int setEncryptionSecret (const char *secret)=0
 
virtual int setEncryptionMode (const char *encryptionMode)=0
 
virtual int registerPacketObserver (IPacketObserver *observer)=0
 
virtual int createDataStream (int *streamId, bool reliable, bool ordered)=0
 
virtual int sendStreamMessage (int streamId, const char *data, size_t length)=0
 
virtual int addPublishStreamUrl (const char *url, bool transcodingEnabled)=0
 
virtual int removePublishStreamUrl (const char *url)=0
 
virtual int setLiveTranscoding (const LiveTranscoding &transcoding)=0
 
virtual int addVideoWatermark (const RtcImage &watermark)=0
 
virtual int addVideoWatermark (const char *watermarkUrl, const WatermarkOptions &options)=0
 
virtual int clearVideoWatermarks ()=0
 
virtual int setBeautyEffectOptions (bool enabled, BeautyOptions options)=0
 
virtual int addInjectStreamUrl (const char *url, const InjectStreamConfig &config)=0
 
virtual int startChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int updateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int stopChannelMediaRelay ()=0
 
virtual int removeInjectStreamUrl (const char *url)=0
 
virtual bool registerEventHandler (IRtcEngineEventHandler *eventHandler)=0
 
virtual bool unregisterEventHandler (IRtcEngineEventHandler *eventHandler)=0
 
virtual CONNECTION_STATE_TYPE getConnectionState ()=0
 
virtual int registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
 

静态 Public 成员函数

static AGORA_CPP_API void release (bool sync=false)
 

Protected 成员函数

virtual ~IRtcEngine ()
 

详细描述

IRtcEngine 类提供了供 App 调用的主要接口方法。

IRtcEngine 是 Agora Native SDK 的基础接口类。创建一个 IRtcEngine 对象并调用这个对象的方法可以激活 Agora Native SDK 的通信功能。

成员类型定义说明

◆ WindowIDType [1/2]

◆ WindowIDType [2/2]

构造及析构函数说明

◆ ~IRtcEngine()

virtual agora::rtc::IRtcEngine::~IRtcEngine ( )
inlineprotectedvirtual

成员函数说明

◆ initialize()

virtual int agora::rtc::IRtcEngine::initialize ( const RtcEngineContext context)
pure virtual

初始化 Agora SDK 服务。

请确保在调用其他 API 前先调用 createAgoraRtcEngineinitialize 创建并初始化 IRtcEngine。

参数
context详见 RtcEngineContext
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败
    • ERR_INVALID_APP_ID(101):不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

◆ release()

static AGORA_CPP_API void agora::rtc::IRtcEngine::release ( bool  sync = false)
static

销毁 IRtcEngine 对象。

注解
如果重启通话,必须在本方法执行结束后再调用 initialize 重新创建 IRtcEngine。
参数
sync
  • true: 同步调用。在等待 IRtcEngine 对象资源释放后再返回。App 不应该在 SDK 产生的回调中调用该接口,否则由于 SDK 要等待回调返回才能回收相关的对象资源,会造成死锁。SDK 会自动检测这种死锁并转为异步调用,但是检测本身会消耗额外的时间。
  • false: 异步调用。不等 IRtcEngine 对象资源释放就立即返回。SDK 会自行释放所有资源。使用异步调用时要注意,不要在该调用后立即卸载 SDK 动态库,否则可能会因为 SDK 的清理线程还没有退出而崩溃。

◆ setChannelProfile()

virtual int agora::rtc::IRtcEngine::setChannelProfile ( CHANNEL_PROFILE_TYPE  profile)
pure virtual

设置直播场景下的频道场景。

该方法用于设置 Agora IRtcEngine 频道的使用场景。RtcEngine 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。

警告
  • 为保证实时音视频质量,我们建议相同频道内的用户使用同一种频道场景。
  • 该方法必须在 joinChannel 前调用和进行设置,进入频道后无法再设置。
参数
profile频道使用场景: CHANNEL_PROFILE_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setClientRole()

virtual int agora::rtc::IRtcEngine::setClientRole ( CLIENT_ROLE_TYPE  role)
pure virtual

设置直播场景下的用户角色。

在加入频道前,用户需要通过本方法设置观众(默认)或主播。在加入频道后,用户可以通过本方法切换用户角色。 直播场景下,如果你在加入频道后调用该方法切换用户角色,调用成功后,本地会触发 onClientRoleChanged 回调;远端会触发 onUserJoined 回调或 onUserOffline (BECOME_AUDIENCE) 回调。

参数
role直播场景里的用户角色: CLIENT_ROLE_TYPE
注解
该方法仅适用于直播场景。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ joinChannel()

virtual int agora::rtc::IRtcEngine::joinChannel ( const char *  token,
const char *  channelId,
const char *  info,
uid_t  uid 
)
pure virtual

加入频道。

该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中,用户必须调用 leaveChannel 退出当前通话,才能进入下一个频道。 成功调用该方加入频道后,本地会触发 onJoinChannelSuccess 回调;通信场景下的用户和直播场景下的主播加入频道后,远端会触发 onUserJoined 回调。 在网络状况不理想的情况下,客户端可能会与 Agora 的服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 onRejoinChannelSuccess 回调。

注解
频道内每个用户的用户 ID 必须是唯一的。如果将 uid 设为 0,系统将自动分配一个 uid。如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 uid 是不同的。
警告
请务必确保用于生成 Token 的 App ID 和 initialize 方法初始化引擎时用的是同一个 App ID,否则会造成旁路推流失败。
参数
token动态秘钥。
  • 安全要求不高: 将值设为 NULL。
  • 安全要求高: 将值设置为 Token。如果你已经启用了 App Certificate, 请务必使用 Token。
channelId标识通话的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a~z;
  • 26 个大写英文字母 A~Z;
  • 10个数字 0~9;
  • 空格;
  • "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"|"、"~"、","。
info(非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串,或频道相关信息。该信息不会传递给频道内的其他用户。
uid(非必选项) 用户ID,32位无符号整数。建议设置范围:1到 232-1,并保证唯一性。如果不指定(即设为0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调方法中返回,App 层必须记住该返回值并维护,SDK不对该返回值进行维护。
返回

◆ switchChannel()

virtual int agora::rtc::IRtcEngine::switchChannel ( const char *  token,
const char *  channelId 
)
pure virtual

快速切换直播频道。

当直播频道中的观众想从一个频道切换到另一个频道时,可以调用该方法,实现快速切换。

成功调用该方切换频道后,本地会先收到离开原频道的回调 onLeaveChannel,再收到成功加入新频道的回调 onJoinChannelSuccess

注解
该方法仅适用于直播场景中,角色为观众的用户。
参数
token在服务器端生成的用于鉴权的 Token:
  • 安全要求不高:你可以使用控制台生成的临时 Token,详见 获取临时 Token
  • 安全要求高:将值设为你的服务端生成的正式 Token,详见 获取正式 Token
channelId标识频道的频道名,最大不超过 64 字节。以下为支持的字符集范围 (共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!","#","$","%","&","(",")","+","-",":",";","<","=",".",">", "?","@","[","]","^","_"," {", "}","|","~",","
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ leaveChannel()

virtual int agora::rtc::IRtcEngine::leaveChannel ( )
pure virtual

离开频道。

离开频道,即挂断或退出通话。

当调用 joinChannel 方法后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。 不管当前是否在通话中,都可以调用 leaveChannel,没有副作用。该方法会把会话相关的所有资源释放掉。 该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 onLeaveChannel 回调。 成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。

注解
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ renewToken()

virtual int agora::rtc::IRtcEngine::renewToken ( const char *  token)
pure virtual

更新 Token。

该方法用于更新 Token。如果启用了 Token 机制,过一段时间后使用的 Token 会失效。当:

App 应重新获取 Token,然后调用该方法更新 Token,否则 SDK 无法和服务器建立连接。

参数
token新的 Token。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ queryInterface()

virtual int agora::rtc::IRtcEngine::queryInterface ( INTERFACE_ID_TYPE  iid,
void **  inter 
)
pure virtual

获取设备管理员对象的指针。

参数
iid想要获取的接口的接口。
inter指向 DeviceManager 对象的指针。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ registerLocalUserAccount()

virtual int agora::rtc::IRtcEngine::registerLocalUserAccount ( const char *  appId,
const char *  userAccount 
)
pure virtual

注册本地用户 User Account。

该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。成功注册 User Account 后,本地会触发 onLocalUserRegistered 回调,告知本地用户的 UID 和 User Account。

该方法为可选。如果你希望用户使用 User Account 加入频道,可以选用以下两种方式:

两种方式的区别在于,提前调用 registerLocalUserAccount,可以缩短使用 joinChannelWithUserAccount 进入频道的时间。

注解
  • userAccount 不能为空,否则该方法不生效。
  • 请确保在该方法中设置的 userAccount 在频道中的唯一性。
  • 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
appId你的项目在 Agora 控制台注册的 App ID
userAccount用户 User Account。该参数为必填,最大不超过 255 字节,不可填 null。请确保注册的 User Account 的唯一性。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ joinChannelWithUserAccount()

virtual int agora::rtc::IRtcEngine::joinChannelWithUserAccount ( const char *  token,
const char *  channelId,
const char *  userAccount 
)
pure virtual

使用 User Account 加入频道。

该方法允许本地用户使用 User Account 加入频道。成功加入频道后,会触发以下回调:

注解
为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
token在 App 服务器端生成的用于鉴权的 Token:
  • 安全要求不高:你可以使用控制台生成的临时 Token,详见 获取临时 Token
  • 安全要求高:将值设为你的服务端生成的正式 Token,详见 获取正式 Token
channelId标识频道的频道名,最大不超过 64 字节。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
userAccount用户 User Account。该参数为必需,最大不超过 255 字节,不可为 null。请确保注册的 User Account 的唯一性。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
返回

◆ getUserInfoByUserAccount()

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

通过 User Account 获取用户信息。

远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表, 并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法, 通过传入 User Account 获取包含了指定用户 UID 的 UserInfo 对象。

参数
userAccount用户 User Account。该参数为必填
[in,out]userInfo标识用户信息的 UserInfo 对象:
  • 输入值:一个 UserInfo 对象
  • 输出值:一个包含了用户 User Account 和 UID 的 UserInfo 对象
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getUserInfoByUid()

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

通过 UID 获取用户信息。

远端用户加入频道后, SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表, 并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法, 通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。

参数
uid用户 UID。该参数为必填
[in,out]userInfo标识用户信息的 UserInfo 对象:
  • 输入值:一个 UserInfo 对象
  • 输出值:一个包含了用户 User Account 和 UID 的 UserInfo 对象
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startEchoTest() [1/2]

virtual int agora::rtc::IRtcEngine::startEchoTest ( )
pure virtual
弃用:
开始语音通话回路测试。

该方法自 v2.4.0 起废弃。

该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在设置的时间间隔(单位为秒)后回放出来。如果用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。

注解
  • 请在加入频道前调用该方法。
  • 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
  • 直播场景下,该方法仅能由用户角色为主播的用户调用。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startEchoTest() [2/2]

virtual int agora::rtc::IRtcEngine::startEchoTest ( int  intervalInSeconds)
pure virtual

开始语音通话回路测试。

该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。 在测试过程中,用户先说一段话,声音会在设置的时间间隔(单位为秒)后回放出来。 如果用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。

注解
  • 请在加入频道前调用该方法。
  • 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
  • 直播场景下,该方法仅能由用户角色为主播的用户调用。
参数
intervalInSeconds设置返回语音通话回路测试结果的时间间隔,取值范围为 [2, 10],单位为秒,默认为 10 秒。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopEchoTest()

virtual int agora::rtc::IRtcEngine::stopEchoTest ( )
pure virtual

停止语音通话回路测试。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableVideo()

virtual int agora::rtc::IRtcEngine::enableVideo ( )
pure virtual

启用视频模块。

该方法可以在加入频道前或者通话中调用,在加入频道前调用则自动开启视频模块;在通话中调用则由音频模式切换为视频模式。 调用 disableVideo 方法可关闭视频模式。 成功调用该方法后,远端会触发 onUserEnableVideo (true) 回调。

注解
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ disableVideo()

virtual int agora::rtc::IRtcEngine::disableVideo ( )
pure virtual

关闭视频模块。

该方法可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频频模式。 调用 enableVideo 方法可开启视频模式。 成功调用该方法后,远端会触发 onUserEnableVideo (false) 回调

注解
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setVideoProfile()

virtual int agora::rtc::IRtcEngine::setVideoProfile ( VIDEO_PROFILE_TYPE  profile,
bool  swapWidthAndHeight 
)
pure virtual
弃用:

设置视频编码配置。

该方法自 v2.3 起废弃。请改用 setVideoEncoderConfiguration 方法。

该方法设置视频编码属性(Profile)。每个属性对应一套视频参数,如分辨率、帧率、码率等。 当设备的摄像头不支持指定的分辨率时,Agora SDK 会自动选择一个合适的摄像头分辨率,但是编码分辨率仍然用 setVideoProfile 指定的。

注解
  • 如果用户加入频道后不需要重新设置视频编码属性,则 声网建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。
  • 应在调用 joinChannelstartPreview 前设置视频属性。
参数
profile视频属性。详见: VIDEO_PROFILE_TYPE
swapWidthAndHeightSDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:
  • true: 交换宽和高
  • false: 不交换宽和高(默认)

你可以直接通过视频属性 (profile) 来定义输出的视频是 Landscape(横屏)还是 Portrait(竖屏)模式,因此 声网建议你将参数设置为默认值。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setVideoEncoderConfiguration()

virtual int agora::rtc::IRtcEngine::setVideoEncoderConfiguration ( const VideoEncoderConfiguration config)
pure virtual

设置视频编码属性。

设置本地视频的编码属性。

参数
config视频编码参数配置。详见: VideoEncoderConfiguration
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setCameraCapturerConfiguration()

virtual int agora::rtc::IRtcEngine::setCameraCapturerConfiguration ( const CameraCapturerConfiguration config)
pure virtual

设置摄像头采集偏好。

一般的视频通话或直播中,默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中,默认的参数通常无法满足需求,或可能引起设备性能问题,我们推荐调用该方法设置摄像头的采集偏好:

  • 使用原始音视频数据自采集接口时,如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数,在后续处理视频帧的时候,比如美颜功能时,会需要更高的 CPU 及内存,容易导致性能问题。在这种情况下,我们推荐将摄像头采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE = 1,避免性能问题。
  • 如果没有本地预览功能或者对预览质量没有要求,我们推荐将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE = 1,以优化 CPU 和内存的资源分配。
  • 如果用户希望本地预览视频比实际编码发送的视频清晰,可以将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PREVIEW = 2。
注解
请在启动摄像头之前调用该方法,如 joinChannelenableVideo 或者 enableLocalVideo 之前。
参数
config摄像头采集偏好,详见 CameraCapturerConfiguration
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setupLocalVideo()

virtual int agora::rtc::IRtcEngine::setupLocalVideo ( const VideoCanvas canvas)
pure virtual

初始化本地视图。

该方法初始化本地视图并设置本地用户视频显示信息,只影响本地用户看到的视频画面,不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view),并设置本地用户视图的渲染模式和镜像模式。

在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。退出频道后,绑定仍然有效,如果需要解除绑定,可以指定空(NULL)View 调用 setupLocalVideo。

注解
  • 建议你在加入频道前调用该方法。
  • 如果你希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode 方法。
参数
canvas视频画布信息: VideoCanvas
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setupRemoteVideo()

virtual int agora::rtc::IRtcEngine::setupRemoteVideo ( const VideoCanvas canvas)
pure virtual

初始化远端用户视图。

该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。

调用该接口时需要指定远端视频的 uid,一般可以在进频道前提前设置好。

如果 App 不能事先知道对方的 uid,可以在 APP 收到 onUserJoined 事件时设置。 如果启用了视频录制功能,视频录制服务会做为一个哑客户端加入频道,因此其他客户端也会收到它的 onUserJoined 事件,App 不应给它绑定视图(因为它不会发送视频流),如果 App 不能识别哑客户端,可以在 onFirstRemoteVideoDecoded 事件时再绑定视图。 解除某个用户的绑定视图可以把 view 设置为空。退出频道后,SDK 会把远端用户的绑定关系清除掉。

注解
如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderMode 方法。
参数
canvas视频画布信息: VideoCanvas
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startPreview()

virtual int agora::rtc::IRtcEngine::startPreview ( )
pure virtual

开启视频预览。

该方法用于在进入频道前启动本地视频预览。调用该 API 前,必须:

启用了本地视频预览后,如果调用 leaveChannel 退出频道,本地预览依然处于启动状态,如需要关闭本地预览,需要调用 stopPreview

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteUserPriority()

virtual int agora::rtc::IRtcEngine::setRemoteUserPriority ( uid_t  uid,
PRIORITY_TYPE  userPriority 
)
pure virtual

设置远端用户流的优先级。

设置远端用户的优先级。如果将某个用户的优先级设为高,那么发给这个用户的音视频流的优先级就会高于其他用户。 该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。如果开启了订阅流回退选项,弱网下 SDK 会优先保证高优先级用户收到的流的质量。

注解
目前 Agora SDK 仅允许将一名远端用户设为高优先级。
参数
uid远端用户的 ID。
userPriority远端用户的需求优先级。详见: PRIORITY_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopPreview()

virtual int agora::rtc::IRtcEngine::stopPreview ( )
pure virtual

停止视频预览。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableAudio()

virtual int agora::rtc::IRtcEngine::enableAudio ( )
pure virtual

启用音频模块。

启用音频模块(默认为开启状态)。

注解
  • 该方法设置内部引擎为启用状态,在频道内和频道外均可调用。在 leaveChannel 后仍然有效。
  • 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制音频模块:
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableLocalAudio()

virtual int agora::rtc::IRtcEngine::enableLocalAudio ( bool  enabled)
pure virtual

开关本地音频采集。

当用户加入频道时,语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能,即停止或重新开始本地音频采集。

该方法不影响接收或播放远端音频流,enableLocalAudio(false) 适用于只听不发的用户场景。

语音功能关闭或重新开启后,会收到回调 onMicrophoneEnabled

注解
该方法与 muteLocalAudioStream 的区别在于:
  • enableLocalAudio: 开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后,本地听远端播放会有短暂中断。
  • muteLocalAudioStream: 停止或继续发送本地音频流。
参数
enabled
  • true: 重新开启本地语音功能,即开启本地语音采集(默认);
  • false: 关闭本地语音功能,即停止本地语音采集。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ disableAudio()

virtual int agora::rtc::IRtcEngine::disableAudio ( )
pure virtual

关闭音频模块。

注解
  • 该方法设置内部引擎为禁用状态,在频道内和频道外均可调用。在 leaveChannel 后仍然有效。
  • 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制音频模块:
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setAudioProfile()

virtual int agora::rtc::IRtcEngine::setAudioProfile ( AUDIO_PROFILE_TYPE  profile,
AUDIO_SCENARIO_TYPE  scenario 
)
pure virtual

设置音频编码属性。

注解
参数
profile设置采样率,码率,编码模式和声道数: AUDIO_PROFILE_TYPE
scenario设置音频应用场景: AUDIO_SCENARIO_TYPE 。不同的音频场景下,设备的系统音量是不同的。详见如何区分媒体音量和通话音量
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteLocalAudioStream()

virtual int agora::rtc::IRtcEngine::muteLocalAudioStream ( bool  mute)
pure virtual

开关本地音频发送。

该方法用于允许/禁止往网络发送本地音频流。 成功调用该方法后,远端会触发 onUserMuteAudio 回调。

注解
  • 该方法不影响录音状态,因为并没有禁用录音设备。
  • 如果你在该方法后调用 setChannelProfile 方法,SDK 会根据你设置的频道场景以及用户角色,重新设置是否停止发送本地音频。因此我们建议在 setChannelProfile 后调用该方法。
参数
mute
  • true: 停止发送本地音频流;
  • false: 继续发送本地音频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteAllRemoteAudioStreams()

virtual int agora::rtc::IRtcEngine::muteAllRemoteAudioStreams ( bool  mute)
pure virtual

接收/停止接收所有音频流。

参数
mute
  • true: 停止接收所有音频流;
  • false: 继续接收所有音频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setDefaultMuteAllRemoteAudioStreams()

virtual int agora::rtc::IRtcEngine::setDefaultMuteAllRemoteAudioStreams ( bool  mute)
pure virtual

设置是否默认接收所有音频流。

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteAudioStreams(true), 会接收不到后面加入频道的用户的音频流。

注解
停止接收音频流后,如果想要恢复接收,请调用 muteRemoteAudioStream(false),并指定你想要接收的远端用户的 ID。 如果想恢复接收多个用户的音频流,则需要多次调用 muteRemoteAudioStreamsetDefaultMuteAllRemoteAudioStreams(false) 只能恢复接收后面加入频道的用户的音频流。
参数
mute
  • true: 默认停止接收所有音频流;
  • false: 默认接收所有音频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ adjustUserPlaybackSignalVolume()

virtual int agora::rtc::IRtcEngine::adjustUserPlaybackSignalVolume ( unsigned int  uid,
int  volume 
)
pure virtual
自从
v3.0.0

调节本地播放的指定远端用户音量。

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。

注解
  • 请在加入频道后,调用该方法。
  • 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
uid远端用户 ID。
volume播放音量,取值范围为 [0,100]:
  • 0: 静音
  • 100: 原始音量
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteRemoteAudioStream()

virtual int agora::rtc::IRtcEngine::muteRemoteAudioStream ( uid_t  userId,
bool  mute 
)
pure virtual

接收/停止接收指定音频流。

注解
如果之前有调用过 muteAllRemoteAudioStreams (true) 停止订阅所有远端音频,在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false)。 muteAllRemoteAudioStreams 是全局控制,muteRemoteAudioStream 是精细控制。
参数
userId指定用户的 ID
mute
  • true: 停止接收指定音频流;
  • false: 继续接收指定音频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteLocalVideoStream()

virtual int agora::rtc::IRtcEngine::muteLocalVideoStream ( bool  mute)
pure virtual

开关本地视频发送。

成功调用该方法后,远端会触发 onUserMuteVideo 回调。

注解
  • 调用该方法时,SDK 不再发送本地视频流,但摄像头仍然处于工作状态。相比于 enableLocalVideo (false) 用于控制本地视频流发送的方法,该方法响应速度更快。该方法不影响本地视频流获取,没有禁用摄像头。
  • 如果你在该方法后调用 setChannelProfile 方法,SDK 会根据你设置的频道场景以及用户角色,重新设置是否停止发送本地视频。因此我们建议在 setChannelProfile 后调用该方法。
参数
mute
  • true: 不发送本地视频流
  • false: 发送本地视频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableLocalVideo()

virtual int agora::rtc::IRtcEngine::enableLocalVideo ( bool  enabled)
pure virtual

开关本地视频采集。

该方法禁用或重新启用本地视频采集,不影响接收远端视频。

调用 enableVideo 后,本地视频即默认开启。你可以调用 enableLocalVideo(false) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(true)

成功禁用或启用本地视频采集后,远端会触发 onUserEnableLocalVideo 回调。

注解
该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。
参数
enabled
  • true: 开启本地视频采集和渲染 (默认);
  • false: 关闭使用本地摄像头设备。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为 false 时,该方法不需要本地有摄像头。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteAllRemoteVideoStreams()

virtual int agora::rtc::IRtcEngine::muteAllRemoteVideoStreams ( bool  mute)
pure virtual

接收/停止接收所有远端视频流。

参数
mute
  • true: 停止接收所有远端视频流;
  • false: 允许接收所有远端视频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setDefaultMuteAllRemoteVideoStreams()

virtual int agora::rtc::IRtcEngine::setDefaultMuteAllRemoteVideoStreams ( bool  mute)
pure virtual

设置是否默认停止接收视频流。

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteVideoStreams (true),会接收不到设置后加入频道的用户的视频流。

注解
停止接收视频流后,如果想要恢复接收,请调用 muteRemoteVideoStream (false),并指定你想要接收的远端用户 uid; 如果想恢复接收多个用户的视频流,则需要多次调用 muteRemoteVideoStreamsetDefaultMuteAllRemoteVideoStreams (false) 只能恢复接收后面加入频道的用户的视频流。
参数
mute
  • true: 默认停止接收所有远端视频;
  • false: 默认接收所有远端视频(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteRemoteVideoStream()

virtual int agora::rtc::IRtcEngine::muteRemoteVideoStream ( uid_t  userId,
bool  mute 
)
pure virtual

接收/停止接收指定远端用户的视频流。

注解
如果之前调用过 muteAllRemoteVideoStreams (true) 停止接收放所有远端视频流,在调用本 API 之前请确保你已调用 muteAllRemoteVideoStreams (false) 。muteAllRemoteVideoStreams 是全局控制,muteRemoteVideoStream 是精细控制。
参数
userId指定用户的用户 ID。
mute
  • true: 停止接收指定远端用户的视频流;
  • false: 允许接收指定远端用户的视频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteVideoStreamType()

virtual int agora::rtc::IRtcEngine::setRemoteVideoStreamType ( uid_t  userId,
REMOTE_VIDEO_STREAM_TYPE  streamType 
)
pure virtual

设置订阅的视频流类型。

在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流可以接为高分辨率高码率的视频流, 小流则是低分辨率低码率的视频流。

正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。

视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 onApiCallExecuted 中返回。

参数
userId用户 ID。
streamType视频流类型: REMOTE_VIDEO_STREAM_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteDefaultVideoStreamType()

virtual int agora::rtc::IRtcEngine::setRemoteDefaultVideoStreamType ( REMOTE_VIDEO_STREAM_TYPE  streamType)
pure virtual

设置默认订阅的视频流类型。

在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式, 接收端可以选择接收大流还是小流。其中,大流可以接为高分辨率高码率的视频流, 小流则是低分辨率低码率的视频流。

正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认 的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 onApiCallExecuted 中返回。

参数
streamType视频流类型: REMOTE_VIDEO_STREAM_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableAudioVolumeIndication()

virtual int agora::rtc::IRtcEngine::enableAudioVolumeIndication ( int  interval,
int  smooth,
bool  report_vad 
)
pure virtual

启用说话者音量提示。

该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。启用该方法后,无论频道内是否有人说话,都会在 onAudioVolumeIndication 回调中按设置的间隔时间返回音量提示。

参数
interval指定音量提示的时间间隔:
  • ≤ 0: 禁用音量提示功能;
  • > 0: 返回音量提示的间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调。
smooth平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
report_vad
  • true:开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
  • false:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startAudioRecording() [1/2]

virtual int agora::rtc::IRtcEngine::startAudioRecording ( const char *  filePath,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)
pure virtual

开始客户端录音。

弃用:
该方法从 v2.9.1 起废弃,其默认录音采样率为 32 kHz,不可修改。请改用新的 startAudioRecording2 方法。

Agora SDK 支持通话过程中在客户端进行录音。该方法录制频道内所有用户的音频,并生成一个包含所有用户声音的录音文件,录音文件格式可以为:

  • .wav: 文件大,音质保真度高;
  • .aac: 文件小,有一定的音质保真度损失。

请确保 App 里指定的目录存在且可写。该接口需在 joinChannel 之后调用。如果调用 leaveChannel 时还在录音,录音会自动停止。

参数
filePath录音文件的本地保存路径,由用户自行指定,需精确到文件名及格式,例如:/dir1/dir2/dir3/audio.aac。
qualityAUDIO_RECORDING_QUALITY_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startAudioRecording() [2/2]

virtual int agora::rtc::IRtcEngine::startAudioRecording ( const char *  filePath,
int  sampleRate,
AUDIO_RECORDING_QUALITY_TYPE  quality 
)
pure virtual

开始客户端录音。

Agora SDK 支持通话过程中在客户端进行录音。调用该方法后,你可以录制频道内所有用户的音频,并得到一个包含所有用户声音的录音文件。录音文件格式可以为:

  • .wav: 文件大,音质保真度较高。
  • .aac: 文件小,音质保真度较低。
注解
参数
filePath录音文件在本地保存的绝对路径,由用户自行指定,需精确到文件名及格式,例如:c:/music/audio.aac。
sampleRate录音采样率(Hz),可以设为以下值:
  • 16000
  • 32000(默认)
  • 44100
  • 48000
quality录音音质。详见 AUDIO_RECORDING_QUALITY_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopAudioRecording()

virtual int agora::rtc::IRtcEngine::stopAudioRecording ( )
pure virtual

停止客户端录音。

停止录音。该接口需要在 leaveChannel 之前调用,不然会在调用 leaveChannel 时自动停止。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startAudioMixing()

virtual int agora::rtc::IRtcEngine::startAudioMixing ( const char *  filePath,
bool  loopback,
bool  replace,
int  cycle 
)
pure virtual

开始播放音乐文件。

指定本地或在线音频文件来和麦克风采集的音频流进行混音和替换。替换是指用音频文件替换录音设备采集的音频流。该方法可以选择是否让对方听到本地播 放的音频并指定循环播放的次数。成功调用该方法后,本地会触发 onAudioMixingStateChanged (PLAY) 回调。播放结束后, 会收到 onAudioMixingStateChanged (STOPPED) 回调。

注解
  • 请在频道内调用该方法,如果在频道外调用该方法可能会出现问题。
  • 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR = 701。
参数
filePath指定需要混音的本地或在线音频文件的绝对路径,例如:c:/music/audio.mp4。建议填写文件后缀名。若无法确定文件后缀名,可不填。 支持的音频格式包括:3GP、ASF、ADTS、AVI、MP3、MP4、MPEG-4、SAMI 和 WAVE。 详见 Supported Media Formats in Media Foundation
loopback
  • true: 只有本地用户可以听到混音的音频;
  • false: 本地用户和远端用户都能听到混音的音频。
replace
  • true: 只推送指定的本地音频文件或者线上音频文件,不传输麦克风收录的音频。
  • false: 本地音频文件与来自麦克风的音频流混音。
cycle循环播放次数:
  • 正整数: 循环播放的次数;
  • -1: 无限循环。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopAudioMixing()

virtual int agora::rtc::IRtcEngine::stopAudioMixing ( )
pure virtual

停止播放音乐文件。

该方法停止播放音乐文件。请在频道内调用该方法。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ pauseAudioMixing()

virtual int agora::rtc::IRtcEngine::pauseAudioMixing ( )
pure virtual

暂停播放音乐文件。

该方法暂停播放音乐文件。请在频道内调用该方法。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ resumeAudioMixing()

virtual int agora::rtc::IRtcEngine::resumeAudioMixing ( )
pure virtual

恢复播放音乐文件。

该方法恢复混音,继续播放音乐文件。请在频道内调用该方法。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setHighQualityAudioParameters()

virtual int agora::rtc::IRtcEngine::setHighQualityAudioParameters ( bool  fullband,
bool  stereo,
bool  fullBitrate 
)
pure virtual
弃用:
该方法已废弃。声网不建议你使用。如果你希望设置音频高音质选项,请改用 setAudioProfile 方法。

设置音频高音质选项。

参数
fullband全频带编解码器(48 kHz 采样率), 不兼容 v1.7.4 以前版本
  • true:启用全频带编解码器
  • false:禁用全频带编解码器
stereo立体声编解码器,不兼容 v1.7.4 以前版本
  • true:启用立体声编解码器
  • false:禁用立体声编解码器
fullBitrate高码率模式,建议仅在纯音频模式下使用
  • true:启用高码率模式
  • false:禁用高码率模式
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ adjustAudioMixingVolume()

virtual int agora::rtc::IRtcEngine::adjustAudioMixingVolume ( int  volume)
pure virtual

调节音乐文件的播放音量。

该方法调节混音音乐文件在本端和远端的播放音量大小。请在频道内调用该方法。

注解
调用该方法不影响调用 playEffect 播放音效文件的音量。
参数
volume音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ adjustAudioMixingPlayoutVolume()

virtual int agora::rtc::IRtcEngine::adjustAudioMixingPlayoutVolume ( int  volume)
pure virtual

调节音乐文件本端播放音量。

该方法调节混音音乐文件在本端的播放音量大小。请在频道内调用该方法。

参数
volume音乐文件音量范围为 0~100。100 (默认值) 为原始文件音量。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getAudioMixingPlayoutVolume()

virtual int agora::rtc::IRtcEngine::getAudioMixingPlayoutVolume ( )
pure virtual

获取音乐文件的本地播放音量。

该方法获取混音的音乐文件本地播放音量,方便排查音量相关问题。

注解
请在频道内调用该方法。
返回
  • ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]
  • < 0: 方法调用失败

◆ adjustAudioMixingPublishVolume()

virtual int agora::rtc::IRtcEngine::adjustAudioMixingPublishVolume ( int  volume)
pure virtual

调节音乐文件远端播放音量。

该方法调节混音音乐文件在远端的播放音量大小。请在频道内调用该方法。

参数
volume音乐文件音量范围为 0~100。100 (默认值) 为原始文件音量。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getAudioMixingPublishVolume()

virtual int agora::rtc::IRtcEngine::getAudioMixingPublishVolume ( )
pure virtual

获取音乐文件的远端播放音量

该接口可以方便开发者排查音量相关问题。

注解
请在频道中调用该方法
返回
  • ≥ 0:方法调用成功则返回音量值,范围为 [0, 100]。
  • < 0:方法调用失败

◆ getAudioMixingDuration()

virtual int agora::rtc::IRtcEngine::getAudioMixingDuration ( )
pure virtual

获取音乐文件总时长。

该方法获取音乐文件总时长,单位为毫秒。请在频道内调用该方法。

返回
  • ≥ 0: 方法调用成功返回音乐文件时长。
  • < 0: 方法调用失败

◆ getAudioMixingCurrentPosition()

virtual int agora::rtc::IRtcEngine::getAudioMixingCurrentPosition ( )
pure virtual

获取音乐文件的播放进度。

该方法获取当前音乐文件播放进度,单位为毫秒。请在频道内调用该方法。

返回
  • ≥ 0: 方法调用成功返回音乐文件播放进度。
  • < 0: 方法调用失败

◆ setAudioMixingPosition()

virtual int agora::rtc::IRtcEngine::setAudioMixingPosition ( int  pos)
pure virtual

设置音乐文件的播放位置。

该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而非从头到尾播放整个文件。

参数
pos整数。进度条位置,单位为毫秒。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setAudioMixingPitch()

virtual int agora::rtc::IRtcEngine::setAudioMixingPitch ( int  pitch)
pure virtual

调整本地播放的音乐文件的音调。

自从
v3.0.1

本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。

注解
该方法需在 startAudioMixing 后调用。
参数
pitch按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12], 每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ getEffectsVolume()

virtual int agora::rtc::IRtcEngine::getEffectsVolume ( )
pure virtual

获取音效文件的播放音量。

音量范围为 0~100。100 (默认值)为原始文件音量。

返回
  • 音效文件的音量。
  • < 0: 方法调用失败

◆ setEffectsVolume()

virtual int agora::rtc::IRtcEngine::setEffectsVolume ( int  volume)
pure virtual

设置音效文件的播放音量。

音量范围为 0~100。100 (默认值)为原始文件音量。

参数
volume该方法设置音效的音量。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setVolumeOfEffect()

virtual int agora::rtc::IRtcEngine::setVolumeOfEffect ( int  soundId,
int  volume 
)
pure virtual

实时调整音效文件的播放音量。

参数
soundId指定音效的 ID。每个音效均有唯一的 ID。
volume播放音量。音量范围为 0~100。100 (默认值)为原始文件音量。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableFaceDetection()

virtual int agora::rtc::IRtcEngine::enableFaceDetection ( bool  enable)
pure virtual

开启/关闭本地人脸检测。仅适用于 Android 和 iOS。

自从
v3.0.1

开启本地人脸检测后,SDK 会触发 onFacePositionChanged 回调向你报告人脸检测的信息:

  • 摄像头采集的画面大小
  • 人脸在画面中的位置
  • 人脸距设备屏幕的距离
参数
enable是否开启人脸检测:
  • true:开启人脸检测
  • false:(默认)关闭人脸检测
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ playEffect()

virtual int agora::rtc::IRtcEngine::playEffect ( int  soundId,
const char *  filePath,
int  loopCount,
double  pitch,
double  pan,
int  gain,
bool  publish = false 
)
pure virtual

播放指定音效文件。

你可以多次调用该方法,通过传入不同的音效文件的 soundIDfilePath,同时播放多个音效文件,实现音效叠加。为获得最佳用户体验,我们建议同时播放的音效文件不要超过 3 个。在 macOS 和 Windows 上,该方法不支持同时播放多个在线音效文件。

参数
soundId指定音效的 ID。每个音效均有唯一的 ID。
注解
如果你已通过 preloadEffect 将音效加载至内存,确保这里设置的 soundId 与 preloadEffect 设置的 soundId 相同。
参数
filePath音效文件的绝对路径或 URL 地址,例如:c:/music/audio.mp4。建议填写文件后缀名。若无法确定文件后缀名,可不填。 支持的音频格式包括:mp3、mp4、m4a、aac、3gp、mkv 及 wav。 详见 Supported Media Formats in Media Foundation
loopCount设置音效循环播放的次数:
  • 0: 播放音效一次;
  • 1: 播放音效两次;
  • -1: 无限循环播放音效,直至调用 stopEffectstopAllEffects 后停止。
pitch设置音效的音调 取值范围为 [0.5, 2]。默认值为 1.0,表示不需要修改音调。取值越小,则音调越低。
pan设置是否改变音效的空间位置。取值范围为 [-1.0, 1.0]:
  • 0.0: 音效出现在正前方;
  • 1.0: 音效出现在右边;
  • -1.0: 音效出现在左边。
gain设置是否改变单个音效的音量。取值范围为 [0.0, 100.0]。默认值为 100.0。取值越小,则音效的音量越低。
publish设置是否将音效传到远端:
  • true: 音效在本地播放的同时,会发布到 Agora 云端,因此远端用户也能听到该音效;
  • false: 音效不会发布到 Agora 云端,因此只能在本地听到该音效。
返回
  • 0:方法调用成功
  • < 0:方法调用失败

◆ stopEffect()

virtual int agora::rtc::IRtcEngine::stopEffect ( int  soundId)
pure virtual

停止播放指定音效文件。

参数
soundId指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopAllEffects()

virtual int agora::rtc::IRtcEngine::stopAllEffects ( )
pure virtual

停止播放所有音效文件。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ preloadEffect()

virtual int agora::rtc::IRtcEngine::preloadEffect ( int  soundId,
const char *  filePath 
)
pure virtual

将音效文件加载至内存。

该方法将指定音效文件预加载至内存。

注解
该方法不支持在线音频文件。

为保证通信畅通,请注意控制预加载音效文件的大小,并在 joinChannel 前就使用该方法完成音效预加载。音频文件支持以下音频格式: mp3、aac、m4a、3gp,和 wav。

参数
soundId指定音效文件的 ID。每个音效文件均有唯一的 ID。
filePath音效文件的绝对路径。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ unloadEffect()

virtual int agora::rtc::IRtcEngine::unloadEffect ( int  soundId)
pure virtual

从内存释放某个预加载的音效文件。

参数
soundId指定音效文件的 ID。每个音效文件均有唯一的 ID
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ pauseEffect()

virtual int agora::rtc::IRtcEngine::pauseEffect ( int  soundId)
pure virtual

暂停音效文件播放。

参数
soundId指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ pauseAllEffects()

virtual int agora::rtc::IRtcEngine::pauseAllEffects ( )
pure virtual

暂停所有音效文件播放。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ resumeEffect()

virtual int agora::rtc::IRtcEngine::resumeEffect ( int  soundId)
pure virtual

恢复播放指定音效文件。

参数
soundId指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ resumeAllEffects()

virtual int agora::rtc::IRtcEngine::resumeAllEffects ( )
pure virtual

恢复播放所有音效文件。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableSoundPositionIndication()

virtual int agora::rtc::IRtcEngine::enableSoundPositionIndication ( bool  enabled)
pure virtual

开启/关闭远端用户的语音立体声。

如果想调用 setRemoteVoicePosition 实现听声辨位的功能,请确保在加入频道前调用该方法开启远端用户的语音立体声。

参数
enabled是否开启远端用户语音立体声:
  • true: 开启
  • false: 关闭
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteVoicePosition()

virtual int agora::rtc::IRtcEngine::setRemoteVoicePosition ( int  uid,
double  pan,
double  gain 
)
pure virtual

设置远端用户的语音位置。

设置远端用户声音的空间位置和音量,方便本地用户听声辨位。

通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。

注解
为获得最佳听觉体验,我们建议使用该方法时使用立体声外放。
参数
uid远端用户的 ID
pan设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
  • (默认)0.0: 声音出现在正前方。
  • -1.0: 声音出现在左边。
  • 1.0: 声音出现在右边。
gain设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLocalVoicePitch()

virtual int agora::rtc::IRtcEngine::setLocalVoicePitch ( double  pitch)
pure virtual

设置本地语音音调。

参数
pitch语音频率可以 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLocalVoiceEqualization()

virtual int agora::rtc::IRtcEngine::setLocalVoiceEqualization ( AUDIO_EQUALIZATION_BAND_FREQUENCY  bandFrequency,
int  bandGain 
)
pure virtual

设置本地语音音效均衡。

参数
bandFrequency频谱子带索引。取值范围是 [0,9],分别代表音效的 10 个频带。对应的中心频率为 [31,62,125,250,500,1k,2k,4k,8k,16k] Hz。详见 AUDIO_EQUALIZATION_BAND_FREQUENCY
bandGain每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15]。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLocalVoiceReverb()

virtual int agora::rtc::IRtcEngine::setLocalVoiceReverb ( AUDIO_REVERB_TYPE  reverbKey,
int  value 
)
pure virtual

设置本地音效混响。

参数
reverbKey混响音效 Key。该方法共有 5 个混响音效 Key: AUDIO_REVERB_TYPE
value各混响音效 Key 所对应的值:
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLocalVoiceChanger()

virtual int agora::rtc::IRtcEngine::setLocalVoiceChanger ( VOICE_CHANGER_PRESET  voiceChanger)
pure virtual

设置本地语音变声、美音或语聊美声效果。

通信场景下的用户或直播场景下的主播均可调用该方法为本地语音设置以下效果。成功设置以后,频道内的所有用户均可听到声音效果。

  • 变声效果:枚举值以 VOICE_CHANGER 为前缀。效果包括老男人、小男孩、小女孩、猪八戒、空灵和绿巨人,通常用于语聊场景。
  • 美音效果:枚举值以 VOICE_BEAUTY 为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷,通常用于语聊和唱歌场景。
  • 语聊美声效果:枚举值以 GENERAL_BEAUTY_VOICE 为前缀。效果包括磁性(男)、清新(女)和活力(女),通常用于语聊场景。该功能主要细化了男声和女声各自的特点。
注解
参数
voiceChanger预设本地语音变声、美音或语聊美声效果选项,默认值为 VOICE_CHANGER_OFF ,即原声。详见 VOICE_CHANGER_PRESET 。 设置语聊美声效果时,Agora 推荐使用 GENERAL_BEAUTY_VOICE_MALE_MAGNETIC 处理男声,使用 GENERAL_BEAUTY_VOICE_FEMALE_FRESHGENERAL_BEAUTY_VOICE_FEMALE_VITALITY 处理女声,否则音频可能会产生失真。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLocalVoiceReverbPreset()

virtual int agora::rtc::IRtcEngine::setLocalVoiceReverbPreset ( AUDIO_REVERB_PRESET  reverbPreset)
pure virtual

设置本地语音混响(含虚拟立体声效果)。

通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后,频道内的所有用户均可听到声音效果。

注解
参数
reverbPreset本地语音混响选项,默认值为 AUDIO_REVERB_OFF ,即原声。详见 AUDIO_REVERB_PRESET 。 为达到更好的混响效果,Agora 推荐使用以 AUDIO_REVERB_FX 为前缀的枚举值。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLogFile()

virtual int agora::rtc::IRtcEngine::setLogFile ( const char *  filePath)
pure virtual

设置日志文件。

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。 App 必须保证指定的目录存在而且可写。

注解
  • Windows 平台下日志文件的默认地址为:"C:\Users\<user_name>\AppData\Local\Agora\<process_name>"。
  • 如需调用本方法,请在调用 initialize 方法初始化 IRtcEngine 对象后立即调用,否则可能造成输出日志不完整。
参数
filePath日志文件的完整路径。该日志文件为 UTF-8 编码。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLogFilter()

virtual int agora::rtc::IRtcEngine::setLogFilter ( unsigned int  filter)
pure virtual

设置日志输出等级。

设置 Agora SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别,你就可以看到在该级别之前所有级别的日志信息。

例如,你选择 WARNING 级别,就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

参数
filter设置过滤等级: LOG_FILTER_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLogFileSize()

virtual int agora::rtc::IRtcEngine::setLogFileSize ( unsigned int  fileSizeInKBytes)
pure virtual

设置日志文件大小。

设置 SDK 输出的日志文件大小,单位为 KB。 Agora SDK 设有 2 个日志文件,每个文件大小为 512 KB。如果你将 fileSizeInKBytes 设置为 1024 KB, SDK 会最多输出 2 M 的日志文件。如果日志文件超出设置值,新的日志会覆盖之前的日志。

参数
fileSizeInKBytes指定 SDK 输出日志文件的内存大小,单位为 KB。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败, 有可能是因为传入的参数无效。

◆ setLocalRenderMode() [1/2]

virtual int agora::rtc::IRtcEngine::setLocalRenderMode ( RENDER_MODE_TYPE  renderMode)
pure virtual
弃用:
该方法已废弃,请改用 setLocalRenderMode2。

设置本地视图显示模式。

该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。

参数
renderModeRENDER_MODE_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLocalRenderMode() [2/2]

virtual int agora::rtc::IRtcEngine::setLocalRenderMode ( RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode 
)
pure virtual
自从
v3.0.0

更新本地视图显示模式。

初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频。

注解
  • 请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。
  • 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。
参数
renderMode本地视图的渲染模式,详见 RENDER_MODE_TYPE
mirrorMode
  • 本地视图的镜像模式,详见 VIDEO_MIRROR_MODE_TYPE
  • Note: 如果你使用前置摄像头,默认启动本地用户视图镜像模式;如果你使用后置摄像头,默认关闭本地视图镜像模式。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteRenderMode() [1/2]

virtual int agora::rtc::IRtcEngine::setRemoteRenderMode ( uid_t  userId,
RENDER_MODE_TYPE  renderMode 
)
pure virtual
弃用:
该方法已废弃,请使用 setRemoteRenderMode2。

设置远端视图显示模式。

该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。

参数
userId远端用户 ID。
renderModeRENDER_MODE_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteRenderMode() [2/2]

virtual int agora::rtc::IRtcEngine::setRemoteRenderMode ( uid_t  userId,
RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode 
)
pure virtual
自从
v3.0.0

更新远端视图显示模式。

初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

注解
  • 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
  • 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
userId远端用户 ID。
renderMode远端用户视图的渲染模式,详见 RENDER_MODE_TYPE
mirrorMode
  • 远端用户视图的镜像模式,详见 VIDEO_MIRROR_MODE_TYPE
  • Note: 默认关闭远端用户的镜像模式。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLocalVideoMirrorMode()

virtual int agora::rtc::IRtcEngine::setLocalVideoMirrorMode ( VIDEO_MIRROR_MODE_TYPE  mirrorMode)
pure virtual
弃用:
该方法已废弃,请改用 setupLocalVideosetLocalRenderMode

设置本地视频镜像模式。

该方法须在 startPreview 前设置。如果在开启预览后设置,需要重新开启预览才能生效。

警告
请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。
参数
mirrorModeVIDEO_MIRROR_MODE_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableDualStreamMode()

virtual int agora::rtc::IRtcEngine::enableDualStreamMode ( bool  enabled)
pure virtual

开关双流模式。

该方法设置单流(默认)或者双流模式。发送端开启双流模式后,接收端可以选择接收大流还是小流。其中,大流指高分辨率、高码率的视频流,小流指低分辨率、低码率的视频流。

参数
enabled
  • true: 双流;
  • false: 单流(默认)。

◆ setExternalAudioSource()

virtual int agora::rtc::IRtcEngine::setExternalAudioSource ( bool  enabled,
int  sampleRate,
int  channels 
)
pure virtual

设置外部音频采集参数。请在 joinChannel 前调用该方法。

参数
enabled
  • true: 开启使用外部音频源的功能;
  • false: 关闭使用外部音频源的功能(默认)。
sampleRate外部音频源的采样率 (Hz),可设置为 8000,16000,32000,44100 或 48000。
channels外部音频源的通道数,可设置为 1 或 2:
  • 1: 单声道
  • 2: 双声道
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setExternalAudioSink()

virtual int agora::rtc::IRtcEngine::setExternalAudioSink ( bool  enabled,
int  sampleRate,
int  channels 
)
pure virtual

设置外部音频渲染。

该方法适用于需要自行渲染音频的场景。开启外部音频渲染后,你可以通过调用 pullAudioFrame 方法拉取远端音频数据。 App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。

注解
开启外部音频渲染后,App 会无法从 onPlaybackAudioFrame 回调中获得数据。
参数
enabled
  • true: 开启外部音频渲染。
  • false: (默认)关闭外部音频渲染。
sampleRate外部音频渲染的采样率 (Hz),可设置为 16000,32000,44100 或 48000。
channels外部音频渲染的声道数,可设置为 1 或 2:
  • 1: 单声道
  • 2: 双声道
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRecordingAudioFrameParameters()

virtual int agora::rtc::IRtcEngine::setRecordingAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
pure virtual

设置录制的声音格式。

该方法设置 onRecordAudioFrame 回调的录制声音格式。

参数
sampleRate指定 onRecordAudioFrame 中返回数据的采样率,可设置为 8000、 16000、 32000、 44100 或 48000。
channel指定 onRecordAudioFrame 中返回数据的通道数,可设置为 1 或 2:
  • 1: 单声道
  • 2: 双声道
modeonRecordAudioFrame 回调的使用模式: RAW_AUDIO_FRAME_OP_MODE_TYPE
samplesPerCall指定 onRecordAudioFrame 中返回数据的采样点数,如 RTMP 推流应用中通常为 1024。
注解
SDK 会根据该采样间隔触发 onRecordAudioFrame 回调。请确保采样间隔不得小于 0.01 (s)。其中,采样间隔 = samplesPerCall/(sampleRate × channel)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setPlaybackAudioFrameParameters()

virtual int agora::rtc::IRtcEngine::setPlaybackAudioFrameParameters ( int  sampleRate,
int  channel,
RAW_AUDIO_FRAME_OP_MODE_TYPE  mode,
int  samplesPerCall 
)
pure virtual

设置播放的声音格式。

参数
sampleRate指定 onPlaybackAudioFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000。
channel指定 onPlaybackAudioFrame 中返回数据的通道数,可设置为 1 或 2:
  • 1: 单声道
  • 2: 双声道
mode指定 onPlaybackAudioFrame 的使用模式: RAW_AUDIO_FRAME_OP_MODE_TYPE
samplesPerCall指定 onPlaybackAudioFrame 中返回数据的采样点数,如RTMP推流应用中通常为 1024。
注解
SDK 会根据该采样间隔触发 onPlaybackAudioFrame 回调。请确保采样间隔不得小于 0.01 (s)。其中,采样间隔 = samplesPerCall/(sampleRate × channel)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setMixedAudioFrameParameters()

virtual int agora::rtc::IRtcEngine::setMixedAudioFrameParameters ( int  sampleRate,
int  samplesPerCall 
)
pure virtual

设置录制与播放声音混音后的数据格式

参数
sampleRate指定 onMixedAudioFrame 中返回数据的采样率,可设置为 8000,16000,32000,44100 或 48000。
samplesPerCall指定 onMixedAudioFrame 中返回数据的采样点数,如 RTMP 推流应用中通常为 1024。
注解
SDK 会根据该采样间隔触发 onMixedAudioFrame 回调。请确保采样间隔不得小于 0.01 (s)。其中,采样间隔 = samplesPerCall/(sampleRate × channels)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ adjustRecordingSignalVolume()

virtual int agora::rtc::IRtcEngine::adjustRecordingSignalVolume ( int  volume)
pure virtual

调节录音音量。

参数
volume录音信号音量。为避免回声并提升通话质量,Agora 建议将 volume 值设为 [0,100]。如果 volume 值需超过 100,联系技术支持:
  • 0: 静音;
  • 100: 原始音量。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ adjustPlaybackSignalVolume()

virtual int agora::rtc::IRtcEngine::adjustPlaybackSignalVolume ( int  volume)
pure virtual

调节本地播放的所有远端用户音量。

注解
  • 该方法调节的是本地播放的所有远端用户混音后的音量。
  • 从 v2.3.2 开始,静音本地音频需同时调用 adjustPlaybackSignalVolumeadjustAudioMixingPlayoutVolume 方法,并将 volume 设置为 0
参数
volume播放音量。为避免回声并提升通话质量,Agora 建议将 volume 值设为 [0,100]。如果 volume 值需超过 100,联系技术支持:
  • 0: 静音;
  • 100: 原始音量。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableWebSdkInteroperability()

virtual int agora::rtc::IRtcEngine::enableWebSdkInteroperability ( bool  enabled)
pure virtual
弃用:
该方法已废弃。自 Native SDK v3.0.0 及之后,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。

打开直播场景下与 Agora Web SDK 的互通。

注解
  • 该方法仅适用于直播场景。通信场景默认打开与 Web SDK 的互通。
  • 如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。
参数
enabled
  • true: 打开互通;
  • false: 关闭互通(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setVideoQualityParameters()

virtual int agora::rtc::IRtcEngine::setVideoQualityParameters ( bool  preferFrameRateOverImageQuality)
pure virtual
弃用:
该方法从 v2.4.0 起废弃。Agora 建议使用 VideoEncoderConfiguration 类中的 degradationPrefer 参数设置视频质量偏好。该方法允许用户设置视频的优化选项。

设置视频优化选项(仅适用于直播)。

参数
preferFrameRateOverImageQuality支持两种优化选项:
  • true:画质和流畅度里,优先保证流畅度
  • false:画质和流畅度里,优先保证画质 (默认)
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLocalPublishFallbackOption()

virtual int agora::rtc::IRtcEngine::setLocalPublishFallbackOption ( STREAM_FALLBACK_OPTIONS  option)
pure virtual

设置弱网条件下发布的音视频流回退选项。

网络不理想的环境下,实时通信音视频的质量都会下降。使用该接口并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2) 后,SDK 会在上行弱网且音视频质量严重受影响时,自动关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。当本地推流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发本地发布的媒体流已回退为音频流 onLocalPublishFallbackToAudioOnly 回调。

注解
视频直播场景下,旁路推流的发流用户(即主播)设置 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2) 可能导致 CDN 观众听到的声音有所延迟。Agora 不建议主播使用视频流回退机制。
参数
option本地发流回退处理选项:
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteSubscribeFallbackOption()

virtual int agora::rtc::IRtcEngine::setRemoteSubscribeFallbackOption ( STREAM_FALLBACK_OPTIONS  option)
pure virtual

设置弱网条件下订阅的音视频流的回退选项。

默认 optionSTREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1) 。 如果你使用本方法并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流,或关断视频流,从而保证或提高音频质量。 同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。 当远端订阅流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发 onRemoteSubscribeFallbackToAudioOnly 回调。

参数
option详见 STREAM_FALLBACK_OPTIONS
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ switchCamera()

virtual int agora::rtc::IRtcEngine::switchCamera ( )
pure virtual

切换前置/后置摄像头

注解
该方法仅适用于 Android 和 iOS 平台。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setDefaultAudioRouteToSpeakerphone()

virtual int agora::rtc::IRtcEngine::setDefaultAudioRouteToSpeakerphone ( bool  defaultToSpeaker)
pure virtual

设置默认的语音路由

该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法,语音默认从听筒出声。

各频道场景下默认的语音路由:

注解
  • 该方法仅适用于 Android 和 iOS 平台。
  • 在 iOS 平台上,该方法只在纯音频模式下工作,在有视频的模式下不工作。
  • 该方法需要在 joinChannel 前设置,否则不生效。如需在加入频道后更改默认语音路由,请调用 setEnableSpeakerphone 方法。
参数
defaultToSpeaker设置默认的语音路由
  • true: 语音路由为外放(扬声器)。如果设备连接了耳机或蓝牙,则无法切换到外放。
  • false:(默认)语音路由为听筒。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setEnableSpeakerphone()

virtual int agora::rtc::IRtcEngine::setEnableSpeakerphone ( bool  speakerOn)
pure virtual

启用/关闭扬声器播放

该方法设置是否将语音路由到扬声器(外放)。

该方法设置是否将语音路由设到扬声器(外放)。 你可以在 setDefaultAudioRouteToSpeakerphone 方法中查看默认的语音路由。

在 Android 上,setAudioProfilescenariosetChannelProfile 的设置 会影响 setEnableSpeakerphone 的行为。setEnableSpeakerphone 不生效的情况如下:

注解
  • 该方法仅适用于 Android 和 iOS 平台。
  • 请确保在调用此方法前已调用过 joinChannel 方法。
  • 调用该方法后,SDK 将返回 onAudioRouteChanged 回调提示状态已更改。
参数
speakerOn设置是否切换语音路由到扬声器(外放):
  • true: 切换到外放。如果设备连接了耳机或蓝牙,则无法切换到外放。
  • false: 切换到听筒。如果设备连接了耳机,则语音路由走耳机。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableInEarMonitoring()

virtual int agora::rtc::IRtcEngine::enableInEarMonitoring ( bool  enabled)
pure virtual

开启耳返功能。

注解
该方法仅适用于 Android 和 iOS 平台。

该方法打开或关闭耳返功能。

参数
enabled开启/关闭耳返功能:
  • true:开启耳返功能
  • false:关闭耳返功能(默认)
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setInEarMonitoringVolume()

virtual int agora::rtc::IRtcEngine::setInEarMonitoringVolume ( int  volume)
pure virtual

设置耳返音量

注解
该方法仅适用于 Android 和 iOS 平台。
参数
volume设置耳返音量,取值范围在 [0,100]。默认值为 100
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ isSpeakerphoneEnabled()

virtual bool agora::rtc::IRtcEngine::isSpeakerphoneEnabled ( )
pure virtual

查询扬声器启用状态

注解
该方法仅适用于 Android 和 iOS 平台。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setAudioSessionOperationRestriction()

virtual int agora::rtc::IRtcEngine::setAudioSessionOperationRestriction ( AUDIO_SESSION_OPERATION_RESTRICTION  restriction)
pure virtual

设置 SDK 对 Audio Session 的控制权限

该接口可以在任意时候调用,可以在任意时候通过该方法把控制权交还给 SDK。

注解
  • 该方法仅适用于 iOS 平台。
  • 该方法限制 Agora SDK 对 Audio Session 的操作权限。在默认情况下,SDK 和 App 对 Audio Session 都有控制权,但某些场景下,App 会希望限制 Agora SDK 对 Audio Session 的控制权限,而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。
  • 一旦调用该方法限制了 Agora SDK 对 Audio Session 的控制权限, SDK 将无法对 Audio Session 进行相关设置,而需要用户自己或第三方组件进行维护。
参数
restrictionAgora SDK 对 Audio Session 的控制权限,详见: AUDIO_SESSION_OPERATION_RESTRICTION 。该 restriction 为 Bit Mask,每个 Bit 对应一个权限。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableLoopbackRecording()

virtual int agora::rtc::IRtcEngine::enableLoopbackRecording ( bool  enabled,
const char *  deviceName = NULL 
)
pure virtual

开启声卡采集

启用声卡采集功能后,声卡播放的声音会被合到本地音频流中,从而可以发送到远端。

注解
  • 该方法仅适用于 macOS 和 Windows 平台。
  • macOS 系统默认声卡不支持采集功能,如需开启此功能需要 App 自己启用一个虚拟声卡,并将该虚拟声卡的名字作为 deviceName 传入 SDK。 Agora 测试并推荐 soundflower 作为虚拟声卡。
参数
enabled设置是否开启声卡采集:
  • true: 开启声卡采集
  • false: (默认)关闭声卡采集
deviceName声卡的设备名。默认设为 NULL,即使用当前声卡采集。 如果用户使用虚拟声卡,如 “Soundflower”,可以将虚拟声卡名称 “Soundflower” 作为参数,SDK 会找到对应的虚拟声卡设备,并开始采集。

◆ startScreenCaptureByDisplayId()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByDisplayId ( unsigned int  displayId,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

通过屏幕 ID 共享屏幕。

共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕 ID。

注解
该方法仅适用于 macOS。
参数
displayId指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。关于如何获取屏幕 ID,请参考进阶功能《共享屏幕》。
regionRect(可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见: Rectangle 。如果设置的共享区域超出了屏幕的边界,则只共享屏幕视窗内的内容;如果宽或高为 0,则共享整个屏幕。
captureParams屏幕共享的编码参数配置。详见: ScreenCaptureParameters
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败:

◆ startScreenCaptureByScreenRect()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByScreenRect ( const Rectangle screenRect,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

通过指定区域共享屏幕。

共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕区域。

参数
screenRect指定待共享的屏幕相对于虚拟屏的位置。关于如何获取屏幕位置,请参考进阶功能《共享屏幕》。
regionRect(可选)指定待共享区域相对于整个屏幕屏幕的位置。如不填,则表示共享整个屏幕。详见: Rectangle 。 如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕。
captureParams屏幕共享的编码参数配置。详见: ScreenCaptureParameters
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败:
    • ERR_INVALID_STATE: 屏幕共享状态无效。可能有屏幕或窗口正在共享中,请调用 stopScreenCapturecreenCapture 停止共享。
    • ERR_INVALID_ARGUMENT: 传入的参数无效。

◆ startScreenCaptureByWindowId()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByWindowId ( view_t  windowId,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

通过窗口 ID 共享窗口。

共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。

自 v3.0.0 起,该方法支持共享通用 Windows 平台。声网对主流的 Windows 应用进行了测试,结果如下:

系统版本 软件 软件版本 是否支持
win10 Chrome 76.0.3809.100
Office Word 18.1903.1152.0
Office Excel
Office PPT
WPS Word 11.1.0.9145
WPS Excel
WPS PPT
Media Player(系统自带) 全部
win8 Chrome 全部
Office Word 全部
Office Excel
Office PPT
WPS Word 11.1.0.9098
WPS Excel
WPS PPT
Media Player(系统自带) 全部
win7 Chrome 73.0.3683.103
Office Word 全部
Office Excel
Office PPT
WPS Word 11.1.0.9098
WPS Excel
WPS PPT
Media Player(系统自带) 全部
参数
windowId指定待共享的窗口 ID。关于如何获取窗口 ID,请参考进阶功能《共享屏幕》。
regionRect(可选)指定待共享的区域相对于整个窗口的位置。如不填,则表示共享整个窗口。详见: Rectangle 。如果设置的共享区域超出了窗口的边界,则只共享窗口内的内容;如果宽或高为 0,则共享整个窗口。
captureParams屏幕共享的编码参数配置。详见: ScreenCaptureParameters
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败:

◆ setScreenCaptureContentHint()

virtual int agora::rtc::IRtcEngine::setScreenCaptureContentHint ( VideoContentHint  contentHint)
pure virtual

设置屏幕共享内容类型。

设置屏幕共享的内容类型。Agora SDK 会根据不同的内容类型,使用不同的算法对共享效果进行优化。如果不调用该方法,SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE ,即无指定的内容类型。

参数
contentHint指定屏幕共享的内容类型。详见: VideoContentHint
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ updateScreenCaptureParameters()

virtual int agora::rtc::IRtcEngine::updateScreenCaptureParameters ( const ScreenCaptureParameters captureParams)
pure virtual

更新屏幕共享的编码参数配置。

参数
captureParams屏幕共享的编码参数配置。详见: ScreenCaptureParameters
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败:
    • ERR_NOT_READY: 如果当前没有共享的屏幕,会返回该错误码。

◆ updateScreenCaptureRegion() [1/2]

virtual int agora::rtc::IRtcEngine::updateScreenCaptureRegion ( const Rectangle regionRect)
pure virtual

更新屏幕共享区域。

参数
regionRect待共享区域相对于整个屏幕或窗口的位置,如不填,则表示共享整个屏幕或窗口。详见: Rectangle 。如果设置的共享区域超出了屏幕或窗口的边界,则只共享屏幕或窗口内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕或窗口。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败:
    • ERR_NOT_READY: 如果当前没有共享的屏幕,会返回该错误码。

◆ stopScreenCapture()

virtual int agora::rtc::IRtcEngine::stopScreenCapture ( )
pure virtual

停止屏幕共享。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startScreenCapture()

virtual int agora::rtc::IRtcEngine::startScreenCapture ( WindowIDType  windowId,
int  captureFreq,
const Rect rect,
int  bitrate 
)
pure virtual

开始屏幕共享。

弃用:
该方法自 v2.4.0 起废弃,请使用以下方法作为替代:

该方法共享整个屏幕,指定窗口,或指定区域:

  • 共享整个屏幕 : 将 windowId 设为 0,且将 rect 设为 NULL。
  • 共享指定窗口 : 将 windowId 设为非 0,每个窗口都有一个非 0 的 windowId。
  • 共享指定区域 : 将 windowId 设为 0,且将 rect 设为非 NULL。在这个情况下,你可以共享指定区域,例如你可以拖动鼠标选中要共享的区域,但这个逻辑你由你自己实现的。这里的共享指定区域指的是共享整个屏幕里的某个区域。目前暂不支持共享指定窗口里的指定区域。
注解
当开启屏幕共享功能时,captureFreq 参数为共享屏幕的帧率,值区间为 1 到 15 fps(必填)。无论你开启的是上述哪个功能,执行成功时均返回 0,执行失败时返回错误代码。
参数
windowId共享屏幕区域。 详见: WindowIDType。
captureFreq共享屏幕的帧率,必须设置,范围是 1 到 15 fps。
rect当 windowsId 设为 0 时该参数有效;当你将 rect 设为 NULL 时,整个屏幕被共享。
bitrate共享屏幕的码率。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ updateScreenCaptureRegion() [2/2]

virtual int agora::rtc::IRtcEngine::updateScreenCaptureRegion ( const Rect rect)
pure virtual

更新屏幕共享区域。

弃用:
请改用 updateScreenCaptureRegion
参数
rect待共享区域相对于整个屏幕的位置,如不填,则表示共享整个屏幕。 详见: Rect。 如果设置的共享区域超出了屏幕或窗口的边界,则只共享屏幕或窗口内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕或窗口。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败:
    • ERR_NOT_READY: 如果当前没有共享的屏幕,会返回该错误码。

◆ getCallId()

virtual int agora::rtc::IRtcEngine::getCallId ( agora::util::AString callId)
pure virtual

获取当前通话 ID。

客户端在每次 joinChannel 后会生成一个对应的 callId,标识该客户端的此次通话。有些方法如 ratecomplain 需要在通话结束后调用,向 SDK 提交反馈,这些方法必须指定 CallId 参数。使用这些反馈方法,需要在通话过程中调用 getCallId 方法获取 CallId,在通话结束后在反馈方法中作为参数传入。

参数
callId当前的通话 ID。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ rate()

virtual int agora::rtc::IRtcEngine::rate ( const char *  callId,
int  rating,
const char *  description 
)
pure virtual

给通话评分。

该方法能够让用户为通话评分,一般在通话结束后调用。

参数
callId通话 getCallId 函数获取的通话 ID。
rating给通话的评分,最低 1 分,最高 5 分。如超过这个范围,SDK 会返回 ERR_INVALID_ARGUMENT (2) 错误。
description(非必选项) 给通话的描述,可选,长度应小于 800 字节。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ complain()

virtual int agora::rtc::IRtcEngine::complain ( const char *  callId,
const char *  description 
)
pure virtual

投诉通话质量。

该方法让用户就通话质量进行投诉。一般在通话结束后调用。

参数
callId通话 getCallId 函数获取的通话 ID。
description(非必选项) 给通话的描述,可选,长度应小于 800 字节。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getVersion()

virtual const char* agora::rtc::IRtcEngine::getVersion ( int *  build)
pure virtual

查询 SDK 版本号。

参数
build编译号。
返回
当前的 SDK 版本号,格式为字符串,如 2.4.0。

◆ enableLastmileTest()

virtual int agora::rtc::IRtcEngine::enableLastmileTest ( )
pure virtual

启动网络测试。

该方法启用网络连接质量测试,用于检测用户目前的网络接入质量(上行网络质量)。默认该功能为关闭状态。该方法主要用于以下场景:

  • 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
  • 直播场景下,当用户角色由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。

启用该方法均会消耗网络流量,影响通话质量。用户必须在收到 onLastmileQuality 回调后须调用 disableLastmileTest 停止测试,再加入频道或切换为主播。

注解
  • 该方法请勿与 startLastmileProbeTest 同时使用。
  • 调用该方法后,在收到 onLastmileQuality 回调前请勿调用其他方法,否则可能由于 API 操作过于频繁导致回调无法执行。
  • 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
  • 加入频道前调用该方法检测网络质量后,SDK 会占用一路视频的带宽,码率与 setVideoEncoderConfiguration 中设置的码率相同。 加入频道后,无论是否调用了 disableLastmileTest ,SDK 均会自动停止带宽占用。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ disableLastmileTest()

virtual int agora::rtc::IRtcEngine::disableLastmileTest ( )
pure virtual

关闭网络测试。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startLastmileProbeTest()

virtual int agora::rtc::IRtcEngine::startLastmileProbeTest ( const LastmileProbeConfig config)
pure virtual

开始通话前网络质量探测。

开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

启用该方法后,SDK 会依次返回如下 2 个回调:

  • onLastmileQuality,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
  • onLastmileProbeResult,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。

该方法主要用于以下两种场景:

  • 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
  • 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
注解
  • 该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要和 enableLastmileTest 同时使用。
  • 调用该方法后,在收到 onLastmileQualityonLastmileProbeResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
  • 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
参数
configLast mile 网络探测配置,详见 LastmileProbeConfig
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopLastmileProbeTest()

virtual int agora::rtc::IRtcEngine::stopLastmileProbeTest ( )
pure virtual

停止通话前网络质量探测。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getErrorDescription()

virtual const char* agora::rtc::IRtcEngine::getErrorDescription ( int  code)
pure virtual

获取警告或错误描述。

参数
codeonWarningonError 提供的警告码或错误码。
返回
WARN_CODE_TYPEERROR_CODE_TYPE

◆ setEncryptionSecret()

virtual int agora::rtc::IRtcEngine::setEncryptionSecret ( const char *  secret)
pure virtual

启用内置加密,并设置数据加密密码。

在加入频道之前,App 需调用 setEncryptionSecret 方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。

注解
  • 请不要在旁路推流时调用此方法。
  • 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
参数
secret加密密码。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setEncryptionMode()

virtual int agora::rtc::IRtcEngine::setEncryptionMode ( const char *  encryptionMode)
pure virtual

启用内置的加密方案。

Agora Video SDK 支持内置加密方案,默认支持 AES-128-XTS。如需采用其他加密方案,可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。

注解
在调用本方法前,请先调用 setEncryptionSecret 启用内置加密功能。
参数
encryptionMode加密模式:
  • "aes-128-xts": 128 位 AES 加密,XTS 模式;
  • "aes-128-ecb":128 位 AES 加密,ECB 模式;
  • "aes-256-xts": 256 位 AES 加密,XTS 模式;
  • "": 设置为空字符串时,默认使用加密方式 "aes-128-xts"。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ registerPacketObserver()

virtual int agora::rtc::IRtcEngine::registerPacketObserver ( IPacketObserver observer)
pure virtual

注册数据包观测器。

该方法注册数据包观测器 (Packet Observer)。在 Agora SDK 发送/接收(语音、视频)网络包时,会回调 IPacketObserver 定义的接口,App 可用此接口对数据做处理,例如加解密。

注解
  • 处理后发送到网络的包大小不应超过 1200 字节,否则有可能发送失败。
  • 若需调用此方法,需确保接收端和发送端都调用此方法,否则会出现未定义行为(例如音频无声或视频黑屏)。
  • 若在直播场景下使用 CDN 推流、录制或储存,Agora 不建议调用此方法。
参数
observerIPacketObserver
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ createDataStream()

virtual int agora::rtc::IRtcEngine::createDataStream ( int *  streamId,
bool  reliable,
bool  ordered 
)
pure virtual

创建数据流。

该方法用于创建数据流。RtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒,若超过 5 秒接收方尚未收到数据流,则数据通道会向 App 报错。

注解
将 reliable 和 ordered 同时设为 true 或 false。不要一个设为 true 另一个设为 false。
参数
streamId数据流 ID。
reliable
  • true: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 onStreamMessageError 回调获得相应报错信息。
  • false: 接收方不保证收到,就算数据丢失也不会报错。
ordered
  • true: 接收方 5 秒内会按照发送方发送的顺序收到数据包;
  • false: 接收方不保证按照发送方发送的顺序收到数据包。
返回
  • 0: 创建数据流成功。
  • < 0: 创建数据流失败。

◆ sendStreamMessage()

virtual int agora::rtc::IRtcEngine::sendStreamMessage ( int  streamId,
const char *  data,
size_t  length 
)
pure virtual

发送数据流。

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。 API 须对数据通道的传送速率进行控制: 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。 成功调用该方法后,远端会触发 onStreamMessage 回调,远端用户可以在该回调中获取接收到的流消息;若调用失败,远端会触发 onStreamMessageError 回调。

注解
  • 请确保在调用该方法前,已调用 createDataStream 创建了数据流。
  • 该方法仅适用于通信场景以及直播场景下的主播用户,如果直播场景下的观众调用此方法可能会造成观众变主播。
参数
streamIdcreateDataStream 返回的数据流 ID。
data自定义数据。
length数据长度。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ addPublishStreamUrl()

virtual int agora::rtc::IRtcEngine::addPublishStreamUrl ( const char *  url,
bool  transcodingEnabled 
)
pure virtual

增加旁路推流地址。

调用该方法后,SDK会在本地触发 onRtmpStreamingStateChanged 回调,报告增加旁路推流地址的状态。

注解
  • 请确保在成功加入频道后才能调用该接口。
  • 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
  • 在直播场景中,只有角色为主播的用户才能调用该方法。
参数
urlCDN 推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。url 不支持中文字符等特殊字符。
transcodingEnabled
  • true: 转码( 转码 是指在旁路推流时对音视频流进行转码处理后再推送到其他 RTMP 服务器。多适用于频道内有多个主播,需要进行混流、合图的场景)。如果设为 true,需先调用 setLiveTranscoding 方法。
  • false: 不转码。
返回

◆ removePublishStreamUrl()

virtual int agora::rtc::IRtcEngine::removePublishStreamUrl ( const char *  url)
pure virtual

删除旁路推流地址。 调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告删除旁路推流地址的状态。

注解
  • 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
  • URL 不支持中文等特殊字符。
  • 在直播场景中,只有角色为主播的用户才能调用该方法。
参数
url待删除的旁路推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLiveTranscoding()

virtual int agora::rtc::IRtcEngine::setLiveTranscoding ( const LiveTranscoding transcoding)
pure virtual

设置直播推流转码。

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 onTranscodingUpdated 回调。

注解
  • 在直播场景中,只有角色为主播的用户才能调用该方法。
  • 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 首次调用该方法更新转码设置时,不会触发 onTranscodingUpdated 回调。
参数
transcoding详见 LiveTranscoding
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ addVideoWatermark() [1/2]

virtual int agora::rtc::IRtcEngine::addVideoWatermark ( const RtcImage watermark)
pure virtual

添加本地视频水印。

弃用:
该方法已废弃,请使用 addVideoWatermark2 作为替代。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的观众,旁路推流观众,甚至录制设备都能看到或采集到该水印图片。 如果你仅仅希望在旁路直播推流中添加水印,请参考 setLiveTranscoding 中描述的用法。

注解
  • 在本地直播和旁路推流中,URL 的定义不同。本地直播中,URL 指本地直播视频上图片的本地绝对/相对路径;旁路推流中,URL 指旁路推流视频上图片的地址。
  • 待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行裁剪,以与设置相符。
  • 声网当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
参数
watermark待添加在本地直播推流中的水印图片: RtcImage
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ addVideoWatermark() [2/2]

virtual int agora::rtc::IRtcEngine::addVideoWatermark ( const char *  watermarkUrl,
const WatermarkOptions options 
)
pure virtual

添加本地视频水印。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的观众、旁路直播观众和录制设备都能看到或采集到该水印图片。Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。

水印坐标和 setVideoEncoderConfiguration 方法中的设置有依赖关系:

  • 如果视频编码方向/ ORIENTATION_MODE 固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
  • 如果视频编码方向/ ORIENTATION_MODE 固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
  • 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。
注解
  • 你需要在调用 enableVideo 方法之后再调用本方法。
  • 如果你只是在旁路直播(推流到CDN)中添加水印,你可以使用本方法或 setLiveTranscoding 方法设置水印。
  • 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
  • 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
  • 如果你已经使用 startPreview 方法开启本地视频预览,那么本方法的 visibleInPreview 可设置水印在预览时是否可见。
  • 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
watermarkUrl待添加的水印图片的本地路径。本方法支持从本地绝对/相对路径添加水印图片。
options待添加的水印图片的设置选项,详见 WatermarkOptions
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ clearVideoWatermarks()

virtual int agora::rtc::IRtcEngine::clearVideoWatermarks ( )
pure virtual

删除已添加的视频水印。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setBeautyEffectOptions()

virtual int agora::rtc::IRtcEngine::setBeautyEffectOptions ( bool  enabled,
BeautyOptions  options 
)
pure virtual
自从
v3.0.0

设置美颜效果选项。

开启本地美颜功能,并设置美颜效果选项。

注解
  • 请在调用 enableVideo 方法后,调用该方法。
  • 该方法目前不适用于 macOS 平台。
参数
enabled是否开启美颜功能:
  • true: 开启。
  • false: (默认)关闭。
options美颜选项。详见: BeautyOptions
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ addInjectStreamUrl()

virtual int agora::rtc::IRtcEngine::addInjectStreamUrl ( const char *  url,
const InjectStreamConfig config 
)
pure virtual

输入在线媒体流。

注解
  • 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 该方法适用于 Native SDK v2.4.1 及之后的版本。
  • 在直播场景中,只有角色为主播的用户才能调用该方法。
  • 频道内同一时间只允许输入一个在线媒体流。

该方法将正在播放的音视频作为音视频源导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。调用该方法后,SDK 会在本地触发 onStreamInjectedStatus 回调,报告输入在线媒体流的状态;成功输入媒体流后,该音视频流会出现在频道中,频道内所有用户都会收到 onUserJoined 回调,其中 uid 为 666。该音视频流会出现在频道中。

参数
url添加到直播中的视频流 URL 地址。支持 RTMP、HLS、HTTP-FLV 协议传输。
  • 支持的音频编码格式:AAC;
  • 支持的视频编码格式:H.264(AVC)。
config所添加的视频流属性定义,详见: InjectStreamConfig
返回

◆ startChannelMediaRelay()

virtual int agora::rtc::IRtcEngine::startChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtual

开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。

成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChangedonChannelMediaRelayEvent 回调,并在回调中报告当前的跨频道媒体流转发状态和事件。

注解
  • 请在成功加入频道后调用该方法。
  • 在直播场景中,只有角色为主播的用户才能调用该方法。
  • 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
  • 跨频道媒体流转发功能需要提交工单联系技术支持开通。
  • 该功能不支持 String 型 UID。
参数
configuration跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration
返回
  • 0:方法调用成功。
  • < 0:方法调用失败

◆ updateChannelMediaRelay()

virtual int agora::rtc::IRtcEngine::updateChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtual

更新媒体流转发的频道。成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道, 或退出当前的转发频道,可以调用该方法。

成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调, 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。

注解
请在 startChannelMediaRelay 方法后调用该方法,更新媒体流转发的频道。
参数
configuration跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration
返回
  • 0:方法调用成功。
  • < 0:方法调用失败

◆ stopChannelMediaRelay()

virtual int agora::rtc::IRtcEngine::stopChannelMediaRelay ( )
pure virtual

停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。

成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0),则表示已停止转发媒体流。

注解
如果该方法调用不成功,SDK 会触发 onChannelMediaRelayStateChanged 回调,并报告状态码 RELAY_ERROR_SERVER_NO_RESPONSE (2) 或 RELAY_ERROR_SERVER_CONNECTION_LOST (8)。你可以调用 leaveChannel 方法离开频道,跨频道媒体流转发会自动停止。
返回
  • 0:方法调用成功。
  • < 0:方法调用失败

◆ removeInjectStreamUrl()

virtual int agora::rtc::IRtcEngine::removeInjectStreamUrl ( const char *  url)
pure virtual

删除导入的外部媒体流。

注解
成功删除外部视频源 URL 地址后会触发 onUserOffline 回调,uid 为 666。
参数
url已导入、待删除的外部视频源 URL 地址。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ registerEventHandler()

virtual bool agora::rtc::IRtcEngine::registerEventHandler ( IRtcEngineEventHandler eventHandler)
pure virtual

◆ unregisterEventHandler()

virtual bool agora::rtc::IRtcEngine::unregisterEventHandler ( IRtcEngineEventHandler eventHandler)
pure virtual

◆ getConnectionState()

virtual CONNECTION_STATE_TYPE agora::rtc::IRtcEngine::getConnectionState ( )
pure virtual

获取当前网络连接状态。

返回
CONNECTION_STATE_TYPE

◆ registerMediaMetadataObserver()

virtual int agora::rtc::IRtcEngine::registerMediaMetadataObserver ( IMetadataObserver observer,
IMetadataObserver::METADATA_TYPE  type 
)
pure virtual

注册媒体 metadata 观测器用于接收或发送 metadata。

注解
  • 请在 joinChannel 前调用该方法
  • 该方法仅使用于直播场景
参数
observer指向已注册的 metadata 观测器的指针。详见: IMetadataObserver
type用户希望在观测器中使用的 METADATA 类型 。目前仅支持 VIDEO_METADATA 。详见: METADATA_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败