@tensamin/audio 0.1.2 → 0.1.3

package/README.md

@@ -7,7 +7,7 @@ A audio processing library for the web, featuring RNNoise-based noise suppressio
 - **Noise Suppression**: Uses `@sapphi-red/web-noise-suppressor` (RNNoise) for high-quality noise reduction.
 - **Robust VAD**: Energy-based VAD with hysteresis, hangover, and pre-roll buffering to prevent cutting off speech onset.
 - **Intelligent Muting**: Automatically gates audio or mutes LiveKit tracks when silent.
-- **LiveKit Integration**: First-class support for `LocalAudioTrack`.
+- **LiveKit Integration**: Good support for `LocalAudioTrack`.
 - **Extensible**: Plugin system for custom WASM/Worklet processors.
 
 ## Installation
@@ -20,18 +20,43 @@ pnpm install @tensamin/audio livekit-client
 
 ## Setup Assets
 
-This library uses WASM and AudioWorklets for processing. You must manually download these assets and serve them from your application (e.g., in your `public/` folder).
+This library uses WASM and AudioWorklets for processing. **Asset setup is optional** - the pipeline can run in passthrough mode without them.
 
-1.  Download the following files from `https://unpkg.com/@sapphi-red/web-noise-suppressor@0.3.5/dist/`:
+### For Noise Suppression (Optional)
+
+If you want to enable noise suppression, download these files from `https://unpkg.com/@sapphi-red/web-noise-suppressor@0.3.5/dist/`:
 
 - `rnnoise.wasm`
 - `rnnoise_simd.wasm`
 - `noise-suppressor-worklet.min.js`
 
-2.  Place them in your project's public directory (e.g., `public/audio-processor/`).
+Place them in your project's public directory (e.g., `public/audio-processor/`).
+
+**Note:** The pipeline will automatically disable noise suppression if these URLs are not provided, and will use passthrough mode instead.
 
 ## Usage
 
+### Minimal Setup (Passthrough Mode)
+
+If you want to use the pipeline without noise suppression or VAD (e.g., for testing or when features are not needed), you can disable them:
+
+```ts
+import { createAudioPipeline } from "@tensamin/audio";
+
+// Get a stream
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+const track = stream.getAudioTracks()[0];
+
+// Create pipeline
+const pipeline = await createAudioPipeline(track, {
+  noiseSuppression: { enabled: false },
+  vad: { enabled: false },
+});
+
+// Use the processed track
+const processedStream = new MediaStream([pipeline.processedTrack]);
+```
+
 ### Basic Usage (Raw MediaStream)
 
 ```ts

package/dist/{chunk-FS635GMR.mjs → chunk-6P2RDBW5.mjs}

@@ -1,9 +1,9 @@
 import {
   RNNoisePlugin
-} from "./chunk-SDTOKWM2.mjs";
+} from "./chunk-XO6B3D4A.mjs";
 import {
   EnergyVADPlugin
-} from "./chunk-UMU2KIB6.mjs";
+} from "./chunk-R5JVHKWA.mjs";
 
 // src/extensibility/plugins.ts
 var nsPlugins = /* @__PURE__ */ new Map();

package/dist/chunk-EXH2PNUE.mjs

@@ -0,0 +1,212 @@
+import {
+  VADStateMachine
+} from "./chunk-JJASCVEW.mjs";
+import {
+  getAudioContext,
+  registerPipeline,
+  unregisterPipeline
+} from "./chunk-OZ7KMC4S.mjs";
+import {
+  getNoiseSuppressionPlugin,
+  getVADPlugin
+} from "./chunk-6P2RDBW5.mjs";
+
+// src/pipeline/audio-pipeline.ts
+import mitt from "mitt";
+async function createAudioPipeline(sourceTrack, config = {}) {
+  const context = getAudioContext();
+  registerPipeline();
+  const nsEnabled = config.noiseSuppression?.enabled !== false && Boolean(config.noiseSuppression?.wasmUrl && config.noiseSuppression?.simdUrl && config.noiseSuppression?.workletUrl);
+  const vadEnabled = config.vad?.enabled !== false;
+  const fullConfig = {
+    noiseSuppression: {
+      enabled: nsEnabled,
+      ...config.noiseSuppression
+    },
+    vad: {
+      enabled: vadEnabled,
+      ...config.vad
+    },
+    output: {
+      speechGain: 1,
+      silenceGain: vadEnabled ? 0 : 1,
+      // If no VAD, always output audio
+      gainRampTime: 0.02,
+      ...config.output
+    },
+    livekit: { manageTrackMute: false, ...config.livekit }
+  };
+  console.log("Audio pipeline config:", {
+    noiseSuppression: fullConfig.noiseSuppression?.enabled,
+    vad: fullConfig.vad?.enabled,
+    output: fullConfig.output
+  });
+  if (!sourceTrack || sourceTrack.kind !== "audio") {
+    throw new Error("createAudioPipeline requires a valid audio MediaStreamTrack");
+  }
+  if (sourceTrack.readyState === "ended") {
+    throw new Error("Cannot create pipeline from an ended MediaStreamTrack");
+  }
+  const sourceStream = new MediaStream([sourceTrack]);
+  const sourceNode = context.createMediaStreamSource(sourceStream);
+  let nsNode;
+  let vadNode;
+  const emitter = mitt();
+  try {
+    const nsPlugin = getNoiseSuppressionPlugin(
+      fullConfig.noiseSuppression?.pluginName
+    );
+    nsNode = await nsPlugin.createNode(
+      context,
+      fullConfig.noiseSuppression
+    );
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    console.error("Failed to create noise suppression node:", err);
+    emitter.emit("error", err);
+    throw err;
+  }
+  const vadStateMachine = new VADStateMachine(fullConfig.vad);
+  try {
+    const vadPlugin = getVADPlugin(fullConfig.vad?.pluginName);
+    vadNode = await vadPlugin.createNode(
+      context,
+      fullConfig.vad,
+      (prob) => {
+        try {
+          const timestamp = context.currentTime * 1e3;
+          const newState = vadStateMachine.processFrame(prob, timestamp);
+          if (newState.state !== lastVadState.state || Math.abs(newState.probability - lastVadState.probability) > 0.1) {
+            emitter.emit("vadChange", newState);
+            lastVadState = newState;
+            updateGain(newState);
+          }
+        } catch (vadError) {
+          const err = vadError instanceof Error ? vadError : new Error(String(vadError));
+          console.error("Error in VAD callback:", err);
+          emitter.emit("error", err);
+        }
+      }
+    );
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    console.error("Failed to create VAD node:", err);
+    emitter.emit("error", err);
+    throw err;
+  }
+  let lastVadState = {
+    isSpeaking: false,
+    probability: 0,
+    state: "silent"
+  };
+  const splitter = context.createGain();
+  sourceNode.connect(nsNode);
+  nsNode.connect(splitter);
+  splitter.connect(vadNode);
+  const delayNode = context.createDelay(1);
+  const preRollSeconds = (fullConfig.vad?.preRollMs ?? 200) / 1e3;
+  delayNode.delayTime.value = preRollSeconds;
+  const gainNode = context.createGain();
+  gainNode.gain.value = fullConfig.output?.silenceGain ?? 0;
+  const destination = context.createMediaStreamDestination();
+  try {
+    splitter.connect(delayNode);
+    delayNode.connect(gainNode);
+    gainNode.connect(destination);
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    console.error("Failed to wire audio pipeline:", err);
+    emitter.emit("error", err);
+    throw err;
+  }
+  function updateGain(state) {
+    try {
+      const { speechGain, silenceGain, gainRampTime } = fullConfig.output;
+      const targetGain = state.isSpeaking ? speechGain ?? 1 : silenceGain ?? 0;
+      const now = context.currentTime;
+      gainNode.gain.setTargetAtTime(targetGain, now, gainRampTime ?? 0.02);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      console.error("Failed to update gain:", err);
+      emitter.emit("error", err);
+    }
+  }
+  const audioTracks = destination.stream.getAudioTracks();
+  console.log("Destination stream tracks:", {
+    count: audioTracks.length,
+    tracks: audioTracks.map((t) => ({
+      id: t.id,
+      label: t.label,
+      enabled: t.enabled,
+      readyState: t.readyState
+    }))
+  });
+  if (audioTracks.length === 0) {
+    const err = new Error(
+      "Failed to create processed audio track: destination stream has no audio tracks. This may indicate an issue with the audio graph connection."
+    );
+    console.error(err);
+    emitter.emit("error", err);
+    throw err;
+  }
+  const processedTrack = audioTracks[0];
+  if (!processedTrack || processedTrack.readyState === "ended") {
+    const err = new Error("Processed audio track is invalid or ended");
+    console.error(err);
+    emitter.emit("error", err);
+    throw err;
+  }
+  console.log("Audio pipeline created successfully:", {
+    sourceTrack: {
+      id: sourceTrack.id,
+      label: sourceTrack.label,
+      readyState: sourceTrack.readyState
+    },
+    processedTrack: {
+      id: processedTrack.id,
+      label: processedTrack.label,
+      readyState: processedTrack.readyState
+    },
+    config: {
+      noiseSuppression: fullConfig.noiseSuppression?.enabled,
+      vad: fullConfig.vad?.enabled
+    }
+  });
+  function dispose() {
+    try {
+      sourceNode.disconnect();
+      nsNode.disconnect();
+      splitter.disconnect();
+      vadNode.disconnect();
+      delayNode.disconnect();
+      gainNode.disconnect();
+      destination.stream.getTracks().forEach((t) => t.stop());
+      unregisterPipeline();
+    } catch (error) {
+      console.error("Error during pipeline disposal:", error);
+    }
+  }
+  return {
+    processedTrack,
+    events: emitter,
+    get state() {
+      return lastVadState;
+    },
+    setConfig: (newConfig) => {
+      try {
+        if (newConfig.vad) {
+          vadStateMachine.updateConfig(newConfig.vad);
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        console.error("Failed to update config:", err);
+        emitter.emit("error", err);
+      }
+    },
+    dispose
+  };
+}
+
+export {
+  createAudioPipeline
+};

package/dist/{chunk-UMU2KIB6.mjs → chunk-R5JVHKWA.mjs}

@@ -42,22 +42,52 @@ 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) {
-      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/chunk-XMTQPMQ6.mjs

@@ -0,0 +1,91 @@
+import {
+  createAudioPipeline
+} from "./chunk-EXH2PNUE.mjs";
+
+// src/livekit/integration.ts
+async function attachProcessingToTrack(track, config = {}) {
+  if (!track) {
+    throw new Error("attachProcessingToTrack requires a valid LocalAudioTrack");
+  }
+  const originalTrack = track.mediaStreamTrack;
+  if (!originalTrack) {
+    throw new Error("LocalAudioTrack has no underlying MediaStreamTrack");
+  }
+  if (originalTrack.readyState === "ended") {
+    throw new Error("Cannot attach processing to an ended MediaStreamTrack");
+  }
+  let pipeline;
+  try {
+    console.log("Creating audio processing pipeline...");
+    pipeline = await createAudioPipeline(originalTrack, config);
+    console.log("Audio processing pipeline created successfully");
+  } catch (error) {
+    const err = new Error(
+      `Failed to create audio pipeline: ${error instanceof Error ? error.message : String(error)}`
+    );
+    console.error(err);
+    throw err;
+  }
+  if (!pipeline.processedTrack) {
+    throw new Error("Pipeline did not return a processed track");
+  }
+  try {
+    console.log("Replacing LiveKit track with processed track...");
+    await track.replaceTrack(pipeline.processedTrack);
+    console.log("LiveKit track replaced successfully");
+  } catch (error) {
+    pipeline.dispose();
+    const err = new Error(
+      `Failed to replace LiveKit track: ${error instanceof Error ? error.message : String(error)}`
+    );
+    console.error(err);
+    throw err;
+  }
+  if (config.livekit?.manageTrackMute) {
+    let isVadMuted = false;
+    pipeline.events.on("vadChange", async (state) => {
+      try {
+        if (state.isSpeaking) {
+          if (isVadMuted) {
+            await track.unmute();
+            isVadMuted = false;
+          }
+        } else {
+          if (!track.isMuted) {
+            await track.mute();
+            isVadMuted = true;
+          }
+        }
+      } catch (error) {
+        console.error("Error handling VAD-based track muting:", error);
+      }
+    });
+  }
+  pipeline.events.on("error", (error) => {
+    console.error("Audio pipeline error:", error);
+  });
+  const originalDispose = pipeline.dispose;
+  pipeline.dispose = () => {
+    try {
+      if (originalTrack.readyState === "live") {
+        console.log("Restoring original track...");
+        track.replaceTrack(originalTrack).catch((error) => {
+          console.error("Failed to restore original track:", error);
+        });
+      }
+      originalDispose();
+    } catch (error) {
+      console.error("Error during pipeline disposal:", error);
+      try {
+        originalDispose();
+      } catch (disposeError) {
+        console.error("Error calling original dispose:", disposeError);
+      }
+    }
+  };
+  return pipeline;
+}
+
+export {
+  attachProcessingToTrack
+};

package/dist/chunk-XO6B3D4A.mjs

@@ -0,0 +1,67 @@
+// src/noise-suppression/rnnoise-node.ts
+var RNNoisePlugin = class {
+  name = "rnnoise-ns";
+  wasmBuffer = null;
+  async createNode(context, config) {
+    const { loadRnnoise, RnnoiseWorkletNode } = await import("@sapphi-red/web-noise-suppressor");
+    if (!config?.enabled) {
+      console.log("Noise suppression disabled, using passthrough node");
+      const pass = context.createGain();
+      return pass;
+    }
+    if (!config?.wasmUrl || !config?.simdUrl || !config?.workletUrl) {
+      const error = new Error(
+        `RNNoisePlugin requires 'wasmUrl', 'simdUrl', and 'workletUrl' to be configured. Please download the assets from @sapphi-red/web-noise-suppressor and provide the URLs in the config. Current config: wasmUrl=${config?.wasmUrl}, simdUrl=${config?.simdUrl}, workletUrl=${config?.workletUrl}
+To disable noise suppression, set noiseSuppression.enabled to false.`
+      );
+      console.error(error.message);
+      throw error;
+    }
+    try {
+      if (!this.wasmBuffer) {
+        console.log("Loading RNNoise WASM binary...");
+        this.wasmBuffer = await loadRnnoise({
+          url: config.wasmUrl,
+          simdUrl: config.simdUrl
+        });
+        console.log("RNNoise WASM loaded successfully");
+      }
+    } catch (error) {
+      const err = new Error(
+        `Failed to load RNNoise WASM binary: ${error instanceof Error ? error.message : String(error)}`
+      );
+      console.error(err);
+      throw err;
+    }
+    const workletUrl = config.workletUrl;
+    try {
+      await context.audioWorklet.addModule(workletUrl);
+      console.log("RNNoise worklet loaded successfully");
+    } catch (e) {
+      const error = new Error(
+        `Failed to load RNNoise worklet from ${workletUrl}: ${e instanceof Error ? e.message : String(e)}. Ensure the workletUrl points to a valid RNNoise worklet script.`
+      );
+      console.error(error.message);
+      throw error;
+    }
+    try {
+      const node = new RnnoiseWorkletNode(context, {
+        wasmBinary: this.wasmBuffer,
+        maxChannels: 1
+        // Mono for now
+      });
+      console.log("RNNoise worklet node created successfully");
+      return node;
+    } catch (error) {
+      const err = new Error(
+        `Failed to create RNNoise worklet node: ${error instanceof Error ? error.message : String(error)}`
+      );
+      console.error(err);
+      throw err;
+    }
+  }
+};
+
+export {
+  RNNoisePlugin
+};

package/dist/extensibility/plugins.js

@@ -44,32 +44,60 @@ var RNNoisePlugin = class {
   async createNode(context, config) {
     const { loadRnnoise, RnnoiseWorkletNode } = await import("@sapphi-red/web-noise-suppressor");
     if (!config?.enabled) {
+      console.log("Noise suppression disabled, using passthrough node");
       const pass = context.createGain();
       return pass;
     }
     if (!config?.wasmUrl || !config?.simdUrl || !config?.workletUrl) {
-      throw new Error(
-        "RNNoisePlugin requires 'wasmUrl', 'simdUrl', and 'workletUrl' to be configured. Please download the assets and provide the URLs."
+      const error = new Error(
+        `RNNoisePlugin requires 'wasmUrl', 'simdUrl', and 'workletUrl' to be configured. Please download the assets from @sapphi-red/web-noise-suppressor and provide the URLs in the config. Current config: wasmUrl=${config?.wasmUrl}, simdUrl=${config?.simdUrl}, workletUrl=${config?.workletUrl}
+To disable noise suppression, set noiseSuppression.enabled to false.`
       );
+      console.error(error.message);
+      throw error;
     }
-    if (!this.wasmBuffer) {
-      this.wasmBuffer = await loadRnnoise({
-        url: config.wasmUrl,
-        simdUrl: config.simdUrl
-      });
+    try {
+      if (!this.wasmBuffer) {
+        console.log("Loading RNNoise WASM binary...");
+        this.wasmBuffer = await loadRnnoise({
+          url: config.wasmUrl,
+          simdUrl: config.simdUrl
+        });
+        console.log("RNNoise WASM loaded successfully");
+      }
+    } catch (error) {
+      const err = new Error(
+        `Failed to load RNNoise WASM binary: ${error instanceof Error ? error.message : String(error)}`
+      );
+      console.error(err);
+      throw err;
     }
     const workletUrl = config.workletUrl;
     try {
       await context.audioWorklet.addModule(workletUrl);
+      console.log("RNNoise worklet loaded successfully");
     } catch (e) {
-      console.warn("Failed to add RNNoise worklet module:", e);
+      const error = new Error(
+        `Failed to load RNNoise worklet from ${workletUrl}: ${e instanceof Error ? e.message : String(e)}. Ensure the workletUrl points to a valid RNNoise worklet script.`
+      );
+      console.error(error.message);
+      throw error;
+    }
+    try {
+      const node = new RnnoiseWorkletNode(context, {
+        wasmBinary: this.wasmBuffer,
+        maxChannels: 1
+        // Mono for now
+      });
+      console.log("RNNoise worklet node created successfully");
+      return node;
+    } catch (error) {
+      const err = new Error(
+        `Failed to create RNNoise worklet node: ${error instanceof Error ? error.message : String(error)}`
+      );
+      console.error(err);
+      throw err;
     }
-    const node = new RnnoiseWorkletNode(context, {
-      wasmBinary: this.wasmBuffer,
-      maxChannels: 1
-      // Mono for now
-    });
-    return node;
   }
 };
 
@@ -117,22 +145,52 @@ 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) {
-      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/extensibility/plugins.mjs

@@ -3,9 +3,9 @@ import {
   getVADPlugin,
   registerNoiseSuppressionPlugin,
   registerVADPlugin
-} from "../chunk-FS635GMR.mjs";
-import "../chunk-SDTOKWM2.mjs";
-import "../chunk-UMU2KIB6.mjs";
+} from "../chunk-6P2RDBW5.mjs";
+import "../chunk-XO6B3D4A.mjs";
+import "../chunk-R5JVHKWA.mjs";
 export {
   getNoiseSuppressionPlugin,
   getVADPlugin,