agora::rtc::ILocalUser类 参考

abstract

ILocalUser 类。 定义了本地用户的行为和状态。

每个 RTC 连接都有自己的用户。你可以通过 IRtcConnection::getLocalUser 获取本地 user。

每个用户有两种角色: 主播 (能发送和接收音视频流) 和 观众 (只能接收音视频流)。

构造及析构函数说明

~ILocalUser()

virtual agora::rtc::ILocalUser::~ILocalUser ( )

成员函数说明

getUserRole()

virtual CLIENT_ROLE_TYPE agora::rtc::ILocalUser::getUserRole ( )

获取用户角色。

返回值

用户角色： CLIENT_ROLE_TYPE 。

publishAudio()

virtual int agora::rtc::ILocalUser::publishAudio ( agora_refptr< ILocalAudioTrack >  audioTrack, aosl_ref_t  ares = AOSL_REF_INVALID  )

将本地音频轨道发送到频道。

默认情况下，所有发布的音频轨道都会进行混音。

参数

参数名	描述
audioTrack	需要发布的本地音频轨道。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • -5(ERR_REFUSED)：如果本地用户的角色不是主播，会返回此错误。

publishVideo()

virtual int agora::rtc::ILocalUser::publishVideo ( agora_refptr< ILocalVideoTrack >  videoTrack, aosl_ref_t  ares = AOSL_REF_INVALID  )

将本地视频轨道发送到频道。

参数

参数名	描述
videoTrack	需要发布的本地视频轨道。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

registerAudioFrameObserver()

virtual int agora::rtc::ILocalUser::registerAudioFrameObserver ( agora::media::IAudioFrameObserverBase *  observer, aosl_ref_t  ares = AOSL_REF_INVALID  )

注册音频帧 observer。

你必须实现 IAudioFrameObserverBase 类并根据需求注册以下回调：

• onRecordAudioFrame
• onPlaybackAudioFrame
• onPlaybackAudioFrameBeforeMixing
• onMixedAudioFrame

参数

参数名	描述
observer	音频帧 observer的指针： IAudioFrameObserverBase 。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

registerLocalUserObserver()

virtual int agora::rtc::ILocalUser::registerLocalUserObserver ( ILocalUserObserver *  observer, void(*)(ILocalUserObserver *)  safeDeleter = NULL, aosl_ref_t  ares = AOSL_REF_INVALID  )

注册本地用户 observer。

参数

参数名	描述
observer	本地用户 observer 对象： ILocalUserObserver 。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

registerVideoEncodedFrameObserver()

virtual int agora::rtc::ILocalUser::registerVideoEncodedFrameObserver ( agora::media::IVideoEncodedFrameObserver *  observer, aosl_ref_t  ares = AOSL_REF_INVALID  )

为编码后的视频图像注册视频帧接收 observer。

参数

参数名	描述
observer	视频帧接收 observer，详见 IVideoEncodedFrameObserver 。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

registerVideoFrameObserver()

virtual int agora::rtc::ILocalUser::registerVideoFrameObserver ( IVideoFrameObserver2 *  observer, aosl_ref_t  ares = AOSL_REF_INVALID  )

注册 IVideoFrameObserver2 对象。

参数

参数名	描述
observer	IVideoFrameObserver2 对象的指针。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

sendIntraRequest()

virtual int agora::rtc::ILocalUser::sendIntraRequest ( user_id_t  userId, aosl_ref_t  ares = AOSL_REF_INVALID  )

向指定主播用户发送关键帧请求。

你成功发送请求后，主播会收到 onIntraRequestReceived 回调。

参数

参数名	描述
userId	主播的用户 ID。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

setAudioEncoderConfiguration()

virtual int agora::rtc::ILocalUser::setAudioEncoderConfiguration ( const rtc::AudioEncoderConfiguration &  config, aosl_ref_t  ares = AOSL_REF_INVALID  )

设置音频编码。

SDK 会将配置应用于全部发送的音频轨道。

参数

参数名	描述
config	音频编码配置。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

setMixedAudioFrameParameters()

virtual int agora::rtc::ILocalUser::setMixedAudioFrameParameters ( size_t  numberOfChannels, uint32_t  sampleRateHz, int  samplesPerCall = 0, aosl_ref_t  ares = AOSL_REF_INVALID  )

设置 onMixedAudioFrame 报告的音频数据格式。

注解

SDK 会根据该方法设置的采样间隔（秒）定期触发 onMixedAudioFrame 回调。 采样间隔 = samplesPerCall/(sampleRate x channel)。请确保你的取值能满足采样间隔大于或等于 0.01 秒。

参数

参数名	描述
numberOfChannels	音频数据声道数，可设置为 1（单声道） 或 2（双声道）。
sampleRateHz	音频数据采样率 (Hz)，可设置为 8000、 16000、32000、 44100 或 48000。
samplesPerCall	指定 onMixedAudioFrame 中返回数据的采样点数，如 RTMP/RTMPS 推流应用中通常为 1024。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

setPlaybackAudioFrameBeforeMixingParameters()

virtual int agora::rtc::ILocalUser::setPlaybackAudioFrameBeforeMixingParameters ( size_t  numberOfChannels, uint32_t  sampleRateHz, aosl_ref_t  ares = AOSL_REF_INVALID  )

设置 onPlaybackAudioFrameBeforeMixing 报告的音频数据格式。

参数

参数名	描述
numberOfChannels	音频数据声道数，可设置为 1（单声道） 或 2（双声道）。
sampleRateHz	音频数据采样率 (Hz)，可设置为 8000、 16000、32000、 44100 或 48000。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

setPlaybackAudioFrameParameters()

virtual int agora::rtc::ILocalUser::setPlaybackAudioFrameParameters ( size_t  numberOfChannels, uint32_t  sampleRateHz, RAW_AUDIO_FRAME_OP_MODE_TYPE  mode = RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, int  samplesPerCall = 0, aosl_ref_t  ares = AOSL_REF_INVALID  )

设置播放的音频格式。

该方法设置 onPlaybackAudioFrame 回调数据的格式。

参数

参数名	描述
numberOfChannels	音频数据声道数，可设置为 1（单声道） 或 2（双声道）。
sampleRateHz	onPlaybackAudioFrame 中返回数据的采样率，可设置为 8000、 16000、 32000、44100 或 48000。
mode	音频帧的使用模式，详见: RAW_AUDIO_FRAME_OP_MODE_TYPE 。
samplesPerCall	onPlaybackAudioFrame 中返回数据的采样点数，如直推 CDN 应用中通常为 1024。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

setRecordingAudioFrameParameters()

virtual int agora::rtc::ILocalUser::setRecordingAudioFrameParameters ( size_t  numberOfChannels, uint32_t  sampleRateHz, RAW_AUDIO_FRAME_OP_MODE_TYPE  mode = RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, int  samplesPerCall = 0, aosl_ref_t  ares = AOSL_REF_INVALID  )

设置采集的原始音频数据格式。

该方法设置 agora::media::IAudioFrameObserverBase::onRecordAudioFrame 回调的采集音频格式。

参数

参数名	描述
numberOfChannels	音频数据声道数，可设置为 1（单声道） 或 2（双声道）。
sampleRateHz	onRecordAudioFrame 中返回数据的采样率，可设置为 8000、 16000、 32000、44100 或 48000。
mode	音频帧的使用模式，详见 RAW_AUDIO_FRAME_OP_MODE_TYPE 。
samplesPerCall	onRecordAudioFrame 中返回数据的采样点数。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

setUserRole()

virtual void agora::rtc::ILocalUser::setUserRole ( rtc::CLIENT_ROLE_TYPE  role, aosl_ref_t  ares = AOSL_REF_INVALID  )

设置用户角色。

你可以在用户连接频道前或连接频道后调用该方法。 onChangeRoleSuccess 回调和 onChangeRoleFailure 回调会报告该方法的结果。

注解

如果 connect 中的 token 与 role 参数设置的角色不同，连接会失败，SDK 会返回 onConnectionFailure 回调。

参数

参数名	描述
role	用户角色 CLIENT_ROLE_TYPE 。
ares	用于 SDK 的生命周期保护，填写默认值即可。

subscribeAllAudio()

virtual int agora::rtc::ILocalUser::subscribeAllAudio ( aosl_ref_t  ares = AOSL_REF_INVALID )

订阅频道中全部远端用户发送的音频流。

该方法会自动订阅频道中后续加入的用户发送的音频流。

参数

参数名	描述
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

subscribeAllVideo()

virtual int agora::rtc::ILocalUser::subscribeAllVideo ( const VideoSubscriptionOptions &  subscriptionOptions, aosl_ref_t  ares = AOSL_REF_INVALID  )

订阅频道中全部远端用户发送的视频流。

该方法会自动订阅频道中后续加入的用户发送的视频流。

参数

参数名	描述
subscriptionOptions	订阅选项： VideoSubscriptionOptions 。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

subscribeAudio()

virtual int agora::rtc::ILocalUser::subscribeAudio ( user_id_t  userId, aosl_ref_t  ares = AOSL_REF_INVALID  )

订阅频道中特定的远端用户发送的音频流。

参数

参数名	描述
userId	远端用户的 ID。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INVALID_ARGUMENT)：如果用户不存在或 userId 无效时会返回该错误。

subscribeVideo()

virtual int agora::rtc::ILocalUser::subscribeVideo ( user_id_t  userId, const VideoSubscriptionOptions &  subscriptionOptions, aosl_ref_t  ares = AOSL_REF_INVALID  )

订阅频道中指定远端用户发送的视频流。

参数

参数名	描述
userId	用户 ID。
subscriptionOptions	订阅选项： VideoSubscriptionOptions 。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INVALID_ARGUMENT)：如果用户不存在或 userId 无效时会返回该错误。

unpublishAudio()

virtual int agora::rtc::ILocalUser::unpublishAudio ( agora_refptr< ILocalAudioTrack >  audioTrack, aosl_ref_t  ares = AOSL_REF_INVALID  )

停止将本地音频轨道发送到频道。

参数

参数名	描述
audioTrack	需要停止发布的本地音频轨道。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

unpublishVideo()

virtual int agora::rtc::ILocalUser::unpublishVideo ( agora_refptr< ILocalVideoTrack >  videoTrack, aosl_ref_t  ares = AOSL_REF_INVALID  )

停止将本地视频轨道发送到频道。

参数

参数名	描述
videoTrack	需要停止发布的本地视频轨道。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

unregisterAudioFrameObserver()

virtual int agora::rtc::ILocalUser::unregisterAudioFrameObserver ( agora::media::IAudioFrameObserverBase *  observer )

销毁音频帧 observer。

参数

参数名	描述
observer	音频帧 observer的指针： IAudioFrameObserverBase 。

返回值

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

unregisterLocalUserObserver()

virtual int agora::rtc::ILocalUser::unregisterLocalUserObserver ( ILocalUserObserver *  observer )

销毁本地用户 observer。

参数

参数名	描述
observer	本地用户 observer 对象： ILocalUserObserver 。

返回值

• 0: Success.
• < 0: Failure.

unregisterVideoEncodedFrameObserver()

virtual int agora::rtc::ILocalUser::unregisterVideoEncodedFrameObserver ( agora::media::IVideoEncodedFrameObserver *  observer )

销毁视频帧接收 observer。

参数

参数名	描述
observer	视频帧接收 observer，详见 IVideoEncodedFrameObserver 。

返回值

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

unregisterVideoFrameObserver()

virtual int agora::rtc::ILocalUser::unregisterVideoFrameObserver ( IVideoFrameObserver2 *  observer )

销毁 IVideoFrameObserver2 对象。

参数

参数名	描述
observer	IVideoFrameObserver2 对象的指针。

返回值

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

unsubscribeAllAudio()

virtual int agora::rtc::ILocalUser::unsubscribeAllAudio ( aosl_ref_t  ares = AOSL_REF_INVALID )

停止订阅频道中全部远端用户发送的音频流。

该方法会自动取消订阅频道中后续加入的用户发送的音频流。你必须调用 subscribeAudio 或 subscribeAllAudio 才能恢复订阅音频。

参数

参数名	描述
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

unsubscribeAllVideo()

virtual int agora::rtc::ILocalUser::unsubscribeAllVideo ( aosl_ref_t  ares = AOSL_REF_INVALID )

停止订阅频道中全部远端用户发送的视频流。

该方法会自动取消订阅频道中后续加入的用户发送的音频流。你必须调用 subscribeVideo 或 subscribeAllVideo 才能恢复订阅。

参数

参数名	描述
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

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

unsubscribeAudio()

virtual int agora::rtc::ILocalUser::unsubscribeAudio ( user_id_t  userId, aosl_ref_t  ares = AOSL_REF_INVALID  )

停止订阅频道中特定的远端用户发送的音频流。

参数

参数名	描述
userId	远端用户的 ID。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INVALID_ARGUMENT)：如果用户不存在或 userId 无效时会返回该错误。

unsubscribeVideo()

virtual int agora::rtc::ILocalUser::unsubscribeVideo ( user_id_t  userId, aosl_ref_t  ares = AOSL_REF_INVALID  )

停止订阅频道中指定远端用户发送的视频流。

参数

参数名	描述
userId	用户 ID。
ares	用于 SDK 的生命周期保护，填写默认值即可。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。
  • -2(ERR_INVALID_ARGUMENT)：如果用户不存在或 userId 无效时会返回该错误。