@mcptoolshop/claude-sfx 0.1.0

package/dist/player.js

@@ -0,0 +1,109 @@
+/**
+ * Cross-platform audio playback.
+ * Writes a temp .wav file, plays it with the OS native player, cleans up.
+ * Zero dependencies.
+ */
+import { writeFileSync, unlinkSync, mkdirSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execSync, spawn } from "node:child_process";
+import { encodeWav } from "./synth.js";
+const TEMP_DIR = join(tmpdir(), "claude-sfx");
+function ensureTempDir() {
+    if (!existsSync(TEMP_DIR)) {
+        mkdirSync(TEMP_DIR, { recursive: true });
+    }
+}
+function getTempPath() {
+    ensureTempDir();
+    return join(TEMP_DIR, `sfx-${Date.now()}-${Math.random().toString(36).slice(2, 6)}.wav`);
+}
+/** Detect OS and return the appropriate play command. */
+function getPlayCommand(filePath) {
+    const platform = process.platform;
+    if (platform === "win32") {
+        // PowerShell SoundPlayer — synchronous, reliable, built-in
+        return {
+            command: "powershell",
+            args: [
+                "-NoProfile",
+                "-Command",
+                `(New-Object Media.SoundPlayer '${filePath}').PlaySync()`,
+            ],
+        };
+    }
+    if (platform === "darwin") {
+        return { command: "afplay", args: [filePath] };
+    }
+    // Linux: try paplay (PulseAudio), then aplay (ALSA)
+    try {
+        execSync("which paplay", { stdio: "ignore" });
+        return { command: "paplay", args: [filePath] };
+    }
+    catch {
+        try {
+            execSync("which aplay", { stdio: "ignore" });
+            return { command: "aplay", args: ["-q", filePath] };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Play a PCM audio buffer through the system speakers. Blocks until done. */
+export function playSync(buffer) {
+    const start = Date.now();
+    const wavData = encodeWav(buffer);
+    const tempPath = getTempPath();
+    try {
+        writeFileSync(tempPath, wavData);
+        const cmd = getPlayCommand(tempPath);
+        if (!cmd) {
+            return { played: false, method: "none", durationMs: 0 };
+        }
+        execSync(`${cmd.command} ${cmd.args.map((a) => `"${a}"`).join(" ")}`, {
+            stdio: "ignore",
+            timeout: 5000,
+        });
+        return {
+            played: true,
+            method: cmd.command,
+            durationMs: Date.now() - start,
+        };
+    }
+    finally {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // Temp file cleanup is best-effort
+        }
+    }
+}
+/** Play a PCM audio buffer asynchronously (fire and forget). */
+export function playAsync(buffer) {
+    const wavData = encodeWav(buffer);
+    const tempPath = getTempPath();
+    writeFileSync(tempPath, wavData);
+    const cmd = getPlayCommand(tempPath);
+    if (!cmd)
+        return;
+    const child = spawn(cmd.command, cmd.args, {
+        stdio: "ignore",
+        detached: true,
+    });
+    child.on("exit", () => {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // best-effort
+        }
+    });
+    child.unref();
+}
+/** Write a WAV file to disk (for export / debugging). */
+export function saveWav(buffer, outputPath) {
+    const wavData = encodeWav(buffer);
+    writeFileSync(outputPath, wavData);
+}

package/dist/profiles.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Profile system — configurable sound palettes.
+ * Each profile defines synthesis parameters for every verb + session sounds.
+ * Profiles are JSON-serializable, so users can create their own.
+ */
+import type { Waveform, Envelope } from "./synth.js";
+/** Synthesis params for a tone-based verb (intake, transform, commit, navigate, execute). */
+export interface ToneVerbConfig {
+    type: "tone";
+    waveform: Waveform;
+    frequency: number;
+    frequencyEnd?: number;
+    duration: number;
+    envelope: Envelope;
+    gain: number;
+    fmRatio?: number;
+    fmDepth?: number;
+    harmonicGain?: number;
+    /** If true, mix a short noise burst underneath (execute verb). */
+    noiseBurst?: {
+        duration: number;
+        gain: number;
+    };
+}
+/** Synthesis params for a whoosh-based verb (move, sync). */
+export interface WhooshVerbConfig {
+    type: "whoosh";
+    duration: number;
+    /** Freq pair for direction=up. [start, end] */
+    freqUp: [number, number];
+    /** Freq pair for direction=down. [start, end] */
+    freqDown: [number, number];
+    bandwidth: number;
+    envelope: Envelope;
+    gain: number;
+    /** Optional tonal anchor mixed underneath (sync verb). */
+    tonalAnchor?: {
+        freqUp: [number, number];
+        freqDown: [number, number];
+        envelope: Envelope;
+        gain: number;
+    };
+}
+export type VerbConfig = ToneVerbConfig | WhooshVerbConfig;
+/** A two-tone chime (session start/end). */
+export interface ChimeConfig {
+    tone1: {
+        waveform: Waveform;
+        frequency: number;
+        duration: number;
+        envelope: Envelope;
+        gain: number;
+        harmonicGain?: number;
+    };
+    tone2: {
+        waveform: Waveform;
+        frequency: number;
+        duration: number;
+        envelope: Envelope;
+        gain: number;
+        harmonicGain?: number;
+    };
+    /** Offset in seconds before tone2 starts. */
+    staggerSeconds: number;
+}
+/** Long-running ambient drone config. */
+export interface AmbientConfig {
+    /** Low drone frequency */
+    droneFreq: number;
+    droneWaveform: Waveform;
+    droneGain: number;
+    /** Seconds per loop chunk (the drone is generated in chunks). */
+    chunkDuration: number;
+    /** Resolution stinger: two ascending notes. */
+    resolveNote1: number;
+    resolveNote2: number;
+    resolveWaveform: Waveform;
+    resolveDuration: number;
+    resolveGain: number;
+}
+/** Complete profile definition. */
+export interface Profile {
+    name: string;
+    description: string;
+    verbs: Record<string, VerbConfig>;
+    sessionStart: ChimeConfig;
+    sessionEnd: ChimeConfig;
+    ambient: AmbientConfig;
+}
+/** Get a built-in profile by name. */
+export declare function getBuiltinProfile(name: string): Profile | undefined;
+/** List all built-in profile names. */
+export declare function listBuiltinProfiles(): string[];
+/** Load a profile from a JSON file path. */
+export declare function loadProfileFromFile(filePath: string): Profile;
+/**
+ * Resolve a profile by name.
+ * 1. Check built-in profiles
+ * 2. Check profiles/ directory next to the package
+ * 3. Treat as absolute/relative file path
+ */
+export declare function resolveProfile(nameOrPath: string): Profile;
+export declare const DEFAULT_PROFILE_NAME = "minimal";

package/dist/profiles.js

@@ -0,0 +1,297 @@
+/**
+ * Profile system — configurable sound palettes.
+ * Each profile defines synthesis parameters for every verb + session sounds.
+ * Profiles are JSON-serializable, so users can create their own.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// --- Built-in profiles ---
+const MINIMAL_PROFILE = {
+    name: "minimal",
+    description: "Tasteful UI tones — subtle, professional, daily-driver",
+    verbs: {
+        intake: {
+            type: "tone",
+            waveform: "sine",
+            frequency: 440,
+            frequencyEnd: 620,
+            duration: 0.15,
+            envelope: { attack: 0.02, decay: 0.06, sustain: 0.4, release: 0.04 },
+            gain: 0.6,
+        },
+        transform: {
+            type: "tone",
+            waveform: "sine",
+            frequency: 520,
+            duration: 0.1,
+            envelope: { attack: 0.005, decay: 0.03, sustain: 0.2, release: 0.03 },
+            gain: 0.55,
+            fmRatio: 1.5,
+            fmDepth: 30,
+        },
+        commit: {
+            type: "tone",
+            waveform: "sine",
+            frequency: 840,
+            duration: 0.08,
+            envelope: { attack: 0.005, decay: 0.03, sustain: 0.2, release: 0.03 },
+            gain: 0.6,
+        },
+        navigate: {
+            type: "tone",
+            waveform: "sine",
+            frequency: 1050,
+            duration: 0.2,
+            envelope: { attack: 0.003, decay: 0.15, sustain: 0.0, release: 0.05 },
+            gain: 0.5,
+        },
+        execute: {
+            type: "tone",
+            waveform: "sine",
+            frequency: 620,
+            duration: 0.1,
+            envelope: { attack: 0.005, decay: 0.03, sustain: 0.2, release: 0.03 },
+            gain: 0.5,
+            noiseBurst: { duration: 0.04, gain: 0.25 },
+        },
+        move: {
+            type: "whoosh",
+            duration: 0.25,
+            freqUp: [600, 2800],
+            freqDown: [2800, 600],
+            bandwidth: 0.8,
+            envelope: { attack: 0.04, decay: 0.08, sustain: 0.5, release: 0.1 },
+            gain: 0.6,
+        },
+        sync: {
+            type: "whoosh",
+            duration: 0.32,
+            freqUp: [400, 3200],
+            freqDown: [3200, 400],
+            bandwidth: 0.6,
+            envelope: { attack: 0.05, decay: 0.1, sustain: 0.45, release: 0.12 },
+            gain: 0.55,
+            tonalAnchor: {
+                freqUp: [350, 700],
+                freqDown: [700, 350],
+                envelope: { attack: 0.03, decay: 0.1, sustain: 0.15, release: 0.08 },
+                gain: 0.2,
+            },
+        },
+    },
+    sessionStart: {
+        tone1: {
+            waveform: "sine",
+            frequency: 523,
+            duration: 0.18,
+            envelope: { attack: 0.01, decay: 0.08, sustain: 0.3, release: 0.06 },
+            gain: 0.5,
+            harmonicGain: 0.1,
+        },
+        tone2: {
+            waveform: "sine",
+            frequency: 659,
+            duration: 0.22,
+            envelope: { attack: 0.01, decay: 0.1, sustain: 0.3, release: 0.08 },
+            gain: 0.45,
+            harmonicGain: 0.1,
+        },
+        staggerSeconds: 0.07,
+    },
+    sessionEnd: {
+        tone1: {
+            waveform: "sine",
+            frequency: 659,
+            duration: 0.15,
+            envelope: { attack: 0.01, decay: 0.08, sustain: 0.2, release: 0.04 },
+            gain: 0.45,
+        },
+        tone2: {
+            waveform: "sine",
+            frequency: 523,
+            duration: 0.25,
+            envelope: { attack: 0.01, decay: 0.12, sustain: 0.2, release: 0.1 },
+            gain: 0.4,
+        },
+        staggerSeconds: 0.08,
+    },
+    ambient: {
+        droneFreq: 150,
+        droneWaveform: "sine",
+        droneGain: 0.12,
+        chunkDuration: 2.0,
+        resolveNote1: 523,
+        resolveNote2: 659,
+        resolveWaveform: "sine",
+        resolveDuration: 0.15,
+        resolveGain: 0.45,
+    },
+};
+const RETRO_PROFILE = {
+    name: "retro",
+    description: "8-bit micro-chirps — fun but controlled",
+    verbs: {
+        intake: {
+            type: "tone",
+            waveform: "square",
+            frequency: 480,
+            frequencyEnd: 720,
+            duration: 0.1,
+            envelope: { attack: 0.005, decay: 0.04, sustain: 0.3, release: 0.02 },
+            gain: 0.4,
+        },
+        transform: {
+            type: "tone",
+            waveform: "square",
+            frequency: 560,
+            duration: 0.07,
+            envelope: { attack: 0.003, decay: 0.03, sustain: 0.15, release: 0.02 },
+            gain: 0.38,
+            fmRatio: 2,
+            fmDepth: 50,
+        },
+        commit: {
+            type: "tone",
+            waveform: "square",
+            frequency: 880,
+            duration: 0.06,
+            envelope: { attack: 0.002, decay: 0.02, sustain: 0.1, release: 0.02 },
+            gain: 0.42,
+        },
+        navigate: {
+            type: "tone",
+            waveform: "square",
+            frequency: 1100,
+            duration: 0.12,
+            envelope: { attack: 0.002, decay: 0.08, sustain: 0.0, release: 0.03 },
+            gain: 0.38,
+        },
+        execute: {
+            type: "tone",
+            waveform: "square",
+            frequency: 660,
+            duration: 0.08,
+            envelope: { attack: 0.002, decay: 0.03, sustain: 0.15, release: 0.02 },
+            gain: 0.38,
+            noiseBurst: { duration: 0.03, gain: 0.3 },
+        },
+        move: {
+            type: "whoosh",
+            duration: 0.18,
+            freqUp: [800, 3500],
+            freqDown: [3500, 800],
+            bandwidth: 1.0,
+            envelope: { attack: 0.02, decay: 0.06, sustain: 0.4, release: 0.06 },
+            gain: 0.45,
+        },
+        sync: {
+            type: "whoosh",
+            duration: 0.22,
+            freqUp: [500, 4000],
+            freqDown: [4000, 500],
+            bandwidth: 0.8,
+            envelope: { attack: 0.03, decay: 0.06, sustain: 0.35, release: 0.08 },
+            gain: 0.42,
+            tonalAnchor: {
+                freqUp: [400, 800],
+                freqDown: [800, 400],
+                envelope: { attack: 0.02, decay: 0.06, sustain: 0.1, release: 0.05 },
+                gain: 0.18,
+            },
+        },
+    },
+    sessionStart: {
+        tone1: {
+            waveform: "square",
+            frequency: 523,
+            duration: 0.1,
+            envelope: { attack: 0.005, decay: 0.04, sustain: 0.2, release: 0.03 },
+            gain: 0.4,
+        },
+        tone2: {
+            waveform: "square",
+            frequency: 659,
+            duration: 0.12,
+            envelope: { attack: 0.005, decay: 0.05, sustain: 0.2, release: 0.04 },
+            gain: 0.38,
+        },
+        staggerSeconds: 0.06,
+    },
+    sessionEnd: {
+        tone1: {
+            waveform: "square",
+            frequency: 659,
+            duration: 0.08,
+            envelope: { attack: 0.005, decay: 0.04, sustain: 0.15, release: 0.02 },
+            gain: 0.38,
+        },
+        tone2: {
+            waveform: "square",
+            frequency: 523,
+            duration: 0.14,
+            envelope: { attack: 0.005, decay: 0.06, sustain: 0.15, release: 0.05 },
+            gain: 0.35,
+        },
+        staggerSeconds: 0.06,
+    },
+    ambient: {
+        droneFreq: 120,
+        droneWaveform: "square",
+        droneGain: 0.08,
+        chunkDuration: 2.0,
+        resolveNote1: 523,
+        resolveNote2: 784,
+        resolveWaveform: "square",
+        resolveDuration: 0.1,
+        resolveGain: 0.35,
+    },
+};
+const BUILTIN_PROFILES = {
+    minimal: MINIMAL_PROFILE,
+    retro: RETRO_PROFILE,
+};
+// --- Profile loading ---
+/** Get a built-in profile by name. */
+export function getBuiltinProfile(name) {
+    return BUILTIN_PROFILES[name];
+}
+/** List all built-in profile names. */
+export function listBuiltinProfiles() {
+    return Object.keys(BUILTIN_PROFILES);
+}
+/** Load a profile from a JSON file path. */
+export function loadProfileFromFile(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    // Basic validation
+    if (!parsed.name || !parsed.verbs || !parsed.sessionStart || !parsed.sessionEnd) {
+        throw new Error(`Invalid profile: missing required fields in ${filePath}`);
+    }
+    return parsed;
+}
+/**
+ * Resolve a profile by name.
+ * 1. Check built-in profiles
+ * 2. Check profiles/ directory next to the package
+ * 3. Treat as absolute/relative file path
+ */
+export function resolveProfile(nameOrPath) {
+    // Built-in?
+    const builtin = getBuiltinProfile(nameOrPath);
+    if (builtin)
+        return builtin;
+    // Check profiles/ directory relative to this package
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const profilesDir = join(__dirname, "..", "profiles");
+    const inProfilesDir = join(profilesDir, `${nameOrPath}.json`);
+    if (existsSync(inProfilesDir)) {
+        return loadProfileFromFile(inProfilesDir);
+    }
+    // Treat as file path
+    if (existsSync(nameOrPath)) {
+        return loadProfileFromFile(nameOrPath);
+    }
+    throw new Error(`Unknown profile "${nameOrPath}". Built-in: ${listBuiltinProfiles().join(", ")}`);
+}
+export const DEFAULT_PROFILE_NAME = "minimal";

package/dist/synth.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure PCM synthesis engine. Zero dependencies.
+ * Generates audio from math — oscillators, envelopes, FM, and WAV encoding.
+ */
+declare const SAMPLE_RATE = 44100;
+declare const BIT_DEPTH = 16;
+declare const NUM_CHANNELS = 1;
+export type Waveform = "sine" | "square" | "sawtooth" | "triangle" | "noise";
+export interface Envelope {
+    attack: number;
+    decay: number;
+    sustain: number;
+    release: number;
+}
+export interface ToneParams {
+    /** Base waveform */
+    waveform: Waveform;
+    /** Starting frequency in Hz */
+    frequency: number;
+    /** Ending frequency in Hz (for sweeps). If omitted, stays at `frequency`. */
+    frequencyEnd?: number;
+    /** Duration in seconds */
+    duration: number;
+    /** Amplitude envelope */
+    envelope: Envelope;
+    /** Master gain 0–1 */
+    gain: number;
+    /** FM modulator frequency ratio (relative to carrier). e.g., 2 = double the carrier freq */
+    fmRatio?: number;
+    /** FM modulation depth in Hz */
+    fmDepth?: number;
+    /** Tremolo rate in Hz (amplitude modulation) */
+    tremoloRate?: number;
+    /** Tremolo depth 0–1 (0 = no effect, 1 = full AM) */
+    tremoloDepth?: number;
+    /** Add an octave harmonic at this gain level (0–1) */
+    harmonicGain?: number;
+    /** Detune amount in Hz (creates a second oscillator for beating) */
+    detune?: number;
+}
+/** Generate a Float64 audio buffer from tone parameters. */
+export declare function generateTone(params: ToneParams): Float64Array;
+/** Mix multiple tone buffers into one (summed and normalized). */
+export declare function mixBuffers(buffers: Float64Array[]): Float64Array;
+/** Concatenate buffers sequentially with an optional gap (in seconds). */
+export declare function concatBuffers(buffers: Float64Array[], gapSeconds?: number): Float64Array;
+/** Encode a Float64 audio buffer as a WAV file (PCM 16-bit mono). */
+export declare function encodeWav(buffer: Float64Array): Buffer;
+/** Apply a hard loudness cap with gentle compression to a buffer. */
+export declare function limitLoudness(buffer: Float64Array, ceiling?: number): Float64Array;
+/** Apply a volume gain (0.0–1.0) to a buffer. */
+export declare function applyVolume(buffer: Float64Array, gain: number): Float64Array;
+export interface WhooshParams {
+    /** Duration in seconds */
+    duration: number;
+    /** Starting center frequency of the bandpass in Hz */
+    freqStart: number;
+    /** Ending center frequency of the bandpass in Hz */
+    freqEnd: number;
+    /** Bandwidth (Q) — lower = wider/breathier, higher = narrower/whistly */
+    bandwidth: number;
+    /** Amplitude envelope */
+    envelope: Envelope;
+    /** Master gain 0–1 */
+    gain: number;
+}
+/**
+ * Generate a whoosh: bandpass-filtered noise with a sweeping center frequency.
+ * Uses a state-variable filter (SVF) for stable real-time coefficient changes.
+ */
+export declare function generateWhoosh(params: WhooshParams): Float64Array;
+export { SAMPLE_RATE, BIT_DEPTH, NUM_CHANNELS };