use-voice-control 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-    <img  src="https://i.imgur.com/ypVzqbg.png" width="200" />
+    <img  src="https://i.imgur.com/ypVzqbg.png"  />
 <br /> 
     <a href="https://www.npmjs.com/package/use-voice-control"><img src="https://img.shields.io/npm/dm/use-voice-control.svg" alt="NPM Monthly Downloads"></a>
     <a href="https://www.npmjs.com/package/use-voice-control"><img src="https://img.shields.io/npm/v/use-voice-control.svg" alt="npm version"></a>

package/dist/core/deepgram.d.ts

@@ -0,0 +1,5 @@
+import { TTSResult } from '../types/types';
+/**
+ * Generate speech from text using Deepgram Aura via Cloudflare Workers AI
+ */
+export declare function generateDeepgramSpeech(text: string, speaker?: string): Promise<TTSResult>;

package/dist/core/kokoro.d.ts

@@ -0,0 +1,5 @@
+import { TTSResult } from '../types/types';
+/**
+ * Generate speech from text using Kokoro
+ */
+export declare function generateKokoroSpeech(text: string, voice?: string): Promise<TTSResult>;

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { TTSOptions, TTSResult } from './types/types';
+export * from './types/types';
+/**
+ * Generate speech from text using the specified provider
+ *
+ * @param options - TTS configuration
+ * @returns Audio buffer and content type
+ *
+ * @example
+ * ```ts
+ * // Use Kokoro (default)
+ * const audio = await generateSpeech({
+ *   text: "Hello world",
+ *   voice: "af_heart"
+ * });
+ *
+ * // Use Deepgram
+ * const audio = await generateSpeech({
+ *   text: "Hello world",
+ *   provider: "deepgram",
+ *   voice: "angus"
+ * });
+ * ```
+ */
+export declare function generateSpeech(options: TTSOptions): Promise<TTSResult>;

package/dist/index.js

@@ -0,0 +1,102 @@
+const c = [
+  "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"
+], u = [
+  "angus",
+  "asteria",
+  "arcas",
+  "orion",
+  "orpheus",
+  "athena",
+  "luna",
+  "zeus",
+  "perseus",
+  "helios",
+  "hera",
+  "stella"
+];
+let t = null, n = null;
+async function f() {
+  return t || (n ? (await n, t) : (n = (async () => {
+    try {
+      const e = await import("@huggingface/transformers"), { StyleTextToSpeech2Model: o, AutoTokenizer: a } = e, s = "hexgrad/Kokoro-82M", [i, l] = await Promise.all([
+        o.from_pretrained(s, {
+          device: "cpu",
+          dtype: "q8"
+        }),
+        a.from_pretrained(s)
+      ]);
+      t = { model: i, tokenizer: l }, console.log("[Kokoro] Model loaded successfully");
+    } catch (r) {
+      throw console.error("[Kokoro] Failed to load model:", r), r;
+    } finally {
+      n = null;
+    }
+  })(), await n, t));
+}
+async function d(r, e = "af_heart") {
+  c.includes(e), await f();
+  try {
+    throw new Error("Server-side Kokoro TTS requires additional setup. Use the browser-based implementation via Web Workers.");
+  } catch (o) {
+    throw console.error("[Kokoro] Error generating speech:", o), o;
+  }
+}
+function h() {
+  var e, o;
+  const r = globalThis;
+  try {
+    if (typeof r.getCloudflareContext == "function") {
+      const a = r.getCloudflareContext();
+      if ((e = a == null ? void 0 : a.env) != null && e.AI) return a.env.AI;
+    }
+  } catch {
+  }
+  return ((o = r.__env__) == null ? void 0 : o.AI) ?? r.AI;
+}
+async function m(r, e = "angus") {
+  const o = u.includes(e) ? e : "angus", a = h();
+  if (!a)
+    throw new Error("Cloudflare AI binding not available");
+  return {
+    audio: await a.run("@cf/deepgram/aura-1", {
+      text: r.slice(0, 5e3),
+      speaker: o,
+      encoding: "mp3"
+    }),
+    contentType: "audio/mpeg"
+  };
+}
+async function _(r) {
+  const { text: e, provider: o = "kokoro", voice: a = "af_heart" } = r;
+  if (!e || typeof e != "string" || e.trim().length === 0)
+    throw new Error("Text is required");
+  switch (o) {
+    case "kokoro":
+      return d(e, a);
+    case "deepgram":
+      return m(e, a);
+    default:
+      throw new Error(`Unknown TTS provider: ${o}`);
+  }
+}
+export {
+  u as DEEPGRAM_SPEAKERS,
+  c as KOKORO_VOICES,
+  _ as generateSpeech
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../speech/types/types.ts","../speech/core/kokoro.ts","../speech/core/deepgram.ts","../speech/index.ts"],"sourcesContent":["/**\n * @fileoverview Type definitions for text-to-speech providers\n */\n\nexport type TTSProvider = \"kokoro\" | \"deepgram\";\n\nexport interface TTSOptions {\n  text: string;\n  provider?: TTSProvider;\n  voice?: string;\n}\n\nexport interface TTSResult {\n  audio: ArrayBuffer;\n  contentType: string;\n}\n\n// Kokoro voices from the model\nexport const KOKORO_VOICES = [\n  \"af_heart\", \"af_alloy\", \"af_aoede\", \"af_bella\",\n  \"af_jessica\", \"af_nicole\", \"af_river\", \"af_sarah\", \"af_sky\",\n  \"am_adam\", \"am_echo\", \"am_fable\", \"am_fenrir\",\n  \"am_liam\", \"am_michael\", \"am_onyx\"\n] as const;\n\nexport type KokoroVoice = (typeof KOKORO_VOICES)[number];\n\n// Deepgram Aura speakers\nexport const DEEPGRAM_SPEAKERS = [\n  \"angus\", \"asteria\", \"arcas\", \"orion\", \"orpheus\", \"athena\",\n  \"luna\", \"zeus\", \"perseus\", \"helios\", \"hera\", \"stella\",\n] as const;\n\nexport type DeepgramSpeaker = (typeof DEEPGRAM_SPEAKERS)[number];\n","/**\n * @fileoverview Kokoro TTS provider implementation using Hugging Face transformers\n * Runs on Node.js CPU via transformers library\n */\nimport type { TTSResult } from \"../types/types\";\nimport { KOKORO_VOICES, type KokoroVoice } from \"../types/types\";\n\nlet ttsInstance: any = null;\nlet modelLoading: Promise<any> | null = null;\n\n/**\n * Lazy-load Kokoro model using Hugging Face transformers (happens once per server instance)\n */\nasync function getKokoroTTS() {\n  if (ttsInstance) return ttsInstance;\n\n  if (modelLoading) {\n    await modelLoading;\n    return ttsInstance;\n  }\n\n  modelLoading = (async () => {\n    try {\n      // Dynamic import to load transformers library. The specifier is kept in\n      // a variable so the type-checker/bundler treats it as an optional runtime\n      // dependency (see optionalDependencies) rather than a build-time one.\n      const transformersModule = \"@huggingface/transformers\";\n      const transformers: any = await import(/* @vite-ignore */ transformersModule);\n      const { StyleTextToSpeech2Model, AutoTokenizer } = transformers;\n\n      const model_id = \"hexgrad/Kokoro-82M\";\n\n      // Load model and tokenizer in parallel\n      const [model, tokenizer] = await Promise.all([\n        StyleTextToSpeech2Model.from_pretrained(model_id, {\n          device: \"cpu\",\n          dtype: \"q8\"\n        }),\n        AutoTokenizer.from_pretrained(model_id)\n      ]);\n\n      ttsInstance = { model, tokenizer };\n\n      console.log(\"[Kokoro] Model loaded successfully\");\n    } catch (error) {\n      console.error(\"[Kokoro] Failed to load model:\", error);\n      throw error;\n    } finally {\n      modelLoading = null;\n    }\n  })();\n\n  await modelLoading;\n  return ttsInstance;\n}\n\n/**\n * Generate speech from text using Kokoro\n */\nexport async function generateKokoroSpeech(\n  text: string,\n  voice: string = \"af_heart\"\n): Promise<TTSResult> {\n  // Validate voice\n  const kokoroVoice = KOKORO_VOICES.includes(voice as KokoroVoice)\n    ? (voice as KokoroVoice)\n    : \"af_heart\";\n\n  const tts = await getKokoroTTS();\n\n  try {\n    // For Node.js server-side TTS, we'd need the complete transformers implementation\n    // This is a placeholder showing the expected interface\n    // Consider using the browser-based implementation via Web Workers for production\n\n    throw new Error(\"Server-side Kokoro TTS requires additional setup. Use the browser-based implementation via Web Workers.\");\n  } catch (error) {\n    console.error(\"[Kokoro] Error generating speech:\", error);\n    throw error;\n  }\n}\n","/**\n * @fileoverview Deepgram TTS provider implementation using Cloudflare Workers AI\n * Requires Cloudflare AI binding\n */\nimport type { TTSResult } from \"../types/types\";\nimport { DEEPGRAM_SPEAKERS, type DeepgramSpeaker } from \"../types/types\";\n\n/**\n * Resolve the Cloudflare Workers AI binding at runtime without a hard\n * dependency on the host application. Consumers running on Cloudflare can\n * expose the context by setting `globalThis.getCloudflareContext` (as the\n * `@opennextjs/cloudflare` / `@cloudflare/next-on-pages` helpers do) or by\n * placing the bound `env` on `globalThis.__env__`.\n */\nfunction resolveCloudflareAI(): any {\n  const g = globalThis as any;\n  try {\n    if (typeof g.getCloudflareContext === \"function\") {\n      const ctx = g.getCloudflareContext();\n      if (ctx?.env?.AI) return ctx.env.AI;\n    }\n  } catch {\n    // CF context helper threw (e.g. called outside a request scope)\n  }\n  return g.__env__?.AI ?? g.AI;\n}\n\n/**\n * Generate speech from text using Deepgram Aura via Cloudflare Workers AI\n */\nexport async function generateDeepgramSpeech(\n  text: string,\n  speaker: string = \"angus\"\n): Promise<TTSResult> {\n  // Validate speaker\n  const auraVoice = DEEPGRAM_SPEAKERS.includes(speaker as DeepgramSpeaker)\n    ? (speaker as DeepgramSpeaker)\n    : \"angus\";\n\n  const ai = resolveCloudflareAI();\n\n  if (!ai) {\n    throw new Error(\"Cloudflare AI binding not available\");\n  }\n\n  const result = await ai.run(\"@cf/deepgram/aura-1\", {\n    text: text.slice(0, 5000),\n    speaker: auraVoice,\n    encoding: \"mp3\",\n  });\n\n  return {\n    audio: result,\n    contentType: \"audio/mpeg\",\n  };\n}\n","/**\n * @fileoverview Unified text-to-speech API supporting Kokoro (default) and Deepgram\n *\n * Kokoro: Faster, more natural, runs on Node CPU\n * Deepgram: Requires Cloudflare AI binding, MP3 output\n */\nimport type { TTSOptions, TTSResult } from \"./types/types\";\nimport { generateKokoroSpeech } from \"./core/kokoro\";\nimport { generateDeepgramSpeech } from \"./core/deepgram\";\n\nexport * from \"./types/types\";\n\n/**\n * Generate speech from text using the specified provider\n *\n * @param options - TTS configuration\n * @returns Audio buffer and content type\n *\n * @example\n * ```ts\n * // Use Kokoro (default)\n * const audio = await generateSpeech({\n *   text: \"Hello world\",\n *   voice: \"af_heart\"\n * });\n *\n * // Use Deepgram\n * const audio = await generateSpeech({\n *   text: \"Hello world\",\n *   provider: \"deepgram\",\n *   voice: \"angus\"\n * });\n * ```\n */\nexport async function generateSpeech(\n  options: TTSOptions\n): Promise<TTSResult> {\n  const { text, provider = \"kokoro\", voice = \"af_heart\" } = options;\n\n  if (!text || typeof text !== \"string\" || text.trim().length === 0) {\n    throw new Error(\"Text is required\");\n  }\n\n  switch (provider) {\n    case \"kokoro\":\n      return generateKokoroSpeech(text, voice);\n\n    case \"deepgram\":\n      return generateDeepgramSpeech(text, voice);\n\n    default:\n      throw new Error(`Unknown TTS provider: ${provider}`);\n  }\n}\n"],"names":["KOKORO_VOICES","DEEPGRAM_SPEAKERS","ttsInstance","modelLoading","getKokoroTTS","transformers","StyleTextToSpeech2Model","AutoTokenizer","model_id","model","tokenizer","error","generateKokoroSpeech","text","voice","resolveCloudflareAI","_a","_b","g","ctx","generateDeepgramSpeech","speaker","auraVoice","ai","generateSpeech","options","provider"],"mappings":"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"}

package/dist/types/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Type definitions for text-to-speech providers
+ */
+export type TTSProvider = "kokoro" | "deepgram";
+export interface TTSOptions {
+    text: string;
+    provider?: TTSProvider;
+    voice?: string;
+}
+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 type KokoroVoice = (typeof KOKORO_VOICES)[number];
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-voice-control",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "React voice control with speech transcription, vocalization, and interruption (STT/TTS/VAD) support.",
   "repository": {
     "type": "git",
@@ -14,19 +14,12 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    },
-    "./hooks": {
-      "types": "./dist/hooks/index.d.ts",
-      "import": "./dist/hooks/index.js"
-    },
-    "./components": {
-      "types": "./dist/components/index.d.ts",
-      "import": "./dist/components/index.js"
     }
   },
   "files": [
     "dist",
-    "src"
+    "speech",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc && vite build",
@@ -34,6 +27,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
     "lucide-react": "^0.344.0",
     "@moonshine-ai/moonshine-js": "^0.1.29",
     "react": "^18.0.0",
@@ -50,5 +44,8 @@
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^3.0.0"
+  },
   "license": "rights.institute/PROSPER"
 }

package/speech/core/KokoroTTS.js

@@ -0,0 +1,91 @@
+import { StyleTextToSpeech2Model, AutoTokenizer, Tensor, RawAudio } from "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.5.1/dist/transformers.min.js";
+
+import { phonemize } from "./phonemize.js";
+import { getVoiceData, VOICES } from "./voices.js";
+
+const STYLE_DIM = 256;
+const SAMPLE_RATE = 24000;
+
+export class KokoroTTS {
+  /**
+   * Create a new KokoroTTS instance.
+   * @param {import('@huggingface/transformers').StyleTextToSpeech2Model} model The model
+   * @param {import('@huggingface/transformers').PreTrainedTokenizer} tokenizer The tokenizer
+   */
+  constructor(model, tokenizer) {
+    this.model = model;
+    this.tokenizer = tokenizer;
+  }
+
+  /**
+   * Load a KokoroTTS model from the Hugging Face Hub.
+   * @param {string} model_id The model id
+   * @param {Object} options Additional options
+   * @param {"fp32"|"fp16"|"q8"|"q4"|"q4f16"} [options.dtype="fp32"] The data type to use.
+   * @param {"wasm"|"webgpu"|"cpu"|null} [options.device=null] The device to run the model on.
+   * @param {import("@huggingface/transformers").ProgressCallback} [options.progress_callback=null] A callback function that is called with progress information.
+   * @returns {Promise<KokoroTTS>} The loaded model
+   */
+  static async from_pretrained(model_id, { dtype = "fp32", device = null, progress_callback = null } = {}) {
+    const model = StyleTextToSpeech2Model.from_pretrained(model_id, { progress_callback, dtype, device });
+    const tokenizer = AutoTokenizer.from_pretrained(model_id, { progress_callback });
+
+    const info = await Promise.all([model, tokenizer]);
+    return new KokoroTTS(...info);
+  }
+
+  get voices() {
+    return VOICES;
+  }
+
+  list_voices() {
+    console.table(VOICES);
+  }
+
+  /**
+   * Generate audio from text.
+   *
+   * Note: The model will be loaded on the first call, and subsequent calls will use the same model.
+   * @param {string} text The input text
+   * @param {Object} options Additional options
+   * @param {keyof typeof VOICES} [options.voice="af"] The voice style to use
+   * @param {number} [options.speed=1] The speaking speed
+   * @returns {Promise<RawAudio>} The generated audio
+   */
+  async generate(text, { voice = "af", speed = 1 } = {}) {
+    if (!VOICES.hasOwnProperty(voice)) {
+      console.error(`Voice "${voice}" not found. Available voices:`);
+      console.table(VOICES);
+      throw new Error(`Voice "${voice}" not found. Should be one of: ${Object.keys(VOICES).join(", ")}.`);
+    }
+
+    const language = voice.at(0); // "a" or "b"
+    const phonemes = await phonemize(text, language);
+    const { input_ids } = this.tokenizer(phonemes, {
+      truncation: true,
+    });
+
+    // Select voice style based on number of input tokens
+    const num_tokens = Math.max(
+      input_ids.dims.at(-1) - 2, // Without padding;
+      0,
+    );
+
+    // Load voice style
+    const data = await getVoiceData(voice);
+    const offset = num_tokens * STYLE_DIM;
+    const voiceData = data.slice(offset, offset + STYLE_DIM);
+
+    // Prepare model inputs
+    const inputs = {
+      input_ids,
+      style: new Tensor("float32", voiceData, [1, STYLE_DIM]),
+      speed: new Tensor("float32", [speed], [1]),
+    };
+
+    // Generate audio
+    const { waveform } = await this.model(inputs);
+
+    return new RawAudio(waveform.data, SAMPLE_RATE);
+  }
+}

package/speech/core/deepgram.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Deepgram TTS provider implementation using Cloudflare Workers AI
+ * Requires Cloudflare AI binding
+ */
+import type { TTSResult } from "../types/types";
+import { DEEPGRAM_SPEAKERS, type DeepgramSpeaker } from "../types/types";
+
+/**
+ * Resolve the Cloudflare Workers AI binding at runtime without a hard
+ * dependency on the host application. Consumers running on Cloudflare can
+ * expose the context by setting `globalThis.getCloudflareContext` (as the
+ * `@opennextjs/cloudflare` / `@cloudflare/next-on-pages` helpers do) or by
+ * placing the bound `env` on `globalThis.__env__`.
+ */
+function resolveCloudflareAI(): any {
+  const g = globalThis as any;
+  try {
+    if (typeof g.getCloudflareContext === "function") {
+      const ctx = g.getCloudflareContext();
+      if (ctx?.env?.AI) return ctx.env.AI;
+    }
+  } catch {
+    // CF context helper threw (e.g. called outside a request scope)
+  }
+  return g.__env__?.AI ?? g.AI;
+}
+
+/**
+ * Generate speech from text using Deepgram Aura via Cloudflare Workers AI
+ */
+export async function generateDeepgramSpeech(
+  text: string,
+  speaker: string = "angus"
+): Promise<TTSResult> {
+  // Validate speaker
+  const auraVoice = DEEPGRAM_SPEAKERS.includes(speaker as DeepgramSpeaker)
+    ? (speaker as DeepgramSpeaker)
+    : "angus";
+
+  const ai = resolveCloudflareAI();
+
+  if (!ai) {
+    throw new Error("Cloudflare AI binding not available");
+  }
+
+  const result = await ai.run("@cf/deepgram/aura-1", {
+    text: text.slice(0, 5000),
+    speaker: auraVoice,
+    encoding: "mp3",
+  });
+
+  return {
+    audio: result,
+    contentType: "audio/mpeg",
+  };
+}

package/speech/core/kokoro.js

@@ -0,0 +1,93 @@
+import { StyleTextToSpeech2Model, AutoTokenizer, Tensor, RawAudio } from "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.5.1/dist/transformers.min.js";
+//import { StyleTextToSpeech2Model, AutoTokenizer, Tensor, RawAudio } from "@huggingface/transformers";
+
+
+import { phonemize } from "./phonemize.js";
+import { getVoiceData, VOICES } from "./voices.js";
+
+const STYLE_DIM = 256;
+const SAMPLE_RATE = 24000;
+
+export class KokoroTTS {
+  /**
+   * Create a new KokoroTTS instance.
+   * @param {import('@huggingface/transformers').StyleTextToSpeech2Model} model The model
+   * @param {import('@huggingface/transformers').PreTrainedTokenizer} tokenizer The tokenizer
+   */
+  constructor(model, tokenizer) {
+    this.model = model;
+    this.tokenizer = tokenizer;
+  }
+
+  /**
+   * Load a KokoroTTS model from the Hugging Face Hub.
+   * @param {string} model_id The model id
+   * @param {Object} options Additional options
+   * @param {"fp32"|"fp16"|"q8"|"q4"|"q4f16"} [options.dtype="fp32"] The data type to use.
+   * @param {"wasm"|"webgpu"|"cpu"|null} [options.device=null] The device to run the model on.
+   * @param {import("@huggingface/transformers").ProgressCallback} [options.progress_callback=null] A callback function that is called with progress information.
+   * @returns {Promise<KokoroTTS>} The loaded model
+   */
+  static async from_pretrained(model_id, { dtype = "fp32", device = null, progress_callback = null } = {}) {
+    const model = StyleTextToSpeech2Model.from_pretrained(model_id, { progress_callback, dtype, device });
+    const tokenizer = AutoTokenizer.from_pretrained(model_id, { progress_callback });
+
+    const info = await Promise.all([model, tokenizer]);
+    return new KokoroTTS(...info);
+  }
+
+  get voices() {
+    return VOICES;
+  }
+
+  list_voices() {
+    console.table(VOICES);
+  }
+
+  /**
+   * Generate audio from text.
+   *
+   * Note: The model will be loaded on the first call, and subsequent calls will use the same model.
+   * @param {string} text The input text
+   * @param {Object} options Additional options
+   * @param {keyof typeof VOICES} [options.voice="af"] The voice style to use
+   * @param {number} [options.speed=1] The speaking speed
+   * @returns {Promise<RawAudio>} The generated audio
+   */
+  async generate(text, { voice = "af", speed = 1 } = {}) {
+    if (!VOICES.hasOwnProperty(voice)) {
+      console.error(`Voice "${voice}" not found. Available voices:`);
+      console.table(VOICES);
+      throw new Error(`Voice "${voice}" not found. Should be one of: ${Object.keys(VOICES).join(", ")}.`);
+    }
+
+    const language = voice.at(0); // "a" or "b"
+    const phonemes = await phonemize(text, language);
+    const { input_ids } = this.tokenizer(phonemes, {
+      truncation: true,
+    });
+
+    // Select voice style based on number of input tokens
+    const num_tokens = Math.max(
+      input_ids.dims.at(-1) - 2, // Without padding;
+      0,
+    );
+
+    // Load voice style
+    const data = await getVoiceData(voice);
+    const offset = num_tokens * STYLE_DIM;
+    const voiceData = data.slice(offset, offset + STYLE_DIM);
+
+    // Prepare model inputs
+    const inputs = {
+      input_ids,
+      style: new Tensor("float32", voiceData, [1, STYLE_DIM]),
+      speed: new Tensor("float32", [speed], [1]),
+    };
+
+    // Generate audio
+    const { waveform } = await this.model(inputs);
+
+    return new RawAudio(waveform.data, SAMPLE_RATE);
+  }
+}

package/speech/core/kokoro.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Kokoro TTS provider implementation using Hugging Face transformers
+ * Runs on Node.js CPU via transformers library
+ */
+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;
+}
+
+/**
+ * Generate speech from text using Kokoro
+ */
+export async function generateKokoroSpeech(
+  text: string,
+  voice: string = "af_heart"
+): 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;
+  }
+}