# Обзор проекта Voice TTS

## Цель

Построить локальный GPU-пайплайн преобразования текста в речь (TTS) с интонацией, управляемый через WebSocket API. Система предназначена для озвучки ИИ-агента: текст поступает от LLM кусками в процессе генерации, а аудио отдаётся клиенту в реальном времени.

## Ключевые требования

- **Локальная работа на GPU**: весь инференс выполняется на видеокарте пользователя (RTX 3090 сейчас, RTX 3060 в перспективе).
- **Стриминг текста**: фразы от LLM приходят частями, сервер не ждёт полного текста.
- **Стриминг аудио**: синтезированные фрагменты отправляются клиенту сразу после готовности.
- **Клонирование голоса**: один спикер, задаваемый референсным аудио.
- **Эмоции**: возможность переключать эмоцию агента по сигналу от ИИ.
- **Прерывание**: агент может немедленно остановить текущее вещание, если его перебили.
- **Мультиязычность**: приоритет — русский; поддерживаются также английский, украинский, испанский, немецкий, французский.
- **Клиент**: Python-агент, сам управляющий дальнейшей маршрутизацией аудиопотока.

## Решения, принятые на этапе планирования

### Стек

| Компонент | Выбор |
|-----------|-------|
| Язык | Python |
| WebSocket сервер | FastAPI + `uvicorn[standard]` |
| TTS | F5-TTS (основной), с возможным fallback на MeloTTS |
| Аудио | torchaudio, numpy |
| Конфиг | pydantic-settings |
| Логи | loguru |

### Почему F5-TTS

- Высокое качество и естественная интонация.
- Быстрый инференс, подходит для реалтайма.
- Поддержка клонирования голоса по референсу (zero-shot).
- Мультиязычность из коробки (en, ru, zh), с потенциалом для европейских языков.
- Помещается в VRAM RTX 3060 (12 GB).

### Формат аудио

- **PCM 16-bit mono, 24 kHz**, упакованный в base64.
- Низкая задержка, простая декодировка на клиенте.
- Opus-энкодинг можно добавить позже как опцию.

## Архитектура (верхний уровень)

```
[Python AI Agent]
       |
       | text chunks over WebSocket
       v
[FastAPI WebSocket Server]
       |
       | buffered text
       v
[Text Segmenter]
       |
       | TTS-ready segments
       v
[TTS Queue]
       |
       v
[GPU TTS Worker]  <-- F5-TTS
       |
       | audio ndarray
       v
[Audio Output Queue]
       |
       | base64 PCM chunks
       v
[Python AI Agent -> audio player / sink]
```

## Состояние репозитория

- Реализован серверный каркас с WebSocket API, сегментатором, сессией и управлением прерыванием.
- Подключён **F5-TTS** как основной бэкенд: модель скачивается в `models/`, загружается на GPU и готова к инференсу.
- **Dummy TTS** остаётся для тестов (`TTS_BACKEND=dummy`).
- Следующий этап — подготовка референсных аудио, тёплый старт и замеры реальной латентности.