音频设备管理
介绍跟音频设备管理相关的方法和回调。
EnumeratePlaybackDevices
获取系统中所有的播放设备列表。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
UIAudioDeviceCollection* EnumeratePlaybackDevices();
详情
该方法返回一个 IAudioDeviceCollection 对象,包含系统中所有的播放设备。通过 IAudioDeviceCollection 对象,App 可以枚举播放设备。在使用结束后,App 需调用 Release 方法销毁返回的对象。
返回值
- 方法调用成功:返回一个 IAudioDeviceCollection 对象,包含所有的音频播放设备。
- 方法调用失败: NULL。
EnumerateRecordingDevices
获取系统中所有的音频采集设备列表。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
UIAudioDeviceCollection* EnumerateRecordingDevices();
详情
该方法返回一个 IAudioDeviceCollection 对象,包含系统中所有的音频采集设备。通过 IAudioDeviceCollection 对象,App 可以枚举音频采集设备。在使用结束后,App 需调用 Release 方法销毁返回的对象。
返回值
- 方法调用成功:返回一个 IAudioDeviceCollection 对象,包含所有的音频采集设备。
- 方法调用失败: NULL。
FollowSystemPlaybackDevice
设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int FollowSystemPlaybackDevice(bool enable);
详情
参数
- enable
- 是否跟随系统默认的音频播放设备:
true
:跟随。当系统默认音频播放设备发生改变时,SDK 立即切换音频播放设备。false
:不跟随。只有当 SDK 使用的音频播放设备被移除后,SDK 才切换至系统默认的音频播放设备。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
FollowSystemRecordingDevice
设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int FollowSystemRecordingDevice(bool enable);
详情
参数
- enable
- 是否跟随系统默认的音频采集设备:
true
:跟随。当系统默认的音频采集设备改变时,SDK 立即切换音频采集设备。false
:不跟随。只有当 SDK 使用的音频采集设备被移除后,SDK 才切换至系统默认的音频采集设备。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
GetApplicationVolume
GetAudioDeviceInfo
获取音频设备信息。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int GetAudioDeviceInfo(FDeviceInfo& deviceInfo);
详情
调用该方法后,你可以获取音频设备是否支持极低延时采集和播放。
- 该方法仅适用于 Android 平台。
- 该方法在加入频道前后均可调用。
参数
- deviceInfo
- 输入和输出参数。标识音频设备信息的 FDeviceInfo 对象。
- 输入值:一个 FDeviceInfo 对象。
- 输出值:一个包含了音频设备信息的 FDeviceInfo 对象。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。详见错误码了解详情和解决建议。
GetCount
获取播放或音频采集设备数量。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceCollection")
int GetCount();
详情
如果先调用 EnumeratePlaybackDevices 再调用该方法,返回播放设备的数量。如果先调用 EnumerateRecordingDevices 再调用该方法,则返回音频采集设备的数量。
返回值
语音设备数目。
所属接口类GetDefaultDevice
获取系统默认的音频设备。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceCollection")
int GetDefaultDevice(FString& deviceName, FString& deviceId);
详情
- 该方法仅适用于 Windows 和 macOS。
- 你需要先调用 EnumeratePlaybackDevices 或 EnumerateRecordingDevices 获取设备列表后,再调用该方法。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见 错误码了解详情和解决建议。
GetDevice
GetPlaybackDevice
GetPlaybackDeviceInfo
GetPlaybackDeviceMute
GetRecordingDevice
GetRecordingDeviceInfo
IsApplicationMute
Release
释放 IAudioDeviceCollection
对象占用的所有资源。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceCollection")
void Release();
Release
释放 IAudioDeviceManager 对象占用的所有资源。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
void Release();
SetApplicationMute
SetApplicationVolume
SetDevice
指定音频设备。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceCollection")
int SetDevice(FString deviceId);
详情
该方法可以更改当前的音频路由,但不会改变系统默认的音频路由。假设系统默认的音频路由是扬声器 1,你在加入频道前调用该方法设置当前的音频路由为扬声器 2,如果在此时进行设备检测,SDK 会对扬声器 2 进行检测。检测结束后,当你加入频道时 SDK 依然会选择使用系统默认的音频路由,即扬声器 1。
参数
- deviceId
- 设备 ID。最大长度为 512 字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetPlaybackDevice
指定播放设备。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int SetPlaybackDevice(FString deviceId);
详情
该方法可以更改当前的音频路由,但不会改变系统默认的音频路由。假设系统默认的音频路由是扬声器 1,你在加入频道前调用该方法设置当前的音频路由为扬声器 2,如果在此时进行设备检测,SDK 会对扬声器 2 进行检测。检测结束后,当你加入频道时 SDK 依然会选择使用系统默认的音频路由,即扬声器 1。
参数
- deviceId
指定播放设备。由 EnumeratePlaybackDevices 获取。插拔设备不会影响 deviceId。
最大长度为 512 字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetPlaybackDeviceMute
StartPlaybackDeviceTest
启动音频播放设备测试。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int StartPlaybackDeviceTest(FString testAudioFilePath);
详情
该方法测试音频播放设备是否能正常工作。启动测试后,SDK 播放指定的音频文件,测试者如果能听到声音,说明播放设备能正常工作。
调用该方法后,SDK 会每隔 100 ms 触发一次 FOnAudioVolumeIndication 回调,报告 uid = 1 及播放设备的音量信息。
- 该方法需要在加入频道前调用。
- 该方法仅适用于 Windows 和 macOS。
参数
- testAudioFilePath
- 音频文件的绝对路径,路径字符串使用 UTF-8 编码格式。
- 支持文件格式: wav、mp3、m4a、aac。
- 支持文件采样率: 8000、16000、32000、44100、48000。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetRecordingDevice
指定音频采集设备。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int SetRecordingDevice(FString deviceId);
详情
该方法可以更改当前的音频采集设备,但不改变系统默认的音频采集设备。假设系统默认的音频采集设备是麦克风 1,你在加入频道前调用该方法设置当前的音频路由为蓝牙耳机 1,如果在此时进行设备检测,SDK 会对蓝牙耳机 1 进行检测。检测结束后,当你加入频道时 SDK 依然会选择使用系统默认的音频采集设备,即麦克风 1。
参数
- deviceId
音频采集设备的 Device ID。可通过 EnumerateRecordingDevices 获取。插拔设备不会影响 deviceId。
最大长度为 512 字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetRecordingDeviceVolume
StartAudioDeviceLoopbackTest
开始音频设备回路测试。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int StartAudioDeviceLoopbackTest(int indicationInterval);
详情
该方法测试音频采集和播放设备是否能正常工作。一旦测试开始,音频采集设备会采集本地音频,然后使用音频播放设备播放出来。SDK 会按设置的时间间隔触发两个 FOnAudioVolumeIndication 回调,分别报告音频采集设备(uid = 0)和音频播放设置(uid = 1)的音量信息。
- 该方法仅适用于 Windows 和 macOS。
- 该方法在加入频道前后都可调用。
- 该方法仅支持主播角色调用。
- 该方法仅在本地进行音频设备测试,不涉及网络连接。
- 完成测试后,必须调用 StopAudioDeviceLoopbackTest 停止音频设备回路测试。
参数
- indicationInterval
- SDK 触发 FOnAudioVolumeIndication 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒,否则会收不到 FOnAudioVolumeIndication 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
StartRecordingDeviceTest
启动音频采集设备测试。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int StartRecordingDeviceTest(int indicationInterval);
详情
该方法测试音频采集设备是否能正常工作。调用该方法后,SDK 会按设置的时间间隔触发 FOnAudioVolumeIndication 回调,报告 uid = 0 及采集设备的音量信息。
- 该方法仅适用于 Windows 和 macOS。
- 该方法需要在加入频道前调用。
参数
- indicationInterval
- SDK 触发 FOnAudioVolumeIndication 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。不得小于 10 毫秒,否则会收不到 FOnAudioVolumeIndication 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
StopAudioDeviceLoopbackTest
停止音频设备回路测试。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int StopAudioDeviceLoopbackTest();
详情
- 该方法仅适用于 Windows 和 macOS。
- 该方法在加入频道前后都可调用。
- 该方法仅支持主播角色调用。
- 在调用 StartAudioDeviceLoopbackTest 后,必须调用该方法停止音频设备回路测试。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
StopRecordingDeviceTest
停止音频采集设备测试。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int StopRecordingDeviceTest();
详情
该方法停止音频采集设备测试。调用 StartRecordingDeviceTest 后,必须调用该方法停止测试。
- 该方法仅适用于 Windows 和 macOS。
- 该方法需要在加入频道前调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
StopPlaybackDeviceTest
停止音频播放设备测试。
UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
int StopPlaybackDeviceTest();
详情
该方法停止音频播放设备测试。调用 StartPlaybackDeviceTest 后,必须调用该方法停止测试。
- 该方法仅适用于 Windows 和 macOS。
- 该方法需要在加入频道前调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
FOnAudioDeviceStateChanged
音频设备变化回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(FOnAudioDeviceStateChanged, FString, deviceId, int, deviceType, int, deviceState);
详情
提示系统音频设备状态发生改变,比如耳机被拔出。
参数
- deviceId
- 设备 ID。
- deviceType
- 设备类型定义。详见 EENUMCUSTOM_MEDIA_DEVICE_TYPE。
- deviceState
- 设备状态,详见 MEDIA_DEVICE_STATE_TYPE。
FOnAudioDeviceVolumeChanged
音频设备或 App 的音量发生改变回调。
DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(FOnAudioDeviceVolumeChanged, FENUMWRAP_MEDIA_DEVICE_TYPE, deviceType, int, volume, bool, muted);
详情
当音频播放、采集设备或 App 的音量发生改变时,会触发该回调。
参数
- deviceType
- 设备类型定义。详见 EENUMCUSTOM_MEDIA_DEVICE_TYPE。
- volume
- 音量。范围为 [0,255]。
- muted
- 音频设备是否为静音状态:
true
: 音频设备已静音。false
: 音频设备未被静音。