c64bridge 1.0.2 → 1.0.3

package/dist/audio/record_and_analyze_audio.js

@@ -1,9 +1,13 @@
 import { parseSidwave, midiToHz } from "../sidwave.js";
-export async function recordAndAnalyzeAudio(params) {
-    const duration = Math.max(0.5, Math.min(120, Number(params.durationSeconds || 0)));
+export function normalizeAudioDuration(durationSeconds) {
+    const duration = Number(durationSeconds);
     if (!Number.isFinite(duration)) {
         throw new Error("durationSeconds must be a number");
     }
+    return Math.max(0.5, Math.min(120, duration));
+}
+export async function recordAndAnalyzeAudio(params) {
+    const duration = normalizeAudioDuration(params.durationSeconds);
     // Capture PCM from default microphone using naudiodon (PortAudio)
     const sampleRate = 44100;
     const channelCount = 1;
@@ -52,9 +56,49 @@ export async function recordAndAnalyzeAudio(params) {
     });
     const pcm16 = Buffer.concat(chunks);
     const float32 = convertInt16ToFloat32(pcm16);
-    const analysis = await analyzePcm(float32, sampleRate, params.expectedSidwave);
+    const analysis = await analyzePcm(float32, sampleRate, "microphone", params.expectedSidwave);
     return analysis;
 }
+/**
+ * Analyzes interleaved 16-bit stereo PCM captured from the Ultimate audio stream.
+ *
+ * The stream carries a large constant offset per channel even when silent
+ * (for example left 26900, right 20000). The mean of each channel is removed
+ * before analysis; otherwise the RMS measures the offset instead of the audio level.
+ * Analyze channel energy separately, since a mono mix can cancel opposite-phase
+ * audio and falsely verify silence. Pitch and level follow the louder channel in each window.
+ */
+export async function analyzeStereoStream(interleaved, sampleRate, expectedSidwave) {
+    const [left, right] = stereoToCenteredChannels(interleaved);
+    return analyzePcm(left, sampleRate, "ultimate-stream", expectedSidwave, right);
+}
+function stereoToCenteredChannels(interleaved) {
+    const frames = Math.floor(interleaved.length / 2);
+    const left = new Float32Array(frames);
+    const right = new Float32Array(frames);
+    if (frames === 0) {
+        return [left, right];
+    }
+    let leftSum = 0;
+    let rightSum = 0;
+    for (let i = 0; i < frames; i += 1) {
+        leftSum += interleaved[i * 2];
+        rightSum += interleaved[i * 2 + 1];
+    }
+    const leftMean = leftSum / frames;
+    const rightMean = rightSum / frames;
+    for (let i = 0; i < frames; i += 1) {
+        left[i] = (interleaved[i * 2] - leftMean) / 32768;
+        right[i] = (interleaved[i * 2 + 1] - rightMean) / 32768;
+    }
+    return [left, right];
+}
+export function stereoToCenteredMono(interleaved) {
+    const [left, right] = stereoToCenteredChannels(interleaved);
+    for (let i = 0; i < left.length; i += 1)
+        left[i] = (left[i] + right[i]) / 2;
+    return left;
+}
 function convertInt16ToFloat32(buf) {
     const len = Math.floor(buf.length / 2);
     const out = new Float32Array(len);
@@ -64,7 +108,7 @@ function convertInt16ToFloat32(buf) {
     }
     return out;
 }
-async function analyzePcm(signal, sampleRate, expectedSidwave) {
+async function analyzePcm(signal, sampleRate, source, expectedSidwave, secondChannel) {
     let Pitchfinder;
     let Meyda = null;
     try {
@@ -87,13 +131,28 @@ async function analyzePcm(signal, sampleRate, expectedSidwave) {
     const yin = Pitchfinder.YIN({ sampleRate });
     const frames = [];
     for (let i = 0; i + windowSize <= signal.length; i += hopSize) {
-        const win = signal.subarray(i, i + windowSize);
-        const rms = computeRms(win, Meyda, sampleRate, windowSize);
+        let win = signal.subarray(i, i + windowSize);
+        let rms = computeRms(win, Meyda, sampleRate, windowSize);
+        if (secondChannel) {
+            const otherWin = secondChannel.subarray(i, i + windowSize);
+            const otherRms = computeRms(otherWin, Meyda, sampleRate, windowSize);
+            if (otherRms > rms) {
+                rms = otherRms;
+                win = otherWin;
+            }
+        }
         const minRms = 0.01; // simple noise gate
         let freq = null;
         if (rms >= minRms) {
             try {
-                const f = yin(win);
+                // pitchfinder's YIN seeds its difference sum with 1, making low-level
+                // normalized PCM produce spurious ultrasonic pitches. Normalize only
+                // the detector input; RMS and the noise gate retain the original level.
+                let peak = 0;
+                for (const value of win)
+                    peak = Math.max(peak, Math.abs(value));
+                const pitchInput = peak > 0 ? Float32Array.from(win, (value) => value / peak) : win;
+                const f = yin(pitchInput);
                 if (Number.isFinite(f) && f > 20 && f < 8000)
                     freq = f;
             }
@@ -175,7 +234,7 @@ async function analyzePcm(signal, sampleRate, expectedSidwave) {
     return {
         sidwave: 1.0,
         analysis: {
-            source: "microphone",
+            source,
             durationSeconds: signal.length / sampleRate,
             voices,
             global_metrics: {
@@ -189,7 +248,7 @@ async function analyzePcm(signal, sampleRate, expectedSidwave) {
 }
 // Test-only helper: bypasses microphone capture and analyzes provided PCM buffer.
 export async function analyzePcmForTest(signal, sampleRate, expectedSidwave) {
-    return analyzePcm(signal, sampleRate, expectedSidwave);
+    return analyzePcm(signal, sampleRate, "microphone", expectedSidwave);
 }
 function groupSegments(frames, _sampleRate) {
     const segments = [];
@@ -286,10 +345,19 @@ function noteNameToMidiSafe(note) {
 function computeRms(win, Meyda, sampleRate, bufferSize) {
     try {
         if (Meyda && typeof Meyda.extract === "function") {
-            const features = Meyda.extract(["rms"], win, { sampleRate, bufferSize });
-            const val = Number(features?.rms ?? 0);
-            if (Number.isFinite(val))
-                return val;
+            // Rectangular windows give plain sample RMS. Restore Meyda's shared setting
+            // synchronously so other consumers retain their window configuration.
+            const previousWindow = Meyda.windowingFunction;
+            try {
+                Meyda.windowingFunction = "rect";
+                const features = Meyda.extract(["rms"], win, { sampleRate, bufferSize });
+                const val = Number(features?.rms ?? 0);
+                if (Number.isFinite(val))
+                    return val;
+            }
+            finally {
+                Meyda.windowingFunction = previousWindow;
+            }
         }
     }
     catch { }

package/dist/c64Client.js

@@ -6,7 +6,9 @@ Licensed under the GNU General Public License v2.0 or later.
 See <https://www.gnu.org/licenses/> for details.
 */
 import { Buffer } from "node:buffer";
+import { execFile } from "node:child_process";
 import { createSocket } from "node:dgram";
+import { networkInterfaces } from "node:os";
 import axios from "axios";
 import { basicToPrg } from "./tools/translation/basicTokenizer.js";
 import { assemblyToPrg } from "./tools/translation/assembler.js";
@@ -16,6 +18,7 @@ import { createAllFacades, createFacade, } from "./device.js";
 import { Api } from "../generated/c64/index.js";
 import { createLoggingHttpClient } from "./loggingHttpClient.js";
 import { withDiagnosticSpan, writeDiagnosticEvent } from "./diagnostics.js";
+import { analyzeStereoStream, normalizeAudioDuration, recordAndAnalyzeAudio, } from "./audio/record_and_analyze_audio.js";
 import { C64U_NTSC_AUDIO_SAMPLE_RATE, C64U_PAL_AUDIO_SAMPLE_RATE, collectCompleteVideoFrames, parseAudioPacket, parseVideoPacket, } from "./streamCapture.js";
 import { buildVicBitmapRegisters, resolveVicBitmapMemoryLayout, } from "./vicBitmap.js";
 /** Raised when the KERNAL keyboard buffer did not drain before another chunk
@@ -29,6 +32,84 @@ export class KeyboardQueueDrainTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+const C64U_SYSTEM_MODE_CATEGORY = "U64 Specific Settings";
+const C64U_SYSTEM_MODE_ITEM = "System Mode";
+// System Mode values that run the machine clock at the NTSC frequency
+// (VIDEO_FMT_NTSC_FREQ in the firmware colour timings); the other values use the PAL clock.
+const NTSC_CLOCK_SYSTEM_MODES = new Set(["NTSC", "PAL-60", "PAL-60/L"]);
+/**
+ * Reads the current System Mode from a config response. The firmware answers
+ * `{ "<category>": { "<item>": { "current": "PAL", ... } } }`; a bare `{ value }` is also accepted.
+ */
+export function readSystemMode(response) {
+    const record = (value) => value && typeof value === "object" ? value : null;
+    const category = record(record(response)?.[C64U_SYSTEM_MODE_CATEGORY]);
+    const node = category?.[C64U_SYSTEM_MODE_ITEM] ?? response;
+    const raw = typeof node === "string" ? node : record(node)?.current ?? record(node)?.value;
+    return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+}
+export function audioSampleRateForSystemMode(mode) {
+    return mode !== null && NTSC_CLOCK_SYSTEM_MODES.has(mode.toUpperCase())
+        ? C64U_NTSC_AUDIO_SAMPLE_RATE
+        : C64U_PAL_AUDIO_SAMPLE_RATE;
+}
+// A partial capture must still hold one analysis window (2048 stereo frames).
+const MIN_PARTIAL_AUDIO_VALUES = 2048 * 2;
+const STREAM_HOST_RESOLVE_ERROR = "Network Host Resolve Error";
+const NEIGHBOR_PRIME_TIMEOUT_MS = 4000;
+/**
+ * The Ultimate firmware resolves a unicast stream target through its ARP cache
+ * and answers 404 "Network Host Resolve Error" immediately when the client is
+ * not cached. Accepts both a thrown HTTP error and an unsuccessful result.
+ */
+function isStreamHostResolveFailure(failure) {
+    const body = axios.isAxiosError(failure) ? failure.response?.data : failure;
+    if (body === undefined || body === null) {
+        return false;
+    }
+    try {
+        return JSON.stringify(body).includes(STREAM_HOST_RESOLVE_ERROR);
+    }
+    catch {
+        return false;
+    }
+}
+/** Hostnames come from configuration; accept only plain host or address characters so they cannot act as ping options. */
+export function pingableHost(hostname) {
+    const host = hostname.replace(/^\[(.*)\]$/, "$1");
+    return /^[A-Za-z0-9][A-Za-z0-9._:%-]*$/.test(host) ? host : null;
+}
+/** True when `host` is an address of one of this machine's network interfaces. */
+export function isLocalAddress(host) {
+    const wanted = host.replace(/^\[(.*)\]$/, "$1").toLowerCase();
+    return Object.values(networkInterfaces()).some((entries) => (entries ?? []).some((entry) => entry.address.toLowerCase() === wanted));
+}
+/** Host part of a `host:port` stream target, or null when it cannot be split. */
+export function streamTargetHost(target) {
+    const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(target);
+    if (bracketed) {
+        return bracketed[1];
+    }
+    const colon = target.indexOf(":");
+    if (colon === -1) {
+        return target.length > 0 ? target : null;
+    }
+    // Exactly one colon separates host and port; several colons are a bare IPv6 address.
+    if (colon !== target.lastIndexOf(":")) {
+        return target;
+    }
+    return colon > 0 ? target.slice(0, colon) : null;
+}
+function neighborPrimeArgs(host) {
+    switch (process.platform) {
+        case "win32":
+            return ["-n", "1", "-w", "2000", host];
+        case "darwin":
+            return ["-c", "1", "-t", "2", host];
+        default:
+            return ["-c", "1", "-W", "2", host];
+    }
+}
 function menuMatrixIncludes(matrix, expected) {
     // Firmware supplies the character matrix followed by its colour matrix. The
     // documented wire format is raw bytes, so only inspect the first 40×25
@@ -1026,7 +1107,7 @@ export class C64Client {
     async streamStart(stream, ip) {
         try {
             const facade = await this.facadePromise;
-            return await facade.streamStart(stream, ip);
+            return await this.startStreamResolvingHost(facade, stream, ip);
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
@@ -1074,6 +1155,25 @@ export class C64Client {
         }
         return this.captureC64uAudioSamples(facade, requestedPairs);
     }
+    /**
+     * Records and analyzes audio. On the C64 Ultimate the PCM comes from the
+     * device audio stream; other backends have no stream, so the host microphone is used.
+     */
+    async recordAndAnalyzeAudio(params) {
+        const durationSeconds = normalizeAudioDuration(params.durationSeconds);
+        const facade = await this.facadePromise;
+        if (facade.type !== "c64u") {
+            return recordAndAnalyzeAudio(params);
+        }
+        const sampleRateHz = await this.getC64uAudioSampleRate(facade);
+        const samplePairs = Math.ceil(durationSeconds * sampleRateHz);
+        const capture = await this.captureC64uAudioSamples(facade, samplePairs, {
+            timeoutMs: Math.ceil(durationSeconds * 1500) + 2000,
+            sampleRateHz,
+            acceptPartial: true,
+        });
+        return analyzeStereoStream(capture.samples, capture.sampleRateHz, params.expectedSidwave);
+    }
     async configsList() {
         const facade = await this.facadePromise;
         return facade.configsList();
@@ -1223,7 +1323,7 @@ export class C64Client {
         try {
             await this.bindCaptureSocket(socket, bindAddress);
             const target = this.socketEndpoint(socket, bindAddress);
-            await this.ensureStreamSuccess(await facade.streamStart("video", target), "start video stream");
+            await this.ensureStreamSuccess(await this.startStreamResolvingHost(facade, "video", target), "start video stream");
             const frames = await new Promise((resolve, reject) => {
                 const timeoutMs = Math.max(1500, count * 750);
                 const timer = setTimeout(() => {
@@ -1313,7 +1413,7 @@ export class C64Client {
             this.rejectC64uVideoCaptureWaiters(session, err);
         });
         try {
-            await this.ensureStreamSuccess(await facade.streamStart("video", target), "start video stream");
+            await this.ensureStreamSuccess(await this.startStreamResolvingHost(facade, "video", target), "start video stream");
         }
         catch (error) {
             session.closed = true;
@@ -1447,44 +1547,76 @@ export class C64Client {
         }
         throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "VICE display capture failed"));
     }
-    async captureC64uAudioSamples(facade, samplePairs) {
+    async captureC64uAudioSamples(facade, samplePairs, options) {
         const host = new URL(this.baseUrl).hostname;
         const bindAddress = await this.resolveLocalCaptureAddress(host);
         const socket = createSocket("udp4");
         const chunks = [];
         let collectedValues = 0;
-        let stopError = null;
+        const neededValues = samplePairs * 2;
+        let captureError = null;
+        let captureSettled = false;
+        let notifyCapture = () => { };
+        let socketBound = false;
+        let streamAttempted = false;
+        let failed = false;
+        // The firmware can emit UDP before its REST response reaches us. Listen
+        // before starting, and cap collection even while start/config/stop requests are pending.
+        const onMessage = (msg) => {
+            if (captureSettled || captureError || collectedValues >= neededValues)
+                return;
+            try {
+                const packet = parseAudioPacket(msg);
+                if (packet.samples.length % 2 !== 0)
+                    throw new Error("Audio packet contains an incomplete stereo sample pair");
+                const samples = packet.samples.subarray(0, neededValues - collectedValues);
+                chunks.push(samples);
+                collectedValues += samples.length;
+            }
+            catch (error) {
+                captureError = error instanceof Error ? error : new Error(String(error));
+            }
+            notifyCapture();
+        };
+        const onError = (error) => {
+            captureError = error;
+            notifyCapture();
+        };
+        socket.on("message", onMessage);
+        socket.on("error", onError);
         try {
             await this.bindCaptureSocket(socket, bindAddress);
+            socketBound = true;
             const target = this.socketEndpoint(socket, bindAddress);
-            await this.ensureStreamSuccess(await facade.streamStart("audio", target), "start audio stream");
-            const neededValues = samplePairs * 2;
+            streamAttempted = true;
+            await this.ensureStreamSuccess(await this.startStreamResolvingHost(facade, "audio", target), "start audio stream");
             await new Promise((resolve, reject) => {
-                const timeoutMs = Math.max(1000, Math.ceil(samplePairs / 192) * 500);
+                const timeoutMs = options?.timeoutMs ?? Math.max(1000, Math.ceil(samplePairs / 192) * 500);
                 const timer = setTimeout(() => {
+                    captureSettled = true;
+                    // UDP drops packets, so a count-based capture can fall short. Analysis accepts what arrived.
+                    if (options?.acceptPartial && collectedValues >= MIN_PARTIAL_AUDIO_VALUES) {
+                        resolve();
+                        return;
+                    }
                     reject(new Error(`Timed out after ${timeoutMs}ms while capturing ${samplePairs} audio sample pair(s)`));
                 }, timeoutMs);
-                socket.on("message", (msg) => {
-                    try {
-                        const packet = parseAudioPacket(Buffer.from(msg));
-                        chunks.push(packet.samples);
-                        collectedValues += packet.samples.length;
-                        if (collectedValues >= neededValues) {
-                            clearTimeout(timer);
-                            resolve();
-                        }
-                    }
-                    catch (error) {
+                notifyCapture = () => {
+                    if (captureSettled)
+                        return;
+                    if (captureError || collectedValues >= neededValues) {
+                        captureSettled = true;
                         clearTimeout(timer);
-                        reject(error);
+                        if (captureError)
+                            reject(captureError);
+                        else
+                            resolve();
                     }
-                });
-                socket.once("error", (error) => {
-                    clearTimeout(timer);
-                    reject(error);
-                });
+                };
+                notifyCapture();
             });
-            const samples = new Int16Array(samplePairs * 2);
+            const capturedPairs = Math.min(samplePairs, Math.floor(collectedValues / 2));
+            const samples = new Int16Array(capturedPairs * 2);
             let offset = 0;
             for (const chunk of chunks) {
                 const remaining = samples.length - offset;
@@ -1497,32 +1629,37 @@ export class C64Client {
             return {
                 backend: "c64u",
                 channels: 2,
-                sampleRateHz: await this.getC64uAudioSampleRate(facade),
-                samplePairs,
+                sampleRateHz: options?.sampleRateHz ?? await this.getC64uAudioSampleRate(facade),
+                samplePairs: capturedPairs,
                 samples,
             };
         }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
         finally {
+            captureSettled = true;
+            notifyCapture = () => { };
+            socket.off("message", onMessage);
+            if (socketBound)
+                socket.close();
             try {
-                await this.ensureStreamSuccess(await facade.streamStop("audio"), "stop audio stream");
+                if (streamAttempted)
+                    await this.ensureStreamSuccess(await facade.streamStop("audio"), "stop audio stream");
             }
             catch (error) {
-                stopError = error instanceof Error ? error : new Error(String(error));
-            }
-            socket.close();
-            if (stopError) {
-                throw stopError;
+                // Preserve the capture/start error, while still reporting cleanup diagnostics.
+                if (!failed)
+                    throw error;
+                writeDiagnosticEvent("audio_capture_stop_failed", { error: this.normaliseError(error) });
             }
         }
     }
     async getC64uAudioSampleRate(facade) {
         try {
-            const response = await facade.configGet("Video", "Mode");
-            const raw = response?.value ?? response;
-            const mode = typeof raw === "string" ? raw.trim().toUpperCase() : "";
-            if (mode.includes("NTSC")) {
-                return C64U_NTSC_AUDIO_SAMPLE_RATE;
-            }
+            const response = await facade.configGet(C64U_SYSTEM_MODE_CATEGORY, C64U_SYSTEM_MODE_ITEM);
+            return audioSampleRateForSystemMode(readSystemMode(response));
         }
         catch {
             // Fall back to PAL below.
@@ -1568,6 +1705,69 @@ export class C64Client {
         }
         return `${bindAddress}:${address.port}`;
     }
+    /**
+     * Starts a stream. When the device answers "Network Host Resolve Error", sends
+     * one ICMP echo to the device so it has to address a reply to this host, then
+     * retries the start once.
+     */
+    async startStreamResolvingHost(facade, stream, target) {
+        let firstResult;
+        let firstError;
+        try {
+            const result = await facade.streamStart(stream, target);
+            if (result.success || !isStreamHostResolveFailure(result.details)) {
+                return result;
+            }
+            firstResult = result;
+        }
+        catch (error) {
+            if (!isStreamHostResolveFailure(error)) {
+                throw error;
+            }
+            firstError = error;
+        }
+        // A ping from this host only helps when the stream target is this host: the device then has to
+        // address the echo reply to it and learns its address. Any other target stays unresolvable.
+        const targetHost = streamTargetHost(target);
+        if (targetHost === null || !isLocalAddress(targetHost)) {
+            if (firstResult) {
+                return firstResult;
+            }
+            throw firstError;
+        }
+        const host = new URL(this.baseUrl).hostname;
+        writeDiagnosticEvent("stream_start_host_resolve_retry", { stream, target, host });
+        await this.primeDeviceNeighborCache(host);
+        try {
+            const retry = await facade.streamStart(stream, target);
+            if (retry.success || !isStreamHostResolveFailure(retry.details)) {
+                return retry;
+            }
+        }
+        catch (error) {
+            if (!isStreamHostResolveFailure(error)) {
+                throw error;
+            }
+        }
+        throw new Error(`The Ultimate at ${host} could not resolve stream target ${target} (${STREAM_HOST_RESOLVE_ERROR}) even after pinging it from this host. ` +
+            "Check that this host is on the same network as the device, or use a multicast target.");
+    }
+    /** Best effort: ping failure (missing binary, blocked ICMP) is ignored and the caller retries anyway. */
+    async primeDeviceNeighborCache(host) {
+        const pingHost = pingableHost(host);
+        if (!pingHost) {
+            writeDiagnosticEvent("stream_start_ping_failed", { host, message: "host is not a plain hostname or address" });
+            return;
+        }
+        await new Promise((resolve) => {
+            execFile("ping", neighborPrimeArgs(pingHost), { timeout: NEIGHBOR_PRIME_TIMEOUT_MS, windowsHide: true }, (error) => {
+                if (error) {
+                    writeDiagnosticEvent("stream_start_ping_failed", { host, message: error.message });
+                }
+                resolve();
+            });
+        });
+    }
     async ensureStreamSuccess(result, action) {
         if (result.success) {
             return;

package/dist/tools/audio.js

@@ -256,7 +256,7 @@ const musicCompileArgsSchema = objectSchema({
     additionalProperties: false,
 });
 const recordAndAnalyzeArgsSchema = objectSchema({
-    description: "Record audio from the default input and analyze SID playback characteristics.",
+    description: "Record audio and analyze SID playback characteristics. On the c64u backend the audio comes from the Ultimate audio stream; on other backends it is recorded from the host default input device (microphone).",
     properties: {
         durationSeconds: numberSchema({
             description: "Capture duration in seconds (0.5 - 30).",
@@ -963,7 +963,7 @@ export const audioModule = defineToolModule({
         },
         {
             name: "record_and_analyze_audio",
-            description: "Record audio from the default input device and analyze SID playback characteristics.",
+            description: "Record audio and analyze SID playback characteristics. On the c64u backend the audio comes from the Ultimate audio stream; on other backends it is recorded from the host default input device (microphone).",
             summary: "Captures PCM data, extracts notes, tempo, and deviation metrics for SID verification workflows.",
             inputSchema: recordAndAnalyzeArgsSchema.jsonSchema,
             relatedResources: ["c64://sound/sid/spec", "c64://sound/sid/file-format"],
@@ -981,7 +981,8 @@ export const audioModule = defineToolModule({
                 try {
                     const parsed = recordAndAnalyzeArgsSchema.parse(args ?? {});
                     ctx.logger.info("Recording audio for analysis", { durationSeconds: parsed.durationSeconds });
-                    const result = await recordAndAnalyzeAudio({
+                    const analyzer = resolveAnalyzer(ctx);
+                    const result = await analyzer({
                         durationSeconds: parsed.durationSeconds,
                         expectedSidwave: normaliseSidwaveInput(parsed.expectedSidwave),
                     });

package/dist/tools/registry/sound.js

@@ -131,7 +131,7 @@ const soundOperations = [
     },
     {
         op: "record_analyze",
-        schema: extendSchemaWithOp("record_analyze", ensureDescriptor(audioDescriptorIndex, "record_and_analyze_audio").inputSchema, { description: "Record audio for a fixed duration and return SID analysis metrics." }),
+        schema: extendSchemaWithOp("record_analyze", ensureDescriptor(audioDescriptorIndex, "record_and_analyze_audio").inputSchema, { description: "Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(audioModule, "record_and_analyze_audio", rawArgs, ctx),
     },
 ];

package/dist/tools/streaming.js

@@ -32,6 +32,15 @@ function toRecord(details) {
     }
     return undefined;
 }
+function withFailureReason(message, details) {
+    const record = toRecord(details);
+    const body = toRecord(record?.data) ?? toRecord(record?.response) ?? record;
+    const errors = body?.errors;
+    const reason = Array.isArray(errors) && errors.length > 0
+        ? errors.map(String).join("; ")
+        : record?.message ?? record?.reason ?? (typeof details === "string" ? details : undefined);
+    return typeof reason === "string" && reason.length > 0 ? `${message}: ${reason}` : message;
+}
 export const streamingModule = defineToolModule({
     domain: "streaming",
     summary: "Long-running or streaming workflows such as audio capture or SID playback monitoring.",
@@ -71,7 +80,7 @@ export const streamingModule = defineToolModule({
                     });
                     const result = await ctx.client.streamStart(parsed.stream, parsed.target);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while starting stream", {
+                        throw new ToolExecutionError(withFailureReason("C64 firmware reported failure while starting stream", result.details), {
                             details: toRecord(result.details),
                         });
                     }
@@ -111,7 +120,7 @@ export const streamingModule = defineToolModule({
                     });
                     const result = await ctx.client.streamStop(parsed.stream);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while stopping stream", {
+                        throw new ToolExecutionError(withFailureReason("C64 firmware reported failure while stopping stream", result.details), {
                             details: toRecord(result.details),
                         });
                     }

package/mcp/schemas/c64_sound.schema.json

@@ -363,7 +363,7 @@
   "required": [
     "op"
   ],
-  "description": "Sound operations available via the c64_sound tool.\n\nOperations:\n- capture_samples: Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. Required inputs: none. Optional inputs: count, encoding.\n- set_volume: Set the SID master volume register at $D418 (0-15). Required inputs: volume.\n- reset: Soft or hard reset of SID registers to clear glitches. Required inputs: none. Optional inputs: hard.\n- note_on: Trigger a SID voice with configurable waveform, ADSR, and pitch. Required inputs: none. Optional inputs: voice, note, frequencyHz, system, waveform, pulseWidth, attack, decay, sustain, release.\n- note_off: Release a SID voice by clearing its gate bit. Required inputs: voice.\n- silence_all: Silence all SID voices with optional audio verification. Required inputs: none. Optional inputs: verify.\n- play_sid_file: Play a SID file stored on the Ultimate filesystem. Required inputs: path. Optional inputs: songnr.\n- play_mod_file: Play a MOD tracker module via the Ultimate SID player. Required inputs: path.\n- generate: Generate a lightweight SID arpeggio playback sequence. Required inputs: none. Optional inputs: root, pattern, steps, tempoMs, waveform, preset.\n- compile_play: Compile SIDWAVE or CPG source and optionally play it immediately. Required inputs: none. Optional inputs: sidwave, cpg, format, output, dryRun.\n- play_preset: Compile and play a built-in SID preset such as Für Elise by Beethoven. Required inputs: none. Optional inputs: preset, platforms, verify, analysisDurationSeconds, waitBeforeCaptureMs, restoreActiveBackend.\n- pipeline: Compile a SIDWAVE score, play it, and analyze the recording. Required inputs: none. Optional inputs: sidwave, cpg, output, waitBeforeCaptureMs, analysisDurationSeconds, expectedSidwave, verifySilenceBefore, verifySilenceAfter, silenceDurationSeconds, silenceRmsThreshold, postSilenceWaitMs, silenceWaitMs.\n- analyze: Automatically analyze SID playback when verification is requested. Required inputs: request. Optional inputs: durationSeconds, expectedSidwave.\n- record_analyze: Record audio for a fixed duration and return SID analysis metrics. Required inputs: durationSeconds. Optional inputs: expectedSidwave.",
+  "description": "Sound operations available via the c64_sound tool.\n\nOperations:\n- capture_samples: Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. Required inputs: none. Optional inputs: count, encoding.\n- set_volume: Set the SID master volume register at $D418 (0-15). Required inputs: volume.\n- reset: Soft or hard reset of SID registers to clear glitches. Required inputs: none. Optional inputs: hard.\n- note_on: Trigger a SID voice with configurable waveform, ADSR, and pitch. Required inputs: none. Optional inputs: voice, note, frequencyHz, system, waveform, pulseWidth, attack, decay, sustain, release.\n- note_off: Release a SID voice by clearing its gate bit. Required inputs: voice.\n- silence_all: Silence all SID voices with optional audio verification. Required inputs: none. Optional inputs: verify.\n- play_sid_file: Play a SID file stored on the Ultimate filesystem. Required inputs: path. Optional inputs: songnr.\n- play_mod_file: Play a MOD tracker module via the Ultimate SID player. Required inputs: path.\n- generate: Generate a lightweight SID arpeggio playback sequence. Required inputs: none. Optional inputs: root, pattern, steps, tempoMs, waveform, preset.\n- compile_play: Compile SIDWAVE or CPG source and optionally play it immediately. Required inputs: none. Optional inputs: sidwave, cpg, format, output, dryRun.\n- play_preset: Compile and play a built-in SID preset such as Für Elise by Beethoven. Required inputs: none. Optional inputs: preset, platforms, verify, analysisDurationSeconds, waitBeforeCaptureMs, restoreActiveBackend.\n- pipeline: Compile a SIDWAVE score, play it, and analyze the recording. Required inputs: none. Optional inputs: sidwave, cpg, output, waitBeforeCaptureMs, analysisDurationSeconds, expectedSidwave, verifySilenceBefore, verifySilenceAfter, silenceDurationSeconds, silenceRmsThreshold, postSilenceWaitMs, silenceWaitMs.\n- analyze: Automatically analyze SID playback when verification is requested. Required inputs: request. Optional inputs: durationSeconds, expectedSidwave.\n- record_analyze: Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends. Required inputs: durationSeconds. Optional inputs: expectedSidwave.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -1119,7 +1119,7 @@
     },
     {
       "op": "record_analyze",
-      "description": "Record audio for a fixed duration and return SID analysis metrics.",
+      "description": "Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends.",
       "required": [
         "durationSeconds"
       ],
@@ -1128,7 +1128,7 @@
       ],
       "inputSchema": {
         "type": "object",
-        "description": "Record audio for a fixed duration and return SID analysis metrics.",
+        "description": "Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends.",
         "properties": {
           "durationSeconds": {
             "type": "number",

package/mcp/server.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "transports": [
     "stdio"