@utterance/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nizh
+
+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,92 @@
+<p align="center">
+  <h1 align="center">Utterance</h1>
+  <p align="center"><strong>Client-side semantic endpointing. Know when they're done talking.</strong></p>
+  <p align="center">
+    <a href="https://utterance.dev">Documentation</a> •
+    <a href="https://utterance.dev/demo">Live Demo</a> •
+    <a href="https://discord.gg/kb4zMHNtEV">Discord</a> •
+    <a href="https://github.com/nizh0/Utterance">GitHub</a>
+  </p>
+</p>
+
+---
+
+## The Problem
+
+Every voice app faces the same annoying problem: **it can't tell when you're done talking.**
+
+You pause to think, and it cuts you off. You take a breath, and it responds too soon. You want to interrupt, and it keeps going.
+
+The current solutions either:
+
+- **Detect silence** (Silero VAD, ricky0123/vad): They know when sound stops, but they can't tell if you're thinking or finished.
+- **Use server-side AI** (OpenAI Realtime, AssemblyAI): They are smart, but they add delay, costs, and privacy issues.
+
+**Utterance is different.** It uses a lightweight ML model entirely on the client side. It recognizes the difference between a thinking pause and a completed turn. No cloud. No delay. No per-minute fees.
+
+## Quick Start
+
+```bash
+npm install @utterance/core
+```
+
+```javascript
+import { Utterance } from "@utterance/core";
+
+const detector = new Utterance();
+
+detector.on("turnEnd", (result) => {
+  console.log("User is done speaking", result.confidence);
+});
+
+detector.on("pause", (result) => {
+  console.log("User is thinking...", result.duration);
+});
+
+detector.on("interrupt", () => {
+  console.log("User wants to speak — stop AI response");
+});
+
+await detector.start();
+```
+
+See the [full documentation](https://utterance.dev/docs/quick-start) for detailed usage, API reference, and integration examples.
+
+## Comparison
+
+| Feature | Silero VAD | ricky0123/vad | Picovoice Cobra | OpenAI Realtime | **Utterance** |
+| --- | --- | --- | --- | --- | --- |
+| Detects speech vs. silence | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Semantic pause detection | ❌ | ❌ | ❌ | ✅ | ✅ |
+| Interrupt detection | ❌ | ❌ | ❌ | ✅ | ✅ |
+| Runs client-side | ✅ | ✅ | ✅ | ❌ | ✅ |
+| No API costs | ✅ | ✅ | ❌ | ❌ | ✅ |
+| Privacy (audio stays local) | ✅ | ✅ | ✅ | ❌ | ✅ |
+
+## Contributing
+
+We're building Utterance in the open, and contributions are welcome.
+
+```bash
+git clone https://github.com/nizh0/Utterance.git
+cd Utterance
+npm install
+npm start
+```
+
+See the [contributing guide](https://utterance.dev/docs/contributing) for development workflow, project structure, and areas where we need help.
+
+## Community
+
+- [Discord](https://discord.gg/kb4zMHNtEV): Chat with contributors
+- [GitHub Issues](https://github.com/nizh0/Utterance/issues): Bug reports & feature requests
+
+## License
+
+MIT © [Utterance](https://utterance.dev)
+
+---
+
+<p align="center">
+  <strong>"Five pharmacies on one road. But this one actually knows when you're done talking."</strong>
+</p>

package/dist/index.cjs

@@ -0,0 +1,381 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Utterance: () => Utterance
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/audio/capture.ts
+var AudioCapture = class {
+  context = null;
+  stream = null;
+  processor = null;
+  callback = null;
+  sampleRate;
+  constructor(sampleRate = 16e3) {
+    this.sampleRate = sampleRate;
+  }
+  onAudioData(callback) {
+    this.callback = callback;
+  }
+  async start() {
+    this.stream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        sampleRate: this.sampleRate,
+        channelCount: 1,
+        echoCancellation: true,
+        noiseSuppression: true
+      }
+    });
+    this.context = new AudioContext({ sampleRate: this.sampleRate });
+    const source = this.context.createMediaStreamSource(this.stream);
+    const bufferSize = 4096;
+    this.processor = this.context.createScriptProcessor(bufferSize, 1, 1);
+    this.processor.onaudioprocess = (event) => {
+      const input = event.inputBuffer.getChannelData(0);
+      this.callback?.(new Float32Array(input));
+    };
+    source.connect(this.processor);
+    this.processor.connect(this.context.destination);
+  }
+  stop() {
+    this.processor?.disconnect();
+    this.stream?.getTracks().forEach((track) => track.stop());
+    void this.context?.close();
+    this.processor = null;
+    this.stream = null;
+    this.context = null;
+  }
+};
+
+// src/features/extractor.ts
+var FeatureExtractor = class {
+  sampleRate;
+  constructor(sampleRate = 16e3) {
+    this.sampleRate = sampleRate;
+  }
+  /**
+   * Extract all features from a single audio frame.
+   */
+  extract(frame) {
+    return {
+      mfcc: this.computeMFCC(frame),
+      energy: this.computeEnergy(frame),
+      pitch: this.estimatePitch(frame),
+      speechRate: this.estimateSpeechRate(frame),
+      pauseDuration: 0
+      // tracked by the detector over time
+    };
+  }
+  /**
+   * Compute Mel-Frequency Cepstral Coefficients.
+   *
+   * TODO: Implement full MFCC pipeline:
+   *   1. Pre-emphasis filter
+   *   2. Windowing (Hamming)
+   *   3. FFT
+   *   4. Mel filterbank
+   *   5. Log energy
+   *   6. DCT
+   */
+  computeMFCC(_frame) {
+    return new Float32Array(13);
+  }
+  /**
+   * Compute RMS energy of the frame.
+   */
+  computeEnergy(frame) {
+    let sum = 0;
+    for (let i = 0; i < frame.length; i++) {
+      sum += frame[i] * frame[i];
+    }
+    return Math.sqrt(sum / frame.length);
+  }
+  /**
+   * Estimate fundamental frequency (pitch) using autocorrelation.
+   *
+   * TODO: Implement YIN or autocorrelation-based pitch detection.
+   */
+  estimatePitch(_frame) {
+    void this.sampleRate;
+    return 0;
+  }
+  /**
+   * Estimate speech rate (syllables per second).
+   *
+   * TODO: Implement energy-envelope peak counting.
+   */
+  estimateSpeechRate(_frame) {
+    return 0;
+  }
+};
+
+// src/model/energy-vad.ts
+var EnergyVAD = class {
+  speechThreshold;
+  silenceThreshold;
+  isSpeaking = false;
+  silenceStart = 0;
+  pauseHintMs;
+  constructor(sensitivity = 0.5) {
+    this.speechThreshold = 0.015 * (1 - sensitivity * 0.8);
+    this.silenceThreshold = this.speechThreshold * 0.6;
+    this.pauseHintMs = 800;
+  }
+  classify(features) {
+    const { energy } = features;
+    const now = Date.now();
+    if (!this.isSpeaking && energy >= this.speechThreshold) {
+      this.isSpeaking = true;
+      this.silenceStart = 0;
+      return { label: "speaking", confidence: this.energyToConfidence(energy), timestamp: now };
+    }
+    if (this.isSpeaking && energy >= this.silenceThreshold) {
+      this.silenceStart = 0;
+      return { label: "speaking", confidence: this.energyToConfidence(energy), timestamp: now };
+    }
+    if (this.isSpeaking && energy < this.silenceThreshold) {
+      if (this.silenceStart === 0) {
+        this.silenceStart = now;
+      }
+      const silenceDuration = now - this.silenceStart;
+      if (silenceDuration >= this.pauseHintMs) {
+        this.isSpeaking = false;
+        const confidence = Math.min(silenceDuration / (this.pauseHintMs * 2), 1);
+        return { label: "turn_complete", confidence, timestamp: now };
+      }
+      return { label: "thinking_pause", confidence: 0.6, timestamp: now };
+    }
+    return { label: "thinking_pause", confidence: 0.3, timestamp: now };
+  }
+  reset() {
+    this.isSpeaking = false;
+    this.silenceStart = 0;
+  }
+  energyToConfidence(energy) {
+    return Math.min(energy / (this.speechThreshold * 4), 1);
+  }
+};
+
+// src/model/onnx.ts
+var ONNXModel = class {
+  session = null;
+  fallback;
+  constructor(sensitivity = 0.5) {
+    this.fallback = new EnergyVAD(sensitivity);
+  }
+  /**
+   * Load the ONNX model from a given path or URL.
+   *
+   * TODO:
+   *   1. Import onnxruntime-web InferenceSession
+   *   2. Load model bytes
+   *   3. Create session with appropriate execution providers
+   */
+  async load(_path) {
+    this.session = null;
+  }
+  /**
+   * Run inference on a set of extracted features.
+   *
+   * TODO:
+   *   1. Build input tensor from AudioFeatures
+   *   2. Run session.run()
+   *   3. Parse output into ClassificationResult
+   */
+  async predict(features) {
+    if (!this.session) {
+      return this.fallback.classify(features);
+    }
+    return this.fallback.classify(features);
+  }
+  /**
+   * Release model resources.
+   */
+  dispose() {
+    this.session = null;
+    this.fallback.reset();
+  }
+};
+
+// src/detector/turn-detector.ts
+var TurnDetector = class {
+  listeners = /* @__PURE__ */ new Map();
+  state = "idle";
+  pauseStart = 0;
+  speakStart = 0;
+  sensitivity;
+  pauseTolerance;
+  constructor(sensitivity = 0.5, pauseTolerance = 1500) {
+    this.sensitivity = sensitivity;
+    this.pauseTolerance = pauseTolerance;
+  }
+  /**
+   * Register an event listener.
+   */
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+  }
+  /**
+   * Remove an event listener.
+   */
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+  }
+  /**
+   * Process a classification result from the model and emit events.
+   */
+  process(result) {
+    const { label, confidence, timestamp } = result;
+    const threshold = this.sensitivity;
+    switch (label) {
+      case "speaking":
+        if (this.state !== "speaking") {
+          this.state = "speaking";
+          this.speakStart = timestamp;
+          this.emit("speechStart", { timestamp });
+        }
+        break;
+      case "thinking_pause":
+        if (this.state === "speaking" && confidence >= threshold) {
+          this.state = "paused";
+          this.pauseStart = timestamp;
+          this.emit("pause", {
+            duration: 0,
+            confidence
+          });
+        } else if (this.state === "paused") {
+          const duration = timestamp - this.pauseStart;
+          if (duration >= this.pauseTolerance) {
+            this.state = "idle";
+            this.emit("turnEnd", {
+              confidence,
+              duration: timestamp - this.speakStart
+            });
+          }
+        }
+        break;
+      case "turn_complete":
+        if ((this.state === "speaking" || this.state === "paused") && confidence >= threshold) {
+          this.state = "idle";
+          this.emit("turnEnd", {
+            confidence,
+            duration: timestamp - this.speakStart
+          });
+        }
+        break;
+      case "interrupt_intent":
+        if (confidence >= threshold) {
+          this.emit("interrupt", { timestamp });
+        }
+        break;
+    }
+  }
+  /**
+   * Reset internal state.
+   */
+  reset() {
+    this.state = "idle";
+    this.pauseStart = 0;
+    this.speakStart = 0;
+  }
+  emit(event, payload) {
+    this.listeners.get(event)?.forEach((fn) => fn(payload));
+  }
+};
+
+// src/types.ts
+var DEFAULT_OPTIONS = {
+  sensitivity: 0.5,
+  pauseTolerance: 1500,
+  modelPath: "bundled",
+  sampleRate: 16e3
+};
+
+// src/utterance.ts
+var Utterance = class {
+  options;
+  audio;
+  features;
+  model;
+  detector;
+  listening = false;
+  constructor(options = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.audio = new AudioCapture(this.options.sampleRate);
+    this.features = new FeatureExtractor(this.options.sampleRate);
+    this.model = new ONNXModel(this.options.sensitivity);
+    this.detector = new TurnDetector(
+      this.options.sensitivity,
+      this.options.pauseTolerance
+    );
+  }
+  /**
+   * Register an event listener.
+   */
+  on(event, listener) {
+    this.detector.on(event, listener);
+  }
+  /**
+   * Remove an event listener.
+   */
+  off(event, listener) {
+    this.detector.off(event, listener);
+  }
+  /**
+   * Start listening to the microphone and detecting turns.
+   */
+  async start() {
+    if (this.listening) return;
+    await this.model.load(this.options.modelPath);
+    this.audio.onAudioData(async (frame) => {
+      const extracted = this.features.extract(frame);
+      const result = await this.model.predict(extracted);
+      this.detector.process(result);
+    });
+    await this.audio.start();
+    this.listening = true;
+  }
+  /**
+   * Stop listening and release all resources.
+   */
+  stop() {
+    if (!this.listening) return;
+    this.audio.stop();
+    this.model.dispose();
+    this.detector.reset();
+    this.listening = false;
+  }
+  /**
+   * Returns whether the detector is currently listening.
+   */
+  isListening() {
+    return this.listening;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Utterance
+});

package/dist/index.d.cts

@@ -0,0 +1,92 @@
+/**
+ * Core types for the Utterance SDK.
+ *
+ * All shared interfaces and type definitions live here to keep
+ * the codebase scalable and avoid circular dependencies.
+ */
+interface UtteranceOptions {
+    /** Detection sensitivity (0-1). Higher = more sensitive to pauses. Default: 0.5 */
+    sensitivity?: number;
+    /** Max thinking pause duration (ms) before triggering turnEnd. Default: 1500 */
+    pauseTolerance?: number;
+    /** Path to a custom ONNX model. Default: bundled model */
+    modelPath?: string;
+    /** Audio sample rate in Hz. Default: 16000 */
+    sampleRate?: number;
+}
+type ClassificationLabel = "speaking" | "thinking_pause" | "turn_complete" | "interrupt_intent";
+interface ClassificationResult {
+    label: ClassificationLabel;
+    confidence: number;
+    timestamp: number;
+}
+interface SpeechStartEvent {
+    timestamp: number;
+}
+interface PauseEvent {
+    duration: number;
+    confidence: number;
+}
+interface TurnEndEvent {
+    confidence: number;
+    duration: number;
+}
+interface InterruptEvent {
+    timestamp: number;
+}
+interface UtteranceEventMap {
+    speechStart: SpeechStartEvent;
+    pause: PauseEvent;
+    turnEnd: TurnEndEvent;
+    interrupt: InterruptEvent;
+}
+type UtteranceEvent = keyof UtteranceEventMap;
+interface AudioFeatures {
+    mfcc: Float32Array;
+    energy: number;
+    pitch: number;
+    speechRate: number;
+    pauseDuration: number;
+}
+
+/**
+ * Main entry point for the Utterance SDK.
+ *
+ * Usage:
+ * ```ts
+ * const detector = new Utterance({ sensitivity: 0.6 });
+ * detector.on("turnEnd", (e) => console.log("Done!", e.confidence));
+ * await detector.start();
+ * ```
+ */
+declare class Utterance {
+    private readonly options;
+    private readonly audio;
+    private readonly features;
+    private readonly model;
+    private readonly detector;
+    private listening;
+    constructor(options?: UtteranceOptions);
+    /**
+     * Register an event listener.
+     */
+    on<E extends UtteranceEvent>(event: E, listener: (payload: UtteranceEventMap[E]) => void): void;
+    /**
+     * Remove an event listener.
+     */
+    off<E extends UtteranceEvent>(event: E, listener: (payload: UtteranceEventMap[E]) => void): void;
+    /**
+     * Start listening to the microphone and detecting turns.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop listening and release all resources.
+     */
+    stop(): void;
+    /**
+     * Returns whether the detector is currently listening.
+     */
+    isListening(): boolean;
+}
+
+export { type AudioFeatures, type ClassificationLabel, type ClassificationResult, type InterruptEvent, type PauseEvent, type SpeechStartEvent, type TurnEndEvent, Utterance, type UtteranceEvent, type UtteranceEventMap, type UtteranceOptions };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Core types for the Utterance SDK.
+ *
+ * All shared interfaces and type definitions live here to keep
+ * the codebase scalable and avoid circular dependencies.
+ */
+interface UtteranceOptions {
+    /** Detection sensitivity (0-1). Higher = more sensitive to pauses. Default: 0.5 */
+    sensitivity?: number;
+    /** Max thinking pause duration (ms) before triggering turnEnd. Default: 1500 */
+    pauseTolerance?: number;
+    /** Path to a custom ONNX model. Default: bundled model */
+    modelPath?: string;
+    /** Audio sample rate in Hz. Default: 16000 */
+    sampleRate?: number;
+}
+type ClassificationLabel = "speaking" | "thinking_pause" | "turn_complete" | "interrupt_intent";
+interface ClassificationResult {
+    label: ClassificationLabel;
+    confidence: number;
+    timestamp: number;
+}
+interface SpeechStartEvent {
+    timestamp: number;
+}
+interface PauseEvent {
+    duration: number;
+    confidence: number;
+}
+interface TurnEndEvent {
+    confidence: number;
+    duration: number;
+}
+interface InterruptEvent {
+    timestamp: number;
+}
+interface UtteranceEventMap {
+    speechStart: SpeechStartEvent;
+    pause: PauseEvent;
+    turnEnd: TurnEndEvent;
+    interrupt: InterruptEvent;
+}
+type UtteranceEvent = keyof UtteranceEventMap;
+interface AudioFeatures {
+    mfcc: Float32Array;
+    energy: number;
+    pitch: number;
+    speechRate: number;
+    pauseDuration: number;
+}
+
+/**
+ * Main entry point for the Utterance SDK.
+ *
+ * Usage:
+ * ```ts
+ * const detector = new Utterance({ sensitivity: 0.6 });
+ * detector.on("turnEnd", (e) => console.log("Done!", e.confidence));
+ * await detector.start();
+ * ```
+ */
+declare class Utterance {
+    private readonly options;
+    private readonly audio;
+    private readonly features;
+    private readonly model;
+    private readonly detector;
+    private listening;
+    constructor(options?: UtteranceOptions);
+    /**
+     * Register an event listener.
+     */
+    on<E extends UtteranceEvent>(event: E, listener: (payload: UtteranceEventMap[E]) => void): void;
+    /**
+     * Remove an event listener.
+     */
+    off<E extends UtteranceEvent>(event: E, listener: (payload: UtteranceEventMap[E]) => void): void;
+    /**
+     * Start listening to the microphone and detecting turns.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop listening and release all resources.
+     */
+    stop(): void;
+    /**
+     * Returns whether the detector is currently listening.
+     */
+    isListening(): boolean;
+}
+
+export { type AudioFeatures, type ClassificationLabel, type ClassificationResult, type InterruptEvent, type PauseEvent, type SpeechStartEvent, type TurnEndEvent, Utterance, type UtteranceEvent, type UtteranceEventMap, type UtteranceOptions };

package/dist/index.js

@@ -0,0 +1,354 @@
+// src/audio/capture.ts
+var AudioCapture = class {
+  context = null;
+  stream = null;
+  processor = null;
+  callback = null;
+  sampleRate;
+  constructor(sampleRate = 16e3) {
+    this.sampleRate = sampleRate;
+  }
+  onAudioData(callback) {
+    this.callback = callback;
+  }
+  async start() {
+    this.stream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        sampleRate: this.sampleRate,
+        channelCount: 1,
+        echoCancellation: true,
+        noiseSuppression: true
+      }
+    });
+    this.context = new AudioContext({ sampleRate: this.sampleRate });
+    const source = this.context.createMediaStreamSource(this.stream);
+    const bufferSize = 4096;
+    this.processor = this.context.createScriptProcessor(bufferSize, 1, 1);
+    this.processor.onaudioprocess = (event) => {
+      const input = event.inputBuffer.getChannelData(0);
+      this.callback?.(new Float32Array(input));
+    };
+    source.connect(this.processor);
+    this.processor.connect(this.context.destination);
+  }
+  stop() {
+    this.processor?.disconnect();
+    this.stream?.getTracks().forEach((track) => track.stop());
+    void this.context?.close();
+    this.processor = null;
+    this.stream = null;
+    this.context = null;
+  }
+};
+
+// src/features/extractor.ts
+var FeatureExtractor = class {
+  sampleRate;
+  constructor(sampleRate = 16e3) {
+    this.sampleRate = sampleRate;
+  }
+  /**
+   * Extract all features from a single audio frame.
+   */
+  extract(frame) {
+    return {
+      mfcc: this.computeMFCC(frame),
+      energy: this.computeEnergy(frame),
+      pitch: this.estimatePitch(frame),
+      speechRate: this.estimateSpeechRate(frame),
+      pauseDuration: 0
+      // tracked by the detector over time
+    };
+  }
+  /**
+   * Compute Mel-Frequency Cepstral Coefficients.
+   *
+   * TODO: Implement full MFCC pipeline:
+   *   1. Pre-emphasis filter
+   *   2. Windowing (Hamming)
+   *   3. FFT
+   *   4. Mel filterbank
+   *   5. Log energy
+   *   6. DCT
+   */
+  computeMFCC(_frame) {
+    return new Float32Array(13);
+  }
+  /**
+   * Compute RMS energy of the frame.
+   */
+  computeEnergy(frame) {
+    let sum = 0;
+    for (let i = 0; i < frame.length; i++) {
+      sum += frame[i] * frame[i];
+    }
+    return Math.sqrt(sum / frame.length);
+  }
+  /**
+   * Estimate fundamental frequency (pitch) using autocorrelation.
+   *
+   * TODO: Implement YIN or autocorrelation-based pitch detection.
+   */
+  estimatePitch(_frame) {
+    void this.sampleRate;
+    return 0;
+  }
+  /**
+   * Estimate speech rate (syllables per second).
+   *
+   * TODO: Implement energy-envelope peak counting.
+   */
+  estimateSpeechRate(_frame) {
+    return 0;
+  }
+};
+
+// src/model/energy-vad.ts
+var EnergyVAD = class {
+  speechThreshold;
+  silenceThreshold;
+  isSpeaking = false;
+  silenceStart = 0;
+  pauseHintMs;
+  constructor(sensitivity = 0.5) {
+    this.speechThreshold = 0.015 * (1 - sensitivity * 0.8);
+    this.silenceThreshold = this.speechThreshold * 0.6;
+    this.pauseHintMs = 800;
+  }
+  classify(features) {
+    const { energy } = features;
+    const now = Date.now();
+    if (!this.isSpeaking && energy >= this.speechThreshold) {
+      this.isSpeaking = true;
+      this.silenceStart = 0;
+      return { label: "speaking", confidence: this.energyToConfidence(energy), timestamp: now };
+    }
+    if (this.isSpeaking && energy >= this.silenceThreshold) {
+      this.silenceStart = 0;
+      return { label: "speaking", confidence: this.energyToConfidence(energy), timestamp: now };
+    }
+    if (this.isSpeaking && energy < this.silenceThreshold) {
+      if (this.silenceStart === 0) {
+        this.silenceStart = now;
+      }
+      const silenceDuration = now - this.silenceStart;
+      if (silenceDuration >= this.pauseHintMs) {
+        this.isSpeaking = false;
+        const confidence = Math.min(silenceDuration / (this.pauseHintMs * 2), 1);
+        return { label: "turn_complete", confidence, timestamp: now };
+      }
+      return { label: "thinking_pause", confidence: 0.6, timestamp: now };
+    }
+    return { label: "thinking_pause", confidence: 0.3, timestamp: now };
+  }
+  reset() {
+    this.isSpeaking = false;
+    this.silenceStart = 0;
+  }
+  energyToConfidence(energy) {
+    return Math.min(energy / (this.speechThreshold * 4), 1);
+  }
+};
+
+// src/model/onnx.ts
+var ONNXModel = class {
+  session = null;
+  fallback;
+  constructor(sensitivity = 0.5) {
+    this.fallback = new EnergyVAD(sensitivity);
+  }
+  /**
+   * Load the ONNX model from a given path or URL.
+   *
+   * TODO:
+   *   1. Import onnxruntime-web InferenceSession
+   *   2. Load model bytes
+   *   3. Create session with appropriate execution providers
+   */
+  async load(_path) {
+    this.session = null;
+  }
+  /**
+   * Run inference on a set of extracted features.
+   *
+   * TODO:
+   *   1. Build input tensor from AudioFeatures
+   *   2. Run session.run()
+   *   3. Parse output into ClassificationResult
+   */
+  async predict(features) {
+    if (!this.session) {
+      return this.fallback.classify(features);
+    }
+    return this.fallback.classify(features);
+  }
+  /**
+   * Release model resources.
+   */
+  dispose() {
+    this.session = null;
+    this.fallback.reset();
+  }
+};
+
+// src/detector/turn-detector.ts
+var TurnDetector = class {
+  listeners = /* @__PURE__ */ new Map();
+  state = "idle";
+  pauseStart = 0;
+  speakStart = 0;
+  sensitivity;
+  pauseTolerance;
+  constructor(sensitivity = 0.5, pauseTolerance = 1500) {
+    this.sensitivity = sensitivity;
+    this.pauseTolerance = pauseTolerance;
+  }
+  /**
+   * Register an event listener.
+   */
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+  }
+  /**
+   * Remove an event listener.
+   */
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+  }
+  /**
+   * Process a classification result from the model and emit events.
+   */
+  process(result) {
+    const { label, confidence, timestamp } = result;
+    const threshold = this.sensitivity;
+    switch (label) {
+      case "speaking":
+        if (this.state !== "speaking") {
+          this.state = "speaking";
+          this.speakStart = timestamp;
+          this.emit("speechStart", { timestamp });
+        }
+        break;
+      case "thinking_pause":
+        if (this.state === "speaking" && confidence >= threshold) {
+          this.state = "paused";
+          this.pauseStart = timestamp;
+          this.emit("pause", {
+            duration: 0,
+            confidence
+          });
+        } else if (this.state === "paused") {
+          const duration = timestamp - this.pauseStart;
+          if (duration >= this.pauseTolerance) {
+            this.state = "idle";
+            this.emit("turnEnd", {
+              confidence,
+              duration: timestamp - this.speakStart
+            });
+          }
+        }
+        break;
+      case "turn_complete":
+        if ((this.state === "speaking" || this.state === "paused") && confidence >= threshold) {
+          this.state = "idle";
+          this.emit("turnEnd", {
+            confidence,
+            duration: timestamp - this.speakStart
+          });
+        }
+        break;
+      case "interrupt_intent":
+        if (confidence >= threshold) {
+          this.emit("interrupt", { timestamp });
+        }
+        break;
+    }
+  }
+  /**
+   * Reset internal state.
+   */
+  reset() {
+    this.state = "idle";
+    this.pauseStart = 0;
+    this.speakStart = 0;
+  }
+  emit(event, payload) {
+    this.listeners.get(event)?.forEach((fn) => fn(payload));
+  }
+};
+
+// src/types.ts
+var DEFAULT_OPTIONS = {
+  sensitivity: 0.5,
+  pauseTolerance: 1500,
+  modelPath: "bundled",
+  sampleRate: 16e3
+};
+
+// src/utterance.ts
+var Utterance = class {
+  options;
+  audio;
+  features;
+  model;
+  detector;
+  listening = false;
+  constructor(options = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.audio = new AudioCapture(this.options.sampleRate);
+    this.features = new FeatureExtractor(this.options.sampleRate);
+    this.model = new ONNXModel(this.options.sensitivity);
+    this.detector = new TurnDetector(
+      this.options.sensitivity,
+      this.options.pauseTolerance
+    );
+  }
+  /**
+   * Register an event listener.
+   */
+  on(event, listener) {
+    this.detector.on(event, listener);
+  }
+  /**
+   * Remove an event listener.
+   */
+  off(event, listener) {
+    this.detector.off(event, listener);
+  }
+  /**
+   * Start listening to the microphone and detecting turns.
+   */
+  async start() {
+    if (this.listening) return;
+    await this.model.load(this.options.modelPath);
+    this.audio.onAudioData(async (frame) => {
+      const extracted = this.features.extract(frame);
+      const result = await this.model.predict(extracted);
+      this.detector.process(result);
+    });
+    await this.audio.start();
+    this.listening = true;
+  }
+  /**
+   * Stop listening and release all resources.
+   */
+  stop() {
+    if (!this.listening) return;
+    this.audio.stop();
+    this.model.dispose();
+    this.detector.reset();
+    this.listening = false;
+  }
+  /**
+   * Returns whether the detector is currently listening.
+   */
+  isListening() {
+    return this.listening;
+  }
+};
+export {
+  Utterance
+};

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@utterance/core",
+  "version": "0.0.1",
+  "description": "Client-side semantic endpointing. Know when they're done talking.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "models"
+  ],
+  "scripts": {
+    "start": "npm run build:sdk && run-p build:sdk:watch dev test:watch",
+    "dev": "next dev",
+    "build": "npm run build:sdk && next build",
+    "build:sdk": "tsup src/index.ts --format esm,cjs --dts --clean --tsconfig tsconfig.sdk.json",
+    "build:sdk:watch": "tsup src/index.ts --watch --format esm,cjs --dts --tsconfig tsconfig.sdk.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint src/ tests/ --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "voice",
+    "speech",
+    "endpointing",
+    "vad",
+    "turn-detection",
+    "audio",
+    "ml",
+    "onnx",
+    "web-audio",
+    "real-time"
+  ],
+  "author": "Utterance Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nizh0/Utterance.git"
+  },
+  "homepage": "https://utterance.dev",
+  "bugs": {
+    "url": "https://github.com/nizh0/Utterance/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@tailwindcss/postcss": "^4.2.0",
+    "@types/mdx": "^2.0.13",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.182.0",
+    "eslint": "^9.0.0",
+    "npm-run-all2": "^8.0.4",
+    "postcss": "^8.5.6",
+    "prettier": "^3.4.0",
+    "shadcn": "^3.8.5",
+    "tailwindcss": "^4.2.0",
+    "tsup": "^8.0.0",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@next/third-parties": "^16.1.6",
+    "@react-three/fiber": "^9.5.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "fumadocs-core": "^16.6.3",
+    "fumadocs-mdx": "^14.2.7",
+    "fumadocs-ui": "^16.6.3",
+    "lucide-react": "^0.574.0",
+    "next": "^16.1.6",
+    "onnxruntime-web": "^1.20.0",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwind-merge": "^3.4.1",
+    "three": "^0.183.0"
+  }
+}