use-voice-control 0.1.86 → 0.1.87

package/dist/semantic-split-CXhk-k1F.js

@@ -0,0 +1,44 @@
+function h(f, i = 500) {
+  const n = f.split(/\n\s*\n/), s = [];
+  for (let o of n) {
+    if (o.length <= i) {
+      s.push(o.trim());
+      continue;
+    }
+    const r = new RegExp(`(?<=[.?!])(?=\\s+["“”'a-z])`, "gi"), l = o.split(r);
+    let t = "";
+    for (let e of l) {
+      if (e = e.trim(), e.length > i) {
+        const p = u(e, i);
+        for (let c of p)
+          (t + " " + c).length > i ? (t && s.push(t.trim()), t = c) : t += (t ? " " : "") + c;
+        continue;
+      }
+      (t + " " + e).length > i ? (t && s.push(t.trim()), t = e) : t += (t ? " " : "") + e;
+    }
+    t && s.push(t.trim());
+  }
+  return s;
+}
+function u(f, i) {
+  const n = [];
+  let s = "";
+  const o = f.split(/,\s*/);
+  for (let r of o)
+    if ((s + ", " + r).length > i)
+      if (s && n.push(s.trim()), r.length > i) {
+        const l = r.split(/\s+/);
+        let t = "";
+        for (let e of l)
+          (t + " " + e).length > i ? (t && n.push(t.trim()), t = e) : t += (t ? " " : "") + e;
+        t && n.push(t.trim()), s = "";
+      } else
+        s = r;
+    else
+      s += (s ? ", " : "") + r;
+  return s && n.push(s.trim()), n;
+}
+export {
+  h as s
+};
+//# sourceMappingURL=semantic-split-CXhk-k1F.js.map

package/dist/semantic-split-CXhk-k1F.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-split-CXhk-k1F.js","sources":["../speech/utils/semantic-split.js"],"sourcesContent":["/**\n * @fileoverview Splits long text into TTS-sized chunks along paragraph, sentence, comma, and word boundaries so speech synthesis can process it incrementally.\n *\n * Exports `splitTextSmart` (primary chunker, falling back to `splitLongSentence` for\n * oversized sentences) and `splitLongSentence`. Also retains an older, unused\n * `splitTextSmartOld` variant that lacks the long-sentence fallback.\n */\nexport function splitTextSmart(text, maxChunkLength = 500) {\n  const paragraphChunks = text.split(/\\n\\s*\\n/);\n  const finalChunks = [];\n\n  for (let para of paragraphChunks) {\n    if (para.length <= maxChunkLength) {\n      finalChunks.push(para.trim());\n      continue;\n    }\n\n    const sentenceRegex = /(?<=[.?!])(?=\\s+[\"“”'a-z])/gi;\n    const sentences = para.split(sentenceRegex);\n\n    let chunk = '';\n    for (let sentence of sentences) {\n      sentence = sentence.trim();\n\n      if (sentence.length > maxChunkLength) {\n        // Sentence too long — fallback split\n        const subChunks = splitLongSentence(sentence, maxChunkLength);\n        for (let sub of subChunks) {\n          if ((chunk + ' ' + sub).length > maxChunkLength) {\n            if (chunk) finalChunks.push(chunk.trim());\n            chunk = sub;\n          } else {\n            chunk += (chunk ? ' ' : '') + sub;\n          }\n        }\n        continue;\n      }\n\n      if ((chunk + ' ' + sentence).length > maxChunkLength) {\n        if (chunk) finalChunks.push(chunk.trim());\n        chunk = sentence;\n      } else {\n        chunk += (chunk ? ' ' : '') + sentence;\n      }\n    }\n    if (chunk) finalChunks.push(chunk.trim());\n  }\n\n  return finalChunks;\n}\n\nexport function splitLongSentence(sentence, maxLen) {\n  const chunks = [];\n  let current = '';\n\n  const commaParts = sentence.split(/,\\s*/);\n  for (let part of commaParts) {\n    if ((current + ', ' + part).length > maxLen) {\n      if (current) chunks.push(current.trim());\n      if (part.length > maxLen) {\n        const words = part.split(/\\s+/);\n        let wordChunk = '';\n        for (let word of words) {\n          if ((wordChunk + ' ' + word).length > maxLen) {\n            if (wordChunk) chunks.push(wordChunk.trim());\n            wordChunk = word;\n          } else {\n            wordChunk += (wordChunk ? ' ' : '') + word;\n          }\n        }\n        if (wordChunk) chunks.push(wordChunk.trim());\n        current = '';\n      } else {\n        current = part;\n      }\n    } else {\n      current += (current ? ', ' : '') + part;\n    }\n  }\n  if (current) chunks.push(current.trim());\n\n  return chunks;\n}\n\n\nfunction splitTextSmartOld(text, maxChunkLength = 500) {\n  const paragraphChunks = text.split(/\\n\\s*\\n/); // Step 1: split on double returns\n  const finalChunks = [];\n\n  for (let para of paragraphChunks) {\n    if (para.length <= maxChunkLength) {\n      finalChunks.push(para.trim());\n      continue;\n    }\n\n    // Step 2: Further split on sentence boundaries if too long\n    const sentenceRegex = /(?<=[.?!])(?=\\s+[\"“”'a-z])/gi;\n    const sentences = para.split(sentenceRegex);\n\n    let chunk = '';\n    for (let sentence of sentences) {\n      sentence = sentence.trim();\n      if ((chunk + ' ' + sentence).length > maxChunkLength) {\n        if (chunk) finalChunks.push(chunk.trim());\n        chunk = sentence;\n      } else {\n        chunk += (chunk ? ' ' : '') + sentence;\n      }\n    }\n    if (chunk) finalChunks.push(chunk.trim());\n  }\n\n  return finalChunks;\n}\n"],"names":["splitTextSmart","text","maxChunkLength","paragraphChunks","finalChunks","para","sentenceRegex","sentences","chunk","sentence","subChunks","splitLongSentence","sub","maxLen","chunks","current","commaParts","part","words","wordChunk","word"],"mappings":"AAOO,SAASA,EAAeC,GAAMC,IAAiB,KAAK;AACzD,QAAMC,IAAkBF,EAAK,MAAM,SAAS,GACtCG,IAAc,CAAA;AAEpB,WAASC,KAAQF,GAAiB;AAChC,QAAIE,EAAK,UAAUH,GAAgB;AACjC,MAAAE,EAAY,KAAKC,EAAK,MAAM;AAC5B;AAAA,IACF;AAEA,UAAMC,IAAgB,WAAA,+BAAA,IAA8B,GAC9CC,IAAYF,EAAK,MAAMC,CAAa;AAE1C,QAAIE,IAAQ;AACZ,aAASC,KAAYF,GAAW;AAG9B,UAFAE,IAAWA,EAAS,KAAI,GAEpBA,EAAS,SAASP,GAAgB;AAEpC,cAAMQ,IAAYC,EAAkBF,GAAUP,CAAc;AAC5D,iBAASU,KAAOF;AACd,WAAKF,IAAQ,MAAMI,GAAK,SAASV,KAC3BM,KAAOJ,EAAY,KAAKI,EAAM,KAAI,CAAE,GACxCA,IAAQI,KAERJ,MAAUA,IAAQ,MAAM,MAAMI;AAGlC;AAAA,MACF;AAEA,OAAKJ,IAAQ,MAAMC,GAAU,SAASP,KAChCM,KAAOJ,EAAY,KAAKI,EAAM,KAAI,CAAE,GACxCA,IAAQC,KAERD,MAAUA,IAAQ,MAAM,MAAMC;AAAA,IAElC;AACA,IAAID,KAAOJ,EAAY,KAAKI,EAAM,KAAI,CAAE;AAAA,EAC1C;AAEA,SAAOJ;AACT;AAEO,SAASO,EAAkBF,GAAUI,GAAQ;AAClD,QAAMC,IAAS,CAAA;AACf,MAAIC,IAAU;AAEd,QAAMC,IAAaP,EAAS,MAAM,MAAM;AACxC,WAASQ,KAAQD;AACf,SAAKD,IAAU,OAAOE,GAAM,SAASJ;AAEnC,UADIE,KAASD,EAAO,KAAKC,EAAQ,KAAI,CAAE,GACnCE,EAAK,SAASJ,GAAQ;AACxB,cAAMK,IAAQD,EAAK,MAAM,KAAK;AAC9B,YAAIE,IAAY;AAChB,iBAASC,KAAQF;AACf,WAAKC,IAAY,MAAMC,GAAM,SAASP,KAChCM,KAAWL,EAAO,KAAKK,EAAU,KAAI,CAAE,GAC3CA,IAAYC,KAEZD,MAAcA,IAAY,MAAM,MAAMC;AAG1C,QAAID,KAAWL,EAAO,KAAKK,EAAU,KAAI,CAAE,GAC3CJ,IAAU;AAAA,MACZ;AACE,QAAAA,IAAUE;AAAA;AAGZ,MAAAF,MAAYA,IAAU,OAAO,MAAME;AAGvC,SAAIF,KAASD,EAAO,KAAKC,EAAQ,KAAI,CAAE,GAEhCD;AACT;"}

package/dist/types/types.d.ts

@@ -11,7 +11,20 @@ export interface TTSResult {
     audio: ArrayBuffer;
     contentType: string;
 }
-export declare const KOKORO_VOICES: readonly ["af_heart", "af_alloy", "af_aoede", "af_bella", "af_jessica", "af_nicole", "af_river", "af_sarah", "af_sky", "am_adam", "am_echo", "am_fable", "am_fenrir", "am_liam", "am_michael", "am_onyx"];
+export declare const KOKORO_VOICES: readonly ["af_heart", "af_alloy", "af_aoede", "af_bella", "af_jessica", "af_kore", "af_nicole", "af_nova", "af_river", "af_sarah", "af_sky", "am_adam", "am_echo", "am_eric", "am_fenrir", "am_liam", "am_michael", "am_onyx", "am_puck", "am_santa", "bf_alice", "bf_emma", "bf_isabella", "bf_lily", "bm_daniel", "bm_fable", "bm_george", "bm_lewis"];
 export type KokoroVoice = (typeof KOKORO_VOICES)[number];
+export interface KokoroVoiceDescription {
+    id: string;
+    /** Display name, e.g. `Heart` for `af_heart`. */
+    name: string;
+    /** `American English` or `British English`. */
+    accent: string;
+    gender: "Female" | "Male";
+}
+/**
+ * Describes a voice from its id, so listings (`--list-voices`, a voice picker)
+ * do not need a hand-maintained table that can drift from `KOKORO_VOICES`.
+ */
+export declare function describeKokoroVoice(id: string): KokoroVoiceDescription;
 export declare const DEEPGRAM_SPEAKERS: readonly ["angus", "asteria", "arcas", "orion", "orpheus", "athena", "luna", "zeus", "perseus", "helios", "hera", "stella"];
 export type DeepgramSpeaker = (typeof DEEPGRAM_SPEAKERS)[number];

package/dist/utils/markdown-to-speech.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Turns Markdown into text a speech synthesizer can read.
+ *
+ * Markdown handed straight to a TTS engine is read literally: "hash hash Getting
+ * started", "star star important star star". This module parses the document
+ * instead and emits only the words, keeping the *structure* the marks encoded —
+ * a heading becomes its own spoken segment ending in a full stop so the
+ * synthesizer pauses, a list item becomes one sentence, a fenced code block is
+ * announced rather than spelled out.
+ *
+ * It is deliberately dependency-free and runs in the browser as well as Node, so
+ * `ReadAloudController` and the CLI can share it.
+ */
+/** Kind of block the converter recognised. */
+export type SpeechSegmentType = "heading" | "paragraph" | "list-item" | "quote" | "code" | "table-row";
+export interface SpeechSegment {
+    type: SpeechSegmentType;
+    /** Spoken text of the block, with every Markdown mark already removed. */
+    text: string;
+    /** Heading level 1-6. Only set on `heading` segments. */
+    level?: number;
+}
+export interface MarkdownToSpeechOptions {
+    /**
+     * How headings are spoken. `text` (default) reads the heading words on their
+     * own so they land between pauses; `announce` prefixes them with "Heading:";
+     * `skip` drops them entirely.
+     */
+    headings?: "text" | "announce" | "skip";
+    /**
+     * What to do with fenced code blocks. `announce` (default) replaces the block
+     * with a short spoken note, `read` reads the code verbatim, `skip` drops it.
+     */
+    codeBlocks?: "announce" | "read" | "skip";
+    /** `text` (default) speaks the link text and drops the URL; `text-and-url` reads both. */
+    links?: "text" | "text-and-url";
+    /** `alt` (default) speaks the image's alt text; `skip` drops images. */
+    images?: "alt" | "skip";
+    /** Read the YAML front matter block. Off by default. */
+    frontMatter?: boolean;
+    /** `rows` (default) reads table rows as comma-separated cells; `skip` drops tables. */
+    tables?: "rows" | "skip";
+    /**
+     * Append a full stop to blocks that do not end in punctuation, so the
+     * synthesizer pauses between them instead of running them together.
+     * Default true.
+     */
+    addTerminalPunctuation?: boolean;
+}
+/**
+ * Strips the inline marks — emphasis, code spans, links, images, raw HTML — from
+ * a single line, leaving the words behind.
+ */
+export declare function stripInlineMarkdown(input: string, options?: MarkdownToSpeechOptions): string;
+/**
+ * Parses Markdown into the blocks that should be spoken, in reading order.
+ *
+ * Use this when the caller wants the structure — to highlight the current
+ * heading, say, or to skip to a section. Callers that only need something to
+ * feed a synthesizer want {@link markdownToSpeech}.
+ */
+export declare function markdownToSpeechSegments(markdown: string, options?: MarkdownToSpeechOptions): SpeechSegment[];
+/**
+ * Converts Markdown to plain text ready for a speech synthesizer.
+ *
+ * Blocks are separated by blank lines so downstream chunkers (`splitTextSmart`)
+ * break on them; runs of list items and table rows stay in one block so a list
+ * is not chopped into one request per bullet.
+ */
+export declare function markdownToSpeech(markdown: string, options?: MarkdownToSpeechOptions): string;
+/**
+ * Guesses whether a blob of text is Markdown, for callers with no filename to go
+ * on (piped stdin, a paste). Errs towards `false`: prose read as Markdown is
+ * mostly unchanged anyway, so only reasonably clear signals count.
+ */
+export declare function looksLikeMarkdown(text: string): boolean;

package/dist/utils/wav.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Minimal WAV (RIFF) encoder for raw Float32 PCM.
+ *
+ * The browser path gets its WAV from `convertAudioBufferToWav`, which needs a Web
+ * Audio `AudioBuffer`. Node has no such thing: the Kokoro model hands back a bare
+ * `Float32Array`, and long documents are synthesized one chunk at a time and
+ * joined before encoding. Both of those are pure buffer work, so they live here
+ * with no platform dependency.
+ */
+/**
+ * Joins per-chunk sample buffers into one contiguous track.
+ *
+ * @param chunks Sample buffers in playback order.
+ * @param silenceSamples Samples of silence to insert between chunks, so the
+ *   seams between separately synthesized chunks do not sound clipped.
+ */
+export declare function concatSamples(chunks: Float32Array[], silenceSamples?: number): Float32Array;
+/**
+ * Encodes Float32 samples (nominally -1..1) as a 16-bit PCM WAV file.
+ *
+ * @param samples Interleaved samples when `channels` is greater than 1.
+ * @param sampleRate Sample rate of the audio, e.g. 24000 for Kokoro.
+ * @param channels Channel count. Kokoro is mono.
+ */
+export declare function encodeWav(samples: Float32Array, sampleRate?: number, channels?: number): ArrayBuffer;
+/** Duration of a Float32 track in seconds, for progress and log lines. */
+export declare function wavDurationSeconds(samples: Float32Array, sampleRate: number): number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "use-voice-control",
-  "version": "0.1.86",
-  "description": "React voice control with speech transcription, vocalization, and interruption (STT/TTS/VAD) support.",
+  "version": "0.1.87",
+  "description": "React voice control with speech transcription, vocalization, and interruption (STT/TTS/VAD) support, plus a CLI that reads Markdown and text files aloud to audio files.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OpenSourceAGI/qwksearch-research-agent.git",
@@ -10,6 +10,9 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "use-voice-control": "./bin/use-voice-control.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -23,6 +26,14 @@
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react.js"
     },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./markdown": {
+      "types": "./dist/utils/markdown-to-speech.d.ts",
+      "import": "./dist/markdown.js"
+    },
     "./api-client": {
       "types": "./speech/api-client.ts",
       "import": "./speech/api-client.ts"
@@ -31,11 +42,11 @@
   "files": [
     "dist",
     "speech",
+    "bin",
     "README.md"
   ],
   "scripts": {
     "build": "tsc && vite build",
-    "prepare": "tsc && vite build",
     "dev": "vite build --watch",
     "type-check": "tsc --noEmit",
     "test": "vitest run",
@@ -44,9 +55,11 @@
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
     "lucide-react": "^0.344.0",
-    "@moonshine-ai/moonshine-js": "^0.1.29"
+    "@moonshine-ai/moonshine-js": "^0.1.29",
+    "kokoro-js": "^1.2.1"
   },
   "devDependencies": {
+    "@types/node": "^22.10.2",
     "@types/react": "^19.2.17",
     "@vitejs/plugin-react": "^4.3.4",
     "@types/react-dom": "^19.2.3",

package/speech/client/index.ts

@@ -18,4 +18,14 @@ export {
   type TranscriberEngine,
 } from "./live-transcriber";
 
+export {
+  looksLikeMarkdown,
+  markdownToSpeech,
+  markdownToSpeechSegments,
+  stripInlineMarkdown,
+  type MarkdownToSpeechOptions,
+  type SpeechSegment,
+  type SpeechSegmentType,
+} from "../utils/markdown-to-speech";
+
 export type { TTSProvider, KokoroVoice, DeepgramSpeaker } from "../types/types";

package/speech/client/read-aloud.ts

@@ -13,6 +13,11 @@
  * `speechSynthesis` rather than failing, so the feature still works everywhere.
  */
 import type { TTSProvider } from "../types/types";
+import {
+  looksLikeMarkdown,
+  markdownToSpeech,
+  type MarkdownToSpeechOptions,
+} from "../utils/markdown-to-speech";
 import { splitTextSmart } from "../utils/semantic-split.js";
 
 export type ReadAloudState = "idle" | "loading" | "speaking" | "paused";
@@ -44,6 +49,14 @@ export interface ReadAloudOptions {
    * seams between chunks more audible. Default 240.
    */
   maxChunkLength?: number;
+  /**
+   * How to read the text handed to `speak()`. `auto` (default) converts text
+   * that looks like Markdown so "##" and "**" are not read out; `markdown`
+   * always converts; `text` never does.
+   */
+  format?: "auto" | "markdown" | "text";
+  /** Markdown conversion options, when the text is read as Markdown. */
+  markdown?: MarkdownToSpeechOptions;
   /** Override synthesis entirely (tests, a bring-your-own-TTS host app). */
   synthesize?: SynthesizeFn;
   /** Called as each chunk starts playing. */
@@ -102,7 +115,7 @@ export class ReadAloudController {
     this.stop();
 
     const maxChunkLength = this.options.maxChunkLength ?? DEFAULT_MAX_CHUNK;
-    const chunks = splitTextSmart(text ?? "", maxChunkLength)
+    const chunks = splitTextSmart(this.toSpeakableText(text ?? ""), maxChunkLength)
       .map((chunk) => chunk.trim())
       .filter((chunk) => chunk.length > 0);
 
@@ -187,6 +200,19 @@ export class ReadAloudController {
     }
   }
 
+  /**
+   * Converts Markdown to spoken words before chunking, so a document read out
+   * of an editor does not have its syntax read back to the listener.
+   */
+  private toSpeakableText(text: string): string {
+    const format = this.options.format ?? "auto";
+    if (format === "text") return text;
+    if (format === "markdown" || looksLikeMarkdown(text)) {
+      return markdownToSpeech(text, this.options.markdown);
+    }
+    return text;
+  }
+
   private setState(state: ReadAloudState): void {
     if (this.state === state) return;
     this.state = state;

package/speech/core/kokoro-node.ts

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Kokoro TTS running locally on Node (or Bun/Deno) via `kokoro-js`.
+ *
+ * This is the engine behind `generateSpeech({ provider: "kokoro" })` on a server
+ * and behind the `use-voice-control` CLI. The model runs on the CPU through
+ * onnxruntime, so nothing is sent to a third-party service; the first call
+ * downloads the weights (~90 MB at the default `q8`) into the Hugging Face cache
+ * and every later call reuses the instance held in this module.
+ *
+ * Kokoro's context is a few hundred phonemes, so anything longer than a
+ * paragraph has to be synthesized in pieces. `synthesizeSamples` chunks on
+ * sentence and paragraph boundaries with `splitTextSmart`, runs the chunks in
+ * order, and joins the audio with a short silence at each seam.
+ */
+import type { TTSResult } from "../types/types";
+import { splitTextSmart } from "../utils/semantic-split.js";
+import { concatSamples, encodeWav } from "../utils/wav";
+
+export type KokoroDtype = "fp32" | "fp16" | "q8" | "q4" | "q4f16";
+export type KokoroDevice = "wasm" | "webgpu" | "cpu";
+
+export interface KokoroNodeOptions {
+  /** Voice id, e.g. `af_heart`. Default `af_heart`. */
+  voice?: string;
+  /** Speaking rate; 1 is the model's natural pace. Default 1. */
+  speed?: number;
+  /** Hugging Face model id. Default `onnx-community/Kokoro-82M-v1.0-ONNX`. */
+  model?: string;
+  /** Weight quantization. `q8` (default) is the best size/quality trade on CPU. */
+  dtype?: KokoroDtype;
+  /** Execution device. Default `cpu`. */
+  device?: KokoroDevice;
+  /**
+   * Target chunk size in characters. Kokoro's context is limited, so long text
+   * is split before synthesis; 400 leaves headroom for phoneme expansion.
+   */
+  maxChunkLength?: number;
+  /** Silence inserted between chunks, in milliseconds. Default 120. */
+  gapMs?: number;
+  /** Model download/loading progress, forwarded from transformers.js. */
+  onModelProgress?: (progress: unknown) => void;
+  /** Called before each chunk is synthesized, for CLI progress output. */
+  onChunk?: (info: { index: number; total: number; text: string }) => void;
+}
+
+export interface KokoroAudio {
+  samples: Float32Array;
+  sampleRate: number;
+}
+
+const DEFAULT_MODEL = "onnx-community/Kokoro-82M-v1.0-ONNX";
+const DEFAULT_VOICE = "af_heart";
+const DEFAULT_DTYPE: KokoroDtype = "q8";
+const DEFAULT_DEVICE: KokoroDevice = "cpu";
+const DEFAULT_MAX_CHUNK = 400;
+const DEFAULT_GAP_MS = 120;
+
+/** One loaded model per model/dtype/device combination, keyed by those three. */
+const instances = new Map<string, Promise<any>>();
+
+/** True on Node, Bun and Deno — anywhere `kokoro-js` can load onnxruntime-node. */
+function isServerRuntime(): boolean {
+  const g = globalThis as any;
+  return Boolean(g.process?.versions?.node || g.Bun || g.Deno);
+}
+
+/**
+ * Loads (and caches) a `kokoro-js` instance.
+ *
+ * `kokoro-js` is an optional dependency: a browser-only consumer should not have
+ * to download onnxruntime-node, so a missing install is reported as an
+ * actionable error rather than a module-resolution stack trace.
+ */
+export async function loadKokoroTTS(options: KokoroNodeOptions = {}): Promise<any> {
+  const model = options.model ?? DEFAULT_MODEL;
+  const dtype = options.dtype ?? DEFAULT_DTYPE;
+  const device = options.device ?? (isServerRuntime() ? DEFAULT_DEVICE : "wasm");
+  const key = `${model}|${dtype}|${device}`;
+
+  const cached = instances.get(key);
+  if (cached) return cached;
+
+  const loading = (async () => {
+    let KokoroTTS: any;
+    try {
+      // Kept in a variable so bundlers treat this as an optional runtime
+      // dependency rather than something to resolve at build time.
+      const specifier = "kokoro-js";
+      ({ KokoroTTS } = await import(/* @vite-ignore */ specifier));
+    } catch (error) {
+      throw new Error(
+        "Local Kokoro speech needs the optional `kokoro-js` package. " +
+          "Install it with `npm install kokoro-js`. " +
+          `(import failed: ${error instanceof Error ? error.message : String(error)})`
+      );
+    }
+
+    return KokoroTTS.from_pretrained(model, {
+      dtype,
+      device,
+      progress_callback: options.onModelProgress,
+    });
+  })();
+
+  instances.set(key, loading);
+
+  try {
+    return await loading;
+  } catch (error) {
+    // A failed download must not poison every later attempt.
+    instances.delete(key);
+    throw error;
+  }
+}
+
+/** Drops cached model instances. Mainly useful in tests and long-lived workers. */
+export function resetKokoroCache(): void {
+  instances.clear();
+}
+
+/**
+ * Synthesizes `text` to raw samples, chunking anything longer than the model's
+ * comfortable context.
+ */
+export async function synthesizeSamples(
+  text: string,
+  options: KokoroNodeOptions = {}
+): Promise<KokoroAudio> {
+  const trimmed = (text ?? "").trim();
+  if (!trimmed) throw new Error("Text is required");
+
+  const chunks = splitTextSmart(trimmed, options.maxChunkLength ?? DEFAULT_MAX_CHUNK)
+    .map((chunk: string) => chunk.trim())
+    .filter((chunk: string) => chunk.length > 0);
+
+  const tts = await loadKokoroTTS(options);
+  const voice = options.voice ?? DEFAULT_VOICE;
+  const speed = options.speed ?? 1;
+
+  const rendered: Float32Array[] = [];
+  let sampleRate = 24000;
+
+  for (let index = 0; index < chunks.length; index += 1) {
+    options.onChunk?.({ index, total: chunks.length, text: chunks[index] });
+    const audio = await tts.generate(chunks[index], { voice, speed });
+    rendered.push(audio.audio);
+    sampleRate = audio.sampling_rate ?? sampleRate;
+  }
+
+  const gapMs = options.gapMs ?? DEFAULT_GAP_MS;
+  return {
+    samples: concatSamples(rendered, Math.round((gapMs / 1000) * sampleRate)),
+    sampleRate,
+  };
+}
+
+/** Synthesizes `text` and encodes it as a 16-bit PCM WAV file. */
+export async function synthesizeWav(
+  text: string,
+  options: KokoroNodeOptions = {}
+): Promise<TTSResult> {
+  const { samples, sampleRate } = await synthesizeSamples(text, options);
+  return { audio: encodeWav(samples, sampleRate), contentType: "audio/wav" };
+}

package/speech/core/kokoro.ts

@@ -1,81 +1,28 @@
 /**
- * @fileoverview Kokoro TTS provider implementation using Hugging Face transformers
- * Runs on Node.js CPU via transformers library
+ * @fileoverview Kokoro TTS provider for `generateSpeech`.
+ *
+ * The work happens in `kokoro-node.ts`, which runs the Kokoro model locally
+ * through `kokoro-js`; this file is the thin provider adapter that validates the
+ * voice and returns the package's `TTSResult` shape.
  */
 import type { TTSResult } from "../types/types";
 import { KOKORO_VOICES, type KokoroVoice } from "../types/types";
-
-let ttsInstance: any = null;
-let modelLoading: Promise<any> | null = null;
-
-/**
- * Lazy-load Kokoro model using Hugging Face transformers (happens once per server instance)
- */
-async function getKokoroTTS() {
-  if (ttsInstance) return ttsInstance;
-
-  if (modelLoading) {
-    await modelLoading;
-    return ttsInstance;
-  }
-
-  modelLoading = (async () => {
-    try {
-      // Dynamic import to load transformers library. The specifier is kept in
-      // a variable so the type-checker/bundler treats it as an optional runtime
-      // dependency (see optionalDependencies) rather than a build-time one.
-      const transformersModule = "@huggingface/transformers";
-      const transformers: any = await import(/* @vite-ignore */ transformersModule);
-      const { StyleTextToSpeech2Model, AutoTokenizer } = transformers;
-
-      const model_id = "hexgrad/Kokoro-82M";
-
-      // Load model and tokenizer in parallel
-      const [model, tokenizer] = await Promise.all([
-        StyleTextToSpeech2Model.from_pretrained(model_id, {
-          device: "cpu",
-          dtype: "q8"
-        }),
-        AutoTokenizer.from_pretrained(model_id)
-      ]);
-
-      ttsInstance = { model, tokenizer };
-
-      console.log("[Kokoro] Model loaded successfully");
-    } catch (error) {
-      console.error("[Kokoro] Failed to load model:", error);
-      throw error;
-    } finally {
-      modelLoading = null;
-    }
-  })();
-
-  await modelLoading;
-  return ttsInstance;
-}
+import { synthesizeWav, type KokoroNodeOptions } from "./kokoro-node";
 
 /**
- * Generate speech from text using Kokoro
+ * Generate speech from text using Kokoro.
+ *
+ * Long text is chunked and joined automatically. An unrecognised voice falls
+ * back to `af_heart` rather than failing the request.
  */
 export async function generateKokoroSpeech(
   text: string,
-  voice: string = "af_heart"
+  voice: string = "af_heart",
+  options: Omit<KokoroNodeOptions, "voice"> = {}
 ): Promise<TTSResult> {
-  // Validate voice
   const kokoroVoice = KOKORO_VOICES.includes(voice as KokoroVoice)
     ? (voice as KokoroVoice)
     : "af_heart";
 
-  const tts = await getKokoroTTS();
-
-  try {
-    // For Node.js server-side TTS, we'd need the complete transformers implementation
-    // This is a placeholder showing the expected interface
-    // Consider using the browser-based implementation via Web Workers for production
-
-    throw new Error("Server-side Kokoro TTS requires additional setup. Use the browser-based implementation via Web Workers.");
-  } catch (error) {
-    console.error("[Kokoro] Error generating speech:", error);
-    throw error;
-  }
+  return synthesizeWav(text, { ...options, voice: kokoroVoice });
 }

package/speech/index.ts

@@ -10,6 +10,20 @@ import { generateDeepgramSpeech } from "./core/deepgram";
 
 export * from "./types/types";
 
+// Markdown handling is exported from the root entry so a server route can turn a
+// document into speakable text with the same rules the CLI and the browser use.
+export {
+  looksLikeMarkdown,
+  markdownToSpeech,
+  markdownToSpeechSegments,
+  stripInlineMarkdown,
+  type MarkdownToSpeechOptions,
+  type SpeechSegment,
+  type SpeechSegmentType,
+} from "./utils/markdown-to-speech";
+
+export { encodeWav, concatSamples, wavDurationSeconds } from "./utils/wav";
+
 /**
  * Generate speech from text using the specified provider
  *