Architecture

Overview

libobsbot is a Rust workspace with two member crates: libobsbot-core (pure Rust library) and libobsbot-ffi (C ABI cdylib + staticlib generated from libobsbot-core). The core crate is the only crate that touches USB.

Layers

+---------------------------------------------------------------+ | public Rust API (Devices, Device, Event, types) | +---------------------------------------------------------------+ | per-model command table (selector, encode, decode triples) | +---------------------------------------------------------------+ | Transport trait { uvc_set(entity, sel, ..), | | uvc_get(req, entity, sel, ..) } | +---------------------------------------------------------------+ | Per-platform driver (Linux today: V4L2 + UVCIOC ioctls on | | /dev/videoN via uvcvideo; macOS = IOKit, Windows = WinUSB | | are planned in-tree, each as its own Transport impl) | +---------------------------------------------------------------+

The narrowest layer - Transport - is the boundary that mocks plug into for encoding tests. Every selector and byte-layout constant in the per-model command table must be justified by a committed pcap; see the sourcing rule.

Control surfaces

The Meet 2 (and OBSBOT cameras generally) expose three UVC entities, all addressed through the same Transport API:

Camera Terminal (entity id 1) for PTZ, zoom, focus - standard UVC 1.5 §A.9.4 selectors.
Processing Unit (entity id 3) for brightness, contrast, saturation, white-balance temperature - standard UVC 1.5 §A.9.5 selectors.
OBSBOT vendor Extension Unit (entity id 2, GUID {9a1e7291-6843-4683-6d92-39bc7906ee49}) for proprietary behaviors (mediaMode, HDR, FOV preset, face AE/focus, AI mode, status). All vendor-specific bytes live here.

Standard UVC selectors are normative (the spec is the source); only the XU surface requires pcap audit-trail entries.

Threading

The hot-plug watcher runs on one std::thread spawned by Devices::new, pumping events into a crossbeam_channel.
Each opened Device owns one status-poller thread that issues uvc_get for brightness, contrast, saturation (Processing Unit) and pan/tilt/zoom (Camera Terminal) every 2.5 s (slow mode) or 25 ms (fast mode), pushing Event::Status snapshots into the same channel. Firmware/serial ride the XU RPC channel and are exposed via dedicated methods rather than the periodic sample.
All public setter methods are synchronous. Getter methods that map to GET_CUR are also synchronous.

No tokio / async runtime. One long-lived thread per device is enough.

Where to expect change

src/devices/meet2.rs grows whenever a new XU control is captured and decoded. The CRC, MAC handshake, and mode-register status blob are already in place; remaining additions are mostly per-method captures of advanced controls (MAE-ISO, mirror / flip, firmware-upgrade trigger, ...).
src/transport/usb.rs (Linux) and src/transport/macos.rs (macOS) ship today. A Windows (WinUSB) transport is planned. See macos-port-plan.md for the macOS design notes.
src/discovery.rs polls every 2 s for hot-plug changes. Switching to push-based notification (libudev on Linux, IOServiceAddMatchingNotification on macOS) is future work.

What is intentionally out of scope (v1)

Models other than the Meet 2.
Firmware update, file transfer, recording controls, exposure modes beyond brightness/contrast/saturation, gimbal-preset CRUD, AI gesture, Bluetooth, WiFi, NDI/RTSP. Some of these use bulk endpoints rather than the XU control channel and would require an entirely separate transport layer. If v2 needs them, the Transport trait will grow.