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

C++ API Reference for All Platforms

概览 IRtcEngine IRtcEngineEventHandler IChannel IChannelEventHandler IAudioDeviceManager IVideoDeviceManager

#include <IAgoraRtcEngine.h>

Public 成员函数

virtual IAudioDeviceCollection * enumeratePlaybackDevices ()=0
 
virtual IAudioDeviceCollection * enumerateRecordingDevices ()=0
 
virtual int setPlaybackDevice (const char deviceId[MAX_DEVICE_ID_LENGTH])=0
 
virtual int setRecordingDevice (const char deviceId[MAX_DEVICE_ID_LENGTH])=0
 
virtual int followSystemPlaybackDevice (bool enable)=0
 
virtual int followSystemRecordingDevice (bool enable)=0
 
virtual int startPlaybackDeviceTest (const char *testAudioFilePath)=0
 
virtual int stopPlaybackDeviceTest ()=0
 
virtual int setPlaybackDeviceVolume (int volume)=0
 
virtual int getPlaybackDeviceVolume (int *volume)=0
 
virtual int setRecordingDeviceVolume (int volume)=0
 
virtual int getRecordingDeviceVolume (int *volume)=0
 
virtual int setPlaybackDeviceMute (bool mute)=0
 
virtual int getPlaybackDeviceMute (bool *mute)=0
 
virtual int setRecordingDeviceMute (bool mute)=0
 
virtual int getRecordingDeviceMute (bool *mute)=0
 
virtual int startRecordingDeviceTest (int indicationInterval)=0
 
virtual int stopRecordingDeviceTest ()=0
 
virtual int getPlaybackDevice (char deviceId[MAX_DEVICE_ID_LENGTH])=0
 
virtual int getPlaybackDeviceInfo (char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH])=0
 
virtual int getRecordingDevice (char deviceId[MAX_DEVICE_ID_LENGTH])=0
 
virtual int getRecordingDeviceInfo (char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH])=0
 
virtual int startAudioDeviceLoopbackTest (int indicationInterval)=0
 
virtual int stopAudioDeviceLoopbackTest ()=0
 
virtual void release ()=0
 

Protected 成员函数

virtual ~IAudioDeviceManager ()
 

详细描述

音频设备管理方法。

IAudioDeviceManager 接口类提供用于测试音频设备的相关接口。可通过实例化 AAudioDeviceManager 类来获取 IAudioDeviceManager 接口。

构造及析构函数说明

◆ ~IAudioDeviceManager()

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

成员函数说明

◆ enumeratePlaybackDevices()

virtual IAudioDeviceCollection * agora::rtc::IAudioDeviceManager::enumeratePlaybackDevices ( )
pure virtual

获取系统中所有的播放设备列表。（仅适用于 macOS 和 Windows）

该方法返回一个 IAudioDeviceCollection 对象，包含系统中所有的播放设备。通过 IAudioDeviceCollection 对象，App 可以枚举播放设备。在使用结束后，App 需调用 release 方法销毁返回的对象。

返回
  • 一个 IAudioDeviceCollection 对象，包含所有的播放设备（方法调用成功）;
  • NULL（方法调用失败）。

◆ enumerateRecordingDevices()

virtual IAudioDeviceCollection * agora::rtc::IAudioDeviceManager::enumerateRecordingDevices ( )
pure virtual

获取系统中所有的音频采集设备列表。（仅适用于 macOS 和 Windows）

该方法返回一个 IAudioDeviceCollection 对象，包含系统中所有的音频采集设备。通过 IAudioDeviceCollection 对象，App 可以枚举音频采集设备。在使用结束后，App 需调用 release 方法销毁返回的对象。

返回
  • 一个 IAudioDeviceCollection 对象，包含所有的音频采集设备（方法调用成功）;
  • NULL（方法调用失败）。

◆ setPlaybackDevice()

virtual int agora::rtc::IAudioDeviceManager::setPlaybackDevice ( const char  deviceId[MAX_DEVICE_ID_LENGTH])
pure virtual

指定播放设备。（仅适用于 macOS 和 Windows）

参数
deviceId通过 deviceID 指定播放设备。由 enumeratePlaybackDevices 获取。插拔设备不会影响 deviceId。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRecordingDevice()

virtual int agora::rtc::IAudioDeviceManager::setRecordingDevice ( const char  deviceId[MAX_DEVICE_ID_LENGTH])
pure virtual

指定音频采集设备。（仅适用于 macOS 和 Windows）

参数
deviceId音频采集设备的 Device ID。可通过 enumerateRecordingDevices 获取。插拔设备不会影响 deviceId。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ followSystemPlaybackDevice()

virtual int agora::rtc::IAudioDeviceManager::followSystemPlaybackDevice ( bool  enable)
pure virtual

设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。（仅适用于 macOS 和 Windows）

自从
v3.6.0
参数
enable是否跟随系统默认的音频播放设备：
  • true：跟随。当系统默认音频播放设备发生改变时，SDK 立即切换音频播放设备。
  • false：不跟随。只有当 SDK 使用的音频播放设备被移除后，SDK 才切换至系统默认的音频播放设备。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ followSystemRecordingDevice()

virtual int agora::rtc::IAudioDeviceManager::followSystemRecordingDevice ( bool  enable)
pure virtual

设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。（仅适用于 macOS 和 Windows）

自从
v3.6.0
参数
enable是否跟随系统默认的音频采集设备：
  • true：跟随。当系统默认的音频采集设备改变时，SDK 立即切换音频采集设备。
  • false：不跟随。只有当 SDK 使用的音频采集设备被移除后，SDK 才切换至系统默认的音频采集设备。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startPlaybackDeviceTest()

virtual int agora::rtc::IAudioDeviceManager::startPlaybackDeviceTest ( const char *  testAudioFilePath)
pure virtual

启动音频播放设备测试。（仅适用于 macOS 和 Windows）

该方法测试音频播放设备是否能正常工作。启动测试后，SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。

自 v3.6.2 起，该方法在加入频道前后均可调用，并每隔 100 ms 触发一次如下回调，报告播放设备的音量信息：

  • 在加入频道前调用该方法，SDK 触发 onAudioVolumeIndication 和 onAudioDeviceTestVolumeIndication 回调，其中：

    • onAudioVolumeIndication 报告 uid = 1 和 volume。
    • onAudioDeviceTestVolumeIndication 报告 volumeType = AudioTestPlaybackVolume(1) 和 volume。

    这两个回调报告的音量信息相同，声网推荐使用 onAudioDeviceTestVolumeIndication。

  • 在加入频道后调用该方法，SDK 触发 onAudioDeviceTestVolumeIndication 回调，报告 volumeType = AudioTestPlaybackVolume(1) 和 volume。
注解
  • 加入频道后调用该方法，测试的是 SDK 正在使用的音频播放设备。
  • 调用该方法后，必须调 stopPlaybackDeviceTest 方法停止测试。
参数
testAudioFilePath音频文件的绝对路径，路径字符串使用 UTF-8 编码格式。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopPlaybackDeviceTest()

virtual int agora::rtc::IAudioDeviceManager::stopPlaybackDeviceTest ( )
pure virtual

停止播放设备测试。（仅适用于 macOS 和 Windows）

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

◆ setPlaybackDeviceVolume()

virtual int agora::rtc::IAudioDeviceManager::setPlaybackDeviceVolume ( int  volume)
pure virtual

设置播放设备音量。（仅适用于 macOS 和 Windows）

参数
volume播放设备音量。取值可在 [0,255]。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getPlaybackDeviceVolume()

virtual int agora::rtc::IAudioDeviceManager::getPlaybackDeviceVolume ( int *  volume)
pure virtual

获取播放设备音量。（仅适用于 macOS 和 Windows）

参数
volume播放设备音量。取值可在 [0,255]。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRecordingDeviceVolume()

virtual int agora::rtc::IAudioDeviceManager::setRecordingDeviceVolume ( int  volume)
pure virtual

设置音频采集设备音量。（仅适用于 macOS 和 Windows）

注解
该方法需要在加入频道后调用。
参数
volume音频采集设备音量。取值范围 [0,255]。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getRecordingDeviceVolume()

virtual int agora::rtc::IAudioDeviceManager::getRecordingDeviceVolume ( int *  volume)
pure virtual

获取音频采集设备音量。（仅适用于 macOS 和 Windows）

参数
volume音频采集设备音量。取值范围 [0,255]。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setPlaybackDeviceMute()

virtual int agora::rtc::IAudioDeviceManager::setPlaybackDeviceMute ( bool  mute)
pure virtual

静音播放设备。（仅适用于 macOS 和 Windows）

参数
mute
  • true: 设备设为静音；
  • false: 设备设为不静音。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getPlaybackDeviceMute()

virtual int agora::rtc::IAudioDeviceManager::getPlaybackDeviceMute ( bool *  mute)
pure virtual

获取播放设备静音状态。（仅适用于 macOS 和 Windows）

参数
mute
  • true: 已静音状态；
  • false: 非静音状态。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRecordingDeviceMute()

virtual int agora::rtc::IAudioDeviceManager::setRecordingDeviceMute ( bool  mute)
pure virtual

静音音频采集设备。（仅适用于 macOS 和 Windows）

参数
mute
  • true: 设备设为静音；
  • false: 设备设为非静音。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getRecordingDeviceMute()

virtual int agora::rtc::IAudioDeviceManager::getRecordingDeviceMute ( bool *  mute)
pure virtual

获取音频采集设备静音状态。（仅适用于 macOS 和 Windows）

参数
mute
  • true: 已静音状态；
  • false: 非静音状态。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startRecordingDeviceTest()

virtual int agora::rtc::IAudioDeviceManager::startRecordingDeviceTest ( int  indicationInterval)
pure virtual

启动音频采集设备测试。（仅适用于 macOS 和 Windows）

该方法测试音频采集设备是否能正常工作。

自 v3.6.2 起，该方法在加入频道前后均可调用，并按设置的时间间隔触发如下回调，报告采集设备的音量信息：

  • 在加入频道前调用该方法，SDK 触发 onAudioVolumeIndication 和 onAudioDeviceTestVolumeIndication 回调，其中：

    • onAudioVolumeIndication 报告 uid = 0 和 volume。
    • onAudioDeviceTestVolumeIndication 报告 volumeType = AudioTestRecordingVolume(0) 和 volume。

    这两个回调报告的音量信息相同，声网推荐使用 onAudioDeviceTestVolumeIndication。

  • 在加入频道后调用该方法，SDK 触发 onAudioDeviceTestVolumeIndication 回调，报告 volumeType = AudioTestRecordingVolume(0) 和 volume。
注解
  • 加入频道后调用该方法前，请确保音频采集设备处于开启状态，即 enableLocalAudio(true) 。否则，方法调用会失败，SDK 触发 onError 回调，报告 ERR_ADM_START_RECORDING(1012) 错误码。
  • 加入频道后调用该方法，测试的是 SDK 正在使用的音频采集设备。
  • 调用该方法后，必须调 stopRecordingDeviceTest 方法停止测试。
参数
indicationIntervalSDK 返回 onAudioVolumeIndication 或 onAudioDeviceTestVolumeIndication 回调的 时间间隔，单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒，否则会收不到音量回调。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopRecordingDeviceTest()

virtual int agora::rtc::IAudioDeviceManager::stopRecordingDeviceTest ( )
pure virtual

停止音频采集设备测试。（仅适用于 macOS 和 Windows）

该方法停止音频采集设备测试。调用 startRecordingDeviceTest 后，必须调用该方法停止测试。

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

◆ getPlaybackDevice()

virtual int agora::rtc::IAudioDeviceManager::getPlaybackDevice ( char  deviceId[MAX_DEVICE_ID_LENGTH])
pure virtual

获取音频播放设备。（仅适用于 macOS 和 Windows）

参数
deviceId音频播放设备的设备 ID。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getPlaybackDeviceInfo()

virtual int agora::rtc::IAudioDeviceManager::getPlaybackDeviceInfo ( char  deviceId[MAX_DEVICE_ID_LENGTH],
char  deviceName[MAX_DEVICE_ID_LENGTH] 
)
pure virtual

根据设备 ID 和设备名称获取播放设备。（仅适用于 macOS 和 Windows）

参数
deviceId播放设备的设备 ID。
deviceName播放设备的设备名称。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getRecordingDevice()

virtual int agora::rtc::IAudioDeviceManager::getRecordingDevice ( char  deviceId[MAX_DEVICE_ID_LENGTH])
pure virtual

根据设备 ID 获取音频采集设备。（仅适用于 macOS 和 Windows）

参数
deviceId采集设备的设备 ID。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ getRecordingDeviceInfo()

virtual int agora::rtc::IAudioDeviceManager::getRecordingDeviceInfo ( char  deviceId[MAX_DEVICE_ID_LENGTH],
char  deviceName[MAX_DEVICE_ID_LENGTH] 
)
pure virtual

根据设备名称和设备 ID 获取音频采集设备信息。（仅适用于 macOS 和 Windows）

参数
deviceId音频采集设备的设备 ID。
deviceName音频采集设备的设备名称。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startAudioDeviceLoopbackTest()

virtual int agora::rtc::IAudioDeviceManager::startAudioDeviceLoopbackTest ( int  indicationInterval)
pure virtual

开始音频设备回路测试。（仅适用于 macOS 和 Windows）

该方法测试音频采集和播放设备是否能正常工作。一旦测试开始，音频采集设备会采集本地音频，然后通过音频播放设备播放。

自 v3.6.2 起，该方法在加入频道前后均可调用，并按设置的时间间隔触发如下回调，分别报告采集设备和播放设备的音量信息：

  • 在加入频道前调用该方法，SDK 触发 onAudioVolumeIndication 和 onAudioDeviceTestVolumeIndication 回调，每个回调触发两次，其中：

    • onAudioVolumeIndication 分别报告 uid = 0 和 volume，以及 uid = 1 和 volume。
    • onAudioDeviceTestVolumeIndication 分别报告 volumeType = AudioTestRecordingVolume(0) 和 volume，以及 volumeType = AudioTestPlaybackVolume(1) 和 volume。

    onAudioVolumeIndication 和 onAudioDeviceTestVolumeIndication 回调报告的音量信息相同，声网推荐使用 onAudioDeviceTestVolumeIndication。

  • 在加入频道后调用该方法，SDK 触发两个 onAudioDeviceTestVolumeIndication 回调，分别报告 volumeType = AudioTestRecordingVolume(0) 和 volume，以及 volumeType = AudioTestPlaybackVolume(1) 和 volume。
注解
  • 该方法仅在本地进行音频设备测试，不涉及网络连接。
  • 加入频道后调用该方法前，请确保音频采集设备处于开启状态，即 enableLocalAudio(true)。否则，方法调用会失败，SDK 触发 onError 回调，报告 ERR_ADM_START_RECORDING(1012) 错误码。
  • 加入频道后调用该方法，测试的是 SDK 正在使用的音频采集和播放设备。
  • 调用该方法后，必须调 stopAudioDeviceLoopbackTest 方法停止测试。
参数
indicationIntervalSDK 触发 onAudioVolumeIndication 或 onAudioDeviceTestVolumeIndication 回调的时间间隔，单位为毫秒。 建议设置到大于 200 毫秒。不得少于 10 毫秒，否则会收不到音量回调。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ stopAudioDeviceLoopbackTest()

virtual int agora::rtc::IAudioDeviceManager::stopAudioDeviceLoopbackTest ( )
pure virtual

停止音频设备回路测试。（仅适用于 macOS 和 Windows）

注解
在调用 startAudioDeviceLoopbackTest 后，必须调用该方法停止音频设备回路测试。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ release()

virtual void agora::rtc::IAudioDeviceManager::release ( )
pure virtual

释放 IAudioDeviceManager 对象占用的所有资源。（仅适用于 macOS 和 Windows）