@mcptoolshop/claude-sfx 0.1.0

package/dist/synth.js

@@ -0,0 +1,254 @@
+/**
+ * Pure PCM synthesis engine. Zero dependencies.
+ * Generates audio from math — oscillators, envelopes, FM, and WAV encoding.
+ */
+const SAMPLE_RATE = 44100;
+const BIT_DEPTH = 16;
+const NUM_CHANNELS = 1; // mono
+/** Returns a sample value in [-1, 1] for a given phase (0–1 cycle). */
+function oscillator(waveform, phase) {
+    const p = phase % 1;
+    switch (waveform) {
+        case "sine":
+            return Math.sin(2 * Math.PI * p);
+        case "square":
+            return p < 0.5 ? 1 : -1;
+        case "sawtooth":
+            return 2 * p - 1;
+        case "triangle":
+            return p < 0.5 ? 4 * p - 1 : 3 - 4 * p;
+        case "noise":
+            return Math.random() * 2 - 1;
+    }
+}
+/** Returns envelope amplitude (0–1) at a given time within a note of total duration. */
+function envelopeAt(env, time, duration) {
+    const { attack, decay, sustain, release } = env;
+    const releaseStart = duration - release;
+    if (time < 0)
+        return 0;
+    if (time < attack) {
+        // Attack: ramp from 0 to 1
+        return time / attack;
+    }
+    if (time < attack + decay) {
+        // Decay: ramp from 1 to sustain level
+        const decayProgress = (time - attack) / decay;
+        return 1 - decayProgress * (1 - sustain);
+    }
+    if (time < releaseStart) {
+        // Sustain
+        return sustain;
+    }
+    if (time < duration) {
+        // Release: ramp from sustain to 0
+        const releaseProgress = (time - releaseStart) / release;
+        return sustain * (1 - releaseProgress);
+    }
+    return 0;
+}
+// --- PCM Generation ---
+/** Generate a Float64 audio buffer from tone parameters. */
+export function generateTone(params) {
+    const numSamples = Math.floor(params.duration * SAMPLE_RATE);
+    const buffer = new Float64Array(numSamples);
+    for (let i = 0; i < numSamples; i++) {
+        const t = i / SAMPLE_RATE; // time in seconds
+        // Frequency sweep (linear interpolation)
+        const freqEnd = params.frequencyEnd ?? params.frequency;
+        const progress = i / numSamples;
+        const freq = params.frequency + (freqEnd - params.frequency) * progress;
+        // FM synthesis: modulate the carrier phase
+        let fmOffset = 0;
+        if (params.fmRatio && params.fmDepth) {
+            const modFreq = freq * params.fmRatio;
+            fmOffset =
+                (params.fmDepth / (2 * Math.PI * freq)) *
+                    Math.sin(2 * Math.PI * modFreq * t);
+        }
+        // Carrier phase
+        const phase = freq * t + fmOffset;
+        let sample = oscillator(params.waveform, phase);
+        // Octave harmonic
+        if (params.harmonicGain && params.harmonicGain > 0) {
+            sample += params.harmonicGain * oscillator(params.waveform, phase * 2);
+            // Normalize to prevent clipping
+            sample /= 1 + params.harmonicGain;
+        }
+        // Detune (second oscillator for beating effect)
+        if (params.detune && params.detune !== 0) {
+            const detunePhase = (freq + params.detune) * t + fmOffset;
+            const detuneSample = oscillator(params.waveform, detunePhase);
+            sample = (sample + detuneSample) / 2;
+        }
+        // Envelope
+        sample *= envelopeAt(params.envelope, t, params.duration);
+        // Tremolo (amplitude modulation)
+        if (params.tremoloRate && params.tremoloDepth) {
+            const tremoloMod = 1 - params.tremoloDepth * 0.5 * (1 + Math.sin(2 * Math.PI * params.tremoloRate * t));
+            sample *= tremoloMod;
+        }
+        // Master gain
+        sample *= params.gain;
+        buffer[i] = sample;
+    }
+    return buffer;
+}
+// --- Mixing ---
+/** Mix multiple tone buffers into one (summed and normalized). */
+export function mixBuffers(buffers) {
+    const maxLen = Math.max(...buffers.map((b) => b.length));
+    const mixed = new Float64Array(maxLen);
+    for (const buf of buffers) {
+        for (let i = 0; i < buf.length; i++) {
+            mixed[i] += buf[i];
+        }
+    }
+    // Find peak for normalization
+    let peak = 0;
+    for (let i = 0; i < mixed.length; i++) {
+        const abs = Math.abs(mixed[i]);
+        if (abs > peak)
+            peak = abs;
+    }
+    // Normalize if clipping
+    if (peak > 1) {
+        for (let i = 0; i < mixed.length; i++) {
+            mixed[i] /= peak;
+        }
+    }
+    return mixed;
+}
+/** Concatenate buffers sequentially with an optional gap (in seconds). */
+export function concatBuffers(buffers, gapSeconds = 0) {
+    const gapSamples = Math.floor(gapSeconds * SAMPLE_RATE);
+    const totalLength = buffers.reduce((sum, b) => sum + b.length + gapSamples, -gapSamples // no gap after last buffer
+    );
+    const result = new Float64Array(Math.max(0, totalLength));
+    let offset = 0;
+    for (let bi = 0; bi < buffers.length; bi++) {
+        const buf = buffers[bi];
+        result.set(buf, offset);
+        offset += buf.length;
+        if (bi < buffers.length - 1) {
+            offset += gapSamples;
+        }
+    }
+    return result;
+}
+// --- WAV Encoding ---
+/** Encode a Float64 audio buffer as a WAV file (PCM 16-bit mono). */
+export function encodeWav(buffer) {
+    const numSamples = buffer.length;
+    const byteRate = SAMPLE_RATE * NUM_CHANNELS * (BIT_DEPTH / 8);
+    const blockAlign = NUM_CHANNELS * (BIT_DEPTH / 8);
+    const dataSize = numSamples * NUM_CHANNELS * (BIT_DEPTH / 8);
+    const fileSize = 44 + dataSize; // 44-byte header + data
+    const wav = Buffer.alloc(fileSize);
+    let offset = 0;
+    // RIFF header
+    wav.write("RIFF", offset);
+    offset += 4;
+    wav.writeUInt32LE(fileSize - 8, offset);
+    offset += 4;
+    wav.write("WAVE", offset);
+    offset += 4;
+    // fmt sub-chunk
+    wav.write("fmt ", offset);
+    offset += 4;
+    wav.writeUInt32LE(16, offset); // sub-chunk size (PCM = 16)
+    offset += 4;
+    wav.writeUInt16LE(1, offset); // audio format (PCM = 1)
+    offset += 2;
+    wav.writeUInt16LE(NUM_CHANNELS, offset);
+    offset += 2;
+    wav.writeUInt32LE(SAMPLE_RATE, offset);
+    offset += 4;
+    wav.writeUInt32LE(byteRate, offset);
+    offset += 4;
+    wav.writeUInt16LE(blockAlign, offset);
+    offset += 2;
+    wav.writeUInt16LE(BIT_DEPTH, offset);
+    offset += 2;
+    // data sub-chunk
+    wav.write("data", offset);
+    offset += 4;
+    wav.writeUInt32LE(dataSize, offset);
+    offset += 4;
+    // PCM samples (float → 16-bit signed int)
+    for (let i = 0; i < numSamples; i++) {
+        let sample = buffer[i];
+        // Hard clip
+        sample = Math.max(-1, Math.min(1, sample));
+        // Convert to 16-bit signed integer
+        const int16 = Math.round(sample * 32767);
+        wav.writeInt16LE(int16, offset);
+        offset += 2;
+    }
+    return wav;
+}
+// --- Loudness Limiter ---
+/** Apply a hard loudness cap with gentle compression to a buffer. */
+export function limitLoudness(buffer, ceiling = 0.85) {
+    const result = new Float64Array(buffer.length);
+    for (let i = 0; i < buffer.length; i++) {
+        let s = buffer[i];
+        // Soft knee compression above 70% of ceiling
+        const knee = ceiling * 0.7;
+        const abs = Math.abs(s);
+        if (abs > knee) {
+            const over = abs - knee;
+            const range = ceiling - knee;
+            // Compress the overshoot with a sqrt curve
+            const compressed = knee + range * Math.sqrt(over / range);
+            s = s > 0 ? Math.min(compressed, ceiling) : Math.max(-compressed, -ceiling);
+        }
+        result[i] = s;
+    }
+    return result;
+}
+// --- Volume scaling ---
+/** Apply a volume gain (0.0–1.0) to a buffer. */
+export function applyVolume(buffer, gain) {
+    if (gain >= 1)
+        return buffer;
+    const result = new Float64Array(buffer.length);
+    for (let i = 0; i < buffer.length; i++) {
+        result[i] = buffer[i] * gain;
+    }
+    return result;
+}
+/**
+ * Generate a whoosh: bandpass-filtered noise with a sweeping center frequency.
+ * Uses a state-variable filter (SVF) for stable real-time coefficient changes.
+ */
+export function generateWhoosh(params) {
+    const numSamples = Math.floor(params.duration * SAMPLE_RATE);
+    const buffer = new Float64Array(numSamples);
+    // SVF state
+    let low = 0;
+    let band = 0;
+    for (let i = 0; i < numSamples; i++) {
+        const t = i / SAMPLE_RATE;
+        const progress = i / numSamples;
+        // Sweep the center frequency
+        const centerFreq = params.freqStart + (params.freqEnd - params.freqStart) * progress;
+        // SVF coefficients
+        const f = 2 * Math.sin((Math.PI * centerFreq) / SAMPLE_RATE);
+        const q = params.bandwidth;
+        // White noise input
+        const input = Math.random() * 2 - 1;
+        // State-variable filter iteration (bandpass output)
+        low += f * band;
+        const high = input - low - q * band;
+        band += f * high;
+        let sample = band; // bandpass output
+        // Envelope
+        sample *= envelopeAt(params.envelope, t, params.duration);
+        // Gain
+        sample *= params.gain;
+        buffer[i] = sample;
+    }
+    return buffer;
+}
+export { SAMPLE_RATE, BIT_DEPTH, NUM_CHANNELS };

package/dist/verbs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Verb generation engine — profile-driven.
+ * Reads synthesis parameters from a Profile, applies modifiers, generates audio.
+ */
+import type { Profile } from "./profiles.js";
+export type Status = "ok" | "err" | "warn";
+export type Scope = "local" | "remote";
+export type Direction = "up" | "down";
+export interface PlayOptions {
+    status?: Status;
+    scope?: Scope;
+    direction?: Direction;
+}
+export type Verb = "intake" | "transform" | "commit" | "navigate" | "execute" | "move" | "sync";
+export declare const VERB_LABELS: Record<Verb, string>;
+export declare const VERB_DESCRIPTIONS: Record<Verb, string>;
+export declare const ALL_VERBS: Verb[];
+/** Generate a verb sound using the given profile. */
+export declare function generateVerb(profile: Profile, verb: Verb, options?: PlayOptions): Float64Array;
+export declare function generateSessionStart(profile: Profile): Float64Array;
+export declare function generateSessionEnd(profile: Profile): Float64Array;
+/** Generate a single chunk of the ambient thinking drone. */
+export declare function generateAmbientChunk(profile: Profile): Float64Array;
+/** Generate the resolution stinger (two ascending notes). */
+export declare function generateAmbientResolve(profile: Profile): Float64Array;

package/dist/verbs.js

@@ -0,0 +1,251 @@
+/**
+ * Verb generation engine — profile-driven.
+ * Reads synthesis parameters from a Profile, applies modifiers, generates audio.
+ */
+import { SAMPLE_RATE, generateTone, generateWhoosh, mixBuffers, limitLoudness, } from "./synth.js";
+export const VERB_LABELS = {
+    intake: "Intake",
+    transform: "Transform",
+    commit: "Commit",
+    navigate: "Navigate",
+    execute: "Execute",
+    move: "Move",
+    sync: "Sync",
+};
+export const VERB_DESCRIPTIONS = {
+    intake: "read / open / fetch",
+    transform: "edit / format / refactor",
+    commit: "write / save / apply",
+    navigate: "search / jump / list",
+    execute: "run / test / build",
+    move: "move / rename / relocate",
+    sync: "git push / pull / deploy",
+};
+export const ALL_VERBS = [
+    "intake",
+    "transform",
+    "commit",
+    "navigate",
+    "execute",
+    "move",
+    "sync",
+];
+// --- Status modifier functions (tone-based) ---
+function applyToneStatus(params, status) {
+    const p = { ...params };
+    switch (status) {
+        case "ok":
+            p.harmonicGain = 0.15;
+            break;
+        case "err":
+            p.frequency *= 0.7;
+            if (p.frequencyEnd)
+                p.frequencyEnd *= 0.7;
+            p.detune = 3;
+            p.duration *= 1.3;
+            break;
+        case "warn":
+            p.tremoloRate = 8;
+            p.tremoloDepth = 0.5;
+            break;
+    }
+    return p;
+}
+function applyToneScope(params, scope) {
+    if (scope === "remote") {
+        const p = { ...params };
+        p.envelope = { ...p.envelope, release: p.envelope.release * 2.5 };
+        p.duration *= 1.2;
+        return p;
+    }
+    return params;
+}
+// --- Status modifier functions (whoosh-based) ---
+function applyWhooshStatus(params, status) {
+    const p = { ...params };
+    switch (status) {
+        case "ok":
+            p.freqEnd = Math.min(p.freqEnd * 1.2, 6000);
+            break;
+        case "err":
+            p.freqStart *= 0.6;
+            p.freqEnd *= 0.6;
+            p.duration *= 1.3;
+            p.bandwidth = 1.2;
+            break;
+        case "warn":
+            p.duration *= 0.8;
+            p.envelope = { ...p.envelope, attack: 0.01, release: 0.03 };
+            break;
+    }
+    return p;
+}
+function applyWhooshScope(params, scope) {
+    if (scope === "remote") {
+        const p = { ...params };
+        p.duration *= 1.3;
+        p.envelope = { ...p.envelope, release: p.envelope.release * 2 };
+        return p;
+    }
+    return params;
+}
+// --- Config → Params conversion ---
+function toneConfigToParams(cfg) {
+    return {
+        waveform: cfg.waveform,
+        frequency: cfg.frequency,
+        frequencyEnd: cfg.frequencyEnd,
+        duration: cfg.duration,
+        envelope: { ...cfg.envelope },
+        gain: cfg.gain,
+        fmRatio: cfg.fmRatio,
+        fmDepth: cfg.fmDepth,
+        harmonicGain: cfg.harmonicGain,
+    };
+}
+function whooshConfigToParams(cfg, direction) {
+    const freqPair = direction === "down" ? cfg.freqDown : cfg.freqUp;
+    return {
+        duration: cfg.duration,
+        freqStart: freqPair[0],
+        freqEnd: freqPair[1],
+        bandwidth: cfg.bandwidth,
+        envelope: { ...cfg.envelope },
+        gain: cfg.gain,
+    };
+}
+// --- Main generation ---
+/** Generate a verb sound using the given profile. */
+export function generateVerb(profile, verb, options = {}) {
+    const cfg = profile.verbs[verb];
+    if (!cfg) {
+        throw new Error(`Profile "${profile.name}" has no config for verb "${verb}"`);
+    }
+    // Whoosh-based verbs
+    if (cfg.type === "whoosh") {
+        const dir = options.direction ?? "up";
+        let wp = whooshConfigToParams(cfg, dir);
+        if (options.status)
+            wp = applyWhooshStatus(wp, options.status);
+        if (options.scope)
+            wp = applyWhooshScope(wp, options.scope);
+        const whoosh = generateWhoosh(wp);
+        // Tonal anchor (sync)
+        if (cfg.tonalAnchor) {
+            const anchorFreqs = dir === "down" ? cfg.tonalAnchor.freqDown : cfg.tonalAnchor.freqUp;
+            const anchor = generateTone({
+                waveform: "sine",
+                frequency: anchorFreqs[0],
+                frequencyEnd: anchorFreqs[1],
+                duration: wp.duration,
+                envelope: { ...cfg.tonalAnchor.envelope },
+                gain: cfg.tonalAnchor.gain,
+            });
+            return limitLoudness(mixBuffers([whoosh, anchor]));
+        }
+        return limitLoudness(whoosh);
+    }
+    // Tone-based verbs
+    let params = toneConfigToParams(cfg);
+    if (options.status)
+        params = applyToneStatus(params, options.status);
+    if (options.scope)
+        params = applyToneScope(params, options.scope);
+    const primary = generateTone(params);
+    // Noise burst layer (execute)
+    if (cfg.noiseBurst) {
+        const noise = generateTone({
+            waveform: "noise",
+            frequency: 0,
+            duration: cfg.noiseBurst.duration,
+            envelope: { attack: 0.002, decay: 0.03, sustain: 0.0, release: 0.005 },
+            gain: cfg.noiseBurst.gain,
+        });
+        return limitLoudness(mixBuffers([primary, noise]));
+    }
+    return limitLoudness(primary);
+}
+// --- Session sounds ---
+function generateChime(chime) {
+    const tone1 = generateTone({
+        waveform: chime.tone1.waveform,
+        frequency: chime.tone1.frequency,
+        duration: chime.tone1.duration,
+        envelope: { ...chime.tone1.envelope },
+        gain: chime.tone1.gain,
+        harmonicGain: chime.tone1.harmonicGain,
+    });
+    const tone2 = generateTone({
+        waveform: chime.tone2.waveform,
+        frequency: chime.tone2.frequency,
+        duration: chime.tone2.duration,
+        envelope: { ...chime.tone2.envelope },
+        gain: chime.tone2.gain,
+        harmonicGain: chime.tone2.harmonicGain,
+    });
+    const offset = Math.floor(chime.staggerSeconds * SAMPLE_RATE);
+    const total = new Float64Array(Math.max(tone1.length, offset + tone2.length));
+    total.set(tone1, 0);
+    for (let i = 0; i < tone2.length; i++) {
+        if (offset + i < total.length) {
+            total[offset + i] += tone2[i];
+        }
+    }
+    return limitLoudness(total);
+}
+export function generateSessionStart(profile) {
+    return generateChime(profile.sessionStart);
+}
+export function generateSessionEnd(profile) {
+    return generateChime(profile.sessionEnd);
+}
+// --- Ambient (long-running thinking) ---
+/** Generate a single chunk of the ambient thinking drone. */
+export function generateAmbientChunk(profile) {
+    const cfg = profile.ambient;
+    // Low drone with very gentle fade in/out to allow seamless looping
+    return generateTone({
+        waveform: cfg.droneWaveform,
+        frequency: cfg.droneFreq,
+        duration: cfg.chunkDuration,
+        envelope: {
+            attack: 0.3,
+            decay: 0.2,
+            sustain: 1.0,
+            release: 0.3,
+        },
+        gain: cfg.droneGain,
+        // Subtle tremolo gives the drone "life" instead of a dead flat tone
+        tremoloRate: 0.5,
+        tremoloDepth: 0.15,
+    });
+}
+/** Generate the resolution stinger (two ascending notes). */
+export function generateAmbientResolve(profile) {
+    const cfg = profile.ambient;
+    const note1 = generateTone({
+        waveform: cfg.resolveWaveform,
+        frequency: cfg.resolveNote1,
+        duration: cfg.resolveDuration,
+        envelope: { attack: 0.008, decay: 0.06, sustain: 0.25, release: 0.04 },
+        gain: cfg.resolveGain,
+        harmonicGain: 0.1,
+    });
+    const note2 = generateTone({
+        waveform: cfg.resolveWaveform,
+        frequency: cfg.resolveNote2,
+        duration: cfg.resolveDuration * 1.3,
+        envelope: { attack: 0.008, decay: 0.08, sustain: 0.25, release: 0.06 },
+        gain: cfg.resolveGain * 0.9,
+        harmonicGain: 0.1,
+    });
+    const offset = Math.floor(cfg.resolveDuration * 0.6 * SAMPLE_RATE);
+    const total = new Float64Array(offset + note2.length);
+    total.set(note1, 0);
+    for (let i = 0; i < note2.length; i++) {
+        if (offset + i < total.length) {
+            total[offset + i] += note2[i];
+        }
+    }
+    return limitLoudness(total);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mcptoolshop/claude-sfx",
+  "version": "0.1.0",
+  "description": "Procedural audio feedback for Claude Code — UX for agentic coding",
+  "type": "module",
+  "bin": {
+    "claude-sfx": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "demo": "node dist/cli.js demo",
+    "play": "node dist/cli.js play",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "sound",
+    "audio",
+    "feedback",
+    "hooks",
+    "accessibility",
+    "developer-experience",
+    "synth",
+    "procedural-audio"
+  ],
+  "author": "mcp-tool-shop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcp-tool-shop-org/claude-sfx.git"
+  },
+  "homepage": "https://mcp-tool-shop-org.github.io/claude-sfx/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "profiles/",
+    "assets/logo.jpg",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  }
+}