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

Установка

Рекомендуется Python 3.11. Python 3.14+ пока не имеет совместимых wheel для torch, поэтому используйте 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

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

# Основной режим: Fish Speech 1.5 на GPU (по умолчанию)
python -m voice_tts.main

# С настроенным референсом и warm-up (рекомендуется)
TTS_BACKEND=fish_speech \
DEFAULT_VOICE_REF=voices/self_ref_clean.wav \
DEFAULT_REF_TEXT="Добрый вечер, меня зовут Евгений." \
WARMUP=true \
python -m voice_tts.main

# Быстрый вариант XTTS-v2
TTS_BACKEND=xtts_v2 \
DEFAULT_VOICE_REF=voices/self_ref_clean.wav \
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":"fish_speech"}

Клиенты

В директории 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/self_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 и выходит.

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

# 1. Терминал 1: запустить TTS сервер (dummy — без GPU, любой бэкенд по выбору)
TTS_BACKEND=dummy python -m voice_tts.main

# 2. Терминал 2: открыть клиент через HTTP (file:// не даёт WebSocket в некоторых браузерах)
python -m http.server 8080 --directory examples/
# Открыть http://localhost:8080/client_browser.html

Нажмите Connect, затем Speak streaming. Клиент:

1. Шлёт init с настройками (язык, скорость, эмоция).
2. Шлёт слова по одному как потоковые text с задержкой 120 мс.
3. Завершает flush.
4. Получает audio-чанки с динамическим sample_rate (поддерживается любой бэкенд).
5. Декодирует PCM16 из base64 и ставит в очередь AudioBuffer для бесшовного воспроизведения.

Кнопка Stop отправляет stop. Кнопка Test audio проверяет звук в браузере независимо от сервера.

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

Модели

Fish Speech 1.5

По умолчанию используется локальный checkpoint models/fishaudio_fish-speech-1.5/:

• model.pth — LLaMA языковая модель,
• firefly-gan-vq-fsq-8x1024-21hz-generator.pth — VQ-GAN декодер,
• tokenizer.tiktoken, config.json, special_tokens.json.

Исходный код Fish Speech v1.5.1 должен лежать в models/fish-speech-v1.5.1/, чтобы Python мог импортировать нужные модули.

XTTS-v2

Coqui-модель tts_models/multilingual/multi-dataset/xtts_v2 скачивается автоматически при первом запуске TTS_BACKEND=xtts_v2. Можно указать локальный путь через TTS_MODEL_PATH.

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

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

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

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

• WAV или другой формат, читаемый torchaudio.
• Моно, 16+ кГц.
• Длина 5–15 секунд для Fish Speech, 3–10 секунд для XTTS-v2.
• Чистая речь одного спикера без фонового шума.
• Для Fish Speech рядом с .wav можно положить .lab с точным транскриптом. Иначе сервер использует DEFAULT_REF_TEXT или Whisper-транскрипцию.

Тесты

# Быстрые тесты без загрузки тяжёлых моделей
python -m pytest tests/ -v

Для запуска в CI рекомендуется отдельно прогонять быстрые и тяжёлые тесты:

python -m pytest tests/test_segmenter.py tests/test_server.py -v
python -m pytest tests/test_fish_speech_backend.py -v