IMediaEngine
IMediaEngine 类。
pullAudioFrame
拉取远端音频数据。
virtual int pullAudioFrame(IAudioFrameObserver::AudioFrame* frame) = 0;
使用该方法前,你需要调用 setExternalAudioSink 通知 app 开启并设置外部渲染。
调用该方法后,app 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
- 该方法仅支持拉取自采集的数据。如果你需要拉取 SDK 采集的数据,请不要调用该方法。
- 该方法需要在加入频道后调用。
- 开启外部音频渲染后,app 将无法从 onPlaybackAudioFrame 回调中获得数据。
- 该方法和 onPlaybackAudioFrame 回调相比,区别在于:
- SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动。
- 调用该方法后 app 会主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。
参数
- frame
- 指向 AudioFrame 的指针。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushAudioFrame
推送外部音频帧。
virtual int pushAudioFrame(MEDIA_SOURCE_TYPE type, IAudioFrameObserver::AudioFrame* frame, bool wrap = false, int sourceId = 0) = 0;
参数
- type
- 音频采集设备类型。详见 MEDIA_SOURCE_TYPE。
- frame
- 外部音频帧。详见 AudioFrame。
- wrap
- 设置是否占位使用。Agora 建议用户使用默认值。
true
: 占位使用;false
:(默认)不占位使用。
- sourceId
- 外部音频源的 ID。如果你要发布自定义的外部音频源,则将该参数设置为你想要发布的自定义音频轨道 ID。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushVideoFrame
推送外部原始视频帧到 SDK。
virtual int pushVideoFrame(base::ExternalVideoFrame* frame, unsigned int videoTrackId = 0) = 0;
调用 createCustomVideoTrack 方法获得视频轨道 ID,在每个频道的 ChannelMediaOptions 中,将 customVideoTrackId 参数设置为你想要发布的视频轨道 ID,并将 publishCustomVideoTrack 设置为 true
后,你可以调用本方法将未编码的外部视频帧推送到 SDK。
参数
- frame
-
待推送的视频帧。详见 ExternalVideoFrame。
- videoTrackId
- 调用 createCustomVideoTrack 方法返回的视频轨道 ID。默认值为 0。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
registerAudioFrameObserver
注册音频观测器对象。
virtual int registerAudioFrameObserver(IAudioFrameObserver* observer) = 0;
该方法用于注册音频观测器对象,即注册回调。当需要 SDK 给出 onMixedAudioFrame、onRecordAudioFrame、onPlaybackAudioFrame 或 onEarMonitoringAudioFrame 等回调时,需要使用该方法注册回调。
参数
- observer
-
接口对象实例。详见 IAudioFrameObserver。如果传入 NULL,则表示取消注册。Agora 建议在收到 onLeaveChannel 后调用,来释放音频观测器对象。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
registerVideoEncodedFrameObserver
为编码后的视频图像注册视频帧接收观测器。
virtual int registerVideoEncodedFrameObserver(IVideoEncodedFrameObserver* observer) = 0;
- 请在加入频道后调用该方法。
- 如果你调用该方法注册了 IVideoEncodedFrameObserver 对象,则不能再注册 IVideoFrameObserver 对象。
参数
- observer
- 视频帧接收观测器,详见 IVideoEncodedFrameObserver。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
registerVideoFrameObserver
注册视频观测器对象。
virtual int registerVideoFrameObserver(IVideoFrameObserver* observer) = 0;
你需要在该方法中实现一个 IVideoFrameObserver 类,并根据场景需要,注册该类的回调。 成功注册视频观测器后,SDK 会在捕捉到每个视频帧时,触发你所注册的上述回调。
- 在处理回调时,你需要考虑视频帧中 width 和 height 参数的变化,因为观测得到的视频帧可能会随以下情况变化:
- 当网络状况差时,分辨率会阶梯式下降。
- 当用户自行调整分辨率时,回调中报告的分辨率也会变化。
- 该方法需要在加入频道前调用。
参数
- observer
- 接口对象实例。详见 IVideoFrameObserver。如果传入 NULL,则取消注册。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setExternalAudioSink
设置外部音频渲染。
virtual int setExternalAudioSink(bool enabled, int sampleRate, int channels) = 0;
该方法适用于需要自行渲染音频的场景。开启外部音频渲染后,你可以调用 pullAudioFrame 拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。
参数
- enabled
-
设置是否开启外部音频渲染:
true
:开启外部音频渲染。false
:(默认)关闭外部音频渲染。
- sampleRate
-
外部音频渲染的采样率 (Hz),可设置为 16000,32000,44100 或 48000。
- channels
- 外部音频渲染的声道数,可设置为 1 或 2:
- 1: 单声道
- 2: 双声道
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExternalAudioSource
设置外部音频采集参数。
virtual int setExternalAudioSource(bool enabled,
int sampleRate,
int channels,
int sourceNumber,
bool localPlayback = false,
bool publish = true) = 0;
参数
- enabled
-
是否开启使用外部音频源的功能:
true
:开启外部音频源。false
:(默认)关闭外部音频源。
- sampleRate
- 外部音频源的采样率 (Hz),可设置为
8000
,16000
,32000
,44100
或48000
。 - channels
- 外部音频源的声道数,可设置为
1
(单声道)或2
(双声道)。 - sourceNumber
- 外部音频源的数量,取值为正整数。SDK 会根据该参数值创建对应数量的自采集音频轨道,并从 0 开始为音频轨道命名。你可以在 ChannelMediaOptions 中,设置 publishCustomAudioSourceId 为你想要发布的音频轨道 ID。
- localPlayback
-
是否在本地播放外部音频源:
true
:在本地播放。false
:(默认)不在本地播放。
- publish
-
是否将音频发布到远端:
true
:(默认)发布到远端。false
:不发布到远端。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
setExternalVideoSource
设置外部视频源。
virtual int setExternalVideoSource(
bool enabled, bool useTexture, EXTERNAL_VIDEO_SOURCE_TYPE sourceType = VIDEO_FRAME,
rtc::SenderOptions encodedVideoOption = rtc::SenderOptions()) = 0;
参数
- enabled
- 是否启用外部视频源:
true
: 启用外部视频源。SDK 准备接收外部视频帧。false
:(默认)不启用外部视频源。
- useTexture
- 是否使用 texture 格式的外部视频帧:
true
: 使用 texture 格式的外部视频帧。false
: 不使用 texture 格式的外部视频帧。
- sourceType
- 是否对外部视频帧编码,详见 EXTERNAL_VIDEO_SOURCE_TYPE。
- encodedVideoOption
- 视频编码选项。如果 sourceType 为 ENCODED_VIDEO_FRAME,则需要设置该参数。你可以联系技术支持了解如何设置该参数。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。