@tensamin/audio 0.1.3 → 0.1.5

package/dist/types.d.ts

@@ -35,46 +35,154 @@ interface AudioProcessingConfig {
     vad?: {
         enabled: boolean;
         /**
-         * Plugin name to use. Defaults to 'rnnoise-vad' or 'energy-vad'.
+         * Plugin name to use. Defaults to 'energy-vad'.
          */
         pluginName?: string;
         /**
          * Probability threshold for speech onset (0-1).
-         * Default: 0.5
+         * When VAD probability rises above this, audio is unmuted.
+         * Lower = more sensitive (catches quiet speech, may include noise)
+         * Higher = less sensitive (only confident speech, may clip quiet parts)
+         * Default: 0.6 (optimized for voice-only)
          */
         startThreshold?: number;
         /**
          * Probability threshold for speech offset (0-1).
-         * Default: 0.4
+         * When VAD probability drops below this (after hangover), audio is muted.
+         * Lower = keeps audio on longer (less aggressive gating)
+         * Higher = mutes faster (more aggressive noise suppression)
+         * Default: 0.45 (balanced voice detection)
          */
         stopThreshold?: number;
         /**
-         * Time in ms to wait after speech stops before considering it silent.
-         * Default: 300ms
+         * Time in ms to wait after speech stops before muting.
+         * Prevents rapid on/off toggling during pauses.
+         * Lower = more aggressive gating, may clip between words
+         * Higher = smoother but may let trailing noise through
+         * Default: 400ms (optimized for natural speech)
          */
         hangoverMs?: number;
         /**
-         * Time in ms of audio to buffer before speech onset to avoid cutting the start.
-         * Default: 200ms
+         * Time in ms of audio to buffer before speech onset.
+         * Prevents cutting off the beginning of speech.
+         * Default: 250ms (generous pre-roll for voice)
          */
         preRollMs?: number;
+        /**
+         * Minimum speech duration in ms to consider it valid speech.
+         * Filters out very brief noise spikes.
+         * Default: 100ms
+         */
+        minSpeechDurationMs?: number;
+        /**
+         * Minimum silence duration in ms before allowing another speech segment.
+         * Prevents false positives from quick noise bursts.
+         * Default: 150ms
+         */
+        minSilenceDurationMs?: number;
+        /**
+         * Advanced: Energy VAD specific parameters
+         */
+        energyVad?: {
+            /**
+             * Smoothing factor for energy calculation (0-1).
+             * Higher = more smoothing, slower to react
+             * Default: 0.95
+             */
+            smoothing?: number;
+            /**
+             * Initial noise floor estimate.
+             * Default: 0.001
+             */
+            initialNoiseFloor?: number;
+            /**
+             * Rate at which noise floor adapts to quiet signals (0-1).
+             * Default: 0.01
+             */
+            noiseFloorAdaptRateQuiet?: number;
+            /**
+             * Rate at which noise floor adapts to loud signals (0-1).
+             * Default: 0.001 (slower adaptation for speech)
+             */
+            noiseFloorAdaptRateLoud?: number;
+            /**
+             * Minimum SNR (Signal-to-Noise Ratio) for speech detection.
+             * Default: 2.0 (voice is 2x louder than noise floor)
+             */
+            minSNR?: number;
+            /**
+             * SNR range for probability scaling.
+             * Default: 8.0 (probability scales from minSNR to minSNR+snrRange)
+             */
+            snrRange?: number;
+        };
     };
     /**
      * Output gain and muting configuration.
      */
     output?: {
         /**
-         * Gain to apply when speaking (0-1+). Default: 1.0
+         * Gain to apply when speaking (0-infinity).
+         * Values > 1.0 will amplify the voice.
+         * Default: 1.0 (unity gain)
          */
         speechGain?: number;
         /**
-         * Gain to apply when silent (0-1). Default: 0.0 (mute)
+         * Gain to apply when silent (0-1).
+         * 0.0 = complete mute (recommended for voice-only)
+         * 0.1-0.3 = allow some background ambience
+         * Default: 0.0 (full mute for voice-only)
          */
         silenceGain?: number;
         /**
-         * Time in seconds to ramp gain changes. Default: 0.02
+         * Time in seconds to ramp gain changes.
+         * Lower = faster transitions (may cause clicks)
+         * Higher = smoother transitions (may sound sluggish)
+         * Default: 0.015 (fast but smooth for voice)
          */
         gainRampTime?: number;
+        /**
+         * Apply additional gain reduction during the transition to silence.
+         * Helps create cleaner cutoffs without abrupt clicks.
+         * Default: true
+         */
+        smoothTransitions?: boolean;
+        /**
+         * Maximum gain in dB to apply (prevents clipping).
+         * Default: 6.0 dB (roughly 2x amplitude)
+         */
+        maxGainDb?: number;
+        /**
+         * Apply dynamic range compression when speaking.
+         * Makes quiet parts louder and loud parts quieter.
+         * Default: false (transparent audio)
+         */
+        enableCompression?: boolean;
+        /**
+         * Compression settings (when enabled)
+         */
+        compression?: {
+            /**
+             * Threshold in dB above which compression starts.
+             * Default: -24.0 dB
+             */
+            threshold?: number;
+            /**
+             * Compression ratio (1:N).
+             * Default: 3.0 (3:1 ratio)
+             */
+            ratio?: number;
+            /**
+             * Attack time in seconds.
+             * Default: 0.003 (3ms)
+             */
+            attack?: number;
+            /**
+             * Release time in seconds.
+             * Default: 0.05 (50ms)
+             */
+            release?: number;
+        };
     };
     /**
      * LiveKit integration configuration.

package/dist/vad/vad-node.d.mts

@@ -3,7 +3,9 @@ import 'mitt';
 
 declare class EnergyVADPlugin implements VADPlugin {
     name: string;
+    private workletNode;
     createNode(context: AudioContext, config: AudioProcessingConfig["vad"], onDecision: (probability: number) => void): Promise<AudioNode>;
+    updateSpeakingState(isSpeaking: boolean): void;
 }
 
 export { EnergyVADPlugin };

package/dist/vad/vad-node.d.ts

@@ -3,7 +3,9 @@ import 'mitt';
 
 declare class EnergyVADPlugin implements VADPlugin {
     name: string;
+    private workletNode;
     createNode(context: AudioContext, config: AudioProcessingConfig["vad"], onDecision: (probability: number) => void): Promise<AudioNode>;
+    updateSpeakingState(isSpeaking: boolean): void;
 }
 
 export { EnergyVADPlugin };

package/dist/vad/vad-node.js

@@ -23,13 +23,32 @@ __export(vad_node_exports, {
   EnergyVADPlugin: () => EnergyVADPlugin
 });
 module.exports = __toCommonJS(vad_node_exports);
-var energyVadWorkletCode = `
+var createEnergyVadWorkletCode = (vadConfig) => {
+  const energyParams = vadConfig?.energyVad || {};
+  const smoothing = energyParams.smoothing ?? 0.95;
+  const initialNoiseFloor = energyParams.initialNoiseFloor ?? 1e-3;
+  const noiseFloorAdaptRateQuiet = energyParams.noiseFloorAdaptRateQuiet ?? 0.01;
+  const noiseFloorAdaptRateLoud = energyParams.noiseFloorAdaptRateLoud ?? 1e-3;
+  const minSNR = energyParams.minSNR ?? 2;
+  const snrRange = energyParams.snrRange ?? 8;
+  return `
 class EnergyVadProcessor extends AudioWorkletProcessor {
   constructor() {
     super();
-    this.smoothing = 0.95;
+    this.smoothing = ${smoothing};
     this.energy = 0;
-    this.noiseFloor = 0.001;
+    this.noiseFloor = ${initialNoiseFloor};
+    this.noiseFloorAdaptRateQuiet = ${noiseFloorAdaptRateQuiet};
+    this.noiseFloorAdaptRateLoud = ${noiseFloorAdaptRateLoud};
+    this.minSNR = ${minSNR};
+    this.snrRange = ${snrRange};
+    this.isSpeaking = false;
+    
+    this.port.onmessage = (event) => {
+      if (event.data && event.data.isSpeaking !== undefined) {
+        this.isSpeaking = event.data.isSpeaking;
+      }
+    };
   }
 
   process(inputs, outputs, parameters) {
@@ -37,41 +56,54 @@ class EnergyVadProcessor extends AudioWorkletProcessor {
     if (!input || !input.length) return true;
     const channel = input[0];
     
-    // Calculate RMS
+    // Calculate RMS (Root Mean Square) energy
     let sum = 0;
     for (let i = 0; i < channel.length; i++) {
       sum += channel[i] * channel[i];
     }
     const rms = Math.sqrt(sum / channel.length);
 
-    // Simple adaptive noise floor (very basic)
-    if (rms < this.noiseFloor) {
-      this.noiseFloor = this.noiseFloor * 0.99 + rms * 0.01;
-    } else {
-      this.noiseFloor = this.noiseFloor * 0.999 + rms * 0.001;
+    // Adaptive noise floor estimation - ONLY during silence
+    // This prevents the noise floor from rising during speech
+    if (!this.isSpeaking) {
+      if (rms < this.noiseFloor) {
+        this.noiseFloor = this.noiseFloor * (1 - this.noiseFloorAdaptRateQuiet) + rms * this.noiseFloorAdaptRateQuiet;
+      } else {
+        // Even during silence, if we detect a loud signal, adapt very slowly
+        // This could be brief noise we haven't classified as speech yet
+        this.noiseFloor = this.noiseFloor * (1 - this.noiseFloorAdaptRateLoud) + rms * this.noiseFloorAdaptRateLoud;
+      }
     }
+    // During speech, freeze the noise floor to maintain consistent detection
 
-    // Calculate "probability" based on SNR
-    // This is a heuristic mapping from energy to 0-1
+    // Calculate Signal-to-Noise Ratio (SNR)
     const snr = rms / (this.noiseFloor + 1e-6);
-    const probability = Math.min(1, Math.max(0, (snr - 1.5) / 10)); // Arbitrary scaling
+    
+    // Map SNR to probability (0-1)
+    // Probability is 0 when SNR <= minSNR
+    // Probability scales linearly from 0 to 1 between minSNR and (minSNR + snrRange)
+    // Probability is 1 when SNR >= (minSNR + snrRange)
+    const probability = Math.min(1, Math.max(0, (snr - this.minSNR) / this.snrRange));
 
-    this.port.postMessage({ probability });
+    this.port.postMessage({ probability, snr, noiseFloor: this.noiseFloor, rms });
 
     return true;
   }
 }
 registerProcessor('energy-vad-processor', EnergyVadProcessor);
 `;
+};
 var EnergyVADPlugin = class {
   name = "energy-vad";
+  workletNode = null;
   async createNode(context, config, onDecision) {
     if (!config?.enabled) {
       console.log("VAD disabled, using passthrough node");
       const pass = context.createGain();
       return pass;
     }
-    const blob = new Blob([energyVadWorkletCode], {
+    const workletCode = createEnergyVadWorkletCode(config);
+    const blob = new Blob([workletCode], {
       type: "application/javascript"
     });
     const url = URL.createObjectURL(blob);
@@ -90,6 +122,7 @@ var EnergyVADPlugin = class {
     let node;
     try {
       node = new AudioWorkletNode(context, "energy-vad-processor");
+      this.workletNode = node;
       console.log("Energy VAD node created successfully");
     } catch (e) {
       const error = new Error(
@@ -115,6 +148,11 @@ var EnergyVADPlugin = class {
     };
     return node;
   }
+  updateSpeakingState(isSpeaking) {
+    if (this.workletNode) {
+      this.workletNode.port.postMessage({ isSpeaking });
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/vad/vad-node.mjs

@@ -1,6 +1,6 @@
 import {
   EnergyVADPlugin
-} from "../chunk-R5JVHKWA.mjs";
+} from "../chunk-VEJXAEMM.mjs";
 export {
   EnergyVADPlugin
 };

package/dist/vad/vad-state.d.mts

@@ -6,6 +6,7 @@ declare class VADStateMachine {
     private currentState;
     private lastSpeechTime;
     private speechStartTime;
+    private lastSilenceTime;
     private frameDurationMs;
     constructor(config: AudioProcessingConfig["vad"]);
     updateConfig(config: Partial<AudioProcessingConfig["vad"]>): void;

package/dist/vad/vad-state.d.ts

@@ -6,6 +6,7 @@ declare class VADStateMachine {
     private currentState;
     private lastSpeechTime;
     private speechStartTime;
+    private lastSilenceTime;
     private frameDurationMs;
     constructor(config: AudioProcessingConfig["vad"]);
     updateConfig(config: Partial<AudioProcessingConfig["vad"]>): void;

package/dist/vad/vad-state.js

@@ -28,31 +28,60 @@ var VADStateMachine = class {
   currentState = "silent";
   lastSpeechTime = 0;
   speechStartTime = 0;
+  lastSilenceTime = 0;
   frameDurationMs = 20;
   // Assumed frame duration, updated by calls
   constructor(config) {
     this.config = {
       enabled: config?.enabled ?? true,
       pluginName: config?.pluginName ?? "energy-vad",
-      startThreshold: config?.startThreshold ?? 0.5,
-      stopThreshold: config?.stopThreshold ?? 0.4,
-      hangoverMs: config?.hangoverMs ?? 300,
-      preRollMs: config?.preRollMs ?? 200
+      // Voice-optimized defaults
+      startThreshold: config?.startThreshold ?? 0.6,
+      // Higher threshold to avoid noise
+      stopThreshold: config?.stopThreshold ?? 0.45,
+      // Balanced for voice
+      hangoverMs: config?.hangoverMs ?? 400,
+      // Smooth for natural speech
+      preRollMs: config?.preRollMs ?? 250,
+      // Generous pre-roll
+      minSpeechDurationMs: config?.minSpeechDurationMs ?? 100,
+      minSilenceDurationMs: config?.minSilenceDurationMs ?? 150,
+      energyVad: {
+        smoothing: config?.energyVad?.smoothing ?? 0.95,
+        initialNoiseFloor: config?.energyVad?.initialNoiseFloor ?? 1e-3,
+        noiseFloorAdaptRateQuiet: config?.energyVad?.noiseFloorAdaptRateQuiet ?? 0.01,
+        noiseFloorAdaptRateLoud: config?.energyVad?.noiseFloorAdaptRateLoud ?? 1e-3,
+        minSNR: config?.energyVad?.minSNR ?? 2,
+        snrRange: config?.energyVad?.snrRange ?? 8
+      }
     };
+    this.lastSilenceTime = Date.now();
   }
   updateConfig(config) {
     this.config = { ...this.config, ...config };
   }
   processFrame(probability, timestamp) {
-    const { startThreshold, stopThreshold, hangoverMs } = this.config;
+    const {
+      startThreshold,
+      stopThreshold,
+      hangoverMs,
+      minSpeechDurationMs,
+      minSilenceDurationMs
+    } = this.config;
     let newState = this.currentState;
     if (this.currentState === "silent" || this.currentState === "speech_ending") {
       if (probability >= startThreshold) {
-        newState = "speech_starting";
-        this.speechStartTime = timestamp;
-        this.lastSpeechTime = timestamp;
+        const silenceDuration = timestamp - this.lastSilenceTime;
+        if (silenceDuration >= minSilenceDurationMs) {
+          newState = "speech_starting";
+          this.speechStartTime = timestamp;
+          this.lastSpeechTime = timestamp;
+        } else {
+          newState = "silent";
+        }
       } else {
         newState = "silent";
+        this.lastSilenceTime = timestamp;
       }
     } else if (this.currentState === "speech_starting" || this.currentState === "speaking") {
       if (probability >= stopThreshold) {
@@ -60,10 +89,15 @@ var VADStateMachine = class {
         this.lastSpeechTime = timestamp;
       } else {
         const timeSinceSpeech = timestamp - this.lastSpeechTime;
+        const speechDuration = timestamp - this.speechStartTime;
         if (timeSinceSpeech < hangoverMs) {
           newState = "speaking";
+        } else if (speechDuration < minSpeechDurationMs) {
+          newState = "silent";
+          this.lastSilenceTime = timestamp;
         } else {
           newState = "speech_ending";
+          this.lastSilenceTime = timestamp;
         }
       }
     }

package/dist/vad/vad-state.mjs

@@ -1,6 +1,6 @@
 import {
   VADStateMachine
-} from "../chunk-JJASCVEW.mjs";
+} from "../chunk-N553RHTI.mjs";
 export {
   VADStateMachine
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tensamin/audio",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/dist/chunk-JJASCVEW.mjs

@@ -1,59 +0,0 @@
-// src/vad/vad-state.ts
-var VADStateMachine = class {
-  config;
-  currentState = "silent";
-  lastSpeechTime = 0;
-  speechStartTime = 0;
-  frameDurationMs = 20;
-  // Assumed frame duration, updated by calls
-  constructor(config) {
-    this.config = {
-      enabled: config?.enabled ?? true,
-      pluginName: config?.pluginName ?? "energy-vad",
-      startThreshold: config?.startThreshold ?? 0.5,
-      stopThreshold: config?.stopThreshold ?? 0.4,
-      hangoverMs: config?.hangoverMs ?? 300,
-      preRollMs: config?.preRollMs ?? 200
-    };
-  }
-  updateConfig(config) {
-    this.config = { ...this.config, ...config };
-  }
-  processFrame(probability, timestamp) {
-    const { startThreshold, stopThreshold, hangoverMs } = this.config;
-    let newState = this.currentState;
-    if (this.currentState === "silent" || this.currentState === "speech_ending") {
-      if (probability >= startThreshold) {
-        newState = "speech_starting";
-        this.speechStartTime = timestamp;
-        this.lastSpeechTime = timestamp;
-      } else {
-        newState = "silent";
-      }
-    } else if (this.currentState === "speech_starting" || this.currentState === "speaking") {
-      if (probability >= stopThreshold) {
-        newState = "speaking";
-        this.lastSpeechTime = timestamp;
-      } else {
-        const timeSinceSpeech = timestamp - this.lastSpeechTime;
-        if (timeSinceSpeech < hangoverMs) {
-          newState = "speaking";
-        } else {
-          newState = "speech_ending";
-        }
-      }
-    }
-    if (newState === "speech_starting") newState = "speaking";
-    if (newState === "speech_ending") newState = "silent";
-    this.currentState = newState;
-    return {
-      isSpeaking: newState === "speaking",
-      probability,
-      state: newState
-    };
-  }
-};
-
-export {
-  VADStateMachine
-};

package/dist/chunk-R5JVHKWA.mjs

@@ -1,98 +0,0 @@
-// src/vad/vad-node.ts
-var energyVadWorkletCode = `
-class EnergyVadProcessor extends AudioWorkletProcessor {
-  constructor() {
-    super();
-    this.smoothing = 0.95;
-    this.energy = 0;
-    this.noiseFloor = 0.001;
-  }
-
-  process(inputs, outputs, parameters) {
-    const input = inputs[0];
-    if (!input || !input.length) return true;
-    const channel = input[0];
-    
-    // Calculate RMS
-    let sum = 0;
-    for (let i = 0; i < channel.length; i++) {
-      sum += channel[i] * channel[i];
-    }
-    const rms = Math.sqrt(sum / channel.length);
-
-    // Simple adaptive noise floor (very basic)
-    if (rms < this.noiseFloor) {
-      this.noiseFloor = this.noiseFloor * 0.99 + rms * 0.01;
-    } else {
-      this.noiseFloor = this.noiseFloor * 0.999 + rms * 0.001;
-    }
-
-    // Calculate "probability" based on SNR
-    // This is a heuristic mapping from energy to 0-1
-    const snr = rms / (this.noiseFloor + 1e-6);
-    const probability = Math.min(1, Math.max(0, (snr - 1.5) / 10)); // Arbitrary scaling
-
-    this.port.postMessage({ probability });
-
-    return true;
-  }
-}
-registerProcessor('energy-vad-processor', EnergyVadProcessor);
-`;
-var EnergyVADPlugin = class {
-  name = "energy-vad";
-  async createNode(context, config, onDecision) {
-    if (!config?.enabled) {
-      console.log("VAD disabled, using passthrough node");
-      const pass = context.createGain();
-      return pass;
-    }
-    const blob = new Blob([energyVadWorkletCode], {
-      type: "application/javascript"
-    });
-    const url = URL.createObjectURL(blob);
-    try {
-      await context.audioWorklet.addModule(url);
-      console.log("Energy VAD worklet loaded successfully");
-    } catch (e) {
-      const error = new Error(
-        `Failed to load Energy VAD worklet: ${e instanceof Error ? e.message : String(e)}`
-      );
-      console.error(error.message);
-      URL.revokeObjectURL(url);
-      throw error;
-    }
-    URL.revokeObjectURL(url);
-    let node;
-    try {
-      node = new AudioWorkletNode(context, "energy-vad-processor");
-      console.log("Energy VAD node created successfully");
-    } catch (e) {
-      const error = new Error(
-        `Failed to create Energy VAD node: ${e instanceof Error ? e.message : String(e)}`
-      );
-      console.error(error.message);
-      throw error;
-    }
-    node.port.onmessage = (event) => {
-      try {
-        const { probability } = event.data;
-        if (typeof probability === "number" && !isNaN(probability)) {
-          onDecision(probability);
-        } else {
-          console.warn("Invalid VAD probability received:", event.data);
-        }
-      } catch (error) {
-        console.error("Error in VAD message handler:", error);
-      }
-    };
-    node.port.onmessageerror = (event) => {
-      console.error("VAD port message error:", event);
-    };
-    return node;
-  }
-};
-
-export {
-  EnergyVADPlugin
-};