> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/XDcobra/react-native-sherpa-onnx/llms.txt
> Use this file to discover all available pages before exploring further.

# Kokoro Models

> Multi-speaker, multi-language TTS models

# Kokoro Models

Kokoro is a **multi-speaker, multi-language** TTS model designed for flexible speech synthesis across different voices and languages.

## Model Architecture

Kokoro uses an end-to-end neural TTS architecture:

* **Model** (`model.onnx` or `kokoro-*.onnx`) – Neural TTS model
* **Tokens** (`tokens.txt`) – Text token vocabulary
* Optional configuration files

## When to Use

<CardGroup cols={2}>
  <Card title="Multi-Language Apps" icon="globe">
    Applications serving users in multiple languages
  </Card>

  <Card title="Multiple Voices" icon="users">
    Need for different speakers/voices in one model
  </Card>

  <Card title="Fast Streaming" icon="bolt">
    Real-time speech generation with low latency
  </Card>

  <Card title="Compact Deployment" icon="mobile">
    Single model for multiple languages and voices
  </Card>
</CardGroup>

## Supported Languages

Kokoro models support multiple languages including:

* English
* Spanish
* French
* German
* And potentially others (check specific model variant)

## Performance Characteristics

| Aspect         | Rating       | Notes                         |
| -------------- | ------------ | ----------------------------- |
| **Streaming**  | ✅ Excellent  | Native streaming support      |
| **Quality**    | ⭐⭐⭐⭐         | High quality, natural speech  |
| **Speed**      | ⭐⭐⭐⭐⭐        | Fast inference                |
| **Memory**     | ⭐⭐⭐⭐         | Moderate, suitable for mobile |
| **Model Size** | Small-Medium | Typically 20-60 MB            |

## Download Links

<Card title="Kokoro Models" icon="download" href="https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models">
  Download Kokoro TTS models
</Card>

## Configuration Example

### Basic TTS

```typescript theme={null}
import { createTTS } from 'react-native-sherpa-onnx/tts';

const tts = await createTTS({
  modelPath: {
    type: 'asset',
    path: 'models/kokoro-multi-language'
  },
  modelType: 'kokoro', // or 'auto'
  numThreads: 2,
});

const audio = await tts.generateSpeech('Hello, world!');
console.log('Generated:', audio.samples.length, 'samples');

await tts.destroy();
```

### With Length Scale

```typescript theme={null}
const tts = await createTTS({
  modelPath: { type: 'asset', path: 'models/kokoro' },
  modelType: 'kokoro',
  modelOptions: {
    kokoro: {
      lengthScale: 1.0,  // Speech speed (< 1.0 = faster, > 1.0 = slower)
    }
  },
});
```

### Streaming TTS

```typescript theme={null}
const tts = await createTTS({
  modelPath: { type: 'asset', path: 'models/kokoro' },
  modelType: 'kokoro',
});

const sampleRate = await tts.getSampleRate();
await tts.startPcmPlayer(sampleRate, 1);

await tts.generateSpeechStream('Streaming speech synthesis', { sid: 0, speed: 1.0 }, {
  onChunk: async (chunk) => {
    await tts.writePcmChunk(chunk.samples);
  },
  onEnd: async () => {
    await tts.stopPcmPlayer();
  },
});

await tts.destroy();
```

### Multi-Speaker Usage

```typescript theme={null}
const tts = await createTTS({
  modelPath: { type: 'asset', path: 'models/kokoro-multi-speaker' },
  modelType: 'kokoro',
});

const numSpeakers = await tts.getNumSpeakers();
console.log('Available speakers:', numSpeakers);

// Generate with different voices
for (let sid = 0; sid < numSpeakers; sid++) {
  const audio = await tts.generateSpeech(`Hello from speaker ${sid}`, { sid, speed: 1.0 });
  console.log(`Speaker ${sid}:`, audio.samples.length, 'samples');
}

await tts.destroy();
```

## Model Options

Kokoro models support one tuning parameter:

| Option        | Type     | Default | Description                                   |
| ------------- | -------- | ------- | --------------------------------------------- |
| `lengthScale` | `number` | 1.0     | Speech speed. \< 1.0 = faster, > 1.0 = slower |

### Tuning Examples

```typescript theme={null}
// Fast speech
const tts = await createTTS({
  modelPath: { type: 'asset', path: 'models/kokoro' },
  modelType: 'kokoro',
  modelOptions: {
    kokoro: { lengthScale: 0.8 }  // 20% faster
  },
});

// Slow, clear speech
const tts2 = await createTTS({
  modelPath: { type: 'asset', path: 'models/kokoro' },
  modelType: 'kokoro',
  modelOptions: {
    kokoro: { lengthScale: 1.3 }  // 30% slower
  },
});
```

### Runtime Updates

```typescript theme={null}
const tts = await createTTS({ ... });

await tts.updateParams({
  modelOptions: {
    kokoro: { lengthScale: 1.2 }
  },
});
```

## Model Detection

Kokoro models are detected by:

* Folder name should contain `kokoro` (not `kitten`)
* Files: `model.onnx` or `kokoro-*.onnx`, plus `tokens.txt`

Expected files:

* `model.onnx` (or variant)
* `tokens.txt`

## Performance Tips

### Optimize Thread Count

```typescript theme={null}
const tts = await createTTS({
  modelPath: { type: 'asset', path: 'models/kokoro' },
  numThreads: 4, // More threads for faster generation
});
```

### Use Streaming for Responsiveness

For interactive apps:

```typescript theme={null}
await tts.generateSpeechStream(text, { sid: 0, speed: 1.0 }, {
  onChunk: async (chunk) => {
    await tts.writePcmChunk(chunk.samples); // Start playing immediately
  },
});
```

### Hardware Acceleration

```typescript theme={null}
const tts = await createTTS({
  modelPath: { type: 'asset', path: 'models/kokoro' },
  provider: 'nnapi', // Android NNAPI
  // provider: 'xnnpack', // XNNPACK
});
```

## Streaming Support

<Note>
  **Streaming**: ✅ Yes

  Kokoro models have excellent streaming support. Use `generateSpeechStream()` for low-latency, incremental audio generation.
</Note>

## Advantages

1. **Multi-Language**: Single model for multiple languages
2. **Multi-Speaker**: Multiple voices in one model
3. **Fast Inference**: Real-time capable
4. **Streaming**: Native incremental generation
5. **Compact**: One model instead of multiple language-specific models
6. **Good Quality**: Natural-sounding speech

## Limitations

1. **No Voice Cloning**: Cannot synthesize custom voices from reference audio
2. **Fixed Voices**: Limited to model's trained speakers
3. **Less Tuning**: Only `lengthScale` parameter available (no noise scale)
4. **Language Coverage**: Fewer languages than some alternatives

## Use Cases

<CardGroup cols={2}>
  <Card title="Multilingual Apps" icon="globe">
    Apps serving users in multiple countries
  </Card>

  <Card title="Voice Assistants" icon="robot">
    Interactive voice interfaces with multiple voices
  </Card>

  <Card title="E-Learning" icon="graduation-cap">
    Educational content in multiple languages
  </Card>

  <Card title="Customer Service" icon="headset">
    Automated responses in different languages
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Model not loading">
    * Verify folder name contains `kokoro` (not `kitten`)
    * Check that `model.onnx` and `tokens.txt` are present
    * Ensure sufficient device memory
  </Accordion>

  <Accordion title="Incorrect language output">
    * Kokoro may auto-detect language from text
    * Ensure input text is in the correct language/script
    * Some models may require language-specific prefixes
  </Accordion>

  <Accordion title="Slow generation">
    * Increase `numThreads` on multi-core devices
    * Use hardware acceleration (`provider: 'nnapi'`)
    * Ensure no other heavy apps are running
  </Accordion>
</AccordionGroup>

## Comparison with Other Models

| Feature            | Kokoro       | VITS      | Matcha    | KittenTTS |
| ------------------ | ------------ | --------- | --------- | --------- |
| **Speed**          | Fast         | Very Fast | Fast      | Very Fast |
| **Quality**        | High         | High      | Very High | Good      |
| **Streaming**      | Yes          | Yes       | Yes       | Yes       |
| **Multi-Language** | Yes          | Varies    | Limited   | Limited   |
| **Multi-Speaker**  | Yes          | Yes       | Yes       | Yes       |
| **Voice Cloning**  | No           | No        | No        | No        |
| **Model Size**     | Small-Medium | Small     | Medium    | Small     |

## Next Steps

<CardGroup cols={2}>
  <Card title="TTS API" icon="code" href="/api/tts">
    Detailed API documentation
  </Card>

  <Card title="Streaming TTS" icon="waveform" href="/api/streaming-tts">
    Low-latency streaming guide
  </Card>

  <Card title="Model Setup" icon="download" href="/features/model-setup">
    How to download and bundle models
  </Card>

  <Card title="Execution Providers" icon="microchip" href="/features/execution-providers">
    Hardware acceleration options
  </Card>
</CardGroup>