remotion_service/docs/consults/video-features-roadmap_v2_ru.md

# Дорожная карта видеофич — Техническая консультация v2 (API-First)

**Дата:** 22 марта 2026
**Консультанты:** ML/AI-инженер, Backend-архитектор, Remotion-инженер, Frontend-архитектор, DevOps-инженер, Инженер по производительности
**Ревизия:** v2 — переход на API-first архитектуру: Deepgram, GigaChat, DeepInfra

---

## Что изменилось по сравнению с v1

Одно принципиальное решение перевернуло всю архитектуру: вместо локальных ML-моделей — управляемые API-сервисы. PyTorch, GPU-инфраструктура, разделение ML-воркеров, большинство проблем с памятью и временем обработки — всё это просто исчезло.

### Замены API

| v1 (локальный ML) | v2 (API-First) | Эффект |
|---|---|---|
| Локальный Whisper (PyTorch, 20-60 мин на CPU) | **Deepgram Nova-3** API (~30 сек) | PyTorch больше не нужен вообще |
| Локальный pyannote.audio (PyTorch, 15-30 мин CPU) | **Deepgram** `diarize=true` (включено в вызов транскрипции) | pyannote + torchaudio — удалены |
| Gemini 2.5 Flash / GPT-4o-mini для вирусной детекции | **GigaChat Pro** (нативная русскоязычная LLM от Сбера) | Лучше понимает русский юмор, культурный контекст, сленг |
| librosa для анализа энергии аудио | **Deepgram** `sentiment=true` (посегментно) | Сентимент заменяет анализ энергии в большинстве сценариев |
| Нет | **DeepInfra** (Llama, Mistral, Qwen через API) | Фоллбэк / A/B-тестирование LLM-анализа |

### Как изменились ключевые метрики

Цифры говорят сами за себя:

| Метрика | v1 | v2 | Изменение |
|---|---|---|---|
| Размер Docker-образа | 1.72 ГБ | **~400-500 МБ** | -75% (нет PyTorch) |
| Пиковое потребление RAM воркера | 8-16 ГБ | **~400 МБ** (только MediaPipe) | -95% |
| Время обработки (30-мин видео, полный пайплайн) | 35-80 мин (CPU) | **5-10 мин** | -85% |
| Стоимость за видео | $0.11 | **$0.20** | +80% (стоимость API) |
| Месячная стоимость (100 видео) | $11 вычисления + сервер + $0-380 GPU | **$20 API + сервер** | Проще, дешевле при малых объёмах |
| Нужен GPU? | Фаза 2 для диаризации | **Никогда** | Полностью исключён |
| Новые Python-зависимости | ~310-340 МБ | **~40 МБ** (mediapipe + HTTP-клиенты) | -88% |
| Общий срок всех MVP | 26-34 dev-дня | **20-27 dev-дней** | -20-25% |

Образ в четыре раза легче. RAM в сорок раз меньше. Обработка в шесть-восемь раз быстрее. Цена за единицу чуть выше, но инфраструктурные расходы сжимаются до нуля. Неплохой обмен.

### Проблемы, которых больше нет

Эти сквозные проблемы из v1 перестали существовать:

| Проблема из v1 | Почему исчезла |
|---|---|
| ~~Переключить PyTorch на CPU-only индекс~~ | PyTorch удалён полностью (Whisper заменён Deepgram) |
| ~~OOM воркера на параллельных ML-джобах~~ | Нет тяжёлого ML — стандартный воркер на 4 ГБ |
| ~~Отдельный Docker-образ для ML-воркера~~ | Один лёгкий образ |
| ~~Планирование GPU-инфраструктуры~~ | Весь ML — через API |
| ~~Конфликты версий PyTorch~~ | Нет PyTorch |
| ~~Скачивание моделей при первом запуске~~ | Нет локальных моделей (кроме MediaPipe, ~2 МБ) |
| ~~Разделение ML через Docker Compose profiles~~ | Не нужно |

### Новые проблемы

Ничего бесплатного не бывает. Вот что появилось взамен:

| Проблема | Приоритет | Митигация |
|---|---|---|
| Управление API-ключами (Deepgram, GigaChat, DeepInfra) | Высокий | Хранить в settings через env-переменные, никогда в коде |
| Rate limit'ы API | Высокий | Retry с exponential backoff в акторах |
| Зависимость от вендора (vendor lock-in) | Средний | Абстрагировать за интерфейсами движков (как уже сделано: `engine: "whisper" \| "google"`) |
| Зависимость от сети (API упал = обработка встала) | Средний | Оставить Whisper как опциональный фоллбэк-движок |
| Более высокая стоимость за видео ($0.20 vs $0.11) | Низкий | Компенсируется нулевыми инфраструктурными расходами; прибыльно на любом SaaS-тарифе |

---

## Общая картина

| # | Фича | Сложность | MVP | Полная версия | Доп. инфраструктура |
|---|-------|-----------|-----|---------------|---------------------|
| 1 | Продвинутые шаблоны Remotion | Легко-средне | 3-4 дня | 3-4 дня | Ничего — можно начинать хоть сейчас |
| 2 | Детекция вирусных моментов | Средне | **3-5 дней** | 6-10 дней | API-ключи (GigaChat, Deepgram) |
| 3 | Авто-монтаж и трекинг лица | Сложно | **8-10 дней** | 20-30 дней | Только MediaPipe (CPU, ~30 МБ) |
| 4 | Конвертация в вертикальные Shorts (9:16) | Средне | 6-8 дней | +3-4 дня после #3 | Ничего |
| **Итого** | | | **20-27 дней** | **35-47 дней** | |

Реалистичный прогноз для одного разработчика: **5-7 недель** (все MVP) или **2-3 месяца** (полные версии).

---

## Фича 1: Продвинутые шаблоны Remotion

**Без изменений по сравнению с v1.** Эта фича не зависит от ML.

**Статус:** Спецификация и план реализации уже написаны. Бери и делай.

- Спецификация: `docs/superpowers/specs/2026-03-21-advanced-remotion-templates-design.md`
- План: `docs/superpowers/plans/2026-03-21-advanced-remotion-templates.md`

**Что делаем:** Расширяем `CaptionStyleSchema` четырьмя новыми стилями подсветки (pop_in, karaoke, bounce, glow_pulse), двумя переходами (zoom_in, drop_in), тремя полями (word_entrance, highlight_rotation_deg, text_transform). Два системных пресета: "Shorts" и "Podcast".

**Где трогаем код:** Расширение схемы в Remotion + бэкенде, логика рендеринга в `Captions.tsx`, Alembic-миграция для пресетов, контролы в StyleEditor на фронте.

---

## Фича 2: Детекция вирусных моментов

### Архитектура (v2 — API-First)

В v1 мы планировали гонять LLM по тексту и считать энергию аудио через librosa. В v2 подход элегантнее: один вызов Deepgram даёт транскрипцию, разметку спикеров и сентимент-анализ — три результата за одну цену. А текст анализирует GigaChat, которому русский язык родной.

**Транскрипция:** Deepgram Nova-3 API с `diarize=true` + `sentiment=true`. Один API-вызов возвращает пословные таймстемпы, метки спикеров и оценку сентимента по каждому высказыванию. Стоимость: $0.0053/мин ($0.16 за 30-минутное видео). Обработка: ~30 секунд.

**LLM-анализ:** GigaChat Pro (от Сбера) — нативная русскоязычная LLM, обученная на русском интернете. Лучше ловит русский юмор, культурные отсылки, сленг и вирусные паттерны, чем модели, для которых русский — второй язык. Фоллбэк: DeepInfra (Llama 3.1 70B или Qwen) для A/B-тестирования.

**Аудио-подкрепление:** Посегментные оценки сентимента от Deepgram заменяют анализ энергии через `librosa` в большинстве случаев. Высокий сентимент коррелирует с вирусными моментами. Опционально: librosa для анализа громкости (смех, повышенный голос) как дополнение.

**Пайплайн:**
1. Транскрипция Deepgram с `diarize=true` + `sentiment=true` -> таймстемпы + спикеры + сентимент
2. Конвертация ответа Deepgram в существующую схему `Document` (segments, lines, words)
3. GigaChat анализирует текст транскрипции + данные сентимента -> кандидаты в вирусные клипы
4. Постобработка: привязка границ к краям сегментов, вычисление композитных скоров
5. Сохранение клипов в таблицу `clips`

### Бэкенд

**Новый модуль:** `clips` (models, schemas, repository, service, router) — хранит найденные клипы со связями project/file/job.

**Модель клипа:**
```
Clip {
  project_id: UUID (FK projects)
  source_file_id: UUID (FK files)
  job_id: UUID? (FK jobs)
  title: str
  start_ms: int
  end_ms: int
  score: float
  source_type: "viral_detected" | "user_created" | "auto_generated"
  status: "pending" | "approved" | "rejected" | "exported"
  meta: JSON? (рассуждения LLM, теги, хэштеги, данные сентимента)
}
```

**Новый тип джоба:** `VIRAL_DETECT` в `JobTypeEnum`. Актор вызывает GigaChat API через `httpx` из Dramatiq-воркера.

**Расширение движков транскрипции:** Добавляем `"deepgram"` к существующему выбору (`engine: "whisper" | "google" | "deepgram"`). Deepgram становится дефолтом для новых транскрипций. Whisper остаётся как фоллбэк.

**Интеграция с LLM:**
- GigaChat API через `httpx` (OAuth2 token auth через Sber ID)
- DeepInfra как фоллбэк (OpenAI-совместимый API)
- Промпты хранятся в `cpv3/infrastructure/prompts/viral_detection_v1.txt`
- Активная версия контролируется через `LLM_VIRAL_PROMPT_VERSION`
- Новые настройки: `GIGACHAT_CLIENT_ID`, `GIGACHAT_CLIENT_SECRET`, `DEEPINFRA_API_KEY`, `DEEPGRAM_API_KEY`

### Фронтенд

- Новый `ViralClipsStep` в визарде проекта (features/project/)
- Список клипов с превьюшками, скорами, заголовками, кнопками принять/отклонить
- Модалка редактирования клипа с видео-превью (воспроизведение в диапазоне start/end)
- Новый тип джоба `VIRAL_DETECT` в обработке нотификаций (через существующую WebSocket-инфраструктуру)

### Ключевые цифры

| Метрика | v1 | v2 |
|---|---|---|
| Время транскрипции | Зависит от Whisper (уже готово) | ~30 сек (Deepgram, если ещё не транскрибировано) |
| Время LLM-анализа | 10-20 сек | 10-20 сек (без изменений) |
| Общее время обработки | 10-20 сек (после транскрипции) | **40-50 сек** (включая транскрипцию Deepgram) |
| Стоимость за видео | ~$0.005 (только LLM) | **~$0.17** ($0.16 Deepgram + $0.01 GigaChat) |
| Точность (precision) | 50-70% | **60-80%** (GigaChat лучше на русском + данные сентимента) |
| Новые зависимости | `google-generativeai` + `librosa` (~30 МБ) | **Только HTTP-клиент** (~0 МБ нового) |
| Срок MVP | 5-7 дней | **3-5 дней** |

Стоимость за видео выросла с полкопейки до семнадцати центов — но зато ноль зависимостей, ноль локальных моделей и на два дня быстрее в разработке.

### Риски

- **Доступность GigaChat API** — у Сбера uptime может быть ниже, чем у Google/OpenAI. Митигация: фоллбэк на DeepInfra.
- **Structured output GigaChat** — проверить, что JSON mode / function calling работает стабильно для извлечения клипов. Тестировать рано.
- **WER Deepgram на русском** — ~10-12% WER (Nova-3). Сопоставимо с Whisper `medium`. Достаточно для вирусной детекции.
- **Визуальные моменты** по-прежнему не ловятся (~20-30%) — то же ограничение, что и в v1.

### MVP vs Полная версия

- **MVP (3-5 дней):** Транскрипция Deepgram + анализ GigaChat. Возвращает клипы со скорами. Пользователь ревьюит и принимает/отклоняет. Без анализа энергии аудио.
- **Полная (6-10 дней):** Добавляем скоринг с весами сентимента, few-shot тюнинг промпта по фидбеку пользователей, пакетную обработку, прямой экспорт клипов в 9:16, A/B-тестирование через DeepInfra.

---

## Фича 3: Авто-монтаж и трекинг лица

В v1 эта фича была монстром: pyannote на CPU 30 минут жуёт аудио, PyTorch конфликтует с Whisper, GPU-воркеры, 16 ГБ RAM. В v2 всё, что касалось диаризации, ушло в один API-вызов Deepgram. Осталась только детекция лиц через MediaPipe — лёгкая библиотека, работающая на CPU за минуту-две.

### Архитектура (v2 — API-First)

**Детекция лиц:** MediaPipe BlazeFace (без изменений). Apache 2.0, модель ~2МБ, 30-60 FPS на CPU. Сэмплируем на 3 FPS. **Это единственный оставшийся локальный ML-компонент.** Зависимость: `mediapipe` (~30МБ).

**Диаризация спикеров:** **Deepgram API** с `diarize=true` (~30 секунд на 30-минутное видео). Полностью заменяет pyannote.audio. Диаризация включена в вызов транскрипции — никаких дополнительных расходов на API.

**Маппинг лицо-спикер:**
- **Фаза 1:** Эвристика по временнОй корреляции — сопоставляем треки лиц с сегментами спикеров Deepgram по максимальному пересечению во времени. 70-85% точности для видео с двумя спикерами. Ноль дополнительных зависимостей. ~100 строк Python.
- **Фаза 2:** TalkNet-ASD — если понадобится повысить точность. Единственный сценарий, где GPU мог бы вернуться в повестку, но можно откладывать бесконечно, если временная корреляция + ручная коррекция пользователем достаточны.

**Видео-композитинг:** Как в v1 — Remotion-композиции с CSS transform crop. Без изменений.

**Новые Remotion-композиции:** Как в v1.

| Композиция | Назначение | Фаза |
|---|---|---|
| `CaptionedVideo` (существует) | Наложение субтитров на нативное видео | Текущая |
| `ShortsVideo` (новая) | Статический/ключевой кроп + субтитры в 9:16 | Фича 4 |
| `AutoEditVideo` (новая) | Кроп с трекингом лица + монтаж + субтитры | Фича 3 (полная) |

**Формат данных кропа:** Как в v1 (ключевые кадры с нормализованными координатами 0-1).

### Бэкенд

**Новые типы джобов:** `FACE_DETECT` в `JobTypeEnum`. `SPEAKER_DIARIZE` **больше не нужен как отдельный джоб** — диаризация приходит от Deepgram в составе транскрипции.

**Отделение ML-сервиса:** **Не требуется.** MediaPipe лёгкая (~30МБ, ~400МБ RAM). Работает в стандартном Dramatiq-воркере.

**Изменения в Remotion-сервисе:** Как в v1 — параметр `compositionId`, пропсы `crop`/`outputWidth`/`outputHeight`.

### Время обработки (30-минутное 1080p видео)

Вот где разница между v1 и v2 ощущается физически:

| Шаг | v1 (CPU) | v2 (API-First) |
|---|---|---|
| Транскрипция + диаризация Deepgram | Нет | **~30 сек** |
| Детекция лиц (MediaPipe, 3 FPS) | 1-2 мин | 1-2 мин (без изменений) |
| ~~Диаризация спикеров (pyannote)~~ | ~~15-30 мин~~ | **Включено в Deepgram** |
| Маппинг лицо-спикер | < 1 сек | < 1 сек |
| Рендер Remotion (кроп + субтитры) | 10-30 мин | 10-30 мин (без изменений) |
| **Итого (с параллелизацией)** | **35-80 мин** | **12-33 мин** |

**Бутылочное горлышко в 15-30 минут на диаризацию — полностью ликвидировано.**

### Требования к памяти

| Конфигурация | v1 | v2 |
|---|---|---|
| Пиковое потребление RAM | 8-16 ГБ | **~400 МБ** (только MediaPipe) |
| Конфигурация воркера | `--threads 1`, лимит 16 ГБ | Стандартный воркер, лимит 4 ГБ |

С 16 гигабайт до 400 мегабайт. В сорок раз. Это не оптимизация — это другая категория задач.

### Фронтенд

Без изменений по сравнению с v1:
- Превью трекинга лица: видеоплеер с наложением bounding box через canvas
- Трек спикеров в TimelinePanel
- Контролы: слайдер зума, скорость перехода, выбор спикера
- Переключатель сравнения «до/после»

### Ключевые цифры

| Метрика | v1 | v2 |
|---|---|---|
| Время диаризации | 15-30 мин (CPU) / 1-2 мин (GPU) | **~30 сек** (API) |
| Время детекции лиц | 1-2 мин | 1-2 мин (без изменений) |
| Общее время анализа | 17-33 мин (CPU) | **~2 мин** |
| Полный пайплайн (с рендером) | 35-80 мин (CPU) | **12-33 мин** |
| Пиковое потребление RAM | 8-16 ГБ | **~400 МБ** |
| Новые зависимости | ~280 МБ (mediapipe + pyannote + torchaudio) | **~30 МБ** (только mediapipe) |
| GPU нужен? | Фаза 2 — рекомендуется | **Никогда** |
| Срок MVP | 12-15 дней | **8-10 дней** |

### Риски

- **Точность маппинга лицо-спикер** не изменилась (70-85% с эвристикой) — по-прежнему самая сложная подзадача
- **Точность диаризации Deepgram** — DER может быть чуть хуже, чем у pyannote 3.1 (~12-15% vs ~10%). Приемлемо для нашего кейса.
- **Потеря качества при кропе** — без изменений
- **TalkNet-ASD отложен** — если временная корреляция недостаточно точна, TalkNet потребует GPU. Разберёмся, когда дойдём.

### MVP vs Полная версия

- **MVP (8-10 дней):** Детекция лиц на сэмплированных кадрах. Deepgram предоставляет метки спикеров. Временная корреляция привязывает лица к спикерам. Пользователь может поправить вручную. Статический кроп на выбранное лицо.
- **Полная (20-30 дней):** Динамический кроп, следующий за активным спикером. Плавные переходы. Сплит-скрин. Мульти-спикер. Опциональный TalkNet-ASD для повышения точности.

---

## Фича 4: Конвертация в вертикальные Shorts (9:16)

**Без изменений по сравнению с v1.** Эта фича не зависит от ML.

### Архитектура

**Пайплайн:** Сначала кроп, потом субтитры — всегда. Один проход рендеринга в Remotion через новую композицию `ShortsVideo`.

**Позиционирование субтитров:** Новые поля в схеме не нужны. Бэкенд корректирует `font_size`, `padding_px`, `max_width_pct` в `styleConfig` под 9:16.

**Спецификация кропа:**
```typescript
type CropConfig = {
  mode: "static" | "keyframe";
  staticCrop?: { x: number; y: number; zoom: number };
  keyframes?: Array<{ time: number; x: number; y: number; zoom: number }>;
  interpolation?: "linear" | "ease" | "smooth";
};
```

### Бэкенд

**Новый тип джоба:** `ASPECT_CONVERT` в `JobTypeEnum`. Новая функция `crop_to_vertical()` в `media/service.py`.

**Новый тип артефакта:** `VERTICAL_VIDEO` в `ArtifactTypeEnum`.

### Фронтенд

- Превью кропа: перетаскиваемый прямоугольник 9:16 поверх видеоплеера
- Переключатель side-by-side превью
- Кнопка «Конвертировать в Short» на каждом одобренном вирусном клипе
- Автозаполнение кропа из данных детекции лица (когда доступны)

### Время обработки

| Подход | Время (30-мин видео) |
|---|---|
| FFmpeg кроп (без субтитров) | 12-36 мин |
| Remotion кроп + субтитры (один проход) | 11-45 мин |
| FFmpeg с NVENC (аппаратное кодирование) | 3-5 мин |

### MVP vs Полная версия

- **MVP (6-8 дней):** Ручной выбор региона кропа с превью. Remotion-композиция `ShortsVideo`.
- **Полная (+3-4 дня после Фичи 3):** Авто-кроп из данных детекции лица. Конвертация в один клик. Пакетный экспорт.

---

## Рекомендуемый порядок разработки

```
Неделя 1-2:    Фича 1 (Шаблоны)              ████████
Неделя 2-3:    Фича 2 (Вирусная детекция)     ██████████
Неделя 3-5:    Фича 4 MVP (9:16 кроп)         ████████████████
Неделя 5-10:   Фича 3 (Трекинг лица)          ██████████████████████████████
Неделя 10-11:  Фича 4 (апгрейд)               ████████
```

**Почему именно так:**
1. **Шаблоны первыми** — готовы к реализации, нулевой риск, моментальная польза для пользователей
2. **Вирусная детекция второй** — самый быстрый ROI с API-first подходом (3-5 дней MVP), валидирует спрос
3. **9:16 MVP третьим** — создаёт композицию `ShortsVideo`, полезна сама по себе
4. **Трекинг лица последним** — всё ещё самая сложная фича, но теперь намного проще без pyannote/GPU
5. **Апгрейд 9:16** — тривиален, когда трекинг лица даёт данные о позициях

---

## Анализ стоимости

### Стоимость обработки одного видео (30-мин, все фичи)

| Компонент | v1 (локальный ML) | v2 (API-First) |
|---|---|---|
| Транскрипция + диаризация | $0.07 вычисления | **$0.16** (Deepgram) |
| LLM вирусная детекция | $0.005 (Gemini) | **$0.01** (GigaChat) |
| Детекция лиц | $0.002 вычисления | $0.002 вычисления (без изменений) |
| FFmpeg/Remotion рендер | $0.02 вычисления | $0.02 вычисления |
| **Итого за видео** | **$0.11** | **$0.20** |

Двадцать центов. За полный пайплайн: транскрипция, диаризация, поиск вирусных моментов, детекция лиц, рендер. Двадцать центов.

### Сравнение месячных расходов

| Масштаб | v1 (локальный ML) | v2 (API-First) |
|---|---|---|
| 100 видео/месяц | $11 вычисления + сервер + $0-380 GPU | **$20 API + сервер** |
| 500 видео/месяц | $55 + $200-380 GPU = $255-435 | **$100 API + сервер** |
| 1 000 видео/месяц | $110 + $380 GPU = $490 | **$200 API + сервер** |
| 5 000 видео/месяц | $550 + $380 GPU = $930 | **$1 000 API + сервер** |

**Точка безубыточности:** ~2 000-3 000 видео/месяц. Ниже этого порога API дешевле. А учитывая, что не нужно думать о GPU, обслуживать ML-инфраструктуру и чинить OOM-крэши — реальный breakeven ещё выше.

### Предлагаемые тарифы SaaS

| Тариф | Цена | Ограничения | Себестоимость | Маржа |
|---|---|---|---|---|
| Free | $0 | Видео до 10 мин, 5/месяц | ~$0.07/видео | Маркетинг |
| Pro | $15-30/мес | Видео до 30 мин, 50/месяц | ~$0.20/видео | 50-70% |
| Business | $50-100/мес | Видео до 60 мин, 200/месяц | ~$0.35/видео | 65-80% |

---

## Инфраструктура (v2 — упрощённая)

### Архитектура

```
Фронтенд → Backend API → Dramatiq-воркер (лёгкий: только MediaPipe)
                              ↕              ↕           ↕
                         PostgreSQL     Deepgram API   GigaChat API
                         Redis          (транскрипция   (вирусная
                         S3/MinIO        + диаризация)   детекция)
                         Remotion        DeepInfra
                                         (фоллбэк LLM)
```

Сравните с v1: нет ML-воркера, нет GPU, нет Docker Compose profiles. Один воркер обрабатывает всё.

### Docker-образ

| | v1 | v2 |
|---|---|---|
| База | python:3.11-slim + PyTorch + Whisper + CUDA libs | python:3.11-slim + mediapipe |
| Размер | 1.72 ГБ | **~400-500 МБ** |
| RAM | 16 ГБ рекомендовано | **4 ГБ достаточно** |

**Можно удалить из `pyproject.toml`:** `openai-whisper` (и транзитивно PyTorch) — если Deepgram полностью заменяет Whisper. Оставить Whisper как опциональную зависимость (`uv sync --group whisper`) для фоллбэка.

### Разделение ML-сервиса не требуется

При том, что локально работает только MediaPipe (~30МБ, ~400МБ RAM), не нужны:
- Отдельный контейнер ML-воркера
- Docker Compose profiles для ML
- GPU-инфраструктура
- Выделенные очереди Dramatiq для ML

Стандартный воркер с `--processes 1 --threads 2` справляется со всем.

### Новые настройки

```python
# Deepgram
deepgram_api_key: str = Field(default="", alias="DEEPGRAM_API_KEY")

# GigaChat (Сбер)
gigachat_client_id: str = Field(default="", alias="GIGACHAT_CLIENT_ID")
gigachat_client_secret: str = Field(default="", alias="GIGACHAT_CLIENT_SECRET")

# DeepInfra (фоллбэк LLM)
deepinfra_api_key: str = Field(default="", alias="DEEPINFRA_API_KEY")

# Конфигурация LLM
llm_provider: str = Field(default="gigachat", alias="LLM_PROVIDER")  # gigachat | deepinfra
llm_viral_prompt_version: str = Field(default="v1", alias="LLM_VIRAL_PROMPT_VERSION")
```

---

## Сводка по технологическому стеку

### Новые зависимости (v2)

| Пакет | Размер | Назначение | Фича |
|---|---|---|---|
| `mediapipe` | ~30 МБ | Детекция лиц (CPU) | 3 |
| `httpx` | Уже установлен | API-вызовы к Deepgram, GigaChat, DeepInfra | 2, 3 |
| **Итого новых зависимостей** | **~30 МБ** | | |

### Удалённые зависимости (по сравнению с v1)

| Пакет | Сэкономлено | Для чего использовался |
|---|---|---|
| ~~`openai-whisper`~~ | ~50 МБ + PyTorch ~2 ГБ | Транскрипция (заменён Deepgram) |
| ~~`pyannote-audio`~~ | ~200 МБ | Диаризация (заменён Deepgram) |
| ~~`torchaudio`~~ | ~50-80 МБ | Зависимость pyannote |
| ~~`librosa`~~ | ~20 МБ | Энергия аудио (заменён сентиментом Deepgram) |
| **Итого удалено** | **~2.3 ГБ** | |

Добавили 30 мегабайт. Удалили 2.3 гигабайта. Соотношение 1:77.

### Новые бэкенд-модули

| Модуль | Назначение | Фича |
|---|---|---|
| `clips` | CRUD клипов, воркфлоу ревью | 2 |

### Новые Remotion-композиции

| Композиция | Назначение | Фича |
|---|---|---|
| `ShortsVideo` | Статический/ключевой кроп + субтитры в 9:16 | 4 |
| `AutoEditVideo` | Динамический кроп с трекингом лица + субтитры | 3 |

### Новые типы джобов

| Тип джоба | Назначение | Фича |
|---|---|---|
| `VIRAL_DETECT` | Анализ транскрипции через GigaChat | 2 |
| `ASPECT_CONVERT` | 9:16 кроп + пере-кодирование | 4 |
| `FACE_DETECT` | Детекция bounding box лиц (MediaPipe) | 3 |

Обратите внимание: `SPEAKER_DIARIZE` **больше не является отдельным типом джоба** — диаризация включена в транскрипцию Deepgram.

### Расширение движков транскрипции

```python
# Расширяем существующий выбор движка:
engine: Literal["whisper", "google", "deepgram"] = "deepgram"
```

Deepgram становится дефолтом. Whisper остаётся как опциональный фоллбэк (требует `uv sync --group whisper`).

---

## Сквозные проблемы (v2)

### Остались из v1

| Проблема | Приоритет | Действие |
|---|---|---|
| `_get_job_status_sync()` течёт соединениями к БД | Высокий | Починить до добавления новых акторов |
| `tasks/service.py` — 1 674 строки, скоро перевалит за 2К | Средний | Вынести бойлерплейт акторов |
| Дефолт `REMOTION_SERVICE_URL` в воркере неверный | Средний | Исправить на `http://remotion:3001` |
| Ни на одном Docker-сервисе нет лимитов ресурсов | Средний | Добавить memory/CPU лимиты |
| Нет очистки временных файлов при OOM-крэше | Средний | Добавить периодическую очистку |
| Проверка `isCurrent` слова в Captions.tsx хрупкая | Низкий | Сравнивать по индексу |

### Новые в v2

| Проблема | Приоритет | Действие |
|---|---|---|
| Управление API-ключами (3 сервиса) | Высокий | Всё через env-переменные в settings, никогда в коде |
| Обработка rate limit'ов API | Высокий | Retry с exponential backoff во всех акторах |
| Зависимость от вендора | Средний | Абстрагировать за интерфейсом движков (существующий паттерн) |
| Зависимость от сети (API недоступен) | Средний | Оставить Whisper как опциональный фоллбэк |
| Конвертация Deepgram -> схема Document | Средний | Построить конвертер под существующую структуру `Document` |
| Обновление OAuth2-токена GigaChat | Средний | Кэширование токена с авто-обновлением в `infrastructure/` |

### Ликвидированные из v1

| ~~Проблема~~ | Почему исчезла |
|---|---|
| ~~PyTorch CPU-only индекс~~ | PyTorch удалён полностью |
| ~~OOM воркера на ML-джобах~~ | Нет тяжёлого ML локально |
| ~~Docker-образ ML-воркера~~ | Один лёгкий образ |
| ~~GPU-инфраструктура~~ | Весь ML — через API |
| ~~Конфликты версий PyTorch~~ | Нет PyTorch |
| ~~Скачивание моделей при первом запуске~~ | Нет локальных моделей |

---

## Отчёты специалистов

Полные выводы специалистов доступны в стенограмме сессии. Ключевые файлы, которые изучал каждый:

- **ML-инженер:** `cpv3/modules/transcription/service.py`, `cpv3/modules/tasks/service.py`, `pyproject.toml`
- **Backend-архитектор:** `cpv3/modules/tasks/service.py`, `cpv3/modules/jobs/schemas.py`, `cpv3/modules/media/service.py`, `cpv3/modules/captions/service.py`, `docker-compose.yml`
- **Remotion-инженер:** `remotion_service/src/components/Composition.tsx`, `Captions.tsx`, `Root.tsx`, `useCaptions.ts`, `useVideoMeta.ts`, все определения типов
- **Frontend-архитектор:** `src/widgets/TimelinePanel/`, `src/features/project/FragmentsStep/`, `src/shared/context/WizardContext.tsx`, `src/shared/store/notifications/`
- **DevOps-инженер:** `docker-compose.yml`, `Dockerfile`, `pyproject.toml`, `uv.lock`
- **Инженер по производительности:** `cpv3/modules/tasks/service.py`, `cpv3/modules/media/service.py`, `cpv3/modules/transcription/service.py`, `docker-compose.yml`

Примечание: Отчёты специалистов подготовлены для архитектуры v1 (локальный ML). Их рекомендации по Remotion-композициям, дизайну бэкенд-модулей, фронтенд-компонентам и форматам данных кропа остаются актуальными в v2. Рекомендации по инфраструктуре и ML-моделям заменены API-first подходом.