音频设备管理
介绍跟音频设备管理相关的方法和回调。
enumeratePlaybackDevices
获取系统中所有的播放设备列表。
List<AudioDeviceInfo> enumeratePlaybackDevices();
详情
返回值
- 方法调用成功，返回 AudioDeviceInfo 数组，包含所有音频播放设备的设备 ID 和设备名称。
- 方法调用失败: 返回空列表。
enumerateRecordingDevices
获取系统中所有的音频采集设备列表。
List<AudioDeviceInfo> enumerateRecordingDevices();
详情
返回值
- 方法调用成功，返回一个 AudioDeviceInfo 数组，包含所有音频采集设备的设备 ID 和设备名称。
- 方法调用失败: 返回空列表。
followSystemLoopbackDevice
设置声卡采集设备是否跟随系统默认的播放设备。
Future<void> followSystemLoopbackDevice(bool enable);
详情
方法仅适用于 Windows 和 macOS。
参数
- enable
- 是否跟随系统默认的播放设备：
true：跟随。当系统默认播放设备发生改变时，SDK 立即跟随切换声卡采集设备。false：不跟随。只有当 SDK 使用的声卡采集设备被移除后，SDK 才切换至系统默认的音频播放设备。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类followSystemPlaybackDevice
设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。
Future<void> followSystemPlaybackDevice(bool enable);
详情
参数
- enable
- 是否跟随系统默认的音频播放设备：
true：跟随。当系统默认音频播放设备发生改变时，SDK 立即切换音频播放设备。false：不跟随。只有当 SDK 使用的音频播放设备被移除后，SDK 才切换至系统默认的音频播放设备。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类followSystemRecordingDevice
设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。
Future<void> followSystemRecordingDevice(bool enable);
详情
参数
- enable
- 是否跟随系统默认的音频采集设备：
true：跟随。当系统默认的音频采集设备改变时，SDK 立即切换音频采集设备。false：不跟随。只有当 SDK 使用的音频采集设备被移除后，SDK 才切换至系统默认的音频采集设备。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类getAudioDeviceInfo
获取音频设备信息。
Future<DeviceInfo> getAudioDeviceInfo();
详情
调用该方法后，你可以获取音频设备是否支持极低延时采集和播放。
- 该方法仅适用于 Android 平台。
- 该方法在加入频道前后均可调用。
返回值
- 非空：方法调用成功。
- 空：方法调用失败。详见错误码了解详情和解决建议。
getAudioDeviceManager
获取 AudioDeviceManager 对象，以管理音频设备。
AudioDeviceManager getAudioDeviceManager();
返回值
一个 AudioDeviceManager 对象。
所属接口类getPlaybackDefaultDevice
获取系统默认的音频播放设备。
Future<AudioDeviceInfo> getPlaybackDefaultDevice();
详情
返回值
默认音频播放设备的信息。详见 AudioDeviceInfo。
所属接口类getPlaybackDevice
getPlaybackDeviceInfo
获取音频播放设备信息。
Future<AudioDeviceInfo> getPlaybackDeviceInfo();
详情
返回值
AudioDeviceInfo 对象，包含音频播放设备的设备 ID 和设备名称。
所属接口类getPlaybackDeviceMute
getPlaybackDeviceVolume
getLoopbackDevice
getRecordingDefaultDevice
获取系统默认的音频采集设备。
Future<AudioDeviceInfo> getRecordingDefaultDevice();
详情
返回值
默认音频采集设备的信息。详见 AudioDeviceInfo。
所属接口类getRecordingDevice
getRecordingDeviceInfo
获取音频采集设备信息。
Future<AudioDeviceInfo> getRecordingDeviceInfo();
详情
返回值
AudioDeviceInfo 对象，包含音频采集设备的设备 ID 和设备名称。
所属接口类getRecordingDeviceVolume
release
setLoopbackDevice
指定声卡采集设备。
Future<void> setLoopbackDevice(String deviceId);
详情
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。
最大长度为 MaxDeviceIdLengthType。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类setPlaybackDevice
指定播放设备。
Future<void> setPlaybackDevice(String deviceId);
详情
该方法可以更改当前的音频路由，但不会改变系统默认的音频路由。假设系统默认的音频路由是扬声器 1，你在加入频道前调用该方法设置当前的音频路由为扬声器 2，如果在此时进行设备检测，SDK 会对扬声器 2 进行检测。检测结束后，当你加入频道时 SDK 依然会选择使用系统默认的音频路由，即扬声器 1。
参数
- deviceId
指定播放设备。由 enumeratePlaybackDevices 获取。插拔设备不会影响 deviceId。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类setPlaybackDeviceMute
设置播放设备静音。
Future<void> setPlaybackDeviceMute(bool mute);
参数
- mute
- 是否设置播放设备为静音：
true: 播放设备设为静音。false: 播放设备不设为静音。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类setPlaybackDeviceVolume
设置播放设备音量。
Future<void> setPlaybackDeviceVolume(int volume);
详情
参数
- volume
- 播放设备音量。取值范围为 [0,255]。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类startPlaybackDeviceTest
启动音频播放设备测试。
Future<void> startPlaybackDeviceTest(String testAudioFilePath);
详情
该方法用于测试本地音频播放设备是否能正常工作。启动测试后，SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。
调用该方法后，SDK 会每隔 100 毫秒触发一次 onAudioVolumeIndication 回调，报告 uid = 1 及播放设备的音量信息。
该方法和 startEchoTest 的区别在于该方法检测本地的音频播放设备能否正常工作，后者可以检测音视频设备及网络是否正常。
参数
- testAudioFilePath
- 音频文件的绝对路径，路径字符串使用 UTF-8 编码格式。
- 支持文件格式: wav、mp3、m4a、aac。
- 支持文件采样率: 8000、16000、32000、44100、48000。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类setRecordingDevice
指定音频采集设备。
Future<void> setRecordingDevice(String deviceId);
详情
该方法可以更改当前的音频采集设备，但不改变系统默认的音频采集设备。假设系统默认的音频采集设备是麦克风 1，你在加入频道前调用该方法设置当前的音频路由为蓝牙耳机 1，如果在此时进行设备检测，SDK 会对蓝牙耳机 1 进行检测。检测结束后，当你加入频道时 SDK 依然会选择使用系统默认的音频采集设备，即麦克风 1。
参数
- deviceId
音频采集设备的 Device ID。可通过 enumerateRecordingDevices 获取。插拔设备不会影响 deviceId。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类setRecordingDeviceVolume
设置音频采集设备音量。
Future<void> setRecordingDeviceVolume(int volume);
详情
该方法仅适用于 Windows 和 macOS。
参数
- volume
- 音频采集设备音量。取值范围 [0,255]。0 代表无声，255 代表最大音量。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类startAudioDeviceLoopbackTest
开始音频设备回路测试。
Future<void> startAudioDeviceLoopbackTest(int indicationInterval);
详情
该方法测试音频采集和播放设备是否能正常工作。一旦测试开始，音频采集设备会采集本地音频，然后使用音频播放设备播放出来。SDK 会按设置的时间间隔触发两个 onAudioVolumeIndication 回调，分别报告音频采集设备（uid = 0）和音频播放设置（uid = 1）的音量信息。
- 该方法仅适用于 Windows 和 macOS。
- 该方法在加入频道前后都可调用。
- 该方法仅支持主播角色调用。
- 该方法仅在本地进行音频设备测试，不涉及网络连接。
- 完成测试后，必须调用 stopAudioDeviceLoopbackTest 停止音频设备回路测试。
参数
- indicationInterval
- SDK 触发 onAudioVolumeIndication 回调的时间间隔，单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒，否则会收不到 onAudioVolumeIndication 回调。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类startRecordingDeviceTest
启动音频采集设备测试。
Future<void> startRecordingDeviceTest(int indicationInterval);
详情
该方法用于测试本地音频采集设备是否能正常工作。调用该方法后，SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调，报告 uid = 0 及采集设备的音量信息。
该方法和 startEchoTest 的区别在于该方法检测本地的音频采集设备能否正常工作，后者可以检测音视频设备及网络是否正常。
参数
- indicationInterval
- SDK 触发 onAudioVolumeIndication 回调的时间间隔，单位为毫秒，最小取值为 10，否则会收不到 onAudioVolumeIndication 回调，SDK 会返回错误码
-2。声网推荐你将该值设为 100。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2: 参数设置错误，请重新设置参数。
stopAudioDeviceLoopbackTest
停止音频设备回路测试。
Future<void> stopAudioDeviceLoopbackTest();
详情
- 该方法仅适用于 Windows 和 macOS。
- 该方法在加入频道前后都可调用。
- 该方法仅支持主播角色调用。
- 在调用 startAudioDeviceLoopbackTest 后，必须调用该方法停止音频设备回路测试。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类stopRecordingDeviceTest
停止音频采集设备测试。
Future<void> stopRecordingDeviceTest();
详情
该方法用于停止音频采集设备测试。调用 startRecordingDeviceTest 后，必须调用该方法停止测试。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类stopPlaybackDeviceTest
停止音频播放设备测试。
Future<void> stopPlaybackDeviceTest();
详情
该方法用于停止音频播放设备测试。调用 startPlaybackDeviceTest 后，必须调用该方法停止测试。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类onAudioDeviceStateChanged
音频设备变化回调。
final void Function(String deviceId, MediaDeviceType deviceType,
MediaDeviceStateType deviceState)? onAudioDeviceStateChanged;
详情
提示系统音频设备状态发生改变，比如耳机被拔出。
参数
- deviceId
- 设备 ID。
- deviceType
- 设备类型定义。详见 MediaDeviceType。
- deviceState
- 设备状态，详见 MediaDeviceStateType。
onAudioDeviceVolumeChanged
音频设备或 App 的音量发生改变回调。
final void Function(MediaDeviceType deviceType, int volume, bool muted)?
onAudioDeviceVolumeChanged;
详情
当音频播放、采集设备或 App 的音量发生改变时，会触发该回调。
参数
- deviceType
- 设备类型定义。详见 MediaDeviceType。
- volume
- 音量。范围为 [0,255]。
- muted
- 音频设备是否为静音状态：
true: 音频设备已静音。false: 音频设备未被静音。