bckgrnd-msc-mcp 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Lane Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# bckgrnd-msc-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![skills.sh](https://skills.sh/b/chrislanejones/bckgrnd-msc-mcp)](https://skills.sh/chrislanejones/bckgrnd-msc-mcp)
+
+An MCP server that puts music under a voice. Hand it a narration MP3 and a track
+name, and it renders the music to the right length, sets it under the voice by
+**measured loudness**, dips it while the voice talks, and hands back one file.
+
+The music comes from [bckgrnd-msc](https://github.com/chrislanejones/bckgrnd-msc), a
+stem machine with eighteen tracks and eight stems each, synthesized by a **Rust**
+engine. This server runs that same engine, compiled to **WebAssembly**, in Node. No
+samples, no streaming service, no licensing questions. The music is made on your
+machine when you ask for it.
+
+## Quick start
+
+Needs Node 20 or newer. Mixing under a voice also needs ffmpeg
+(`brew install ffmpeg`, `sudo apt install ffmpeg` or `winget install Gyan.FFmpeg`).
+
+Use the local server by default, pinned to the v0.3.0 release archive.
+The GitHub package is ready to install; publication to the npm registry is
+pending restoration of the maintainer's registry login.
+
+```sh
+claude mcp add bckgrnd-msc -- pnpm dlx https://github.com/chrislanejones/bckgrnd-msc-mcp/releases/download/v0.3.0/bckgrnd-msc-mcp-0.3.0.tgz
+pnpm dlx skills add chrislanejones/bckgrnd-msc-mcp --skill background-music
+```
+
+Local processing keeps narration on your machine rather than uploading it to
+our hosted MCP. You can also [run from a clone](docs/Getting-Started.md#from-a-clone).
+The current skills installer requires Node 22.20+.
+
+For an explicitly chosen hosted alternative (clips up to two minutes), read
+[ownership, source and audio-processing details](docs/Vercel.md#ownership-and-audio-processing)
+before uploading narration:
+
+```sh
+claude mcp add --transport http bckgrnd-msc https://bckgrnd-msc-mcp.vercel.app/mcp
+```
+
+Then ask for it in plain words: "put Rain under `~/notes/article.mp3`."
+
+The server gives an agent the tools. The skill gives it the taste: which track
+suits which content, where to set the level, and what to change when the listener
+says "I can't hear the words." Other clients, settings and running from a clone →
+**[Getting Started](docs/Getting-Started.md)**.
+
+## Preview, remember and export
+
+Ask your agent:
+
+- "Compare two gentle tracks under this tutorial before mixing the whole file."
+- "Save these as my podcast settings; use subtle ducking and an evolving arrangement."
+- "Add music to this screen recording and keep the video synchronized."
+- "Master the finished export to -18 LUFS with a -2 dBTP ceiling."
+
+Local setup check: `pnpm dlx https://github.com/chrislanejones/bckgrnd-msc-mcp/releases/download/v0.3.0/bckgrnd-msc-mcp-0.3.0.tgz --check`.
+Codex setup: `codex mcp add bckgrnd-msc -- pnpm dlx https://github.com/chrislanejones/bckgrnd-msc-mcp/releases/download/v0.3.0/bckgrnd-msc-mcp-0.3.0.tgz`.
+
+[Workflow examples](docs/Workflows.md) cover previews, presets, video exports
+and mastering. All seven tools run locally. Hosted processing adds previews,
+ducking controls, arrangements and mastering for short uploaded audio; saved
+presets, video and setup diagnostics stay local.
+
+## Documentation
+
+- **[Vercel hosting](docs/Vercel.md)**: remote MCP endpoint, audio uploads and hosted clip limits.
+- **[Getting Started](docs/Getting-Started.md)**: install it in Claude Code, Claude Desktop or any client, add the skill, the settings.
+- **[Tools](docs/Tools.md)**: the local and hosted tools, every argument, what comes back, and what the errors mean.
+- **[Workflows](docs/Workflows.md)**: compare music, save favorites, export video and master final loudness.
+- **[Levels](docs/Levels.md)**: how the music level is set by measured loudness, the ducking, and which numbers to pick for which content.
+- **[Tracks](docs/Tracks.md)**: the eighteen tracks and eight stems, their moods and energy, and matching music to content.
+- **[Architecture](docs/Architecture.md)**: one engine in two places, streaming to disk, and the ffmpeg mix step by step.
+- **[File Map](docs/File-Map.md)**: where everything lives.
+- **[Updating the Engine](docs/Updating-the-Engine.md)**: copying a new engine or new tracks in from bckgrnd-msc.
+- **[Development](docs/Development.md)**: the gates, what the tests check, and releasing.
+- **[Change Summary](docs/Change-summary.md)**: the full dated release history.
+- **[The skill](skills/background-music/SKILL.md)**: what the agent reads.
+
+Design decisions live in **[docs/adr/](docs/adr/INDEX.md)**. Each one says what was
+decided, what was turned down, and what would make it the wrong call later.
+
+| ADR | Decision |
+|---|---|
+| [001](docs/adr/001-typescript-server-over-vendored-wasm.md) | A TypeScript server runs bckgrnd-msc's own `.wasm` build, and ffmpeg does the mix |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `bckgrnd_list_tracks` | The eighteen tracks, with bpm, mood, energy (1 to 5) and what each one suits |
+| `bckgrnd_render_track` | One track to a 48 kHz stereo WAV of any length, up to an hour. Cut any stems, set the fades |
+| `bckgrnd_preview_tracks` | Automatically select an audible excerpt and compare up to three tracks locally or hosted |
+| `bckgrnd_mix_under_voice` | Narration plus music to MP3/WAV, with optional presets, ducking strength, evolving arrangements and final mastering |
+| `bckgrnd_mix_video` | Synchronized MP4 export, copying the original picture (local) |
+| `bckgrnd_presets` | Save, list, retrieve and delete favorite mix settings (local) |
+| `bckgrnd_check_setup` | Check dependencies, output access and the actual music engine (local) |
+
+Rendering runs about **20x faster** than real time. Seven minutes of music takes
+about eighteen seconds.
+
+## Tech Stack
+
+- **Rust → WebAssembly**: the bckgrnd-msc engine, built with `wasm-pack`, copied into `vendor/`
+- **TypeScript** on **Node 20+**: the server
+- **MCP TypeScript SDK**: the protocol, over stdio
+- **Zod**: tool argument checking
+- **ffmpeg**: loudness measuring (`ebur128`), ducking (`sidechaincompress`) and MP3 encoding
+- **Vitest**: tests against the real server, real audio and real ffmpeg
+
+## Changelog
+
+Latest release below. Full dated history → **[docs/Change-summary.md](docs/Change-summary.md)**.
+
+### v0.3.0: 10-31-2026
+
+Automatic preview selection and recommendations, persistent favorite presets,
+three ducking strengths, synchronized video export, evolving stem arrangements,
+finished-export mastering and a setup health check. Seven local tools and four
+hosted tools. The companion skill covers the complete workflow for Claude and
+Codex. Existing calls retain their defaults; limiter delay is now compensated.
+
+### v0.2.0: 10-21-2026
+
+Vercel HTTP hosting, atomic file writes, unique render filenames, cancellation
+and progress, measured export loudness/true peak, narration previews, and CI
+with isolated package-install checks. The hosted service has three tools; the
+local server adds `bckgrnd_preview_tracks`.
+
+### v0.1.0: 10-21-2026
+
+**First release. Music under a voice, with levels set by measured loudness.**
+
+Three tools: list the tracks, render one to a WAV, and mix one under a narration.
+The mix measures both files, sets the voice to -16 LUFS and the music 14 LU under
+it, and dips the music while the voice talks. A quiet voice file and a loud one
+come out at the same level. The `background-music` skill matches tracks to content.
+
+## License
+
+MIT

package/dist/doctor.js

@@ -0,0 +1,52 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tool } from './mix.js';
+import { defaultOutDir } from './paths.js';
+import { findTrack, listTracks } from './library.js';
+import { renderTrack } from './render.js';
+import { toolJob } from './jobs.js';
+export async function checkSetup(job = {}) {
+    const checks = [];
+    checks.push({ name: 'Node.js', ok: Number(process.versions.node.split('.')[0]) >= 20, detail: process.version });
+    for (const name of ['ffmpeg', 'ffprobe']) {
+        try {
+            const { stdout } = await tool(process.env[name === 'ffmpeg' ? 'FFMPEG_PATH' : 'FFPROBE_PATH'] || name, ['-version'], job);
+            checks.push({ name, ok: true, detail: stdout.split('\n')[0] ?? name });
+        }
+        catch (error) {
+            checks.push({ name, ok: false, detail: error.message });
+        }
+    }
+    let scratch;
+    try {
+        scratch = mkdtempSync(join(defaultOutDir(), '.health-'));
+        writeFileSync(join(scratch, 'write-check'), 'ok');
+        checks.push({ name: 'output folder', ok: true, detail: defaultOutDir() });
+        const tracks = listTracks();
+        const rendered = await renderTrack({ ...job, track: findTrack('rain'), seconds: 0.5, outputPath: join(scratch, 'engine.wav') });
+        checks.push({ name: 'music engine', ok: tracks.length === 18 && rendered.peak_dbfs > -70, detail: `${tracks.length} tracks; WASM rendered a short audio check.` });
+    }
+    catch (error) {
+        checks.push({ name: scratch ? 'music engine' : 'output folder', ok: false, detail: error.message });
+    }
+    finally {
+        if (scratch)
+            rmSync(scratch, { recursive: true, force: true });
+    }
+    return { ok: checks.every((c) => c.ok), checks,
+        connections: {
+            claude: 'claude mcp add bckgrnd-msc -- pnpm dlx https://github.com/chrislanejones/bckgrnd-msc-mcp/releases/download/v0.3.0/bckgrnd-msc-mcp-0.3.0.tgz',
+            codex: 'codex mcp add bckgrnd-msc -- pnpm dlx https://github.com/chrislanejones/bckgrnd-msc-mcp/releases/download/v0.3.0/bckgrnd-msc-mcp-0.3.0.tgz',
+            skill: 'pnpm dlx skills add chrislanejones/bckgrnd-msc-mcp --skill background-music',
+        },
+    };
+}
+export function registerDoctor(server) {
+    server.registerTool('bckgrnd_check_setup', {
+        title: 'Check local audio setup', description: 'Check Node, ffmpeg/ffprobe, output-folder access and the actual WASM engine. Writes and removes a tiny temporary render. Returns fixes and Claude/Codex connection commands; it does not change client configuration.',
+        inputSchema: {}, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async (_args, extra) => {
+        const result = await checkSetup(toolJob(extra));
+        return { content: [{ type: 'text', text: result.checks.map((c) => `${c.ok ? 'OK' : 'FAIL'} ${c.name}: ${c.detail}`).join('\n') }], structuredContent: result };
+    });
+}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * bckgrnd-msc-mcp: the bckgrnd-msc stem machine as an MCP server, over stdio.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer, VERSION } from './server.js';
+import { checkSetup } from './doctor.js';
+async function main() {
+    if (process.argv.includes('--check') || process.argv.includes('doctor')) {
+        const result = await checkSetup();
+        console.log(JSON.stringify(result, null, 2));
+        process.exitCode = result.ok ? 0 : 1;
+        return;
+    }
+    if (process.argv.includes('--version')) {
+        console.log(VERSION);
+        return;
+    }
+    if (process.argv.includes('--help')) {
+        console.log('bckgrnd-msc-mcp: stdio MCP server. Use --check (or doctor) to check setup, --version to show version.');
+        return;
+    }
+    await createServer().connect(new StdioServerTransport());
+    // stdout is the protocol channel; anything human-readable goes to stderr.
+    console.error(`bckgrnd-msc-mcp ${VERSION} on stdio`);
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/jobs.js

@@ -0,0 +1,11 @@
+export function toolJob(extra) {
+    const token = extra._meta?.progressToken;
+    return {
+        signal: extra.signal,
+        onProgress: async (progress, message) => {
+            extra.signal.throwIfAborted();
+            if (token !== undefined)
+                await extra.sendNotification({ method: 'notifications/progress', params: { progressToken: token, progress, total: 100, message } });
+        },
+    };
+}

package/dist/library.js

@@ -0,0 +1,47 @@
+/**
+ * The track library, read from the JSON bckgrnd-msc exports.
+ *
+ * `vendor/library/index.json` lists the tracks; each `<id>.json` holds the full
+ * arrangement under `track`, which is the exact object the engine's
+ * `load_track_wasm` parses.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { moodFor } from './moods.js';
+const libraryDir = fileURLToPath(new URL('../vendor/library/', import.meta.url));
+/** The eight stems, in the engine's mixer order (`Stem::ALL`). */
+export const STEMS = ['kick', 'clap', 'hats', 'bass', 'stab', 'lead', 'pad', 'arp'];
+let cached = null;
+/** Every track, in library order. */
+export function listTracks() {
+    if (!cached) {
+        const index = JSON.parse(readFileSync(`${libraryDir}index.json`, 'utf8'));
+        cached = index.tracks.map(({ id, name, section, style, bpm, kind }) => ({
+            id,
+            name,
+            section,
+            style,
+            bpm,
+            kind,
+            ...moodFor(style),
+        }));
+    }
+    return cached;
+}
+/** Find a track by id or display name, ignoring case. */
+export function findTrack(idOrName) {
+    const key = idOrName.trim().toLowerCase();
+    return listTracks().find((t) => t.id === key || t.name.toLowerCase() === key);
+}
+/** The arrangement JSON for one track, ready for `Engine.load_track_wasm`. */
+export function arrangementJson(id) {
+    const file = JSON.parse(readFileSync(`${libraryDir}${id}.json`, 'utf8'));
+    return JSON.stringify(file.track);
+}
+/** An error message that names the tracks that do exist. */
+export function unknownTrackMessage(asked) {
+    const ids = listTracks()
+        .map((t) => t.id)
+        .join(', ');
+    return `No track called "${asked}". Use one of: ${ids}. Call bckgrnd_list_tracks for styles and tempos.`;
+}

package/dist/mix.js

@@ -0,0 +1,183 @@
+/**
+ * Lay a music bed under a narration with ffmpeg.
+ *
+ * Levels are set by measurement, not by guesswork. Both files are measured in
+ * LUFS (EBU R128 integrated loudness, the scale podcasts and streaming services
+ * normalize to), the voice is brought to a target loudness, and the music is set
+ * a fixed number of LU below the voice. A quiet TTS file and a hot podcast take
+ * end up with the same balance.
+ *
+ * The voice is then the key input to a sidechain compressor on the music, so the
+ * bed dips while someone is talking and comes back up in the pauses between
+ * paragraphs. Because the voice has already been brought to its target, the
+ * compressor's threshold means the same thing for every input. The music starts
+ * a moment before the voice and rings out after it, then fades.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve, join } from 'node:path';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { atomicOutput } from './paths.js';
+const run = promisify(execFile);
+const ffmpeg = () => process.env.FFMPEG_PATH || 'ffmpeg';
+const ffprobe = () => process.env.FFPROBE_PATH || 'ffprobe';
+const INSTALL_HINT = 'Install it and try again: macOS "brew install ffmpeg", Debian/Ubuntu "sudo apt install ffmpeg", ' +
+    'Windows "winget install Gyan.FFmpeg". Or point FFMPEG_PATH and FFPROBE_PATH at the binaries.';
+/** ebur128 reports this for digital silence; anything at or below it has no level to match. */
+export const SILENCE_LUFS = -70;
+export class MissingFfmpegError extends Error {
+}
+export async function tool(cmd, args, job = {}) {
+    try {
+        return await run(cmd, args, { maxBuffer: 4 * 1024 * 1024, timeout: 120_000, signal: job.signal, killSignal: 'SIGKILL' });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new MissingFfmpegError(`"${cmd}" isn't installed or isn't on PATH. ${INSTALL_HINT}`, { cause: error });
+        }
+        const stderr = String(error.stderr ?? '').trim();
+        const tail = stderr.split('\n').slice(-4).join('\n');
+        throw new Error(`${cmd} failed: ${tail || error.message}`, { cause: error });
+    }
+}
+/** Length of any file ffmpeg can read, in seconds. */
+export async function durationSeconds(path, job = {}) {
+    const { stdout } = await tool(ffprobe(), ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', path], job);
+    const seconds = Number.parseFloat(stdout.trim());
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new Error(`Couldn't read a duration from ${path}. Is it an audio file?`);
+    }
+    return seconds;
+}
+/** Integrated loudness of a file, in LUFS. */
+export async function loudnessLufs(path, job = {}) {
+    const { stderr } = await tool(ffmpeg(), ['-hide_banner', '-nostats', '-nostdin', '-i', path, '-map', '0:a:0', '-af', 'aformat=channel_layouts=stereo,ebur128=framelog=quiet', '-f', 'null', '-'], job);
+    const lufs = parseIntegratedLoudness(stderr);
+    if (lufs === null)
+        throw new Error(`Couldn't measure the loudness of ${path}.`);
+    return lufs;
+}
+/** Pull "I: -19.6 LUFS" out of ebur128's summary. The last one is the whole file. */
+export function parseIntegratedLoudness(log) {
+    const matches = [...log.matchAll(/^\s*I:\s+(-?\d+(?:\.\d+)?)\s+LUFS/gm)];
+    const last = matches.at(-1);
+    return last ? Number.parseFloat(last[1]) : null;
+}
+/**
+ * The two gains that put the voice at `targetLufs` and the music `musicDb` LU
+ * under it. Silent music is left alone: there's no level to match.
+ */
+export function levelsFor(voiceLufs, musicLufs, targetLufs, musicDb) {
+    const round = (v) => Math.round(v * 10) / 10;
+    const voiceGainDb = voiceLufs > SILENCE_LUFS ? targetLufs - voiceLufs : 0;
+    const musicGainDb = musicLufs > SILENCE_LUFS ? targetLufs + musicDb - musicLufs : 0;
+    return { voiceGainDb: round(voiceGainDb), musicGainDb: round(musicGainDb) };
+}
+/** The `-filter_complex` graph. Exported so the tests can pin it. */
+export function mixGraph(o) {
+    const leadMs = Math.round(o.leadInSeconds * 1000);
+    const fadeStart = Math.max(0, o.totalSeconds - o.tailSeconds).toFixed(3);
+    const fadeDur = Math.max(0.01, o.tailSeconds).toFixed(3);
+    const fmt = 'aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo';
+    const voice = `[0:a:0]${fmt},volume=${o.voiceGainDb}dB,adelay=delays=${leadMs}:all=1,apad[v]`;
+    const bed = `[1:a:0]${fmt},volume=${o.musicGainDb}dB,afade=t=out:st=${fadeStart}:d=${fadeDur}[m]`;
+    // The limiter only catches the odd peak the gain pushed over; levels come from the gains.
+    const out = `amix=inputs=2:duration=longest:normalize=0,alimiter=limit=0.95:level=0:latency=1[out]`;
+    if (!o.duck)
+        return [voice, bed, `[v][m]${out}`].join(';');
+    const compressor = {
+        subtle: 'threshold=0.035:ratio=2:attack=60:release=1200',
+        normal: 'threshold=0.02:ratio=6:attack=30:release=600',
+        strong: 'threshold=0.012:ratio=10:attack=15:release=900',
+    }[o.ducking ?? 'normal'];
+    return [
+        voice,
+        `[v]asplit=2[vkey][vout]`,
+        bed,
+        // With the voice at its target, this threshold sits under speech and over room tone.
+        `[m][vkey]sidechaincompress=${compressor}[md]`,
+        `[vout][md]${out}`,
+    ].join(';');
+}
+export async function mixUnderVoice(o) {
+    if ([o.voicePath, o.musicPath].some((p) => resolve(p) === resolve(o.outputPath)))
+        throw new Error('Output must differ from input files.');
+    return atomicOutput(o.outputPath, o.overwrite, async (temporary) => {
+        if (o.finalLufs === undefined)
+            await mixToFile({ ...o, outputPath: temporary });
+        else {
+            const scratch = mkdtempSync(join(tmpdir(), 'bckgrnd-master-'));
+            try {
+                const raw = join(scratch, 'mix.wav');
+                await mixToFile({ ...o, outputPath: raw });
+                await o.onProgress?.(85, 'Mastering finished mix');
+                await masterAudio(raw, temporary, o.finalLufs, o.truePeakDbfs ?? -1.5, o);
+            }
+            finally {
+                rmSync(scratch, { recursive: true, force: true });
+            }
+        }
+        await o.onProgress?.(90, 'Measuring finished audio');
+        return measureAudio(temporary, o);
+    }, o);
+}
+/** Two-pass normalization of the complete mix, with headroom for lossy encoding. */
+export async function masterAudio(input, output, target, peak, job = {}, codec) {
+    const encoding = codec ?? (output.toLowerCase().endsWith('.wav') ? ['-c:a', 'pcm_s16le'] : ['-c:a', 'libmp3lame', '-q:a', '2']);
+    const { stderr } = await tool(ffmpeg(), ['-hide_banner', '-nostats', '-nostdin', '-i', input, '-map', '0:a:0', '-af', `loudnorm=I=${target}:TP=${peak}:LRA=50:print_format=json`, '-f', 'null', '-'], job);
+    const json = stderr.match(/\{\s*"input_i"[\s\S]*?\}/)?.[0];
+    if (!json)
+        throw new Error('Could not measure the mix for mastering.');
+    const stats = JSON.parse(json);
+    for (const key of ['input_i', 'input_tp', 'input_lra', 'input_thresh', 'target_offset']) {
+        if (!Number.isFinite(Number(stats[key])))
+            throw new Error('Cannot master silent or invalid audio.');
+    }
+    let ceiling = Math.max(-9, peak - 0.3);
+    let normalizationTarget = target;
+    let measured;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const filter = `loudnorm=I=${normalizationTarget}:TP=${ceiling}:LRA=50:measured_I=${stats.input_i}:measured_TP=${stats.input_tp}:measured_LRA=${stats.input_lra}:measured_thresh=${stats.input_thresh}:offset=${stats.target_offset}:linear=true`;
+        await tool(ffmpeg(), ['-v', 'error', '-nostdin', '-y', '-i', input, '-map', '0:a:0', '-af', filter, '-ar', '48000', ...encoding, output], job);
+        measured = await measureAudio(output, job);
+        if (measured.output_true_peak_dbfs <= peak + 0.05 && Math.abs(measured.output_lufs - target) <= 0.3)
+            return;
+        normalizationTarget = Math.max(-70, Math.min(-5, normalizationTarget + target - measured.output_lufs));
+        if (measured.output_true_peak_dbfs > peak + 0.05)
+            ceiling = Math.max(-9, ceiling - (measured.output_true_peak_dbfs - peak) - 0.3);
+    }
+    if (measured.output_true_peak_dbfs > peak + 0.05)
+        throw new Error('Could not meet the requested encoded true-peak ceiling. Try a lower final_lufs target.');
+}
+async function mixToFile(o) {
+    const codec = o.outputPath.toLowerCase().endsWith('.wav') ? ['-c:a', 'pcm_s16le'] : ['-c:a', 'libmp3lame', '-q:a', '2'];
+    await tool(ffmpeg(), [
+        '-hide_banner',
+        '-nostdin',
+        o.overwrite ? '-y' : '-n',
+        '-i', o.voicePath,
+        // Loop the music, so a bed shorter than the voice keeps going; -t cuts it.
+        '-stream_loop', '-1',
+        '-i', o.musicPath,
+        '-filter_complex', mixGraph(o),
+        '-map', '[out]',
+        '-t', o.totalSeconds.toFixed(3),
+        '-ar', '48000',
+        ...codec,
+        o.outputPath,
+    ], o);
+}
+/** Measure the actual encoded export, including ducking, fades and limiting. */
+export async function measureAudio(path, job = {}) {
+    const { stderr } = await tool(ffmpeg(), ['-hide_banner', '-nostats', '-nostdin', '-i', path, '-af', 'ebur128=peak=true:framelog=quiet', '-f', 'null', '-'], job);
+    const loudness = parseIntegratedLoudness(stderr);
+    const peak = [...stderr.matchAll(/Peak:\s+(-?(?:\d+(?:\.\d+)?|inf))\s+dBFS/g)].at(-1);
+    if (loudness === null || !peak)
+        throw new Error('Could not measure the finished audio.');
+    const value = Number(peak[1]);
+    return { output_lufs: loudness, output_true_peak_dbfs: Number.isFinite(value) ? value : -120 };
+}
+export async function extractPreview(input, output, start, seconds, job = {}) {
+    await tool(ffmpeg(), ['-v', 'error', '-nostdin', '-ss', String(start), '-i', input, '-t', String(seconds), '-map', '0:a:0', '-c:a', 'pcm_s16le', '-ar', '48000', output], job);
+}

package/dist/moods.js

@@ -0,0 +1,22 @@
+/**
+ * What each style is for, so an agent can match music to what's being read.
+ *
+ * These are set per style, not per track, and they're editorial: a first pass
+ * from the style and tempo, to be tuned by ear. Energy runs 1 (barely there) to
+ * 5 (wants your attention). Anything at 3 or above competes with dense speech.
+ */
+export const MOODS = {
+    Chillhop: { mood: 'relaxed, unhurried', energy: 1, good_for: ['long articles', 'explainers', 'study notes', 'how-tos'] },
+    Dusty: { mood: 'warm, nostalgic', energy: 1, good_for: ['stories', 'history', 'personal essays', 'memoir'] },
+    Jazz: { mood: 'cozy, jazzy', energy: 1, good_for: ['food and travel', 'culture', 'interviews', 'reviews'] },
+    Deep: { mood: 'moody, late-night', energy: 2, good_for: ['tech and science', 'analysis', 'night reading'] },
+    House: { mood: 'upbeat, steady four-on-the-floor', energy: 3, good_for: ['news roundups', 'product updates', 'changelogs', 'demos'] },
+    Acid: { mood: 'intense, squelchy', energy: 4, good_for: ['hype reels', 'launch trailers'] },
+    Garage: { mood: 'bouncy, swung', energy: 3, good_for: ['pop culture', 'sports', 'light commentary'] },
+    Breakbeat: { mood: 'energetic, rave', energy: 4, good_for: ['gaming', 'trailers', 'montages'] },
+    'Liquid DnB': { mood: 'fast but smooth', energy: 3, good_for: ['recaps', 'fast-paced explainers', 'workouts'] },
+};
+const UNKNOWN = { mood: 'unrated', energy: 3, good_for: [] };
+export function moodFor(style) {
+    return MOODS[style] ?? UNKNOWN;
+}

package/dist/paths.js

@@ -0,0 +1,48 @@
+/**
+ * Where output goes, and the checks that keep a tool call from writing somewhere
+ * it shouldn't.
+ *
+ * An MCP server is started by the client from a working directory nobody chose,
+ * so relative paths are refused rather than guessed at.
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync, renameSync, linkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, extname, isAbsolute, join } from 'node:path';
+/** Build beside the destination, then publish atomically without a check/write race. */
+export async function atomicOutput(path, overwrite, work, job = {}) {
+    job.signal?.throwIfAborted();
+    const dir = mkdtempSync(join(dirname(path), '.bckgrnd-'));
+    try {
+        const temporary = join(dir, basename(path));
+        const result = await work(temporary);
+        job.signal?.throwIfAborted();
+        if (overwrite)
+            renameSync(temporary, path);
+        else
+            linkSync(temporary, path);
+        return result;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** `BCKGRND_MSC_OUT_DIR`, or a folder in the system temp directory. */
+export function defaultOutDir() {
+    const dir = process.env.BCKGRND_MSC_OUT_DIR || join(tmpdir(), 'bckgrnd-msc');
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/**
+ * Validate an output path and return a message if it can't be used.
+ * Returns null when the path is fine.
+ */
+export function outputProblem(path, allowed, overwrite) {
+    if (!isAbsolute(path))
+        return `output_path must be absolute, got "${path}".`;
+    const ext = extname(path).toLowerCase();
+    if (!allowed.includes(ext))
+        return `output_path must end in ${allowed.join(' or ')}, got "${ext || 'no extension'}".`;
+    if (!overwrite && existsSync(path))
+        return `${path} already exists. Pass overwrite: true to replace it, or pick another output_path.`;
+    return null;
+}

package/dist/presets.js

@@ -0,0 +1,68 @@
+import { mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, isAbsolute } from 'node:path';
+import { z } from 'zod';
+import { atomicOutput } from './paths.js';
+import { findTrack, unknownTrackMessage } from './library.js';
+import { mixSettingsSchema, presetNameSchema } from './settings.js';
+export function presetDir() {
+    const root = process.env.BCKGRND_MSC_CONFIG_DIR ?? join(homedir(), '.config', 'bckgrnd-msc');
+    if (!isAbsolute(root))
+        throw new Error('BCKGRND_MSC_CONFIG_DIR must be absolute.');
+    return join(root, 'presets');
+}
+function presetPath(name) { return join(presetDir(), `${presetNameSchema.parse(name)}.json`); }
+export function readPreset(name) {
+    const path = presetPath(name);
+    if (!existsSync(path))
+        throw new Error(`No preset called "${name}". List saved settings with bckgrnd_presets.`);
+    return mixSettingsSchema.parse(JSON.parse(readFileSync(path, 'utf8')));
+}
+export function resolveSettings(input) {
+    const explicit = Object.fromEntries(Object.entries(input).filter(([key, value]) => key in mixSettingsSchema.shape && value !== undefined));
+    const settings = { ...(input.preset ? readPreset(input.preset) : {}), ...explicit };
+    if (input.music_path && input.track === undefined)
+        delete settings.track;
+    return mixSettingsSchema.parse(settings);
+}
+export function registerPresets(server) {
+    server.registerTool('bckgrnd_presets', {
+        title: 'Save and reuse favorite mix settings',
+        description: 'List, get, save or delete local named presets. Saves track, levels, ducking, stem cuts, arrangement and intro/outro/mastering settings, never media paths. save refuses an existing name unless overwrite:true. Explicit mix arguments override a preset.',
+        inputSchema: {
+            action: z.enum(['list', 'get', 'save', 'delete']), name: presetNameSchema.optional(),
+            settings: mixSettingsSchema.optional(), overwrite: z.boolean().default(false),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    }, async ({ action, name, settings, overwrite }) => {
+        try {
+            if (action === 'list') {
+                const names = existsSync(presetDir()) ? readdirSync(presetDir()).filter((f) => /^[a-z0-9][a-z0-9-]{0,63}\.json$/.test(f)).map((f) => f.slice(0, -5)).sort() : [];
+                return { content: [{ type: 'text', text: names.join('\n') || 'No saved presets yet.' }], structuredContent: { presets: names } };
+            }
+            if (!name)
+                throw new Error(`name is required for ${action}.`);
+            if (action === 'save') {
+                if (!settings || Object.keys(settings).length === 0)
+                    throw new Error('Provide at least one setting to save.');
+                if (settings.track && !findTrack(settings.track))
+                    throw new Error(unknownTrackMessage(settings.track));
+                if (settings.true_peak_dbfs !== undefined && settings.final_lufs === undefined)
+                    throw new Error('Set final_lufs when specifying a true-peak ceiling.');
+                mkdirSync(presetDir(), { recursive: true });
+                if (!overwrite && existsSync(presetPath(name)))
+                    throw new Error(`Preset "${name}" already exists. Use overwrite:true to replace it.`);
+                await atomicOutput(presetPath(name), overwrite, async (temporary) => { writeFileSync(temporary, JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 }); });
+            }
+            if (action === 'delete') {
+                readPreset(name);
+                unlinkSync(presetPath(name));
+            }
+            const result = { name, ...(action === 'delete' ? { deleted: true } : { settings: readPreset(name) }) };
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: error.message }] };
+        }
+    });
+}