Device API

Device APIs require a session and matching capability on the current connection. device.list and device.get are filtered by auth_context.device_scope.

DeviceDescriptor

Field	Type	Notes
device_id	string	Device ID.
model	string	Device model.
display_name	string	Display name.
vid	number	USB vendor ID.
pid	number	USB product ID.
status	string	Device status.
authorized	boolean	Whether the device is in current auth scope.
supports_video	boolean	Whether video preview is supported.
features.image_transfer_protocol	boolean	Whether image transfer protocol is supported.
resolutions[]	array	Resolution list.

Resolution

Field	Type	Notes
width	number	Preview width.
height	number	Preview height.
real_width	number	Actual device output width.
real_height	number	Actual device output height.
fps	number	Frame rate.
pixel_format	string	Video frame format. Supports mjpeg, jpeg, and bgr24; jpeg is handled as mjpeg.
is_default	boolean	Whether this is the default resolution.

CaptureOutputCapabilities

device.open responses may additionally include capture_output, which describes the capture output size buckets supported by the opened device. Clients should use device.open.data.capture_output.target_sizes as the source of valid profile.output.target_size values.

Field	Type	Notes
target_size_supported	boolean	Whether the current device supports target output size buckets.
target_sizes[]	array	Available target output size buckets.

OutputTargetSizeOption

Field	Type	Notes
target_size	number	Target size bucket value to pass as profile.output.target_size.
width	number	Target width for this bucket.
height	number	Target height for this bucket.
is_device_default	boolean	Optional. Whether this is the device default bucket.

Methods

Method	Parameters	Response data	Notes
device.list	none	devices: DeviceDescriptor[], count: number	Lists devices visible to current session.
device.get	device_id: string required	DeviceDescriptor + provider: string	Gets one device.
device.open	device_id: string required, width?: number, height?: number, fps?: number, pixel_format?: string=mjpeg; supports mjpeg, jpeg, and bgr24	DeviceDescriptor + opened: boolean, provider, optional capture_output	Opens a device.
device.close	device_id: string required	device_id, closed, was_opened, stopped_stream, stream_id, provider	Closes a device and stops the active stream for that device on the current connection.

device.list and device.get do not guarantee capture_output. If you need to set the capture output size, call device.open first and choose a supported target_size from the opened-device response.

Device Events

When a device is removed, Command WS pushes device.removed to related connections. The event is sent to connections that opened the device or still own a video stream for it; the runtime also clears the related device and video state.

Event	Payload	Notes
device.removed	device_id, reason, was_opened, was_streaming, ts_ms	The device was removed.

After receiving this event, clients should stop the preview UI, clear the current device selection, and call device.list again to refresh available devices.

{
  "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
}

Example

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

Successful response example:

{
  "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
}