文档中心
互动直播 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

C++ API Reference for All Platforms

概览 IRtcEngine IRtcEngineEventHandler IChannel IChannelEventHandler IAudioDeviceManager IVideoDeviceManager

#include <IAgoraMediaEngine.h>

Public 成员函数

virtual ~IMediaEngine ()
 
virtual void release ()=0
 
virtual int registerAudioFrameObserver (IAudioFrameObserver *observer)=0
 
virtual int registerVideoFrameObserver (IVideoFrameObserver *observer)=0
 
virtual int registerVideoRenderFactory (IExternalVideoRenderFactory *factory)=0
 
virtual int pushAudioFrame (MEDIA_SOURCE_TYPE type, IAudioFrameObserver::AudioFrame *frame, bool wrap)=0
 
virtual int pushAudioFrame (IAudioFrameObserver::AudioFrame *frame)=0
 
virtual int pushAudioFrame (int32_t sourcePos, IAudioFrameObserver::AudioFrame *frame)=0
 
virtual int setExternalAudioSourceVolume (int32_t sourcePos, int32_t volume)=0
 
virtual int pullAudioFrame (IAudioFrameObserver::AudioFrame *frame)=0
 
virtual int setExternalVideoSource (bool enable, bool useTexture)=0
 
virtual int pushVideoFrame (ExternalVideoFrame *frame)=0
 
virtual int registerVideoEncodedFrameObserver (IVideoEncodedFrameObserver *observer)=0
 

构造及析构函数说明

◆ ~IMediaEngine()

virtual agora::media::IMediaEngine::~IMediaEngine ( )
inlinevirtual

成员函数说明

◆ release()

virtual void agora::media::IMediaEngine::release ( )
pure virtual

◆ registerAudioFrameObserver()

virtual int agora::media::IMediaEngine::registerAudioFrameObserver ( IAudioFrameObserver *  observer)
pure virtual

注册语音观测器对象

该方法用于注册语音观测器对象，即注册回调。当需要引擎给出 onRecordAudioFrame 或 onPlaybackAudioFrame 回调时，需要使用该方法注册回调。

注解
该方法需要在加入频道前调用。
参数
observer接口对象实例。详见 IAudioFrameObserver。如果传入 NULL，则表示取消注册， 我们建议在收到 onLeaveChannel 后调用，来释放语音观测器对象。
返回
  • 0：方法调用成功
  • < 0：方法调用失败

◆ registerVideoFrameObserver()

virtual int agora::media::IMediaEngine::registerVideoFrameObserver ( IVideoFrameObserver *  observer)
pure virtual

注册视频观测器对象

你需要在该方法中实现一个 IVideoFrameObserver 类，并根据场景需要，注册该类的回调。 成功注册视频观测器后，SDK 会在捕捉到每个视频帧时，触发你所注册的上述回调。

注解
  • 在处理回调时，你需要考虑视频帧中 width 和 height 参数的变化，因为观测得到的视频帧可能会随以下情况变化：
    • 当网络状况差时，分辨率会阶梯式下降。
    • 当用户自行调整分辨率时，回调中报告的分辨率也会变化。
  • 该方法需要在加入频道前调用。
  • 使用 3.0.1 或之后版本的 SDK 时，请注意如下：
    • SDK 不再保证 IVideoFrameObserver 中的回调函数在同一个线程中报告。SDK 只会保证这些回调的顺序性。
    • 如果你使用 OpenGL 对视频原始数据进行美颜处理，为适应多线程场景，你需要在 IVideoFrameObserver 中的回调函数中主动切换 OpenGL 的上下文，否则美颜可能失效。
参数
observer接口对象实例。如果传入 NULL，则取消注册。详见 IVideoFrameObserver
返回
  • 0：方法调用成功
  • < 0：方法调用失败

◆ registerVideoRenderFactory()

virtual int agora::media::IMediaEngine::registerVideoRenderFactory ( IExternalVideoRenderFactory *  factory)
pure virtual
弃用:

◆ pushAudioFrame() [1/3]

virtual int agora::media::IMediaEngine::pushAudioFrame ( MEDIA_SOURCE_TYPE  type,
IAudioFrameObserver::AudioFrame *  frame,
bool  wrap 
)
pure virtual

推送外部音频帧

弃用:
该方法已废弃，请改用 pushAudioFrame [3/3]。
参数
type音频采集设备类型。详见： MEDIA_SOURCE_TYPE 。
frame音频帧指针。详见： AudioFrame
wrap设置是否占位使用。声网建议用户使用默认值即可。
  • true: 占位使用；
  • false:（默认）不占位使用。
返回
  • 0：方法调用成功
  • < 0：方法调用失败

◆ pushAudioFrame() [2/3]

virtual int agora::media::IMediaEngine::pushAudioFrame ( IAudioFrameObserver::AudioFrame *  frame)
pure virtual

推送外部音频帧

弃用:
该方法自 v3.5.1 起废弃，请改用 pushAudioFrame [3/3]。
参数
frame音频帧指针。详见： AudioFrame
返回
  • 0：方法调用成功
  • < 0：方法调用失败

◆ pushAudioFrame() [3/3]

virtual int agora::media::IMediaEngine::pushAudioFrame ( int32_t  sourcePos,
IAudioFrameObserver::AudioFrame *  frame 
)
pure virtual

推送外部音频帧到指定位置。

自从
v3.5.1

根据实际需求，你可以将外部音频帧推送到音频采集后、编码前或本地播放前的位置。你可以多次调用该方法，将一个音频帧推送到多个位置或者将多个音频 帧推送到不同位置。例如，在 KTV 场景中，你可以将歌声推送到音频采集后的位置，让歌声经过 SDK 音频模块的处理，从而获取优质的音频体验；将伴奏 推送到音频编码前的位置，让伴奏不受 SDK 音频模块的影响。

注解
该方法需要在加入频道后调用。
参数
sourcePos外部音频帧的推送位置。详见 AUDIO_EXTERNAL_SOURCE_POSITION
frame外部音频帧。详见 AudioFrame 。音频帧长度范围为 [10,60]，单位为 ms。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败
    • -2(ERR_INVALID_ARGUMENT): 无效参数
    • -12(ERR_TOO_OFTEN): 调用频率太高，导致内部缓冲区溢出。建议在 30～50 ms 后重新调用该方法

◆ setExternalAudioSourceVolume()

virtual int agora::media::IMediaEngine::setExternalAudioSourceVolume ( int32_t  sourcePos,
int32_t  volume 
)
pure virtual

设置指定位置的外部音频帧音量。

自从
v3.5.1

你可以多次调用该方法，设置不同位置的外部音频帧音量。音量设置对被推送到指定位置的所有外部音频帧都有效。

注解
该方法需要在加入频道后调用。
参数
sourcePos外部音频帧的推送位置。详见 AUDIO_EXTERNAL_SOURCE_POSITION
volume外部音频帧的音量。取值范围为 [0,100]。默认值为 100，表示原始音量。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败
    • -2(ERR_INVALID_ARGUMENT): 无效参数

◆ pullAudioFrame()

virtual int agora::media::IMediaEngine::pullAudioFrame ( IAudioFrameObserver::AudioFrame *  frame)
pure virtual

拉取远端音频数据。

使用该方法前，你需要调用 setExternalAudioSink(enabled: true) 方法通知 App 开启并设置外部渲染。

调用该方法后，App 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

注解
  • 该方法需要在加入频道后调用。
  • 使用早于 3.5.0 版的 SDK 时，设置 Pull 方式的音频自渲染后，你将无法收到 onPlaybackAudioFrame 回调。
  • 该方法和 onPlaybackAudioFrame 回调相比，区别在于：
    • onPlaybackAudioFrame：SDK 通过该回调将音频数据传输给 app。如果 app 处理延时，可能会导致音频播放抖动。
    • pullAudioFrame：App 主动拉取音频数据。通过设置音频数据， SDK 可以调整缓存，帮助 App 处理延时，从而有效避免音频播放抖动。
参数
frame指向 AudioFrame 的指针。
返回
  • 0：方法调用成功。
  • < 0：方法调用失败。

◆ setExternalVideoSource()

virtual int agora::media::IMediaEngine::setExternalVideoSource ( bool  enable,
bool  useTexture 
)
pure virtual

配置外部视频源

注解
该方法需要在加入频道前调用。
参数
enable是否使用外部视频源：
  • true：使用外部视频源
  • false：（默认）不使用外部视频源
useTexture是否使用 Texture 作为输入：
  • true：使用 texture 作为输入
  • false：（默认）不使用 texture 作为输入
返回
  • 0：方法调用成功
  • < 0：方法调用失败

◆ pushVideoFrame()

virtual int agora::media::IMediaEngine::pushVideoFrame ( ExternalVideoFrame *  frame)
pure virtual

使用 ExternalVideoFrame 将视频帧数据传递给 SDK

注解
通信场景下，不支持 Texture 格式的视频帧，只支持非 Texture 格式的视频帧
参数
frame待传输的视频帧。详见 ExternalVideoFrame
返回
  • 0：方法调用成功
  • < 0：方法调用失败

◆ registerVideoEncodedFrameObserver()

virtual int agora::media::IMediaEngine::registerVideoEncodedFrameObserver ( IVideoEncodedFrameObserver *  observer)
pure virtual

注册本地视频编码数据观测器。

自从
v3.4.5

成功注册本地视频编码数据观测器后，SDK 会在捕捉到每个视频帧时， 触发你在 IVideoEncodedFrameObserver 类中实现的回调。

注解
  • 该方法需要在加入频道前调用。
  • 通过观测器获取的视频宽高可能会因网络情况变差和用户自行调整分辨率而变化。
参数
observer本地视频编码数据观测器。详见 IVideoEncodedFrameObserver。 传空表示取消注册本地视频编码数据观测器。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败