音频设备管理
介绍跟音频设备管理相关的方法和回调。
enumeratePlaybackDevices
获取系统中所有的播放设备列表。
virtual IAudioDeviceCollection* enumeratePlaybackDevices() = 0;
详情
该方法返回一个 IAudioDeviceCollection 对象,包含系统中所有的播放设备。通过 IAudioDeviceCollection 对象,App 可以枚举播放设备。在使用结束后,app 需调用 release 方法销毁返回的对象。
返回值
- 方法调用成功:返回一个 IAudioDeviceCollection 对象,包含所有的音频播放设备。
- 方法调用失败: NULL。
enumerateRecordingDevices
获取系统中所有的音频采集设备列表。
virtual IAudioDeviceCollection* enumerateRecordingDevices() = 0;
详情
该方法返回一个 IAudioDeviceCollection 对象,包含系统中所有的音频采集设备。通过 IAudioDeviceCollection 对象,App 可以枚举音频采集设备。在使用结束后,App 需调用 release 方法销毁返回的对象。
返回值
- 方法调用成功:返回一个 IAudioDeviceCollection 对象,包含所有的音频采集设备。
- 方法调用失败: NULL。
followSystemLoopbackDevice
设置声卡采集设备是否跟随系统默认的播放设备。
virtual int followSystemLoopbackDevice(bool enable) = 0;
详情
- 自从
- v4.0.1
方法仅适用于 Windows 和 macOS。
参数
- enable
- 是否跟随系统默认的播放设备:
true
:跟随。当系统默认播放设备发生改变时,SDK 立即跟随切换声卡采集设备。false
:不跟随。只有当 SDK 使用的声卡采集设备被移除后,SDK 才切换至系统默认的音频播放设备。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
followSystemPlaybackDevice
设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。
virtual int followSystemPlaybackDevice(bool enable) = 0;
详情
参数
- enable
- 是否跟随系统默认的音频播放设备:
true
:跟随。当系统默认音频播放设备发生改变时,SDK 立即切换音频播放设备。false
:不跟随。只有当 SDK 使用的音频播放设备被移除后,SDK 才切换至系统默认的音频播放设备。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
followSystemRecordingDevice
设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。
virtual int followSystemRecordingDevice(bool enable) = 0;
详情
- enable
- 是否跟随系统默认的音频采集设备:
true
:跟随。当系统默认的音频采集设备改变时,SDK 立即切换音频采集设备。false
:不跟随。只有当 SDK 使用的音频采集设备被移除后,SDK 才切换至系统默认的音频采集设备。
返回值
- 0:方法调用成功
- < 0:方法调用失败
getApplicationVolume
获取 app 的当前音量。
virtual int getApplicationVolume(int& volume) = 0;
参数
- volume
- app 当前的音量,取值范围为 [0,255]。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getAudioDeviceInfo
获取音频设备信息。
virtual int getAudioDeviceInfo(DeviceInfo& deviceInfo) = 0;
详情
调用该方法后,你可以获取音频设备是否支持极低延时采集和播放。
- 该方法仅适用于 Android 平台。
- 该方法在加入频道前后均可调用。
参数
- deviceInfo
- 输入和输出参数。标识音频设备信息的 DeviceInfo 对象。
- 输入值:一个 DeviceInfo 对象。
- 输出值:一个包含了音频设备信息的 DeviceInfo 对象。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
getCount
获取播放或音频采集设备数量。
virtual int getCount() = 0;
详情
如果先调用 enumeratePlaybackDevices 再调用该方法,返回播放设备的数量。如果先调用 enumerateRecordingDevices 再调用该方法,则返回音频采集设备的数量。
返回值
语音设备数目。
getDefaultDevice
获取系统默认的音频设备。
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: 方法调用失败。
getDevice
获取指定 index 的设备信息。
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: 方法调用失败。
getLoopbackDevice
获取当前的声卡采集设备。
virtual int getLoopbackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
详情
- 自从
- v4.0.1
该方法仅适用于 Windows 和 macOS。
参数
- deviceId
- 输出参数,当前声卡采集设备的 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getPlaybackDevice
获取当前音频播放设备。
virtual int getPlaybackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
详情
参数
- deviceId
- 输出参数,当前音频播放设备的设备 ID。最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getPlaybackDeviceInfo
根据设备 ID 和设备名称获取播放设备。
virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0;
详情
参数
- deviceId
- 播放设备的设备 ID。最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
- deviceName
- 播放设备的设备名称。最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getRecordingDevice
获取当前音频采集设备。
virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
详情
参数
- deviceId
- 输出参数。当前采集设备的设备 ID。最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getRecordingDeviceInfo
根据设备名称和设备 ID 获取音频采集设备信息。
virtual int getRecordingDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0;
详情
参数
- deviceId
- 播放设备的设备 ID。最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
- deviceName
- 播放设备的设备名称。最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
isSpeakerphoneEnabled
检查扬声器状态启用状态。
virtual bool isSpeakerphoneEnabled() = 0;
- 该方法仅适用于 Android 和 iOS。
- 该方法在加入频道前后都能调用。
返回值
true
: 扬声器已开启,语音会输出到扬声器。false
: 扬声器未开启,语音会输出到非扬声器(听筒,耳机等)。
release
释放 IAudioDeviceCollection 对象占用的所有资源。
virtual void release() = 0;
release
释放 IAudioDeviceManager 对象占用的所有资源。
virtual void release() = 0;
setApplicationMute
设置是否将 app 静音。
virtual int setApplicationMute(bool mute) = 0;
参数
- mute
- 是否将 app 设置为静音。
true
: 将 app 静音。false
: 将 app 解除静音。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setApplicationVolume
设置 app 音量。
virtual int setApplicationVolume(int volume) = 0;
参数
- volume
- app 的音量,取值范围为 [0,255]。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDevice
指定音频设备。
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: 方法调用失败。
setEnableSpeakerphone
开启或关闭扬声器播放。
virtual int setEnableSpeakerphone(bool speakerOn) = 0;
详情
如果 SDK 默认的音频路由(见音频路由)或 setDefaultAudioRouteToSpeakerphone 的设置无法满足你的需求,你可以调用 setEnableSpeakerphone 切换当前的音频路由。成功改变音频路由后,SDK 会触发 onAudioRoutingChanged 回调。
该方法只设置用户在当前频道内使用的音频路由,不会影响 SDK 默认的音频路由。如果用户离开当前频道并加入新的频道,则用户还是会使用 SDK 默认的音频路由。
- 该方法仅适用于 Android 和 iOS 平台。
- 该方法需要在加入频道后调用。
- 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备,则该方法的设置无效,音频只会通过外接设备播放。当有多个外接设备时,音频会通过最后一个接入的设备播放。
参数
- speakerOn
-
设置是否开启扬声器播放:
true
: 开启。音频路由为扬声器。false
: 关闭。音频路由为听筒。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLoopbackDevice
指定声卡采集设备。
virtual int setLoopbackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
详情
- 自从
- v4.0.1
SDK 默认采用当前的播放设备作为声卡采集设备,如果想要指定其他音频设备作为声卡采集设备,则调用该方法并设置 deviceId 为你想要指定的声卡采集设备。
该方法可以更改当前的音频采集设备,但不改变系统默认的音频采集设备。假设系统默认的音频采集设备是麦克风 1,你在加入频道前调用该方法设置当前的音频路由为声卡 1,如果在此时进行设备检测,SDK 会对声卡 1 做设备检测。检测结束后,当你加入频道时 SDK 依然会选择使用系统默认的音频采集设备,即麦克风 1。
该方法仅适用于 Windows 和 macOS。
该方法适用的场景如下:
- 如果设置声卡采集设备为蓝牙耳机,则 SDK 会将 app A 中的音乐发布到远端。
- 如果设置声卡采集设备设置为扬声器,则 SDK 不会将 app A 中的音乐发布到远端。
- 如果设置声卡采集设备为蓝牙耳机后,又改用有线耳机播放 app A 中的音乐,则需要重新调用该方法,设置声卡采集设备为有线耳机,则 SDK 会继续将 app A 中的音乐发布到远端。
参数
- deviceId
-
指定 SDK 的声卡采集设备。由 enumeratePlaybackDevices 获取。插拔设备不会影响 deviceId。
最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setPlaybackDevice
指定播放设备。
virtual int setPlaybackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
详情
该方法可以更改当前的音频路由,但不会改变系统默认的音频路由。假设系统默认的音频路由是扬声器 1,你在加入频道前调用该方法设置当前的音频路由为扬声器 2,如果在此时进行设备检测,SDK 会对扬声器 2 进行检测。检测结束后,当你加入频道时 SDK 依然会选择使用系统默认的音频路由,即扬声器 1。
参数
- deviceId
-
指定播放设备。由 enumeratePlaybackDevices 获取。插拔设备不会影响 deviceId。
最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRecordingDevice
指定音频采集设备。
virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
详情
该方法可以更改当前的音频采集设备,但不改变系统默认的音频采集设备。假设系统默认的音频采集设备是麦克风 1,你在加入频道前调用该方法设置当前的音频路由为蓝牙耳机 1,如果在此时进行设备检测,SDK 会对蓝牙耳机 1 进行检测。检测结束后,当你加入频道时 SDK 依然会选择使用系统默认的音频采集设备,即麦克风 1。
参数
- deviceId
-
音频采集设备的 Device ID。可通过 enumerateRecordingDevices 获取。插拔设备不会影响 deviceId。
最大长度为 MAX_DEVICE_ID_LENGTH_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRecordingDeviceVolume
设置音频采集设备音量。
virtual int setRecordingDeviceVolume(int volume) = 0;
详情
该方法仅适用于 Windows 和 macOS。
参数
- volume
- 音频采集设备音量。取值范围 [0,255]。0 代表无声,255 代表最大音量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startAudioDeviceLoopbackTest
开始音频设备回路测试。
virtual int startAudioDeviceLoopbackTest(int indicationInterval) = 0;
详情
该方法测试音频采集和播放设备是否能正常工作。一旦测试开始,音频采集设备会采集本地音频,然后使用音频播放设备播放出来。SDK 会按设置的时间间隔触发两个 onAudioVolumeIndication 回调,分别报告音频采集设备(uid = 0)和音频播放设置(uid = 1)的音量信息。
- 该方法仅适用于 Windows 和 macOS。
- 该方法在加入频道前后都可调用。
- 该方法仅支持主播角色调用。
- 该方法仅在本地进行音频设备测试,不涉及网络连接。
- 完成测试后,必须调用 stopAudioDeviceLoopbackTest 停止音频设备回路测试。
参数
- indicationInterval
- SDK 触发 onAudioVolumeIndication 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startPlaybackDeviceTest
启动音频播放设备测试。
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。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startRecordingDeviceTest
启动音频采集设备测试。
virtual int startRecordingDeviceTest(int indicationInterval) = 0;
详情
该方法测试音频采集设备是否能正常工作。调用该方法后,SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调,报告 uid = 0 及采集设备的音量信息。
- 该方法仅适用于 Windows 和 macOS。
- 该方法需要在加入频道前调用。
参数
- indicationInterval
- SDK 触发 onAudioVolumeIndication 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。不得小于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopAudioDeviceLoopbackTest
停止音频设备回路测试。
virtual int stopAudioDeviceLoopbackTest() = 0;
详情
- 该方法仅适用于 Windows 和 macOS。
- 该方法在加入频道前后都可调用。
- 该方法仅支持主播角色调用。
- 在调用 startAudioDeviceLoopbackTest 后,必须调用该方法停止音频设备回路测试。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopPlaybackDeviceTest
停止音频播放设备测试。
virtual int stopPlaybackDeviceTest() = 0;
详情
该方法停止音频播放设备测试。调用 startPlaybackDeviceTest 后,必须调用该方法停止测试。
- 该方法仅适用于 Windows 和 macOS。
- 该方法需要在加入频道前调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopRecordingDeviceTest
停止音频采集设备测试。
virtual int stopRecordingDeviceTest() = 0;
详情
该方法停止音频采集设备测试。调用 startRecordingDeviceTest 后,必须调用该方法停止测试。
- 该方法仅适用于 Windows 和 macOS。
- 该方法需要在加入频道前调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
onAudioDeviceStateChanged
音频设备变化回调。
virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) { (void)deviceId; (void)deviceType; (void)deviceState; }
提示系统音频设备状态发生改变,比如耳机被拔出。
参数
- deviceId
- 设备 ID。
- deviceType
- 设备类型定义。详见 MEDIA_DEVICE_TYPE。
- deviceState
- 设备状态。
onAudioDeviceVolumeChanged
音频设备或 app 的音量发生改变回调。
virtual void onAudioDeviceVolumeChanged(MEDIA_DEVICE_TYPE deviceType, int volume, bool muted) { (void)deviceType; (void)volume; (void)muted; }
当音频播放、采集设备或 app 的音量发生改变时,会触发该回调。
参数
- deviceType
- 设备类型定义。详见 MEDIA_DEVICE_TYPE。
- volume
- 音量。范围为 [0,255]。
- muted
-
音频设备是否为静音状态:
true
: 音频设备已静音。false
: 音频设备未被静音。