设备接入

设备接入由开放平台 API Key 的 deviceScope 和本地 SDK runtime 的设备 provider 共同决定。

设备范围

deviceScope 是 API Key 的设备白名单，元素格式为：

[
  { "vid": 4660, "pid": 22136 }
]

如果未配置 deviceScope，或 deviceScope 为空数组，表示不限制设备范围；runtime 不会按 VID/PID 过滤设备。

当 deviceScope 非空时，本地 runtime 在 device.list 和 device.get 中会按当前会话的 auth_context.device_scope 过滤设备。设备不在范围内时会返回 1105 DEVICE_NOT_IN_AUTH_SCOPE。

本地接入流程

1. 启动 SDK runtime。
2. 建立 Command WS。
3. 调用 auth.create_session 绑定 API Key。
4. 调用 device.list 查看授权范围内设备。
5. 调用 device.get 读取分辨率。
6. 调用 device.open 打开设备。
7. 调用 video.start 创建视频流，或调用 capture.take 拍摄。
8. 结束时调用 device.close，它会自动停止当前连接下该设备的视频流。

分辨率与像素格式

device.get 返回 resolutions，每项包含 width、height、real_width、real_height、fps、pixel_format 和 is_default。当前 Video WS 二进制帧按 pixel_format=mjpeg 处理；客户端应把每个二进制帧与前一个 stream.frame_meta 文本事件配对，将二进制载荷按 JPEG/MJPEG 图像解码后绘制到 Canvas。

常见问题

问题	处理方式
device.list 为空	检查设备连接、provider 是否就绪；如果配置了 deviceScope，再确认是否包含该设备 VID/PID。
device.open 返回设备不在授权范围	在控制台重新签发或轮换包含正确 VID/PID 的 API Key。
切换分辨率失败	先停止视频流，或使用 video.set_format 更新当前 stream 格式。
页面退出后设备占用	调用 device.close 或断开 Command WS；runtime 会在连接关闭时清理该连接打开的设备。