react-native-tts-kado

A high-performance Text-to-Speech library for React Native with full language, rate, volume, and pitch control on both Android and iOS.

✨ Features

• 🌍 12+ Languages — English, Vietnamese, Japanese, Korean, Chinese, French, German, Spanish, Portuguese, Italian, Russian, Thai
• ⚡ Speed Control — 0.5x to 2.0x with unified cross-platform scale
• 🔊 Volume & Pitch — Fine-grained audio control
• 🎯 Dual API — React Hook (useTextToSpeech) + Imperative (KadoTTS.speak())
• 📡 Events — start, finish, cancel, error, progress (word boundary)
• 🔌 Module Federation — Safe lazy-loading, no crash on import
• ♻️ Auto Cleanup — Stop-on-unmount, event auto-unsubscribe
• 📱 React Native 0.72+ — Supports New Architecture

📦 Installation

npm install react-native-tts-kado
# or
yarn add react-native-tts-kado

iOS

cd ios && pod install

Android

No additional setup needed. Rebuild the app:

npx react-native run-android

🚀 Quick Start

Hook API (Recommended)

import React, { useState } from 'react';
import { View, TextInput, Button } from 'react-native';
import { useTextToSpeech } from 'react-native-tts-kado';

function TTSDemo() {
  const [text, setText] = useState('Hello World');
  const { speak, stop, isSpeaking, isInitialized } = useTextToSpeech({
    language: 'en',
    rate: 1.0,
    volume: 1.0,
    onFinish: () => console.log('Done!'),
  });

  return (
    <View>
      <TextInput value={text} onChangeText={setText} />
      <Button
        title={isSpeaking ? '⏹ Stop' : '▶️ Speak'}
        onPress={() => (isSpeaking ? stop() : speak(text))}
        disabled={!isInitialized}
      />
    </View>
  );
}

Imperative API

import { KadoTTS } from 'react-native-tts-kado';

// Basic
await KadoTTS.speak('Hello World');

// With options
await KadoTTS.speak('Xin chào!', {
  language: 'vi',
  rate: 0.8,
  volume: 0.9,
  pitch: 1.1,
});

// Stop
await KadoTTS.stop();

// Events
const unsubscribe = KadoTTS.addEventListener('tts-finish', (event) => {
  console.log('Finished:', event.utteranceId);
});
unsubscribe(); // cleanup

🌍 Supported Languages

| Flag | Code | Language | |------|------|----------| | 🇺🇸 | en | English | | 🇻🇳 | vi | Tiếng Việt | | 🇯🇵 | ja | 日本語 | | 🇰🇷 | ko | 한국어 | | 🇨🇳 | zh | 中文 | | 🇫🇷 | fr | Français | | 🇩🇪 | de | Deutsch | | 🇪🇸 | es | Español | | 🇧🇷 | pt | Português | | 🇮🇹 | it | Italiano | | 🇷🇺 | ru | Русский | | 🇹🇭 | th | ภาษาไทย |

You can also use full BCP 47 tags (e.g., 'en-US', 'vi-VN').

⚙️ API Reference

useTextToSpeech(options?)

React Hook for declarative TTS control.

const { speak, stop, isSpeaking, isInitialized, error } = useTextToSpeech({
  language: 'en',     // Default language
  rate: 1.0,          // Speed: 0.5 (slow) → 2.0 (fast)
  volume: 1.0,        // Volume: 0.0 → 1.0
  pitch: 1.0,         // Pitch: 0.5 → 2.0
  stopOnUnmount: true, // Auto-stop on component unmount
  onStart: (event) => {},
  onFinish: (event) => {},
  onCancel: (event) => {},
  onError: (event) => {},
  onProgress: (event) => {},
});

Returns:

| Property | Type | Description | |----------|------|-------------| | speak | (text, overrides?) => Promise<string \| null> | Speak text with optional overrides | | stop | () => Promise<void> | Stop all speech | | isSpeaking | boolean | Whether currently speaking | | isInitialized | boolean | Whether TTS engine is ready | | error | string \| null | Last error message |

KadoTTS (Imperative API)

| Method | Description | |--------|-------------| | speak(text, options?) | Speak text, returns utterance ID | | stop() | Stop all speech | | setDefaultRate(rate) | Set default rate (0.0–2.0) | | setDefaultPitch(pitch) | Set default pitch (0.5–2.0) | | setDefaultVolume(volume) | Set default volume (0.0–1.0) | | getAvailableVoices() | List available voices | | isLanguageAvailable(lang) | Check language support | | addEventListener(type, fn) | Listen to events |

Events

| Event | Description | |-------|-------------| | tts-start | Speech started | | tts-finish | Speech completed | | tts-cancel | Speech cancelled | | tts-error | Error occurred | | tts-progress | Word boundary progress |

📋 Requirements

• React Native ≥ 0.72
• React ≥ 18
• iOS ≥ 15.1
• Android SDK ≥ 21

📄 License

MIT © ndd2509