whispermix 1.4.14 → 1.6.2

package/README.md

@@ -1,6 +1,6 @@
 # 🎙️ WhisperMix
 
-WhisperMix is a flexible module that provides an interface for transcribing audio using OpenAI's Whisper model, Groq's Whisper Large v3 model, or local Whisper models.
+WhisperMix is a flexible module that provides an interface for transcribing audio using OpenAI's Whisper model, Groq's Whisper Large v3 model, local Whisper models, or local Parakeet TDT v3 models.
 
 ## 📦 Installation
 
@@ -36,6 +36,12 @@ const whisperGroq = new WhisperMix({ model: 'groq/whisper-large-v3' }); // For G
 const whisperLocal = new WhisperMix({ model: 'xenova/whisper-large-v3' }); // For local Whisper (large)
 // or
 const whisperLocalBase = new WhisperMix({ model: 'xenova/whisper-base' }); // For local Whisper (base)
+// or
+const whisperParakeet = new WhisperMix({ model: 'istupakov/parakeet-tdt-0.6b-v3' }); // For local Parakeet v3 (int8)
+// or
+const whisperParakeetInt4 = new WhisperMix({ model: 'efederici/parakeet-tdt-0.6b-v3-int4' }); // For local Parakeet v3 (int4 encoder)
+// or
+const whisperParakeetAlt = new WhisperMix({ model: 'nasedkinpv/parakeet-tdt-0.6b-v3-int8' }); // For local Parakeet v3 (alt int8 repo)
 ```
 
 ### 📄 Transcribing from a File
@@ -67,7 +73,49 @@ whisperGroq.fromStream(audioStream)
   .catch(error => console.error(error));
 ```
 
-**Note:** Stream transcription is only available for API-based models (OpenAI and Groq). Local Whisper models require file input.
+**Note:** Stream transcription is only available for API-based models (OpenAI and Groq). Local models (Whisper and Parakeet) require file input.
+
+### ⏱️ Word-Level Timestamps
+
+By default, WhisperMix returns only the transcribed text. To include the start and end time for each word, pass `wordTimestamps: true` per call:
+
+```javascript
+const result = await whisperGroq.fromFile('path/to/audio.mp3', {
+  wordTimestamps: true
+});
+
+console.log(result.text);
+console.log(result.words);
+// [{ word: 'Hello', start: 0.12, end: 0.48 }, ...]
+```
+
+You can also enable it on the instance:
+
+```javascript
+const whisper = new WhisperMix({
+  model: 'openai/whisper-1',
+  wordTimestamps: true
+});
+
+const result = await whisper.fromStream(audioStream);
+```
+
+### 🐦 Parakeet local models
+
+Parakeet TDT v3 local models are downloaded once and cached in:
+
+`~/.cache/whispermix/parakeet/<modelKey>/`
+
+Available local Parakeet model keys:
+
+- `istupakov/parakeet-tdt-0.6b-v3` (about 670 MB, int8)
+- `efederici/parakeet-tdt-0.6b-v3-int4` (about 410 MB, int4/int8 hybrid)
+- `nasedkinpv/parakeet-tdt-0.6b-v3-int8` (about 890 MB, int8)
+
+Notes:
+
+- Parakeet TDT v3 is multilingual (25 European languages).
+- `language` is ignored for Parakeet local models.
 
 ### ⏱️ Long Audio Processing
 
@@ -108,25 +156,29 @@ You can adjust these settings based on your specific rate limiting needs. Note t
 
 Creates a new WhisperMix instance.
 
-- `options.model`: The model to use for transcription. Can be `'openai/whisper-1'` (OpenAI), `'groq/whisper-large-v3'` (Groq), `'xenova/whisper-large-v3'` or `'xenova/whisper-base'` (local).
+- `options.model`: The model to use for transcription. Can be `'openai/whisper-1'` (OpenAI), `'groq/whisper-large-v3'` (Groq), `'xenova/whisper-large-v3'` or `'xenova/whisper-base'` (local Whisper), `'istupakov/parakeet-tdt-0.6b-v3'`, `'efederici/parakeet-tdt-0.6b-v3-int4'`, or `'nasedkinpv/parakeet-tdt-0.6b-v3-int8'` (local Parakeet).
 - `options.bottleneck`: (Optional) Configuration for Bottleneck rate limiting (API models only).
 - `options.chunkSize`: (Optional) The size in seconds of the chunks to split the audio into. Default is 890 seconds.
 - `options.language`: (Optional) Language for local Whisper model. Defaults to 'auto' for automatic detection.
-### `whisper.fromFile(filePath)`
+- `options.wordTimestamps`: (Optional) Return `{ text, words }` instead of plain text, where each word has `start` and `end` times in seconds.
+
+### `whisper.fromFile(filePath, options)`
 
 Transcribes audio from a file.
 
 - `filePath`: Path to the audio file.
+- `options.wordTimestamps`: (Optional) Return word-level timestamps for this call.
 
-Returns a Promise that resolves with the transcription text.
+Returns a Promise that resolves with the transcription text, or `{ text, words }` when `wordTimestamps` is enabled.
 
-### `whisper.fromStream(audioStream)`
+### `whisper.fromStream(audioStream, options)`
 
 Transcribes audio from a stream.
 
 - `audioStream`: A readable stream of the audio data.
+- `options.wordTimestamps`: (Optional) Return word-level timestamps for this call.
 
-Returns a Promise that resolves with the transcription text.
+Returns a Promise that resolves with the transcription text, or `{ text, words }` when `wordTimestamps` is enabled.
 
 ## 📄 License
 

package/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: whispermix
+description: Transcribe audio to text using WhisperMix, a Node.js wrapper around OpenAI Whisper, Groq Whisper Large v3, local Whisper (xenova) and local Parakeet TDT v3 models. Use when the user asks to "transcribe audio", "speech to text", "convert audio/voice to text", mentions an audio file (.mp3, .wav, .m4a, .ogg, .flac, .webm) to turn into text, or names any of these models/providers: Whisper, OpenAI Whisper, Groq Whisper, Whisper Large v3, Parakeet, NVIDIA Parakeet, xenova/whisper, onnx-asr. Also use when the user wants to pick between a cloud API and a local on-device transcription model in a Node.js project.
+---
+
+# WhisperMix
+
+Single Node.js entry point for audio transcription. Picks one of four backends behind the same API: OpenAI Whisper, Groq Whisper Large v3, local Whisper (xenova), or local Parakeet TDT v3. Handles long files by chunking and rate-limits API calls automatically.
+
+Do NOT use for TTS, live microphone streaming, or translation. WhisperMix is one-way: a complete audio file/stream → text.
+
+## Model selection (decide first)
+
+| Need | Pick |
+|---|---|
+| Offline, lowest latency | `istupakov/parakeet-tdt-0.6b-v3` |
+| Offline, smallest footprint (~410 MB) | `efederici/parakeet-tdt-0.6b-v3-int4` |
+| Highest accuracy, cloud | `groq/whisper-large-v3` (fast) or `openai/whisper-1` |
+| Offline + per-language control | `xenova/whisper-large-v3` or `xenova/whisper-base` |
+| Node stream input (not a file) | API only: `openai/whisper-1` or `groq/whisper-large-v3` |
+
+Constraints to surface before coding:
+- Local models (`xenova/*`, `*/parakeet-tdt-0.6b-v3*`) accept **files only**, not streams.
+- `language` option applies only to local Whisper. Parakeet is multilingual and ignores it.
+- API models need `OPENAI_API_KEY` or `GROQ_API_KEY` in the environment.
+- First Parakeet run downloads weights to `~/.cache/whispermix/parakeet/<modelKey>/` — warn the user.
+- Requires `ffmpeg` on `PATH` for long-audio chunking (>15 min split automatically).
+- `wordTimestamps: true` changes the return value from plain text to `{ text, words }`, where each word has `start` and `end` times in seconds.
+
+## API
+
+```bash
+npm install whispermix
+```
+
+ESM only. If the consumer is CommonJS, use `const WhisperMix = (await import('whispermix')).default;`.
+
+```javascript
+import WhisperMix from 'whispermix';
+
+const w = new WhisperMix({ model: '<modelKey>' });
+const text = await w.fromFile('path/to/audio.mp3');
+// API models only:
+const text2 = await w.fromStream(fs.createReadStream('path/to/audio.mp3'));
+```
+
+Constructor options:
+- `model` (required) — see selection table.
+- `language` — local Whisper only, e.g. `'spanish'`. Default `'auto'`.
+- `chunkSize` — seconds per chunk for long audio. Default `890` (~14m50s).
+- `bottleneck` — Bottleneck config for API models. Defaults: `minTime: 3000`, `maxConcurrent: 1`, `reservoir: 18`, `reservoirRefreshAmount: 18`, `reservoirRefreshInterval: 60000`.
+- `showProgress` — boolean, prints chunk/decoding progress.
+- `wordTimestamps` — boolean, returns `{ text, words }` instead of a string. Can also be passed per call to `fromFile(filePath, { wordTimestamps: true })` or `fromStream(stream, { wordTimestamps: true })`.
+
+## Examples
+
+Cheapest local:
+
+```javascript
+import WhisperMix from 'whispermix';
+const w = new WhisperMix({ model: 'efederici/parakeet-tdt-0.6b-v3-int4', showProgress: true });
+console.log(await w.fromFile('meeting.wav'));
+```
+
+Groq with custom rate limit:
+
+```javascript
+import WhisperMix from 'whispermix';
+const w = new WhisperMix({
+    model: 'groq/whisper-large-v3',
+    bottleneck: { minTime: 4000, maxConcurrent: 1 },
+});
+console.log(await w.fromFile('podcast.mp3'));
+```
+
+Word-level timestamps:
+
+```javascript
+import WhisperMix from 'whispermix';
+const w = new WhisperMix({ model: 'openai/whisper-1' });
+const result = await w.fromFile('meeting.mp3', { wordTimestamps: true });
+console.log(result.text);
+console.log(result.words); // [{ word, start, end }, ...]
+```
+
+Local Whisper, fixed language:
+
+```javascript
+import WhisperMix from 'whispermix';
+const w = new WhisperMix({ model: 'xenova/whisper-large-v3', language: 'spanish' });
+console.log(await w.fromFile('entrevista.m4a'));
+```
+
+## Troubleshooting
+
+- **`OPENAI_API_KEY`/`GROQ_API_KEY is not set`** — export the key, or switch to a local model.
+- **`fromStream` not supported** — local models are file-only. Use `fromFile`, or switch to an API model.
+- **`Cannot find ffmpeg`** — install it (`brew install ffmpeg` / `apt install ffmpeg`).
+- **First Parakeet call hangs** — weights downloading; enable `showProgress: true`.
+- **`ERR_REQUIRE_ESM`** — WhisperMix is ESM-only; use dynamic `import()` from CommonJS.

package/demo/parakeet.js

@@ -0,0 +1,9 @@
+import WhisperMix from '../index.js';
+
+const whisperParakeet = new WhisperMix({
+    model: 'efederici/parakeet-tdt-0.6b-v3-int4',
+    showProgress: true,
+});
+
+const result = await whisperParakeet.fromFile('conversation.wav');
+console.log(result);

package/index.js

@@ -4,11 +4,52 @@ import path from 'path';
 import ffmpeg from 'fluent-ffmpeg';
 import { getAudioDurationInSeconds } from 'get-audio-duration';
 import os from 'os'; // For temporary directory
+import { Readable } from 'stream';
+import { pipeline as streamPipeline } from 'stream/promises';
 
 // Static imports for local dependencies
-import { pipeline, env } from '@huggingface/transformers';
+import { pipeline as hfPipeline, env } from '@huggingface/transformers';
 import audioDecode from 'audio-decode';
 
+const PARAKEET_LAYOUTS = {
+    'istupakov/parakeet-tdt-0.6b-v3': {
+        cacheKey: 'istupakov-parakeet-tdt-0.6b-v3',
+        repo: 'istupakov/parakeet-tdt-0.6b-v3-onnx',
+        files: [
+            { src: 'config.json', dst: 'config.json' },
+            { src: 'nemo128.onnx', dst: 'nemo128.onnx' },
+            { src: 'encoder-model.int8.onnx', dst: 'encoder-model.int8.onnx' },
+            { src: 'decoder_joint-model.int8.onnx', dst: 'decoder_joint-model.int8.onnx' },
+            { src: 'vocab.txt', dst: 'vocab.txt' },
+        ],
+    },
+    'efederici/parakeet-tdt-0.6b-v3-int4': {
+        cacheKey: 'efederici-parakeet-tdt-0.6b-v3-int4',
+        repo: 'efederici/parakeet-tdt-0.6b-v3-onnx-int4',
+        files: [
+            { src: 'config.json', dst: 'config.json' },
+            { src: 'nemo128.onnx', dst: 'nemo128.onnx' },
+            { src: 'encoder-model.int4.onnx', dst: 'encoder-model.int8.onnx' },
+            { src: 'decoder_joint-model.int8.onnx', dst: 'decoder_joint-model.int8.onnx' },
+            { src: 'vocab.txt', dst: 'vocab.txt' },
+        ],
+    },
+    'nasedkinpv/parakeet-tdt-0.6b-v3-int8': {
+        cacheKey: 'nasedkinpv-parakeet-tdt-0.6b-v3-int8',
+        repo: 'nasedkinpv/parakeet-tdt-0.6b-v3-onnx-int8',
+        files: [
+            { src: 'encoder-int8.onnx', dst: 'encoder-model.int8.onnx' },
+            { src: 'encoder-int8.onnx.data', dst: 'encoder-model.int8.onnx.data' },
+            { src: 'decoder_joint-int8.onnx', dst: 'decoder_joint-model.int8.onnx' },
+            { src: 'vocab.txt', dst: 'vocab.txt' },
+            { srcRepo: 'istupakov/parakeet-tdt-0.6b-v3-onnx', src: 'nemo128.onnx', dst: 'nemo128.onnx' },
+        ],
+        synthConfig: {
+            model_type: 'nemo-conformer-tdt',
+        },
+    },
+};
+
 class WhisperMix {
     constructor(setup = {}) {
         this.model = 'openai/whisper-1';
@@ -41,7 +82,26 @@ class WhisperMix {
                 local: true,
                 modelName: 'Xenova/whisper-base',
                 dtype: 'q8',
-            },            
+                backend: 'transformers',
+            },
+            'istupakov/parakeet-tdt-0.6b-v3': {
+                local: true,
+                modelName: 'Parakeet-TDT-0.6B-v3',
+                backend: 'onnx-asr-web',
+                layout: PARAKEET_LAYOUTS['istupakov/parakeet-tdt-0.6b-v3'],
+            },
+            'efederici/parakeet-tdt-0.6b-v3-int4': {
+                local: true,
+                modelName: 'Parakeet-TDT-0.6B-v3-int4',
+                backend: 'onnx-asr-web',
+                layout: PARAKEET_LAYOUTS['efederici/parakeet-tdt-0.6b-v3-int4'],
+            },
+            'nasedkinpv/parakeet-tdt-0.6b-v3-int8': {
+                local: true,
+                modelName: 'Parakeet-TDT-0.6B-v3-int8',
+                backend: 'onnx-asr-web',
+                layout: PARAKEET_LAYOUTS['nasedkinpv/parakeet-tdt-0.6b-v3-int8'],
+            },
         };
 
         Object.assign(this, setup);
@@ -56,12 +116,17 @@ class WhisperMix {
         this.modelName = this.config.modelName;
         this.dtype = this.dtype || this.config.dtype;
         this.showProgress = this.showProgress || false;
+        this.localBackend = this.config.backend || 'transformers';
+        this.layout = this.config.layout;
         this.transcriber = null;
+        this._onnxAsrNodeModule = null;
+        this._warnedParakeetLanguage = false;
 
         this.limiter = new Bottleneck(this.bottleneck);
     }
 
-    async fromFile(filePath) {
+    async fromFile(filePath, options = {}) {
+        const transcriptionOptions = this._resolveTranscriptionOptions(options);
         const absolutePath = path.resolve(filePath);
         
         // Check if file exists
@@ -78,14 +143,10 @@ class WhisperMix {
 
             if (duration <= this.chunkSize) {
                 // Process as a single file
-                if (this.isLocal) {
-                    return this._transcribeLocalFile(absolutePath);
-                } else {
-                    return this.fromStream(fs.createReadStream(absolutePath));
-                }
+                return this._transcribeFilePath(absolutePath, transcriptionOptions);
             } else {
                 // Split audio and process chunks
-                let accumulatedTranscription = "";
+                const transcriptions = [];
                 const numChunks = Math.ceil(duration / this.chunkSize);
 
                 for (let i = 0; i < numChunks; i++) {
@@ -107,14 +168,8 @@ class WhisperMix {
                             .run();
                     });
 
-                    let transcription;
-                    if (this.isLocal) {
-                        transcription = await this._transcribeLocalFile(chunkPath);
-                    } else {
-                        const chunkStream = fs.createReadStream(chunkPath);
-                        transcription = await this.fromStream(chunkStream);
-                    }
-                    accumulatedTranscription += (transcription + " ").trimStart();
+                    const transcription = await this._transcribeFilePath(chunkPath, transcriptionOptions);
+                    transcriptions.push(this._offsetTranscription(transcription, startTime));
                     
                     // Clean up chunk immediately after processing
                     try {
@@ -123,7 +178,7 @@ class WhisperMix {
                         console.warn(`Could not delete chunk ${chunkPath}:`, unlinkErr);
                     }
                 }
-                return accumulatedTranscription.trim();
+                return this._mergeTranscriptions(transcriptions, transcriptionOptions, duration);
             }
         } finally {
             // Clean up the temporary directory
@@ -135,10 +190,18 @@ class WhisperMix {
         }
     }
 
-    async fromStream(audioStream) {
+    async _transcribeFilePath(filePath, options) {
+        if (this.isLocal) {
+            return this._transcribeLocalFile(filePath, options);
+        }
+        return this.fromStream(fs.createReadStream(filePath), options);
+    }
+
+    async fromStream(audioStream, options = {}) {
         if (this.isLocal) {
             throw new Error('fromStream is not supported for local Whisper model. Use fromFile instead.');
         }
+        const transcriptionOptions = this._resolveTranscriptionOptions(options);
 
         const chunks = [];
         for await (const chunk of audioStream) {
@@ -146,10 +209,10 @@ class WhisperMix {
         }
         const buffer = Buffer.concat(chunks);
 
-        return this.limiter.schedule(() => this._makeRequest(buffer));
+        return this.limiter.schedule(() => this._makeRequest(buffer, transcriptionOptions));
     }
 
-    async _makeRequest(buffer) {
+    async _makeRequest(buffer, options = {}) {
         try {
             const blob = new Blob([buffer], { type: 'audio/mpeg' });
             const formData = new FormData();
@@ -158,6 +221,10 @@ class WhisperMix {
             if (this.language) {
                 formData.append('language', this.language);
             }
+            if (options.wordTimestamps) {
+                formData.append('response_format', 'verbose_json');
+                formData.append('timestamp_granularities[]', 'word');
+            }
 
             const response = await fetch(this.apiUrl, {
                 method: 'POST',
@@ -173,13 +240,13 @@ class WhisperMix {
                 throw responseData;
             }
 
-            return responseData.text.trim();
+            return this._formatApiTranscription(responseData, options);
         } catch (error) {
             throw error?.message || error;
         }
     }
 
-    async _transcribeLocalFile(filePath) {
+    async _transcribeLocalFile(filePath, options = {}) {
         try {
             // Read the audio file as a buffer
             const buffer = fs.readFileSync(filePath);
@@ -212,6 +279,19 @@ class WhisperMix {
             // Reuse a single pipeline instance so repeated calls don't re-download/re-initialize.
             const transcriber = await this._getLocalTranscriber();
 
+            if (this.localBackend === 'onnx-asr-web') {
+                if (this.language !== undefined && this.showProgress && !this._warnedParakeetLanguage) {
+                    console.log('[WhisperMix] "language" option is ignored for Parakeet local models.');
+                    this._warnedParakeetLanguage = true;
+                }
+                const result = await transcriber.transcribeSamples(audioData, 16000);
+                const text = result?.text || result?.utterance_text;
+                if (typeof text !== 'string') {
+                    throw new Error('Parakeet transcription returned no text output.');
+                }
+                return this._formatLocalTranscription(text, result?.words, options);
+            }
+
             // Pass the processed audio data
             const transcriberOptions = {
                 task: 'transcribe',
@@ -219,16 +299,178 @@ class WhisperMix {
             if (this.language !== undefined) {
                 transcriberOptions.language = this.language;
             }
+            if (options.wordTimestamps) {
+                transcriberOptions.return_timestamps = 'word';
+            }
             const result = await transcriber(audioData, transcriberOptions);
-
-            return result.text.trim();
+            const words = options.wordTimestamps ? this._wordsFromTransformersChunks(result.chunks) : undefined;
+            return this._formatLocalTranscription(result.text, words, options);
         } catch (error) {
-            throw new Error(`Local transcription failed: ${error.message}. If this happened after an interrupted download, remove the model cache at ${env.cacheDir}${this.modelName}/ and try again.`);
+            const cacheHint = this.localBackend === 'onnx-asr-web'
+                ? this._getParakeetCacheDir(this.layout)
+                : `${env.cacheDir}${this.modelName}/`;
+            throw new Error(`Local transcription failed: ${error.message}. If this happened after an interrupted download, remove the model cache at ${cacheHint} and try again.`);
+        }
+    }
+
+    _resolveTranscriptionOptions(options = {}) {
+        return {
+            wordTimestamps: Boolean(options.wordTimestamps ?? this.wordTimestamps),
+        };
+    }
+
+    _formatApiTranscription(responseData, options) {
+        const text = this._formatText(responseData.text);
+        if (!options.wordTimestamps) {
+            return text;
+        }
+        return {
+            ...responseData,
+            text,
+            words: this._normalizeWords(responseData.words),
+        };
+    }
+
+    _formatLocalTranscription(text, words, options) {
+        const formattedText = this._formatText(text);
+        if (!options.wordTimestamps) {
+            return formattedText;
+        }
+        return {
+            text: formattedText,
+            words: this._normalizeWords(words),
+        };
+    }
+
+    _formatText(text) {
+        if (typeof text !== 'string') {
+            throw new Error('Transcription returned no text output.');
+        }
+        return text.trim();
+    }
+
+    _wordsFromTransformersChunks(chunks) {
+        if (!Array.isArray(chunks)) {
+            return undefined;
+        }
+        return chunks.map((chunk) => ({
+            word: chunk.text,
+            timestamp: chunk.timestamp,
+        }));
+    }
+
+    _normalizeWords(words) {
+        if (!Array.isArray(words)) {
+            throw new Error('Word timestamps were requested, but the selected backend did not return word timestamps.');
+        }
+
+        return words
+            .map((word) => {
+                if (!word || typeof word !== 'object') {
+                    throw new Error('Word timestamp response contains an invalid word entry.');
+                }
+
+                const text = typeof word.word === 'string' ? word.word : word.text;
+                const start = typeof word.start === 'number' ? word.start : word.timestamp?.[0];
+                const end = typeof word.end === 'number' ? word.end : word.timestamp?.[1];
+
+                if (typeof text !== 'string' || typeof start !== 'number' || typeof end !== 'number') {
+                    throw new Error('Word timestamp response contains an invalid word entry.');
+                }
+
+                return {
+                    word: text.trim(),
+                    start,
+                    end,
+                };
+            })
+            .filter((word) => word.word.length > 0);
+    }
+
+    _mergeTranscriptions(transcriptions, options, duration) {
+        const text = transcriptions
+            .map((transcription) => this._transcriptionText(transcription))
+            .filter((chunkText) => chunkText.length > 0)
+            .join(' ')
+            .trim();
+
+        if (!options.wordTimestamps) {
+            return text;
+        }
+
+        const words = transcriptions.flatMap((transcription) => {
+            if (!Array.isArray(transcription.words)) {
+                throw new Error('Word timestamps were requested, but a chunk returned no word timestamps.');
+            }
+            return transcription.words;
+        });
+        const segments = transcriptions.flatMap((transcription) => (
+            Array.isArray(transcription.segments) ? transcription.segments : []
+        ));
+        const result = { text, words, duration };
+
+        if (segments.length > 0) {
+            result.segments = segments;
+        }
+
+        return result;
+    }
+
+    _transcriptionText(transcription) {
+        if (typeof transcription === 'string') {
+            return transcription.trim();
         }
+        return this._formatText(transcription.text);
+    }
+
+    _offsetTranscription(transcription, offsetSeconds) {
+        if (typeof transcription === 'string' || offsetSeconds === 0) {
+            return transcription;
+        }
+
+        return {
+            ...transcription,
+            words: Array.isArray(transcription.words)
+                ? this._offsetTimedItems(transcription.words, offsetSeconds)
+                : transcription.words,
+            segments: Array.isArray(transcription.segments)
+                ? this._offsetTimedItems(transcription.segments, offsetSeconds)
+                : transcription.segments,
+        };
+    }
+
+    _offsetTimedItems(items, offsetSeconds) {
+        return items.map((item) => ({
+            ...item,
+            start: this._offsetTime(item.start, offsetSeconds),
+            end: this._offsetTime(item.end, offsetSeconds),
+        }));
+    }
+
+    _offsetTime(value, offsetSeconds) {
+        if (typeof value !== 'number') {
+            return value;
+        }
+        return Number((value + offsetSeconds).toFixed(3));
     }
 
     async _getLocalTranscriber() {
         if (!this.transcriber) {
+            if (this.localBackend === 'onnx-asr-web') {
+                if (!this.layout) {
+                    throw new Error(`Missing Parakeet layout for model: ${this.model}`);
+                }
+                const modelDir = await this._ensureParakeetAssets(this.layout);
+                const { loadLocalModel } = await this._getOnnxAsrNodeModule();
+                this.transcriber = await loadLocalModel(modelDir, {
+                    quantization: 'int8',
+                    sessionOptions: {
+                        executionProviders: ['wasm'],
+                    },
+                });
+                return this.transcriber;
+            }
+
             const options = {};
             if (this.dtype) {
                 options.dtype = this.dtype;
@@ -244,11 +486,90 @@ class WhisperMix {
                 };
             }
 
-            this.transcriber = pipeline('automatic-speech-recognition', this.modelName, options);
+            this.transcriber = hfPipeline('automatic-speech-recognition', this.modelName, options);
         }
 
         return this.transcriber;
     }
+
+    async _getOnnxAsrNodeModule() {
+        if (!this._onnxAsrNodeModule) {
+            this._onnxAsrNodeModule = await import('onnx-asr-web/node');
+        }
+        return this._onnxAsrNodeModule;
+    }
+
+    _getParakeetCacheDir(layout) {
+        if (this.cacheDir) {
+            return path.resolve(this.cacheDir);
+        }
+        if (!layout?.cacheKey) {
+            throw new Error(`Missing cache key for Parakeet layout: ${this.model}`);
+        }
+        return path.join(os.homedir(), '.cache', 'whispermix', 'parakeet', layout.cacheKey);
+    }
+
+    async _ensureParakeetAssets(layout) {
+        const cacheDir = this._getParakeetCacheDir(layout);
+        await fs.promises.mkdir(cacheDir, { recursive: true });
+
+        for (const fileDef of layout.files) {
+            const destination = path.join(cacheDir, fileDef.dst);
+            const sourceRepo = fileDef.srcRepo || layout.repo;
+
+            if (await this._hasFileWithContent(destination)) {
+                continue;
+            }
+
+            const sourceUrl = `https://huggingface.co/${sourceRepo}/resolve/main/${fileDef.src}`;
+            if (this.showProgress) {
+                console.log(`[WhisperMix] Downloading ${fileDef.src} from ${sourceRepo}`);
+            }
+            await this._downloadToFile(sourceUrl, destination);
+        }
+
+        if (layout.synthConfig) {
+            const configPath = path.join(cacheDir, 'config.json');
+            if (!(await this._hasFileWithContent(configPath))) {
+                await fs.promises.writeFile(configPath, JSON.stringify(layout.synthConfig, null, 2));
+            }
+        }
+
+        return cacheDir;
+    }
+
+    async _hasFileWithContent(filePath) {
+        try {
+            const stats = await fs.promises.stat(filePath);
+            return stats.isFile() && stats.size > 0;
+        } catch {
+            return false;
+        }
+    }
+
+    async _downloadToFile(url, filePath) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Download failed (${response.status} ${response.statusText}) for ${url}`);
+        }
+        if (!response.body) {
+            throw new Error(`Empty response body while downloading ${url}`);
+        }
+
+        await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+        const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+
+        try {
+            await streamPipeline(
+                Readable.fromWeb(response.body),
+                fs.createWriteStream(tempPath),
+            );
+            await fs.promises.rename(tempPath, filePath);
+        } catch (error) {
+            await fs.promises.rm(tempPath, { force: true });
+            throw error;
+        }
+    }
 }
 
 // Support both CommonJS and ES modules

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "whispermix",
   "description": "🎙️ WhisperMix is a versatile module for transcribing audio using OpenAI’s Whisper or Groq’s Whisper v3 model.",
-  "version": "1.4.14",
+  "version": "1.6.2",
   "type": "module",
   "keywords": [
     "whisper",
@@ -28,7 +28,10 @@
     "chunk",
     "clasen",
     "local",
-    "xenova"
+    "xenova",
+    "parakeet",
+    "nvidia",
+    "onnx"
   ],
   "repository": {
     "type": "git",
@@ -45,7 +48,8 @@
     "audio-decode": "^2.2.3",
     "bottleneck": "^2.19.5",
     "fluent-ffmpeg": "^2.1.3",
-    "get-audio-duration": "^4.0.1"
+    "get-audio-duration": "^4.0.1",
+    "onnx-asr-web": "^0.1.3"
   },
   "devDependencies": {
     "node-addon-api": "^8.7.0",