pyannote-cpp-node 0.6.0 → 1.0.0

package/README.md

@@ -1,49 +1,69 @@
 # pyannote-cpp-node
 
-![Platform](https://img.shields.io/badge/platform-macOS-lightgrey)
+![Platform](https://img.shields.io/badge/platform-macOS%20arm64%20%7C%20Windows%20x64-lightgrey)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
 
-Node.js native bindings for integrated Whisper transcription + speaker diarization with speaker-labeled segment output.
+Node.js native bindings for whisper.cpp transcription/VAD plus the pyannote speaker diarization pipeline.
 
 ## Overview
 
-`pyannote-cpp-node` exposes the integrated C++ pipeline that combines Whisper transcription and speaker diarization into a single API.
+`pyannote-cpp-node` is now the single package for both:
 
-Given 16 kHz mono PCM audio (`Float32Array`), it produces cumulative and final transcript segments shaped as:
+- low-level whisper.cpp APIs: `WhisperContext`, `VadContext`, `transcribe`, `transcribeAsync`, `getGpuDevices`
+- high-level pyannote pipeline APIs: `Pipeline`, `PipelineSession`
 
-- speaker label (`SPEAKER_00`, `SPEAKER_01`, ...)
+Platform support:
+
+- `darwin-arm64`: full pipeline (CoreML + Metal acceleration)
+- `win32-x64`: full pipeline (Vulkan GPU + optional OpenVINO acceleration)
+- unsupported: `darwin-x64`, `win32-ia32`, Linux
+
+On both supported pipeline platforms, `getCapabilities().pipeline` is `true`.
+
+The integrated pipeline combines Whisper transcription and optional speaker diarization into a single API (`transcriptionOnly: true` skips diarization).
+
+Given 16 kHz mono PCM audio (`Float32Array`), it produces transcript segments shaped as below. In streaming mode, diarization emits cumulative `segments` events, while `transcriptionOnly: true` emits incremental `segments` events. `finalize()` returns all segments in both modes.
+
+- speaker label (`SPEAKER_00`, `SPEAKER_01`, ...), `"UNKNOWN"` when diarization could not assign a speaker, or empty string (`""`) when `transcriptionOnly` is `true`
 - segment start/duration in seconds
 - segment text
 
-The API supports three modes: **offline** batch processing (`transcribeOffline`), **one-shot** streaming (`transcribe`), and **incremental** streaming (`createSession` + `push`/`finalize`). All heavy operations are asynchronous and run on libuv worker threads.
+The API supports three modes: **offline** batch processing (`transcribeOffline`), **one-shot** streaming (`transcribe`), and **incremental** streaming (`createSession` + `push`/`finalize`). All three modes support transcription-only operation via `transcriptionOnly: true`. All heavy operations are asynchronous and run on libuv worker threads.
 
 ## Features
 
+- Low-level whisper.cpp transcription API compatible with prior `whisper-cpp-node` usage
+- Built-in Silero VAD via `VadContext`
+- GPU device enumeration via `getGpuDevices()`
 - Integrated transcription + diarization in one pipeline
 - Speaker-labeled transcript segments with sentence-level text
 - **Offline mode**: runs Whisper on the full audio at once + offline diarization (fastest for batch)
 - **One-shot mode**: streaming pipeline with automatic chunking
 - **Streaming mode**: incremental push/finalize with real-time `segments` events and `audio` chunk streaming
+- **Transcription-only mode**: skip speaker diarization entirely, only segmentation, VAD, and Whisper models required
 - Deterministic output for the same audio/models/config
 - CoreML-accelerated inference on macOS
 - **Shared model cache**: all models loaded once during `Pipeline.load()`, reused across offline/streaming/session modes
-- **Runtime backend switching**: switch Whisper between GPU-only and CoreML-accelerated without reloading the pipeline
+- **Runtime backend switching**: switch inference backends at runtime on macOS and Windows
 - **Progress reporting**: optional `onProgress` callback for `transcribeOffline` reports Whisper, diarization, and alignment phases
 - **Real-time segment streaming**: optional `onSegment` callback for `transcribeOffline` delivers each Whisper segment (start, end, text) as it's produced — enables live transcript preview and time-based loading bars
 - TypeScript-first API with complete type definitions
 
 ## Requirements
 
-- macOS (Apple Silicon or Intel)
+- macOS Apple Silicon or Windows x64
 - Node.js >= 18
 - Model files:
-  - Segmentation GGUF (`segModelPath`)
-  - Embedding GGUF (`embModelPath`)
-  - PLDA GGUF (`pldaPath`)
-  - Embedding CoreML `.mlpackage` (`coremlPath`)
-  - Segmentation CoreML `.mlpackage` (`segCoremlPath`)
-  - Whisper GGUF (`whisperModelPath`)
+  - Segmentation GGUF (`segModelPath`) — required on all platforms
+  - Embedding GGUF (`embModelPath`) — required unless `transcriptionOnly` is `true`
+  - PLDA GGUF (`pldaPath`) — required unless `transcriptionOnly` is `true`
+  - Whisper GGUF (`whisperModelPath`) — required on all platforms
   - Optional Silero VAD model (`vadModelPath`)
+  - Required backend config (`backend`) with one of: `metal`, `vulkan`, `coreml`, or `openvino-hybrid`
+  - Accelerator-specific paths now live inside `backend`
+    - `backend: { type: 'coreml', segPath, embPath? }` uses CoreML `.mlpackage` assets on macOS
+    - `backend: { type: 'openvino-hybrid', whisperEncoderPath, embPath? }` uses OpenVINO IR `.xml` assets on Windows
+    - `backend: { type: 'metal' }` on macOS and `backend: { type: 'vulkan' }` on Windows do not need extra accelerator paths
 
 ## Installation
 
@@ -57,8 +77,45 @@ pnpm add pyannote-cpp-node
 
 The package installs a platform-specific native addon through `optionalDependencies`.
 
+## Low-Level Quick Start
+
+```typescript
+import {
+  WhisperContext,
+  createVadContext,
+  getCapabilities,
+  transcribeAsync,
+} from 'pyannote-cpp-node';
+
+const capabilities = getCapabilities();
+console.log(capabilities);
+
+const ctx = new WhisperContext({
+  model: './models/ggml-base.en.bin',
+  use_gpu: true,
+  no_prints: true,
+});
+
+const result = await transcribeAsync(ctx, {
+  fname_inp: './audio.wav',
+  language: 'en',
+});
+
+const vad = createVadContext({
+  model: './models/ggml-silero-v6.2.0.bin',
+});
+
+console.log(result.segments);
+console.log(vad.getWindowSamples());
+
+vad.free();
+ctx.free();
+```
+
 ## Quick Start
 
+### macOS (Apple Silicon)
+
 ```typescript
 import { Pipeline } from 'pyannote-cpp-node';
 
@@ -66,15 +123,43 @@ const pipeline = await Pipeline.load({
   segModelPath: './models/segmentation.gguf',
   embModelPath: './models/embedding.gguf',
   pldaPath: './models/plda.gguf',
-  coremlPath: './models/embedding.mlpackage',
-  segCoremlPath: './models/segmentation.mlpackage',
   whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+  backend: {
+    type: 'coreml',
+    segPath: './models/segmentation.mlpackage',
+    embPath: './models/embedding.mlpackage',
+  },
   language: 'en',
 });
 
 const audio = loadAudioAsFloat32Array('./audio-16khz-mono.wav');
+const result = await pipeline.transcribeOffline(audio);
+
+for (const segment of result.segments) {
+  const end = segment.start + segment.duration;
+  console.log(
+    `[${segment.speaker}] ${segment.start.toFixed(2)}-${end.toFixed(2)} ${segment.text.trim()}`
+  );
+}
 
-// Offline mode — fastest for batch processing
+pipeline.close();
+```
+
+### Windows (x64)
+
+```typescript
+import { Pipeline } from 'pyannote-cpp-node';
+
+const pipeline = await Pipeline.load({
+  segModelPath: './models/segmentation.gguf',
+  embModelPath: './models/embedding.gguf',
+  pldaPath: './models/plda.gguf',
+  whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+  language: 'en',
+  backend: { type: 'vulkan' },
+});
+
+const audio = loadAudioAsFloat32Array('./audio-16khz-mono.wav');
 const result = await pipeline.transcribeOffline(audio);
 
 for (const segment of result.segments) {
@@ -87,31 +172,86 @@ for (const segment of result.segments) {
 pipeline.close();
 ```
 
+To use the Windows OpenVINO hybrid path instead, pass the OpenVINO assets through `backend`:
+
+```typescript
+const pipeline = await Pipeline.load({
+  segModelPath: './models/segmentation.gguf',
+  embModelPath: './models/embedding.gguf',
+  pldaPath: './models/plda.gguf',
+  whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+  backend: {
+    type: 'openvino-hybrid',
+    whisperEncoderPath: './models/ggml-large-v3-turbo-encoder-openvino.xml',
+    embPath: './models/embedding-openvino.xml',
+  },
+});
+```
+
+### Transcription-only mode
+
+```typescript
+const macPipeline = await Pipeline.load({
+  segModelPath: './models/segmentation.gguf',
+  whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+  language: 'en',
+  transcriptionOnly: true,
+  backend: {
+    type: 'coreml',
+    segPath: './models/segmentation.mlpackage',
+  },
+});
+
+const windowsPipeline = await Pipeline.load({
+  segModelPath: './models/segmentation.gguf',
+  whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+  language: 'en',
+  transcriptionOnly: true,
+  backend: { type: 'vulkan' },
+});
+
+const result = await macPipeline.transcribe(audio);
+
+for (const segment of result.segments) {
+  const end = segment.start + segment.duration;
+  // No speaker label - segment.speaker is empty string
+  console.log(`${segment.start.toFixed(2)}-${end.toFixed(2)} ${segment.text.trim()}`);
+}
+
+macPipeline.close();
+windowsPipeline.close();
+```
+
 ## API Reference
 
 ### `Pipeline`
 
 ```typescript
 class Pipeline {
-  static async load(config: ModelConfig): Promise<Pipeline>;
+  static async load(config: PipelineConfig): Promise<Pipeline>;
   async transcribeOffline(audio: Float32Array, onProgress?: (phase: number, progress: number) => void, onSegment?: (start: number, end: number, text: string) => void): Promise<TranscriptionResult>;
   async transcribe(audio: Float32Array): Promise<TranscriptionResult>;
   setLanguage(language: string): void;
   setDecodeOptions(options: DecodeOptions): void;
   createSession(): PipelineSession;
-  async setUseCoreml(useCoreml: boolean): Promise<void>;
+  async setExecutionBackend(options: BackendConfig): Promise<void>;
   close(): void;
   get isClosed(): boolean;
 }
 ```
 
-#### `static async load(config: ModelConfig): Promise<Pipeline>`
+#### `static async load(config: PipelineConfig): Promise<Pipeline>`
+
+Validates model paths and loads all models into a shared cache on a background thread. The accelerator assets are selected by `config.backend`, which is required and has no default. On macOS, `backend: { type: 'coreml', ... }` loads CoreML segmentation and embedding assets, while `backend: { type: 'metal' }` uses Metal. On Windows x64, `backend: { type: 'vulkan' }` loads the Vulkan path, and `backend: { type: 'openvino-hybrid', ... }` also loads OpenVINO IR models for the Whisper encoder and embedding model. When `transcriptionOnly` is `true`, embedding, PLDA, and embedding-specific backend assets are not loaded. Models are loaded once and reused across all subsequent `transcribe()`, `transcribeOffline()`, and `createSession()` calls. Models are freed only when `close()` is called.
 
-Validates model paths and loads all models (Whisper, CoreML segmentation/embedding, PLDA, and optionally VAD) into a shared cache on a background thread. Models are loaded once and reused across all subsequent `transcribe()`, `transcribeOffline()`, and `createSession()` calls — no redundant loading occurs when switching between modes. Models are freed only when `close()` is called.
+- `backend` is required in every `Pipeline.load()` call
+- `coreml` requires `segPath`, and `embPath` unless `transcriptionOnly` is `true`
+- `openvino-hybrid` requires `whisperEncoderPath`, and `embPath` unless `transcriptionOnly` is `true`
+- `metal` and `vulkan` do not require extra accelerator model paths
 
 #### `async transcribeOffline(audio: Float32Array, onProgress?, onSegment?): Promise<TranscriptionResult>`
 
-Runs Whisper on the **entire** audio buffer in a single `whisper_full()` call, then runs offline diarization and WhisperX-style speaker alignment. This is the fastest mode for batch processing — no streaming infrastructure is involved.
+Runs Whisper on the **entire** audio buffer in a single `whisper_full()` call, then runs offline diarization and WhisperX-style speaker alignment. In transcription-only mode, diarization and speaker alignment are skipped, and segments have an empty `speaker` field. This is the fastest mode for batch processing — no streaming infrastructure is involved.
 
 The optional `onProgress` callback receives `(phase, progress)` updates:
 
@@ -153,7 +293,7 @@ const result = await pipeline.transcribeOffline(
 
 #### `async transcribe(audio: Float32Array): Promise<TranscriptionResult>`
 
-Runs one-shot transcription + diarization using the streaming pipeline internally (pushes 1-second chunks then finalizes).
+Runs one-shot transcription (+ diarization unless `transcriptionOnly` is set) using the streaming pipeline internally (pushes 1-second chunks then finalizes).
 
 #### `setLanguage(language: string): void`
 
@@ -164,28 +304,62 @@ Updates the Whisper decode language for subsequent `transcribe()` calls. This is
 Updates one or more Whisper decode options for subsequent `transcribe()` calls. Only the fields you pass are changed; others retain their current values. See `DecodeOptions` for available fields.
 
 
-#### `async setUseCoreml(useCoreml: boolean): Promise<void>`
+#### `async setExecutionBackend(options: BackendConfig): Promise<void>`
 
-Switches the Whisper inference backend between GPU-only (`false`) and GPU+CoreML (`true`) at runtime. The method reloads the Whisper context on a background thread with the new `use_coreml` setting. The promise resolves when the new context is ready.
+Switches the inference backend at runtime. Tears down and reloads the entire model cache with the new backend configuration. The promise resolves when the new models are ready.
 
-- If the requested mode matches the current mode, returns immediately (no reload).
-- Throws if the pipeline is closed, busy, or models are not loaded.
-- After switching, all subsequent `transcribe()`, `transcribeOffline()`, and streaming session calls use the new backend.
+- **macOS**: supports `metal` and `coreml`
+- **Windows**: supports `vulkan` and `openvino-hybrid`
+
+Pass one of these `BackendConfig` variants:
 
 ```typescript
-// Start with GPU-only Whisper
-const pipeline = await Pipeline.load({
-  ...modelPaths,
-  useCoreml: false,
+type BackendConfig =
+  | { type: 'metal'; gpuDevice?: number; flashAttn?: boolean }
+  | { type: 'vulkan'; gpuDevice?: number; flashAttn?: boolean }
+  | {
+      type: 'coreml';
+      gpuDevice?: number;
+      flashAttn?: boolean;
+      segPath: string;
+      embPath?: string;
+      whisperEncoderPath?: string;
+    }
+  | {
+      type: 'openvino-hybrid';
+      gpuDevice?: number;
+      flashAttn?: boolean;
+      whisperEncoderPath: string;
+      embPath?: string;
+      openvinoDevice?: string;
+      openvinoCacheDir?: string;
+    };
+```
+
+> **Warning**: This is a heavy operation (~5-6s on Intel iGPU). It fully tears down and rebuilds the model cache. Treat it as a one-time configuration change, not something to call in a loop. See [Warnings and Known Issues](#warnings-and-known-issues) for Intel iGPU limitations.
+
+```typescript
+// macOS: switch to Metal
+await pipeline.setExecutionBackend({ type: 'metal' });
+
+// macOS: switch to CoreML
+await pipeline.setExecutionBackend({
+  type: 'coreml',
+  segPath: './models/segmentation.mlpackage',
+  embPath: './models/embedding.mlpackage',
 });
 
-// Switch to CoreML-accelerated Whisper at runtime
-await pipeline.setUseCoreml(true);
-const result = await pipeline.transcribeOffline(audio);
+// Windows: switch to OpenVINO hybrid
+await pipeline.setExecutionBackend({
+  type: 'openvino-hybrid',
+  whisperEncoderPath: './models/ggml-large-v3-turbo-encoder-openvino.xml',
+  embPath: './models/embedding-openvino.xml',
+});
 
-// Switch back to GPU-only
-await pipeline.setUseCoreml(false);
+// Windows: switch back to Vulkan
+await pipeline.setExecutionBackend({ type: 'vulkan' });
 ```
+
 #### `createSession(): PipelineSession`
 
 Creates an independent streaming session for incremental processing.
@@ -242,7 +416,7 @@ Updates one or more Whisper decode options on the live streaming session. Takes
 
 #### `async finalize(): Promise<TranscriptionResult>`
 
-Flushes all stages, runs final recluster + alignment, and returns the definitive result.
+Flushes all stages, runs final recluster + alignment, and returns the definitive result. `finalize()` always returns all accumulated segments regardless of mode. In diarization mode this is the final re-aligned output, and in transcription-only mode this is the union of all incremental `segments` emissions.
 
 ```typescript
 type TranscriptionResult = {
@@ -262,11 +436,30 @@ Returns `true` after `close()`.
 
 #### Event: `'segments'`
 
-Emitted after each Whisper transcription result with the latest cumulative aligned output.
+Emitted after each Whisper transcription result. Behavior depends on mode:
+
+- With diarization (default): each emission contains all segments re-aligned against the latest speaker clustering. Earlier segments may get updated speaker labels as more data arrives. The final emission after `finalize()` is the definitive output.
+- With `transcriptionOnly: true`: each emission contains only the new segments from the latest Whisper result. Earlier segments never change, so incremental delivery is safe. Accumulate across emissions to build the full transcript.
 
 ```typescript
+// With diarization (default): cumulative, re-aligned output
 session.on('segments', (segments: AlignedSegment[]) => {
-  // `segments` contains the latest cumulative speaker-labeled transcript
+  // `segments` contains the latest full speaker-labeled transcript so far
+  const latest = segments[segments.length - 1];
+  if (latest) {
+    const end = latest.start + latest.duration;
+    console.log(`[${latest.speaker}] ${latest.start.toFixed(2)}-${end.toFixed(2)} ${latest.text.trim()}`);
+  }
+});
+
+// With transcriptionOnly: incremental output, accumulate manually
+const allSegments: AlignedSegment[] = [];
+session.on('segments', (newSegments: AlignedSegment[]) => {
+  allSegments.push(...newSegments);
+  for (const seg of newSegments) {
+    const end = seg.start + seg.duration;
+    console.log(`${seg.start.toFixed(2)}-${end.toFixed(2)} ${seg.text.trim()}`);
+  }
 });
 ```
 
@@ -283,46 +476,32 @@ session.on('audio', (chunk: Float32Array) => {
 ### Types
 
 ```typescript
-export interface ModelConfig {
+export interface PipelineConfig {
   // === Required Model Paths ===
   /** Path to segmentation GGUF model */
   segModelPath: string;
 
-  /** Path to embedding GGUF model */
-  embModelPath: string;
-
-  /** Path to PLDA GGUF model */
-  pldaPath: string;
-
-  /** Path to embedding CoreML .mlpackage directory */
-  coremlPath: string;
-
-  /** Path to segmentation CoreML .mlpackage directory */
-  segCoremlPath: string;
-
   /** Path to Whisper GGUF model */
   whisperModelPath: string;
 
+  /** Path to embedding GGUF model (required unless transcriptionOnly is true) */
+  embModelPath?: string;
+
+  /** Path to PLDA GGUF model (required unless transcriptionOnly is true) */
+  pldaPath?: string;
+
   // === Optional Model Paths ===
   /** Path to Silero VAD model (optional, enables silence compression) */
   vadModelPath?: string;
 
-  // === Whisper Context Options (model loading) ===
-  /** Enable GPU acceleration (default: true) */
-  useGpu?: boolean;
-
-  /** Enable Flash Attention (default: true) */
-  flashAttn?: boolean;
-
-  /** GPU device index (default: 0) */
-  gpuDevice?: number;
-
   /**
-   * Enable CoreML acceleration for Whisper encoder on macOS (default: false).
-   * The CoreML model must be placed next to the GGUF model with naming convention:
-   * e.g., ggml-base.en.bin -> ggml-base.en-encoder.mlmodelc/
+   * Transcription-only mode - skip speaker diarization (default: false).
+   * When true, embModelPath, pldaPath, and backend embedding assets are not required.
    */
-  useCoreml?: boolean;
+  transcriptionOnly?: boolean;
+
+  /** Required execution backend configuration */
+  backend: BackendConfig;
 
   /** Suppress whisper.cpp log output (default: false) */
   noPrints?: boolean;
@@ -380,6 +559,54 @@ export interface ModelConfig {
   suppressNst?: boolean;
 }
 
+export type BackendConfig =
+  | {
+      /** Metal backend on macOS */
+      type: 'metal';
+      /** GPU device index */
+      gpuDevice?: number;
+      /** Enable Flash Attention */
+      flashAttn?: boolean;
+    }
+  | {
+      /** Vulkan backend on Windows */
+      type: 'vulkan';
+      /** GPU device index */
+      gpuDevice?: number;
+      /** Enable Flash Attention */
+      flashAttn?: boolean;
+    }
+  | {
+      /** CoreML backend on macOS */
+      type: 'coreml';
+      /** GPU device index */
+      gpuDevice?: number;
+      /** Enable Flash Attention */
+      flashAttn?: boolean;
+      /** Path to segmentation CoreML .mlpackage directory */
+      segPath: string;
+      /** Path to embedding CoreML .mlpackage directory (required unless transcriptionOnly is true) */
+      embPath?: string;
+      /** Optional path to Whisper encoder CoreML .mlmodelc directory */
+      whisperEncoderPath?: string;
+    }
+  | {
+      /** OpenVINO hybrid backend on Windows */
+      type: 'openvino-hybrid';
+      /** GPU device index */
+      gpuDevice?: number;
+      /** Enable Flash Attention */
+      flashAttn?: boolean;
+      /** Path to Whisper encoder OpenVINO IR (.xml) */
+      whisperEncoderPath: string;
+      /** Path to embedding OpenVINO IR (.xml) (required unless transcriptionOnly is true) */
+      embPath?: string;
+      /** OpenVINO device target (default: 'GPU') */
+      openvinoDevice?: string;
+      /** OpenVINO model cache directory */
+      openvinoCacheDir?: string;
+    };
+
 export interface DecodeOptions {
   /** Language code (e.g., 'en', 'zh'). Omit for auto-detect. */
   language?: string;
@@ -416,7 +643,7 @@ export interface DecodeOptions {
 }
 
 export interface AlignedSegment {
-  /** Global speaker label (e.g., SPEAKER_00). */
+  /** Global speaker label (e.g., SPEAKER_00). "UNKNOWN" when diarization could not assign a speaker. Empty string when transcriptionOnly is true. */
   speaker: string;
 
   /** Segment start time in seconds. */
@@ -430,7 +657,7 @@ export interface AlignedSegment {
 }
 
 export interface TranscriptionResult {
-  /** Full speaker-labeled transcript segments. */
+  /** Transcript segments. Speaker-labeled when diarization is enabled; speaker is empty string in transcription-only mode. */
   segments: AlignedSegment[];
   /**
    * Silence-filtered audio (16 kHz mono Float32Array).
@@ -455,9 +682,12 @@ async function runOffline(audio: Float32Array) {
     segModelPath: './models/segmentation.gguf',
     embModelPath: './models/embedding.gguf',
     pldaPath: './models/plda.gguf',
-    coremlPath: './models/embedding.mlpackage',
-    segCoremlPath: './models/segmentation.mlpackage',
     whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+    backend: {
+      type: 'coreml',
+      segPath: './models/segmentation.mlpackage',
+      embPath: './models/embedding.mlpackage',
+    },
   });
 
   // Runs Whisper on full audio at once + offline diarization
@@ -485,9 +715,12 @@ async function runOfflineWithVAD(audio: Float32Array) {
     segModelPath: './models/segmentation.gguf',
     embModelPath: './models/embedding.gguf',
     pldaPath: './models/plda.gguf',
-    coremlPath: './models/embedding.mlpackage',
-    segCoremlPath: './models/segmentation.mlpackage',
     whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+    backend: {
+      type: 'coreml',
+      segPath: './models/segmentation.mlpackage',
+      embPath: './models/embedding.mlpackage',
+    },
     vadModelPath: './models/ggml-silero-v6.2.0.bin', // enables silence filtering
   });
 
@@ -519,9 +752,12 @@ async function runOfflineWithCallbacks(audio: Float32Array) {
     segModelPath: './models/segmentation.gguf',
     embModelPath: './models/embedding.gguf',
     pldaPath: './models/plda.gguf',
-    coremlPath: './models/embedding.mlpackage',
-    segCoremlPath: './models/segmentation.mlpackage',
     whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+    backend: {
+      type: 'coreml',
+      segPath: './models/segmentation.mlpackage',
+      embPath: './models/embedding.mlpackage',
+    },
   });
 
   const result = await pipeline.transcribeOffline(
@@ -553,9 +789,12 @@ async function runOneShot(audio: Float32Array) {
     segModelPath: './models/segmentation.gguf',
     embModelPath: './models/embedding.gguf',
     pldaPath: './models/plda.gguf',
-    coremlPath: './models/embedding.mlpackage',
-    segCoremlPath: './models/segmentation.mlpackage',
     whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+    backend: {
+      type: 'coreml',
+      segPath: './models/segmentation.mlpackage',
+      embPath: './models/embedding.mlpackage',
+    },
   });
 
   // Uses streaming pipeline internally (push 1s chunks + finalize)
@@ -580,12 +819,16 @@ async function runStreaming(audio: Float32Array) {
     segModelPath: './models/segmentation.gguf',
     embModelPath: './models/embedding.gguf',
     pldaPath: './models/plda.gguf',
-    coremlPath: './models/embedding.mlpackage',
-    segCoremlPath: './models/segmentation.mlpackage',
     whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+    backend: {
+      type: 'coreml',
+      segPath: './models/segmentation.mlpackage',
+      embPath: './models/embedding.mlpackage',
+    },
   });
 
   const session = pipeline.createSession();
+  // Diarization mode (default): each event is cumulative and may relabel earlier segments
   session.on('segments', (segments) => {
     const latest = segments[segments.length - 1];
     if (latest) {
@@ -616,6 +859,47 @@ async function runStreaming(audio: Float32Array) {
 }
 ```
 
+```typescript
+import { Pipeline, type AlignedSegment } from 'pyannote-cpp-node';
+
+async function runStreamingTranscriptionOnly(audio: Float32Array) {
+  const pipeline = await Pipeline.load({
+    segModelPath: './models/segmentation.gguf',
+    whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+    transcriptionOnly: true,
+    backend: {
+      type: 'coreml',
+      segPath: './models/segmentation.mlpackage',
+    },
+  });
+
+  const session = pipeline.createSession();
+
+  // Transcription-only: each event has only NEW segments
+  const allSegments: AlignedSegment[] = [];
+  session.on('segments', (newSegments) => {
+    allSegments.push(...newSegments);
+    for (const seg of newSegments) {
+      const end = seg.start + seg.duration;
+      console.log(`${seg.start.toFixed(2)}-${end.toFixed(2)} ${seg.text.trim()}`);
+    }
+  });
+
+  const chunkSize = 16000;
+  for (let i = 0; i < audio.length; i += chunkSize) {
+    const chunk = audio.slice(i, Math.min(i + chunkSize, audio.length));
+    await session.push(chunk);
+  }
+
+  const finalResult = await session.finalize();
+  console.log(`Final segments from finalize(): ${finalResult.segments.length}`);
+  console.log(`Accumulated from incremental events: ${allSegments.length}`);
+
+  session.close();
+  pipeline.close();
+}
+```
+
 ### Custom Whisper decode options
 
 ```typescript
@@ -625,15 +909,14 @@ const pipeline = await Pipeline.load({
   segModelPath: './models/segmentation.gguf',
   embModelPath: './models/embedding.gguf',
   pldaPath: './models/plda.gguf',
-  coremlPath: './models/embedding.mlpackage',
-  segCoremlPath: './models/segmentation.mlpackage',
   whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
-
-  // Whisper runtime options
-  useGpu: true,
-  flashAttn: true,
-  gpuDevice: 0,
-  useCoreml: false,
+  backend: {
+    type: 'coreml',
+    segPath: './models/segmentation.mlpackage',
+    embPath: './models/embedding.mlpackage',
+    flashAttn: true,
+    gpuDevice: 0,
+  },
 
   // Decode strategy
   nThreads: 8,
@@ -666,9 +949,12 @@ const pipeline = await Pipeline.load({
   segModelPath: './models/segmentation.gguf',
   embModelPath: './models/embedding.gguf',
   pldaPath: './models/plda.gguf',
-  coremlPath: './models/embedding.mlpackage',
-  segCoremlPath: './models/segmentation.mlpackage',
   whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+  backend: {
+    type: 'coreml',
+    segPath: './models/segmentation.mlpackage',
+    embPath: './models/embedding.mlpackage',
+  },
   language: 'en',
 });
 
@@ -690,34 +976,71 @@ const result3 = await pipeline.transcribe(chineseAudio);
 pipeline.close();
 ```
 
-### Switching Whisper backend at runtime
+### Switching execution backend at runtime (macOS)
 
 ```typescript
 import { Pipeline } from 'pyannote-cpp-node';
 
-// Start with GPU-only Whisper (default)
+// Start with Metal
 const pipeline = await Pipeline.load({
   segModelPath: './models/segmentation.gguf',
   embModelPath: './models/embedding.gguf',
   pldaPath: './models/plda.gguf',
-  coremlPath: './models/embedding.mlpackage',
-  segCoremlPath: './models/segmentation.mlpackage',
   whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
-  useCoreml: false,
+  backend: { type: 'metal' },
 });
 
-// Switch to CoreML-accelerated Whisper encoder at runtime
-// (requires ggml-large-v3-turbo-q5_0-encoder.mlmodelc next to the GGUF)
-await pipeline.setUseCoreml(true);
+// Switch to CoreML
+await pipeline.setExecutionBackend({
+  type: 'coreml',
+  segPath: './models/segmentation.mlpackage',
+  embPath: './models/embedding.mlpackage',
+  whisperEncoderPath: './models/ggml-large-v3-turbo-q5_0-encoder.mlmodelc',
+});
 const result1 = await pipeline.transcribeOffline(audio);
 
-// Switch back to GPU-only
-await pipeline.setUseCoreml(false);
+// Switch back to Metal
+await pipeline.setExecutionBackend({ type: 'metal' });
 const result2 = await pipeline.transcribeOffline(audio);
 
 pipeline.close();
 ```
 
+## Execution Backends
+
+`setExecutionBackend(options)` switches the inference backend at runtime.
+
+- On macOS: supports `metal` and `coreml`
+- On Windows: supports `vulkan` and `openvino-hybrid`
+- `openvino-hybrid` uses OpenVINO for the Whisper encoder and embedding model, and Vulkan for everything else
+- `gpuDevice` and `flashAttn` are configured inside the backend object
+
+```typescript
+const pipeline = await Pipeline.load({
+  segModelPath: './models/segmentation.gguf',
+  embModelPath: './models/embedding.gguf',
+  pldaPath: './models/plda.gguf',
+  whisperModelPath: './models/ggml-large-v3-turbo-q5_0.bin',
+  language: 'en',
+  backend: {
+    type: 'openvino-hybrid',
+    whisperEncoderPath: './models/ggml-large-v3-turbo-encoder-openvino.xml',
+    embPath: './models/embedding-openvino.xml',
+  },
+});
+
+// Switch to OpenVINO-hybrid at runtime
+await pipeline.setExecutionBackend({
+  type: 'openvino-hybrid',
+  whisperEncoderPath: './models/ggml-large-v3-turbo-encoder-openvino.xml',
+  embPath: './models/embedding-openvino.xml',
+});
+const result = await pipeline.transcribeOffline(audio);
+
+// Switch back to Vulkan
+await pipeline.setExecutionBackend({ type: 'vulkan' });
+```
+
 Streaming sessions also support runtime changes:
 
 ```typescript
@@ -756,6 +1079,21 @@ The pipeline returns this JSON shape:
 }
 ```
 
+When `transcriptionOnly` is `true`, the `speaker` field is an empty string:
+
+```json
+{
+  "segments": [
+    {
+      "speaker": "",
+      "start": 0.497000,
+      "duration": 2.085000,
+      "text": "Hello world"
+    }
+  ]
+}
+```
+
 ## Audio Format Requirements
 
 - Input must be `Float32Array`
@@ -775,6 +1113,8 @@ All API methods expect decoded PCM samples; file decoding/resampling is handled
 4. WhisperX-style alignment (speaker assignment by maximum segment overlap)
 5. Return segments + filtered audio bytes (timestamps aligned to filtered audio)
 
+In transcription-only mode, steps 3 (diarization) and 4 (alignment) are skipped.
+
 ### Streaming mode (`transcribe` / `createSession`)
 
 The streaming pipeline runs in 7 stages:
@@ -787,6 +1127,8 @@ The streaming pipeline runs in 7 stages:
 6. Finalize (flush + final recluster + final alignment)
 7. Callback/event emission (`segments` updates + `audio` chunk streaming)
 
+In transcription-only mode, steps 5 (alignment) and 6 (recluster) are skipped, and segments are emitted with an empty `speaker` field. Each `segments` event contains only the new segments from that Whisper call (incremental), unlike diarization mode which re-emits all segments after each recluster (cumulative).
+
 ## Performance
 
 - Offline transcription + diarization: **~12x real-time** (30s audio in 2.5s)
@@ -796,14 +1138,82 @@ The streaming pipeline runs in 7 stages:
 - Each Whisper segment maps 1:1 to a speaker-labeled segment (no merging)
 - Speaker confusion rate: **2.55%**
 
+## Warnings and Known Issues
+
+### Intel Integrated GPU (Iris Xe) - Vulkan driver memory leak
+
+- Intel Iris Xe (12th/13th gen) Vulkan drivers have a known memory leak when GPU contexts are repeatedly created and destroyed
+- This is a confirmed Intel driver bug (Intel internal tracking ID: 14022504159), not a bug in this library
+- Affects: repeated `Pipeline.load()` / `pipeline.close()` cycles in the same process (crashes after ~8-10 cycles)
+- Affects: repeated `setExecutionBackend()` calls (each call tears down and rebuilds the full GPU context)
+- Does NOT affect: creating/closing sessions (sessions borrow cached GPU contexts, no new Vulkan allocations)
+- Does NOT affect: NVIDIA or AMD discrete GPUs, or Intel Core Ultra (newer gen) integrated GPUs
+- Workaround: load the pipeline once at application startup and reuse it. Close only at shutdown.
+- Reference: https://community.intel.com/t5/Developing-Games-on-Intel/Memory-leaks-on-Intel-Iris-Xe-graphics/td-p/1585566
+
+### setExecutionBackend is a heavy operation
+
+- Each call fully tears down and reloads the model cache (Whisper context, GGML models, Vulkan/OpenVINO backends)
+- Takes ~5-6 seconds on Intel Iris Xe
+- Treat it as a one-time configuration change, not something to call repeatedly
+- On Intel iGPU: limit to 1-2 switches per process lifetime to avoid the driver leak
+
+### One operation at a time
+
+The pipeline enforces exclusive access to its GPU resources. Only one of the following can be active at a time:
+
+- A streaming session (`createSession()`)
+- A one-shot transcription (`transcribe()`)
+- An offline transcription (`transcribeOffline()`)
+- A backend switch (`setExecutionBackend()`)
+
+Attempting to start a second operation while one is active throws an error. Close the current session or wait for the current operation to complete before starting the next one.
+
+```typescript
+// CORRECT: sequential operations
+const session = pipeline.createSession();
+// ... push audio, finalize ...
+session.close();
+const result = await pipeline.transcribeOffline(audio); // OK — session is closed
+
+// ERROR: concurrent operations
+const session1 = pipeline.createSession();
+const session2 = pipeline.createSession(); // throws: "A session is already active"
+await pipeline.transcribeOffline(audio);   // throws: "Model is busy"
+```
+
+### Session creation is cheap
+
+- `createSession()` borrows pre-loaded models and GPU contexts from the cache
+- No new Vulkan backends or model loads occur
+- Close the session when done, then create another — safe to repeat unlimited times
+
+```typescript
+// SAFE: load once, create many sessions sequentially
+const pipeline = await Pipeline.load(config);
+for (const file of files) {
+  const session = pipeline.createSession();
+  // ... push audio, finalize ...
+  session.close(); // cheap — no GPU teardown
+}
+pipeline.close(); // once, at shutdown
+
+// DANGEROUS on Intel iGPU: repeated load/close cycles
+for (const file of files) {
+  const pipeline = await Pipeline.load(config); // creates Vulkan context
+  await pipeline.transcribe(audio);
+  pipeline.close(); // destroys Vulkan context - driver leaks ~8th cycle crashes
+}
+```
+
 ## Platform Support
 
-| Platform | Status |
-| --- | --- |
-| macOS arm64 (Apple Silicon) | Supported |
-| macOS x64 (Intel) | Supported |
-| Linux | Not supported |
-| Windows | Not supported |
+| Platform | Low-level (Whisper/VAD) | Pipeline (Transcription + Diarization) |
+| --- | --- | --- |
+| macOS arm64 (Apple Silicon) | Supported | Supported (CoreML + Metal) |
+| Windows x64 | Supported | Supported (Vulkan + optional OpenVINO) |
+| macOS x64 (Intel) | Supported | Not tested |
+| Linux | Not supported | Not supported |
 
 ## License