react-native-tts-kit 0.1.0

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["export type EngineId = 'supertonic' | 'system' | 'neutts' | 'cloud:eleven' | 'cloud:openai' | 'cloud:cartesia';\n\nexport type SupertonicLang =\n  | 'en' | 'ko' | 'ja' | 'ar' | 'bg' | 'cs' | 'da' | 'de' | 'el' | 'es'\n  | 'et' | 'fi' | 'fr' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'lt' | 'lv'\n  | 'nl' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'sv' | 'tr' | 'uk' | 'vi';\n\nexport interface Voice {\n  id: string;\n  name: string;\n  gender?: 'male' | 'female' | 'neutral';\n  engine: EngineId;\n  language?: string;\n  sampleUrl?: string;\n}\n\n/**\n * Options for synthesis calls.\n *\n * **Privacy:** the text you pass to `speak()` / `stream()` is processed\n * entirely on-device. It is never sent to a remote server when using the\n * `supertonic` engine. The `system` engine forwards text to the OS-level\n * TTS service (`expo-speech`), which on some platforms (notably some\n * Android OEMs) may route through a cloud service — verify with the\n * device vendor's privacy policy if that matters for your app.\n */\nexport interface SpeakOptions {\n  voice?: string;\n  engine?: EngineId;\n  /**\n   * BCP-47 language code passed to the model.\n   * Supertonic-3 supports 31 languages (see SupertonicLang); other engines may\n   * use this differently (system engine forwards it as-is to expo-speech).\n   */\n  language?: string;\n  /**\n   * Speech speed multiplier (default 1.05 — matches Supertonic upstream).\n   * Higher = faster.\n   */\n  rate?: number;\n  pitch?: number;\n  volume?: number;\n  /**\n   * Number of denoising steps for diffusion-based engines (Supertonic).\n   * Default 8. Lower = faster but lower quality.\n   */\n  totalStep?: number;\n  onStart?: () => void;\n  onDone?: () => void;\n  onError?: (err: Error) => void;\n}\n\nexport interface StreamHandle {\n  id: string;\n  on(event: 'chunk', listener: (pcm: Uint8Array) => void): this;\n  on(event: 'end', listener: () => void): this;\n  on(event: 'error', listener: (err: Error) => void): this;\n  cancel(): Promise<void>;\n}\n\nexport interface CloneOptions {\n  sampleUri: string;\n  name?: string;\n}\n\nexport interface ClonedVoice {\n  id: string;\n  name: string;\n  engine: EngineId;\n}\n\nexport interface PrefetchProgress {\n  bytesDownloaded: number;\n  totalBytes: number;\n  percent: number;\n}\n\nexport interface EngineCapabilities {\n  streaming: boolean;\n  cloning: boolean;\n  emotionTags: boolean;\n  offline: boolean;\n  languages: string[];\n}\n\nexport interface TTSKitError extends Error {\n  code:\n    | 'ENGINE_NOT_AVAILABLE'\n    | 'VOICE_NOT_FOUND'\n    | 'MODEL_NOT_LOADED'\n    | 'SYNTHESIS_FAILED'\n    | 'PERMISSION_DENIED'\n    | 'NETWORK_ERROR'\n    | 'CANCELLED';\n}\n"]}

package/build/voices/catalog.d.ts

@@ -0,0 +1,12 @@
+import type { Voice } from '../types';
+/**
+ * Supertonic-3 ships 10 voices (5 M, 5 F). Each voice is language-agnostic —
+ * the model takes a `language` argument at call time, separate from the voice.
+ * Pair any voice with any of the 31 supported languages.
+ */
+export declare const SUPERTONIC_VOICES: Voice[];
+export declare const SUPERTONIC_LANGUAGES: string[];
+export declare const DEFAULT_VOICE_ID = "F1";
+export declare const DEFAULT_LANGUAGE = "en";
+export declare function findVoice(id: string): Voice | undefined;
+//# sourceMappingURL=catalog.d.ts.map

package/build/voices/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/voices/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,EAWpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,UAIhC,CAAC;AAEF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAEvD"}

package/build/voices/catalog.js

@@ -0,0 +1,28 @@
+/**
+ * Supertonic-3 ships 10 voices (5 M, 5 F). Each voice is language-agnostic —
+ * the model takes a `language` argument at call time, separate from the voice.
+ * Pair any voice with any of the 31 supported languages.
+ */
+export const SUPERTONIC_VOICES = [
+    { id: 'M1', name: 'M1', gender: 'male', engine: 'supertonic' },
+    { id: 'M2', name: 'M2', gender: 'male', engine: 'supertonic' },
+    { id: 'M3', name: 'M3', gender: 'male', engine: 'supertonic' },
+    { id: 'M4', name: 'M4', gender: 'male', engine: 'supertonic' },
+    { id: 'M5', name: 'M5', gender: 'male', engine: 'supertonic' },
+    { id: 'F1', name: 'F1', gender: 'female', engine: 'supertonic' },
+    { id: 'F2', name: 'F2', gender: 'female', engine: 'supertonic' },
+    { id: 'F3', name: 'F3', gender: 'female', engine: 'supertonic' },
+    { id: 'F4', name: 'F4', gender: 'female', engine: 'supertonic' },
+    { id: 'F5', name: 'F5', gender: 'female', engine: 'supertonic' },
+];
+export const SUPERTONIC_LANGUAGES = [
+    'en', 'ko', 'ja', 'ar', 'bg', 'cs', 'da', 'de', 'el', 'es',
+    'et', 'fi', 'fr', 'hi', 'hr', 'hu', 'id', 'it', 'lt', 'lv',
+    'nl', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sv', 'tr', 'uk', 'vi',
+];
+export const DEFAULT_VOICE_ID = 'F1';
+export const DEFAULT_LANGUAGE = 'en';
+export function findVoice(id) {
+    return SUPERTONIC_VOICES.find((v) => v.id === id);
+}
+//# sourceMappingURL=catalog.js.map

package/build/voices/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/voices/catalog.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAY;IACxC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAI,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAI,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAI,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAI,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAI,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE;IAChE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE;CACjE,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAC1D,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAC1D,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CACjE,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACpD,CAAC","sourcesContent":["import type { Voice } from '../types';\n\n/**\n * Supertonic-3 ships 10 voices (5 M, 5 F). Each voice is language-agnostic —\n * the model takes a `language` argument at call time, separate from the voice.\n * Pair any voice with any of the 31 supported languages.\n */\nexport const SUPERTONIC_VOICES: Voice[] = [\n  { id: 'M1', name: 'M1', gender: 'male',   engine: 'supertonic' },\n  { id: 'M2', name: 'M2', gender: 'male',   engine: 'supertonic' },\n  { id: 'M3', name: 'M3', gender: 'male',   engine: 'supertonic' },\n  { id: 'M4', name: 'M4', gender: 'male',   engine: 'supertonic' },\n  { id: 'M5', name: 'M5', gender: 'male',   engine: 'supertonic' },\n  { id: 'F1', name: 'F1', gender: 'female', engine: 'supertonic' },\n  { id: 'F2', name: 'F2', gender: 'female', engine: 'supertonic' },\n  { id: 'F3', name: 'F3', gender: 'female', engine: 'supertonic' },\n  { id: 'F4', name: 'F4', gender: 'female', engine: 'supertonic' },\n  { id: 'F5', name: 'F5', gender: 'female', engine: 'supertonic' },\n];\n\nexport const SUPERTONIC_LANGUAGES = [\n  'en', 'ko', 'ja', 'ar', 'bg', 'cs', 'da', 'de', 'el', 'es',\n  'et', 'fi', 'fr', 'hi', 'hr', 'hu', 'id', 'it', 'lt', 'lv',\n  'nl', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sv', 'tr', 'uk', 'vi',\n];\n\nexport const DEFAULT_VOICE_ID = 'F1';\nexport const DEFAULT_LANGUAGE = 'en';\n\nexport function findVoice(id: string): Voice | undefined {\n  return SUPERTONIC_VOICES.find((v) => v.id === id);\n}\n"]}

package/build/voices/prosody.d.ts

@@ -0,0 +1,8 @@
+export type ProsodyTag = 'excited' | 'whisper' | 'calm' | 'sad' | 'angry' | 'fast' | 'slow';
+export interface ProsodySegment {
+    text: string;
+    tags: ProsodyTag[];
+}
+export declare function parseProsody(input: string): ProsodySegment[];
+export declare function stripProsody(input: string): string;
+//# sourceMappingURL=prosody.d.ts.map

package/build/voices/prosody.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prosody.d.ts","sourceRoot":"","sources":["../../src/voices/prosody.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,EAAE,CAAC;CACpB;AAID,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAyB5D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/build/voices/prosody.js

@@ -0,0 +1,28 @@
+const TAG_RE = /\[([a-z_ ]+)\]/gi;
+export function parseProsody(input) {
+    const segments = [];
+    let lastIndex = 0;
+    let activeTags = [];
+    let match;
+    while ((match = TAG_RE.exec(input)) !== null) {
+        if (match.index > lastIndex) {
+            const text = input.slice(lastIndex, match.index).trim();
+            if (text)
+                segments.push({ text, tags: [...activeTags] });
+        }
+        const tags = match[1]
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((t) => ['excited', 'whisper', 'calm', 'sad', 'angry', 'fast', 'slow'].includes(t));
+        activeTags = tags;
+        lastIndex = TAG_RE.lastIndex;
+    }
+    const tail = input.slice(lastIndex).trim();
+    if (tail)
+        segments.push({ text: tail, tags: [...activeTags] });
+    return segments.length ? segments : [{ text: input, tags: [] }];
+}
+export function stripProsody(input) {
+    return input.replace(TAG_RE, '').replace(/\s+/g, ' ').trim();
+}
+//# sourceMappingURL=prosody.js.map

package/build/voices/prosody.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prosody.js","sourceRoot":"","sources":["../../src/voices/prosody.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,GAAG,kBAAkB,CAAC;AAElC,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,QAAQ,GAAqB,EAAE,CAAC;IACtC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,UAAU,GAAiB,EAAE,CAAC;IAClC,IAAI,KAA6B,CAAC;IAElC,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC7C,IAAI,KAAK,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;YACxD,IAAI,IAAI;gBAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC;aAClB,WAAW,EAAE;aACb,KAAK,CAAC,KAAK,CAAC;aACZ,MAAM,CAAC,CAAC,CAAC,EAAmB,EAAE,CAC7B,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAC3E,CAAC;QACJ,UAAU,GAAG,IAAI,CAAC;QAClB,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,IAAI;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;IAE/D,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAC/D,CAAC","sourcesContent":["export type ProsodyTag = 'excited' | 'whisper' | 'calm' | 'sad' | 'angry' | 'fast' | 'slow';\n\nexport interface ProsodySegment {\n  text: string;\n  tags: ProsodyTag[];\n}\n\nconst TAG_RE = /\\[([a-z_ ]+)\\]/gi;\n\nexport function parseProsody(input: string): ProsodySegment[] {\n  const segments: ProsodySegment[] = [];\n  let lastIndex = 0;\n  let activeTags: ProsodyTag[] = [];\n  let match: RegExpExecArray | null;\n\n  while ((match = TAG_RE.exec(input)) !== null) {\n    if (match.index > lastIndex) {\n      const text = input.slice(lastIndex, match.index).trim();\n      if (text) segments.push({ text, tags: [...activeTags] });\n    }\n    const tags = match[1]\n      .toLowerCase()\n      .split(/\\s+/)\n      .filter((t): t is ProsodyTag =>\n        ['excited', 'whisper', 'calm', 'sad', 'angry', 'fast', 'slow'].includes(t)\n      );\n    activeTags = tags;\n    lastIndex = TAG_RE.lastIndex;\n  }\n\n  const tail = input.slice(lastIndex).trim();\n  if (tail) segments.push({ text: tail, tags: [...activeTags] });\n\n  return segments.length ? segments : [{ text: input, tags: [] }];\n}\n\nexport function stripProsody(input: string): string {\n  return input.replace(TAG_RE, '').replace(/\\s+/g, ' ').trim();\n}\n"]}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["ios", "android"],
+  "ios": {
+    "modules": ["RNTTSKitModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.ttskit.RNTTSKitModule"]
+  }
+}

package/ios/RNTTSKit.podspec

@@ -0,0 +1,28 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'RNTTSKit'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = { :ios => '14.0', :tvos => '14.0' }
+  s.swift_version  = '5.9'
+  s.source         = { git: 'https://github.com/ahk-d/react-native-tts-kit' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+  s.dependency 'onnxruntime-objc', '~> 1.18.0'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+  }
+
+  s.source_files = '**/*.{h,m,mm,swift,hpp,cpp}'
+  s.resources    = ['Resources/**/*']
+end

package/ios/RNTTSKitModule.swift

@@ -0,0 +1,133 @@
+import ExpoModulesCore
+
+public class RNTTSKitModule: Module {
+    private var session: SupertonicSession?
+    private let audioEngine = AudioEngine()
+    private var prefetchTask: Task<Void, Error>?
+
+    public func definition() -> ModuleDefinition {
+        Name("RNTTSKit")
+
+        Events(
+            "onPrefetchProgress",
+            "onStreamChunk",
+            "onStreamEnd",
+            "onStreamError",
+            "onSpeakStart",
+            "onSpeakDone"
+        )
+
+        OnCreate {
+            self.session = SupertonicSession()
+        }
+
+        OnDestroy {
+            self.session?.tearDown()
+            self.session = nil
+            self.audioEngine.tearDown()
+        }
+
+        AsyncFunction("isAvailable") { () -> Bool in
+            return ModelLocator.modelExists()
+        }
+
+        AsyncFunction("prefetch") { (promise: Promise) in
+            self.prefetchTask?.cancel()
+            self.prefetchTask = Task { [weak self] in
+                guard let self else { return }
+                do {
+                    try await ModelLocator.ensureModel { progress in
+                        self.sendEvent("onPrefetchProgress", [
+                            "bytesDownloaded": progress.bytesDownloaded,
+                            "totalBytes": progress.totalBytes,
+                            "percent": progress.percent
+                        ])
+                    }
+                    try self.session?.loadIfNeeded()
+                    // Pre-warm the default voice so first speak() after
+                    // prefetch doesn't pay JSON-decode + tensor-alloc cost.
+                    self.session?.prewarmDefaultVoice()
+                    promise.resolve()
+                } catch {
+                    promise.reject("PREFETCH_FAILED", error.localizedDescription)
+                }
+            }
+        }
+
+        AsyncFunction("speak") { (id: String, text: String, voiceId: String, lang: String, totalStep: Int, speed: Double, volume: Double, promise: Promise) in
+            Task { [weak self] in
+                guard let self, let session = self.session else {
+                    promise.reject("MODEL_NOT_LOADED", "Supertonic session unavailable")
+                    return
+                }
+                do {
+                    try session.loadIfNeeded()
+                    self.sendEvent("onSpeakStart", ["id": id])
+                    let samples = try session.synthesize(
+                        text: text,
+                        lang: lang,
+                        voiceId: voiceId,
+                        totalStep: totalStep,
+                        speed: speed
+                    )
+                    try await self.audioEngine.play(pcm: samples, sampleRate: session.sampleRate, volume: Float(volume))
+                    self.sendEvent("onSpeakDone", ["id": id])
+                    promise.resolve()
+                } catch {
+                    promise.reject("SYNTHESIS_FAILED", error.localizedDescription)
+                }
+            }
+        }
+
+        AsyncFunction("stream") { (id: String, text: String, voiceId: String, lang: String, totalStep: Int, speed: Double, volume: Double, promise: Promise) in
+            Task { [weak self] in
+                guard let self, let session = self.session else {
+                    promise.reject("MODEL_NOT_LOADED", "Supertonic session unavailable")
+                    return
+                }
+                do {
+                    try session.loadIfNeeded()
+                    try self.audioEngine.beginStream(sampleRate: session.sampleRate, volume: Float(volume))
+                    try session.synthesizeStreaming(
+                        text: text,
+                        lang: lang,
+                        voiceId: voiceId,
+                        totalStep: totalStep,
+                        speed: speed
+                    ) { samples in
+                        let pcm16 = SupertonicSession.toPCM16(samples: samples)
+                        self.sendEvent("onStreamChunk", ["id": id, "pcm": pcm16.base64EncodedString()])
+                        self.audioEngine.feedStream(chunk: samples)
+                    }
+                    self.audioEngine.endStream()
+                    self.sendEvent("onStreamEnd", ["id": id])
+                    promise.resolve()
+                } catch {
+                    self.audioEngine.endStream()
+                    self.sendEvent("onStreamError", ["id": id, "message": error.localizedDescription])
+                    promise.reject("SYNTHESIS_FAILED", error.localizedDescription)
+                }
+            }
+        }
+
+        AsyncFunction("stop") { (promise: Promise) in
+            self.audioEngine.stop()
+            self.session?.cancel()
+            promise.resolve()
+        }
+
+        AsyncFunction("clearCache") { (promise: Promise) in
+            // Tear down loaded ORTSessions first — they hold references to the
+            // files we're about to delete. Otherwise the next loadIfNeeded()
+            // would short-circuit (isReady == true) and skip re-loading from
+            // disk, masking whether the re-download actually worked.
+            self.prefetchTask?.cancel()
+            self.audioEngine.stop()
+            self.session?.cancel()
+            self.session?.tearDown()
+            ModelLocator.clearCache()
+            self.session = SupertonicSession()
+            promise.resolve()
+        }
+    }
+}

package/ios/Supertonic/AudioEngine.swift

@@ -0,0 +1,110 @@
+import AVFoundation
+import Foundation
+
+/// Streams float32 PCM through AVAudioEngine. Used for both blocking `speak()`
+/// (one-shot enqueue + wait) and `stream()` (chunk-by-chunk feeding).
+///
+/// We keep PCM as float32 internally — that's what Supertonic emits and what
+/// `AVAudioPlayerNode` natively consumes. The Int16 conversion only happens
+/// at the JS bridge boundary (when emitting `onStreamChunk`).
+final class AudioEngine {
+    private let engine = AVAudioEngine()
+    private let player = AVAudioPlayerNode()
+    private var configuredSampleRate: Double = 0
+    private var attached = false
+    private var streaming = false
+    private let queue = DispatchQueue(label: "ttskit.audioengine", qos: .userInitiated)
+
+    /// Configure (or reconfigure) the player for the given sample rate.
+    private func ensureAttached(sampleRate: Int) throws {
+        let target = Double(sampleRate)
+        if attached && configuredSampleRate == target { return }
+
+        if attached {
+            engine.disconnectNodeOutput(player)
+        } else {
+            engine.attach(player)
+        }
+        let format = AVAudioFormat(commonFormat: .pcmFormatFloat32, sampleRate: target, channels: 1, interleaved: false)
+        engine.connect(player, to: engine.mainMixerNode, format: format)
+
+        let session = AVAudioSession.sharedInstance()
+        try session.setCategory(.playback, mode: .spokenAudio, options: [.duckOthers])
+        try session.setActive(true, options: [])
+
+        if !engine.isRunning {
+            try engine.start()
+        }
+        configuredSampleRate = target
+        attached = true
+    }
+
+    /// One-shot playback that resolves only when the buffer has finished playing.
+    func play(pcm: [Float], sampleRate: Int, volume: Float) async throws {
+        try ensureAttached(sampleRate: sampleRate)
+        player.volume = volume
+        guard let buffer = makeBuffer(from: pcm, sampleRate: sampleRate) else { return }
+
+        await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
+            player.scheduleBuffer(buffer, at: nil, options: []) {
+                cont.resume()
+            }
+            if !player.isPlaying { player.play() }
+        }
+    }
+
+    func beginStream(sampleRate: Int, volume: Float) throws {
+        try ensureAttached(sampleRate: sampleRate)
+        player.volume = volume
+        streaming = true
+        if !player.isPlaying { player.play() }
+    }
+
+    func feedStream(chunk: [Float]) {
+        // Only refuse work if we've been fully stopped — not on endStream(),
+        // which only signals "no more chunks coming." Pending buffers that are
+        // already in the async pipeline must still play out.
+        guard streaming else { return }
+        let sr = Int(configuredSampleRate)
+        queue.async { [weak self] in
+            guard let self, let buffer = self.makeBuffer(from: chunk, sampleRate: sr) else { return }
+            self.player.scheduleBuffer(buffer, at: nil, options: [], completionHandler: nil)
+        }
+    }
+
+    /// Signals that no more chunks will be fed. Does NOT cancel pending audio —
+    /// `feedStream` may have enqueued buffers on the audio queue that haven't
+    /// scheduled yet. Those must play out so the user hears the audio they
+    /// synthesized. Use `stop()` to interrupt actual playback.
+    func endStream() {
+        // Intentionally leaves `streaming = true` so any feedStream() calls
+        // still in flight from the synthesis callback complete normally.
+        // The flag is reset by `stop()` or by the next `beginStream()`.
+    }
+
+    func stop() {
+        streaming = false
+        if player.isPlaying { player.stop() }
+    }
+
+    func tearDown() {
+        stop()
+        if engine.isRunning { engine.stop() }
+        attached = false
+        configuredSampleRate = 0
+    }
+
+    private func makeBuffer(from pcm: [Float], sampleRate: Int) -> AVAudioPCMBuffer? {
+        guard !pcm.isEmpty,
+              let format = AVAudioFormat(commonFormat: .pcmFormatFloat32, sampleRate: Double(sampleRate), channels: 1, interleaved: false),
+              let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: AVAudioFrameCount(pcm.count))
+        else { return nil }
+        buffer.frameLength = AVAudioFrameCount(pcm.count)
+        if let dst = buffer.floatChannelData?.pointee {
+            pcm.withUnsafeBufferPointer { src in
+                dst.update(from: src.baseAddress!, count: pcm.count)
+            }
+        }
+        return buffer
+    }
+}