Repository avatar
Multimedia
v0.1.0
active

stereoweave

io.github.raydeoliveira/stereoweave

macOS EDID 3D/RGB-4:4:4 solver, Metal stereo weaver, and MV-HEVC Spatial Video converter.

Documentation

StereoWeave

Native Apple Silicon macOS CLI and MCP server that audits and patches VESA EDID 1.4 / CTA-861 display overrides for 3D monitors, AR glasses, 3D projectors, and 4K OLEDs, weaves stereo/lenticular frames on Metal, and converts Apple MV-HEVC Spatial Video bidirectionally via VideoToolbox — in a single 645 KB zero-dependency binary.

Measured Footprint

Measured on Apple M4 Max (arm64-apple-macos14.0, Swift 6.4.2):

MetricMeasured Value
Stripped binary (arm64)645,216 bytes (630 KB)
Compressed release tarball253,290 bytes (247 KB, includes binary + docs + MCP manifest)
External dependencies0 (Apple system frameworks only; no FFmpeg, no Python)
Cold-start --version latency (15 runs)7.90 ms median (7.18–9.10 ms)
Automated test suite (16 tests)1.07 s (includes live Metal GPU & VideoToolbox MV-HEVC)

What It Does / What It Does Not Do

CapabilityStatusTier
Live macOS CoreGraphics + IOKit display/EDID probe (probe)IncludedFree
VESA EDID 1.4, CTA-861, HDMI 3D VSDB & DisplayID 2.x inspection (edid inspect)IncludedFree
VESA CVT-RB2 timing synthesis & HDMI/DP/USB-C link-budget solver (edid budget)IncludedFree
Dry-run EDID patch preview & checksum verification (edid patch --dry-run)IncludedFree
Dubois color-preserving Red/Cyan anaglyph Metal preview (weave --out-layout dubois-anaglyph)IncludedFree
Immediate override rollback (edid restore)IncludedFree
Read-only stdio MCP server (probe_displays, inspect_edid, solve_link_budget, dry-run patch_edid)IncludedFree
Surgical EDID binary + macOS DisplayOverride plist export (full-sbs-1080p, full-sbs-1080p-120, force-rgb444, hdmi-3d-framepack)IncludedPro ($29)
Snapshot + timed auto-revert + SIGINT/SIGTERM rollback override installer (edid apply)IncludedPro ($29)
Full Metal GPU weaver (Full-SBS, Half-SBS unsqueeze, TAB, Row/Col Interlaced, Checkerboard, Slanted Subpixel Lenticular, RGB-D DIBR)IncludedPro ($29)
Bidirectional hardware VideoToolbox MV-HEVC Spatial Video <-> 3D stereo video transcoding with audio pass-through (convert)IncludedPro ($29)

Explicit Non-Goals & Current Verification Limits:

  • macOS Apple Silicon (arm64, macOS 14+) only. Windows and Linux binaries are not built in v0.1.0.
  • No kernel extensions, SIP disabling, or game-engine DLL injection. Display overrides use Apple's standard /Library/Displays/Contents/Resources/Overrides plist path (requires sudo when targeting the system directory, and display reconnect or reboot for WindowServer reload).
  • Hardware testing disclosure: CoreGraphics/IOKit probing, Metal GPU pixel-oracle rendering across all 8 layouts + RGB-D DIBR, VideoToolbox bidirectional MV-HEVC <-> Full-SBS transcoding, symlink/signal rollback, and loopback HTTP Polar.sh licensing were all executed and verified on real Apple M4 Max hardware. Physical external AR glasses (XREAL/VITURE/Rokid), lenticular monitors (Samsung Odyssey 3D / Acer SpatialLabs), and 3D projectors have not yet been visually verified on physical units — EDID transformations are verified against VESA EDID 1.4 / CTA-861 binary fixtures and strict checksum re-parsing.

Install & Uninstall

From Release Tarball

tar -xzf stereoweave-0.1.0-macos-arm64.tar.gz
shasum -a 256 -c SHA256SUMS.txt
install -m 755 stereoweave-0.1.0-macos-arm64/stereoweave /usr/local/bin/stereoweave
stereoweave --version

Build From Source (Swift 6, macOS 14+)

swift test

# Open-Source Edition build (all features unlocked offline, zero network calls):

Uninstall

rm -f /usr/local/bin/stereoweave
rm -rf ~/.config/stereoweave
# If you installed a system display override, restore it first:
sudo stereoweave edid restore --display-vendor <hex> --display-product <hex>

Quick Start

1. Probe Connected Displays & Audit an EDID

stereoweave probe

Real output on Apple Silicon MacBook Pro:

Display #1: Built-in Apple Display [0610:a05c] 3024x1964@120.0Hz builtIn=true edid=apple-internal-attributes

Inspect a binary EDID file (or one of 4 built-in hardware fixtures: xreal-ar-glasses, odyssey-3d-lenticular, lg-oled-ycbcr420, projector-hdmi-3d):

stereoweave edid inspect --fixture xreal-ar-glasses

Real output:

Display: XREAL Air/One (NRL 3a4c:0574) EDID 1.4 [256B, checksums=true]
  Timing (base-dtd-0): 1920x1080@60.0Hz (133320 kHz)
  [!] No HDMI VSDB 3D structures advertised (fix for 3D projectors/TVs: `--preset hdmi-3d-framepack`).
  [!] No Full-SBS 3840x1080 timing advertised (fix for AR glasses / 3D displays: `--preset full-sbs-1080p`).

2. Verify Physical Cable Link Budget Before Patching

stereoweave edid budget --width 3840 --height 1080 --hz 60 --link usbc-4lane

Real output:

Timing: 3840x1080@60.0Hz (261310 kHz) | PASS: 6.27 Gbps fits within usbc-4lane ceiling (25.92 Gbps, 24.2% load).

Check an impossible link in machine-readable --json mode:

stereoweave edid budget --width 3840 --height 1080 --hz 120 --bpc 10 --link hdmi20 --json

Real output:

{"data":{"bitsPerComponent":10,"chroma":"444","dscEnabled":false,"effectiveRequiredGbps":16.144,"fits":false,"link":"hdmi20","linkCapacityGbps":14.4,"recommendation":"FAIL: 16.14 Gbps exceeds hdmi20 ceiling (14.40 Gbps). Lower Hz, use 8bpc, or switch to a 4-lane/FRL6 cable.","requiredGbps":16.144,"timing":{"hBlank":80,"hFrontPorch":8,"hSyncWidth":32,"height":1080,"interlaced":false,"pixelClockKHz":538140,"refreshHz":120,"source":"cvt-rb2","vBlank":64,"vFrontPorch":1,"vSyncWidth":8,"width":3840},"utilizationPercent":112.1},"ok":true,"schema_version":1}

3. Dry-Run Patch, Metal Weave, MV-HEVC Convert & AI Agent MCP

# Preview Full-SBS 3840x1080@60Hz EDID patch with checksum verification (Free):
stereoweave edid patch --fixture xreal-ar-glasses --preset full-sbs-1080p --dry-run --json

# Activate Pro license via Polar.sh (validates once, 14-day offline grace, zero telemetry):
stereoweave license activate --key <YOUR_POLAR_KEY>

# Weave stereo image pair into slanted subpixel lenticular output on Metal GPU (Pro):
stereoweave weave --input left.png --right right.png --in-layout pair --out-layout lenticular --lens-pitch 4.5 --lens-slant 0.3333 --output woven.png

# Convert Apple Vision Pro / iPhone MV-HEVC Spatial Video -> Full-SBS for AR glasses (Pro):
stereoweave convert --input spatial.mov --in-layout mv-hevc --out-layout full-sbs --output glasses_sbs.mov

# Start stdio JSON-RPC 2.0 MCP server for Claude Code, Codex, Cursor, or Antigravity:
stereoweave mcp

Safety & Rollback

Every display override mutation enforces the 6-stage safety chain:

  1. Validate: Parses target plist + embedded IODisplayEDID bytes and verifies every 128-byte VESA checksum before touching disk. Refuses symbolic links (lstat).
  2. Dry-Run: Pass --dry-run to validate without writing any file.
  3. Non-TTY Guard: Refuses to mutate disk when stdin is not an interactive TTY unless --yes is explicitly supplied.
  4. Snapshot: Copies any existing override file atomically to ~/.config/stereoweave/snapshots/ (or --snapshot-dir) before overwriting.
  5. Timed + Signal-Safe Auto-Revert: Writes atomically, verifies byte-for-byte readback, then waits --confirm-timeout seconds (default 15s) for y + Enter. If the screen goes blank, the timer expires, or SIGINT/SIGTERM (Ctrl-C) arrives, StereoWeave immediately restores the prior file (or deletes the new override if none existed).
  6. Instant Manual Restore: stereoweave edid restore --display-vendor <hex> --display-product <hex> is always unlocked on the Free tier.

Exit Codes & CLI Contract

Every command accepts --json and emits {"schema_version":1,"ok":true|false,"data":...,"error":...} to stdout (diagnostics only on stderr). Run stereoweave --describe for the full machine-readable capability manifest or stereoweave --help for full usage.

Exit CodeMeaning
0Success ("ok": true)
1Runtime error, media/GPU failure, or auto-rollback triggered
2Invalid CLI usage, invalid EDID/checksum, or link bandwidth exceeded on patch
3Hardware unavailable (no displays or Metal GPU)
4Permission denied, read-only volume, or symbolic link rejected
5Pro license required or invalid/expired Polar.sh license key
130Interrupted by SIGINT/SIGTERM after automatic rollback cleanup

License & Support

  • Commercial binary distribution is licensed under LICENSE (Free Core + $29 one-time Perpetual Pro license via Polar.sh, valid for up to 3 personal Macs, offline-capable with zero telemetry).
  • Security & vulnerability disclosure: SECURITY.md.
  • AI Agent integration docs: SKILL.md and server.json.

Install (Commercial Free Core + Pro $29)

brew tap raydeoliveira/tap
brew install stereoweave
  • MCP Clients (One-Click .mcpb): Download stereoweave-0.1.0-macos-arm64.mcpb from GitHub Releases.
  • Pro License ($29, or $49 Complete 4-Tool Spatial Wedge Bundle): Purchase at https://polar.sh/raymond-de-oliveira and activate via stereoweave license activate --key <YOUR-KEY>.
  • Distribution Notice: This public repository hosts official documentation, AI-agent SKILL.md / server.json manifests, and signed commercial release archives. Source code is maintained privately.
MCPB
https://github.com/raydeoliveira/stereoweave/releases/download/v0.1.0/stereoweave-0.1.0-macos-arm64.mcpb
Install Command
# mcpb: https://github.com/raydeoliveira/stereoweave/releases/download/v0.1.0/stereoweave-0.1.0-macos-arm64.mcpb