bckgrnd-msc-mcp 0.0.0-stage → 0.2.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,110 @@
-# 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 version 0.2.0:
+
+```sh
+claude mcp add bckgrnd-msc -- pnpm dlx bckgrnd-msc-mcp@0.2.0
+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)**.
+
+## 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.
+- **[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` | Compare up to three tracks under the same short narration excerpt (local server) |
+| `bckgrnd_mix_under_voice` | A voice file plus a track, or your own music file, to one MP3 or WAV |
+
+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.2.0: 10-21-2026 — package publication pending
+
+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/index.js

@@ -0,0 +1,15 @@
+#!/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';
+async function main() {
+    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,135 @@
+/**
+ * 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 } from 'node:path';
+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 {
+}
+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, '-af', '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]${fmt},volume=${o.voiceGainDb}dB,adelay=delays=${leadMs}:all=1,apad[v]`;
+    const bed = `[1:a]${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[out]`;
+    if (!o.duck)
+        return [voice, bed, `[v][m]${out}`].join(';');
+    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=threshold=0.02:ratio=6:attack=30:release=600[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) => {
+        await mixToFile({ ...o, outputPath: temporary });
+        await o.onProgress?.(90, 'Measuring finished audio');
+        return measureAudio(temporary, o);
+    }, o);
+}
+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/preview.js

@@ -0,0 +1,79 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { z } from 'zod';
+import { findTrack, STEMS, unknownTrackMessage } from './library.js';
+import { defaultOutDir } from './paths.js';
+import { durationSeconds, extractPreview } from './mix.js';
+import { toolJob } from './jobs.js';
+export function registerPreview(server) {
+    server.registerTool('bckgrnd_preview_tracks', {
+        title: 'Compare music under a narration excerpt',
+        description: 'Compare one to three tracks under the same 15–30 second narration excerpt before committing to a full mix. Returns separate MP3 paths and measured levels. Use start_seconds to select the excerpt.',
+        inputSchema: {
+            voice_path: z.string().min(1),
+            tracks: z.array(z.string().min(1)).min(1).max(3),
+            seconds: z.number().min(15).max(30).default(20),
+            start_seconds: z.number().min(0).default(0),
+            cut: z.array(z.enum(STEMS)).optional(),
+            music_db: z.number().min(-40).max(0).default(-14),
+            loudness_lufs: z.number().min(-30).max(-9).default(-16),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async (args, extra) => {
+        const job = toolJob(extra);
+        let scratch;
+        let outDir;
+        let complete = false;
+        let client;
+        let internal;
+        try {
+            if (!isAbsolute(args.voice_path))
+                throw new Error('voice_path must be absolute.');
+            for (const name of args.tracks)
+                if (!findTrack(name))
+                    throw new Error(unknownTrackMessage(name));
+            const duration = await durationSeconds(args.voice_path, job);
+            if (args.start_seconds >= duration)
+                throw new Error('start_seconds must be before the end of the narration.');
+            scratch = mkdtempSync(join(tmpdir(), 'bckgrnd-preview-'));
+            outDir = mkdtempSync(join(defaultOutDir(), 'previews-'));
+            const excerpt = join(scratch, 'excerpt.wav');
+            await extractPreview(args.voice_path, excerpt, args.start_seconds, args.seconds, job);
+            const { createServer } = await import('./server.js');
+            internal = createServer();
+            client = new Client({ name: 'preview', version: '1' });
+            const [a, b] = InMemoryTransport.createLinkedPair();
+            await internal.connect(b);
+            await client.connect(a);
+            const previews = [];
+            for (const [i, track] of args.tracks.entries()) {
+                job.signal?.throwIfAborted();
+                const result = await client.callTool({ name: 'bckgrnd_mix_under_voice', arguments: {
+                        voice_path: excerpt, track, cut: args.cut, music_db: args.music_db,
+                        loudness_lufs: args.loudness_lufs, lead_in_seconds: 0, tail_seconds: 1,
+                        output_path: join(outDir, `${i + 1}-${findTrack(track).id}.mp3`),
+                    } }, undefined, { signal: job.signal, timeout: 180_000, onprogress: (p) => { void job.onProgress?.((i * 100 + p.progress) / args.tracks.length, `Preview ${i + 1}: ${p.message ?? track}`).catch(() => { }); } });
+                if (result.isError)
+                    throw new Error(result.content[0]?.text ?? 'Preview mix failed.');
+                previews.push(result.structuredContent);
+            }
+            await job.onProgress?.(100, 'Previews complete');
+            complete = true;
+            return { content: [{ type: 'text', text: previews.map((p) => `${p.music}: ${p.path}`).join('\n') }], structuredContent: { previews, start_seconds: args.start_seconds } };
+        }
+        catch (cause) {
+            return { isError: true, content: [{ type: 'text', text: cause instanceof Error ? cause.message : String(cause) }] };
+        }
+        finally {
+            await client?.close();
+            await internal?.close();
+            if (scratch)
+                rmSync(scratch, { recursive: true, force: true });
+            if (!complete && outDir)
+                rmSync(outDir, { recursive: true, force: true });
+        }
+    });
+}

package/dist/remote.js

@@ -0,0 +1,144 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { fileURLToPath } from 'node:url';
+const ffmpegPath = fileURLToPath(new URL('../vendor/runtime/ffmpeg', import.meta.url));
+const ffprobePath = fileURLToPath(new URL('../vendor/runtime/ffprobe', import.meta.url));
+import { z } from 'zod';
+import { durationSeconds, measureAudio } from './mix.js';
+import { STEMS } from './library.js';
+import { createServer, VERSION } from './server.js';
+const run = promisify(execFile);
+export const MAX_REMOTE_SECONDS = 120;
+export const MAX_UPLOAD_BYTES = 2 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 2_000_000;
+let running = 0;
+function error(message) {
+    return { isError: true, content: [{ type: 'text', text: message }] };
+}
+/** Use the same local tools, but never expose their filesystem arguments remotely. */
+async function localCall(name, args, signal) {
+    const server = createServer();
+    const client = new Client({ name: 'remote-adapter', version: VERSION });
+    const [a, b] = InMemoryTransport.createLinkedPair();
+    try {
+        await server.connect(b);
+        await client.connect(a);
+        return await client.callTool({ name, arguments: args }, undefined, { signal, timeout: 55_000 });
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+async function audioJob(work) {
+    if (running >= 2)
+        return error('This instance is busy. Retry shortly.');
+    running++;
+    let dir;
+    try {
+        if (!ffmpegPath)
+            throw new Error('Audio encoder unavailable on this platform.');
+        process.env.FFMPEG_PATH = ffmpegPath;
+        process.env.FFPROBE_PATH = ffprobePath;
+        dir = await mkdtemp(join(tmpdir(), 'bckgrnd-remote-'));
+        return await work(dir, AbortSignal.timeout(45_000));
+    }
+    catch (cause) {
+        // Do not return ffmpeg stderr or paths from user-supplied media to clients.
+        console.error('Remote audio job failed:', cause instanceof Error ? cause.name : 'unknown');
+        return error('Audio processing failed. Use a valid MP3, WAV, Ogg or FLAC within the upload and duration limits.');
+    }
+    finally {
+        if (dir)
+            await rm(dir, { recursive: true, force: true });
+        running--;
+    }
+}
+async function encodeResult(source, dir, metadata, signal) {
+    const output = join(dir, 'result.mp3');
+    await run(ffmpegPath, ['-v', 'error', '-nostdin', '-i', source, '-map', '0:a:0', '-c:a', 'libmp3lame', '-b:a', '96k', '-t', String(MAX_REMOTE_SECONDS), output], { timeout: 15_000, signal, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024 });
+    const measured = await measureAudio(output, { signal });
+    const data = await readFile(output);
+    if (data.length > MAX_OUTPUT_BYTES)
+        throw new Error('Encoded output exceeds response limit.');
+    return {
+        content: [
+            { type: 'text', text: 'Generated MP3 attached as MCP audio. Save the audio content as an .mp3 file; no public download URL is stored.' },
+            { type: 'audio', mimeType: 'audio/mpeg', data: data.toString('base64') },
+        ],
+        structuredContent: { ...metadata, ...measured, mime_type: 'audio/mpeg', bytes: data.length },
+    };
+}
+const musicArgs = {
+    track: z.string().min(1).max(100).describe('Track id from bckgrnd_list_tracks'),
+    cut: z.array(z.enum(STEMS)).max(8).optional(),
+};
+export function createRemoteServer() {
+    const server = new McpServer({ name: 'bckgrnd-msc', version: VERSION }, {
+        instructions: 'Remote audio tools return embedded MP3 audio, not local paths or download URLs. Clips are limited to 120 seconds. For longer files or agents without audio upload/output support, use the local stdio server.',
+    });
+    server.registerTool('bckgrnd_list_tracks', {
+        description: 'List tracks, moods, energy, tempo and stems. Use this before selecting music.',
+        inputSchema: { section: z.enum(['EDM', 'Lofi', 'Breaks']).optional(), max_energy: z.number().int().min(1).max(5).optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    }, (args) => localCall('bckgrnd_list_tracks', args));
+    server.registerTool('bckgrnd_render_track', {
+        description: 'Render 1–120 seconds of synthesized background music. Returns embedded MP3 audio. No output path is needed. For longer renders use the local server.',
+        inputSchema: {
+            ...musicArgs,
+            seconds: z.number().min(1).max(MAX_REMOTE_SECONDS),
+            fade_in_seconds: z.number().min(0).max(30).default(1),
+            fade_out_seconds: z.number().min(0).max(60).default(4),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, (args) => audioJob(async (dir, signal) => {
+        const output = join(dir, 'render.wav');
+        const result = await localCall('bckgrnd_render_track', { ...args, output_path: output }, signal);
+        if (result.isError)
+            return result;
+        const { path: _path, ...metadata } = result.structuredContent;
+        void _path;
+        return encodeResult(output, dir, metadata, signal);
+    }));
+    server.registerTool('bckgrnd_mix_under_voice', {
+        description: 'Mix a track beneath uploaded narration. Supply actual base64-encoded audio bytes (not a filename). Maximum upload 2 MiB; narration plus lead-in/tail must fit 120 seconds. Returns embedded MP3 audio. Use local stdio for longer files or custom music.',
+        inputSchema: {
+            ...musicArgs,
+            voice_base64: z.string().min(4).max(Math.ceil(MAX_UPLOAD_BYTES / 3) * 4).describe('Base64 file contents, without a data-URL prefix; never invent these bytes'),
+            voice_format: z.enum(['mp3', 'wav', 'ogg', 'flac']),
+            music_db: z.number().min(-40).max(0).default(-14),
+            loudness_lufs: z.number().min(-30).max(-9).default(-16),
+            duck: z.boolean().default(true),
+            lead_in_seconds: z.number().min(0).max(10).default(2),
+            tail_seconds: z.number().min(0).max(10).default(3),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, (args) => audioJob(async (dir, signal) => {
+        const { voice_base64, voice_format, ...mixArgs } = args;
+        const bytes = Buffer.from(voice_base64, 'base64');
+        if (bytes.toString('base64') !== voice_base64 || bytes.length > MAX_UPLOAD_BYTES)
+            return error('Invalid base64 or upload exceeds 2 MiB.');
+        const input = join(dir, 'upload');
+        const voice = join(dir, 'voice.wav');
+        const output = join(dir, 'mixed.wav');
+        await writeFile(input, bytes);
+        // Force a simple audio demuxer: uploaded playlists cannot read server files or URLs.
+        await run(ffmpegPath, ['-v', 'error', '-nostdin', '-protocol_whitelist', 'file,pipe', '-f', voice_format, '-i', input, '-map', '0:a:0', '-t', '121', '-ar', '48000', '-ac', '2', '-c:a', 'pcm_s16le', voice], { timeout: 15_000, signal, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024 });
+        const seconds = await durationSeconds(voice, { signal });
+        if (seconds + args.lead_in_seconds + args.tail_seconds > MAX_REMOTE_SECONDS)
+            return error('Narration plus lead-in and tail exceeds 120 seconds. Use a shorter clip or the local server.');
+        const result = await localCall('bckgrnd_mix_under_voice', { ...mixArgs, voice_path: voice, output_path: output }, signal);
+        if (result.isError)
+            return error('Could not mix this recording. Check that it contains audible speech and that the track exists.');
+        const { path: _path, ...metadata } = result.structuredContent;
+        void _path;
+        return encodeResult(output, dir, metadata, signal);
+    }));
+    return server;
+}