Использование и развёртывание

Установка

Рекомендуется Python 3.11. Python 3.14+ пока не имеет совместимых wheel для torch / f5-tts, поэтому используйте 3.10–3.12.

# Клонировать / перейти в директорию проекта
cd voice

# Создать виртуальное окружение
python3.11 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Установить PyTorch с CUDA 12.6 (обязательно первым)
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu126

# Установить остальные зависимости
pip install -r requirements.txt

# (Опционально) скопировать настройки
cp .env.example .env

Запуск сервера

# Основной режим: F5-TTS на GPU
python -m voice_tts.main

# С настроенным референсом и warm-up (рекомендуется)
TTS_BACKEND=f5_tts \
DEFAULT_VOICE_REF=voices/rick_ref_clean.wav \
DEFAULT_REF_TEXT="Ва-ба-ла-ба-дап-дап! Рикки-тики-тави, сученька! И вот такие у нас новости! Иди." \
WARMUP=true \
python -m voice_tts.main

# Тестовый режим без модели
TTS_BACKEND=dummy python -m voice_tts.main

Сервер поднимется на ws://localhost:8765/ws.

Проверка работоспособности

curl http://localhost:8765/health
# {"status":"ok","backend":"f5_tts"}

Клиенты

В директории examples/ лежат готовые клиенты:

• examples/client_python.py — Python-клиент с воспроизведением через sounddevice.
• examples/client_browser.html — HTML/JS клиент для браузера с AudioContext.

Python-клиент

pip install websockets sounddevice
python examples/client_python.py --uri ws://localhost:8765/ws "Привет, мир!"

Опции:

python examples/client_python.py \
  --uri ws://localhost:8765/ws \
  --voice-ref voices/rick_ref_clean.wav \
  --language ru \
  --speed 1.0 \
  "Это тестовая фраза для проверки."

Клиент:

1. Отправляет init с настройками.
2. Разбивает текст на слова и шлёт их как потоковые text.
3. Отправляет flush.
4. Получает audio-чанки, декодирует base64 PCM16 и складывает в аудиобуфер.
5. sounddevice воспроизводит аудио в реальном времени из callback.
6. По Ctrl+C отправляет stop и выходит.

Браузерный клиент

Откройте examples/client_browser.html в браузере, укажите URI сервера и нажмите Connect, затем Speak streaming. Браузер создаст AudioContext на 24 кГц, декодирует PCM16 из base64 и ставит буферы в очередь для бесшовного воспроизведения. Кнопка Stop отправляет stop на сервер.

Настройка через переменные окружения (.env)

Загрузка модели

Если TTS_BACKEND=f5_tts (по умолчанию), при первом старте сервер автоматически скачает нужный checkpoint из Hugging Face в кэш. Чтобы скачать модель заранее:

python scripts/download_f5_tts.py --model F5TTS_v1_Base

Поддерживаемые варианты: F5TTS_v1_Base, F5TTS_Base, E2TTS_Base. Модель сохраняется в models/F5TTS_v1_Base/.

Тесты

# Быстрые тесты без загрузки F5-TTS
TTS_BACKEND=dummy python -m pytest tests/ -v

Референсные аудио

Поместите файлы в директорию voices/:

voices/
├── default_neutral.wav
├── default_happy.wav
├── default_sad.wav
└── ...

Требования к референсу:

• WAV или другой формат, читаемый torchaudio.
• Моно, 16+ кГц.
• Длина 3–10 секунд (для F5-TTS).
• Чистая речь одного спикера без фонового шума.
• Для мгновенного старта задайте точный DEFAULT_REF_TEXT — иначе сервер будет транскрибировать референс через Whisper при первом запуске (5–6 с).