Download js/README.md from KaleComputer/kale-tts-1-tiny: direct link, hf CLI and curl.
- Browser
- Download file 4.71 kB
-
https://huggingface.co/KaleComputer/kale-tts-1-tiny/resolve/main/js/README.md
- Command line
-
hf download hf://KaleComputer/kale-tts-1-tiny/js/README.md
-
curl -L -o README.md https://huggingface.co/KaleComputer/kale-tts-1-tiny/resolve/main/js/README.md
kale-tts JS API (draft)
kale-tts.mjs: KaleTTS.load(model, { ort?, frontend?, threads?, graph?, executionProviders?, sessionOptions? }), tts.listVoices() (id, name, description, accent, label = "Name · description"), tts.resolveVoice(nameOrId), tts.preload(voices?), tts.speak(text, { voice }) -> { audio, sampleRate },
tts.stream(text, { voice }) (async iterator, one sentence at a time), toWav(audio, sampleRate), KaleTTS.registerFrontEnd(accent, { g2pModel, lexicon, override, terms } | loader) (the four front-end files, or a loader such as loadEnGB).
Expects ../models/<name>/ (model.onnx, voices.json, voices/*.bin, tokenizer.json) and ../frontend/ next to it.
Accent switch: voices.json accent -> front end (en-us now; en-gb hook for the british front end).
Tested 16 Nov: Node 24 + onnxruntime-node 1.22.0; headless Chromium (Playwright's chrome-headless-shell) + onnxruntime-web 1.22.0 wasm; nano and tiny.
preload: work offline after load
await tts.preload() loads every voice's files and the front end(s) those voices need, up front; tts.preload("kenzie") or
tts.preload(["kenzie", "amy"]) loads only those. It returns the loaded ids. Afterwards speak() / stream() for those voices need no
network or file access (onnxruntime and the model are already loaded by KaleTTS.load). Voices that weren't preloaded still load on
first use. Loads are cached per voice and shared between parallel callers; a failed load is retried on the next call. An unknown id
throws with the list of valid ids.
const tts = await KaleTTS.load("kale-tts-1-nano");
await tts.preload(); // all 8 voices + front end; from here on, offline is fine
Tested 16 Nov: Node (model + front-end folders moved away after preload, all 8 voices still speak) and headless Chromium (browser context set offline after preload, all 8 voices speak, 0 console errors).
Graph and backend
KaleTTS.load(name, { graph, executionProviders, sessionOptions }):
graph:"auto"(default),"int8"(kale-tts-1-tiny.onnx),"fp32"(kale-tts-1-tiny.fp32.onnx, nano only for now) or a file name in the model folder.executionProviders: onnxruntime EPs, e.g.["webgpu"],["wasm"],["cpu"].sessionOptionsgo toInferenceSession.create.- Default with nothing set: in a browser with a WebGPU adapter, fp32 on webgpu (checked with one tiny run); if there's no adapter, no fp32 file, or the run fails, int8 on wasm. In Node: int8 on cpu. Options you set are used as given, with no fallback.
- WebGPU sessions keep the six LSTM layers on the CPU (
forceCpuNodeNames): since onnxruntime-web 1.27 their WebGPU kernel is slower for this model (nano fp32 85x -> 163-175x, tiny int8 29x -> 58-62x, Mac Chrome). Pass your own{ name: "webgpu", ... }object to override. With no fp32 file (tiny), the default tries int8 on webgpu before wasm. tts.backendtells what was picked:{ graph: "kale-tts-1-tiny.fp32.onnx", executionProviders: ["webgpu"] }.- Browser: WebGPU needs onnxruntime-web 1.31 or newer, loaded from its WebGPU build, e.g. an import map entry
"onnxruntime-web": "https://cdn.jsdelivr.net/npm/onnxruntime-web@1.31.1/dist/ort.webgpu.bundle.min.mjs"(that build runs wasm too). With 1.22.0, WebGPU fails at run time and the default falls back to wasm.
const tts = await KaleTTS.load("kale-tts-1-nano"); // auto
const cpu = await KaleTTS.load("kale-tts-1-nano", { graph: "int8", executionProviders: ["wasm"] });
Tested 16 Nov in headless Chrome for Testing (WebGPU adapter) and chrome-headless-shell with onnxruntime-web 1.31.1 and 1.22.0, every option and the fallback, nano and tiny; and in Node (onnxruntime-node 1.22): default, fp32, int8, sessionOptions.
Voices by name
Every call that takes a voice accepts its public name in any case ("kenzie", "Kenzie") or its internal id ("s057b"); earlier names stay as aliases ("imogen" -> Amy, "alistair" -> Jack). The HTTP server
(server/server.mjs) and the Python package (resolve_voice) do the same; with no voice given they use the first voice.
Guards
Only voices listed in the model's voices.json load (by name, alias or id); anything else throws unknown voice … with the valid list,
never a silent fallback to another voice. Each voice's files are size-checked against voices.json (<id>.bin = rows of 256 floats,
<id>.extra.bin = exactly the voice_inputs floats), and a model file that starts like a text / HTML page is refused. A web server that
answers a missing file with an HTML page (status 200) therefore gives a clear error instead of a broken voice. The Python package does the same.