@mcptoolshop/claude-sfx 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-03-30
+
+### Added
+- **Density-aware ducking** (`mix.ts`) — rolling 3s window classifies event density as sparse/medium/bursty. Gain and release are scaled per density level. High-priority verbs (commit, sync) duck less; low-priority (navigate) ducks more during bursts.
+- **Repetition guard** — same verb firing 2+ times in 3s triggers variant rotation, gain reduction (×0.95→×0.85), and release shortening. Prevents search/grep spam from becoming a chirp wall.
+- **Remote low-pass softening** — one-pole RC filter (6dB/octave rolloff at 2500 Hz) applied to all remote-scope sounds. Mimics distance by absorbing high frequencies, complementing the existing envelope/gain changes.
+- **Per-verb ducking priorities** — commit/sync are "high" (protected from heavy ducking), navigate is "low" (maximally ducked during bursts), others are "normal"
+- **Gain floor** at 0.40 prevents sounds from disappearing under worst-case stacking (bursty + many repeats + low priority)
+- `applyLowPass(buffer, cutoffHz)` in synth.ts — reusable one-pole LP filter
+- `MixAdvice` type and `getMixAdvice()` in mix.ts — pure function returning ducking adjustments
+- `mixGain` and `mixRelease` fields in `PlayOptions` for density/repetition adjustments
+- 59 new tests (262 total)
+
 ## [1.2.1] - 2026-03-30
 
 ### Fixed

package/dist/guard.d.ts

@@ -6,6 +6,14 @@
  * Each play call reads/writes a small JSON ledger.
  */
 import { type SfxConfig } from "./config.js";
+export interface LedgerEntry {
+    verb: string;
+    timestamp: number;
+}
+export interface Ledger {
+    entries: LedgerEntry[];
+}
+export declare function readLedger(): Ledger;
 export interface GuardResult {
     allowed: boolean;
     reason?: string;

package/dist/guard.js

@@ -18,7 +18,7 @@ const RATE_LIMIT_MAX = 8;
 const RATE_LIMIT_WINDOW_MS = 10_000;
 /** Ledger file — tiny JSON tracking recent plays. */
 const LEDGER_FILE = join(tmpdir(), "claude-sfx-ledger.json");
-function readLedger() {
+export function readLedger() {
     if (!existsSync(LEDGER_FILE)) {
         return { entries: [] };
     }

package/dist/hook-handler.js

@@ -14,7 +14,8 @@ import { applyVolume } from "./synth.js";
 import { playSync } from "./player.js";
 import { resolveProfile } from "./profiles.js";
 import { loadConfig, resolveProfileName, volumeToGain } from "./config.js";
-import { guardPlay } from "./guard.js";
+import { guardPlay, readLedger } from "./guard.js";
+import { getMixAdvice } from "./mix.js";
 import { resolveAmbient, isAmbientRunning } from "./ambient.js";
 import { recordSuccess, recordError, getSessionOutcome, resetStreak } from "./streak.js";
 /** Map a PostToolUse tool_name to a verb + options. */
@@ -122,6 +123,18 @@ function playVerb(verb, options = {}) {
         const { intensity } = recordSuccess(verb);
         options = { ...options, intensity };
     }
+    // Mix intelligence — density ducking + repetition guard
+    const ledger = readLedger();
+    const advice = getMixAdvice(verb, ledger.entries);
+    if (advice.gainMultiplier < 1) {
+        options = { ...options, mixGain: advice.gainMultiplier };
+    }
+    if (advice.releaseMultiplier < 1) {
+        options = { ...options, mixRelease: advice.releaseMultiplier };
+    }
+    if (advice.forcedVariantIndex !== undefined && options.variantIndex === undefined) {
+        options = { ...options, variantIndex: advice.forcedVariantIndex };
+    }
     const profileName = resolveProfileName(config);
     const profile = resolveProfile(profileName);
     let buffer = generateVerb(profile, verb, options);

package/dist/mix.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Mix intelligence — density-aware ducking and repetition guard.
+ * Pure functions that read the guard ledger and return adjustment advice.
+ * No side effects, no writes — the guard module owns the ledger.
+ */
+import type { LedgerEntry } from "./guard.js";
+export type DensityLevel = "sparse" | "medium" | "bursty";
+export type DuckingPriority = "high" | "normal" | "low";
+export interface MixAdvice {
+    /** Gain multiplier (0.4–1.0), applied on top of existing gain. */
+    gainMultiplier: number;
+    /** Release multiplier (< 1.0 shortens tails under density). */
+    releaseMultiplier: number;
+    /** If set, force this variant index (for repetition rotation). */
+    forcedVariantIndex?: number;
+    /** Current density level (for diagnostics/testing). */
+    density: DensityLevel;
+    /** How many times the same verb repeated recently. */
+    recentRepeatCount: number;
+}
+/**
+ * Classify event density based on recent entries in the window.
+ * 0–2 events = sparse, 3–5 = medium, 6+ = bursty.
+ */
+export declare function classifyDensity(entries: LedgerEntry[], now?: number): DensityLevel;
+/**
+ * Count how many times the same verb fired in the recent window.
+ * Returns the count of prior occurrences (0 = first time).
+ */
+export declare function countRecentRepeats(entries: LedgerEntry[], verb: string, now?: number, windowMs?: number): number;
+/**
+ * Get the ducking priority for a verb.
+ * High = important culmination events (less ducking).
+ * Low = frequent scan events (more ducking during bursts).
+ * Normal = everything else.
+ */
+export declare function getDuckingPriority(verb: string): DuckingPriority;
+/**
+ * Compute mix advice for a verb given the current ledger state.
+ * Returns gain/release multipliers, optional forced variant, and diagnostics.
+ */
+export declare function getMixAdvice(verb: string, entries: LedgerEntry[], now?: number): MixAdvice;

package/dist/mix.js

@@ -0,0 +1,119 @@
+/**
+ * Mix intelligence — density-aware ducking and repetition guard.
+ * Pure functions that read the guard ledger and return adjustment advice.
+ * No side effects, no writes — the guard module owns the ledger.
+ */
+// --- Constants ---
+/** Window for density classification and repeat counting. */
+const DENSITY_WINDOW_MS = 3000;
+/** Minimum gain multiplier — prevents sounds from disappearing entirely. */
+const GAIN_FLOOR = 0.40;
+// --- Density classification ---
+/**
+ * Classify event density based on recent entries in the window.
+ * 0–2 events = sparse, 3–5 = medium, 6+ = bursty.
+ */
+export function classifyDensity(entries, now = Date.now()) {
+    const cutoff = now - DENSITY_WINDOW_MS;
+    const recent = entries.filter((e) => e.timestamp > cutoff);
+    if (recent.length <= 2)
+        return "sparse";
+    if (recent.length <= 5)
+        return "medium";
+    return "bursty";
+}
+// --- Repetition counting ---
+/**
+ * Count how many times the same verb fired in the recent window.
+ * Returns the count of prior occurrences (0 = first time).
+ */
+export function countRecentRepeats(entries, verb, now = Date.now(), windowMs = DENSITY_WINDOW_MS) {
+    const cutoff = now - windowMs;
+    return entries.filter((e) => e.timestamp > cutoff && e.verb === verb).length;
+}
+// --- Priority tiers ---
+/**
+ * Get the ducking priority for a verb.
+ * High = important culmination events (less ducking).
+ * Low = frequent scan events (more ducking during bursts).
+ * Normal = everything else.
+ */
+export function getDuckingPriority(verb) {
+    switch (verb) {
+        case "commit":
+        case "sync":
+            return "high";
+        case "navigate":
+            return "low";
+        default:
+            return "normal";
+    }
+}
+// --- Density ducking tables ---
+const DENSITY_GAIN = {
+    sparse: { high: 1.0, normal: 1.0, low: 1.0 },
+    medium: { high: 0.95, normal: 0.88, low: 0.82 },
+    bursty: { high: 0.90, normal: 0.75, low: 0.65 },
+};
+const DENSITY_RELEASE = {
+    sparse: 1.0,
+    medium: 0.85,
+    bursty: 0.70,
+};
+// --- Repetition ducking ---
+function getRepetitionGain(repeatCount) {
+    if (repeatCount <= 1)
+        return 1.0;
+    if (repeatCount === 2)
+        return 0.95;
+    if (repeatCount === 3)
+        return 0.90;
+    return 0.85; // 4+
+}
+function getRepetitionRelease(repeatCount) {
+    if (repeatCount <= 1)
+        return 1.0;
+    if (repeatCount === 2)
+        return 1.0;
+    if (repeatCount === 3)
+        return 0.85;
+    return 0.80; // 4+
+}
+/**
+ * Determine variant rotation for repeated verbs.
+ * After 2+ repeats, force rotation to the next variant.
+ */
+function getRepetitionVariant(entries, verb, now, repeatCount) {
+    if (repeatCount < 2)
+        return undefined;
+    // Rotate based on repeat count (simple modular rotation across 3 variants)
+    return repeatCount % 3;
+}
+// --- Main entry point ---
+/**
+ * Compute mix advice for a verb given the current ledger state.
+ * Returns gain/release multipliers, optional forced variant, and diagnostics.
+ */
+export function getMixAdvice(verb, entries, now = Date.now()) {
+    const density = classifyDensity(entries, now);
+    const priority = getDuckingPriority(verb);
+    const repeatCount = countRecentRepeats(entries, verb, now);
+    // Density ducking
+    const densityGain = DENSITY_GAIN[density][priority];
+    const densityRelease = DENSITY_RELEASE[density];
+    // Repetition ducking (composes multiplicatively)
+    const repGain = getRepetitionGain(repeatCount);
+    const repRelease = getRepetitionRelease(repeatCount);
+    // Compose
+    const gainMultiplier = Math.max(densityGain * repGain, GAIN_FLOOR);
+    const releaseMultiplier = Math.max(densityRelease * repRelease, 0.50);
+    // Variant rotation
+    const forcedVariantIndex = getRepetitionVariant(entries, verb, now, repeatCount);
+    return {
+        gainMultiplier,
+        releaseMultiplier,
+        forcedVariantIndex,
+        density,
+        recentRepeatCount: repeatCount,
+    };
+}

package/dist/synth.d.ts

@@ -46,6 +46,11 @@ export declare function mixBuffers(buffers: Float64Array[]): Float64Array;
 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;
+/**
+ * One-pole RC low-pass filter.
+ * Gentle 6dB/octave rolloff — mimics distance (air absorbs highs).
+ */
+export declare function applyLowPass(buffer: Float64Array, cutoffHz: number): Float64Array;
 /** 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. */

package/dist/synth.js

@@ -187,6 +187,21 @@ export function encodeWav(buffer) {
     }
     return wav;
 }
+// --- Low-Pass Filter ---
+/**
+ * One-pole RC low-pass filter.
+ * Gentle 6dB/octave rolloff — mimics distance (air absorbs highs).
+ */
+export function applyLowPass(buffer, cutoffHz) {
+    const a = Math.exp(-2 * Math.PI * cutoffHz / SAMPLE_RATE);
+    const result = new Float64Array(buffer.length);
+    let prev = 0;
+    for (let i = 0; i < buffer.length; i++) {
+        prev = (1 - a) * buffer[i] + a * prev;
+        result[i] = prev;
+    }
+    return result;
+}
 // --- Loudness Limiter ---
 /** Apply a hard loudness cap with gentle compression to a buffer. */
 export function limitLoudness(buffer, ceiling = 0.85) {

package/dist/verbs.d.ts

@@ -19,6 +19,10 @@ export interface PlayOptions {
     escalation?: number;
     /** Override variant selection (0-indexed). For testing determinism. */
     variantIndex?: number;
+    /** Mix-layer gain multiplier from density/repetition analysis (0.4–1.0). */
+    mixGain?: number;
+    /** Mix-layer release multiplier from density/repetition analysis. */
+    mixRelease?: number;
 }
 export type Verb = "intake" | "transform" | "commit" | "navigate" | "execute" | "move" | "sync";
 export declare const VERB_LABELS: Record<Verb, string>;

package/dist/verbs.js

@@ -5,7 +5,7 @@
  * Architecture: multi-note motifs in A major pentatonic with constrained variation.
  * Each verb has 3 variants. Micro-jitter keeps sounds alive without breaking identity.
  */
-import { SAMPLE_RATE, generateTone, generateWhoosh, mixBuffers, limitLoudness, } from "./synth.js";
+import { SAMPLE_RATE, generateTone, generateWhoosh, mixBuffers, limitLoudness, applyLowPass, applyVolume, } from "./synth.js";
 import { SCALE, scaleStepDown } from "./profiles.js";
 export const VERB_LABELS = {
     intake: "Intake",
@@ -335,6 +335,30 @@ function applyWhooshEscalation(params, escalation) {
     }
     return p;
 }
+// --- Mix modifiers (density/repetition from Pass B) ---
+/** Scale all note release times in a motif (density/repetition ducking). */
+function applyMotifMixRelease(variant, multiplier) {
+    if (multiplier >= 1)
+        return variant;
+    return {
+        ...variant,
+        notes: variant.notes.map(n => ({
+            ...n,
+            envelope: { ...n.envelope, release: n.envelope.release * multiplier },
+        })),
+    };
+}
+/** Scale whoosh envelope release (density/repetition ducking). */
+function applyWhooshMixRelease(params, multiplier) {
+    if (multiplier >= 1)
+        return params;
+    return {
+        ...params,
+        envelope: { ...params.envelope, release: params.envelope.release * multiplier },
+    };
+}
+/** Low-pass cutoff for remote scope (Hz). Gentle rolloff mimicking distance. */
+const REMOTE_LP_CUTOFF = 2500;
 // --- Main generation ---
 /** Generate a verb sound using the given profile. */
 export function generateVerb(profile, verb, options = {}) {
@@ -342,6 +366,7 @@ export function generateVerb(profile, verb, options = {}) {
     if (!cfg) {
         throw new Error(`Profile "${profile.name}" has no config for verb "${verb}"`);
     }
+    const isRemote = options.scope === "remote";
     // ── Whoosh-based verbs (move, sync) ─────────────────────────
     if (cfg.type === "whoosh") {
         const dir = options.direction ?? "up";
@@ -362,11 +387,13 @@ export function generateVerb(profile, verb, options = {}) {
             wp = applyWhooshIntensity(wp, options.intensity);
         if (options.escalation)
             wp = applyWhooshEscalation(wp, options.escalation);
+        if (options.mixRelease && options.mixRelease < 1)
+            wp = applyWhooshMixRelease(wp, options.mixRelease);
         const whooshBuf = generateWhoosh(wp);
         // Tonal anchor variant
+        let result;
         if (cfg.anchorVariants && cfg.anchorVariants.length > 0) {
             let anchor = pickVariant(cfg.anchorVariants, options.variantIndex);
-            // Apply motif modifiers to anchor notes too
             let anchorMotif = { notes: anchor.notes };
             if (options.status)
                 anchorMotif = applyMotifStatus(anchorMotif, options.status);
@@ -376,16 +403,26 @@ export function generateVerb(profile, verb, options = {}) {
                 anchorMotif = applyMotifIntensity(anchorMotif, options.intensity);
             if (options.escalation)
                 anchorMotif = applyMotifEscalation(anchorMotif, options.escalation);
+            if (options.mixRelease && options.mixRelease < 1)
+                anchorMotif = applyMotifMixRelease(anchorMotif, options.mixRelease);
             const anchorBuf = renderMotif(anchorMotif, cfg.gain);
-            // Mix: align to same start, extend to longest
             const maxLen = Math.max(whooshBuf.length, anchorBuf.length);
             const whooshPadded = new Float64Array(maxLen);
             whooshPadded.set(whooshBuf, 0);
             const anchorPadded = new Float64Array(maxLen);
             anchorPadded.set(anchorBuf, 0);
-            return limitLoudness(mixBuffers([whooshPadded, anchorPadded]));
+            result = mixBuffers([whooshPadded, anchorPadded]);
+        }
+        else {
+            result = whooshBuf;
         }
-        return limitLoudness(whooshBuf);
+        // Remote low-pass softening
+        if (isRemote)
+            result = applyLowPass(result, REMOTE_LP_CUTOFF);
+        // Mix gain ducking
+        if (options.mixGain && options.mixGain < 1)
+            result = applyVolume(result, options.mixGain);
+        return limitLoudness(result);
     }
     // ── Motif-based verbs (intake, transform, commit, navigate, execute) ──
     let variant = pickVariant(cfg.variants, options.variantIndex);
@@ -397,7 +434,15 @@ export function generateVerb(profile, verb, options = {}) {
         variant = applyMotifIntensity(variant, options.intensity);
     if (options.escalation)
         variant = applyMotifEscalation(variant, options.escalation);
-    const buffer = renderMotif(variant, cfg.gain);
+    if (options.mixRelease && options.mixRelease < 1)
+        variant = applyMotifMixRelease(variant, options.mixRelease);
+    let buffer = renderMotif(variant, cfg.gain);
+    // Remote low-pass softening
+    if (isRemote)
+        buffer = applyLowPass(buffer, REMOTE_LP_CUTOFF);
+    // Mix gain ducking
+    if (options.mixGain && options.mixGain < 1)
+        buffer = applyVolume(buffer, options.mixGain);
     return limitLoudness(buffer);
 }
 // --- Session sounds ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/claude-sfx",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Procedural audio feedback for Claude Code — UX for agentic coding",
   "type": "module",
   "bin": {