QNAudioInterface
接口介绍
QNAudioInterface
为 SDK 提供的音频模块相关的接口,凡是涉及音频范畴的功能接口均定义在此接口内。
其中回调接口 QNAudioListener
是 QNAudioInterface
内嵌类。
控制接口 QNAudioInterface
QNAudioInterface
的获取由 QNRoomInterface::ObtainAudioInterface
方法获取,其生命周期在开发者调用 QNRoomInterface::DestroyRoomInterface
之前均有效,开发者自己无需主动释放。
// 用于获取指定类型的音频设备数量,adt_record or adt_playout
// @param device_type_ 设备类型,录制 or 播放
// @return 指定类型的设备数量
// 返回非 0 时,可通过 GetAudioDeviceInfo 获取指定 index 的设备信息
virtual int GetAudioDeviceCount(AudioDeviceInfo::AudioDeviceType device_type_) = 0;
// 获取指定 index 设备信息
// @param device_type_ 设备类型
// @param index_ 设备 index
// @param audio_info_ 输出参数,用于返回指定的音频设备信息
// @return 0:成功
virtual int GetAudioDeviceInfo(
AudioDeviceInfo::AudioDeviceType device_type_,
unsigned int index_,
__out AudioDeviceInfo& audio_info_
) = 0;
// 设置音频事件通知回调接口
// @param listener_ptr_ QNAudioListener 派生类实例指针
virtual void SetAudioListener(QNAudioInterface::QNAudioListener* listener_ptr_) = 0;
// 获取 SetAudioListener 配置的 QNAudioListener 派生类实例指针
virtual QNAudioInterface::QNAudioListener* GetAudioListener() = 0;
// 设置连麦使用的音频录制设备,不调用则使用系统默认录制设备
// 连麦过程中设置无效,需在发布音频 Track 前调用
// @param recording_device_setting_ AudioDeviceSetting 结构体
// @return 成功返回 0,其它请参考错误码列表
virtual int SetRecordingDevice(AudioDeviceSetting recording_device_setting_) = 0;
// 设置连麦使用的音频播放设备,不调用则使用系统默认播放设备
// 连麦过程中设置无效,需在订阅任何音频 Track 前调用
// @param playout_device_setting_ AudioDeviceSetting 结构体
// @return 成功返回 0,其它请参考错误码列表
virtual int SetPlayoutDevice(AudioDeviceSetting playout_device_setting_) = 0;
// 获取指定设备类型的系统音量,adt_record or adt_playout
virtual int GetAudioVolume(AudioDeviceInfo::AudioDeviceType device_type_) = 0;
// 设置指定设备类型的系统音量,adt_record or adt_playout
// @param device_type_ adt_record or adt_playout
// @param volume_ 0 ~ 100
// @return 成功返回 0,否则返回 SDK 错误码
virtual int SetAudioVolume(AudioDeviceInfo::AudioDeviceType device_type_, int volume_) = 0;
// 设置指定用户的音量(不改变系统设备的音量)
// @param track_id_ User Id; 由于 SDK 每个用户只能发布一路音频,所以音量控制由 User Id 指定
// @param volume_scale_ratio_ 音量缩放倍数,建议值为 0.0f ~ 2.0f
// @return 成功返回 0,其它请参考错误码列表
virtual int SetAudioVolume(const std::string& user_id_, float volume_scale_ratio_) = 0;
// 静音或取消静音指定类型的设备
// @return 成功返回 0,其它请参考错误码列表
virtual int SetAudioMuteFlag(AudioDeviceInfo::AudioDeviceType device_type_, bool mute_flag_) = 0;
// 获取指定类型的设备是否静音
// @return true:已静音;false:未静音
virtual bool GetAudioMuteFlag(AudioDeviceInfo::AudioDeviceType device_type_) = 0;
// 当使用外部数据导入时,首先通过此接口激活外部 PCM 数据导入开关
// @param enable_flag_ 激活开关
// @return 成功返回 0,其它请参考错误码列表
virtual int EnableAudioFakeInput(bool enable_flag_) = 0;
// 实时导入外部音频 PCM 数据,仅当 EnableAudioFakeInput(true) 时有效
// @param audio_data_ PCM 数据内存地址
// @param data_size_ 数据大小
// @param bits_per_sample_ 位宽,即每采样点所占位数
// @param sample_rate_ 采样率
// @param number_of_channels_ 声道数
// @param number_of_frames_ 每次导入数据所包含的采样点数
// @return 成功返回 0,其它请参考错误码列表
virtual int InputAudioFrame(
const unsigned char* audio_data_,
unsigned int data_size_,
unsigned int bits_per_sample_,
unsigned int sample_rate_,
unsigned int number_of_channels_,
unsigned int number_of_frames_
) = 0;
// 是否激活了外部音频数据导入
// @return true or false
virtual bool IsEnableAudioFakeInput() = 0;
// 激活监听功能:混合本地麦克风和系统声卡的声音,此方法非线程安全接口
// @param enable_ 是否激活监听功能开关
// @param volume_scale_ratio_ 系统声音缩放倍数,以方便控制系统音量大小
// @return 成功返回 0,其它请参考错误码列表
virtual int MixDesktopAudio(bool enable_, float volume_scale_ratio_ = 1.0f) = 0;
// 是否开启回声消除,默认开启,禁用后在使用扬声器的场景下将产生回声
// @param enable_ 是否开启, true or false
// @return 目前阶段全部返回 0
// @brief 测试阶段,慎用
virtual int EnableAec(bool enable_) = 0;
//开启软件回音消除功能,在有些机器上效果不明显,需要强制降采样为 16K 才有效果,
//开启可能会降低音质,内部是默认开启,如果对回音消除没有需求,但对音质有需求,需要禁用。
// @param enable_ 是否开启, true or false
// @return 目前阶段全部返回 0
virtual int ForceLowSamplerate(bool enable_) = 0;
// 是否开启本地音频 track 编码后数据回调
// @param enable_ 是否开启,true or false,当为 true 时,通过 OnEncrypt 接口回调
virtual void EnableLocalAudioPacketCallBack(bool enable_) = 0;
// 是否开启远端音频 track 编码后数据回调
// @param enable_ 是否开启,true or false,当为 true 时,通过 OnDecrypt 接口回调
virtual void EnableRemoteAudioPacketCallBack(bool enbale_) = 0;
回调接口 QNAudioListener
QNAudioListener
是 QNAudioInterface
内嵌类,开发者需在上层继承此虚类并实现其纯虚接口,然后在 JoinRoom
前通过 SetRoomListener
设置房间事件监听接口,中途不能修改,直至上层调用 LeaveRoom
。
// 本地和远端 PCM 数据回调
// @param audio_data_ PCM 数据内存指针
// @param bits_per_sample_ 位宽,即每个采样点占用位数
// @param sample_rate_ 采样率
// @param number_of_channels_ 声道数
// @param number_of_frames_ 此次回调内包含了多少采样点数
// @param user_id_ PCM 数据所属 User Id,可以是远端用户也可以是本地用户
virtual void OnAudioPCMFrame(
const unsigned char* audio_data_,
int bits_per_sample_,
int sample_rate_,
size_t number_of_channels_,
size_t number_of_frames_,
const std::string& user_id_
) = 0;
// 音频设备插拔事件通知
// @param device_state_ 最新音频设备状态
// @param 设备 GUID
virtual void OnAudioDeviceStateChanged(
AudioDeviceState device_state_,
const std::string& device_guid_
) = 0;
// 放置音频自定义数据回调
// @param extra_data_ 用户自定义数据
// @param extra_data_max_size_ 用户可以放置到 extra_data_ 的最大字节数
// @param track_id_ 所属 Track Id,自己或者远端用户发布的 Track
// @return 返回放置到 extra_data_ 中的数据大小,没有添加则返回 0
virtual int OnPutExtraData(
unsigned char* extra_data_,
int extra_data_max_size_,
const std::string& track_id_
) = 0;
// 设置加密后最大字节数
// 配合 OnEncrypt 使用
// @param frame_size_ 未加密数据大小
// @param track_id_ 所属 Track Id,自己或者远端用户发布的 Track
// @return 需要的最大字节数
virtual int OnSetMaxEncryptSize(
int frame_size_,
const std::string& track_id_
) = 0;
// 加密回调接口
// @param frame_ 加密前的数据
// @param frame_size_ 加密前的数据大小
// @param encrypted_frame_ 加密后的数据
// @param track_id_ 所属 Track Id,自己或者远端用户发布的 Track
// @return 加密后的数据大小
virtual int OnEncrypt(
const unsigned char* frame_,
int frame_size_,
unsigned char* encrypted_frame_,
const std::string& track_id_
) = 0;
// 接收音频自定义数据回调
// @param extra_data_ 接收的用户自定义数据
// @param extra_data_size_ 自定义数据大小
// @param track_id_ 所属 Track Id,自己或者远端用户发布的 Track
virtual void OnGetExtraData(
const unsigned char* extra_data_,
int extra_data_size_,
const std::string& track_id_
) = 0;
// 设置解密后最大字节数
// 配合 OnDecrypt 使用
// @param encrypted_frame_size_ 加密后数据大小
// @param track_id_ 所属 Track Id,自己或者远端用户发布的 Track
// @return 需要的最大字节数
virtual int OnSetMaxDecryptSize(
int encrypted_frame_size_,
const std::string& track_id_
) = 0;
// 解密回调接口
// @param encrypted_frame_ 加密后的数据
// @param encrypted_size_ 加密后的数据大小
// @param frame_ 解密后的数据
// @param track_id_ 所属 Track Id,自己或者远端用户发布的 Track
// @return 解密后的数据大小
virtual int OnDecrypt(
const unsigned char* encrypted_frame_,
int encrypted_size_,
unsigned char* frame_,
const std::string& track_id_
) = 0;