@tensamin/audio 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      
+      - name: Publish
+        run: |
+          npm ci
+          npm run build
+          npm pack
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+          npm publish --access public

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Methanium]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @tensamin/audio
+
+A audio processing library for the web, featuring RNNoise-based noise suppression and robust Voice Activity Detection (VAD). Designed for seamless integration with LiveKit.
+
+## Features
+
+- **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`.
+- **Extensible**: Plugin system for custom WASM/Worklet processors.
+
+## Installation
+
+```bash
+npm install @tensamin/audio livekit-client
+bun add @tensamin/audio livekit-client
+pnpm install @tensamin/audio livekit-client
+```
+
+## Usage
+
+### Basic Usage (Raw MediaStream)
+
+```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: true },
+  vad: { enabled: true },
+});
+
+// Use the processed track
+const processedStream = new MediaStream([pipeline.processedTrack]);
+// audioElement.srcObject = processedStream;
+
+// Listen to VAD events
+pipeline.events.on("vadChange", (state) => {
+  console.log("Is Speaking:", state.isSpeaking);
+});
+```
+
+### LiveKit Integration
+
+```ts
+import { attachProcessingToTrack } from "@tensamin/audio";
+import { LocalAudioTrack } from "livekit-client";
+
+// Assume you have a LocalAudioTrack
+const localTrack = await LocalAudioTrack.create();
+
+// Attach processing (replaces the underlying track)
+const pipeline = await attachProcessingToTrack(localTrack, {
+  noiseSuppression: { enabled: true },
+  vad: { enabled: true },
+  livekit: { manageTrackMute: true }, // Optional: mute the track object itself
+});
+
+// Publish the track
+await room.localParticipant.publishTrack(localTrack);
+```

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@tensamin/audio",
+  "version": "0.1.0",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "author": {
+    "email": "aloisianer@proton.me",
+    "name": "Alois"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Tensamin/Audio"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "format": "bunx prettier --write ."
+  },
+  "dependencies": {
+    "@sapphi-red/web-noise-suppressor": "^0.3.5",
+    "mitt": "^3.0.1"
+  },
+  "peerDependencies": {
+    "livekit-client": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/web": "^0.0.298",
+    "livekit-client": "^2.16.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/context/audio-context.ts

@@ -0,0 +1,69 @@
+/**
+ * Manages a shared AudioContext for the application.
+ */
+
+let sharedContext: AudioContext | null = null;
+let activePipelines = 0;
+
+/**
+ * Gets the shared AudioContext, creating it if necessary.
+ * @param options Optional AudioContextOptions
+ */
+export function getAudioContext(options?: AudioContextOptions): AudioContext {
+  if (typeof window === "undefined" || typeof AudioContext === "undefined") {
+    throw new Error(
+      "AudioContext is not supported in this environment (browser only).",
+    );
+  }
+
+  if (!sharedContext || sharedContext.state === "closed") {
+    sharedContext = new AudioContext(options);
+  }
+
+  return sharedContext;
+}
+
+/**
+ * Registers a pipeline usage. Keeps track of active users.
+ */
+export function registerPipeline(): void {
+  activePipelines++;
+}
+
+/**
+ * Unregisters a pipeline usage.
+ * Optionally closes the context if no pipelines are active (not implemented by default to avoid churn).
+ */
+export function unregisterPipeline(): void {
+  activePipelines = Math.max(0, activePipelines - 1);
+}
+
+/**
+ * Resumes the shared AudioContext.
+ * Should be called in response to a user gesture.
+ */
+export async function resumeAudioContext(): Promise<void> {
+  if (sharedContext && sharedContext.state === "suspended") {
+    await sharedContext.resume();
+  }
+}
+
+/**
+ * Suspends the shared AudioContext.
+ */
+export async function suspendAudioContext(): Promise<void> {
+  if (sharedContext && sharedContext.state === "running") {
+    await sharedContext.suspend();
+  }
+}
+
+/**
+ * Closes the shared AudioContext and releases resources.
+ */
+export async function closeAudioContext(): Promise<void> {
+  if (sharedContext && sharedContext.state !== "closed") {
+    await sharedContext.close();
+  }
+  sharedContext = null;
+  activePipelines = 0;
+}

package/src/extensibility/plugins.ts

@@ -0,0 +1,45 @@
+import type { NoiseSuppressionPlugin, VADPlugin } from "../types.js";
+import { RNNoisePlugin } from "../noise-suppression/rnnoise-node.js";
+import { EnergyVADPlugin } from "../vad/vad-node.js";
+
+const nsPlugins = new Map<string, NoiseSuppressionPlugin>();
+const vadPlugins = new Map<string, VADPlugin>();
+
+// Register defaults
+const defaultNs = new RNNoisePlugin();
+nsPlugins.set(defaultNs.name, defaultNs);
+
+const defaultVad = new EnergyVADPlugin();
+vadPlugins.set(defaultVad.name, defaultVad);
+
+export function registerNoiseSuppressionPlugin(plugin: NoiseSuppressionPlugin) {
+  nsPlugins.set(plugin.name, plugin);
+}
+
+export function registerVADPlugin(plugin: VADPlugin) {
+  vadPlugins.set(plugin.name, plugin);
+}
+
+export function getNoiseSuppressionPlugin(
+  name?: string,
+): NoiseSuppressionPlugin {
+  if (!name) return defaultNs;
+  const plugin = nsPlugins.get(name);
+  if (!plugin) {
+    console.warn(
+      `Noise suppression plugin '${name}' not found, falling back to default.`,
+    );
+    return defaultNs;
+  }
+  return plugin;
+}
+
+export function getVADPlugin(name?: string): VADPlugin {
+  if (!name) return defaultVad;
+  const plugin = vadPlugins.get(name);
+  if (!plugin) {
+    console.warn(`VAD plugin '${name}' not found, falling back to default.`);
+    return defaultVad;
+  }
+  return plugin;
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./context/audio-context.js";
+export * from "./pipeline/audio-pipeline.js";
+export * from "./livekit/integration.js";
+export * from "./extensibility/plugins.js";
+export * from "./noise-suppression/rnnoise-node.js";
+export * from "./vad/vad-node.js";
+export * from "./vad/vad-state.js";

package/src/livekit/integration.ts

@@ -0,0 +1,61 @@
+import type { LocalAudioTrack } from "livekit-client";
+import { createAudioPipeline } from "../pipeline/audio-pipeline.js";
+import type { AudioPipelineHandle, AudioProcessingConfig } from "../types.js";
+
+/**
+ * Attaches the audio processing pipeline to a LiveKit LocalAudioTrack.
+ * This replaces the underlying MediaStreamTrack with the processed one.
+ */
+export async function attachProcessingToTrack(
+  track: LocalAudioTrack,
+  config: AudioProcessingConfig = {},
+): Promise<AudioPipelineHandle> {
+  // 1. Get the original track
+  const originalTrack = track.mediaStreamTrack;
+
+  // 2. Create pipeline
+  const pipeline = await createAudioPipeline(originalTrack, config);
+
+  // 3. Replace the track in LiveKit
+  // Use replaceTrack which is the public API to swap the underlying MediaStreamTrack.
+  await track.replaceTrack(pipeline.processedTrack);
+
+  // 4. Handle intelligent muting if enabled
+  if (config.livekit?.manageTrackMute) {
+    let isVadMuted = false;
+
+    pipeline.events.on("vadChange", async (state) => {
+      if (state.isSpeaking) {
+        if (isVadMuted) {
+          // Only unmute if we were the ones who muted it
+          // And check if the track is not globally muted by user?
+          // This is tricky. If user muted manually, track.isMuted is true.
+          // We should probably check a separate flag or assume VAD overrides only when "active".
+          // For safety, we only unmute if we muted.
+          await track.unmute();
+          isVadMuted = false;
+        }
+      } else {
+        // Silence
+        if (!track.isMuted) {
+          await track.mute();
+          isVadMuted = true;
+        }
+      }
+    });
+  }
+
+  // 5. Handle cleanup
+  const originalDispose = pipeline.dispose;
+  pipeline.dispose = () => {
+    // Restore original track?
+    // Or just stop.
+    // If we dispose, we should probably try to restore the original track if it's still alive.
+    if (originalTrack.readyState === "live") {
+      track.replaceTrack(originalTrack).catch(console.error);
+    }
+    originalDispose();
+  };
+
+  return pipeline;
+}

package/src/noise-suppression/rnnoise-node.ts

@@ -0,0 +1,62 @@
+import {
+  RnnoiseWorkletNode,
+  loadRnnoise,
+} from "@sapphi-red/web-noise-suppressor";
+import type {
+  AudioProcessingConfig,
+  NoiseSuppressionPlugin,
+} from "../types.js";
+
+// Default URLs (can be overridden by config)
+// These defaults assume the assets are served from the same origin or a known CDN.
+// In a real package, we might want to bundle them or require the user to provide them.
+const DEFAULT_WASM_URL =
+  "https://unpkg.com/@sapphi-red/web-noise-suppressor@0.3.5/dist/rnnoise.wasm";
+const DEFAULT_SIMD_WASM_URL =
+  "https://unpkg.com/@sapphi-red/web-noise-suppressor@0.3.5/dist/rnnoise_simd.wasm";
+const DEFAULT_WORKLET_URL =
+  "https://unpkg.com/@sapphi-red/web-noise-suppressor@0.3.5/dist/noise-suppressor-worklet.min.js";
+
+export class RNNoisePlugin implements NoiseSuppressionPlugin {
+  name = "rnnoise-ns";
+  private wasmBuffer: ArrayBuffer | null = null;
+
+  async createNode(
+    context: AudioContext,
+    config: AudioProcessingConfig["noiseSuppression"],
+  ): Promise<AudioNode> {
+    if (!config?.enabled) {
+      // Return a passthrough gain node if disabled but requested (though pipeline usually handles this)
+      const pass = context.createGain();
+      return pass;
+    }
+
+    // 1. Load WASM if not loaded
+    // We use the library's loader which handles SIMD detection if we provide both URLs.
+    // But wait, loadRnnoise returns ArrayBuffer.
+    if (!this.wasmBuffer) {
+      this.wasmBuffer = await loadRnnoise({
+        url: config.wasmUrl || DEFAULT_WASM_URL,
+        simdUrl: DEFAULT_SIMD_WASM_URL, // We should probably allow config for this too, but for now default is fine.
+      });
+    }
+
+    // 2. Load Worklet
+    const workletUrl = config.workletUrl || DEFAULT_WORKLET_URL;
+
+    try {
+      await context.audioWorklet.addModule(workletUrl);
+    } catch (e) {
+      console.warn("Failed to add RNNoise worklet module:", e);
+      // Proceeding, assuming it might be already loaded.
+    }
+
+    // 3. Create Node
+    const node = new RnnoiseWorkletNode(context, {
+      wasmBinary: this.wasmBuffer,
+      maxChannels: 1, // Mono for now
+    });
+
+    return node;
+  }
+}

package/src/pipeline/audio-pipeline.ts

@@ -0,0 +1,154 @@
+import mitt from "mitt";
+import {
+  getAudioContext,
+  registerPipeline,
+  unregisterPipeline,
+} from "../context/audio-context.js";
+import {
+  getNoiseSuppressionPlugin,
+  getVADPlugin,
+} from "../extensibility/plugins.js";
+import { VADStateMachine } from "../vad/vad-state.js";
+import type {
+  AudioPipelineEvents,
+  AudioPipelineHandle,
+  AudioProcessingConfig,
+  VADState,
+} from "../types.js";
+
+export async function createAudioPipeline(
+  sourceTrack: MediaStreamTrack,
+  config: AudioProcessingConfig = {},
+): Promise<AudioPipelineHandle> {
+  const context = getAudioContext();
+  registerPipeline();
+
+  // Defaults
+  const fullConfig: AudioProcessingConfig = {
+    noiseSuppression: { enabled: true, ...config.noiseSuppression },
+    vad: { enabled: true, ...config.vad },
+    output: {
+      speechGain: 1.0,
+      silenceGain: 0.0,
+      gainRampTime: 0.02,
+      ...config.output,
+    },
+    livekit: { manageTrackMute: false, ...config.livekit },
+  };
+
+  // 1. Source
+  const sourceStream = new MediaStream([sourceTrack]);
+  const sourceNode = context.createMediaStreamSource(sourceStream);
+
+  // 2. Noise Suppression
+  const nsPlugin = getNoiseSuppressionPlugin(
+    fullConfig.noiseSuppression?.pluginName,
+  );
+  const nsNode = await nsPlugin.createNode(
+    context,
+    fullConfig.noiseSuppression,
+  );
+
+  // 3. VAD
+  const vadPlugin = getVADPlugin(fullConfig.vad?.pluginName);
+  const vadStateMachine = new VADStateMachine(fullConfig.vad);
+  const emitter = mitt<AudioPipelineEvents>();
+
+  const vadNode = await vadPlugin.createNode(
+    context,
+    fullConfig.vad,
+    (prob) => {
+      const timestamp = context.currentTime * 1000;
+      const newState = vadStateMachine.processFrame(prob, timestamp);
+
+      // Emit if state changed or periodically?
+      // For now, emit on change.
+      if (
+        newState.state !== lastVadState.state ||
+        Math.abs(newState.probability - lastVadState.probability) > 0.1
+      ) {
+        emitter.emit("vadChange", newState);
+        lastVadState = newState;
+        updateGain(newState);
+      }
+    },
+  );
+
+  let lastVadState: VADState = {
+    isSpeaking: false,
+    probability: 0,
+    state: "silent",
+  };
+
+  // 4. Pipeline Wiring
+  // Source -> NS -> Splitter
+  // Splitter -> VAD
+  // Splitter -> Delay -> Gain -> Destination
+
+  const splitter = context.createGain(); // Using Gain as splitter (fan-out)
+
+  sourceNode.connect(nsNode);
+  nsNode.connect(splitter);
+
+  // Path 1: VAD
+  splitter.connect(vadNode);
+  // vadNode usually doesn't output audio, or we don't connect it to destination.
+
+  // Path 2: Audio Output
+  const delayNode = context.createDelay(1.0); // Max 1 sec
+  const preRollSeconds = (fullConfig.vad?.preRollMs ?? 200) / 1000;
+  delayNode.delayTime.value = preRollSeconds;
+
+  const gainNode = context.createGain();
+  gainNode.gain.value = fullConfig.output?.silenceGain ?? 0;
+
+  const destination = context.createMediaStreamDestination();
+
+  splitter.connect(delayNode);
+  delayNode.connect(gainNode);
+  gainNode.connect(destination);
+
+  // Helper to update gain
+  function updateGain(state: VADState) {
+    const { speechGain, silenceGain, gainRampTime } = fullConfig.output!;
+    const targetGain = state.isSpeaking
+      ? (speechGain ?? 1.0)
+      : (silenceGain ?? 0.0);
+
+    // Ramp to target
+    const now = context.currentTime;
+    gainNode.gain.setTargetAtTime(targetGain, now, gainRampTime ?? 0.02);
+  }
+
+  // Handle disposal
+  function dispose() {
+    sourceNode.disconnect();
+    nsNode.disconnect();
+    splitter.disconnect();
+    vadNode.disconnect();
+    delayNode.disconnect();
+    gainNode.disconnect();
+
+    // Stop tracks? No, we don't own the source track.
+    // But we own the destination track.
+    destination.stream.getTracks().forEach((t) => t.stop());
+
+    unregisterPipeline();
+  }
+
+  return {
+    processedTrack: destination.stream.getAudioTracks()[0]!,
+    events: emitter,
+    get state() {
+      return lastVadState;
+    },
+    setConfig: (newConfig) => {
+      // TODO: Implement runtime config updates
+      // For now, just update the VAD state machine config
+      if (newConfig.vad) {
+        vadStateMachine.updateConfig(newConfig.vad);
+      }
+    },
+    dispose,
+  };
+}

package/src/types.ts

@@ -0,0 +1,167 @@
+import type { LocalAudioTrack, TrackPublication } from "livekit-client";
+import type { Emitter } from "mitt";
+
+/**
+ * Configuration for the audio processing pipeline.
+ */
+export interface AudioProcessingConfig {
+  /**
+   * Noise suppression configuration.
+   */
+  noiseSuppression?: {
+    enabled: boolean;
+    /**
+     * Path or URL to the RNNoise WASM binary.
+     * If not provided, the default from @sapphi-red/web-noise-suppressor will be used (if bundler supports it).
+     */
+    wasmUrl?: string;
+    /**
+     * Path or URL to the RNNoise worklet script.
+     */
+    workletUrl?: string;
+    /**
+     * Plugin name to use. Defaults to 'rnnoise-ns'.
+     */
+    pluginName?: string;
+  };
+
+  /**
+   * Voice Activity Detection (VAD) configuration.
+   */
+  vad?: {
+    enabled: boolean;
+    /**
+     * Plugin name to use. Defaults to 'rnnoise-vad' or 'energy-vad'.
+     */
+    pluginName?: string;
+    /**
+     * Probability threshold for speech onset (0-1).
+     * Default: 0.5
+     */
+    startThreshold?: number;
+    /**
+     * Probability threshold for speech offset (0-1).
+     * Default: 0.4
+     */
+    stopThreshold?: number;
+    /**
+     * Time in ms to wait after speech stops before considering it silent.
+     * Default: 300ms
+     */
+    hangoverMs?: number;
+    /**
+     * Time in ms of audio to buffer before speech onset to avoid cutting the start.
+     * Default: 200ms
+     */
+    preRollMs?: number;
+  };
+
+  /**
+   * Output gain and muting configuration.
+   */
+  output?: {
+    /**
+     * Gain to apply when speaking (0-1+). Default: 1.0
+     */
+    speechGain?: number;
+    /**
+     * Gain to apply when silent (0-1). Default: 0.0 (mute)
+     */
+    silenceGain?: number;
+    /**
+     * Time in seconds to ramp gain changes. Default: 0.02
+     */
+    gainRampTime?: number;
+  };
+
+  /**
+   * LiveKit integration configuration.
+   */
+  livekit?: {
+    /**
+     * Whether to call track.mute()/unmute() on the LocalAudioTrack based on VAD.
+     * This saves bandwidth but has more signaling overhead.
+     * Default: false (uses gain gating only)
+     */
+    manageTrackMute?: boolean;
+  };
+}
+
+/**
+ * Represents the state of Voice Activity Detection.
+ */
+export interface VADState {
+  /**
+   * Whether speech is currently detected (after hysteresis).
+   */
+  isSpeaking: boolean;
+  /**
+   * Raw probability of speech from the VAD model (0-1).
+   */
+  probability: number;
+  /**
+   * Current state enum.
+   */
+  state: "silent" | "speech_starting" | "speaking" | "speech_ending";
+}
+
+/**
+ * Events emitted by the audio pipeline.
+ */
+export type AudioPipelineEvents = {
+  vadChange: VADState;
+  error: Error;
+};
+
+/**
+ * Handle to a running audio processing pipeline.
+ */
+export interface AudioPipelineHandle {
+  /**
+   * The processed MediaStreamTrack.
+   */
+  readonly processedTrack: MediaStreamTrack;
+
+  /**
+   * Event emitter for VAD state and errors.
+   */
+  readonly events: Emitter<AudioPipelineEvents>;
+
+  /**
+   * Current VAD state.
+   */
+  readonly state: VADState;
+
+  /**
+   * Update configuration at runtime.
+   */
+  setConfig(config: Partial<AudioProcessingConfig>): void;
+
+  /**
+   * Stop processing and release resources.
+   */
+  dispose(): void;
+}
+
+/**
+ * Interface for a Noise Suppression Plugin.
+ */
+export interface NoiseSuppressionPlugin {
+  name: string;
+  createNode(
+    context: AudioContext,
+    config: AudioProcessingConfig["noiseSuppression"],
+  ): Promise<AudioNode>;
+}
+
+/**
+ * Interface for a VAD Plugin.
+ */
+export interface VADPlugin {
+  name: string;
+  createNode(
+    context: AudioContext,
+    config: AudioProcessingConfig["vad"],
+    onDecision: (probability: number) => void,
+  ): Promise<AudioNode>;
+}

package/src/vad/vad-node.ts

@@ -0,0 +1,78 @@
+import type { AudioProcessingConfig, VADPlugin } from "../types.js";
+
+// Inline AudioWorklet processor for Energy VAD
+const 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);
+`;
+
+export class EnergyVADPlugin implements VADPlugin {
+  name = "energy-vad";
+
+  async createNode(
+    context: AudioContext,
+    config: AudioProcessingConfig["vad"],
+    onDecision: (probability: number) => void,
+  ): Promise<AudioNode> {
+    // 1. Create Worklet
+    const blob = new Blob([energyVadWorkletCode], {
+      type: "application/javascript",
+    });
+    const url = URL.createObjectURL(blob);
+
+    try {
+      await context.audioWorklet.addModule(url);
+    } catch (e) {
+      console.warn("Failed to add Energy VAD worklet:", e);
+      throw e;
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+
+    // 2. Create Node
+    const node = new AudioWorkletNode(context, "energy-vad-processor");
+
+    node.port.onmessage = (event) => {
+      const { probability } = event.data;
+      onDecision(probability);
+    };
+
+    return node;
+  }
+}

package/src/vad/vad-state.ts

@@ -0,0 +1,71 @@
+import type { AudioProcessingConfig, VADState } from "../types.js";
+
+export class VADStateMachine {
+  private config: Required<NonNullable<AudioProcessingConfig["vad"]>>;
+  private currentState: VADState["state"] = "silent";
+  private lastSpeechTime = 0;
+  private speechStartTime = 0;
+  private frameDurationMs = 20; // Assumed frame duration, updated by calls
+
+  constructor(config: AudioProcessingConfig["vad"]) {
+    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: Partial<AudioProcessingConfig["vad"]>) {
+    this.config = { ...this.config, ...config };
+  }
+
+  processFrame(probability: number, timestamp: number): VADState {
+    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 {
+        // Check hangover
+        const timeSinceSpeech = timestamp - this.lastSpeechTime;
+        if (timeSinceSpeech < hangoverMs) {
+          newState = "speaking"; // Still in hangover
+        } else {
+          newState = "speech_ending";
+        }
+      }
+    }
+
+    // Transition from starting/ending to stable states
+    if (newState === "speech_starting") newState = "speaking";
+    if (newState === "speech_ending") newState = "silent";
+
+    this.currentState = newState;
+
+    return {
+      isSpeaking: newState === "speaking",
+      probability,
+      state: newState,
+    };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}