react-native-tts-kit 0.1.0

package/src/engines/SystemEngine.ts

@@ -0,0 +1,96 @@
+import type {
+  EngineCapabilities,
+  EngineId,
+  PrefetchProgress,
+  SpeakOptions,
+  StreamHandle,
+  Voice,
+} from '../types';
+import type { Engine } from './Engine';
+
+type ExpoSpeechModule = {
+  speak(text: string, options?: any): void;
+  stop(): Promise<void>;
+  getAvailableVoicesAsync(): Promise<Array<{ identifier: string; name: string; language: string }>>;
+};
+
+let cached: ExpoSpeechModule | null = null;
+function loadExpoSpeech(): ExpoSpeechModule | null {
+  if (cached) return cached;
+  try {
+    cached = require('expo-speech') as ExpoSpeechModule;
+    return cached;
+  } catch {
+    return null;
+  }
+}
+
+export class SystemEngine implements Engine {
+  readonly id: EngineId = 'system';
+  readonly capabilities: EngineCapabilities = {
+    streaming: false,
+    cloning: false,
+    emotionTags: false,
+    offline: true,
+    languages: ['*'],
+  };
+
+  async isAvailable(): Promise<boolean> {
+    return loadExpoSpeech() !== null;
+  }
+
+  async prefetch(_onProgress?: (p: PrefetchProgress) => void): Promise<void> {
+    // No-op: system voices are bundled with the OS.
+  }
+
+  async getVoices(): Promise<Voice[]> {
+    const speech = loadExpoSpeech();
+    if (!speech) return [];
+    const voices = await speech.getAvailableVoicesAsync();
+    return voices.map((v) => ({
+      id: v.identifier,
+      name: v.name,
+      language: v.language,
+      engine: 'system' as EngineId,
+    }));
+  }
+
+  speak(text: string, options: SpeakOptions = {}): Promise<void> {
+    const speech = loadExpoSpeech();
+    if (!speech) {
+      throw new Error('[ttskit] expo-speech is not installed');
+    }
+    return new Promise((resolve, reject) => {
+      try {
+        speech.speak(text, {
+          voice: options.voice,
+          language: options.language,
+          rate: options.rate,
+          pitch: options.pitch,
+          volume: options.volume,
+          onStart: options.onStart,
+          onDone: () => {
+            options.onDone?.();
+            resolve();
+          },
+          onError: (err: Error) => {
+            options.onError?.(err);
+            reject(err);
+          },
+          onStopped: () => resolve(),
+        });
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  stream(_text: string, _options: SpeakOptions = {}): StreamHandle {
+    throw new Error('[ttskit] System engine does not support streaming. Use engine: "supertonic".');
+  }
+
+  async stop(): Promise<void> {
+    const speech = loadExpoSpeech();
+    await speech?.stop();
+  }
+}

package/src/engines/__tests__/BufferedStreamEmitter.test.ts

@@ -0,0 +1,65 @@
+import { BufferedStreamEmitter } from '../BufferedStreamEmitter';
+
+describe('BufferedStreamEmitter', () => {
+  it('delivers chunks emitted before any listener attaches', () => {
+    const emitter = new BufferedStreamEmitter();
+    const a = new Uint8Array([1, 2, 3]);
+    const b = new Uint8Array([4, 5]);
+    emitter.emitChunk(a);
+    emitter.emitChunk(b);
+
+    const received: Uint8Array[] = [];
+    emitter.on('chunk', (pcm) => received.push(pcm));
+
+    expect(received).toEqual([a, b]);
+  });
+
+  it('forwards live chunks once a listener is attached', () => {
+    const emitter = new BufferedStreamEmitter();
+    const received: Uint8Array[] = [];
+    emitter.on('chunk', (pcm) => received.push(pcm));
+
+    const a = new Uint8Array([7]);
+    emitter.emitChunk(a);
+    expect(received).toEqual([a]);
+  });
+
+  it('replays a buffered end event to a late-attaching listener', () => {
+    const emitter = new BufferedStreamEmitter();
+    emitter.emitEnd();
+    const fn = jest.fn();
+    emitter.on('end', fn);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not double-fire end when a listener is already attached', () => {
+    const emitter = new BufferedStreamEmitter();
+    const fn = jest.fn();
+    emitter.on('end', fn);
+    emitter.emitEnd();
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('replays a buffered error to a late-attaching listener', () => {
+    const emitter = new BufferedStreamEmitter();
+    const err = new Error('boom');
+    emitter.emitError(err);
+    const fn = jest.fn();
+    emitter.on('error', fn);
+    expect(fn).toHaveBeenCalledWith(err);
+  });
+
+  it('drains pending chunks only once', () => {
+    const emitter = new BufferedStreamEmitter();
+    const a = new Uint8Array([1]);
+    emitter.emitChunk(a);
+    const fn = jest.fn();
+    emitter.on('chunk', fn);
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    // Add a second listener — it should NOT see the already-drained chunk.
+    const fn2 = jest.fn();
+    emitter.on('chunk', fn2);
+    expect(fn2).not.toHaveBeenCalled();
+  });
+});

package/src/index.ts

@@ -0,0 +1,156 @@
+import { Platform } from 'react-native';
+
+import { SupertonicEngine } from './engines/SupertonicEngine';
+import { SystemEngine } from './engines/SystemEngine';
+import type { Engine } from './engines/Engine';
+import type {
+  ClonedVoice,
+  CloneOptions,
+  EngineId,
+  PrefetchProgress,
+  SpeakOptions,
+  StreamHandle,
+  Voice,
+} from './types';
+
+export type {
+  ClonedVoice,
+  CloneOptions,
+  EngineId,
+  PrefetchProgress,
+  SpeakOptions,
+  StreamHandle,
+  Voice,
+} from './types';
+export type { Engine } from './engines/Engine';
+export { parseProsody, stripProsody } from './voices/prosody';
+export { SUPERTONIC_VOICES, SUPERTONIC_LANGUAGES } from './voices/catalog';
+
+const engines = new Map<EngineId, Engine>();
+engines.set('supertonic', new SupertonicEngine());
+engines.set('system', new SystemEngine());
+
+let activeEngineId: EngineId = 'supertonic';
+
+function getEngine(id: EngineId = activeEngineId): Engine {
+  const engine = engines.get(id);
+  if (!engine) {
+    throw new Error(`[ttskit] Engine "${id}" is not registered.`);
+  }
+  return engine;
+}
+
+export const TTSKit = {
+  setEngine(id: EngineId): void {
+    if (!engines.has(id)) {
+      throw new Error(`[ttskit] Engine "${id}" is not registered.`);
+    }
+    activeEngineId = id;
+  },
+
+  getEngine(): EngineId {
+    return activeEngineId;
+  },
+
+  registerEngine(engine: Engine): void {
+    engines.set(engine.id, engine);
+  },
+
+  /**
+   * Suggest a sensible engine for the current device.
+   *
+   * - On iOS, always returns `'supertonic'` — every iPhone with iOS 13+ has the
+   *   Neural Engine and runs neural TTS well (~1-2s TTFA).
+   * - On Android, returns `'supertonic'` for devices that report a recent SoC
+   *   with NNAPI 1.2+ acceleration, else `'system'`. The heuristic is
+   *   conservative: it errs toward `system` for any mid-range or older device
+   *   because Supertonic on a mid-range Snapdragon runs at ~0.5× realtime
+   *   (10s+ TTFA), which is worse UX than a robotic but instant system voice.
+   * - Defaults to `'supertonic'` on web / unknown platforms.
+   *
+   * This is opt-in. The library default is still Supertonic everywhere — apps
+   * that want graceful fallback should call this once at startup:
+   *
+   *     TTSKit.setEngine(TTSKit.recommendEngine());
+   *
+   * The detection is heuristic. For a hard guarantee, run a one-time benchmark
+   * (synthesize a known short input, measure TTFA, persist the result) and
+   * decide based on actual numbers — that's more accurate than any static
+   * device-tier list.
+   */
+  recommendEngine(): EngineId {
+    if (Platform.OS === 'ios') return 'supertonic';
+    if (Platform.OS !== 'android') return 'supertonic';
+
+    // Android tier detection. We can't read SoC directly from JS, so we rely
+    // on what `Platform.constants` exposes: Brand, Manufacturer, Model.
+    // The check is "is this likely a flagship / recent device?" — keep it
+    // narrow and additive. Anything not on the allow-list falls back to system.
+    const c: any = Platform.constants ?? {};
+    const brand = String(c.Brand ?? '').toLowerCase();
+    const manufacturer = String(c.Manufacturer ?? '').toLowerCase();
+    const model = String(c.Model ?? '').toLowerCase();
+    const apiLevel = typeof c.Release === 'string' ? parseInt(c.Release, 10) : 0;
+
+    // Android 10 = API 29 = NNAPI 1.2 floor. Below this, NNAPI partitioning
+    // is poor enough that ORT often falls back to XNNPACK silently.
+    if (apiLevel && apiLevel < 10) return 'system';
+
+    // Pixel 6 and newer have Tensor G1/G2/G3/G4 with a real NPU.
+    if (brand === 'google' && /pixel\s*([6-9]|1\d)/.test(model)) return 'supertonic';
+    // Samsung S22+ and Tab S8+ are Snapdragon 8 Gen 1 / Exynos 2200 floor.
+    if (manufacturer === 'samsung' && /sm-s9\d\d|sm-x[78]\d\d/i.test(model)) return 'supertonic';
+    // OnePlus 10 Pro+, current generation flagships are usually safe.
+    if (brand === 'oneplus' && /ne|le2\d\d\d/i.test(model)) return 'supertonic';
+
+    // Default for everything else (including the Galaxy A52 you tested on,
+    // which has SD720G and gets ~10s TTFA): use the system engine.
+    return 'system';
+  },
+
+  async isAvailable(engineId?: EngineId): Promise<boolean> {
+    return getEngine(engineId).isAvailable();
+  },
+
+  async prefetchModel(
+    onProgress?: (p: PrefetchProgress) => void,
+    engineId?: EngineId
+  ): Promise<void> {
+    return getEngine(engineId).prefetch(onProgress);
+  },
+
+  async getVoices(engineId?: EngineId): Promise<Voice[]> {
+    return getEngine(engineId).getVoices();
+  },
+
+  async speak(text: string, options: SpeakOptions = {}): Promise<void> {
+    return getEngine(options.engine).speak(text, options);
+  },
+
+  stream(text: string, options: SpeakOptions = {}): StreamHandle {
+    return getEngine(options.engine).stream(text, options);
+  },
+
+  async stop(engineId?: EngineId): Promise<void> {
+    return getEngine(engineId).stop();
+  },
+
+  /** Delete locally cached model files so the next `prefetchModel()` re-downloads.
+   *  No-op for engines that don't have a cache (e.g. the system engine). */
+  async clearCache(engineId?: EngineId): Promise<void> {
+    const engine = getEngine(engineId);
+    if (engine.clearCache) {
+      await engine.clearCache();
+    }
+  },
+
+  async cloneVoice(options: CloneOptions, engineId?: EngineId): Promise<ClonedVoice> {
+    const engine = getEngine(engineId);
+    if (!engine.cloneVoice) {
+      throw new Error(`[ttskit] Engine "${engine.id}" does not support voice cloning.`);
+    }
+    return engine.cloneVoice(options);
+  },
+};
+
+export default TTSKit;

package/src/types.ts

@@ -0,0 +1,95 @@
+export type EngineId = 'supertonic' | 'system' | 'neutts' | 'cloud:eleven' | 'cloud:openai' | 'cloud:cartesia';
+
+export type SupertonicLang =
+  | '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 interface Voice {
+  id: string;
+  name: string;
+  gender?: 'male' | 'female' | 'neutral';
+  engine: EngineId;
+  language?: string;
+  sampleUrl?: string;
+}
+
+/**
+ * Options for synthesis calls.
+ *
+ * **Privacy:** the text you pass to `speak()` / `stream()` is processed
+ * entirely on-device. It is never sent to a remote server when using the
+ * `supertonic` engine. The `system` engine forwards text to the OS-level
+ * TTS service (`expo-speech`), which on some platforms (notably some
+ * Android OEMs) may route through a cloud service — verify with the
+ * device vendor's privacy policy if that matters for your app.
+ */
+export interface SpeakOptions {
+  voice?: string;
+  engine?: EngineId;
+  /**
+   * BCP-47 language code passed to the model.
+   * Supertonic-3 supports 31 languages (see SupertonicLang); other engines may
+   * use this differently (system engine forwards it as-is to expo-speech).
+   */
+  language?: string;
+  /**
+   * Speech speed multiplier (default 1.05 — matches Supertonic upstream).
+   * Higher = faster.
+   */
+  rate?: number;
+  pitch?: number;
+  volume?: number;
+  /**
+   * Number of denoising steps for diffusion-based engines (Supertonic).
+   * Default 8. Lower = faster but lower quality.
+   */
+  totalStep?: number;
+  onStart?: () => void;
+  onDone?: () => void;
+  onError?: (err: Error) => void;
+}
+
+export interface StreamHandle {
+  id: string;
+  on(event: 'chunk', listener: (pcm: Uint8Array) => void): this;
+  on(event: 'end', listener: () => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  cancel(): Promise<void>;
+}
+
+export interface CloneOptions {
+  sampleUri: string;
+  name?: string;
+}
+
+export interface ClonedVoice {
+  id: string;
+  name: string;
+  engine: EngineId;
+}
+
+export interface PrefetchProgress {
+  bytesDownloaded: number;
+  totalBytes: number;
+  percent: number;
+}
+
+export interface EngineCapabilities {
+  streaming: boolean;
+  cloning: boolean;
+  emotionTags: boolean;
+  offline: boolean;
+  languages: string[];
+}
+
+export interface TTSKitError extends Error {
+  code:
+    | 'ENGINE_NOT_AVAILABLE'
+    | 'VOICE_NOT_FOUND'
+    | 'MODEL_NOT_LOADED'
+    | 'SYNTHESIS_FAILED'
+    | 'PERMISSION_DENIED'
+    | 'NETWORK_ERROR'
+    | 'CANCELLED';
+}

package/src/voices/__tests__/catalog.test.ts

@@ -0,0 +1,46 @@
+import {
+  DEFAULT_LANGUAGE,
+  DEFAULT_VOICE_ID,
+  SUPERTONIC_LANGUAGES,
+  SUPERTONIC_VOICES,
+  findVoice,
+} from '../catalog';
+
+describe('voice catalog', () => {
+  it('ships exactly 10 voices (5 male, 5 female)', () => {
+    expect(SUPERTONIC_VOICES).toHaveLength(10);
+    const ids = SUPERTONIC_VOICES.map((v) => v.id).sort();
+    expect(ids).toEqual(['F1', 'F2', 'F3', 'F4', 'F5', 'M1', 'M2', 'M3', 'M4', 'M5']);
+    expect(SUPERTONIC_VOICES.filter((v) => v.gender === 'male')).toHaveLength(5);
+    expect(SUPERTONIC_VOICES.filter((v) => v.gender === 'female')).toHaveLength(5);
+  });
+
+  it('all voices use the supertonic engine', () => {
+    for (const v of SUPERTONIC_VOICES) {
+      expect(v.engine).toBe('supertonic');
+    }
+  });
+
+  it('exports the 31 supported languages, no Mandarin', () => {
+    expect(SUPERTONIC_LANGUAGES).toHaveLength(31);
+    expect(SUPERTONIC_LANGUAGES).toContain('en');
+    expect(SUPERTONIC_LANGUAGES).toContain('ja');
+    expect(SUPERTONIC_LANGUAGES).toContain('ko');
+    // Mandarin is *not* in the open-source release — guard against accidental re-add.
+    expect(SUPERTONIC_LANGUAGES).not.toContain('zh');
+  });
+
+  it('default voice and language are valid catalog entries', () => {
+    expect(SUPERTONIC_VOICES.find((v) => v.id === DEFAULT_VOICE_ID)).toBeDefined();
+    expect(SUPERTONIC_LANGUAGES).toContain(DEFAULT_LANGUAGE);
+  });
+
+  describe('findVoice', () => {
+    it('finds a known voice', () => {
+      expect(findVoice('F1')?.id).toBe('F1');
+    });
+    it('returns undefined for unknown voice', () => {
+      expect(findVoice('zz9-plural-z-alpha')).toBeUndefined();
+    });
+  });
+});

package/src/voices/__tests__/prosody.test.ts

@@ -0,0 +1,63 @@
+import { parseProsody, stripProsody } from '../prosody';
+
+describe('parseProsody', () => {
+  it('returns a single tagless segment for plain text', () => {
+    expect(parseProsody('hello world')).toEqual([{ text: 'hello world', tags: [] }]);
+  });
+
+  it('returns one empty segment shape for empty input', () => {
+    // The tag regex matches nothing, so input is returned as-is.
+    expect(parseProsody('')).toEqual([{ text: '', tags: [] }]);
+  });
+
+  it('parses a single tag', () => {
+    expect(parseProsody('[excited] hello')).toEqual([
+      { text: 'hello', tags: ['excited'] },
+    ]);
+  });
+
+  it('switches tags mid-string', () => {
+    const out = parseProsody('hello [whisper] there [excited] world');
+    expect(out).toEqual([
+      { text: 'hello', tags: [] },
+      { text: 'there', tags: ['whisper'] },
+      { text: 'world', tags: ['excited'] },
+    ]);
+  });
+
+  it('combines two tags inside one bracket group', () => {
+    const out = parseProsody('[fast excited] go');
+    expect(out).toEqual([{ text: 'go', tags: ['fast', 'excited'] }]);
+  });
+
+  it('drops unknown tags silently rather than throwing', () => {
+    const out = parseProsody('[totallybogustag] hi');
+    expect(out).toEqual([{ text: 'hi', tags: [] }]);
+  });
+});
+
+describe('stripProsody', () => {
+  it('passes plain text through unchanged', () => {
+    expect(stripProsody('hello world')).toBe('hello world');
+  });
+
+  it('removes a single tag', () => {
+    expect(stripProsody('[excited] go')).toBe('go');
+  });
+
+  it('removes multiple tags and collapses whitespace', () => {
+    expect(stripProsody('[whisper]  hello   [excited]  world')).toBe('hello world');
+  });
+
+  it('handles tag-only input', () => {
+    expect(stripProsody('[whisper]')).toBe('');
+  });
+
+  it('joins text directly adjacent to a tag (no whitespace inserted)', () => {
+    // The current implementation simply removes the tag and collapses
+    // whitespace. It does NOT insert a separator, so adjacent text fuses.
+    // Documented behavior — callers should put a space before the tag if they
+    // want word boundaries preserved.
+    expect(stripProsody('a[whisper]b')).toBe('ab');
+  });
+});

package/src/voices/catalog.ts

@@ -0,0 +1,32 @@
+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 const SUPERTONIC_VOICES: Voice[] = [
+  { 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: string): Voice | undefined {
+  return SUPERTONIC_VOICES.find((v) => v.id === id);
+}

package/src/voices/prosody.ts

@@ -0,0 +1,39 @@
+export type ProsodyTag = 'excited' | 'whisper' | 'calm' | 'sad' | 'angry' | 'fast' | 'slow';
+
+export interface ProsodySegment {
+  text: string;
+  tags: ProsodyTag[];
+}
+
+const TAG_RE = /\[([a-z_ ]+)\]/gi;
+
+export function parseProsody(input: string): ProsodySegment[] {
+  const segments: ProsodySegment[] = [];
+  let lastIndex = 0;
+  let activeTags: ProsodyTag[] = [];
+  let match: RegExpExecArray | null;
+
+  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): t is ProsodyTag =>
+        ['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: string): string {
+  return input.replace(TAG_RE, '').replace(/\s+/g, ' ').trim();
+}