# Kokoro TTS

Kokoro — это модель синтеза речи из текста с 82 миллионами параметров, которая значительно превосходит ожидания для своего класса. Несмотря на небольшой размер (меньше 2 ГБ видеопамяти), она воспроизводит удивительно естественную английскую речь и работает в реальном времени или быстрее даже на бюджетном оборудовании. С лицензией Apache 2.0, несколькими встроенными стилями голоса и поддержкой вывода на CPU, Kokoro идеально подходит для приложений в реальном времени, чат-ботов и развёртываний на периферии.

**HuggingFace:** [hexgrad/Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) **PyPI:** [kokoro](https://pypi.org/project/kokoro/) **Лицензия:** Apache 2.0

## Ключевые особенности

* **82M параметров** — одна из самых маленьких высококачественных моделей TTS
* **< 2 ГБ VRAM** — работает практически на любой GPU и даже на CPU
* **Несколько стилей голоса** — американский английский, британский английский; мужские и женские голоса
* **В реальном времени или быстрее** — низкая задержка вывода, подходящая для стриминга
* **Потоковая генерация** — выдаёт аудиочанки по мере их генерации
* **Поддержку нескольких языков** — английский (основной), японский (`misaki[ja]`), китайский (`misaki[zh]`)
* **Apache 2.0** — бесплатно для личного и коммерческого использования

## Требования

| Компонент | Минимум              | Рекомендуется |
| --------- | -------------------- | ------------- |
| GPU       | Любая с 2 ГБ VRAM    | RTX 3060      |
| VRAM      | 2 GB                 | 4 ГБ          |
| ОЗУ       | 4 ГБ                 | 8 ГБ          |
| Диск      | 500 МБ               | 1 ГБ          |
| Python    | 3.9+                 | 3.11          |
| Система   | espeak-ng установлен | —             |

**Рекомендация Clore.ai:** RTX 3060 (\~$0.15–0.30/день) более чем достаточна. Kokoro может даже запускаться на экземплярах только с CPU, обеспечивая чрезвычайно выгодный по стоимости TTS.

## Установка

```bash
# Установите системную зависимость
apt-get install -y espeak-ng

# Установите Kokoro и аудио I/O
pip install kokoro>=0.9.4 soundfile torch

# Для поддержки японского (необязательно)
pip install misaki[ja]

# Для поддержки китайского (необязательно)
pip install misaki[zh]

# Проверка
python -c "from kokoro import KPipeline; print('Kokoro ready')"
```

## Быстрый старт

```python
from kokoro import KPipeline
import soundfile as sf

# Инициализация конвейера
# 'a' = американский английский, 'b' = британский английский
pipeline = KPipeline(lang_code='a')

text = """
Kokoro — это лёгкая модель синтеза речи из текста с всего лишь восемьюдесятью двумя миллионами
параметров. Несмотря на свой небольшой размер, она создаёт естественную и выразительную речь.
"""

# Генерация аудио — варианты голосов: af_heart, af_bella, af_nicole, af_sarah, af_sky,
#                                  am_adam, am_michael, bf_emma, bf_isabella, bm_george, bm_lewis
generator = pipeline(text, voice='af_heart', speed=1.0)

for i, (graphemes, phonemes, audio) in enumerate(generator):
    sf.write(f'output_{i}.wav', audio, 24000)
    print(f"Chunk {i}: {graphemes[:50]}...")

print("Готово!")
```

## Примеры использования

### Сравнение нескольких голосов

Сгенерируйте один и тот же текст разными голосами для сравнения:

```python
from kokoro import KPipeline
import soundfile as sf

pipeline = KPipeline(lang_code='a')

text = "Welcome to Clore.ai, the peer-to-peer GPU marketplace."

voices = ['af_heart', 'af_bella', 'am_adam', 'am_michael']

for voice in voices:
    generator = pipeline(text, voice=voice, speed=1.0)
    for i, (gs, ps, audio) in enumerate(generator):
        sf.write(f'{voice}_{i}.wav', audio, 24000)
    print(f"Generated: {voice}")
```

### Британский английский с управлением скоростью

```python
from kokoro import KPipeline
import soundfile as sf

# 'b' = британский английский
pipeline = KPipeline(lang_code='b')

text = "Good afternoon. This is a demonstration of British English synthesis."

# speed < 1.0 = медленнее, speed > 1.0 = быстрее
generator = pipeline(text, voice='bf_emma', speed=0.85)

all_audio = []
for gs, ps, audio in generator:
    all_audio.append(audio)

import numpy as np
combined = np.concatenate(all_audio)
sf.write('british_slow.wav', combined, 24000)
print(f"Total duration: {len(combined)/24000:.1f}s")
```

### Пакетная обработка файлов

Обрабатывайте несколько текстов и объединяйте в единый файл в стиле аудиокниги:

```python
from kokoro import KPipeline
import soundfile as sf
import numpy as np

pipeline = KPipeline(lang_code='a')

chapters = [
    "Глава первая. Начало нашего пути начинается здесь.",
    "Солнце взошло над горами, отбрасывая длинные тени по долине.",
    "Она открыла дверь и шагнула в неизвестность.",
]

all_audio = []
silence = np.zeros(int(24000 * 0.5))  # 0.5 с тишины между главами

for idx, text in enumerate(chapters):
    for gs, ps, audio in pipeline(text, voice='af_bella', speed=1.0):
        all_audio.append(audio)
    all_audio.append(silence)
    print(f"Chapter {idx+1} done")

combined = np.concatenate(all_audio)
sf.write('audiobook.wav', combined, 24000)
print(f"Total: {len(combined)/24000:.1f}s")
```

## Советы для пользователей Clore.ai

* **Вывод на CPU** — Kokoro достаточно мала, чтобы работать на CPU; полезно для задач с ограниченным бюджетом или когда GPU недоступны
* **Потоковая передача (Streaming)** — генератор выдаёт аудиочанки по мере их создания, что позволяет воспроизводить в реальном времени в веб-приложениях
* **Комбинирование с WhisperX** — используйте WhisperX для транскрипции и Kokoro для повторного синтеза в голосовых конвейерах
* **Docker** — используйте `pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime` и добавьте `apt-get install -y espeak-ng` в ваш автозапуск
* **Согласованность голоса** — придерживайтесь одного идентификатора голоса на проект для консистентного восприятия рассказчика
* **Экономичность** — при $0.15/день на RTX 3060 Kokoro — одно из самых дешёвых решений TTS для самостоятельного хостинга

## Устранение неполадок

| Проблема                       | Решение                                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| `espeak-ng не найден`          | Запустите `apt-get install -y espeak-ng` (требуемая системная зависимость)                  |
| `ModuleNotFoundError: kokoro`  | Установите с помощью `pip install kokoro>=0.9.4 soundfile`                                  |
| Аудио звучит роботизированно   | Попробуйте другой голос (например, `af_heart` обычно звучит наиболее естественно)           |
| Японский/китайский не работают | Установите языковые дополнения: `pip install misaki[ja]` или `misaki[zh]`                   |
| Недостаточно памяти на CPU     | Уменьшите длину текста за вызов; Kokoro стримит чанки, поэтому память остаётся ограниченной |
| Медленный первый запуск        | Загрузка весов модели при первом использовании (\~200 МБ); последующие запуски мгновенные   |