Video API
Video Methods
| Method | Parameters | Response data | Notes |
|---|---|---|---|
video.start | device_id: string required, width?: number, height?: number, fps?: number, pixel_format?: string=mjpeg, profile?: CaptureProfile | device_id, stream_id, session_token, pixel_format, width, height, fps | Creates a video stream. |
video.stop | device_id: string required | device_id, stream_id, stopped: true | Stops the stream for the device on the current connection. |
video.set_format | device_id: string required, pixel_format?: string=mjpeg, width?: number=1280, height?: number=720, fps?: number=15 | device_id, stream_id, pixel_format, width, height, fps | Updates current stream format. |
video.set_profile | device_id: string required, profile: CaptureProfile required; profile.output may include quality and target_size | device_id, page_processing, single_page, applied | Updates realtime processing profile and caches output options for later capture tasks. |
pixel_format supports mjpeg, jpeg, and bgr24; jpeg is normalized to mjpeg. When video.start omits width, height, or fps, the stream is registered with 1280*720, and 15fps respectively. The final response reflects the format and resolution actually selected by the provider.
CaptureProfile Effects on Video
video.start may apply profile when creating the stream. video.set_profile may update the realtime processing profile after the stream has started. See Capture API / CaptureProfile for the complete CaptureProfile structure.
The video stream currently uses these CaptureProfile fields:
| Field | Notes |
|---|---|
capture.page_processing | Realtime single-page recognition logic is enabled only when the value is single_page. |
capture.single_page.realtime_detect_rects | Whether realtime detection boxes are enabled. When enabled, stream.frame_meta may include detected_rects and detected_rects_source. |
capture.single_page.multi_target_paging | Takes effect only when realtime detection boxes are enabled, and allows multiple target boxes to be returned. |
output.quality | Cached as the JPG/JPEG output quality for later capture.take or device hard-grab tasks. It does not affect the current Video WS frame quality. |
output.target_size | Cached as the target output size for later capture.take or device hard-grab tasks. It does not affect the current Video WS frame resolution. |
video.set_profile requires the video stream for the device to already be running; otherwise a stream-not-ready error is returned. Video stream resolution is still controlled by video.set_format. To set output.target_size, first read device.open.data.capture_output.target_sizes, then write the selected bucket to profile.output.target_size. Page-turn auto detection does not currently have a public CaptureProfile parameter and is not documented as a supported video capability.
Video WS Frame Events
For client-side pairing of stream.frame_meta with binary frames and rendering them in the UI, see Device and Video / Render Video Frames.
Default external SDK Video WSS URL:
wss://sdk-runtime.localhost:18091?session_token=<session_token>&stream_id=<stream_id>For a custom TLS deployment, use a certificate-matching wss://<tls-host>:18091; the session_token and stream_id query parameters are required.
Each frame sends a stream.frame_meta text event first, then a binary frame. The binary frame format is determined by the current pixel_format: mjpeg/jpeg outputs JPEG-encoded frames, while bgr24 outputs raw BGR24 frames.
payload fields: device_id, stream_id, frame_seq, timestamp_ms, width, height, pixel_format, and optional detected_rects and detected_rects_source.