@framers/agentos-ext-diarization 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,71 @@
+---
+name: diarization
+description: Speaker diarization — identifies and tracks who is speaking at each moment in an audio stream
+category: voice
+---
+
+# Diarization Extension Pack
+
+Speaker diarization for the AgentOS voice pipeline.  Supports two modes:
+
+1. **Provider-delegated** — extracts speaker labels from STT provider word-level results (e.g. Deepgram with `diarize: true`).  Zero additional compute, no voiceprint model needed.
+2. **Local clustering** — uses a sliding-window spectral-centroid voiceprint with agglomerative clustering, fully offline.  An ONNX x-vector model can be plugged in later without API changes.
+
+## Setup
+
+No API key required for local mode.  For provider mode, enable diarization on your STT provider (e.g. `providerOptions.diarize: true` on the Deepgram STT pack).
+
+## Configuration
+
+```json
+{
+  "voice": {
+    "diarization": "local"
+  }
+}
+```
+
+To use provider-delegated diarization:
+
+```json
+{
+  "voice": {
+    "diarization": "provider",
+    "stt": "deepgram",
+    "providerOptions": { "diarize": true }
+  }
+}
+```
+
+### Speaker enrollment (optional)
+
+Pre-register known speakers so the engine can label them by name instead of `Speaker_N`:
+
+```ts
+await session.enrollSpeaker('Alice', aliceVoiceprintFloat32Array);
+await session.enrollSpeaker('Bob', bobVoiceprintFloat32Array);
+```
+
+## Events
+
+| Event                 | Payload              | Description                                              |
+|-----------------------|----------------------|----------------------------------------------------------|
+| `speaker_identified`  | `SpeakerIdentified`  | Emitted whenever the active speaker label changes        |
+| `segment_ready`       | `DiarizedSegment`    | A labelled audio or transcript segment is ready          |
+| `error`               | `Error`              | Unrecoverable diarization error                          |
+| `close`               | —                    | Session fully terminated                                 |
+
+## Local backend feature extraction
+
+The built-in feature extractor computes a 16-dimensional vector per 1.5 s window (0.5 s overlap):
+
+- Dimensions 0–3: octave-band RMS energy (sub-bass, bass, mid, high)
+- Dimensions 4–7: spectral centroid per octave band
+- Dimensions 8–11: zero-crossing rate per octave band
+- Dimensions 12–15: delta energy (frame-to-frame change) per octave band
+
+This is intentionally lightweight.  Replace `LocalDiarizationBackend.extractSimpleEmbedding()` with an ONNX x-vector model for production-quality voiceprints.
+
+## Clustering
+
+`ClusteringStrategy` runs agglomerative merging whenever the centroid count exceeds `expectedSpeakers`.  Centroids with cosine similarity above `mergeThreshold` (default 0.85) are collapsed into a single speaker identity.

package/dist/ClusteringStrategy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file ClusteringStrategy.ts
+ * @description Agglomerative clustering to merge drifted speaker centroids.
+ *
+ * Over the course of a long session, a single speaker's vocal characteristics
+ * may drift enough that two separate centroids are created for them.
+ * {@link ClusteringStrategy.mergeClusters} detects this by computing pairwise
+ * cosine similarity between all centroids and iteratively merging the closest
+ * pair until either no pair exceeds the merge threshold or the centroid count
+ * equals `expectedSpeakers`.
+ *
+ * @module diarization/ClusteringStrategy
+ */
+/**
+ * Agglomerative speaker-centroid merging strategy.
+ *
+ * This is an optional post-processing step applied by {@link DiarizationSession}
+ * when the number of tracked centroids exceeds the expected speaker count.
+ *
+ * @example
+ * ```ts
+ * const strategy = new ClusteringStrategy(0.85);
+ * const mapping = strategy.mergeClusters(cache.centroids, 2);
+ * // mapping: Map<oldId, canonicalId>
+ * ```
+ */
+export declare class ClusteringStrategy {
+    private readonly mergeThreshold;
+    /**
+     * @param mergeThreshold - Minimum cosine similarity between two centroids
+     *   for them to be considered the same speaker and merged.
+     *   @defaultValue 0.85
+     */
+    constructor(mergeThreshold?: number);
+    /**
+     * Identify centroid pairs that should be merged and return a renaming map.
+     *
+     * The algorithm:
+     * 1. Compute all pairwise cosine similarities.
+     * 2. If `expectedSpeakers` is set and the current count exceeds it, merge
+     *    the closest pair regardless of the threshold.
+     * 3. Otherwise merge pairs that exceed `mergeThreshold`.
+     * 4. Repeat until no further merges are possible or the count matches
+     *    `expectedSpeakers`.
+     *
+     * The returned `Map<string, string>` maps every old centroid ID that was
+     * subsumed into a canonical ID.  IDs that were not merged are not present in
+     * the map.  Callers should rename all occurrences of a key to its value.
+     *
+     * @param centroids - Current centroid snapshot (id → embedding).
+     * @param expectedSpeakers - Optional upper bound on speaker count.
+     * @returns Rename map: `oldId → canonicalId`.
+     */
+    mergeClusters(centroids: Map<string, Float32Array>, expectedSpeakers?: number): Map<string, string>;
+}
+//# sourceMappingURL=ClusteringStrategy.d.ts.map

package/dist/ClusteringStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusteringStrategy.d.ts","sourceRoot":"","sources":["../src/ClusteringStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAkB;IAUjB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAL3C;;;;OAIG;gBAC0B,cAAc,GAAE,MAAa;IAM1D;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CACX,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EACpC,gBAAgB,CAAC,EAAE,MAAM,GACxB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAmEvB"}

package/dist/ClusteringStrategy.js

@@ -0,0 +1,123 @@
+/**
+ * @file ClusteringStrategy.ts
+ * @description Agglomerative clustering to merge drifted speaker centroids.
+ *
+ * Over the course of a long session, a single speaker's vocal characteristics
+ * may drift enough that two separate centroids are created for them.
+ * {@link ClusteringStrategy.mergeClusters} detects this by computing pairwise
+ * cosine similarity between all centroids and iteratively merging the closest
+ * pair until either no pair exceeds the merge threshold or the centroid count
+ * equals `expectedSpeakers`.
+ *
+ * @module diarization/ClusteringStrategy
+ */
+import { cosineSimilarity } from './SpeakerEmbeddingCache.js';
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * Agglomerative speaker-centroid merging strategy.
+ *
+ * This is an optional post-processing step applied by {@link DiarizationSession}
+ * when the number of tracked centroids exceeds the expected speaker count.
+ *
+ * @example
+ * ```ts
+ * const strategy = new ClusteringStrategy(0.85);
+ * const mapping = strategy.mergeClusters(cache.centroids, 2);
+ * // mapping: Map<oldId, canonicalId>
+ * ```
+ */
+export class ClusteringStrategy {
+    mergeThreshold;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param mergeThreshold - Minimum cosine similarity between two centroids
+     *   for them to be considered the same speaker and merged.
+     *   @defaultValue 0.85
+     */
+    constructor(mergeThreshold = 0.85) {
+        this.mergeThreshold = mergeThreshold;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Identify centroid pairs that should be merged and return a renaming map.
+     *
+     * The algorithm:
+     * 1. Compute all pairwise cosine similarities.
+     * 2. If `expectedSpeakers` is set and the current count exceeds it, merge
+     *    the closest pair regardless of the threshold.
+     * 3. Otherwise merge pairs that exceed `mergeThreshold`.
+     * 4. Repeat until no further merges are possible or the count matches
+     *    `expectedSpeakers`.
+     *
+     * The returned `Map<string, string>` maps every old centroid ID that was
+     * subsumed into a canonical ID.  IDs that were not merged are not present in
+     * the map.  Callers should rename all occurrences of a key to its value.
+     *
+     * @param centroids - Current centroid snapshot (id → embedding).
+     * @param expectedSpeakers - Optional upper bound on speaker count.
+     * @returns Rename map: `oldId → canonicalId`.
+     */
+    mergeClusters(centroids, expectedSpeakers) {
+        // Build a mutable working copy so we can iteratively merge.
+        const working = new Map(centroids);
+        // Accumulated rename mapping.
+        const renameMap = new Map();
+        while (true) {
+            const ids = Array.from(working.keys());
+            const count = ids.length;
+            // Nothing to merge.
+            if (count < 2)
+                break;
+            // Find the closest pair.
+            let bestSim = -Infinity;
+            let bestI = 0;
+            let bestJ = 1;
+            for (let i = 0; i < count; i++) {
+                for (let j = i + 1; j < count; j++) {
+                    const sim = cosineSimilarity(working.get(ids[i]), working.get(ids[j]));
+                    if (sim > bestSim) {
+                        bestSim = sim;
+                        bestI = i;
+                        bestJ = j;
+                    }
+                }
+            }
+            // Decide whether to merge.
+            const shouldMergeDueToThreshold = bestSim >= this.mergeThreshold;
+            const shouldMergeDueToCount = expectedSpeakers !== undefined && count > expectedSpeakers;
+            if (!shouldMergeDueToThreshold && !shouldMergeDueToCount)
+                break;
+            // Merge ids[bestJ] into ids[bestI] (keep the lexicographically earlier
+            // ID as the canonical one for determinism).
+            const keepId = ids[bestI];
+            const dropId = ids[bestJ];
+            // Average the two centroids (equal weight — simple heuristic).
+            const keepEmb = working.get(keepId);
+            const dropEmb = working.get(dropId);
+            const merged = new Float32Array(keepEmb.length);
+            for (let k = 0; k < keepEmb.length; k++) {
+                merged[k] = (keepEmb[k] + dropEmb[k]) / 2;
+            }
+            working.set(keepId, merged);
+            working.delete(dropId);
+            // Record the rename. Chase any existing mappings so the final map is
+            // transitively resolved.
+            renameMap.set(dropId, keepId);
+            // Resolve transitive renames: if dropId was itself a canonical target of
+            // an earlier merge, update those entries to point to keepId.
+            for (const [old, target] of renameMap) {
+                if (target === dropId) {
+                    renameMap.set(old, keepId);
+                }
+            }
+        }
+        return renameMap;
+    }
+}
+//# sourceMappingURL=ClusteringStrategy.js.map

package/dist/ClusteringStrategy.js.map

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

package/dist/DiarizationEngine.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file DiarizationEngine.ts
+ * @description Factory that creates {@link DiarizationSession} instances,
+ * selecting the appropriate backend based on the supplied configuration.
+ *
+ * When a provider backend is requested (`config.backend === 'provider'`), the
+ * engine creates a {@link ProviderDiarizationBackend} and wraps it in a
+ * session.  Otherwise it constructs the full local pipeline:
+ * {@link SlidingWindowExtractor} → {@link LocalDiarizationBackend} →
+ * {@link SpeakerEmbeddingCache}.
+ *
+ * @module diarization/DiarizationEngine
+ */
+import type { IDiarizationEngine, IDiarizationSession, DiarizationConfig } from './types.js';
+/**
+ * Factory for diarization sessions.
+ *
+ * @example
+ * ```ts
+ * const engine = new DiarizationEngine();
+ *
+ * // Local mode (default)
+ * const session = engine.startSession();
+ * session.on('speaker_identified', ({ speakerId }) => console.log(speakerId));
+ *
+ * // Provider mode
+ * const providerSession = engine.startSession({ backend: 'provider' });
+ * sttSession.on('transcript', (e) => providerSession.labelTranscript(e));
+ * ```
+ */
+export declare class DiarizationEngine implements IDiarizationEngine {
+    /**
+     * Create and return a new {@link IDiarizationSession}.
+     *
+     * The backend is selected based on `config.backend`:
+     * - `'provider'` — use {@link ProviderDiarizationBackend}
+     * - `'local'` (default) — use {@link LocalDiarizationBackend} with a fresh
+     *   {@link SpeakerEmbeddingCache} and {@link SlidingWindowExtractor}
+     *
+     * @param config - Optional session configuration.
+     * @returns A ready-to-use {@link DiarizationSession}.
+     */
+    startSession(config?: DiarizationConfig): IDiarizationSession;
+}
+//# sourceMappingURL=DiarizationEngine.d.ts.map

package/dist/DiarizationEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiarizationEngine.d.ts","sourceRoot":"","sources":["../src/DiarizationEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAoB7F;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAK1D;;;;;;;;;;OAUG;IACH,YAAY,CAAC,MAAM,GAAE,iBAAsB,GAAG,mBAAmB;CA2BlE"}

package/dist/DiarizationEngine.js

@@ -0,0 +1,84 @@
+/**
+ * @file DiarizationEngine.ts
+ * @description Factory that creates {@link DiarizationSession} instances,
+ * selecting the appropriate backend based on the supplied configuration.
+ *
+ * When a provider backend is requested (`config.backend === 'provider'`), the
+ * engine creates a {@link ProviderDiarizationBackend} and wraps it in a
+ * session.  Otherwise it constructs the full local pipeline:
+ * {@link SlidingWindowExtractor} → {@link LocalDiarizationBackend} →
+ * {@link SpeakerEmbeddingCache}.
+ *
+ * @module diarization/DiarizationEngine
+ */
+import { DiarizationSession } from './DiarizationSession.js';
+import { SpeakerEmbeddingCache } from './SpeakerEmbeddingCache.js';
+import { SlidingWindowExtractor } from './SlidingWindowExtractor.js';
+import { LocalDiarizationBackend } from './LocalDiarizationBackend.js';
+import { ProviderDiarizationBackend } from './ProviderDiarizationBackend.js';
+// ---------------------------------------------------------------------------
+// Default values
+// ---------------------------------------------------------------------------
+const DEFAULT_SIMILARITY_THRESHOLD = 0.7;
+const DEFAULT_CHUNK_SIZE_MS = 1500;
+const DEFAULT_OVERLAP_MS = 500;
+const DEFAULT_SAMPLE_RATE = 16_000;
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * Factory for diarization sessions.
+ *
+ * @example
+ * ```ts
+ * const engine = new DiarizationEngine();
+ *
+ * // Local mode (default)
+ * const session = engine.startSession();
+ * session.on('speaker_identified', ({ speakerId }) => console.log(speakerId));
+ *
+ * // Provider mode
+ * const providerSession = engine.startSession({ backend: 'provider' });
+ * sttSession.on('transcript', (e) => providerSession.labelTranscript(e));
+ * ```
+ */
+export class DiarizationEngine {
+    // -------------------------------------------------------------------------
+    // IDiarizationEngine implementation
+    // -------------------------------------------------------------------------
+    /**
+     * Create and return a new {@link IDiarizationSession}.
+     *
+     * The backend is selected based on `config.backend`:
+     * - `'provider'` — use {@link ProviderDiarizationBackend}
+     * - `'local'` (default) — use {@link LocalDiarizationBackend} with a fresh
+     *   {@link SpeakerEmbeddingCache} and {@link SlidingWindowExtractor}
+     *
+     * @param config - Optional session configuration.
+     * @returns A ready-to-use {@link DiarizationSession}.
+     */
+    startSession(config = {}) {
+        const backend = config.backend ?? 'local';
+        if (backend === 'provider') {
+            return new DiarizationSession({
+                kind: 'provider',
+                backend: new ProviderDiarizationBackend(),
+            });
+        }
+        // Local mode — wire up the full pipeline.
+        const threshold = config.similarityThreshold ?? DEFAULT_SIMILARITY_THRESHOLD;
+        const chunkSizeMs = config.chunkSizeMs ?? DEFAULT_CHUNK_SIZE_MS;
+        const overlapMs = config.overlapMs ?? DEFAULT_OVERLAP_MS;
+        const sampleRate = config.sampleRate ?? DEFAULT_SAMPLE_RATE;
+        const cache = new SpeakerEmbeddingCache(threshold);
+        const extractor = new SlidingWindowExtractor(chunkSizeMs, overlapMs, sampleRate);
+        const localBackend = new LocalDiarizationBackend(cache, extractor);
+        return new DiarizationSession({
+            kind: 'local',
+            backend: localBackend,
+            cache,
+            extractor,
+        });
+    }
+}
+//# sourceMappingURL=DiarizationEngine.js.map

package/dist/DiarizationEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiarizationEngine.js","sourceRoot":"","sources":["../src/DiarizationEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAE7E,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,4BAA4B,GAAG,GAAG,CAAC;AACzC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AACnC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEnC,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,iBAAiB;IAC5B,4EAA4E;IAC5E,oCAAoC;IACpC,4EAA4E;IAE5E;;;;;;;;;;OAUG;IACH,YAAY,CAAC,SAA4B,EAAE;QACzC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC;QAE1C,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;YAC3B,OAAO,IAAI,kBAAkB,CAAC;gBAC5B,IAAI,EAAE,UAAU;gBAChB,OAAO,EAAE,IAAI,0BAA0B,EAAE;aAC1C,CAAC,CAAC;QACL,CAAC;QAED,0CAA0C;QAC1C,MAAM,SAAS,GAAG,MAAM,CAAC,mBAAmB,IAAI,4BAA4B,CAAC;QAC7E,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,qBAAqB,CAAC;QAChE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,kBAAkB,CAAC;QACzD,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAE5D,MAAM,KAAK,GAAG,IAAI,qBAAqB,CAAC,SAAS,CAAC,CAAC;QACnD,MAAM,SAAS,GAAG,IAAI,sBAAsB,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QACjF,MAAM,YAAY,GAAG,IAAI,uBAAuB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAEnE,OAAO,IAAI,kBAAkB,CAAC;YAC5B,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,YAAY;YACrB,KAAK;YACL,SAAS;SACV,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/DiarizationSession.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @file DiarizationSession.ts
+ * @description Live diarization session that wraps either a
+ * {@link ProviderDiarizationBackend} or a {@link LocalDiarizationBackend}.
+ *
+ * The session implements {@link IDiarizationSession} and bridges the raw audio
+ * / transcript inputs to the selected backend, forwarding `speaker_identified`
+ * and `segment_ready` events to callers.
+ *
+ * @module diarization/DiarizationSession
+ */
+import { EventEmitter } from 'node:events';
+import type { IDiarizationSession, AudioFrame, TranscriptEvent, DiarizedSegment } from './types.js';
+import type { ProviderDiarizationBackend } from './ProviderDiarizationBackend.js';
+import type { LocalDiarizationBackend } from './LocalDiarizationBackend.js';
+import type { SpeakerEmbeddingCache } from './SpeakerEmbeddingCache.js';
+import type { SlidingWindowExtractor } from './SlidingWindowExtractor.js';
+/** Provider-delegated backend descriptor. */
+interface ProviderBackendDescriptor {
+    kind: 'provider';
+    backend: ProviderDiarizationBackend;
+}
+/** Local-clustering backend descriptor. */
+interface LocalBackendDescriptor {
+    kind: 'local';
+    backend: LocalDiarizationBackend;
+    cache: SpeakerEmbeddingCache;
+    extractor: SlidingWindowExtractor;
+}
+type BackendDescriptor = ProviderBackendDescriptor | LocalBackendDescriptor;
+/**
+ * A live diarization session.
+ *
+ * Create instances via {@link DiarizationEngine.startSession} rather than
+ * constructing directly.
+ *
+ * ### Events
+ * - `speaker_identified` — payload: {@link SpeakerIdentified}
+ * - `segment_ready`      — payload: {@link DiarizedSegment}
+ * - `error`              — payload: `Error`
+ * - `close`              — no payload
+ */
+export declare class DiarizationSession extends EventEmitter implements IDiarizationSession {
+    private readonly descriptor;
+    private closed;
+    /** Most recently identified speaker (used for transcript labelling in local mode). */
+    private lastSpeakerId;
+    /**
+     * @param descriptor - Resolved backend descriptor.
+     */
+    constructor(descriptor: BackendDescriptor);
+    /**
+     * Push a raw audio frame into the pipeline.
+     *
+     * In local mode the frame is forwarded to the sliding-window extractor.
+     * In provider mode this is a no-op.
+     *
+     * @param frame - Audio frame to process.
+     */
+    pushAudio(frame: AudioFrame): void;
+    /**
+     * Attach speaker labels to a transcript event and emit a segment.
+     *
+     * In provider mode, word-level speaker labels are extracted directly.  In
+     * local mode, the most recently identified speaker is used.
+     *
+     * @param event - Transcript event from the STT provider.
+     * @returns The labelled {@link DiarizedSegment}, or `null` if no speaker
+     *   information is available yet.
+     */
+    labelTranscript(event: TranscriptEvent): DiarizedSegment | null;
+    /**
+     * Pre-register a known speaker voiceprint.
+     *
+     * Only has effect in local mode.  In provider mode, speaker IDs come
+     * directly from the STT provider and this call is a no-op.
+     *
+     * @param id - Human-readable speaker name.
+     * @param voiceprint - Reference embedding for this speaker.
+     */
+    enrollSpeaker(id: string, voiceprint: Float32Array): void;
+    /**
+     * Terminate the session and release all resources.
+     *
+     * After `close()` no further events are emitted.
+     */
+    close(): void;
+}
+export {};
+//# sourceMappingURL=DiarizationSession.d.ts.map

package/dist/DiarizationSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiarizationSession.d.ts","sourceRoot":"","sources":["../src/DiarizationSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAqB,MAAM,YAAY,CAAC;AACvH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAM1E,6CAA6C;AAC7C,UAAU,yBAAyB;IACjC,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,0BAA0B,CAAC;CACrC;AAED,2CAA2C;AAC3C,UAAU,sBAAsB;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,uBAAuB,CAAC;IACjC,KAAK,EAAE,qBAAqB,CAAC;IAC7B,SAAS,EAAE,sBAAsB,CAAC;CACnC;AAED,KAAK,iBAAiB,GAAG,yBAAyB,GAAG,sBAAsB,CAAC;AAM5E;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,SAAQ,YAAa,YAAW,mBAAmB;IAiBrE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAZvC,OAAO,CAAC,MAAM,CAAS;IAEvB,sFAAsF;IACtF,OAAO,CAAC,aAAa,CAAuB;IAM5C;;OAEG;gBAC0B,UAAU,EAAE,iBAAiB;IAkB1D;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IASlC;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,GAAG,IAAI;IA2B/D;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,GAAG,IAAI;IAOzD;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAYd"}

package/dist/DiarizationSession.js

@@ -0,0 +1,139 @@
+/**
+ * @file DiarizationSession.ts
+ * @description Live diarization session that wraps either a
+ * {@link ProviderDiarizationBackend} or a {@link LocalDiarizationBackend}.
+ *
+ * The session implements {@link IDiarizationSession} and bridges the raw audio
+ * / transcript inputs to the selected backend, forwarding `speaker_identified`
+ * and `segment_ready` events to callers.
+ *
+ * @module diarization/DiarizationSession
+ */
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * A live diarization session.
+ *
+ * Create instances via {@link DiarizationEngine.startSession} rather than
+ * constructing directly.
+ *
+ * ### Events
+ * - `speaker_identified` — payload: {@link SpeakerIdentified}
+ * - `segment_ready`      — payload: {@link DiarizedSegment}
+ * - `error`              — payload: `Error`
+ * - `close`              — no payload
+ */
+export class DiarizationSession extends EventEmitter {
+    descriptor;
+    // -------------------------------------------------------------------------
+    // Private state
+    // -------------------------------------------------------------------------
+    closed = false;
+    /** Most recently identified speaker (used for transcript labelling in local mode). */
+    lastSpeakerId = null;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param descriptor - Resolved backend descriptor.
+     */
+    constructor(descriptor) {
+        super();
+        this.descriptor = descriptor;
+        if (descriptor.kind === 'local') {
+            // Forward speaker_identified events from the local backend.
+            descriptor.backend.on('speaker_identified', (payload) => {
+                this.lastSpeakerId = payload.speakerId;
+                this.emit('speaker_identified', payload);
+            });
+            descriptor.backend.start();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // IDiarizationSession implementation
+    // -------------------------------------------------------------------------
+    /**
+     * Push a raw audio frame into the pipeline.
+     *
+     * In local mode the frame is forwarded to the sliding-window extractor.
+     * In provider mode this is a no-op.
+     *
+     * @param frame - Audio frame to process.
+     */
+    pushAudio(frame) {
+        if (this.closed)
+            return;
+        if (this.descriptor.kind === 'local') {
+            this.descriptor.extractor.pushAudio(frame);
+        }
+        // Provider mode: audio processing happens on the provider side.
+    }
+    /**
+     * Attach speaker labels to a transcript event and emit a segment.
+     *
+     * In provider mode, word-level speaker labels are extracted directly.  In
+     * local mode, the most recently identified speaker is used.
+     *
+     * @param event - Transcript event from the STT provider.
+     * @returns The labelled {@link DiarizedSegment}, or `null` if no speaker
+     *   information is available yet.
+     */
+    labelTranscript(event) {
+        if (this.closed)
+            return null;
+        let segment = null;
+        if (this.descriptor.kind === 'provider') {
+            segment = this.descriptor.backend.pushTranscriptEvent(event);
+        }
+        else {
+            // Local mode — use the last identified speaker.
+            if (this.lastSpeakerId !== null) {
+                segment = {
+                    speakerId: this.lastSpeakerId,
+                    text: event.text,
+                    startMs: event.timestamp,
+                    endMs: event.timestamp + event.text.length * 50, // rough estimate
+                    confidence: 0.7,
+                };
+            }
+        }
+        if (segment) {
+            this.emit('segment_ready', segment);
+        }
+        return segment;
+    }
+    /**
+     * Pre-register a known speaker voiceprint.
+     *
+     * Only has effect in local mode.  In provider mode, speaker IDs come
+     * directly from the STT provider and this call is a no-op.
+     *
+     * @param id - Human-readable speaker name.
+     * @param voiceprint - Reference embedding for this speaker.
+     */
+    enrollSpeaker(id, voiceprint) {
+        if (this.descriptor.kind === 'local') {
+            this.descriptor.cache.enrollSpeaker(id, voiceprint);
+        }
+        // Provider mode: enrolment is handled by the provider; ignore here.
+    }
+    /**
+     * Terminate the session and release all resources.
+     *
+     * After `close()` no further events are emitted.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.descriptor.kind === 'local') {
+            this.descriptor.backend.stop();
+            this.descriptor.extractor.flush();
+        }
+        this.emit('close');
+        this.removeAllListeners();
+    }
+}
+//# sourceMappingURL=DiarizationSession.js.map

package/dist/DiarizationSession.js.map

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