@framers/agentos-ext-diarization 0.2.0

package/dist/LocalDiarizationBackend.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @file LocalDiarizationBackend.ts
+ * @description Offline speaker diarization backend using a sliding-window
+ * spectral-centroid voiceprint and cosine similarity matching.
+ *
+ * Audio is accumulated in a {@link SlidingWindowExtractor}.  When a full chunk
+ * is ready, a 16-dimensional feature vector is extracted and matched against
+ * cached speaker centroids.  If no centroid exceeds the similarity threshold a
+ * new `Speaker_N` identity is created.
+ *
+ * The built-in feature extractor is intentionally lightweight.  An ONNX
+ * x-vector model can replace {@link LocalDiarizationBackend.extractSimpleEmbedding}
+ * later without changing the surrounding API.
+ *
+ * @module diarization/LocalDiarizationBackend
+ */
+import { EventEmitter } from 'node:events';
+import type { SpeakerEmbeddingCache } from './SpeakerEmbeddingCache.js';
+import type { SlidingWindowExtractor } from './SlidingWindowExtractor.js';
+/**
+ * Fully offline diarization backend.
+ *
+ * Connects a {@link SlidingWindowExtractor} to a {@link SpeakerEmbeddingCache}
+ * and emits `speaker_identified` events whenever a speaker label is resolved
+ * for a new audio chunk.
+ *
+ * @example
+ * ```ts
+ * const cache = new SpeakerEmbeddingCache(0.7);
+ * const extractor = new SlidingWindowExtractor(1500, 500, 16000);
+ * const backend = new LocalDiarizationBackend(cache, extractor);
+ *
+ * backend.on('speaker_identified', ({ speakerId }) => console.log(speakerId));
+ * backend.start();
+ *
+ * microphone.on('frame', (f) => extractor.pushAudio(f));
+ * ```
+ */
+export declare class LocalDiarizationBackend extends EventEmitter {
+    private readonly cache;
+    private readonly extractor;
+    /**
+     * @param cache - Speaker voiceprint cache used for matching and centroid
+     *   updates.
+     * @param extractor - Sliding-window extractor that supplies audio chunks.
+     */
+    constructor(cache: SpeakerEmbeddingCache, extractor: SlidingWindowExtractor);
+    /**
+     * Attach the `'chunk_ready'` listener to the extractor and begin processing
+     * audio chunks.
+     *
+     * Calling `start()` more than once is safe — subsequent calls are no-ops
+     * because the same bound listener is reused.
+     */
+    start(): void;
+    /**
+     * Detach from the extractor and stop processing.
+     */
+    stop(): void;
+    /**
+     * Bound handler for `'chunk_ready'` events from the extractor.
+     *
+     * Stored as an arrow-function property so the same reference is used for
+     * both `on()` and `off()`.
+     */
+    private readonly _onChunkReady;
+    /**
+     * Extract a 16-dimensional voiceprint from a raw PCM chunk.
+     *
+     * Feature layout (4 octave bands × 4 features per band):
+     * - Band 0: sub-bass  (0 –  500 Hz equivalent bucket)
+     * - Band 1: bass      (500 – 2000 Hz equivalent bucket)
+     * - Band 2: mid       (2000 – 4000 Hz equivalent bucket)
+     * - Band 3: high      (4000 Hz+ equivalent bucket)
+     *
+     * For each band the following statistics are computed:
+     * - [0] RMS energy
+     * - [1] Spectral centroid (normalised to band range)
+     * - [2] Zero-crossing rate
+     * - [3] Delta energy (mean absolute frame-to-frame change)
+     *
+     * This is a placeholder implementation suitable for demos and testing.
+     * Replace with an ONNX x-vector model for production accuracy.
+     *
+     * @param chunk - Float32 PCM audio data.
+     * @returns 16-dimensional embedding vector.
+     */
+    extractSimpleEmbedding(chunk: Float32Array): Float32Array;
+}
+//# sourceMappingURL=LocalDiarizationBackend.d.ts.map

package/dist/LocalDiarizationBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalDiarizationBackend.d.ts","sourceRoot":"","sources":["../src/LocalDiarizationBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAoB1E;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;IAWrD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5B;;;;OAIG;gBAEgB,KAAK,EAAE,qBAAqB,EAC5B,SAAS,EAAE,sBAAsB;IASpD;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI;IAQZ;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAW5B;IAMF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBAAsB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY;CAuD1D"}

package/dist/LocalDiarizationBackend.js

@@ -0,0 +1,177 @@
+/**
+ * @file LocalDiarizationBackend.ts
+ * @description Offline speaker diarization backend using a sliding-window
+ * spectral-centroid voiceprint and cosine similarity matching.
+ *
+ * Audio is accumulated in a {@link SlidingWindowExtractor}.  When a full chunk
+ * is ready, a 16-dimensional feature vector is extracted and matched against
+ * cached speaker centroids.  If no centroid exceeds the similarity threshold a
+ * new `Speaker_N` identity is created.
+ *
+ * The built-in feature extractor is intentionally lightweight.  An ONNX
+ * x-vector model can replace {@link LocalDiarizationBackend.extractSimpleEmbedding}
+ * later without changing the surrounding API.
+ *
+ * @module diarization/LocalDiarizationBackend
+ */
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Size of the local feature vector in dimensions. */
+const FEATURE_DIMS = 16;
+/** Number of octave-band buckets used by the feature extractor. */
+const OCTAVE_BANDS = 4;
+/** Dimensions per octave band (FEATURE_DIMS / OCTAVE_BANDS). */
+const DIMS_PER_BAND = FEATURE_DIMS / OCTAVE_BANDS;
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * Fully offline diarization backend.
+ *
+ * Connects a {@link SlidingWindowExtractor} to a {@link SpeakerEmbeddingCache}
+ * and emits `speaker_identified` events whenever a speaker label is resolved
+ * for a new audio chunk.
+ *
+ * @example
+ * ```ts
+ * const cache = new SpeakerEmbeddingCache(0.7);
+ * const extractor = new SlidingWindowExtractor(1500, 500, 16000);
+ * const backend = new LocalDiarizationBackend(cache, extractor);
+ *
+ * backend.on('speaker_identified', ({ speakerId }) => console.log(speakerId));
+ * backend.start();
+ *
+ * microphone.on('frame', (f) => extractor.pushAudio(f));
+ * ```
+ */
+export class LocalDiarizationBackend extends EventEmitter {
+    cache;
+    extractor;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param cache - Speaker voiceprint cache used for matching and centroid
+     *   updates.
+     * @param extractor - Sliding-window extractor that supplies audio chunks.
+     */
+    constructor(cache, extractor) {
+        super();
+        this.cache = cache;
+        this.extractor = extractor;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Attach the `'chunk_ready'` listener to the extractor and begin processing
+     * audio chunks.
+     *
+     * Calling `start()` more than once is safe — subsequent calls are no-ops
+     * because the same bound listener is reused.
+     */
+    start() {
+        this.extractor.on('chunk_ready', this._onChunkReady);
+    }
+    /**
+     * Detach from the extractor and stop processing.
+     */
+    stop() {
+        this.extractor.off('chunk_ready', this._onChunkReady);
+    }
+    // -------------------------------------------------------------------------
+    // Internal event handler
+    // -------------------------------------------------------------------------
+    /**
+     * Bound handler for `'chunk_ready'` events from the extractor.
+     *
+     * Stored as an arrow-function property so the same reference is used for
+     * both `on()` and `off()`.
+     */
+    _onChunkReady = (chunk) => {
+        const embedding = this.extractSimpleEmbedding(chunk);
+        const { speakerId } = this.cache.getOrCreateSpeaker(embedding);
+        const payload = {
+            speakerId,
+            confidence: 0.7,
+            timestamp: Date.now(),
+        };
+        this.emit('speaker_identified', payload);
+    };
+    // -------------------------------------------------------------------------
+    // Feature extraction
+    // -------------------------------------------------------------------------
+    /**
+     * Extract a 16-dimensional voiceprint from a raw PCM chunk.
+     *
+     * Feature layout (4 octave bands × 4 features per band):
+     * - Band 0: sub-bass  (0 –  500 Hz equivalent bucket)
+     * - Band 1: bass      (500 – 2000 Hz equivalent bucket)
+     * - Band 2: mid       (2000 – 4000 Hz equivalent bucket)
+     * - Band 3: high      (4000 Hz+ equivalent bucket)
+     *
+     * For each band the following statistics are computed:
+     * - [0] RMS energy
+     * - [1] Spectral centroid (normalised to band range)
+     * - [2] Zero-crossing rate
+     * - [3] Delta energy (mean absolute frame-to-frame change)
+     *
+     * This is a placeholder implementation suitable for demos and testing.
+     * Replace with an ONNX x-vector model for production accuracy.
+     *
+     * @param chunk - Float32 PCM audio data.
+     * @returns 16-dimensional embedding vector.
+     */
+    extractSimpleEmbedding(chunk) {
+        const features = new Float32Array(FEATURE_DIMS);
+        const n = chunk.length;
+        if (n === 0)
+            return features;
+        // Split the chunk index range into OCTAVE_BANDS equal bands.
+        const bandSize = Math.ceil(n / OCTAVE_BANDS);
+        for (let band = 0; band < OCTAVE_BANDS; band++) {
+            const start = band * bandSize;
+            const end = Math.min(start + bandSize, n);
+            const bandLen = end - start;
+            if (bandLen === 0)
+                continue;
+            // --- RMS energy ---
+            let sumSq = 0;
+            for (let i = start; i < end; i++)
+                sumSq += (chunk[i]) ** 2;
+            const rms = Math.sqrt(sumSq / bandLen);
+            // --- Spectral centroid (weighted mean index, normalised to [0,1]) ---
+            let weightedIdx = 0;
+            let totalAbs = 0;
+            for (let i = start; i < end; i++) {
+                const abs = Math.abs(chunk[i]);
+                weightedIdx += (i - start) * abs;
+                totalAbs += abs;
+            }
+            const centroid = totalAbs > 0 ? weightedIdx / totalAbs / bandLen : 0;
+            // --- Zero-crossing rate ---
+            let zeroCrossings = 0;
+            for (let i = start + 1; i < end; i++) {
+                if ((chunk[i] >= 0) !== (chunk[i - 1] >= 0))
+                    zeroCrossings++;
+            }
+            const zcr = zeroCrossings / (bandLen - 1);
+            // --- Delta energy (mean |diff| between consecutive samples) ---
+            let deltaSum = 0;
+            for (let i = start + 1; i < end; i++) {
+                deltaSum += Math.abs(chunk[i] - chunk[i - 1]);
+            }
+            const delta = deltaSum / (bandLen - 1);
+            // Write into the feature vector.
+            const base = band * DIMS_PER_BAND;
+            features[base + 0] = rms;
+            features[base + 1] = centroid;
+            features[base + 2] = zcr;
+            features[base + 3] = delta;
+        }
+        return features;
+    }
+}
+//# sourceMappingURL=LocalDiarizationBackend.js.map

package/dist/LocalDiarizationBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalDiarizationBackend.js","sourceRoot":"","sources":["../src/LocalDiarizationBackend.ts"],"names":[],"mappings":"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"}

package/dist/ProviderDiarizationBackend.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file ProviderDiarizationBackend.ts
+ * @description Thin adapter that extracts speaker labels from STT provider
+ * transcript events containing word-level speaker annotations.
+ *
+ * Many cloud STT providers (Deepgram, AssemblyAI, …) support native
+ * diarization that produces a `speaker` label on each word in the transcript.
+ * This backend consumes those events and re-emits them as
+ * {@link DiarizedSegment} objects without any additional compute.
+ *
+ * @module diarization/ProviderDiarizationBackend
+ */
+import type { TranscriptEvent, DiarizedSegment } from './types.js';
+/**
+ * Extracts speaker labels from word-level STT results.
+ *
+ * Stateless — each call to {@link pushTranscriptEvent} is independent.  The
+ * caller is responsible for any session-level bookkeeping.
+ *
+ * @example
+ * ```ts
+ * const backend = new ProviderDiarizationBackend();
+ * sttSession.on('transcript', (event) => {
+ *   const segment = backend.pushTranscriptEvent(event);
+ *   if (segment) console.log(segment.speakerId, segment.text);
+ * });
+ * ```
+ */
+export declare class ProviderDiarizationBackend {
+    /**
+     * Process a transcript event and extract the dominant speaker label.
+     *
+     * The dominant speaker is determined by majority vote across the word-level
+     * `speaker` annotations.  If no words carry speaker labels, `null` is
+     * returned.
+     *
+     * For final transcripts (`isFinal: true`) the returned segment covers the
+     * full utterance.  For interim transcripts the segment is a best-effort
+     * approximation based on the current words.
+     *
+     * @param event - Transcript event from an STT provider session.
+     * @returns A {@link DiarizedSegment} if speaker information is available,
+     *   or `null` if the event lacks word-level speaker labels.
+     */
+    pushTranscriptEvent(event: TranscriptEvent): DiarizedSegment | null;
+    /**
+     * Determine the most-frequently-occurring speaker label among a set of words.
+     *
+     * @param words - Words that all have a defined `speaker` property.
+     * @returns The dominant `speaker` label.
+     */
+    private dominantSpeaker;
+}
+//# sourceMappingURL=ProviderDiarizationBackend.d.ts.map

package/dist/ProviderDiarizationBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderDiarizationBackend.d.ts","sourceRoot":"","sources":["../src/ProviderDiarizationBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAkB,MAAM,YAAY,CAAC;AAMnF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,0BAA0B;IAKrC;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,GAAG,IAAI;IAsCnE;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAoBxB"}

package/dist/ProviderDiarizationBackend.js

@@ -0,0 +1,101 @@
+/**
+ * @file ProviderDiarizationBackend.ts
+ * @description Thin adapter that extracts speaker labels from STT provider
+ * transcript events containing word-level speaker annotations.
+ *
+ * Many cloud STT providers (Deepgram, AssemblyAI, …) support native
+ * diarization that produces a `speaker` label on each word in the transcript.
+ * This backend consumes those events and re-emits them as
+ * {@link DiarizedSegment} objects without any additional compute.
+ *
+ * @module diarization/ProviderDiarizationBackend
+ */
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * Extracts speaker labels from word-level STT results.
+ *
+ * Stateless — each call to {@link pushTranscriptEvent} is independent.  The
+ * caller is responsible for any session-level bookkeeping.
+ *
+ * @example
+ * ```ts
+ * const backend = new ProviderDiarizationBackend();
+ * sttSession.on('transcript', (event) => {
+ *   const segment = backend.pushTranscriptEvent(event);
+ *   if (segment) console.log(segment.speakerId, segment.text);
+ * });
+ * ```
+ */
+export class ProviderDiarizationBackend {
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Process a transcript event and extract the dominant speaker label.
+     *
+     * The dominant speaker is determined by majority vote across the word-level
+     * `speaker` annotations.  If no words carry speaker labels, `null` is
+     * returned.
+     *
+     * For final transcripts (`isFinal: true`) the returned segment covers the
+     * full utterance.  For interim transcripts the segment is a best-effort
+     * approximation based on the current words.
+     *
+     * @param event - Transcript event from an STT provider session.
+     * @returns A {@link DiarizedSegment} if speaker information is available,
+     *   or `null` if the event lacks word-level speaker labels.
+     */
+    pushTranscriptEvent(event) {
+        const words = event.words;
+        if (!words || words.length === 0) {
+            return null;
+        }
+        // Collect all words that have a speaker label.
+        const labelledWords = words.filter((w) => w.speaker !== undefined && w.speaker !== '');
+        if (labelledWords.length === 0) {
+            return null;
+        }
+        // Majority-vote for the dominant speaker in this transcript event.
+        const speakerId = this.dominantSpeaker(labelledWords);
+        // Derive segment boundaries from word timestamps (seconds → milliseconds).
+        const firstWord = labelledWords[0];
+        const lastWord = labelledWords[labelledWords.length - 1];
+        // Average per-word confidence (default 1 if not present).
+        const avgConfidence = labelledWords.reduce((sum, w) => sum + (w.confidence ?? 1), 0) / labelledWords.length;
+        return {
+            speakerId,
+            text: event.text,
+            startMs: Math.round(firstWord.start * 1000),
+            endMs: Math.round(lastWord.end * 1000),
+            confidence: avgConfidence,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Internal helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Determine the most-frequently-occurring speaker label among a set of words.
+     *
+     * @param words - Words that all have a defined `speaker` property.
+     * @returns The dominant `speaker` label.
+     */
+    dominantSpeaker(words) {
+        const counts = new Map();
+        for (const word of words) {
+            const label = word.speaker;
+            counts.set(label, (counts.get(label) ?? 0) + 1);
+        }
+        let best = words[0].speaker;
+        let bestCount = 0;
+        for (const [label, count] of counts) {
+            if (count > bestCount) {
+                bestCount = count;
+                best = label;
+            }
+        }
+        return best;
+    }
+}
+//# sourceMappingURL=ProviderDiarizationBackend.js.map

package/dist/ProviderDiarizationBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderDiarizationBackend.js","sourceRoot":"","sources":["../src/ProviderDiarizationBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,0BAA0B;IACrC,4EAA4E;IAC5E,aAAa;IACb,4EAA4E;IAE5E;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,KAAsB;QACxC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAE1B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,+CAA+C;QAC/C,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;QAEvF,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mEAAmE;QACnE,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC;QAEtD,2EAA2E;QAC3E,MAAM,SAAS,GAAG,aAAa,CAAC,CAAC,CAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,aAAa,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;QAE1D,0DAA0D;QAC1D,MAAM,aAAa,GACjB,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC;QAExF,OAAO;YACL,SAAS;YACT,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC;YAC3C,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,GAAG,IAAI,CAAC;YACtC,UAAU,EAAE,aAAa;SAC1B,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,mBAAmB;IACnB,4EAA4E;IAE5E;;;;;OAKG;IACK,eAAe,CAAC,KAAuB;QAC7C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QAEzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAQ,CAAC;YAC5B,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,OAAQ,CAAC;QAC9B,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;YACpC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;gBACtB,SAAS,GAAG,KAAK,CAAC;gBAClB,IAAI,GAAG,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/SlidingWindowExtractor.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file SlidingWindowExtractor.ts
+ * @description Ring buffer that accumulates audio frames into fixed-size chunks
+ * with configurable overlap, tuned for diarization (1.5 s chunks, 0.5 s overlap).
+ *
+ * Mirrors the design of `SlidingWindowBuffer` from the Whisper STT pack but
+ * operates on {@link AudioFrame} objects rather than raw sample arrays, and
+ * uses millisecond-based chunk/overlap sizes for a friendlier API.
+ *
+ * @module diarization/SlidingWindowExtractor
+ */
+import { EventEmitter } from 'node:events';
+import type { AudioFrame } from './types.js';
+/** Event map for {@link SlidingWindowExtractor}. */
+export interface SlidingWindowExtractorEvents {
+    /** Emitted when a complete chunk of audio samples is ready. */
+    chunk_ready: [chunk: Float32Array];
+}
+/**
+ * Sliding-window audio extractor for the diarization pipeline.
+ *
+ * Accepts {@link AudioFrame} objects pushed by the voice pipeline, accumulates
+ * samples in an internal ring buffer, and emits `'chunk_ready'` events when a
+ * full chunk is available.  The last `overlapSamples` of each chunk are kept
+ * as context at the head of the next chunk.
+ *
+ * @example
+ * ```ts
+ * const extractor = new SlidingWindowExtractor(1500, 500, 16000);
+ * extractor.on('chunk_ready', (chunk) => processChunk(chunk));
+ * microphone.on('frame', (f) => extractor.pushAudio(f));
+ * ```
+ */
+export declare class SlidingWindowExtractor extends EventEmitter {
+    private readonly chunkSizeMs;
+    private readonly overlapMs;
+    private readonly sampleRate;
+    /** Internal sample store.  Sized to {@link chunkSizeSamples}. */
+    private buffer;
+    /** Current write position within {@link buffer}. */
+    private writePos;
+    /** Number of samples per emitted chunk. */
+    private readonly chunkSizeSamples;
+    /** Number of overlap samples carried forward to the next chunk. */
+    private readonly overlapSamples;
+    /**
+     * @param chunkSizeMs - Duration of each emitted chunk in milliseconds.
+     *   @defaultValue 1500
+     * @param overlapMs - Overlap between consecutive chunks in milliseconds.
+     *   Must be less than `chunkSizeMs`.
+     *   @defaultValue 500
+     * @param sampleRate - Expected audio sample rate in Hz.
+     *   @defaultValue 16000
+     */
+    constructor(chunkSizeMs?: number, overlapMs?: number, sampleRate?: number);
+    /**
+     * Push an audio frame into the extractor.
+     *
+     * Samples are appended to the internal ring buffer.  When the buffer fills
+     * to `chunkSizeSamples`, a `'chunk_ready'` event is emitted and the overlap
+     * region is copied to the head of the buffer for the next chunk.
+     *
+     * @param frame - Audio frame to append.
+     */
+    pushAudio(frame: AudioFrame): void;
+    /**
+     * Flush any remaining samples as a final partial chunk.
+     *
+     * If the buffer is empty this is a no-op.
+     */
+    flush(): void;
+    /**
+     * Clear the buffer without emitting a chunk.
+     */
+    reset(): void;
+    /** Number of samples currently held in the buffer. */
+    get bufferedSamples(): number;
+    /**
+     * Append raw PCM samples and emit chunks as they fill.
+     *
+     * @param samples - Float32 PCM data to append.
+     */
+    private pushSamples;
+}
+//# sourceMappingURL=SlidingWindowExtractor.d.ts.map

package/dist/SlidingWindowExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlidingWindowExtractor.d.ts","sourceRoot":"","sources":["../src/SlidingWindowExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,oDAAoD;AACpD,MAAM,WAAW,4BAA4B;IAC3C,+DAA+D;IAC/D,WAAW,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;CACpC;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IAmCpD,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAhC7B,iEAAiE;IACjE,OAAO,CAAC,MAAM,CAAe;IAE7B,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAK;IAMrB,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAMxC;;;;;;;;OAQG;gBAEgB,WAAW,GAAE,MAAa,EAC1B,SAAS,GAAE,MAAY,EACvB,UAAU,GAAE,MAAe;IAoB9C;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAIlC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,KAAK,IAAI,IAAI;IASb,sDAAsD;IACtD,IAAI,eAAe,IAAI,MAAM,CAE5B;IAMD;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAsBpB"}

package/dist/SlidingWindowExtractor.js

@@ -0,0 +1,140 @@
+/**
+ * @file SlidingWindowExtractor.ts
+ * @description Ring buffer that accumulates audio frames into fixed-size chunks
+ * with configurable overlap, tuned for diarization (1.5 s chunks, 0.5 s overlap).
+ *
+ * Mirrors the design of `SlidingWindowBuffer` from the Whisper STT pack but
+ * operates on {@link AudioFrame} objects rather than raw sample arrays, and
+ * uses millisecond-based chunk/overlap sizes for a friendlier API.
+ *
+ * @module diarization/SlidingWindowExtractor
+ */
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * Sliding-window audio extractor for the diarization pipeline.
+ *
+ * Accepts {@link AudioFrame} objects pushed by the voice pipeline, accumulates
+ * samples in an internal ring buffer, and emits `'chunk_ready'` events when a
+ * full chunk is available.  The last `overlapSamples` of each chunk are kept
+ * as context at the head of the next chunk.
+ *
+ * @example
+ * ```ts
+ * const extractor = new SlidingWindowExtractor(1500, 500, 16000);
+ * extractor.on('chunk_ready', (chunk) => processChunk(chunk));
+ * microphone.on('frame', (f) => extractor.pushAudio(f));
+ * ```
+ */
+export class SlidingWindowExtractor extends EventEmitter {
+    chunkSizeMs;
+    overlapMs;
+    sampleRate;
+    // -------------------------------------------------------------------------
+    // Private state
+    // -------------------------------------------------------------------------
+    /** Internal sample store.  Sized to {@link chunkSizeSamples}. */
+    buffer;
+    /** Current write position within {@link buffer}. */
+    writePos = 0;
+    // -------------------------------------------------------------------------
+    // Computed dimensions (from ms → samples)
+    // -------------------------------------------------------------------------
+    /** Number of samples per emitted chunk. */
+    chunkSizeSamples;
+    /** Number of overlap samples carried forward to the next chunk. */
+    overlapSamples;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param chunkSizeMs - Duration of each emitted chunk in milliseconds.
+     *   @defaultValue 1500
+     * @param overlapMs - Overlap between consecutive chunks in milliseconds.
+     *   Must be less than `chunkSizeMs`.
+     *   @defaultValue 500
+     * @param sampleRate - Expected audio sample rate in Hz.
+     *   @defaultValue 16000
+     */
+    constructor(chunkSizeMs = 1500, overlapMs = 500, sampleRate = 16_000) {
+        super();
+        this.chunkSizeMs = chunkSizeMs;
+        this.overlapMs = overlapMs;
+        this.sampleRate = sampleRate;
+        this.chunkSizeSamples = Math.round((chunkSizeMs / 1000) * sampleRate);
+        this.overlapSamples = Math.round((overlapMs / 1000) * sampleRate);
+        if (this.overlapSamples >= this.chunkSizeSamples) {
+            throw new RangeError(`overlapMs (${overlapMs}) must result in fewer samples than chunkSizeMs (${chunkSizeMs})`);
+        }
+        this.buffer = new Float32Array(this.chunkSizeSamples);
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Push an audio frame into the extractor.
+     *
+     * Samples are appended to the internal ring buffer.  When the buffer fills
+     * to `chunkSizeSamples`, a `'chunk_ready'` event is emitted and the overlap
+     * region is copied to the head of the buffer for the next chunk.
+     *
+     * @param frame - Audio frame to append.
+     */
+    pushAudio(frame) {
+        this.pushSamples(frame.samples);
+    }
+    /**
+     * Flush any remaining samples as a final partial chunk.
+     *
+     * If the buffer is empty this is a no-op.
+     */
+    flush() {
+        if (this.writePos === 0)
+            return;
+        this.emit('chunk_ready', this.buffer.slice(0, this.writePos));
+        this.reset();
+    }
+    /**
+     * Clear the buffer without emitting a chunk.
+     */
+    reset() {
+        this.buffer = new Float32Array(this.chunkSizeSamples);
+        this.writePos = 0;
+    }
+    // -------------------------------------------------------------------------
+    // Accessors
+    // -------------------------------------------------------------------------
+    /** Number of samples currently held in the buffer. */
+    get bufferedSamples() {
+        return this.writePos;
+    }
+    // -------------------------------------------------------------------------
+    // Internal helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Append raw PCM samples and emit chunks as they fill.
+     *
+     * @param samples - Float32 PCM data to append.
+     */
+    pushSamples(samples) {
+        let srcOffset = 0;
+        while (srcOffset < samples.length) {
+            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) {
+                // Emit a copy — the buffer is reused for the next chunk.
+                this.emit('chunk_ready', this.buffer.slice());
+                // Copy the overlap region to the start of the buffer.
+                const overlapStart = this.chunkSizeSamples - this.overlapSamples;
+                this.buffer.copyWithin(0, overlapStart, this.chunkSizeSamples);
+                this.writePos = this.overlapSamples;
+            }
+        }
+    }
+}
+//# sourceMappingURL=SlidingWindowExtractor.js.map