@framers/agentos-ext-streaming-stt-whisper 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Framers
+
+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/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: streaming-stt-whisper
+description: Chunked sliding-window streaming speech-to-text via OpenAI Whisper HTTP API
+category: voice
+---
+
+# Whisper Chunked Streaming STT
+
+Streaming speech-to-text using OpenAI's Whisper model via the `/v1/audio/transcriptions` HTTP API.
+Audio is accumulated in a sliding-window ring buffer and sent as 1-second WAV chunks with 200 ms
+overlap for continuity.
+
+## Setup
+
+Set `OPENAI_API_KEY` in your environment or agent secrets store.
+
+## Features
+
+- Works with any OpenAI-compatible Whisper endpoint (e.g. local Faster-Whisper, Groq, OpenRouter)
+- Sliding-window ring buffer: 1 s chunks, 200 ms overlap to prevent word boundary clipping
+- Inline WAV encoding — zero runtime dependencies (no `ws`, no native binaries)
+- Previous chunk transcript forwarded as `prompt` for cross-chunk continuity
+- Simple RMS energy detector emits `speech_start` / `speech_end` events
+- On fetch failure, emits `error` and continues processing — no session crash
+
+## Configuration
+
+In `agent.config.json`:
+
+```json
+{
+  "voice": {
+    "stt": "whisper"
+  }
+}
+```
+
+Provider-specific options via `providerOptions`:
+
+```json
+{
+  "voice": {
+    "stt": "whisper",
+    "providerOptions": {
+      "model": "whisper-1",
+      "language": "en",
+      "baseUrl": "https://api.openai.com"
+    }
+  }
+}
+```
+
+## Events
+
+| Event                  | Payload           | Description                                     |
+|------------------------|-------------------|-------------------------------------------------|
+| `interim_transcript`   | `TranscriptEvent` | Emitted after each chunk is transcribed         |
+| `final_transcript`     | `TranscriptEvent` | Emitted after flush() completes                 |
+| `speech_start`         | —                 | RMS energy crossed threshold (0.01)             |
+| `speech_end`           | —                 | RMS energy dropped below threshold              |
+| `error`                | `Error`           | Fetch failure (session continues)               |
+| `close`                | —                 | Session fully terminated                        |

package/dist/SlidingWindowBuffer.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @file SlidingWindowBuffer.ts
+ * @description Ring buffer that accumulates Float32 audio frames into fixed-size chunks
+ * with configurable overlap between consecutive chunks.
+ *
+ * When {@link pushSamples} fills the internal buffer to {@link chunkSizeSamples}, it
+ * emits a `'chunk_ready'` event carrying the complete `Float32Array` chunk, copies the
+ * last {@link overlapSamples} samples to the head of the buffer as overlap context for
+ * the next chunk, and resets the write cursor accordingly.
+ *
+ * The overlap strategy prevents words straddling chunk boundaries from being silently
+ * dropped by the Whisper model.
+ *
+ * @module streaming-stt-whisper/SlidingWindowBuffer
+ */
+import { EventEmitter } from 'node:events';
+/**
+ * Default chunk size in samples.
+ * At 16 kHz this corresponds to exactly 1 second of mono audio.
+ */
+export declare const DEFAULT_CHUNK_SIZE_SAMPLES = 16000;
+/**
+ * Default overlap in samples carried forward to the next chunk.
+ * At 16 kHz this corresponds to 200 ms of audio context.
+ */
+export declare const DEFAULT_OVERLAP_SAMPLES = 3200;
+/** Event map for {@link SlidingWindowBuffer}. */
+export interface SlidingWindowBufferEvents {
+    /** Emitted when a complete chunk of {@link chunkSizeSamples} is ready. */
+    chunk_ready: [chunk: Float32Array];
+}
+/**
+ * Ring-buffer that accumulates raw PCM samples and emits fixed-size audio
+ * chunks with configurable overlap.
+ *
+ * @example
+ * ```ts
+ * const buf = new SlidingWindowBuffer(16_000, 3_200);
+ * buf.on('chunk_ready', (chunk) => sendToWhisper(chunk));
+ *
+ * microphone.on('frame', (f) => buf.pushSamples(f.samples));
+ * await buf.flush(); // emit any remaining samples
+ * ```
+ */
+export declare class SlidingWindowBuffer extends EventEmitter {
+    private readonly chunkSizeSamples;
+    private readonly overlapSamples;
+    /**
+     * Internal sample store.  Sized to {@link chunkSizeSamples} so a single
+     * allocation is reused for the lifetime of the session.
+     */
+    private buffer;
+    /**
+     * Current write position within {@link buffer}.
+     * Always in the range `[0, chunkSizeSamples)`.
+     */
+    private writePos;
+    /**
+     * @param chunkSizeSamples - Number of samples per emitted chunk.
+     *   Defaults to {@link DEFAULT_CHUNK_SIZE_SAMPLES} (1 s at 16 kHz).
+     * @param overlapSamples - Number of samples carried forward from each chunk
+     *   to the start of the next.  Must be less than `chunkSizeSamples`.
+     *   Defaults to {@link DEFAULT_OVERLAP_SAMPLES} (200 ms at 16 kHz).
+     */
+    constructor(chunkSizeSamples?: number, overlapSamples?: number);
+    /**
+     * Append audio samples to the internal buffer.
+     *
+     * If the incoming batch causes the buffer to reach or exceed
+     * {@link chunkSizeSamples}, one or more `'chunk_ready'` events are emitted
+     * before the remainder is retained for the next chunk.  Each chunk includes
+     * an overlap region copied from the tail of the previous chunk.
+     *
+     * @param samples - Float32 PCM samples to append.
+     */
+    pushSamples(samples: Float32Array): void;
+    /**
+     * Emit any samples currently held in the buffer as a final partial chunk.
+     *
+     * If the buffer contains no samples (`writePos === 0`), this is a no-op.
+     * After flushing, the buffer is reset to an empty state.
+     */
+    flush(): void;
+    /**
+     * Clear all buffered samples and reset the write cursor to zero.
+     *
+     * Does NOT emit a `'chunk_ready'` event — use {@link flush} for that.
+     */
+    reset(): void;
+    /** Number of samples currently held in the buffer. */
+    get bufferedSamples(): number;
+}
+//# sourceMappingURL=SlidingWindowBuffer.d.ts.map

package/dist/SlidingWindowBuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlidingWindowBuffer.d.ts","sourceRoot":"","sources":["../src/SlidingWindowBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C;;;GAGG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAM7C,iDAAiD;AACjD,MAAM,WAAW,yBAAyB;IACxC,0EAA0E;IAC1E,WAAW,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;CACpC;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IA6BjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAzBjC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAe;IAE7B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAK;IAMrB;;;;;;OAMG;gBAEgB,gBAAgB,GAAE,MAAmC,EACrD,cAAc,GAAE,MAAgC;IAiBnE;;;;;;;;;OASG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAyBxC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAQb;;;;OAIG;IACH,KAAK,IAAI,IAAI;IASb,sDAAsD;IACtD,IAAI,eAAe,IAAI,MAAM,CAE5B;CACF"}

package/dist/SlidingWindowBuffer.js

@@ -0,0 +1,144 @@
+/**
+ * @file SlidingWindowBuffer.ts
+ * @description Ring buffer that accumulates Float32 audio frames into fixed-size chunks
+ * with configurable overlap between consecutive chunks.
+ *
+ * When {@link pushSamples} fills the internal buffer to {@link chunkSizeSamples}, it
+ * emits a `'chunk_ready'` event carrying the complete `Float32Array` chunk, copies the
+ * last {@link overlapSamples} samples to the head of the buffer as overlap context for
+ * the next chunk, and resets the write cursor accordingly.
+ *
+ * The overlap strategy prevents words straddling chunk boundaries from being silently
+ * dropped by the Whisper model.
+ *
+ * @module streaming-stt-whisper/SlidingWindowBuffer
+ */
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Default chunk size in samples.
+ * At 16 kHz this corresponds to exactly 1 second of mono audio.
+ */
+export const DEFAULT_CHUNK_SIZE_SAMPLES = 16_000;
+/**
+ * Default overlap in samples carried forward to the next chunk.
+ * At 16 kHz this corresponds to 200 ms of audio context.
+ */
+export const DEFAULT_OVERLAP_SAMPLES = 3_200;
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * Ring-buffer that accumulates raw PCM samples and emits fixed-size audio
+ * chunks with configurable overlap.
+ *
+ * @example
+ * ```ts
+ * const buf = new SlidingWindowBuffer(16_000, 3_200);
+ * buf.on('chunk_ready', (chunk) => sendToWhisper(chunk));
+ *
+ * microphone.on('frame', (f) => buf.pushSamples(f.samples));
+ * await buf.flush(); // emit any remaining samples
+ * ```
+ */
+export class SlidingWindowBuffer extends EventEmitter {
+    chunkSizeSamples;
+    overlapSamples;
+    // -------------------------------------------------------------------------
+    // Private state
+    // -------------------------------------------------------------------------
+    /**
+     * Internal sample store.  Sized to {@link chunkSizeSamples} so a single
+     * allocation is reused for the lifetime of the session.
+     */
+    buffer;
+    /**
+     * Current write position within {@link buffer}.
+     * Always in the range `[0, chunkSizeSamples)`.
+     */
+    writePos = 0;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param chunkSizeSamples - Number of samples per emitted chunk.
+     *   Defaults to {@link DEFAULT_CHUNK_SIZE_SAMPLES} (1 s at 16 kHz).
+     * @param overlapSamples - Number of samples carried forward from each chunk
+     *   to the start of the next.  Must be less than `chunkSizeSamples`.
+     *   Defaults to {@link DEFAULT_OVERLAP_SAMPLES} (200 ms at 16 kHz).
+     */
+    constructor(chunkSizeSamples = DEFAULT_CHUNK_SIZE_SAMPLES, overlapSamples = DEFAULT_OVERLAP_SAMPLES) {
+        super();
+        this.chunkSizeSamples = chunkSizeSamples;
+        this.overlapSamples = overlapSamples;
+        if (overlapSamples >= chunkSizeSamples) {
+            throw new RangeError(`overlapSamples (${overlapSamples}) must be less than chunkSizeSamples (${chunkSizeSamples})`);
+        }
+        this.buffer = new Float32Array(chunkSizeSamples);
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Append audio samples to the internal buffer.
+     *
+     * If the incoming batch causes the buffer to reach or exceed
+     * {@link chunkSizeSamples}, one or more `'chunk_ready'` events are emitted
+     * before the remainder is retained for the next chunk.  Each chunk includes
+     * an overlap region copied from the tail of the previous chunk.
+     *
+     * @param samples - Float32 PCM samples to append.
+     */
+    pushSamples(samples) {
+        let srcOffset = 0;
+        while (srcOffset < samples.length) {
+            // How many samples can we copy into the current chunk before it is full?
+            const spaceLeft = this.chunkSizeSamples - this.writePos;
+            const copyCount = Math.min(spaceLeft, samples.length - srcOffset);
+            this.buffer.set(samples.subarray(srcOffset, srcOffset + copyCount), this.writePos);
+            this.writePos += copyCount;
+            srcOffset += copyCount;
+            if (this.writePos >= this.chunkSizeSamples) {
+                // Chunk is full — emit a copy (not a reference to the internal buffer).
+                this.emit('chunk_ready', this.buffer.slice());
+                // Copy the last `overlapSamples` to the beginning of the buffer so that
+                // the next chunk begins with audio context from the previous boundary.
+                const overlapStart = this.chunkSizeSamples - this.overlapSamples;
+                this.buffer.copyWithin(0, overlapStart, this.chunkSizeSamples);
+                this.writePos = this.overlapSamples;
+            }
+        }
+    }
+    /**
+     * Emit any samples currently held in the buffer as a final partial chunk.
+     *
+     * If the buffer contains no samples (`writePos === 0`), this is a no-op.
+     * After flushing, the buffer is reset to an empty state.
+     */
+    flush() {
+        if (this.writePos === 0)
+            return;
+        // Emit only the samples that were actually written (not the whole buffer).
+        this.emit('chunk_ready', this.buffer.slice(0, this.writePos));
+        this.reset();
+    }
+    /**
+     * Clear all buffered samples and reset the write cursor to zero.
+     *
+     * Does NOT emit a `'chunk_ready'` event — use {@link flush} for that.
+     */
+    reset() {
+        this.buffer = new Float32Array(this.chunkSizeSamples);
+        this.writePos = 0;
+    }
+    // -------------------------------------------------------------------------
+    // Accessors (useful for testing)
+    // -------------------------------------------------------------------------
+    /** Number of samples currently held in the buffer. */
+    get bufferedSamples() {
+        return this.writePos;
+    }
+}
+//# sourceMappingURL=SlidingWindowBuffer.js.map

package/dist/SlidingWindowBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlidingWindowBuffer.js","sourceRoot":"","sources":["../src/SlidingWindowBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAY7C,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IA6BhC;IACA;IA7BnB,4EAA4E;IAC5E,gBAAgB;IAChB,4EAA4E;IAE5E;;;OAGG;IACK,MAAM,CAAe;IAE7B;;;OAGG;IACK,QAAQ,GAAG,CAAC,CAAC;IAErB,4EAA4E;IAC5E,cAAc;IACd,4EAA4E;IAE5E;;;;;;OAMG;IACH,YACmB,mBAA2B,0BAA0B,EACrD,iBAAyB,uBAAuB;QAEjE,KAAK,EAAE,CAAC;QAHS,qBAAgB,GAAhB,gBAAgB,CAAqC;QACrD,mBAAc,GAAd,cAAc,CAAkC;QAIjE,IAAI,cAAc,IAAI,gBAAgB,EAAE,CAAC;YACvC,MAAM,IAAI,UAAU,CAClB,mBAAmB,cAAc,yCAAyC,gBAAgB,GAAG,CAC9F,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,gBAAgB,CAAC,CAAC;IACnD,CAAC;IAED,4EAA4E;IAC5E,aAAa;IACb,4EAA4E;IAE5E;;;;;;;;;OASG;IACH,WAAW,CAAC,OAAqB;QAC/B,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,OAAO,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAClC,yEAAyE;YACzE,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC;YACxD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;YAElE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YACnF,IAAI,CAAC,QAAQ,IAAI,SAAS,CAAC;YAC3B,SAAS,IAAI,SAAS,CAAC;YAEvB,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC3C,wEAAwE;gBACxE,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;gBAE9C,wEAAwE;gBACxE,uEAAuE;gBACvE,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,cAAc,CAAC;gBACjE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;gBAC/D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC;YACtC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC;YAAE,OAAO;QAEhC,2EAA2E;QAC3E,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC9D,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACtD,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IACpB,CAAC;IAED,4EAA4E;IAC5E,iCAAiC;IACjC,4EAA4E;IAE5E,sDAAsD;IACtD,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}

package/dist/WhisperChunkSession.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @file WhisperChunkSession.ts
+ * @description Active streaming STT session backed by the OpenAI Whisper HTTP API.
+ *
+ * {@link WhisperChunkSession} implements the `StreamingSTTSession` interface
+ * (EventEmitter-based) using a sliding-window ring buffer to accumulate audio
+ * into fixed-size chunks.  Each chunk is encoded as a RIFF/WAV file and posted
+ * to the Whisper `/v1/audio/transcriptions` endpoint.
+ *
+ * ### Chunk lifecycle
+ * 1. {@link pushAudio} feeds PCM frames into the internal {@link SlidingWindowBuffer}.
+ * 2. When a full chunk is ready, {@link onChunkReady} is invoked.
+ * 3. The chunk is WAV-encoded and POST-ed to Whisper with multipart/form-data.
+ * 4. The parsed response is emitted as `'interim_transcript'`.
+ * 5. The response text becomes the `prompt` for the next API call (continuity).
+ *
+ * ### Speech detection
+ * A simple RMS energy threshold (`RMS_THRESHOLD = 0.01`) gates `speech_start`
+ * and `speech_end` events.  This is not VAD — it is a lightweight proxy that
+ * avoids emitting events on pure-silence frames.
+ *
+ * ### Error resilience
+ * On fetch failure the error is emitted as an `'error'` event and the session
+ * continues processing subsequent chunks rather than terminating.
+ *
+ * @module streaming-stt-whisper/WhisperChunkSession
+ */
+import { EventEmitter } from 'node:events';
+import type { WhisperChunkedConfig, AudioFrame } from './types.js';
+/**
+ * Active chunked Whisper STT session.
+ *
+ * Construct via {@link WhisperChunkedSTT.startSession} rather than directly.
+ *
+ * @example
+ * ```ts
+ * const session = new WhisperChunkSession({ apiKey: process.env.OPENAI_API_KEY! });
+ *
+ * session.on('interim_transcript', (evt) => console.log('chunk:', evt.text));
+ * session.on('final_transcript',   (evt) => console.log('done:', evt.text));
+ *
+ * microphone.on('frame', (f) => session.pushAudio(f));
+ * await session.flush();
+ * session.close();
+ * ```
+ */
+export declare class WhisperChunkSession extends EventEmitter {
+    /** Resolved Whisper API configuration. */
+    private readonly cfg;
+    /** Sliding-window ring buffer feeding audio chunks. */
+    private readonly slidingBuffer;
+    /** Whether {@link close} has been called. */
+    private closed;
+    /** Whether the session is currently in a speech segment (above RMS threshold). */
+    private inSpeech;
+    /**
+     * Transcript text from the most recently completed chunk.
+     * Forwarded as `prompt` to the next Whisper API call for cross-chunk
+     * lexical continuity.
+     */
+    private previousPrompt;
+    /**
+     * @param config - Whisper session configuration.  `apiKey` is required.
+     */
+    constructor(config: WhisperChunkedConfig);
+    /**
+     * Feed a raw audio frame into the session.
+     *
+     * The frame's samples are appended to the sliding-window buffer.  When the
+     * buffer accumulates a full chunk, {@link onChunkReady} is invoked.
+     *
+     * Speech detection is performed on every frame: if the RMS energy crosses
+     * {@link RMS_THRESHOLD}, `'speech_start'` is emitted on the first such frame
+     * and `'speech_end'` when energy falls back below the threshold.
+     *
+     * @param frame - Audio frame with normalised Float32 samples.
+     */
+    pushAudio(frame: AudioFrame): void;
+    /**
+     * Flush any remaining buffered samples, transcribe the final partial chunk,
+     * and emit `'final_transcript'`.
+     *
+     * Must be called when the audio stream ends to ensure the tail of the
+     * recording is not silently discarded.
+     *
+     * @returns Promise that resolves when the final Whisper request completes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Immediately terminate the session.
+     *
+     * No further events are emitted after `close()`.
+     */
+    close(): void;
+    /**
+     * Transcribe a ready audio chunk by POST-ing it to the Whisper API.
+     *
+     * Steps:
+     * 1. Encode the Float32 chunk as a RIFF/WAV `ArrayBuffer`.
+     * 2. Build a multipart/form-data body with the WAV blob.
+     * 3. POST to `${baseUrl}/v1/audio/transcriptions`.
+     * 4. Parse the `verbose_json` response into a {@link TranscriptEvent}.
+     * 5. Emit `'interim_transcript'` and save the text as `previousPrompt`.
+     *
+     * On any fetch error, `'error'` is emitted and the method returns normally
+     * so that subsequent chunks are still processed.
+     *
+     * @param chunk - Float32 PCM samples for one audio chunk.
+     */
+    private onChunkReady;
+    /**
+     * Convert a Whisper `verbose_json` response into a {@link TranscriptEvent}.
+     *
+     * Word-level timestamps are sourced from the first segment's `words` array
+     * when available.  Confidence is approximated from the segment `avg_logprob`
+     * (clamped to [0, 1]) when present; falls back to 1 otherwise.
+     *
+     * @param response - Parsed Whisper verbose_json response.
+     * @returns A `TranscriptEvent` suitable for emission.
+     */
+    private parseWhisperResponse;
+}
+//# sourceMappingURL=WhisperChunkSession.d.ts.map

package/dist/WhisperChunkSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhisperChunkSession.d.ts","sourceRoot":"","sources":["../src/WhisperChunkSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EAKX,MAAM,YAAY,CAAC;AA6IpB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IAKnD,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CACqB;IAEzC,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IAEpD,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAAS;IAEvB,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAqB;IAM3C;;OAEG;gBACS,MAAM,EAAE,oBAAoB;IA4BxC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAgBlC;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;;;OAIG;IACH,KAAK,IAAI,IAAI;IASb;;;;;;;;;;;;;;OAcG;YACW,YAAY;IAgD1B;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;CAgC7B"}