桌面端音频设备管理

enumeratePlaybackDevices

获取系统中所有的播放设备列表。

C++
virtual IAudioDeviceCollection* enumeratePlaybackDevices() = 0;

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

返回值

方法调用成功：返回一个 IAudioDeviceCollection 对象，包含所有的音频播放设备。
方法调用失败: NULL。

所属接口类

IAudioDeviceManager

enumerateRecordingDevices

获取系统中所有的音频采集设备列表。

C++
virtual IAudioDeviceCollection* enumerateRecordingDevices() = 0;

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

返回值

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

所属接口类

IAudioDeviceManager

followSystemLoopbackDevice

设置声卡采集设备是否跟随系统默认的播放设备。

C++
virtual int followSystemLoopbackDevice(bool enable) = 0;

自从

v4.0.1

方法仅适用于 Windows 和 macOS。

参数

参数名描述

参数名	描述
enable	是否跟随系统默认的播放设备： `true`：跟随。当系统默认播放设备发生改变时，SDK 立即跟随切换声卡采集设备。 `false`：不跟随。只有当 SDK 使用的声卡采集设备被移除后，SDK 才切换至系统默认的音频播放设备。

enable

是否跟随系统默认的播放设备：

true：跟随。当系统默认播放设备发生改变时，SDK 立即跟随切换声卡采集设备。
false：不跟随。只有当 SDK 使用的声卡采集设备被移除后，SDK 才切换至系统默认的音频播放设备。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

followSystemPlaybackDevice

设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。

C++
virtual int followSystemPlaybackDevice(bool enable) = 0;

注意：该方法仅适用于 Windows 和 macOS。

参数

参数名描述

参数名	描述
enable	是否跟随系统默认的音频播放设备： `true`：跟随。当系统默认音频播放设备发生改变时，SDK 立即切换音频播放设备。 `false`：不跟随。只有当 SDK 使用的音频播放设备被移除后，SDK 才切换至系统默认的音频播放设备。

enable

是否跟随系统默认的音频播放设备：

true：跟随。当系统默认音频播放设备发生改变时，SDK 立即切换音频播放设备。
false：不跟随。只有当 SDK 使用的音频播放设备被移除后，SDK 才切换至系统默认的音频播放设备。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

followSystemRecordingDevice

设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。

C++
virtual int followSystemRecordingDevice(bool enable) = 0;

注意：该方法仅适用于 Windows 和 macOS。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

getApplicationVolume

获取 app 的当前音量。

C++
virtual int getApplicationVolume(int& volume) = 0;

参数

参数名	描述
volume	app 当前的音量，取值范围为 [0,255]。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceCollection

getAudioDeviceInfo

获取音频设备信息。

C++
virtual int getAudioDeviceInfo(DeviceInfo& deviceInfo) = 0;

调用该方法后，你可以获取音频设备是否支持极低延时采集和播放。

注意：

该方法仅适用于 Android 平台。
该方法在加入频道前后均可调用。

参数

参数名描述

参数名	描述
deviceInfo	输入和输出参数。标识音频设备信息的 `DeviceInfo` 对象。输入值：一个 `DeviceInfo` 对象。输出值：一个包含了音频设备信息的 `DeviceInfo` 对象。

deviceInfo

输入和输出参数。标识音频设备信息的 DeviceInfo 对象。

输入值：一个 DeviceInfo 对象。
输出值：一个包含了音频设备信息的 DeviceInfo 对象。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

getCount

获取播放或音频采集设备数量。

C++
virtual int getCount() = 0;

如果先调用 enumeratePlaybackDevices 再调用该方法，返回播放设备的数量。如果先调用 enumerateRecordingDevices 再调用该方法，则返回音频采集设备的数量。

返回值

语音设备数目。

所属接口类

IAudioDeviceCollection

getDefaultDevice

获取系统默认的音频设备。

C++
virtual int getDefaultDevice(char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

该方法仅适用于 Windows 和 macOS。
你需要先调用 enumeratePlaybackDevices 或 enumerateRecordingDevices 获取设备列表后，再调用该方法。

参数

参数名	描述
deviceName	输出参数，系统默认的音频设备名称。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。
deviceId	输出参数，系统默认的音频设备 ID。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见 错误码了解详情和解决建议。

所属接口类

IAudioDeviceCollection

getDevice

获取指定 index 的设备信息。

C++
virtual int getDevice(int index, char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

参数

参数名	描述
index	输入参数，指定想查询的设备信息。
deviceName	输出参数，设备名称。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。
deviceId	输出参数，设备 ID。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceCollection

getLoopbackDevice

获取当前的声卡采集设备。

C++
virtual int getLoopbackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

自从

v4.0.1

该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
deviceId	输出参数，当前声卡采集设备的 ID。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

getPlaybackDevice

获取当前音频播放设备。

C++
virtual int getPlaybackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

注意：该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
deviceId	输出参数，当前音频播放设备的设备 ID。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

getPlaybackDeviceInfo

根据设备 ID 和设备名称获取播放设备。

C++
virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0;

注意：该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
deviceId	播放设备的设备 ID。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。
deviceName	播放设备的设备名称。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

getRecordingDevice

获取当前音频采集设备。

C++
virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

注意：该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
deviceId	输出参数。当前采集设备的设备 ID。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

getRecordingDeviceInfo

根据设备名称和设备 ID 获取音频采集设备信息。

C++
virtual int getRecordingDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0;

注意：该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
deviceId	播放设备的设备 ID。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。
deviceName	播放设备的设备名称。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

isApplicationMute

获取 app 当前的静音状态。

C++
virtual int isApplicationMute(bool &mute) = 0;

参数

参数名	描述
mute	app 当前是否静音： `true`: app 为静音状态。 `false`: app 为非静音状态。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceCollection

release

释放 IAudioDeviceCollection 对象占用的所有资源。

C++
virtual void release() = 0;

所属接口类

IAudioDeviceCollection

release

释放 IAudioDeviceManager 对象占用的所有资源。

C++
virtual void release() = 0;

所属接口类

IAudioDeviceManager

setApplicationMute

设置是否将 app 静音。

C++
virtual int setApplicationMute(bool mute) = 0;

参数

参数名	描述
mute	是否将 app 设置为静音。 `true`: 将 app 静音。 `false`: 将 app 解除静音。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceCollection

setApplicationVolume

设置 app 音量。

C++
virtual int setApplicationVolume(int volume) = 0;

参数

参数名	描述
volume	app 的音量，取值范围为 [0,255]。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceCollection

setDevice

指定音频设备。

C++
virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

该方法可以更改当前的音频路由，但不会改变系统默认的音频路由。假设系统默认的音频路由是扬声器 1，你在加入频道前调用该方法设置当前的音频路由为扬声器 2，如果在此时进行设备检测，SDK 会对扬声器 2 进行检测。检测结束后，当你加入频道时 SDK 依然会选择使用系统默认的音频路由，即扬声器 1。

参数

参数名	描述
deviceId	设备 ID。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceCollection

setLoopbackDevice

指定声卡采集设备。

C++
virtual int setLoopbackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

自从

v4.0.1

SDK 默认采用当前的播放设备作为声卡采集设备，如果想要指定其他音频设备作为声卡采集设备，则调用该方法并设置 deviceId 为你想要指定的声卡采集设备。

该方法可以更改当前的音频采集设备，但不改变系统默认的音频采集设备。假设系统默认的音频采集设备是麦克风 1，你在加入频道前调用该方法设置当前的音频路由为声卡 1，如果在此时进行设备检测，SDK 会对声卡 1 做设备检测。检测结束后，当你加入频道时 SDK 依然会选择使用系统默认的音频采集设备，即麦克风 1。

注：
该方法仅适用于 Windows 和 macOS。
该方法适用的场景如下：
使用 app A 播放音乐，通过蓝牙耳机播放；同时使用 app B 进行视频会议，通过扬声器播放。

如果设置声卡采集设备为蓝牙耳机，则 SDK 会将 app A 中的音乐发布到远端。
如果设置声卡采集设备设置为扬声器，则 SDK 不会将 app A 中的音乐发布到远端。
如果设置声卡采集设备为蓝牙耳机后，又改用有线耳机播放 app A 中的音乐，则需要重新调用该方法，设置声卡采集设备为有线耳机，则 SDK 会继续将 app A 中的音乐发布到远端。

参数

参数名	描述
deviceId	指定 SDK 的声卡采集设备。由 `enumeratePlaybackDevices` 获取。插拔设备不会影响 `deviceId`。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

setPlaybackDevice

指定播放设备。

C++
virtual int setPlaybackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

注意：该方法仅适用于 Windows 和 macOS。该方法可以更改当前的音频路由，但不会改变系统默认的音频路由。假设系统默认的音频路由是扬声器 1，你在加入频道前调用该方法设置当前的音频路由为扬声器 2，如果在此时进行设备检测，SDK 会对扬声器 2 进行检测。检测结束后，当你加入频道时 SDK 依然会选择使用系统默认的音频路由，即扬声器 1。

参数

参数名	描述
deviceId	指定播放设备。由 `enumeratePlaybackDevices` 获取。插拔设备不会影响 `deviceId`。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

setRecordingDevice

指定音频采集设备。

C++
virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

注意：该方法仅适用于 Windows 和 macOS。该方法可以更改当前的音频采集设备，但不改变系统默认的音频采集设备。假设系统默认的音频采集设备是麦克风 1，你在加入频道前调用该方法设置当前的音频路由为蓝牙耳机 1，如果在此时进行设备检测，SDK 会对蓝牙耳机 1 进行检测。检测结束后，当你加入频道时 SDK 依然会选择使用系统默认的音频采集设备，即麦克风 1。

参数

参数名	描述
deviceId	音频采集设备的 Device ID。可通过 `enumerateRecordingDevices` 获取。插拔设备不会影响 `deviceId`。最大长度为 `MAX_DEVICE_ID_LENGTH_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

setRecordingDeviceVolume

设置音频采集设备音量。

C++
virtual int setRecordingDeviceVolume(int volume) = 0;

该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
volume	音频采集设备音量。取值范围 [0,255]。0 代表无声，255 代表最大音量。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

startAudioDeviceLoopbackTest

开始音频设备回路测试。

C++
virtual int startAudioDeviceLoopbackTest(int indicationInterval) = 0;

该方法测试音频采集和播放设备是否能正常工作。一旦测试开始，音频采集设备会采集本地音频，然后使用音频播放设备播放出来。SDK 会按设置的时间间隔触发两个 onAudioVolumeIndication 回调，分别报告音频采集设备（uid = 0）和音频播放设置（uid = 1）的音量信息。

注意：

该方法仅适用于 Windows 和 macOS。
该方法在加入频道前后都可调用。
该方法仅支持主播角色调用。
该方法仅在本地进行音频设备测试，不涉及网络连接。
完成测试后，必须调用 stopAudioDeviceLoopbackTest 停止音频设备回路测试。

参数

参数名	描述
indicationInterval	SDK 触发 `onAudioVolumeIndication` 回调的时间间隔，单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒，否则会收不到 `onAudioVolumeIndication` 回调。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

startPlaybackDeviceTest

启动音频播放设备测试。

C++
virtual int startPlaybackDeviceTest(const char* testAudioFilePath) = 0;

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

调用该方法后，SDK 会每隔 100 ms 触发一次 onAudioVolumeIndication 回调，报告 uid = 1 及播放设备的音量信息。

注意：

该方法需要在加入频道前调用。
该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
testAudioFilePath	音频文件的绝对路径，路径字符串使用 UTF-8 编码格式。支持文件格式: wav、mp3、m4a、aac。支持文件采样率: 8000、16000、32000、44100、48000。

参数名

描述

testAudioFilePath

音频文件的绝对路径，路径字符串使用 UTF-8 编码格式。

支持文件格式: wav、mp3、m4a、aac。
支持文件采样率: 8000、16000、32000、44100、48000。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

startRecordingDeviceTest

启动音频采集设备测试。

C++
virtual int startRecordingDeviceTest(int indicationInterval) = 0;

该方法测试音频采集设备是否能正常工作。调用该方法后，SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调，报告 uid = 0 及采集设备的音量信息。

注：

该方法仅适用于 Windows 和 macOS。
该方法需要在加入频道前调用。

参数

参数名	描述
indicationInterval	SDK 触发 `onAudioVolumeIndication` 回调的时间间隔，单位为毫秒。建议设置到大于 200 毫秒。不得小于 10 毫秒，否则会收不到 `onAudioVolumeIndication` 回调。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

stopAudioDeviceLoopbackTest

停止音频设备回路测试。

C++
virtual int stopAudioDeviceLoopbackTest() = 0;

注意：

该方法仅适用于 Windows 和 macOS。
该方法在加入频道前后都可调用。
该方法仅支持主播角色调用。
在调用 startAudioDeviceLoopbackTest 后，必须调用该方法停止音频设备回路测试。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

stopPlaybackDeviceTest

停止音频播放设备测试。

C++
virtual int stopPlaybackDeviceTest() = 0;

该方法停止音频播放设备测试。调用 startPlaybackDeviceTest 后，必须调用该方法停止测试。

注意：

该方法仅适用于 Windows 和 macOS。
该方法需要在加入频道前调用。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

stopRecordingDeviceTest

停止音频采集设备测试。

C++
virtual int stopRecordingDeviceTest() = 0;

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

注：

该方法仅适用于 Windows 和 macOS。
该方法需要在加入频道前调用。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IAudioDeviceManager

onAudioDeviceStateChanged

音频设备变化回调。

C++
virtual void onAudioDeviceStateChanged(const char* deviceId,
     int deviceType,
     int deviceState) {
     (void)deviceId;
     (void)deviceType;
     (void)deviceState;
     }

提示系统音频设备状态发生改变，比如耳机被拔出。

注：该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
deviceId	设备 ID。
deviceType	设备类型定义。详见 `MEDIA_DEVICE_TYPE`。
deviceState	设备状态。

所属接口类

IRtcEngineEventHandler

onAudioDeviceVolumeChanged

音频设备或 app 的音量发生改变回调。

C++
virtual void onAudioDeviceVolumeChanged(MEDIA_DEVICE_TYPE deviceType, int volume, bool muted) {
    (void)deviceType;
    (void)volume;
    (void)muted;
  }

当音频播放、采集设备或 app 的音量发生改变时，会触发该回调。

注：该回调仅适用于 Windows 和 macOS。

参数

参数名描述

参数名	描述
deviceType	设备类型定义。详见 `MEDIA_DEVICE_TYPE`。
volume	音量。范围为 [0,255]。
muted	音频设备是否为静音状态： `true`: 音频设备已静音。 `false`: 音频设备未被静音。

deviceType

设备类型定义。详见 MEDIA_DEVICE_TYPE。

volume

音量。范围为 [0,255]。

muted

音频设备是否为静音状态：

true: 音频设备已静音。
false: 音频设备未被静音。

所属接口类

IRtcEngineEventHandler

enumeratePlaybackDevices

返回值​

enumerateRecordingDevices

返回值​

followSystemLoopbackDevice

参数​

返回值​

followSystemPlaybackDevice

参数​

返回值​

followSystemRecordingDevice

返回值​

getApplicationVolume

参数​

返回值​

getAudioDeviceInfo

参数​

返回值​

getCount

返回值​

getDefaultDevice

参数​

返回值​

getDevice

参数​

返回值​

getLoopbackDevice

参数​

返回值​

getPlaybackDevice

参数​

返回值​

getPlaybackDeviceInfo

参数​

返回值​

getRecordingDevice

参数​

返回值​

getRecordingDeviceInfo

参数​

返回值​

isApplicationMute

参数​

返回值​

release

release

setApplicationMute

参数​

返回值​

setApplicationVolume

参数​

返回值​

setDevice

参数​

返回值​

setLoopbackDevice

参数​

返回值​

setPlaybackDevice

参数​

返回值​

setRecordingDevice

参数​

返回值​

setRecordingDeviceVolume

参数​

返回值​

startAudioDeviceLoopbackTest

参数​

返回值​

startPlaybackDeviceTest

参数​

返回值​

startRecordingDeviceTest

参数​

返回值​

stopAudioDeviceLoopbackTest

返回值​

stopPlaybackDeviceTest

返回值​

返回值

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

返回值

返回值

参数

参数