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

## Установка

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu126
pip install -r requirements.txt
cp .env.example .env
# отредактировать .env под свой бэкенд
```

## Запуск: S2-Pro INT4 (рекомендуемый)

Требуется **PyTorch 2.4.0+cu121** (установлен). S2-сервер и WebSocket-прокси 
запускаются в разных терминалах:

```bash
# Терминал 1: S2 API сервер
cd models/fish-speech
PYTHONPATH=. /home/gmikcon/Projects/voice/.venv/bin/python tools/api_server.py \
  --llama-checkpoint-path checkpoints/fs-1.2-int4-g128-s2-pro-nf4 \
  --decoder-checkpoint-path checkpoints/s2-pro/codec.pth \
  --listen 127.0.0.1:8081 --compile
# Первый запуск ~3.5 мин (компиляция), потом ~50 tok/s, ~9.6 GB VRAM

# Терминал 2: WebSocket прокси
cd /home/gmikcon/Projects/voice
TTS_BACKEND=s2 python -m voice_tts.main
```

### S2 без компиляции (меньше VRAM, медленнее)

```bash
# Без --compile: ~6 tok/s
cd models/fish-speech && PYTHONPATH=. /home/gmikcon/Projects/voice/.venv/bin/python \
  tools/api_server.py \
  --llama-checkpoint-path checkpoints/fs-1.2-int4-g128-s2-pro-nf4 \
  --decoder-checkpoint-path checkpoints/s2-pro/codec.pth \
  --listen 127.0.0.1:8081
```

### Обновление чекпоинта S2

Если выходит новая версия S2-Pro:
1. Скачать новый чекпоинт с HuggingFace
2. Запустить квантизацию: `python tools/llama/quantize.py --checkpoint-path ... --mode int4 --groupsize 128`
3. Обновить `--llama-checkpoint-path` на новый квантизованный чекпоинт

## Запуск: Fish Speech 1.5

```bash
TTS_BACKEND=fish_speech \
DEFAULT_VOICE_REF=voices/default_ref.wav \
DEFAULT_REF_TEXT="текст референса" \
WARMUP=true \
python -m voice_tts.main
```

## Запуск: XTTS-v2

```bash
TTS_BACKEND=xtts_v2 \
DEFAULT_VOICE_REF=voices/default_ref.wav \
python -m voice_tts.main
```

Модель скачивается автоматически при первом запуске.

## Запуск: тестовый dummy

```bash
TTS_BACKEND=dummy python -m voice_tts.main
```

## Проверка

```bash
curl http://localhost:8765/health
# {"status":"ok","backend":"s2"}
```

## Клиенты

В `examples/`:
- `client_python.py` — Python-клиент с sounddevice
- `client_browser.html` — браузерный клиент

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

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

Поместите в `voices/`:
```
voices/
├── product_voice_sample_clean.wav
├── product_voice_sample_clean.lab  (точный транскрипт для Fish Speech)
└── ...
```

Требования:
- WAV, моно, 16+ кГц
- 5–15 секунд чистой речи одного спикера
- Для Fish Speech рядом с `.wav` можно положить `.lab` с транскриптом

## Тесты

```bash
pytest tests/ -v
```

## Добавление нового бэкенда

1. Создать файл `src/voice_tts/tts/my_model.py`
2. Унаследоваться от `TTSEngine`, добавить декоратор:

```python
from voice_tts.tts import register as _register_backend
from voice_tts.tts.engine import TTSEngine

@_register_backend("my_model")
class MyEngine(TTSEngine):
    def __init__(self):
        # читать настройки из voice_tts.config.settings

    async def synthesize(self, text, ref_audio_path, language, speed, emotion, ref_text=None):
        ...

    async def warm_up(self):
        ...
```

3. Готово — бэкенд доступен через `TTS_BACKEND=my_model`

## Переменные окружения

Полный список — в `.env.example`.