@clipkit/speech-to-text 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Clipkit Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,57 @@
+# @clipkit/speech-to-text
+
+Transcribe an audio/video source into **word-timestamped captions** for Clipkit.
+
+One Whisper model (via [Transformers.js](https://github.com/huggingface/transformers.js) / ONNX) runs the **same** in the browser (WebGPU/WASM) and in Node (`onnxruntime-node`) — no paid API, no native binaries, MIT-licensed weights. The output maps straight onto the protocol's `caption` element `words[]`.
+
+**Authoring-time only.** The runtime never sees this package — it just renders the `words[]` we produce. The protocol is unchanged; this is the layer that *fills* a caption.
+
+## Pipeline
+
+```
+audio/video file ──decode──▶ 16 kHz mono PCM ──transcribe──▶ TranscriptResult ──toCaptionWords──▶ caption.words[]
+                  (env-specific)               (Whisper/ONNX)                   (the protocol bridge)
+```
+
+- **`transcribe(audio, opts?)`** — 16 kHz mono PCM → word-timestamped transcript. Env-agnostic.
+- **`toCaptionWords(result, opts?)`** — transcript → `caption` element `words[]`. Pure; the one place this meets the protocol.
+- **Audio decode is env-specific** — import from the matching entry point.
+
+## Node
+
+```ts
+import { transcribe, toCaptionWords } from '@clipkit/speech-to-text';
+import { decodeAudioFile } from '@clipkit/speech-to-text/node'; // needs ffmpeg on PATH
+
+const audio = await decodeAudioFile('clip.mp4');
+const result = await transcribe(audio, { model: 'Xenova/whisper-base' });
+const words = toCaptionWords(result);
+// → a caption element:  { type: 'caption', time: 0, track: 3, words }
+```
+
+## Browser
+
+```ts
+import { transcribe, toCaptionWords } from '@clipkit/speech-to-text';
+import { decodeAudioBlob } from '@clipkit/speech-to-text/browser'; // WebAudio
+
+const audio = await decodeAudioBlob(file);            // a File/Blob
+const result = await transcribe(audio);               // WebGPU when available
+```
+
+## Models
+
+`model` is any Whisper variant on the Hugging Face hub; default `Xenova/whisper-base`. Trade size/speed for accuracy: `whisper-tiny(.en)` (~40 MB, fast) → `whisper-base` → `whisper-small` (~250 MB). `.en` variants are English-only and faster. The model downloads once and is cached (browser cache / Node fs).
+
+## Notes
+
+- **Word timestamps** use Whisper's `return_timestamps: 'word'`. Quality scales with model size; for tight sync, prefer `base`/`small`.
+- **`offset`** on `toCaptionWords` shifts absolute audio times to be relative to the caption element's `time` (the protocol stores word times relative to the element).
+- On Node, `onnxruntime-node` may print a harmless `mutex lock failed` line during process **teardown** (after results are produced) — an upstream thread-pool cleanup quirk, not a transcription error.
+
+## Verify
+
+```
+npm run build && node --test test/caption.test.mjs   # protocol bridge (fast, no model)
+node test/smoke.mjs [file]                            # end-to-end (downloads a model)
+```

package/dist/audio.browser.d.ts

@@ -0,0 +1,9 @@
+import type { MonoAudio } from './types.js';
+/**
+ * Decode audio bytes (any format the browser supports — mp4/mov/mp3/wav/webm)
+ * to 16 kHz mono float PCM. Pass a File/Blob's ArrayBuffer.
+ */
+export declare function decodeAudioData(data: ArrayBuffer): Promise<MonoAudio>;
+/** Convenience: decode a File/Blob directly. */
+export declare function decodeAudioBlob(blob: Blob): Promise<MonoAudio>;
+//# sourceMappingURL=audio.browser.d.ts.map

package/dist/audio.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.browser.d.ts","sourceRoot":"","sources":["../src/audio.browser.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAa3E;AAED,gDAAgD;AAChD,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAEpE"}

package/dist/audio.browser.js

@@ -0,0 +1,29 @@
+// Browser audio extraction — a File/Blob/ArrayBuffer (audio or video) → 16 kHz
+// mono PCM, via WebAudio's OfflineAudioContext (decode + resample in one pass).
+// The only browser-specific piece; the engine itself is env-agnostic.
+//
+// Import path: `@clipkit/speech-to-text/browser`.
+const SAMPLE_RATE = 16000;
+/**
+ * Decode audio bytes (any format the browser supports — mp4/mov/mp3/wav/webm)
+ * to 16 kHz mono float PCM. Pass a File/Blob's ArrayBuffer.
+ */
+export async function decodeAudioData(data) {
+    // Decode at native rate first (decodeAudioData needs a real context), then
+    // resample to 16 kHz mono with an OfflineAudioContext render pass.
+    const tmp = new OfflineAudioContext(1, 1, 44100);
+    const decoded = await tmp.decodeAudioData(data.slice(0));
+    const frames = Math.ceil(decoded.duration * SAMPLE_RATE);
+    const offline = new OfflineAudioContext(1, Math.max(1, frames), SAMPLE_RATE);
+    const src = offline.createBufferSource();
+    src.buffer = decoded;
+    src.connect(offline.destination);
+    src.start();
+    const rendered = await offline.startRendering();
+    return { samples: rendered.getChannelData(0).slice(), sampleRate: SAMPLE_RATE };
+}
+/** Convenience: decode a File/Blob directly. */
+export async function decodeAudioBlob(blob) {
+    return decodeAudioData(await blob.arrayBuffer());
+}
+//# sourceMappingURL=audio.browser.js.map

package/dist/audio.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.browser.js","sourceRoot":"","sources":["../src/audio.browser.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gFAAgF;AAChF,sEAAsE;AACtE,EAAE;AACF,kDAAkD;AAIlD,MAAM,WAAW,GAAG,KAAK,CAAC;AAE1B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAiB;IACrD,2EAA2E;IAC3E,mEAAmE;IACnE,MAAM,GAAG,GAAG,IAAI,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,WAAW,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IACzC,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC;IACrB,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACjC,GAAG,CAAC,KAAK,EAAE,CAAC;IACZ,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAChD,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;AAClF,CAAC;AAED,gDAAgD;AAChD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAU;IAC9C,OAAO,eAAe,CAAC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AACnD,CAAC"}

package/dist/audio.node.d.ts

@@ -0,0 +1,7 @@
+import type { MonoAudio } from './types.js';
+/**
+ * Decode an audio/video file to 16 kHz mono float PCM. Requires `ffmpeg` on PATH.
+ * Works for any container ffmpeg reads (mp4, mov, mp3, wav, m4a, webm, …).
+ */
+export declare function decodeAudioFile(path: string): Promise<MonoAudio>;
+//# sourceMappingURL=audio.node.d.ts.map

package/dist/audio.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.node.d.ts","sourceRoot":"","sources":["../src/audio.node.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAsBtE"}

package/dist/audio.node.js

@@ -0,0 +1,36 @@
+// Node audio extraction — any audio/video file → 16 kHz mono PCM, via the
+// system `ffmpeg` (already a Clipkit toolchain dependency). This is the only
+// Node-specific piece; the transcription engine itself is env-agnostic.
+//
+// Import path: `@clipkit/speech-to-text/node`.
+import { spawn } from 'node:child_process';
+const SAMPLE_RATE = 16000;
+/**
+ * Decode an audio/video file to 16 kHz mono float PCM. Requires `ffmpeg` on PATH.
+ * Works for any container ffmpeg reads (mp4, mov, mp3, wav, m4a, webm, …).
+ */
+export async function decodeAudioFile(path) {
+    // -f f32le: raw 32-bit float little-endian; -ac 1: mono; -ar 16000: 16 kHz.
+    const args = ['-i', path, '-f', 'f32le', '-ac', '1', '-ar', String(SAMPLE_RATE), '-hide_banner', '-loglevel', 'error', 'pipe:1'];
+    const chunks = [];
+    const errChunks = [];
+    await new Promise((resolve, reject) => {
+        const ff = spawn('ffmpeg', args);
+        ff.stdout.on('data', (d) => chunks.push(d));
+        ff.stderr.on('data', (d) => errChunks.push(d));
+        ff.on('error', (e) => reject(new Error(`ffmpeg failed to start (is it installed?): ${e.message}`)));
+        ff.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`ffmpeg exited ${code}: ${Buffer.concat(errChunks).toString().trim()}`));
+        });
+    });
+    const buf = Buffer.concat(chunks);
+    // Float32 view over the raw bytes (copy into an aligned ArrayBuffer).
+    const samples = new Float32Array(buf.byteLength / 4);
+    for (let i = 0; i < samples.length; i++)
+        samples[i] = buf.readFloatLE(i * 4);
+    return { samples, sampleRate: SAMPLE_RATE };
+}
+//# sourceMappingURL=audio.node.js.map

package/dist/audio.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.node.js","sourceRoot":"","sources":["../src/audio.node.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,wEAAwE;AACxE,EAAE;AACF,+CAA+C;AAE/C,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C,MAAM,WAAW,GAAG,KAAK,CAAC;AAE1B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IAChD,4EAA4E;IAC5E,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,cAAc,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACjI,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACjC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QACpG,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACtB,IAAI,IAAI,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAC;;gBACrB,MAAM,CAAC,IAAI,KAAK,CAAC,iBAAiB,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QACjG,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,sEAAsE;IACtE,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IACrD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;AAC9C,CAAC"}

package/dist/caption.d.ts

@@ -0,0 +1,55 @@
+import type { CaptionWord } from '@clipkit/protocol';
+import type { TranscriptResult, TranscriptWord } from './types.js';
+export interface ToCaptionWordsOptions {
+    /**
+     * Seconds of source audio that the caption element's `time` corresponds to —
+     * i.e. where the element starts on the timeline, in the audio's clock. Word
+     * timings are shifted by `-offset` so they read relative to the element.
+     * Default 0 (the caption element starts at the audio's start).
+     */
+    offset?: number;
+    /** Drop words shorter than this many seconds (model noise). Default 0. */
+    minDuration?: number;
+}
+/** Map a transcript's words onto a `caption` element's `words[]` (§ protocol). */
+export declare function toCaptionWords(result: TranscriptResult, options?: ToCaptionWordsOptions): CaptionWord[];
+/** Convenience: the full caption-element fields ready to spread into an element. */
+export declare function toCaptionFields(result: TranscriptResult, options?: ToCaptionWordsOptions): {
+    type: 'caption';
+    words: CaptionWord[];
+};
+/** One caption-sized phrase: where it starts in the audio, plus its words. */
+export interface CaptionSegment {
+    /** Absolute start of the segment in the source audio (seconds). */
+    start: number;
+    /** Words, times RELATIVE to this segment's `start` (ready for a caption element). */
+    words: CaptionWord[];
+}
+export interface ToCaptionSegmentsOptions {
+    /** Max words per segment. Default 6. */
+    maxWords?: number;
+    /** A silent gap (seconds) between words at/above this starts a new segment. Default 0.6. */
+    maxGap?: number;
+    /** Max segment duration (seconds) before forcing a break. Default 3. */
+    maxDuration?: number;
+}
+/**
+ * Group timed words into caption-sized PHRASES. A new phrase starts when the
+ * current one hits `maxWords`, a silent gap ≥ `maxGap` opens, or it exceeds
+ * `maxDuration`. Pure and generic — the single source of truth for "how big is
+ * a caption segment," shared by transcription and the editor's manual split.
+ */
+export declare function segmentWords<T extends {
+    start: number;
+    end: number;
+}>(words: readonly T[], options?: ToCaptionSegmentsOptions): T[][];
+/**
+ * Split a transcript into caption-sized PHRASES — one `caption` element each.
+ * A whole-video transcript renders as an unreadable single line; segmenting it
+ * into short phrases is how real auto-captions display. Each segment's words are
+ * rebased to its own `start`, ready to drop into a `caption` element at
+ * `time = mediaStart + segment.start`.
+ */
+export declare function toCaptionSegments(result: TranscriptResult, options?: ToCaptionSegmentsOptions): CaptionSegment[];
+export type { TranscriptResult, TranscriptWord };
+//# sourceMappingURL=caption.d.ts.map

package/dist/caption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caption.d.ts","sourceRoot":"","sources":["../src/caption.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,qBAA0B,GAClC,WAAW,EAAE,CAYf;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,qBAA0B,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE,CAE3C;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACnE,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,GAAE,wBAA6B,GACrC,CAAC,EAAE,EAAE,CAcP;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,wBAA6B,GACrC,cAAc,EAAE,CASlB;AAED,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC"}

package/dist/caption.js

@@ -0,0 +1,70 @@
+// The protocol bridge — the ONE place transcription meets the Clipkit protocol.
+//
+// A `caption` element's `words` are `{ text, start, end }` with start/end in
+// seconds RELATIVE TO THE ELEMENT'S `time` (PROTOCOL.md §5.x). Transcript words
+// are absolute in the source audio, so mapping is: subtract the element's start
+// offset, clamp to ≥ 0 (the schema requires nonnegative), drop empties.
+//
+// This file imports only the protocol's `CaptionWord` type — no model, no audio.
+// It's pure and the part that's verified against the schema.
+/** Map a transcript's words onto a `caption` element's `words[]` (§ protocol). */
+export function toCaptionWords(result, options = {}) {
+    const { offset = 0, minDuration = 0 } = options;
+    const out = [];
+    for (const w of result.words) {
+        const text = w.text.trim();
+        if (!text)
+            continue;
+        const start = Math.max(0, w.start - offset);
+        const end = Math.max(start, w.end - offset);
+        if (end - start < minDuration)
+            continue;
+        out.push({ text, start, end });
+    }
+    return out;
+}
+/** Convenience: the full caption-element fields ready to spread into an element. */
+export function toCaptionFields(result, options = {}) {
+    return { type: 'caption', words: toCaptionWords(result, options) };
+}
+/**
+ * Group timed words into caption-sized PHRASES. A new phrase starts when the
+ * current one hits `maxWords`, a silent gap ≥ `maxGap` opens, or it exceeds
+ * `maxDuration`. Pure and generic — the single source of truth for "how big is
+ * a caption segment," shared by transcription and the editor's manual split.
+ */
+export function segmentWords(words, options = {}) {
+    const { maxWords = 6, maxGap = 0.6, maxDuration = 3 } = options;
+    const groups = [];
+    let cur = [];
+    const flush = () => { if (cur.length > 0)
+        groups.push(cur); cur = []; };
+    for (const w of words) {
+        if (cur.length > 0) {
+            const prev = cur[cur.length - 1];
+            if (cur.length >= maxWords || w.start - prev.end >= maxGap || w.end - cur[0].start > maxDuration)
+                flush();
+        }
+        cur.push(w);
+    }
+    flush();
+    return groups;
+}
+/**
+ * Split a transcript into caption-sized PHRASES — one `caption` element each.
+ * A whole-video transcript renders as an unreadable single line; segmenting it
+ * into short phrases is how real auto-captions display. Each segment's words are
+ * rebased to its own `start`, ready to drop into a `caption` element at
+ * `time = mediaStart + segment.start`.
+ */
+export function toCaptionSegments(result, options = {}) {
+    const words = result.words.filter((w) => w.text.trim().length > 0);
+    return segmentWords(words, options).map((group) => {
+        const base = group[0].start;
+        return {
+            start: base,
+            words: group.map((w) => ({ text: w.text.trim(), start: Math.max(0, w.start - base), end: Math.max(0, w.end - base) })),
+        };
+    });
+}
+//# sourceMappingURL=caption.js.map

package/dist/caption.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { transcribe, type TranscribeOptions, type WhisperModel } from './transcribe.js';
+export { toCaptionWords, toCaptionFields, toCaptionSegments, segmentWords, type ToCaptionWordsOptions, type ToCaptionSegmentsOptions, type CaptionSegment } from './caption.js';
+export type { TranscriptResult, TranscriptWord, MonoAudio } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAAE,KAAK,qBAAqB,EAAE,KAAK,wBAAwB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAChL,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+// @clipkit/speech-to-text — transcribe an audio/video source into word-
+// timestamped captions. One Whisper model (Transformers.js / ONNX) runs in the
+// browser and in Node; no paid API. The output maps onto the protocol's
+// `caption` element via `toCaptionWords`. Authoring-time only — the runtime
+// never sees this; it just renders the `words[]` we produce.
+//
+//   transcribe(audio)        → word-timestamped transcript
+//   toCaptionWords(result)   → caption element words[]  (the protocol bridge)
+//
+// Audio decoding is env-specific — import from the matching entry point:
+//   Node:    import { decodeAudioFile } from '@clipkit/speech-to-text/node';
+//   Browser: import { decodeAudioBlob } from '@clipkit/speech-to-text/browser';
+export { transcribe } from './transcribe.js';
+export { toCaptionWords, toCaptionFields, toCaptionSegments, segmentWords } from './caption.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAC/E,wEAAwE;AACxE,4EAA4E;AAC5E,6DAA6D;AAC7D,EAAE;AACF,2DAA2D;AAC3D,8EAA8E;AAC9E,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,gFAAgF;AAEhF,OAAO,EAAE,UAAU,EAA6C,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAAkF,MAAM,cAAc,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,3 @@
+export { decodeAudioFile } from './audio.node.js';
+export { transcribeFile, type TranscribeFileOptions } from './transcribe-file.node.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/node.js

@@ -0,0 +1,6 @@
+// Node entry — `@clipkit/speech-to-text/node`. Audio extraction (ffmpeg) plus
+// the safe one-call `transcribeFile` (worker-isolated). The model engine and the
+// protocol bridge stay env-agnostic on the main export.
+export { decodeAudioFile } from './audio.node.js';
+export { transcribeFile } from './transcribe-file.node.js';
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,iFAAiF;AACjF,wDAAwD;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,cAAc,EAA8B,MAAM,2BAA2B,CAAC"}

package/dist/transcribe-file.node.d.ts

@@ -0,0 +1,16 @@
+import type { TranscriptResult } from './types.js';
+export interface TranscribeFileOptions {
+    /** Whisper model id (Hugging Face). Default 'Xenova/whisper-base'. */
+    model?: string;
+    /** Force a language (e.g. 'en'); omit to auto-detect. */
+    language?: string;
+    /** Streamed worker stderr (model-download progress lines). */
+    onLog?: (line: string) => void;
+}
+/**
+ * Transcribe an audio/video file → word-timestamped transcript. Requires
+ * `ffmpeg` on PATH. Runs the model in an isolated worker, so a long-running
+ * caller (MCP server) stays alive regardless of the model runtime's teardown.
+ */
+export declare function transcribeFile(file: string, options?: TranscribeFileOptions): Promise<TranscriptResult>;
+//# sourceMappingURL=transcribe-file.node.d.ts.map

package/dist/transcribe-file.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe-file.node.d.ts","sourceRoot":"","sources":["../src/transcribe-file.node.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuB3G"}

package/dist/transcribe-file.node.js

@@ -0,0 +1,38 @@
+// transcribeFile — the safe, one-call Node entry: decode + transcribe a file,
+// returning a TranscriptResult. The model runs in a worker subprocess so the
+// caller's process is never touched by onnxruntime-node's teardown abort. Both
+// the CLI and the MCP server use this; neither has to know about the quirk.
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const WORKER = fileURLToPath(new URL('./worker.js', import.meta.url));
+/**
+ * Transcribe an audio/video file → word-timestamped transcript. Requires
+ * `ffmpeg` on PATH. Runs the model in an isolated worker, so a long-running
+ * caller (MCP server) stays alive regardless of the model runtime's teardown.
+ */
+export function transcribeFile(file, options = {}) {
+    const { model, language, onLog } = options;
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [WORKER, JSON.stringify({ file, model, language })], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let out = '';
+        child.stdout.on('data', (d) => { out += d.toString(); });
+        child.stderr.on('data', (d) => onLog?.(d.toString()));
+        child.on('error', reject);
+        child.on('close', () => {
+            const trimmed = out.trim();
+            if (!trimmed) {
+                reject(new Error('transcription produced no output (check ffmpeg + the file)'));
+                return;
+            }
+            try {
+                resolve(JSON.parse(trimmed));
+            }
+            catch {
+                reject(new Error('transcription output was not valid JSON'));
+            }
+        });
+    });
+}
+//# sourceMappingURL=transcribe-file.node.js.map

package/dist/transcribe-file.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe-file.node.js","sourceRoot":"","sources":["../src/transcribe-file.node.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAE5E,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAWtE;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,UAAiC,EAAE;IAC9E,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC3C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE;YACzF,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;QACH,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,GAAG,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC9D,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACrB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC,CAAC;gBAChF,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAqB,CAAC,CAAC;YACnD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/transcribe.d.ts

@@ -0,0 +1,27 @@
+import type { MonoAudio, TranscriptResult } from './types.js';
+/** Whisper variants — size/speed/accuracy trade-off. `.en` are English-only. */
+export type WhisperModel = 'Xenova/whisper-tiny' | 'Xenova/whisper-tiny.en' | 'Xenova/whisper-base' | 'Xenova/whisper-base.en' | 'Xenova/whisper-small' | 'Xenova/whisper-small.en' | (string & {});
+export interface TranscribeOptions {
+    /** Model id (Hugging Face). Default 'Xenova/whisper-base'. */
+    model?: WhisperModel;
+    /** Force a language (e.g. 'en'); omit to auto-detect. Multilingual models only. */
+    language?: string;
+    /** Quantized weights — smaller download, slightly lower accuracy. Default true. */
+    quantized?: boolean;
+    /** Progress callback (model download). `progress` is 0..100 where known. */
+    onProgress?: (info: {
+        status: string;
+        file?: string;
+        progress?: number;
+    }) => void;
+}
+/**
+ * Transcribe 16 kHz mono PCM into a word-timestamped transcript.
+ *
+ * @example
+ * const audio = await decodeAudioFile('clip.mp4'); // from '@clipkit/speech-to-text/node'
+ * const result = await transcribe(audio);
+ * const words = toCaptionWords(result);            // → caption element words[]
+ */
+export declare function transcribe(audio: MonoAudio, options?: TranscribeOptions): Promise<TranscriptResult>;
+//# sourceMappingURL=transcribe.d.ts.map

package/dist/transcribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe.d.ts","sourceRoot":"","sources":["../src/transcribe.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAkB,MAAM,YAAY,CAAC;AAe9E,gFAAgF;AAChF,MAAM,MAAM,YAAY,GACpB,qBAAqB,GACrB,wBAAwB,GACxB,qBAAqB,GACrB,wBAAwB,GACxB,sBAAsB,GACtB,yBAAyB,GACzB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACnF;AAoBD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CA4B3B"}

package/dist/transcribe.js

@@ -0,0 +1,58 @@
+// The transcription engine — Whisper via Transformers.js (ONNX). The SAME model
+// runs in the browser (WebGPU/WASM) and in Node (onnxruntime-node); the library
+// picks the provider for the environment, so this file is env-agnostic.
+//
+// Input is always 16 kHz mono PCM (Float32). Output is a word-timestamped
+// transcript. Map it onto the protocol with `toCaptionWords` (caption.ts).
+import { pipeline as rawPipeline } from '@huggingface/transformers';
+const pipeline = rawPipeline;
+const SAMPLE_RATE = 16000;
+// One cached pipeline per model id — loading is expensive; reuse across calls.
+const pipelines = new Map();
+function getPipeline(model, quantized, onProgress) {
+    const key = `${model}:${quantized}`;
+    let p = pipelines.get(key);
+    if (!p) {
+        p = pipeline('automatic-speech-recognition', model, {
+            dtype: quantized ? 'q8' : 'fp32',
+            progress_callback: onProgress,
+        });
+        pipelines.set(key, p);
+    }
+    return p;
+}
+/**
+ * Transcribe 16 kHz mono PCM into a word-timestamped transcript.
+ *
+ * @example
+ * const audio = await decodeAudioFile('clip.mp4'); // from '@clipkit/speech-to-text/node'
+ * const result = await transcribe(audio);
+ * const words = toCaptionWords(result);            // → caption element words[]
+ */
+export async function transcribe(audio, options = {}) {
+    const { model = 'Xenova/whisper-base', language, quantized = true, onProgress } = options;
+    if (audio.sampleRate !== SAMPLE_RATE) {
+        throw new Error(`transcribe: audio must be ${SAMPLE_RATE} Hz mono (got ${audio.sampleRate} Hz). Decode via '@clipkit/speech-to-text/node' or '/browser'.`);
+    }
+    const asr = await getPipeline(model, quantized, onProgress);
+    const out = await asr(audio.samples, {
+        return_timestamps: 'word',
+        chunk_length_s: 30,
+        stride_length_s: 5,
+        language,
+    });
+    const chunks = out.chunks ?? [];
+    const words = chunks.map((c, i) => {
+        const start = c.timestamp[0] ?? 0;
+        // The last word can have a null end; fall back to the next word's start or +0.3s.
+        const end = c.timestamp[1] ?? (chunks[i + 1]?.timestamp[0] ?? start + 0.3);
+        return { text: c.text.trim(), start, end };
+    }).filter((w) => w.text.length > 0);
+    return {
+        text: (out?.text ?? '').trim(),
+        words,
+        language,
+        duration: audio.samples.length / SAMPLE_RATE,
+    };
+}
+//# sourceMappingURL=transcribe.js.map

package/dist/transcribe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe.js","sourceRoot":"","sources":["../src/transcribe.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,gFAAgF;AAChF,wEAAwE;AACxE,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAE3E,OAAO,EAAE,QAAQ,IAAI,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAUpE,MAAM,QAAQ,GAAG,WAIE,CAAC;AAuBpB,MAAM,WAAW,GAAG,KAAK,CAAC;AAE1B,+EAA+E;AAC/E,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEpD,SAAS,WAAW,CAAC,KAAa,EAAE,SAAkB,EAAE,UAA4C;IAClG,MAAM,GAAG,GAAG,GAAG,KAAK,IAAI,SAAS,EAAE,CAAC;IACpC,IAAI,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,CAAC,GAAG,QAAQ,CAAC,8BAA8B,EAAE,KAAK,EAAE;YAClD,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;YAChC,iBAAiB,EAAE,UAAU;SAC9B,CAAC,CAAC;QACH,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAgB,EAChB,UAA6B,EAAE;IAE/B,MAAM,EAAE,KAAK,GAAG,qBAAqB,EAAE,QAAQ,EAAE,SAAS,GAAG,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC1F,IAAI,KAAK,CAAC,UAAU,KAAK,WAAW,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,6BAA6B,WAAW,iBAAiB,KAAK,CAAC,UAAU,gEAAgE,CAAC,CAAC;IAC7J,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE;QACnC,iBAAiB,EAAE,MAAM;QACzB,cAAc,EAAE,EAAE;QAClB,eAAe,EAAE,CAAC;QAClB,QAAQ;KACT,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;IAChC,MAAM,KAAK,GAAqB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAClD,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClC,kFAAkF;QAClF,MAAM,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,GAAG,CAAC,CAAC;QAC3E,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEpC,OAAO;QACL,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QAC9B,KAAK;QACL,QAAQ;QACR,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,WAAW;KAC7C,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/** One transcribed word with absolute timings in the source audio. */
+export interface TranscriptWord {
+    text: string;
+    /** Seconds from the start of the transcribed audio. */
+    start: number;
+    /** Seconds from the start of the transcribed audio. */
+    end: number;
+}
+/** The result of transcribing an audio buffer. */
+export interface TranscriptResult {
+    /** The full transcript, untimed. */
+    text: string;
+    /** Word-level transcript with timings. */
+    words: TranscriptWord[];
+    /** Detected (or forced) BCP-47-ish language code, when the model reports one. */
+    language?: string;
+    /** Length of the transcribed audio, in seconds. */
+    duration: number;
+}
+/** 16 kHz mono PCM — the canonical model input. */
+export interface MonoAudio {
+    /** Samples in [-1, 1]. */
+    samples: Float32Array;
+    /** Sample rate in Hz. MUST be 16000 for the model. */
+    sampleRate: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAOA,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,0BAA0B;IAC1B,OAAO,EAAE,YAAY,CAAC;IACtB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,8 @@
+// Core transcription types. Environment- and model-agnostic.
+//
+// The audio fed to the model is always 16 kHz mono PCM (Float32, samples in
+// [-1, 1]) — Whisper's canonical input. How you GET there (ffmpeg in Node,
+// WebAudio in the browser) is the only env-specific concern; see `./node` and
+// `./browser`.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,8EAA8E;AAC9E,eAAe"}

package/dist/worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":""}

package/dist/worker.js

@@ -0,0 +1,26 @@
+// Internal worker entry. Runs in its OWN process so onnxruntime-node's harmless
+// `mutex lock failed` teardown abort can never take down the caller (CLI, MCP
+// server, editor build). Decodes + transcribes one file, prints the
+// TranscriptResult as JSON to stdout, then exits. Not a public export — invoked
+// by `transcribeFile` (transcribe-file.node.ts).
+//
+//   node dist/worker.js '{"file":"clip.mp4","model":"Xenova/whisper-base"}'
+import { transcribe } from './transcribe.js';
+import { decodeAudioFile } from './audio.node.js';
+const input = JSON.parse(process.argv[2] ?? '{}');
+const audio = await decodeAudioFile(input.file);
+const seen = new Set();
+const result = await transcribe(audio, {
+    model: input.model,
+    language: input.language,
+    // Surface model-download progress on stderr (stdout is reserved for the JSON
+    // result); the caller streams these via `transcribeFile`'s onLog.
+    onProgress: (i) => {
+        if (i.status === 'initiate' && i.file && !seen.has(i.file)) {
+            seen.add(i.file);
+            process.stderr.write(`  ↓ ${i.file}\n`);
+        }
+    },
+});
+process.stdout.write(JSON.stringify(result), () => process.exit(0));
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,8EAA8E;AAC9E,oEAAoE;AACpE,gFAAgF;AAChF,iDAAiD;AACjD,EAAE;AACF,4EAA4E;AAE5E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAQlD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAgB,CAAC;AACjE,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAChD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;AAC/B,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE;IACrC,KAAK,EAAE,KAAK,CAAC,KAAK;IAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;IACxB,6EAA6E;IAC7E,kEAAkE;IAClE,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE;QAChB,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3D,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@clipkit/speech-to-text",
+  "version": "1.0.0",
+  "description": "Speech-to-text for Clipkit — transcribe an audio/video source into word-timestamped captions. Runs the same Whisper model (Transformers.js / ONNX) in the browser (WebGPU/WASM) and in Node (onnxruntime-node); no paid API, no native binaries. The output maps straight onto the protocol's `caption` element `words[]`. Authoring-time only: the runtime stays pure.",
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/clipkit-video/clipkit.git", "directory": "packages/speech-to-text" },
+  "homepage": "https://clipkit.dev",
+  "bugs": "https://github.com/clipkit-video/clipkit/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./caption": {
+      "import": "./dist/caption.js",
+      "types": "./dist/caption.d.ts"
+    },
+    "./node": {
+      "import": "./dist/node.js",
+      "types": "./dist/node.d.ts"
+    },
+    "./browser": {
+      "import": "./dist/audio.browser.js",
+      "types": "./dist/audio.browser.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@clipkit/protocol": "^1.0.0",
+    "@huggingface/transformers": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.3"
+  }
+}