Understanding Controls and Streaming

Libusb-UVC exposes the structure of UVC descriptors so you can build robust workflows for camera configuration and streaming. This guide summarises the key concepts and how they map to the Python API.

Video Control Units

Video Control (VC) interfaces contain units such as camera terminals, processing units, and extension units (XU). During enumeration the library parses descriptors into libusb_uvc.UVCUnit objects containing lists of controls (libusb_uvc.UVCControl).

The libusb_uvc.UVCControlsManager validates controls using the UVC GET_INFO probe and merges metadata defined through quirks JSON files. Controls that respond positively are exposed to higher layers via libusb_uvc.ControlEntry.

For convenience Libusb-UVC temporarily detaches the VC interface from the kernel driver while querying controls. Set the environment variable LIBUSB_UVC_AUTO_DETACH_VC=0 if you prefer to handle detaching manually.

Extension Units and Quirks

Many cameras expose proprietary controls via extension units. To assign human readable names you can ship JSON descriptors under src/libusb_uvc/quirks. Each file contains a GUID, a friendly name, and a mapping of selector IDs to control definitions. The helper libusb_uvc.load_quirks() aggregates these files at runtime, enabling cameras like the Quanta 5 MP series to present controls such as Privacy Shutter and LED Control.

Libusb-UVC also understands the Microsoft Camera Control XU (0f3f95dc-2632-4c4e-92c9-a04782f43bc8). The bundled quirk file provides a heuristic description of each selector using the GET_INFO flags and payload lengths returned by the device. When a match is found the resulting libusb_uvc.ControlEntry exposes readable names (Video HDR Mode, Metadata Control, etc.) and preserves the underlying quirk metadata in the metadata attribute so applications can inspect the original Microsoft property key. If your camera exposes the Microsoft XU with a different ordering, copy the JSON file, assign explicit selector numbers, and place it in your own package.

Streaming Interfaces

Video Streaming (VS) interfaces describe the data formats, frame sizes, and alternate settings used for isochronous transfers. The function libusb_uvc.list_streaming_interfaces() parses these descriptors into libusb_uvc.StreamingInterface objects which enumerate available formats and frames.

When a stream is opened, libusb_uvc.UVCCamera negotiates the desired format using GET_DEF/GET_CUR/SET_CUR requests, selects an alternate setting whose maximum packet size can sustain the throughput, and schedules isochronous transfers through the libusb_uvc.uvc_async backend.

Frame Objects

Capturing functions return libusb_uvc.CapturedFrame instances. These wrap the raw payload together with the negotiated libusb_uvc.StreamFormat and libusb_uvc.FrameInfo. Convenience methods such as libusb_uvc.CapturedFrame.to_rgb() leverage OpenCV or Pillow to convert MJPEG/YUYV payloads into ready-to-display arrays.

Device Reset and Kernel Cooperation

To avoid leaving uvcvideo in a bind state, the library issues a USB device reset whenever a stream stops and the kernel driver was detached previously. This ensures that /dev/video* nodes reappear immediately, allowing native V4L2 applications such as mplayer or cheese to resume using the camera.