Skip to content
GitHub

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 frames from USB webcams and other cameras the operating system can open, and returns them as JPEG bytes. The driver uses OpenCV (opencv-python-headless), which talks to V4L2 on Linux, AVFoundation on macOS and Media Foundation or DirectShow on Windows. The driver is read-only and never changes exposure, focus or any other camera control.

What it supports

  • image read channels, returning one fresh JPEG frame per read.
  • Number read channels for capture properties (width, height, fps, brightness, contrast, saturation, hue, gain, exposure, focus), as the camera reports them.
  • A requested resolution and frame rate when the camera opens.
  • discover() on Linux, which lists capture devices from sysfs without opening them.

Setup

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

The wheel is about 35 MB and bundles OpenCV and its codecs. On Linux, your user needs to be in the video group to open /dev/video*. On macOS, macOS prompts for camera permission the first time the terminal or app running the hub opens a camera.

Parameters

ParameterDefaultMeaning
nameautoauto (the first camera), a camera index such as 1, or a device path such as /dev/video2. The shorthand uvc: auto sets it
width, heightthe camera's defaultRequested frame size
fpsthe camera's defaultRequested frame rate
jpeg_quality85JPEG quality, 1 to 100
backendanyany, v4l2, avfoundation, dshow, msmf or gstreamer
flush_frames1Frames grabbed and dropped before each capture, so a read never returns an old buffered frame
timeout5 sDeadline for opening and for each capture

The requested size and rate are only requests, because cameras use the nearest mode they support, and the width, height and fps properties report the mode the camera uses.

Channels

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

Image channels need no map, but number channels need map: { property: <name> }. The hub doesn't poll image channels during the snapshot it takes on connect, so a frame is only captured when a client requests one.

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 (missing, busy in another app, no permission) raises DriverError.
  • A capture that returns no frame raises DriverError and marks the camera as failed, which the next heartbeat reports, so the hub reopens the camera.
  • No frame within timeout raises TimeoutError.
  • health() grabs one frame and reports the camera as disconnected if no frame arrives.

Limitations

  • The driver has no camera controls, so exposure, focus, zoom and pan stay as the camera sets them.
  • The driver captures only single frames on request, with no video streams or recording.
  • discover() only works on Linux, so on macOS and Windows cameras are opened by index.
  • Camera indexes can change when cameras are plugged in a different order, but on Linux a /dev/v4l/by-id/... path is stable.

Hazard default and safe state

The default hazard is low and the driver has no write channels, so safe_state_support is none and there is nothing to put in a safe state. 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