@williamzujkowski/live-coding-music-mcp 4.0.0 → 4.1.0

package/dist/services/AudioExportService.js

@@ -0,0 +1,318 @@
+/**
+ * AudioExportService - records live Strudel audio and writes it to disk
+ *
+ * `audio_capture` returns base64 inline in the MCP response. For a 30s
+ * capture that is roughly 1.5MB of response text — hundreds of thousands
+ * of tokens dropped into the calling agent's context, for data the agent
+ * cannot listen to anyway. And WebM/Opus is not what a DAW or a person
+ * wants at the other end (#223).
+ *
+ * This service exports instead: record a window, decode and encode it
+ * *in the browser*, and hand back a path.
+ *
+ * Everything that can happen in page context does. The bytes cross the
+ * CDP boundary once, as a base64 string, because that is the only shape
+ * Playwright serializes losslessly — returning a `Blob` yields `{}` on the
+ * Node side with no `arrayBuffer` method, which is the bug that made
+ * `audio_capture` silently broken since it was written.
+ *
+ * @module services/AudioExportService
+ * @nist si-10 "Information input validation"
+ * @nist ac-3 "Access enforcement"
+ */
+import { mkdirSync, writeFileSync } from 'fs';
+import { Logger } from '../utils/Logger.js';
+import { resolveSafeOutputPath, resolveExportDirectory } from '../utils/SafePath.js';
+/** Longest window a single export may record. */
+export const MAX_EXPORT_DURATION_MS = 30_000;
+/** Shortest window worth recording. */
+export const MIN_EXPORT_DURATION_MS = 100;
+/**
+ * Peak amplitude at or below which a capture counts as silent.
+ *
+ * Strudel's graph emits a low noise floor even with nothing playing, so
+ * an exact-zero test would never fire and every silent export would be
+ * reported as successful audio.
+ */
+export const SILENCE_PEAK_THRESHOLD = 0.0005;
+export class AudioExportService {
+    exportDir;
+    logger;
+    /**
+     * @param exportDir - Directory exports are confined to (default `./exports`)
+     */
+    constructor(exportDir) {
+        this.exportDir = resolveExportDirectory(exportDir);
+        this.logger = new Logger();
+    }
+    /** Directory this service writes to. */
+    getExportDirectory() {
+        return this.exportDir;
+    }
+    /**
+     * Records a window of live audio and exports it.
+     *
+     * @param page - Page with the Strudel audio graph, already playing
+     * @param options - Duration, format, filename, and output mode
+     * @returns Path or base64 payload, plus what was actually recorded
+     *
+     * @example
+     * const result = await service.exportAudio(page, { duration: 3000 });
+     * // -> { success: true, path: '<cwd>/exports/capture.wav', silent: false, ... }
+     */
+    async exportAudio(page, options = {}) {
+        const format = options.format ?? 'wav';
+        const output = options.output ?? 'file';
+        const duration = options.duration ?? 5000;
+        if (!Number.isFinite(duration) || duration < MIN_EXPORT_DURATION_MS || duration > MAX_EXPORT_DURATION_MS) {
+            return {
+                success: false,
+                bytes: 0,
+                duration: 0,
+                format,
+                error: `Invalid duration: ${String(options.duration)}. ` +
+                    `Must be between ${MIN_EXPORT_DURATION_MS} and ${MAX_EXPORT_DURATION_MS} ms.`,
+            };
+        }
+        let payload;
+        try {
+            payload = await page.evaluate(AudioExportService.browserCapture, { durationMs: duration, wantWav: format === 'wav' });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { success: false, bytes: 0, duration: 0, format, error: `Audio export failed: ${message}` };
+        }
+        if (!payload.success || payload.base64 === undefined) {
+            return {
+                success: false,
+                bytes: 0,
+                duration: 0,
+                format,
+                error: payload.error ?? 'Audio export failed for an unknown reason.',
+            };
+        }
+        const bytes = Buffer.from(payload.base64, 'base64');
+        const warnings = [];
+        // Report silence rather than writing a silent file and calling it a
+        // success — the caller has no way to hear the difference (#223).
+        const silent = payload.peak !== undefined && payload.peak <= SILENCE_PEAK_THRESHOLD;
+        if (silent) {
+            warnings.push('Captured audio is silent. Is a pattern playing? ' +
+                'Call playback({ action: "play" }) before exporting.');
+        }
+        else if (payload.peak === undefined) {
+            // Not measured is not the same as not silent.
+            //
+            // A WebM capture the browser could not decode returns without a
+            // peak, so `silent` is false and the check above never fires. The
+            // tool promises it "reports silent captures instead of writing a
+            // silent file and claiming success" — and that promise was kept
+            // by staying quiet about a file it had not been able to look at
+            // (#437 item 2). Say so instead.
+            warnings.push('Captured audio could not be decoded, so it was not checked for silence. '
+                + 'The bytes are the recorder\'s own output and may be empty.');
+        }
+        const base = {
+            success: true,
+            bytes: bytes.length,
+            duration: payload.duration ?? duration,
+            format,
+            ...(payload.sampleRate !== undefined ? { sampleRate: payload.sampleRate } : {}),
+            ...(payload.channels !== undefined ? { channels: payload.channels } : {}),
+            ...(payload.peak !== undefined ? { peak: payload.peak, rms: payload.rms, silent } : {}),
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+        if (output === 'base64') {
+            return { ...base, audio: payload.base64 };
+        }
+        try {
+            const target = resolveSafeOutputPath(options.filename, {
+                directory: this.exportDir,
+                extension: format === 'wav' ? '.wav' : '.webm',
+                defaultName: `strudel-capture-${String(Date.now())}.${format}`,
+            });
+            mkdirSync(this.exportDir, { recursive: true });
+            writeFileSync(target.path, bytes);
+            this.logger.debug(`Exported ${String(bytes.length)} bytes to ${target.path}`);
+            return {
+                ...base,
+                path: target.path,
+                ...(target.wasModified
+                    ? { sanitizedFilename: target.filename, requestedFilename: target.requested }
+                    : {}),
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { ...base, success: false, error: `Failed to write audio file: ${message}` };
+        }
+    }
+    /**
+     * Runs in page context: record, decode, measure, encode.
+     *
+     * Defined as a static so the function passed to `page.evaluate` is a
+     * plain closure over its argument with no `this` — Playwright
+     * serializes the source, so anything captured from the enclosing scope
+     * would be undefined at runtime.
+     *
+     * Returns base64 rather than a Blob or Uint8Array: a Blob does not
+     * survive the CDP boundary at all, and a large typed array round-trips
+     * as a slow object map.
+     */
+    /* istanbul ignore next -- runs in the browser; covered by npm run test:export-audio */
+    static browserCapture = async (args) => {
+        const capture = window.strudelAudioCapture;
+        if (!capture) {
+            return { success: false, error: 'Audio recorder not injected. Run init first.' };
+        }
+        if (!capture.isConnected) {
+            return {
+                success: false,
+                error: 'Audio recorder not connected to Strudel output. Play a pattern first.',
+            };
+        }
+        if (capture.isCapturing) {
+            return { success: false, error: 'A capture is already in progress.' };
+        }
+        const started = capture.startCapture();
+        if (started.success !== true) {
+            return { success: false, error: started.error ?? 'Failed to start capture.' };
+        }
+        await new Promise(resolve => setTimeout(resolve, args.durationMs));
+        const stopped = await capture.stopCapture();
+        if (stopped.success !== true || !stopped.blob) {
+            return { success: false, error: stopped.error ?? 'Capture produced no audio.' };
+        }
+        const recorded = await stopped.blob.arrayBuffer();
+        // Helpers live as object METHODS, not `const fn = () => {}`.
+        // esbuild (which tsx uses) rewrites a named inner function into
+        // `__name(fn, "fn")` to preserve `.name`, and `__name` does not exist
+        // in page context — so the whole evaluate throws
+        // `ReferenceError: __name is not defined` under `npm run dev`, while
+        // working fine from `dist/` where tsc emits it untouched. Method
+        // shorthand is the one form esbuild leaves alone.
+        const h = {
+            toBase64(buffer) {
+                const view = new Uint8Array(buffer);
+                let binary = '';
+                // Chunked: String.fromCharCode(...view) blows the stack on a
+                // multi-megabyte capture.
+                const CHUNK = 0x8000;
+                for (let i = 0; i < view.length; i += CHUNK) {
+                    binary += String.fromCharCode(...view.subarray(i, i + CHUNK));
+                }
+                return btoa(binary);
+            },
+            writeAscii(view, offset, text) {
+                for (let i = 0; i < text.length; i++)
+                    view.setUint8(offset + i, text.charCodeAt(i));
+            },
+        };
+        // Decode for BOTH formats.
+        //
+        // The webm path used to return here, before anything measured the
+        // signal — so `peak` was undefined, the silence check upstream
+        // (`payload.peak !== undefined && ...`) was false, and a silent webm
+        // was reported as a clean export. The tool description promises
+        // "Reports silent captures instead of writing a silent file and
+        // claiming success" with no format qualifier, and that promise held
+        // only for wav (#437).
+        //
+        // webm still ships the ORIGINAL Opus bytes; the decode is only to
+        // measure them. A decode failure is fatal for wav, which needs the
+        // samples, and merely means "no peak reported" for webm, which does
+        // not.
+        const AudioCtx = window.AudioContext ?? window.webkitAudioContext;
+        const ctx = new AudioCtx();
+        let decoded = null;
+        let decodeError = '';
+        try {
+            decoded = await ctx.decodeAudioData(recorded.slice(0));
+        }
+        catch (error) {
+            decodeError = String(error?.message ?? error);
+        }
+        if (decoded === null) {
+            await ctx.close();
+            if (args.wantWav) {
+                return { success: false, error: `Failed to decode captured audio: ${decodeError}` };
+            }
+            return { success: true, base64: h.toBase64(recorded), duration: stopped.duration };
+        }
+        const channels = decoded.numberOfChannels;
+        const frames = decoded.length;
+        const sampleRate = decoded.sampleRate;
+        const channelData = [];
+        for (let c = 0; c < channels; c++)
+            channelData.push(decoded.getChannelData(c));
+        // Measure before quantising, so the numbers describe the real signal.
+        let peak = 0;
+        let sumSquares = 0;
+        for (const data of channelData) {
+            for (let i = 0; i < data.length; i++) {
+                const v = Math.abs(data[i]);
+                if (v > peak)
+                    peak = v;
+                sumSquares += data[i] * data[i];
+            }
+        }
+        const rms = frames > 0 ? Math.sqrt(sumSquares / (frames * channels)) : 0;
+        if (!args.wantWav) {
+            await ctx.close();
+            return {
+                success: true,
+                base64: h.toBase64(recorded),
+                // The audio's own length, not the wall clock. `stopped.duration`
+                // is `Date.now() - startTime`, which counts the time spent
+                // starting and stopping the recorder as if it were sound (#437).
+                duration: Math.round((frames / sampleRate) * 1000),
+                peak,
+                rms,
+                sampleRate,
+                channels,
+            };
+        }
+        // 16-bit PCM WAV: 44-byte RIFF header then interleaved samples.
+        const bytesPerSample = 2;
+        const blockAlign = channels * bytesPerSample;
+        const dataSize = frames * blockAlign;
+        const buffer = new ArrayBuffer(44 + dataSize);
+        const view = new DataView(buffer);
+        h.writeAscii(view, 0, 'RIFF');
+        view.setUint32(4, 36 + dataSize, true);
+        h.writeAscii(view, 8, 'WAVE');
+        h.writeAscii(view, 12, 'fmt ');
+        view.setUint32(16, 16, true); // PCM chunk size
+        view.setUint16(20, 1, true); // format: PCM
+        view.setUint16(22, channels, true);
+        view.setUint32(24, sampleRate, true);
+        view.setUint32(28, sampleRate * blockAlign, true);
+        view.setUint16(32, blockAlign, true);
+        view.setUint16(34, 16, true); // bits per sample
+        h.writeAscii(view, 36, 'data');
+        view.setUint32(40, dataSize, true);
+        let offset = 44;
+        for (let i = 0; i < frames; i++) {
+            for (let c = 0; c < channels; c++) {
+                const sample = Math.max(-1, Math.min(1, channelData[c][i]));
+                view.setInt16(offset, sample < 0 ? sample * 0x8000 : sample * 0x7fff, true);
+                offset += bytesPerSample;
+            }
+        }
+        await ctx.close();
+        return {
+            success: true,
+            base64: h.toBase64(buffer),
+            // The audio's own length. `stopped.duration` is
+            // `Date.now() - startTime`, so it counted the time spent starting
+            // and stopping the recorder as if it were sound — and a caller
+            // could compute (bytes - 44) / (sampleRate * channels * 2) from
+            // this very response and get a different answer (#437).
+            duration: Math.round((frames / sampleRate) * 1000),
+            sampleRate,
+            channels,
+            peak,
+            rms,
+        };
+    };
+}

package/dist/services/BrowserOnlyFunctions.js

@@ -0,0 +1,149 @@
+/**
+ * Strudel functions the local engine cannot provide.
+ *
+ * `StrudelEngine` builds its context from @strudel/core, @strudel/mini and
+ * @strudel/tonal. strudel.cc loads considerably more: sample loaders that
+ * fetch over the network, transport controls that need a running
+ * scheduler, MIDI/OSC bridges, and the visualisers, which draw to a
+ * canvas.
+ *
+ * Without this list those all fail with errors that blame the pattern:
+ *
+ *   setcpm(120)          -> "references unknown identifier 'setcpm'"
+ *   s("bd").pianoroll()  -> "s(...).pianoroll is not a function"
+ *   samples("github:..") -> "Invalid argument"
+ *
+ * `setcpm` is the one that shows why this matters — it is a core, very
+ * common Strudel function, and telling someone it is an unknown
+ * identifier reads as "you typo'd" when the truth is "this validator
+ * cannot see it". Local and browser validation disagreeing about the same
+ * pattern is bad; disagreeing *and* misattributing the cause is worse.
+ *
+ * Every name here was verified to fail locally before being listed (#232).
+ *
+ * @module services/BrowserOnlyFunctions
+ */
+/** Functions that exist on strudel.cc but not in the local engine. */
+export const BROWSER_ONLY_FUNCTIONS = new Map([
+    // Transport: need a running scheduler, which the local engine has no
+    // equivalent of — it builds patterns, it does not play them.
+    ['setcpm', 'transport'],
+    // Lowercase. It was listed as 'setCps', which Strudel does not have,
+    // so `setcps(170/60)` fell through to "references unknown identifier
+    // 'setcps'" — the reads-as-a-typo message #232 exists to remove. The
+    // mechanism was fine; the key was mis-cased, which is invisible on
+    // inspection because the entry looks present (#355).
+    ['setcps', 'transport'],
+    ['getcps', 'transport'],
+    ['hush', 'transport'],
+    // Siblings of hush and setcpm, and just as absent locally. Without
+    // them, panic() and getcpm() produced the "references unknown
+    // identifier — reads as a typo" message that #232 was filed to
+    // remove (#343).
+    ['panic', 'transport'],
+    ['getcpm', 'transport'],
+    ['all', 'transport'],
+    // Used by two of Strudel's own flagship tunes (flatrave, amensister),
+    // so anyone pasting a real pattern in hits it immediately.
+    ['useRNG', 'transport'],
+    // Loaders: fetch sample banks over the network at evaluation time.
+    ['samples', 'loader'],
+    // An instrument shortcut, not a free identifier — it fails as
+    // "note(...).piano is not a function" rather than as an unknown
+    // name, so the allowlist never saw it. findBrowserOnlyCall matches
+    // `.name(` as well as `name(`, so listing it is enough (#355).
+    ['piano', 'loader'],
+    // Visualisers: draw to a canvas.
+    ['pianoroll', 'visual'],
+    ['scope', 'visual'],
+    ['punchcard', 'visual'],
+    ['spiral', 'visual'],
+    ['wordfall', 'visual'],
+    ['animate', 'visual'],
+    ['initHydra', 'visual'],
+    ['H', 'visual'],
+    ['P5', 'visual'],
+    // Bridges to hardware or other processes.
+    ['midi', 'io'],
+    ['osc', 'io'],
+]);
+const REASON_TEXT = {
+    transport: 'controls playback, which the local engine does not run',
+    loader: 'loads samples over the network',
+    visual: 'draws to a canvas',
+    io: 'bridges to MIDI/OSC hardware',
+};
+/**
+ * Explains that a function is real but unavailable locally.
+ *
+ * @param name - Function the pattern referenced
+ * @returns An explanation, or null when the name is not browser-only
+ */
+export function explainBrowserOnly(name) {
+    const reason = BROWSER_ONLY_FUNCTIONS.get(name);
+    if (reason === undefined)
+        return null;
+    return (`'${name}' is a real Strudel function, but it ${REASON_TEXT[reason]}, ` +
+        'so local validation cannot evaluate it. The pattern may be perfectly ' +
+        'valid — check it in the browser with validate_pattern_runtime, or ' +
+        'remove this call to validate the rest locally.');
+}
+/**
+ * Finds a browser-only function called in pattern source.
+ *
+ * Error-message matching is not enough on its own. `samples("github:...")`
+ * fails as "Invalid argument", because the transpiler rewrites every
+ * double-quoted string into a `mini()` call and a URL is not mini
+ * notation — so the failure never mentions `samples` at all. Scanning the
+ * source catches those too.
+ *
+ * @param code - Strudel pattern source
+ * @returns The first browser-only function called, or null
+ */
+export function findBrowserOnlyCall(code) {
+    // Comments are not calls.
+    //
+    // The regex only guarded the single character before the name, so a
+    // mention inside a comment matched. This is consulted on the ERROR
+    // path, so the effect was misattribution rather than false
+    // rejection — but it fired ahead of the real diagnosis: an
+    // unterminated string with `samples("x")` in a trailing comment was
+    // reported as "samples loads over the network" instead of as the
+    // syntax error it is (#343).
+    const withoutComments = code
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/\/\/[^\n]*/g, ' ');
+    for (const name of BROWSER_ONLY_FUNCTIONS.keys()) {
+        // Called as a function or chained as a method, not merely mentioned
+        // inside a string.
+        const called = new RegExp(`(^|[^\\w$."'])${name}\\s*\\(|\\.${name}\\s*\\(`);
+        if (called.test(withoutComments))
+            return name;
+    }
+    return null;
+}
+/**
+ * Rewrites an engine error when a browser-only function caused it.
+ *
+ * Handles both shapes the failure takes: an allowlist rejection for a
+ * bare call, and a "not a function" runtime error for a method call.
+ *
+ * @param message - The original error
+ * @returns A clearer message, or the original when nothing applies
+ */
+export function clarifyEngineError(message) {
+    const patterns = [
+        /unknown identifier '([A-Za-z_$][\w$]*)'/,
+        /\.\.\.\)\.([A-Za-z_$][\w$]*) is not a function/,
+        /([A-Za-z_$][\w$]*) is not a function/,
+    ];
+    for (const pattern of patterns) {
+        const found = pattern.exec(message);
+        if (found === null)
+            continue;
+        const explanation = explainBrowserOnly(found[1]);
+        if (explanation !== null)
+            return explanation;
+    }
+    return message;
+}