简介
DeviceStore 提供了一套全面的 API 来管理音视频设备，包括麦克风、摄像头和屏幕分享等功能。重要：
请使用 shared 单例获取
DeviceStore 实例。不要尝试直接初始化。说明：
设备状态更新通过 state 发布者传递。订阅它以接收有关麦克风、摄像头、网络等状态的实时更新。
功能特性
麦克风管理：打开/关闭麦克风，设置采集音量和输出音量。
摄像头管理：打开/关闭摄像头，切换前后摄像头，设置镜像和视频质量。
音频路由：切换扬声器和听筒。
网络状态：实时监控网络质量信息。
可订阅数据
DeviceState 的字段描述如下：
属性名 | 类型 | 描述 |
microphoneStatus | 麦克风状态。 | |
microphoneLastError | 麦克风错误，用于出现报错时提取错误信息。 | |
captureVolume | Int | 采集音量，取值范围0到100。 |
captureVolume | ValueListenable<int> | 采集音量，取值范围0到100。已废弃，请使用 microphoneVolume 代替。 |
currentMicVolume | Int | 当前用户实际输出音量。 |
currentMicVolume | ValueListenable<int> | 当前用户实际输出音量。已废弃，请使用 microphoneInputLevel 代替。 |
outputVolume | Int | 最大输出音量，取值范围0到100。 |
outputVolume | ValueListenable<int> | 最大输出音量，取值范围0到100。已废弃，请使用 speakerVolume 代替。 |
cameraStatus | 摄像头状态。 | |
cameraLastError | 摄像头错误，用于出现报错时提取错误信息。 | |
isFrontCamera | ValueListenable<bool> | 是否为前置摄像头。 |
localMirrorType | 镜像状态。 | |
localVideoQuality | 本地视频质量。 | |
currentAudioRoute | 当前音频路由位置。 | |
currentAudioRoute | 当前音频路由位置。已废弃，请使用 currentSpeaker 代替。 | |
screenStatus | 屏幕分享状态。 | |
screenStatus | 屏幕分享状态。已废弃，请使用 ScreenShareStore.state.screenStatus 代替。 | |
networkInfo | 网络信息。 | |
networkType | 当前网络类型。 | |
microphoneList | 当前麦克风设备列表。移动端不提供麦克风设备枚举，列表为空。
由引擎自动维护，系统设备列表发生变化时更新。 | |
currentMicrophone | 当前麦克风设备，deviceId 为空时表示未选择麦克风。 | |
microphoneVolume | ValueListenable<int> | 麦克风采集音量，取值范围0到100。 |
microphoneInputLevel | ValueListenable<int> | 用于展示麦克风音量条的实时电平值，范围0-100。
仅在麦克风测试进行中更新，参见 startMicrophoneTest。 |
cameraList | 摄像头设备列表。桌面端包含所有摄像头，移动端包含前置摄像头和后置摄像头。
由引擎自动维护，系统设备列表发生变化时更新。 | |
currentCamera | 当前摄像头设备，deviceId 为空时表示未选择摄像头。 | |
speakerList | 扬声器设备列表。桌面端包含所有扬声器，移动端包含扬声器和听筒。
由引擎自动维护，系统设备列表发生变化时更新。 | |
currentSpeaker | 当前扬声器设备，deviceId 为空时表示未选择扬声器。 | |
speakerVolume | ValueListenable<int> | 扬声器播放音量，取值范围0到100。 |
speakerOutputLevel | ValueListenable<int> | 扬声器实时输出电平值，范围0-100。
仅在扬声器测试进行中更新，参见 startSpeakerTest。 |
API 列表
函数名 | 描述 |
单例对象。 | |
打开本地麦克风。 | |
关闭本地麦克风。 | |
设置采集音量。 | |
设置输出音量。 | |
设置麦克风采集音量。 | |
设置扬声器播放音量。 | |
选择麦克风设备。 | |
开始麦克风测试。 | |
停止麦克风测试。 | |
选择扬声器设备。 | |
开始扬声器测试。 | |
停止扬声器测试。 | |
设置音频路由。 | |
开始摄像头测试。 | |
停止摄像头测试。 | |
打开本地摄像头。 | |
关闭本地摄像头。 | |
切换摄像头。 | |
选择摄像头设备。 | |
切换镜像状态。 | |
更新视频质量。 | |
设置采集音量，请使用 setMicrophoneVolume 代替。 | |
设置输出音量，请使用 setSpeakerVolume 代替。 | |
设置音频路由，请使用 setCurrentSpeaker 代替。 | |
切换摄像头，请使用 setCurrentCamera 代替。 | |
重置为默认状态。 |
获取实例
shared
单例对象。
麦克风操作
openLocalMicrophone
打开本地麦克风。
Future<CompletionHandler> openLocalMicrophone();
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
completion | CompletionClosure? | 操作是否成功。 |
closeLocalMicrophone
关闭本地麦克风。
void closeLocalMicrophone();
版本信息
从3.5版本开始支持。
setCaptureVolume
设置采集音量（已废弃，请使用 setMicrophoneVolume）。
警告：
已废弃：请使用 setMicrophoneVolume 代替。将在 5.5 版本中移除。
@Deprecated('Use setMicrophoneVolume instead. Will be removed in version 5.5.')void setCaptureVolume(int volume);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
volume | int | 采集音量，取值范围0到100。 |
setOutputVolume
设置最大输出音量（已废弃，请使用 setSpeakerVolume）。
警告：
已废弃：请使用 setSpeakerVolume 代替。将在 5.5 版本中移除。
@Deprecated('Use setSpeakerVolume instead. Will be removed in version 5.5.')void setOutputVolume(int volume);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
volume | int | 最大音量，取值范围0到100。 |
setMicrophoneVolume
设置麦克风采集音量。
void setMicrophoneVolume(int volume);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
volume | int | 采集音量，取值范围0到100。 |
setSpeakerVolume
设置扬声器播放音量。
void setSpeakerVolume(int volume);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
volume | int | 播放音量，取值范围0到100。 |
setCurrentMicrophone
设置当前麦克风设备
仅桌面端支持，移动端不允许切换麦克风设备，调用无效。仅在麦克风处于开启状态时生效。
void setCurrentMicrophone(DeviceInfo microphone);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
microphone | 麦克风设备，取 microphoneList 中的元素。 |
startMicrophoneTest
开始麦克风测试，采集电平实时回灌到 microphoneInputLevel，可传入采集间隔（毫秒）。
void startMicrophoneTest(int interval);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
interval | int | 采集间隔，单位毫秒，默认 200ms。 |
stopMicrophoneTest
停止麦克风测试。
void stopMicrophoneTest();
版本信息
从3.5版本开始支持。
扬声器操作
setCurrentSpeaker
设置当前扬声器设备。
void setCurrentSpeaker(DeviceInfo speaker);
全平台支持：桌面端可选中 speakerList 中的任意设备，移动端仅扬声器/听筒切换生效。
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
speaker | 扬声器设备，取 speakerList 中的元素。 |
startSpeakerTest
开始扬声器测试，播放电平实时回灌到 speakerOutputLevel
测试时会播放一段音频文件，用于确认当前使用的扬声器设备是否正确。
void startSpeakerTest(String filePath);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
filePath | String | 测试播放使用的音频文件路径，必填；为空时返回参数错误。 |
stopSpeakerTest
停止扬声器测试。
void stopSpeakerTest();
版本信息
从3.5版本开始支持。
音频路由
setAudioRoute
设置音频路由（已废弃，请使用 setCurrentSpeaker）。
警告：
已废弃：请使用 setCurrentSpeaker 代替。将在 5.5 版本中移除。
@Deprecated('Use setCurrentSpeaker instead. Will be removed in version 5.5.')void setAudioRoute(AudioRoute route);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
route | 路由位置。移动端 speakerList 中包含扬声器和听筒，可由 setCurrentSpeaker 覆盖该能力。 |
摄像头操作
startCameraTest
开始摄像头测试，如果摄像头打开成功，会将画面渲染到设置的 CameraView 上。
Future<CompletionHandler> startCameraTest(int cameraViewPtr);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
cameraViewPtr | int | 摄像头采集画面的渲染视图。 |
completion | CompletionClosure? | 操作是否成功。 |
stopCameraTest
停止摄像头测试。
void stopCameraTest();
版本信息
从3.5版本开始支持。
openLocalCamera
打开本地摄像头。
Future<CompletionHandler> openLocalCamera(bool isFront);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
isFront | bool | 是否前置摄像头。 |
completion | CompletionClosure? | 操作是否成功。 |
closeLocalCamera
关闭本地摄像头。
void closeLocalCamera();
版本信息
从3.5版本开始支持。
switchCamera
切换摄像头（已废弃，请使用 setCurrentCamera）。
警告：
已废弃：请使用 setCurrentCamera 代替。将在 5.5 版本中移除。
@Deprecated('Use setCurrentCamera instead. Will be removed in version 5.5.')void switchCamera(bool isFront);
移动端 cameraList 中包含前置摄像头和后置摄像头，因此 setCurrentCamera 可覆盖该能力。
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
isFront | bool | 是否前置摄像头。 |
setCurrentCamera
设置当前摄像头设备
全平台支持：桌面端可选中 cameraList 中的任意设备，移动端等价于切换前后摄像头。
仅在摄像头处于开启状态时生效。
void setCurrentCamera(DeviceInfo camera);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
camera | 摄像头设备，取 cameraList 中的元素。 |
switchMirror
切换镜像状态。
void switchMirror(MirrorType mirrorType);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
mirrorType | 镜像状态。 |
updateVideoQuality
更新视频质量。
void updateVideoQuality(VideoQuality quality, {VideoOrientation orientation = VideoOrientation.portrait});
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
quality | 视频质量。 | |
orientation | 视频方向。默认 portrait。传 landscape 使用基准（宽 × 高）分辨率。 |
已废弃
setCaptureVolume
设置采集音量（已废弃，请使用 setMicrophoneVolume）。
警告：
已废弃：请使用 setMicrophoneVolume 代替。将在 5.5 版本中移除。
@Deprecated('Use setMicrophoneVolume instead. Will be removed in version 5.5.')void setCaptureVolume(int volume);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
volume | int | 采集音量，取值范围0到100。 |
setOutputVolume
设置最大输出音量（已废弃，请使用 setSpeakerVolume）。
警告：
已废弃：请使用 setSpeakerVolume 代替。将在 5.5 版本中移除。
@Deprecated('Use setSpeakerVolume instead. Will be removed in version 5.5.')void setOutputVolume(int volume);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
volume | int | 最大音量，取值范围0到100。 |
setAudioRoute
设置音频路由（已废弃，请使用 setCurrentSpeaker）。
警告：
已废弃：请使用 setCurrentSpeaker 代替。将在 5.5 版本中移除。
@Deprecated('Use setCurrentSpeaker instead. Will be removed in version 5.5.')void setAudioRoute(AudioRoute route);
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
route | 路由位置。移动端 speakerList 中包含扬声器和听筒，可由 setCurrentSpeaker 覆盖该能力。 |
switchCamera
切换摄像头（已废弃，请使用 setCurrentCamera）。
警告：
已废弃：请使用 setCurrentCamera 代替。将在 5.5 版本中移除。
@Deprecated('Use setCurrentCamera instead. Will be removed in version 5.5.')void switchCamera(bool isFront);
移动端 cameraList 中包含前置摄像头和后置摄像头，因此 setCurrentCamera 可覆盖该能力。
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
isFront | bool | 是否前置摄像头。 |
重置
reset
重置为默认状态。
void reset();
版本信息
从3.5版本开始支持。
数据结构
DeviceType
设备类型。
枚举值 | 值 | 说明 |
microphone | 1 | 麦克风类型。 |
camera | 2 | 摄像头类型。 |
screenShare | 3 | 屏幕分享类型。 |
DeviceError
设备相关错误码。
枚举值 | 值 | 说明 |
noError | 0 | 操作成功。 |
noDeviceDetected | 1 | 未检测到设备。 |
noSystemPermission | 2 | 没有系统权限。 |
notSupportCapture | 3 | 不支持采集。 |
occupiedError | 4 | 设备已占用。 |
unknownError | 5 | 未知错误。 |
DeviceStatus
设备开启状态。
枚举值 | 值 | 说明 |
off | 0 | 关闭。 |
on | 1 | 开启。 |
AudioRoute
音频路由。已废弃，请使用 DeviceInfo 代替。
枚举值 | 值 | 说明 |
speakerphone | 0 | 扬声器，使用扬声器播放（即"免提"），扬声器位于手机底部，声音偏大，适合外放音乐。 |
earpiece | 1 | 听筒，使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。 |
VideoQuality
视频质量档位。最终编码分辨率由本档位与 VideoOrientation 共同决定：横屏保持基准分辨率（宽 × 高），竖屏宽高互换。
枚举值 | 值 | 说明 |
quality360P | 1 | 360P。横屏分辨率 640 × 360；竖屏（宽高互换）为 360 × 640。 |
quality540P | 2 | 540P。横屏分辨率 960 × 540；竖屏（宽高互换）为 540 × 960。 |
quality720P | 3 | 720P。横屏分辨率 1280 × 720；竖屏（宽高互换）为 720 × 1280。 |
quality1080P | 4 | 1080P。横屏分辨率 1920 × 1080；竖屏（宽高互换）为 1080 × 1920。 |
VideoOrientation
视频方向。与 VideoQuality 共同决定最终编码分辨率：横屏保持基准分辨率（宽 × 高），竖屏宽高互换。
枚举值 | 值 | 说明 |
landscape | 0 | 横屏，编码分辨率宽大于高（例如 1280 x 720）。 |
portrait | 1 | 竖屏，编码分辨率高大于宽（例如 720 x 1280）。 |
NetworkQuality
网络质量。
枚举值 | 值 | 说明 |
unknown | 0 | 未知网络。 |
excellent | 1 | 极佳。 |
good | 2 | 良好。 |
poor | 3 | 较差。 |
bad | 4 | 差。 |
veryBad | 5 | 极差。 |
down | 6 | 中断。 |
MirrorType
摄像头镜像状态。
枚举值 | 值 | 说明 |
auto | 0 | 自动，前置摄像头镜像，后置摄像头不镜像。 |
enable | 1 | 前后摄像头均镜像。 |
disable | 2 | 前后摄像头均不镜像。 |
NetworkType
网络类型。
枚举值 | 值 | 说明 |
unknown | 0 | 未知或未识别的网络类型。 |
wifi | 1 | WiFi 网络连接。 |
cellular | 2 | 蜂窝/移动数据网络连接。 |
DeviceInfo
设备信息。
属性 | 类型 | 说明 |
deviceId | String | 设备 ID。 |
deviceName | String | 设备名称。 |
NetworkInfo
网络信息。
属性 | 类型 | 说明 |
userID | String | 用户唯一 ID。 |
quality | 网络质量。 | |
upLoss | int | 上行丢包率，取值范围0到100。 |
downLoss | int | 下行丢包率，取值范围0到100。 |
delay | int | 延迟（单位：毫秒）。 |
DeviceState
设备状态。
属性 | 类型 | 说明 |
microphoneStatus | 麦克风状态。 | |
microphoneLastError | 麦克风错误，用于出现报错时提取错误信息。 | |
captureVolume | Int | 采集音量，取值范围0到100。 |
captureVolume | ValueListenable<int> | 采集音量，取值范围0到100。已废弃，请使用 microphoneVolume 代替。 |
currentMicVolume | Int | 当前用户实际输出音量。 |
currentMicVolume | ValueListenable<int> | 当前用户实际输出音量。已废弃，请使用 microphoneInputLevel 代替。 |
outputVolume | Int | 最大输出音量，取值范围0到100。 |
outputVolume | ValueListenable<int> | 最大输出音量，取值范围0到100。已废弃，请使用 speakerVolume 代替。 |
cameraStatus | 摄像头状态。 | |
cameraLastError | 摄像头错误，用于出现报错时提取错误信息。 | |
isFrontCamera | ValueListenable<bool> | 是否为前置摄像头。 |
localMirrorType | 镜像状态。 | |
localVideoQuality | 本地视频质量。 | |
currentAudioRoute | 当前音频路由位置。 | |
currentAudioRoute | 当前音频路由位置。已废弃，请使用 currentSpeaker 代替。 | |
screenStatus | 屏幕分享状态。 | |
screenStatus | 屏幕分享状态。已废弃，请使用 ScreenShareStore.state.screenStatus 代替。 | |
networkInfo | 网络信息。 | |
networkType | 当前网络类型。 | |
microphoneList | 当前麦克风设备列表。移动端不提供麦克风设备枚举，列表为空。
由引擎自动维护，系统设备列表发生变化时更新。 | |
currentMicrophone | 当前麦克风设备，deviceId 为空时表示未选择麦克风。 | |
microphoneVolume | ValueListenable<int> | 麦克风采集音量，取值范围0到100。 |
microphoneInputLevel | ValueListenable<int> | 用于展示麦克风音量条的实时电平值，范围0-100。
仅在麦克风测试进行中更新，参见 startMicrophoneTest。 |
cameraList | 摄像头设备列表。桌面端包含所有摄像头，移动端包含前置摄像头和后置摄像头。
由引擎自动维护，系统设备列表发生变化时更新。 | |
currentCamera | 当前摄像头设备，deviceId 为空时表示未选择摄像头。 | |
speakerList | 扬声器设备列表。桌面端包含所有扬声器，移动端包含扬声器和听筒。
由引擎自动维护，系统设备列表发生变化时更新。 | |
currentSpeaker | 当前扬声器设备，deviceId 为空时表示未选择扬声器。 | |
speakerVolume | ValueListenable<int> | 扬声器播放音量，取值范围0到100。 |
speakerOutputLevel | ValueListenable<int> | 扬声器实时输出电平值，范围0-100。
仅在扬声器测试进行中更新，参见 startSpeakerTest。 |
使用示例
// 获取单例实例let store = DeviceStore.shared// 订阅状态变化store.state.subscribe { state inprint("麦克风状态: \\(state.microphoneStatus)")print("摄像头状态: \\(state.cameraStatus)")print("网络质量: \\(state.networkInfo.quality)")}// 打开麦克风store.openLocalMicrophone { code, message inif code == 0 {print("麦克风打开成功")}}// 打开前置摄像头store.openLocalCamera(isFront: true) { code, message inif code == 0 {print("摄像头打开成功")}}
