设备接口

设备接口要求当前连接已有 session，并拥有对应 capability。device.list 和 device.get 会按 auth_context.device_scope 过滤设备。

DeviceDescriptor

字段	类型	说明
device_id	string	设备 ID。
model	string	设备型号。
display_name	string	展示名称。
vid	number	USB vendor ID。
pid	number	USB product ID。
status	string	设备状态。
authorized	boolean	是否在当前授权范围内。
supports_video	boolean	是否支持视频预览。
features.image_transfer_protocol	boolean	是否支持图片传输协议。
resolutions[]	array	分辨率列表。

Resolution

字段	类型	说明
width	number	预览宽度。
height	number	预览高度。
real_width	number	设备真实输出宽度。
real_height	number	设备真实输出高度。
fps	number	帧率。
pixel_format	string	视频帧格式，支持 mjpeg、jpeg、bgr24；jpeg 会按 mjpeg 处理。
is_default	boolean	是否默认分辨率。

CaptureOutputCapabilities

device.open 响应可能额外返回 capture_output，用于描述当前打开设备支持的采集输出尺寸档位。客户端应以 device.open.data.capture_output.target_sizes 作为 profile.output.target_size 的可选值来源。

字段	类型	说明
target_size_supported	boolean	当前设备是否支持目标输出尺寸档位。
target_sizes[]	array	可选目标输出尺寸档位列表。

OutputTargetSizeOption

字段	类型	说明
target_size	number	目标尺寸档位值，传给 profile.output.target_size。
width	number	该档位对应的目标宽度。
height	number	该档位对应的目标高度。
is_device_default	boolean	可选。是否为设备默认档位。

方法

方法	参数	响应 data	说明
device.list	无	devices: DeviceDescriptor[]，count: number	获取当前会话可见设备。
device.get	device_id: string 必填	DeviceDescriptor + provider: string	获取单个设备详情。
device.open	device_id: string 必填，width?: number，height?: number，fps?: number，pixel_format?: string=mjpeg，支持 mjpeg、jpeg、bgr24	DeviceDescriptor + opened: boolean，provider，可选 capture_output	打开设备。
device.close	device_id: string 必填	device_id，closed，was_opened，stopped_stream，stream_id，provider	关闭设备，并自动停止当前连接下该设备的视频流。

device.list 和 device.get 不保证返回 capture_output；需要设置采集输出尺寸时，建议先调用 device.open，再从打开设备的响应中选择支持的 target_size。

设备事件

设备被移除时，Command WS 会向相关连接推送 device.removed。该事件会发送给已打开该设备或仍持有该设备视频流的连接；运行时会同步清理对应设备和视频状态。

事件	payload	说明
device.removed	device_id，reason，was_opened，was_streaming，ts_ms	设备已移除。

收到该事件后，客户端应停止预览 UI、清理当前设备选择，并重新调用 device.list 刷新设备列表。

{
  "event": "device.removed",
  "code": 0,
  "message": "ok",
  "payload": {
    "device_id": "mock-device-01",
    "reason": "hotplug_removed",
    "was_opened": true,
    "was_streaming": true,
    "ts_ms": 1710000000000
  },
  "ts": 1710000000
}

示例

{
  "request_id": "req-device-open-001",
  "method": "device.open",
  "params": {
    "device_id": "mock-device-01",
    "width": 1280,
    "height": 720,
    "fps": 15,
    "pixel_format": "mjpeg"
  }
}

成功响应示例：

{
  "request_id": "req-device-open-001",
  "code": 0,
  "message": "ok",
  "data": {
    "device_id": "mock-device-01",
    "model": "CZUR Mock",
    "display_name": "CZUR Mock Device",
    "vid": 7759,
    "pid": 10243,
    "status": "online",
    "authorized": true,
    "supports_video": true,
    "features": {
      "image_transfer_protocol": false
    },
    "resolutions": [],
    "opened": true,
    "provider": "czur-device-provider",
    "capture_output": {
      "target_size_supported": true,
      "target_sizes": [
        {
          "target_size": 500,
          "width": 2592,
          "height": 1944
        },
        {
          "target_size": 1600,
          "width": 4608,
          "height": 3456,
          "is_device_default": true
        }
      ]
    }
  },
  "ts": 1710000000
}