Audio Calibration MCP

Audio Calibration MCP is a local-first, cross-platform Model Context Protocol
server for Room EQ Wizard (REW). It guides acoustic measurement, speaker and
room calibration, subwoofer and crossover analysis, conservative EQ, DSP
deployment, and measured verification for general, powered-speaker, car, and
laptop audio systems.

This project does not promise universally “perfect” sound. REW can measure an
acoustic system; it cannot infer listener preference, microphone placement, or a
speaker's safe output capability without evidence. The MCP reports missing data
and keeps preference separate from engineering calculations.

Choose the right audio MCP

The projects share measurement discipline, but this MCP deliberately stays hardware-neutral; EvoBurrow owns the A1 and AVR-specific safety boundary.

Measured laptop example — before and after

This is measured evidence from four repeated REW sweeps per state, averaged with
1/12-octave smoothing. Factory is amber and the cut-only JamesDSP preset is cyan.
The shaded area below 500 Hz marks the protection-limited bass region where no
boost was applied. The plot preserves measured SPL; preference was assessed in a
separate level-matched listening comparison. Device, microphone, and preset
identifiers are intentionally removed from the public artifact.

Compatibility

Install

Download a GitHub release archive and point Codex at its .mcp.json. For a source
checkout:

npm ci --ignore-scripts
npm test
npm run validate:release

The checked-in MCP configuration starts the self-contained dist/server.mjs.
The packaged CLI is also bundled, and the published artifact declares zero
runtime npm dependencies. Third-party build inputs are exact-pinned and installed
with lifecycle scripts disabled. Run
rew_install_discover to locate REW through a user override, the
AUDIO_REW_EXECUTABLE environment variable, PATH, and conventional Windows,
macOS, or Linux locations. If discovery fails, pass the absolute executable path
(or REW.app on macOS) to that tool or rew_launch_plan. Starting REW requires
the matching rew_launch_execute confirmation. Startup is verified against the
API on http://127.0.0.1:4735; override AUDIO_REW_URL only for a trusted local
network endpoint. REW's API still must be enabled in REW itself.

Guided workflow

1. Run audio_doctor. If REW is offline, use rew_install_discover, then the
   confirmed rew_launch_plan/rew_launch_execute pair. Continue with
   rew_capability_negotiate and audio_guided_session_plan.
2. Inventory the host, REW, microphone calibration, output route, and DSP state.
3. Create a protected repeated-session plan. Audible execution requires fresh
   microphone-placement, area-clear, and route/safety confirmation.
4. Save separate raw traces, then run quality, dual-resolution, direct/late,
   crossover, distortion/compression, and human-listening analyses.
5. Prefer placement, polarity, timing, crossover, and stable cut-first EQ.
6. Apply only a hash-bound confirmed plan with backup and rollback.
7. Re-measure at matched level. Start audio_post_eq_verification, then poll
   audio_job_status; the verifier derives level difference from the traces.
   Predicted response and caller-claimed level matching are never acceptance evidence.
8. Use randomized, level-matched A/B or ABX for preference/discrimination.
   On JamesDSP, jamesdsp_ab_plan plus its presentation and restore executors
   switch presets and host volume transactionally without revealing assignments.

Analysis views

Reports preserve the source trace and display native unsmoothed data, derived
engineering resolution, 1/48-octave structure, adaptive modal-to-perceptual
smoothing, and ERB/perceptual views. Filters are eligible only when features are
stable across repetitions and held-out data. Narrow/spatial nulls are not boosted.

audio_report_plan can also accept two to four repeated comparison groups. It
averages each state, preserves ±1 SD, calculates the measured level difference,
and exports Markdown, HTML, JSON, and a standalone labeled SVG suitable for a
README. Missing SNR rejects the quality gate by default; exploratory callers must
explicitly opt out with requireSnr: false.

Privacy

There is no telemetry. Local sessions may contain usernames, absolute paths,
device names, room coordinates, microphone hashes, and preset fingerprints.
Never publish measurements/, sessions/, backups/, profiles/, reports/,
or filters/ directly. Use the redacted support-artifact tools and review the
result before sharing it.

Development and validation

npm test is hardware-independent. npm run coverage exercises deterministic
DSP and safety fixtures. npm run validate:release checks manifests, metadata,
the bundled server, and package contents. Real-system smoke tests are opt-in and
must never run in ordinary CI.

REW requests are bounded to four concurrent calls by default. Set
AUDIO_REW_MAX_CONCURRENCY from 1–8 only when the local REW instance has been
validated at that concurrency.

See SECURITY.md, CONTRIBUTING.md, and
CHANGELOG.md. Licensed under the MIT License.

Measurement-science laboratory modules

Bounded tools cover GUM-style uncertainty budgets and Monte Carlo propagation,
bootstrap repeatability, complex-transfer coherence and phase confidence,
ISO-3382-aligned room screening, exploratory polar/directivity scans, clean-output
ladders, held-out-seat complex multi-source optimization, regularized FIR proposals,
controlled listening trials, immersive/SOFA metadata preflight, and reference-corpus
auditing.

Screening, inspired, and standards-aligned never mean certified conformity.
ISO, IEC, ANSI/CTA, AES, and ITU conformity requires the complete current normative
document, prescribed setup and processing, calibrated instrumentation, and traceable
evidence. Optimization and FIR outputs remain proposals until protected, level-matched
hardware remeasurement accepts them.

Curated external datasets

audio_dataset_catalog exposes reviewed metadata for selected SADIE II, FLAIR,
MeshRIR, and RAVes artifacts without downloading them. Dataset acquisition uses a
hash-bound plan/execute pair, requires license acknowledgement, enforces an exact
byte ceiling, accepts only pinned Zenodo HTTPS URLs, refuses overwrites, checks the
upstream checksum, calculates SHA-256, and writes a provenance receipt under the
workspace datasets/ directory.

Remote entries and checksum-verified downloads are not automatically scientific
validation. Readiness is calculated per domain and requires parsed, method-compatible
references from at least two independent institutions with justified tolerances.

Laptop calibration

Laptop speakers remain fully supported, but this is the least general workflow and
is intentionally documented last. Laptop mode starts at 120 Hz and -30 dBFS by
default. Stop immediately on an unexpected route, silence, clipping, limiter
activity, rattling, or distress.

Support the project

Audio Calibration MCP is free and open source. If it saves you time or improves
your system, you can buy daredoole a coffee.