cto-legends · module specification · studio · v0.1.2
legends-obs: OBS Studio WebSocket v5 Controller, Scene Planner & Recording QA
Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.
GitHub Repository (https://github.com/avalonreset/legends-obs) · Handoff: cto-legends handoff legends-obs
legends-obs (formerly legends-obs-kit) is a guarded, zero-MCP Node.js 22+ CLI for Windows that controls OBS Studio 28+ through its built-in WebSocket v5 loopback server, local configuration files, and FFprobe. Unassisted agents attempting to automate OBS typically guess .ini keys, overwrite configuration files while the OBS process is running (which OBS silently clobbers on exit), or treat an HTTP/WebSocket 200 OK response as proof that recording works. legends-obs replaces ad-hoc file edits and fragile UI click macros with a transactional flight recorder that inventories GPU adapters, loaded encoders, scene collections, and audio routing before planning any change.
Architecturally, the runtime separates read-only diagnostics and dry-run planning from doubly gated live mutations (LEGENDS_OBS_DRY_RUN=false plus --confirm). Every profile or audio mutation verifies that all OBS outputs (recording, streaming, replay buffer, virtual camera) are idle, captures a pre-mutation snapshot under %LOCALAPPDATA%\LegendsOBS\state, refreshes the active OBS video pipeline via SetVideoSettings, and enforces exact readback verification with automatic fail-closed rollback on mismatch. To prove end-to-end output health, record:canary captures a bounded 3-to-30-second local clip, inspects container stream tags with FFprobe, checks render/output skipped-frame deltas and fresh OBS logs, and advances the machine's last-known-good pointer only when every check passes.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
A Frontier LLM in a browser window has no visibility into the active D3D11 adapter table, loaded OBS encoder modules, NVIDIA Video Codec SDK driver gates, or Windows audio endpoint states. Even when given shell access, an unguided LLM that edits basic.ini while OBS is open either fails to rebuild the active video pipeline or corrupts the profile when OBS flushes its in-memory state on shutdown.
- In-Process Loopback WebSocket Authentication Without Secret Leaks: src/obs-websocket.ts and src/obs-config.ts read the local OBS WebSocket v5 server configuration and authenticate directly in-process over loopback without ever printing, copying, or exposing WebSocket passwords or stream keys in agent transcripts.
- Active Video Pipeline Rebuild & Fail-Closed Rollback: Writing profile parameters on disk does not rebuild a running OBS encoder session. src/profile.ts verifies all outputs are idle, writes a rollback snapshot, triggers a guarded SetVideoSettings refresh, and automatically rolls back if live WebSocket readback diverges from the preset.
- FFprobe Container Verification vs. API Status Assumptions: An obs-websocket StartRecord request can succeed while NVENC fails to initialize, colorspace tags are misconfigured, or a USB microphone is muted. record:canary records a real local clip and validates codec, dimensions, FPS, bit depth, color tuple, audio signal, and skipped-frame counters via FFprobe and OBS log parsing.
- Immutable Dual-Pointer Machine Audit Ledger: src/audit.ts hashes stable host hardware, capability surfaces, and redacted basic.ini/global.ini states into .legends-obs-kit/audits/<machine-key>/snapshots/, strictly separating the latest observed state from the canary-qualified last-known-good pointer.
CLI Subcommands & Capability Surface
legends-obs doctor --pretty | inventory --pretty — Authenticated Control Plane & Capability Doctor: Validates the local authenticated OBS WebSocket v5 control plane, detects OBS 33.0+ Safe Mode crash-sentinel locks (.sentinel / run_* markers in %APPDATA%\obs-studio), and summarizes GPU adapters, NVIDIA SDK 13 driver 570+ NVENC readiness, sdr_on_hdr_filter availability, FFprobe paths, and microphone status in a privacy-minimized JSON receipt.legends-obs audit:capture --reason <tag> | audit:diff --against good — Dual-Pointer Hardware Audit Ledger & Drift Diffing: Captures immutable, secret-redacted snapshots of GPU VRAM/driver versions, loaded video/audio encoders, scene graphs, and INI parameters keyed by stable machine hardware identity. Operators and agents run audit:diff --against good to pinpoint exact JSON path changes between current state and the last canary-proven recording configuration.legends-obs profile:plan | profile:apply --preset <id> --confirm | profile:rollback — Transactional Profile Planning, Application & Rollback: Computes dry-run parameter diffs against explicit hardware presets (such as hdr-4k60-av1-hybrid-mp4) and refuses execution if any output is active. Live application writes a pre-mutation snapshot, refreshes the video pipeline, verifies exact readback, and exposes profile:rollback for deterministic restoration.legends-obs record:canary --preset <id> --seconds 8 --confirm [--require-microphone] — FFprobe & Log-Backed Recording Canary: Executes a bounded 3-to-30-second local test recording—never streaming—waiting through encoder initialization before timing. Probes the resulting media container with FFprobe for codec, resolution, framerate, bit-depth, and color tags, checks OBS log errors and frame-drop deltas, and advances last-known-good only on a clean WORKS verdict.legends-obs vision-switch:plan | vision-switch:arm | vision-switch:tick | vision-switch:daemon — Deterministic Shell-Geometry Vision Switcher: Maps active desktop panel pairs (A/B and C/D) from an external PowerShell geometry sensor (LEGENDS_OBS_PANEL_SENSOR) to OBS scenes panel-ab and panel-cd with zero LLM calls in the cut loop. Disarmed and dry-run by default, it refuses scene cuts while outputs are active and requires --go <note> for transactional scene renames.extras/cursor/install_into_obs.ps1 (Legends Cursor Filter) — Optional Animated Cursor Overlay Filter: Ships a separable GPL-2.0-or-later Windows LuaJIT FFI (user32) video filter in extras/cursor/ that renders a smooth cursor halo, speed-driven momentum ticks, left-click ripples, right-click diamond bursts, and comet trails. Backing up the scene collection before install, it operates independently of the MIT-licensed core CLI.
Raw Frontier LLM vs. legends-obs Execution Matrix
- Configuration Mutation & Pipeline State: Raw LLM (Edits basic.ini while OBS is open; OBS ignores the edit in memory and overwrites the file on exit.) vs. Module (Asserts all outputs are idle, writes a rollback snapshot, applies changes via WebSocket v5, and runs SetVideoSettings.) — Exact live WebSocket readback comparison with automatic fail-closed rollback on any mismatch.
- Recording Quality Assurance: Raw LLM (Assumes recording succeeded because StartRecord returned HTTP/WS 200 OK.) vs. Module (Runs a bounded 3–30s local record:canary clip and inspects the output file, encoder init, and audio track.) — FFprobe stream/color tag inspection, OBS log error grep, skipped-frame delta check, and receipts:verify.
- Session-to-Session Drift Diagnosis: Raw LLM (Guesses which OBS dropdown or Windows update broke recording with no historical baseline.) vs. Module (Maintains per-machine immutable audits with separate latest and canary-qualified last-known-good pointers.) — audit:diff --against good outputs up to 250 exact JSON path before/after diffs; audit:verify checks hashes.
- Credential & Workstation Privacy: Raw LLM (Reads and dumps raw INI files containing stream keys, WebSocket passwords, and local window titles into chat.) vs. Module (Authenticates in-process, excludes stream keys/service tokens from audits, and defaults to redacted summaries.) — Automated secret scanning in audit:verify and privacy-minimized JSON output unless --full is requested.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Why does authenticated-control fail in doctor even when OBS Studio is open?
- Verify that Tools -> WebSocket Server Settings has Enable WebSocket server checked and authentication enabled. Additionally, if OBS was previously force-closed, it may be blocked on a modal Safe Mode prompt (.sentinel or run_* markers in %APPDATA%\obs-studio), and OBS 33.0+ disables the WebSocket server while running in Safe Mode.
- Why does doctor report nvenc-av1 unavailable on OBS Studio 32.2 or newer?
- OBS Studio 32.2+ compiles against NVIDIA Video Codec SDK 13, which requires NVIDIA Windows driver 570 or newer alongside an AV1-capable GPU (such as an NVIDIA RTX 40-series adapter).
- How is the optional cursor overlay licensed compared to the core CLI?
- The core legends-obs TypeScript/Node CLI and documentation are licensed under MIT. The optional Legends Cursor Filter in extras/cursor/ (which uses LuaJIT FFI into user32 for cursor halo, momentum ticks, click ripples, and comet trail) is a separable component licensed under GPL-2.0-or-later and is not installed by default.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.