kokoro.js: forward session_options through KokoroTTS.from_pretrained

[pieterbotes]

What

Adds an optional session_options field to KokoroTTS.from_pretrained(model_id, options) and forwards it to StyleTextToSpeech2Model.from_pretrained. transformers.js already accepts session_options and passes it to the ONNX Runtime inference session — kokoro.js just doesn't expose it today.

const tts = await KokoroTTS.from_pretrained(model_id, {
  dtype: "q8",
  session_options: { intraOpNumThreads: 1 },
});

No defaults change; when the option is omitted, behavior is identical to today.

Why

When several KokoroTTS instances run in parallel worker processes (a TTS pool in a server), each ONNX session sizes its intra-op thread pool to the machine's full core count by default, and the workers thrash each other. Measured on a 16-logical-core machine (q8, CPU EP): 8 concurrent syntheses scaled only 1.89× over a single worker. Capping each worker to intraOpNumThreads: 1 and running more workers yielded 1.91× more aggregate throughput than the default threading, with the same model and inputs.

There is currently no clean way to do this from the public API:

• env.backends.onnx global tweaks don't reach per-session options.
• Constructing the model yourself and using new KokoroTTS(model, tokenizer) works for generate() but breaks stream() ("Missing the following inputs: style, speed"), so it isn't a practical workaround.

Notes

• One field, threaded through with a JSDoc line; session_options is applied only when provided, so omitted callers see no change.
• We've been running this exact change in production via patch-package against the published 1.2.1 dist; happy to adjust naming/shape if you'd prefer it spelled differently.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E6YJ48EqBVrYcZdP7JNpri