Repository avatar
Other Tools
v0.1.0
active

edidsmith

io.github.raydeoliveira/edidsmith

EDID 1.4/CTA-861/DisplayID 2.1 parser, CVT-RB2 link-budget solver, and safe EDID patcher.

Documentation

EdidSmith

Clean-room EDID 1.4, CTA-861, and DisplayID 2.0/2.1 parser, VESA CVT-RB2 link-budget solver, display quirk catalog, and safe rollback override CLI and stdio MCP server for macOS Apple Silicon and Linux/SteamOS DRM.

Measured release binary (macOS arm64, stripped + ad-hoc codesigned): 907,312 bytes (~886 KB), 6.3 ms median --version cold start across 20 runs, zero third-party dependencies.

What It Does / What It Does Not Do

CapabilityStatusNotes
EDID 1.4 base block (0x00..0x7F)SupportedEstablished/Standard timings, DTDs, 0xFC name, 0xFD Range Limits (+255 offsets & CVT), 0xFE/0xFF
Multi-block CTA-861 (0x02)SupportedAudio (1), Speaker (4), SVD (2, VIC 1..219 + native bit 7), HDMI 1.4 VSDB, HF-VSDB, 0x00/0x05/0x06/0x0E/0x0F/0x79
DisplayID 2.0/2.1 (0x70)SupportedDual inner+outer checksums, payloadLen <= 121, 0x20, 0x21, 0x22, 0x23, 0x25, 0x27, 0x28, 0x2A
VESA CVT-RB2 & Link-Budget SolverSupported1 kHz / 10 kHz, 1000/1001 NTSC, 15 HDMI/DP/USB-C link standards, DSC 1.2 8 bpp floor
Safe EDID & DisplayID PatcherSupportedfull-sbs-1080p, full-sbs-1080p-120, force-rgb444, hdmi-3d-framepack, inject-vrr, inject-displayid-t7
Safe Display Override & 15s RollbackSupportedlstat symlink guard, atomic snapshot, byte-for-byte readback check, sigaction (sa_flags=0) rollback
Built-in Quirk DB & Stdio MCP ServerSupported6-entry quirk DB, --from-json - composability, JSON-RPC 2.0 mcp (2024-11-05)
Kernel extensions / SIP disablingNot usedZero kexts or DriverKit extensions; relies on standard macOS override plists or Linux DRM overrides
Automatic WindowServer reloadNot supportedWriting macOS /Library/Displays/Contents/Resources/Overrides requires sudo and display reconnect/reboot

Install & Uninstall

Build from source (macOS 14+ Apple Silicon or Swift 6 toolchain)

cd projects/edidsmith
# Or open-source build with all features unlocked offline:

Homebrew (when tap release is published)

brew install raydeoliveira/tap/edidsmith

Uninstall

Remove the installed binary and optional license cache (~/.config/edidsmith/license.json) or override snapshots (~/.config/edidsmith/snapshots/). Use edidsmith edid restore before uninstalling if you applied a display override.

Quick Start

Human CLI

# 1. Inspect an EDID / DisplayID 2.1 fixture (or live attached display with `probe`)
edidsmith --version
# edidsmith 0.1.0 (commercial, arm64)

edidsmith edid inspect --fixture displayid21-5k-tiled
edidsmith quirks --vendor 3a4c --product 0574

AI-Agent --json & --from-json - Usage

edidsmith edid budget --width 3840 --height 1080 --hz 60 --link usbc-2lane --json

Measured output:

{"data":{"bpc":8,"chroma":"444","dsc_enabled":false,"effective_required_gbps":6.271,"fits":true,"link":"usbc-2lane","link_capacity_gbps":12.96,"recommendation":"Fits usbc-2lane uncompressed (48.4% link utilization).","required_gbps":6.271,"solved_mode":{"bpc":8,"chroma":"444","fits":true,"height":1080,"pixel_clock_khz":261310,"refresh_hz":60,"stereo_layout":null,"width":3840},"timing":{"h_blank":80,"h_front_porch":8,"h_sync_positive":true,"h_sync_width":32,"height":1080,"interlaced":false,"pixel_clock_khz":261310,"preferred":false,"refresh_hz":60,"source":"cvt-rb2","stereo_mode":null,"v_blank":31,"v_front_porch":1,"v_sync_positive":false,"v_sync_width":8,"width":3840},"utilization_percent":48.4},"error":null,"ok":true,"schema_version":1}
edidsmith quirks --vendor 3a4c --product 0574 --json

Measured output:

{"data":{"count":1,"matches":[{"category":"ar-glasses","known_issues":["macOS suppresses 3840x1080 Full-SBS DTD over USB-C DP Alt Mode without an explicit CVT-RB2 override.","Some USB-C 2-lane hubs restrict high-refresh 3840x1080@120Hz."],"manufacturer_code":"NRL","model_name":"XREAL Air / One AR Glasses","notes":"Verify 2-lane vs 4-lane USB-C DP Alt Mode budget before applying 120 Hz Full-SBS.","product_id_hex":"0574","quirk_id":"xreal-full-sbs","recommended_link":"usbc-4lane","recommended_presets":["full-sbs-1080p","full-sbs-1080p-120"],"vendor_id_hex":"3a4c"}]},"error":null,"ok":true,"schema_version":1}

Pipe outputs across tools via --from-json - (upstream ok: false fails closed with exit 2 UPSTREAM_ENVELOPE_FAILED; explicit CLI flags override piped fields):

edidsmith edid patch --fixture xreal-ar-glasses --preset full-sbs-1080p --dry-run --json \
  | edidsmith edid budget --from-json - --link hdmi21-frl3 --json

Start the stdio JSON-RPC 2.0 MCP server (2024-11-05):

edidsmith mcp

Safety & Rollback

  1. Probe & Validate First: probe probes external displays only by default (exit 3 if absent; pass --sim or --fixture <name> for hardware-free runs). EDIDParser validates both outer 128B block checksums and DisplayID 0x70 inner checksums before patching or applying.
  2. STW-003 Patcher Guards: Never overwrites Block 1 DisplayID (0x70), never clobbers 0xFC/0xFD/0xFE/0xFF descriptors, rejects CTA DBC overflow (> 123B), and preserves dtdOffset == 0 -> 4 alignment.
  3. Symlink Guard & Atomic Snapshots: FileOverrideStorageAdapter checks paths with lstat (exit 4 on symlink traversal), snapshots existing overrides before writing, and verifies byte-for-byte readback.
  4. Non-TTY & 15s Signal Watchdog: edid apply fails closed (exit 2) if stdin is non-interactive without --yes. Interactive runs wait up to --confirm-timeout <sec=15> using non-restarting sigaction (sa_flags = 0) + poll(); timeout (exit 1) or SIGINT/SIGTERM (exit 130) restores the exact prior override.
  5. Hardware Test Scope: All EDID/DisplayID codecs, link budgets, multi-display matching, Linux DRM sysfs/debugfs helpers, lstat symlink guards, openpty SIGINT rollback (exit 130), Polar loopback HTTP licensing, CLI composability, and MCP stdio behavior pass automated tests on Apple Silicon macOS. Physical external 3D monitors and Linux kernel debugfs nodes were not attached on the build host; test live overrides with --dry-run first.

Exit Codes & CLI Reference

Run edidsmith --help for human usage or edidsmith --describe for the JSON capability manifest.

CodeMeaning
0Success
1Runtime or rollback failure
2Usage, invalid EDID, bandwidth exceeded, non-TTY without --yes, or UPSTREAM_ENVELOPE_FAILED
3External hardware or SPI symbol unavailable
4Permission, symlink (lstat), or Linux debugfs denied
130Interrupted (SIGINT/SIGTERM) after automatic rollback

License & Security

MCPB
https://github.com/raydeoliveira/edidsmith/releases/download/v0.1.0/edidsmith-0.1.0-macos-arm64.mcpb
Install Command
# mcpb: https://github.com/raydeoliveira/edidsmith/releases/download/v0.1.0/edidsmith-0.1.0-macos-arm64.mcpb