@twkevinzhang/lyric-align-ts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lyric-align-ts contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @twkevinzhang/lyric-align-ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+瀏覽器端 Whisper ASR 與歌詞對齊，提供 contract v1 的 session API。ES module only；推論在 session 專用 module Worker 執行。
+
+## 使用
+
+```sh
+npm install @twkevinzhang/lyric-align-ts
+```
+
+```ts
+import { binding } from '@twkevinzhang/lyric-align-ts';
+
+const controller = new AbortController();
+const context = { signal: controller.signal, onProgress: console.log };
+const session = await binding.createSession();
+try {
+  await session.prepare({ language: 'en' }, context);
+  const segments = await session.transcribe(
+    { pcm, sampleRate: 16000 }, // 完整、單聲道、有限數值 Float32Array
+    { language: 'en' },
+    context,
+  );
+  const lines = await session.align(segments, lyrics, { karaoke: false }, context);
+  // 整首驗證成功後才套用字幕，所有時間為秒。
+} finally {
+  await session.dispose();
+}
+```
+
+`pcm`、逐行 `lyrics` 由應用提供。套件不下載音訊、不控制播放器、不建立字幕或 SRT。空白行由應用保留於原文、排除於 align 輸入；其他行逐字保留、不插補。消費端須驗證全部行數、順序、原文、匹配與時間界限後才一次套用，score 是文字相似度，不是時間準確率。
+
+預設 WebGPU，固定 `onnx-community/whisper-small.en_timestamped`、revision `8085393831131554ad978a4e438295a734d3d2c0`、q4，僅支援 `en`。另可 `createBinding({ device: 'wasm' })` 明確選擇既有 WASM 配置，不自動 fallback。`capabilities.lyricsContext=false`，不要傳歌詞提示。支援 pairing、threshold、window、karaoke=false；預設 auto／window4／文字門檻。
+
+## 執行環境與資源
+
+需要支援 module Worker、WebAssembly 及所選後端的桌面瀏覽器、安全來源與足夠記憶體。這不是 Node.js 推論套件。包內含固定版 Transformers.js、ONNX Runtime Web 與壓縮 runtime，沒有額外 npm runtime dependencies。模型權重不含於 npm 包，prepare 首次向 Hugging Face 下載固定 revision 並由瀏覽器快取；音訊及歌詞不會上傳至推論服務。
+
+使用支援 Worker／`new URL(..., import.meta.url)` 資源處理的 bundler。若直接靜態載入，完整複製安裝目錄並保留 index.js 與 assets/ 的相對路徑。其他 bundler、extension offscreen/CSP 需自行驗證。host 啟用 COEP 時，Worker 回應必須使用相符 header；CSP 與 host permissions 必須允許 Worker、WASM、模型取得及 runtime 必要資源。
+
+## 生命週期
+
+同 session 依序等待 prepare → transcribe → align，不並行。`controller.abort()` 終止專用 Worker，操作拒絕 `{ code: 'ABORTED', message }`；等待操作結束後再 dispose，重試另建 session。dispose 可重複呼叫，操作尚未結束時會拒絕提前 dispose。
+
+錯誤為 `{ code, message }`。進度階段為 preparing-model、transcribing、aligning；sequence 在每次操作內從 1 遞增。有實測 total 才回報 measured（bytes/items 及 scope），否則為 indeterminate，不應推估百分比。
+
+## 驗證與限制
+
+Chrome WebGPU 真實完整 130.30 秒英文音訊：6 ASR 段、12/12 行合法匹配，原文與順序保持；真實推論中途取消及重複 dispose 已測。這不是任意歌曲品質承諾。WASM 核心另有既有驗證，但不代表已重測 npm 安裝後的 WASM 全曲、其他硬體或消費端 extension。
+
+原創程式碼採 MIT；衍生演算法與內含依賴保留各自授權。詳見 LICENSE、THIRD_PARTY_NOTICES.md 與 licenses/。模型權重另外受模型來源授權約束。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,17 @@
+# Third-party notices
+
+The MIT license for lyric-align-ts applies to original project code. Third-party code retains its own license. Dependencies are bundled in the Worker artifact.
+
+| Component | Version / source | License / notice |
+| --- | --- | --- |
+| lyric-align rules (TypeScript adaptation) | ebe62d8a8628d0b2579987598f0442ebffcc68bb | licenses/upstream.LICENSE (MIT) |
+| faster-whisper / CTranslate2 rules (TypeScript adaptation) | 1.2.1 / 4.8.3 | licenses/asr-upstream.LICENSE (MIT) |
+| Transformers.js | 4.3.1 | licenses/transformers.LICENSE (Apache-2.0) |
+| Hugging Face tokenizers / jinja (included in Transformers.js browser bundle) | 0.2.0 / 0.5.10 | licenses/tokenizers.LICENSE (Apache-2.0), licenses/jinja.LICENSE (MIT) |
+| ONNX Runtime Web | 1.31.0-dev.20260914-8d85527a0 | licenses/onnxruntime.LICENSE (MIT), licenses/onnxruntime.NOTICE |
+| ONNX Runtime Common | 1.30.0 and Web runtime's 1.31.0-dev.20260911-2a43ec07e | licenses/onnxruntime.LICENSE (MIT) |
+| pako | 3.0.2 | licenses/pako.LICENSE (MIT), licenses/pako-zlib.LICENSE (Zlib) |
+
+ONNX Runtime notices are preserved from upstream commit 8d85527a010e294a26b274749f74294b2a32cec5. The complete upstream notice file covers multiple distributions and may list components not used by this browser build.
+
+Model weights are not distributed in this package. The fixed Hugging Face revision is downloaded separately at prepare time; consult the model repository for its license. The upstream Python/C++ libraries are not executed by this TypeScript adaptation.

package/assets/worker-CNw7yNoM.js

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/assets/worker-CNw7yNoM.js
+size: 72223391 bytes
+sha256: ddf0d50e0489cf472a47370b960743c4777837074859c73e0985713cb18b62f0

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./types/binding/index.js";

package/index.js

@@ -0,0 +1,130 @@
+// app/lib/protocol.ts
+var e = {
+	id: "onnx-community/whisper-small.en_timestamped",
+	revision: "8085393831131554ad978a4e438295a734d3d2c0"
+};
+// app/lib/binding/errors.ts
+function t(e, t) {
+	return {
+		code: e,
+		message: t
+	};
+}
+var n = [
+	"UNSUPPORTED_LANGUAGE",
+	"UNSUPPORTED_DEVICE",
+	"UNSUPPORTED_OPTION",
+	"MODEL_LOAD_FAILED",
+	"INVALID_INPUT",
+	"OUT_OF_MEMORY",
+	"TRANSCRIPTION_FAILED",
+	"ALIGNMENT_FAILED",
+	"ABORTED"
+];
+function r(e, r) {
+	if (e && typeof e == "object" && "code" in e && n.includes(String(e.code)) && "message" in e && typeof e.message == "string") return e;
+	let i = e instanceof Error ? e.message : String(e);
+	return t(/out of memory|allocation failed|memory access out of bounds/i.test(i) ? "OUT_OF_MEMORY" : r, i);
+}
+// app/lib/binding/transport.ts
+function i(e, n) {
+	let i = 0, a = !1, o = !1, s, c, l = () => {
+		o || (o = !0, e.terminate());
+	}, u = (e, t) => {
+		let n = c;
+		n && (c = void 0, n.cleanup(), e ? n.reject(r(e, n.code)) : n.resolve(t));
+	}, d = (e) => {
+		a = !0, l(), u(t(c?.code ?? "INVALID_INPUT", e));
+	};
+	e.onerror = (e) => {
+		e.preventDefault(), d(e.message || "Worker crashed");
+	}, e.onmessageerror = () => d("Worker response could not be deserialized"), e.onmessage = ({ data: e }) => {
+		if (c && e.id === c.id) {
+			if (e.progress) try {
+				c.context?.onProgress?.(e.progress);
+			} catch {}
+			else u(e.error, e.result);
+		}
+	};
+	function f(r, o, s, d) {
+		return a || c ? Promise.reject(t("INVALID_INPUT", a ? "Session disposed or terminated" : "Session already busy")) : d?.signal.aborted ? Promise.reject(t("ABORTED", "Operation aborted")) : new Promise((f, p) => {
+			let m = () => {
+				a = !0, l(), u(t("ABORTED", "Operation aborted; session worker terminated"));
+			};
+			c = {
+				id: ++i,
+				code: s,
+				context: d,
+				resolve: (e) => f(e),
+				reject: p,
+				cleanup: () => d?.signal.removeEventListener("abort", m)
+			}, d?.signal.addEventListener("abort", m, { once: !0 });
+			try {
+				e.postMessage({
+					id: i,
+					method: r,
+					args: o,
+					device: n
+				});
+			} catch (e) {
+				a = !0, l(), u(e);
+			}
+		});
+	}
+	return {
+		prepare: (e, t) => f("prepare", [e], "MODEL_LOAD_FAILED", t),
+		transcribe: (e, t, n) => f("transcribe", [e, t], "TRANSCRIPTION_FAILED", n),
+		align: (e, t, n, r) => f("align", [
+			e,
+			t,
+			n
+		], "ALIGNMENT_FAILED", r),
+		dispose() {
+			if (!s) {
+				if (c) return Promise.reject(t("INVALID_INPUT", "Wait for active operation before dispose"));
+				s = a ? Promise.resolve() : f("dispose", [], "INVALID_INPUT"), a = !0, s = s.finally(l);
+			}
+			return s;
+		}
+	};
+}
+// app/lib/binding/index.ts
+function a(n = {}) {
+	let r = n.device ?? "webgpu";
+	if (r !== "wasm" && r !== "webgpu") throw t("UNSUPPORTED_DEVICE", "Supported devices: wasm, webgpu");
+	for (let e of Object.keys(n)) if (e !== "device") throw t("UNSUPPORTED_OPTION", `Unsupported binding option: ${e}`);
+	let a = Object.freeze({
+		contractVersion: 1,
+		libraryVersion: "0.1.0",
+		supportedLanguages: Object.freeze(["en"]),
+		model: Object.freeze({
+			...e,
+			device: r,
+			dtype: "q4"
+		}),
+		alignmentOptions: Object.freeze([
+			"pairing",
+			"threshold",
+			"window",
+			"karaoke"
+		]),
+		lyricsContext: !1
+	});
+	return Object.freeze({
+		capabilities: a,
+		async createSession() {
+			if (typeof Worker > "u" || r === "webgpu" && (typeof navigator > "u" || !navigator.gpu)) throw t("UNSUPPORTED_DEVICE", `Browser ${r} worker support is required`);
+			try {
+				return i(new Worker(new URL(
+					/* @vite-ignore */
+					new URL("assets/worker-CNw7yNoM.js", import.meta.url).href,
+					"" + import.meta.url
+				), { type: "module" }), r);
+			} catch (e) {
+				throw t("UNSUPPORTED_DEVICE", e instanceof Error ? e.message : String(e));
+			}
+		}
+	});
+}
+var o = a();
+export { o as binding, a as createBinding };

package/licenses/asr-upstream.LICENSE

@@ -0,0 +1,70 @@
+ASR control and alignment rules derived from faster-whisper 1.2.1 and CTranslate2 4.8.3.
+
+MIT License
+
+Copyright (c) 2023 SYSTRAN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+MIT License
+
+Copyright (c) 2018-     SYSTRAN.
+Copyright (c) 2019-     The OpenNMT Authors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Bundled compression dependency: pako 3.0.2
+
+(The MIT License)
+
+Copyright (C) 2014-2017 by Vitaly Puzrin and Andrei Tuputcyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/licenses/jinja.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Hugging Face
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/licenses/onnxruntime.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.