@tensamin/audio 0.1.2 → 0.1.4

package/dist/types.d.mts

@@ -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/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.js

@@ -23,13 +23,25 @@ __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};
   }
 
   process(inputs, outputs, parameters) {
@@ -37,51 +49,89 @@ 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)
+    // Adaptive noise floor estimation
+    // When signal is quiet, adapt quickly to find new noise floor
+    // When signal is loud (speech), adapt slowly to avoid raising noise floor
     if (rms < this.noiseFloor) {
-      this.noiseFloor = this.noiseFloor * 0.99 + rms * 0.01;
+      this.noiseFloor = this.noiseFloor * (1 - this.noiseFloorAdaptRateQuiet) + rms * this.noiseFloorAdaptRateQuiet;
     } else {
-      this.noiseFloor = this.noiseFloor * 0.999 + rms * 0.001;
+      this.noiseFloor = this.noiseFloor * (1 - this.noiseFloorAdaptRateLoud) + rms * this.noiseFloorAdaptRateLoud;
     }
 
-    // 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";
   async createNode(context, config, onDecision) {
-    const blob = new Blob([energyVadWorkletCode], {
+    if (!config?.enabled) {
+      console.log("VAD disabled, using passthrough node");
+      const pass = context.createGain();
+      return pass;
+    }
+    const workletCode = createEnergyVadWorkletCode(config);
+    const blob = new Blob([workletCode], {
       type: "application/javascript"
     });
     const url = URL.createObjectURL(blob);
     try {
       await context.audioWorklet.addModule(url);
+      console.log("Energy VAD worklet loaded successfully");
     } catch (e) {
-      console.warn("Failed to add Energy VAD worklet:", e);
-      throw e;
-    } finally {
+      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;
     }
-    const node = new AudioWorkletNode(context, "energy-vad-processor");
     node.port.onmessage = (event) => {
-      const { probability } = event.data;
-      onDecision(probability);
+      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;
   }

package/dist/vad/vad-node.mjs

@@ -1,6 +1,6 @@
 import {
   EnergyVADPlugin
-} from "../chunk-UMU2KIB6.mjs";
+} from "../chunk-NMHKX64G.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.2",
+  "version": "0.1.4",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/dist/chunk-HFSKQ33X.mjs

@@ -1,38 +0,0 @@
-import {
-  createAudioPipeline
-} from "./chunk-QU7E5HBA.mjs";
-
-// src/livekit/integration.ts
-async function attachProcessingToTrack(track, config = {}) {
-  const originalTrack = track.mediaStreamTrack;
-  const pipeline = await createAudioPipeline(originalTrack, config);
-  await track.replaceTrack(pipeline.processedTrack);
-  if (config.livekit?.manageTrackMute) {
-    let isVadMuted = false;
-    pipeline.events.on("vadChange", async (state) => {
-      if (state.isSpeaking) {
-        if (isVadMuted) {
-          await track.unmute();
-          isVadMuted = false;
-        }
-      } else {
-        if (!track.isMuted) {
-          await track.mute();
-          isVadMuted = true;
-        }
-      }
-    });
-  }
-  const originalDispose = pipeline.dispose;
-  pipeline.dispose = () => {
-    if (originalTrack.readyState === "live") {
-      track.replaceTrack(originalTrack).catch(console.error);
-    }
-    originalDispose();
-  };
-  return pipeline;
-}
-
-export {
-  attachProcessingToTrack
-};