Skip to content
GitHub
Specification version v0.1

uvc

tested on simulator

Tier Tier 1
Protocol USB Video Class 1.1 and 1.5 through V4L2, AVFoundation, Media Foundation or DirectShow
Covers USB webcams, USB microscopes, HDMI to USB capture cards, document cameras
Hazard default low
Conformance core
Tested with fake cv2.VideoCapture with a simulated camera, real cv2 JPEG encoding

Estimated reach. Thousands of models. UVC is the class every mainstream USB webcam, microscope camera and capture card implements so that it works without a vendor driver, and the Linux UVC driver alone lists hundreds of tested models. The driver only captures frames, so it works with any of them the operating system can open. Cameras that need a vendor SDK, such as many machine vision cameras, are not covered.

The uvc driver captures JPEG frames from USB webcams and other cameras the operating system can open, through OpenCV opencv-python-headless on V4L2, AVFoundation, Media Foundation or DirectShow. The driver is read-only and never changes exposure, focus or any other camera control.

Supports

  • image reads, one fresh JPEG frame each.
  • Number reads of the capture properties width, height, fps, brightness, contrast, saturation, hue, gain, exposure and focus, as reported by the camera.
  • discover() on Linux lists capture devices from sysfs without opening any.

Setup

uv tool install --compile-bytecode "halkit[uvc] @ git+https://github.com/sohan-bhat/OpenHAL"

The 35 MB wheel bundles OpenCV and codecs. On Linux, join the video group. On macOS, grant camera permission the first time the app running the hub opens a camera.

ParameterDefaultMeaning
nameautoauto for the first camera, an index such as 1, or a path such as /dev/video2. uvc: auto is shorthand
width, heightthe camera's defaultRequested frame size
fpsthe camera's defaultRequested frame rate
jpeg_quality851 to 100
backendanyany, v4l2, avfoundation, dshow, msmf or gstreamer
flush_frames1Frames dropped before each capture, so reads never return an old buffer
timeout5 sOpen and capture deadline

Cameras use the nearest supported mode, which the width, height and fps properties report.

Channels

read:
  frame: { type: image }
  frame_width: { unit: dimensionless, map: { property: width } }
  fps: { unit: Hz, map: { property: fps } }

Number channels need map: { property: <name> }. The hub skips image channels in the connect snapshot, so frames are captured only on request.

Example

openhal/drivers/uvc/examples/bench-webcam.hal.yaml captures 1280x720 frames from the first webcam.

Errors and health

  • A camera that won't open, because the camera is missing, busy or lacks permission, raises DriverError.
  • A capture with no frame raises DriverError and marks the camera failed, so the hub reopens the camera after the next heartbeat.
  • No frame within timeout raises TimeoutError.
  • health() grabs one frame and reports disconnected without one.

Limitations

  • No camera controls such as exposure, focus, zoom or pan.
  • Single frames on request only, with no video streams or recording.
  • discover() works only on Linux. Elsewhere cameras open by index.
  • Indexes can change with plug order, but /dev/v4l/by-id/... paths on Linux are stable.

Hazard default and safe state

Low with no write channels, so safe_state_support is none. Frames can show people and private spaces, so point cameras with care and tell people the cameras are there.

Sources

OpenHAL is an open protocol, released under Apache 2.0.

OpenHAL is not affiliated with Anthropic or MHS.

Source on GitHub

Specification v0.1