op-cap

op-cap is a Linux toolkit for stabilising high-throughput USB capture cards used with OBS. It targets the common failure modes of cheap HDMI capture devices: random disconnects, driver hangs, buffer corruption and OBS crashes. Core approach: FFmpeg reads the physical capture device and writes to a v4l2loopback virtual device (default /dev/video10, labelled USB_Capture_Loop). OBS then reads from that stable loopback instead of the hardware, so a hardware hang only kills the FFmpeg feed, which a monitor service restarts automatically. Features described in the README: - Automatic crash recovery: OBS is relaunched on USB device failure, unlimited by default. - Stream resumption: logs are monitored to detect an active stream and restart it after a crash. - Auto-reconnect: device is watched and the feed restarted on disconnect. - USB reset and driver rebind to recover hung devices without rebooting. - Performance tweaks: disables USB autosuspend and adjusts power settings, with udev rule guidance for persistence. - HDR handling modes (auto, force HDR + tonemap, HDR passthrough, force SDR). - Optional overlay/watermark from URL or file, plus delogo and crop filters for removing on-screen logos. - Format auto-detection of resolution and framerate during install. - Wayland graphics optimisation for Nvidia, AMD and Intel drivers, addressing explicit sync and PipeWire issues. Installation is via make build / make install, which interactively selects the capture device and installs systemd services (usb-capture-ffmpeg.service, usb-capture-monitor.service). Host aliases sobs and cobs launch OBS with crash recovery, either unbound or after picking a /dev/video* device. An interactive maintenance menu (scripts/maintenance.sh) exposes nine recovery tools: detect_device, disable_overlay, hard_reset, optimise_device, pick_delogo, repair, simulate_disconnect, uhubctl_reset and usb_reset. Additional scripts cover capture validation (corruption and timeout diagnosis with fallback resolution), device optimisation, driver optimisation, auto-reconnect, format parsing and a quick-reference cheat sheet. Configuration lives in /etc/default/usb-capture, covering device path, resolution, framerate, input format, HDR mode, overlay URL/file/position/scale, delogo toggle, buffer validation and corruption threshold with fallback resolution. A safety launcher (obs-safe-launch.sh) adds device health monitoring, crash restart with a short stabilisation delay, stream auto-resume, log capture under ~/.cache/obs-safe-launch/, and flags for loopback, device, auto-resume and extra OBS arguments. USB hardware recovery needs sudo; an optional sudoers installer limits which recovery scripts may run without a password. Requirements include ffmpeg, v4l-utils and v4l2loopback-dkms, with optional uhubctl and slop, plus GPU-specific drivers for hardware acceleration.