通用设备管理

enumerateDevices:

获取系统中所有的音视频设备。

Objective-C

- (NSArray<AgoraRtcDeviceInfo *> * _Nullable)enumerateDevices:(AgoraMediaDeviceType)type;

详情

该方法返回一个 NSArray 对象，包含系统中所有的音视频设备。应用程序可以通过 AgoraRtcDeviceInfo NSArray 对象枚举设备。

注意

不要在主线程调用该方法。

参数

type

设备的类型，包括音、视频采集或播放设备，详见 AgoraMediaDeviceType。

返回值

调用成功时，返回 AgoraRtcDeviceInfo NSArray 对象，包含所有的音视频设备。

所属接口类

• AgoraRtcEngineKit

followSystemPlaybackDevice:

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

Objective-C

(int) followSystemPlaybackDevice:(BOOL)enable;

参数

enable

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

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

返回值

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

所属接口类

• AgoraRtcEngineKit

followSystemRecordingDevice:

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

Objective-C

(int) followSystemRecordingDevice:(BOOL)enable;

参数

enable

是否跟随系统默认的音频采集设备：

• YES：跟随。当系统默认的音频采集设备改变时，SDK 立即切换音频采集设备。
• NO：不跟随。只有当 SDK 使用的音频采集设备被移除后，SDK 才切换至系统默认的音频采集设备。

返回值

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

所属接口类

• AgoraRtcEngineKit

getDefaultAudioDevice:

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

Objective-C

- (AgoraRtcDeviceInfo* _Nullable)getDefaultAudioDevice:(AgoraMediaDeviceType)type;

参数

type

输出参数，设备的类型，详见 AgoraMediaDeviceType。

返回值

• 调用成功时，返回 AgoraRtcDeviceInfo 对象，包含默认的音频设备信息。
• 调用失败时，返回 nil。

所属接口类

• AgoraRtcEngineKit

getDeviceInfo:

获取当前设备名称。

Objective-C

- (AgoraRtcDeviceInfo * _Nullable)getDeviceInfo:(AgoraMediaDeviceType)type;

详情

该方法通过 type 参数获取当前音、视频采集或播放设备。

参数

type

设备的类型，包括音、视频采集或播放设备，详见 AgoraMediaDeviceType。

返回值

• 调用成功时，返回 AgoraRtcDeviceInfo
• 调用失败时，返回 nil

所属接口类

• AgoraRtcEngineKit

getDeviceVolume:

获取当前设备的音量。

Objective-C

- (int)getDeviceVolume:(AgoraMediaDeviceType)type;

参数

type

设备的类型，包括音、视频采集或播放设备，详见 AgoraMediaDeviceType。

返回值

• 调用成功，返回设备的音量
• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

monitorDeviceChange:

监测设备变化。

Objective-C

- (void)monitorDeviceChange:(BOOL)enabled;

详情

该方法用来开启设备插拔监测，这里设备指的是音视频外接设备，比如外接摄像头等。

参数

enabled

是否开启监测:

• YES: 开启。
• NO: 关闭。

所属接口类

• AgoraRtcEngineKit

setCameraCapturerConfiguration

设置摄像头采集配置。

Objective-C

- (int)setCameraCapturerConfiguration:(AgoraCameraCapturerConfiguration * _Nullable)config;

调用时机

该方法必须在开启本地摄像头采集前调用，如 startPreview: 和 joinChannelByToken:channelId:uid:mediaOptions:joinSuccess: 前调用。

调用限制

无。

参数

config

摄像头采集配置，详见 AgoraCameraCapturerConfiguration。

返回值

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

所属接口类

• AgoraRtcEngineKit

setDevice:deviceId:

指定设备。

Objective-C

- (int)setDevice:(AgoraMediaDeviceType)type deviceId:(NSString * _Nonnull)deviceId;

参数

type

设备的类型，包括音、视频采集或播放设备，详见 AgoraMediaDeviceType。

deviceId

设备 ID。可通过 enumerateDevices: 获取。插拔设备不会影响 deviceId。

返回值

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

所属接口类

• AgoraRtcEngineKit

setDeviceVolume:volume:

设置设备音量。

Objective-C

- (int)setDeviceVolume:(AgoraMediaDeviceType)type volume:(int)volume;

详情

设置音、视频采集或播放设备的音量。

注意

该方法需要在加入频道后调用。

参数

type

设备的类型，包括音、视频采集或播放设备，详见 AgoraMediaDeviceType。

volume

设备音量。取值范围 [0,255]。0 表示无声，255 表示最大音量。

返回值

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

所属接口类

• AgoraRtcEngineKit

startAudioDeviceLoopbackTest:

开始音频设备回路测试。

Objective-C

-(int)startAudioDeviceLoopbackTest:(int)indicationInterval;

详情

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

注意

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

参数

indicationInterval

SDK 触发 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调的时间间隔，单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒，否则会收不到 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调。

返回值

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

所属接口类

• AgoraRtcEngineKit

startPlaybackDeviceTest:

启动音频播放设备测试。

Objective-C

- (int)startPlaybackDeviceTest:(NSString * _Nonnull)audioFileName;

详情

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

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

该方法和 startEchoTestWithConfig: 的区别在于该方法检测本地的音频播放设备能否正常工作，后者可以检测音视频设备及网络是否正常。

注意

该方法需要在加入频道前调用。测试完成后，如需加入频道，请确保先调用 stopPlaybackDeviceTest 停止设备测试。

参数

audioFileName

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

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

返回值

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

所属接口类

• AgoraRtcEngineKit

startRecordingDeviceTest:

启动音频采集设备测试。

Objective-C

- (int)startRecordingDeviceTest:(int)indicationInterval;

详情

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

该方法和 startEchoTestWithConfig: 的区别在于该方法检测本地的音频采集设备能否正常工作，后者可以检测音视频设备及网络是否正常。

信息

该方法需要在加入频道前调用。测试完成后，如需加入频道，请确保先调用 stopRecordingDeviceTest 停止设备测试。

参数

indicationInterval

SDK 触发 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调的时间间隔，单位为毫秒，最小取值为 10，否则会收不到 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调，SDK 会返回错误码 -2。声网推荐你将该值设为 100。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -2: 参数设置错误，请重新设置参数。

所属接口类

• AgoraRtcEngineKit

rtcEngine:device:type:stateChanged:

设备状态改变回调。

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine device:(NSString* _Nonnull)deviceId
    type:(AgoraMediaDeviceType)deviceType
    stateChanged:(NSInteger)state;

参数

engine

AgoraRtcEngineKit 对象。

deviceId

设备 ID。

deviceType

设备的类型，包括音、视频采集或播放设备，详见 AgoraMediaDeviceType。

state

设备状态：

• 0：设备就绪。
• 8：设备被拔出。

所属接口类

• AgoraRtcEngineDelegate

stopAudioDeviceLoopbackTest

停止音频设备回路测试。

Objective-C

-(int)stopAudioDeviceLoopbackTest;

详情

注意

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

返回值

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

所属接口类

• AgoraRtcEngineKit

stopPlaybackDeviceTest

停止音频播放设备测试。

Objective-C

- (int)stopPlaybackDeviceTest;

详情

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

注意

该方法需要在加入频道前调用。

返回值

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

所属接口类

• AgoraRtcEngineKit

stopRecordingDeviceTest

停止音频采集设备测试。

Objective-C

- (int)stopRecordingDeviceTest;

详情

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

信息

该方法需要在加入频道前调用。

返回值

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

所属接口类

• AgoraRtcEngineKit