## Что изменилось по сравнению с 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 (15-30 мин CPU) | Deepgram `diarize=true` | pyannote + torchaudio — удалены
Gemini 2.5 Flash / GPT-4o-mini | GigaChat Pro (Сбер) | Нативный русский: юмор, сленг, контекст
librosa (энергия аудио) | Deepgram `sentiment=true` | Сентимент заменяет анализ энергии
— | DeepInfra (Llama, Mistral, Qwen) | Фоллбэк / A/B-тестирование LLM

### Ключевые метрики

-75%
Размер Docker-образа
1.72 ГБ → 400-500 МБ
-95%
Пиковое потребление RAM
8-16 ГБ → 400 МБ
-85%
Время обработки
35-80 мин → 5-10 мин
+80%
Стоимость за видео
$0.11 → $0.20 (API)
-88%
Новые Python-зависимости
310-340 МБ → 40 МБ
Никогда
Нужен GPU?
Полностью исключён
Образ в четыре раза легче. RAM в сорок раз меньше. Обработка в шесть-восемь раз быстрее. Цена за единицу чуть выше, но инфраструктурные расходы сжимаются до нуля. Неплохой обмен.

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

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

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

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

Проблема | Приоритет | Митигация
--- | --- | ---
Управление API-ключами (3 сервиса) | Высокий | Через env-переменные в settings, никогда в коде
Rate limit'ы API | Высокий | Retry с exponential backoff в акторах
Vendor lock-in | Средний | Абстрагировать за интерфейсами движков
API упал = обработка встала | Средний | Whisper как опциональный фоллбэк
$0.20 vs $0.11 за видео | Низкий | Нулевые инфраструктурные расходы; прибыльно на любом SaaS-тарифе

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

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

Реалистичный прогноз для одного разработчика: 5-7 недель (все MVP) или 2-3 месяца (полные версии).
1
Продвинутые шаблоны Remotion
Без изменений по сравнению с v1. Эта фича не зависит от ML. Спецификация и план уже написаны — бери и делай.

Что делаем: Расширяем `CaptionStyleSchema` четырьмя новыми стилями подсветки (`pop_in`, `karaoke`, `bounce`, `glow_pulse`), двумя переходами (`zoom_in`, `drop_in`), тремя полями. Два системных пресета: "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`. Один вызов — пословные таймстемпы, метки спикеров, оценка сентимента. Стоимость: $0.0053/мин ($0.16 за 30-минутное видео). Обработка: ~30 секунд.

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

Аудио-подкрепление: Сентимент от Deepgram заменяет librosa. Высокий сентимент коррелирует с вирусными моментами.

#### Пайплайн

1 Deepgram транскрипция
→
2 Конвертация в Document
→
3 GigaChat анализ
→
4 Постобработка
→
5 Сохранение в clips

### Бэкенд

Новый модуль: `clips` (models, schemas, repository, service, router).

#### Модель клипа

    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 через `httpx` из Dramatiq-воркера.

Расширение движков: `engine: "whisper" | "google" | "deepgram"`. Deepgram — дефолт.

#### Интеграция с LLM

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

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

Метрика | v1 | v2
--- | --- | ---
Время транскрипции | Зависит от Whisper | ~30 сек (Deepgram)
Время LLM-анализа | 10-20 сек | 10-20 сек
Общее время | 10-20 сек (после транскрипции) | 40-50 сек
Стоимость за видео | ~$0.005 | ~$0.17
Точность (precision) | 50-70% | 60-80%
Новые зависимости | ~30 МБ | ~0 МБ
Срок MVP | 5-7 дней | 3-5 дней

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

### Риски

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

### 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-компонент.

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

#### Маппинг лицо-спикер

#### Фаза 1

Временная корреляция: треки лиц × сегменты спикеров. 70-85% точности. ~100 строк Python. Ноль зависимостей.

#### Фаза 2

TalkNet-ASD (анализ губ + аудио). ~92% точности. Нужен GPU. Можно откладывать бесконечно.

Видео-композитинг: CSS `transform: scale() translate()` в Remotion. GPU-ускоренная браузерная операция — бесплатная по производительности.

#### Remotion-композиции

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

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

Шаг | 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 минут на диаризацию — полностью ликвидировано.

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

8-16 ГБ
v1 — пиковое RAM
~400 МБ
v2 — пиковое RAM
С 16 гигабайт до 400 мегабайт. В сорок раз. Это не оптимизация — это другая категория задач.

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

Метрика | 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 МБ | ~30 МБ
GPU нужен? | Фаза 2 рекомендуется | Никогда
Срок MVP | 12-15 дней | 8-10 дней

### Риски

Маппинг лицо-спикер — 70-85% точности. Каждое пятое назначение может быть неверным. Пользователь должен поправить вручную.
Deepgram DER — ~12-15% vs ~10% у pyannote. Приемлемо.
Потеря качества при кропе — без изменений.
TalkNet-ASD отложен — если нужен GPU, разберёмся когда дойдём.

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

#### MVP — 8-10 дней

Детекция лиц + Deepgram спикеры. Временная корреляция. Ручная коррекция. Статический кроп.

#### Полная — 20-30 дней

Динамический кроп. Плавные переходы. Сплит-скрин. Мульти-спикер. Опциональный TalkNet-ASD.

4
Конвертация в Shorts (9:16)
Без изменений по сравнению с v1. Не зависит от ML.

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

#### Спецификация кропа

    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`. Функция `crop_to_vertical()` в `media/service.py`.

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

### Фронтенд

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

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

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

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

#### MVP — 6-8 дней

Ручной выбор кропа с превью. Remotion-композиция `ShortsVideo`.

#### Полная — +3-4 дня после Фичи 3

Авто-кроп по лицу. Один клик. Пакетный экспорт.

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

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

### Почему именно так

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

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

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

Компонент | v1 (локальный ML) | v2 (API-First)
--- | --- | ---
Транскрипция + диаризация | $0.07 compute | $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 | v2
--- | --- | ---
100 видео/мес | $11 + сервер + $0-380 GPU | $20 API + сервер
500 видео/мес | $255-435 | $100 + сервер
1 000 видео/мес | $490 | $200 + сервер
5 000 видео/мес | $930 | $1 000 + сервер

Точка безубыточности: ~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 — упрощённая)

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

Frontend
→
Backend API
→
Dramatiq-воркер (MediaPipe)
↓
PostgreSQL
Redis
S3/MinIO
Remotion
↓
Deepgram API
GigaChat API
DeepInfra

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

### Docker-образ

1.72 ГБ
v1: python + PyTorch + Whisper + CUDA
400-500 МБ
v2: python + mediapipe
16 ГБ
v1: рекомендованная RAM
4 ГБ
v2: достаточная RAM

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

MediaPipe (~30МБ, ~400МБ RAM) — это всё, что работает локально. Не нужны:

- Отдельный контейнер ML-воркера
- Docker Compose profiles для ML
- GPU-инфраструктура
- Выделенные очереди Dramatiq для ML

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

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

    # 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")
    llm_viral_prompt_version: str = Field(default="v1", alias="LLM_VIRAL_PROMPT_VERSION")

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

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

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

### Удалённые зависимости

Пакет | Сэкономлено | Заменён на
--- | --- | ---
`openai-whisper` | ~50 МБ + PyTorch ~2 ГБ | Deepgram
`pyannote-audio` | ~200 МБ | Deepgram
`torchaudio` | ~50-80 МБ | Deepgram
`librosa` | ~20 МБ | Deepgram sentiment
Итого удалено | ~2.3 ГБ |

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

### Новые компоненты

clips
Бэкенд-модуль: CRUD + ревью клипов
ShortsVideo
Remotion: кроп + субтитры 9:16
AutoEditVideo
Remotion: трекинг лица + субтитры

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

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

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

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

    engine: Literal["whisper", "google", "deepgram"] = "deepgram"

Deepgram — дефолт. Whisper — опциональный фоллбэк (`uv sync --group whisper`).

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

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

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

### Новые в v2

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

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

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