whispermix 1.5.2 → 1.6.2

package/README.md

@@ -75,6 +75,31 @@ whisperGroq.fromStream(audioStream)
 
 **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:
@@ -135,21 +160,25 @@ Creates a new WhisperMix instance.
 - `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

@@ -25,6 +25,7 @@ Constraints to surface before coding:
 - 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
 
@@ -49,6 +50,7 @@ Constructor options:
 - `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
 
@@ -71,6 +73,16 @@ const w = new WhisperMix({
 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

package/index.js

@@ -125,7 +125,8 @@ class WhisperMix {
         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
@@ -142,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++) {
@@ -171,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 {
@@ -187,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
@@ -199,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) {
@@ -210,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();
@@ -222,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',
@@ -237,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);
@@ -286,7 +289,7 @@ class WhisperMix {
                 if (typeof text !== 'string') {
                     throw new Error('Parakeet transcription returned no text output.');
                 }
-                return text.trim();
+                return this._formatLocalTranscription(text, result?.words, options);
             }
 
             // Pass the processed audio data
@@ -296,8 +299,12 @@ 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) {
             const cacheHint = this.localBackend === 'onnx-asr-web'
                 ? this._getParakeetCacheDir(this.layout)
@@ -306,6 +313,147 @@ class WhisperMix {
         }
     }
 
+    _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') {

package/package.json

@@ -1,62 +1,61 @@
 {
-    "name": "whispermix",
-    "description": "🎙️ WhisperMix is a versatile module for transcribing audio using OpenAI’s Whisper or Groq’s Whisper v3 model.",
-    "version": "1.5.2",
-    "type": "module",
-    "keywords": [
-        "whisper",
-        "openai",
-        "groq",
-        "transcription",
-        "speech-to-text",
-        "audio",
-        "voice",
-        "ai",
-        "machine-learning",
-        "nlp",
-        "natural-language-processing",
-        "audio-processing",
-        "voice-recognition",
-        "speech-recognition",
-        "api-wrapper",
-        "whisper-large-v3",
-        "whisper-1",
-        "streaming",
-        "file-processing",
-        "multilingual",
-        "bottleneck",
-        "chunk",
-        "clasen",
-        "local",
-        "xenova",
-        "parakeet",
-        "nvidia",
-        "onnx"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/clasen/WhisperMix.git"
-    },
-    "main": "index.js",
-    "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "author": "Martin Clasen",
-    "license": "MIT",
-    "bugs": {
-        "url": "https://github.com/clasen/WhisperMix/issues"
-    },
-    "dependencies": {
-        "@huggingface/transformers": "^4.2.0",
-        "audio-decode": "^2.2.3",
-        "bottleneck": "^2.19.5",
-        "fluent-ffmpeg": "^2.1.3",
-        "get-audio-duration": "^4.0.1",
-        "onnx-asr-web": "^0.1.3"
-    },
-    "devDependencies": {
-        "node-addon-api": "^8.7.0",
-        "node-gyp": "^12.3.0"
-    },
-    "packageManager": "pnpm@11.1.2"
-}
+  "name": "whispermix",
+  "description": "🎙️ WhisperMix is a versatile module for transcribing audio using OpenAI’s Whisper or Groq’s Whisper v3 model.",
+  "version": "1.6.2",
+  "type": "module",
+  "keywords": [
+    "whisper",
+    "openai",
+    "groq",
+    "transcription",
+    "speech-to-text",
+    "audio",
+    "voice",
+    "ai",
+    "machine-learning",
+    "nlp",
+    "natural-language-processing",
+    "audio-processing",
+    "voice-recognition",
+    "speech-recognition",
+    "api-wrapper",
+    "whisper-large-v3",
+    "whisper-1",
+    "streaming",
+    "file-processing",
+    "multilingual",
+    "bottleneck",
+    "chunk",
+    "clasen",
+    "local",
+    "xenova",
+    "parakeet",
+    "nvidia",
+    "onnx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clasen/WhisperMix.git"
+  },
+  "main": "index.js",
+  "author": "Martin Clasen",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/clasen/WhisperMix/issues"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "audio-decode": "^2.2.3",
+    "bottleneck": "^2.19.5",
+    "fluent-ffmpeg": "^2.1.3",
+    "get-audio-duration": "^4.0.1",
+    "onnx-asr-web": "^0.1.3"
+  },
+  "devDependencies": {
+    "node-addon-api": "^8.7.0",
+    "node-gyp": "^12.3.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}