docs initial

2026-04-06 01:44:58 +03:00
parent 2a344ad588
commit 694b8bc77c
84 changed files with 6922 additions and 298 deletions
@@ -0,0 +1,800 @@
+# Исследование API-сервисов: Video Intelligence, STT, TTS & B-Roll
+
+**Дата:** 1 апреля 2026
+**Консультанты:** ML/AI-инженер, Backend-архитектор, Remotion-инженер, Product Lead, + 4 исследовательских агента
+**Контекст:** Глубокий анализ API-сервисов для будущих фич — highlight detection, shorts generation, semantic search, B-Roll
+
+---
+
+## Содержание
+
+1. [Executive Summary](#1-executive-summary)
+2. [STT — обновлённое сравнение](#2-stt--обновлённое-сравнение)
+3. [TTS — обновлённое сравнение](#3-tts--обновлённое-сравнение)
+4. [Video Intelligence — полное сравнение](#4-video-intelligence--полное-сравнение)
+5. [TwelveLabs — глубокий анализ](#5-twelvelabs--глубокий-анализ)
+6. [Gemini 2.5 — ключевой новый игрок](#6-gemini-25--ключевой-новый-игрок)
+7. [Clipping-платформы (OpusClip, Reap, Vizard)](#7-clipping-платформы)
+8. [B-Roll генерация](#8-b-roll-генерация)
+9. [Архитектура интеграции в Coffee Project](#9-архитектура-интеграции-в-coffee-project)
+10. [Remotion Pipeline — эволюция](#10-remotion-pipeline--эволюция)
+11. [Продуктовая стратегия и монетизация](#11-продуктовая-стратегия-и-монетизация)
+12. [Сводная таблица стоимости](#12-сводная-таблица-стоимости)
+13. [Рекомендации и дорожная карта](#13-рекомендации-и-дорожная-карта)
+14. [Красные флаги в текущем коде](#14-красные-флаги-в-текущем-коде)
+15. [Источники](#15-источники)
+
+---
+
+## 1. Executive Summary
+
+### Ключевые находки
+
+1. **Gemini 2.5 Flash — game-changer.** $0.005/мин за видеоанализ (20-60x дешевле TwelveLabs). Достаточно для MVP highlight detection.
+
+2. **TwelveLabs оправдан только для повторных запросов.** Модель «проиндексируй раз — ищи многократно» выгодна при 10+ запросах к одному видео. Для одноразового анализа — Gemini дешевле.
+
+3. **ElevenLabs Scribe v2 — лучший STT для нашего продукта.** WER 2.3%, точные пословные таймстемпы (критично для субтитров), встроенная диаризация. $0.40/час.
+
+4. **B-Roll генерация НЕ готова для продакшна.** Рекомендация: Pexels API (бесплатный) для поиска стокового видео по ключевым словам из транскрипции.
+
+5. **Reap.video — неожиданно сильный конкурент.** API + CLI + MCP за $9.99/мес, 98 языков для субтитров. Дешевле и доступнее OpusClip.
+
+6. **У Coffee Project нулевая инфраструктура монетизации.** Нет планов, тарифов, трекинга использования, биллинга. Это блокер для любых платных фич.
+
+7. **Русский рынок — first-mover advantage.** Нет локальных конкурентов в AI video clipping. Западные инструменты недоступны из-за санкций.
+
+### Рекомендуемый стек (обновлённый)
+
+| Задача | Сервис | Цена | Зачем именно этот |
+|--------|--------|------|-------------------|
+| STT (продакшн) | ElevenLabs Scribe v2 | $0.40/час | Лучший WER + таймстемпы для субтитров |
+| STT (черновик/preview) | Whisper v3-turbo (DeepInfra) | $0.06/час | 253x realtime, мгновенный preview |
+| Highlight detection (MVP) | Gemini 2.5 Flash | $0.005/мин | 20-60x дешевле TwelveLabs |
+| Highlight detection (premium) | TwelveLabs Pegasus 1.2 | $0.063/мин | Лучшая точность для автоматизации |
+| Chapters | Gemini 2.5 Flash | $0.005/мин | Достаточно качества, минимальная цена |
+| Semantic search | TwelveLabs Marengo 3.0 | $4/1000 запросов | Единственный с pre-indexed search |
+| B-Roll suggestions | Pexels API | Бесплатно | Реальное видео > AI-генерация |
+| TTS (русский) | SaluteSpeech | $2.1/1M символов | Самый дешёвый для RU |
+
+---
+
+## 2. STT — обновлённое сравнение
+
+### Сравнительная таблица (апрель 2026)
+
+| Сервис | WER (EN) | WER (RU, оценка) | $/час | Пословные таймстемпы | Диаризация | Особенности |
+|--------|----------|-------------------|-------|----------------------|------------|-------------|
+| **ElevenLabs Scribe v2** | **2.3%** | ~5-7% | $0.40 | Да, точные (для субтитров) | Да (batch) | Audio tagging (смех, музыка), 90+ языков |
+| **Deepgram Nova-3 Mono** | 5.4% | ~8-12% | $0.46 | Да, улучшены в v3 | Да (+$0.12/час) | Code-switching 10 языков в одном потоке |
+| **Deepgram Nova-3 Multi** | 5.4% | ~8-12% | $0.55 | Да | Да | Мультиязычная версия |
+| **Whisper large-v3 (stock)** | 4.2% | 9.0% | $0.06 (DeepInfra) | Да, ±500ms нативно | Нет | Open-source, pay-as-you-go |
+| **Whisper large-v3 (fine-tuned RU)** | — | **6.4%** | Self-hosted | Да, ±500ms | Нет | Требует GPU, инфраструктура |
+| **Whisper v3-turbo** | 4.8% | 10.2% | $0.06 (DeepInfra) | Да, менее точные | Нет | 253x realtime, 6x быстрее large |
+| **Google Speech V1** (текущий) | ~6-8% | ~8-12% | ~$0.06/15сек | Да | Да | Уже интегрирован |
+
+### Критический вывод: точность таймстемпов
+
+Для Coffee Project **точность пословных таймстемпов — главная метрика**, потому что субтитры синхронизируются покадрово в Remotion через `WordNode.time.start/end`.
+
+- **ElevenLabs Scribe v2**: создан для субтитрирования. Точность таймстемпов достаточна без постобработки.
+- **Whisper нативный**: ±500ms на уровне сегментов. Пословные таймстемпы из cross-attention весов — заметно неточные. Это проблема, которая уже есть в проекте.
+- **Whisper + WhisperX**: значительно лучше через wav2vec2 forced alignment, но добавляет вторую модель и сложность.
+
+### Рекомендация ML/AI-инженера
+
+**Двухуровневая архитектура STT:**
+
+| Уровень | Движок | Задержка | $/час | Когда |
+|---------|--------|----------|-------|-------|
+| Черновик (мгновенный) | Whisper v3-turbo (DeepInfra) | ~2-3 сек на 5 мин | $0.06 | Preview сразу после загрузки |
+| Продакшн (точный) | ElevenLabs Scribe v2 | ~15-30 сек на 5 мин | $0.40 | Заменяет черновик, используется для рендера |
+
+Экономия: 85% на большинстве взаимодействий (просмотр, предпросмотр), где достаточно черновика.
+
+### Новое в ElevenLabs Scribe v2
+
+- **Audio tagging** (январь 2026): детектирует смех, аплодисменты, музыку, шаги, фоновый шум. Теги появляются inline в транскрипте с таймстемпами: `(laughter)`, `(music)`.
+- **Scribe v2 Realtime**: 30-80ms задержка, 93.5% точность на 30 языках.
+- **Voice Isolator**: нейронное разделение речи — полезно для предобработки шумного видео.
+
+### Новое в Deepgram Nova-3
+
+- **54.2% снижение WER** для стриминга vs конкурентов.
+- **Live code-switching**: 10 языков (включая русский) в одном потоке.
+- **Keyterm prompting**: мультиязычный, улучшает точность для специфических терминов.
+- **Audio Intelligence — по-прежнему только EN.** Sentiment, topics, intent — только английский. Это критическое ограничение для нашего продукта.
+
+---
+
+## 3. TTS — обновлённое сравнение
+
+Без изменений vs первоначальное исследование. Обновлённые цены Deepgram:
+
+| Сервис | $/1K символов | $/1M символов | Особенности |
+|--------|---------------|---------------|-------------|
+| **SaluteSpeech** (Сбер) | ~$0.0021 | ~$2.1 | Самый дешёвый. RU/EN/KZ |
+| **Deepgram Aura-1** | $0.015 | $15 | Предыдущее поколение |
+| **Deepgram Aura-2** | $0.030 | $30 | Новейшая модель |
+| **ElevenLabs Flash/Turbo** | $0.06 | $60 | Business tier, ~75ms, 32 языка |
+| **ElevenLabs Multilingual v2/v3** | $0.12 | $120 | Премиум качество, voice cloning |
+
+---
+
+## 4. Video Intelligence — полное сравнение
+
+### Сравнительная матрица
+
+| Параметр | TwelveLabs | Gemini 2.5 Pro | Gemini 2.5 Flash | GPT-4o/4.1 | Google Video Intelligence | Azure Video Indexer |
+|----------|-----------|----------------|------------------|------------|--------------------------|---------------------|
+| **Тип** | Video-native foundation models | General VLM с видеовходом | General VLM (лёгкий) | Image-only (кадры) | Structured annotation | ML pipeline orchestrator |
+| **Архитектура** | Marengo (embeddings) + Pegasus (генерация) | Мультимодальный LLM | Мультимодальный LLM | Мультимодальный LLM (без видео) | Отдельные ML-модели | Набор Azure AI сервисов |
+| **Highlight detection** | Нативный API, таймкоды | Через промпт, секундные таймкоды | Через промпт | Нет | Нет | Нет |
+| **Semantic search** | Pre-indexed (Marengo) | Промпт-based | Промпт-based | Нет | Нет | Нет |
+| **Chapters** | Нативный API | Через промпт | Через промпт | Через промпт | Нет | Нет |
+| **Object tracking** | Сильный, cross-frame | Ограниченный | Ограниченный | Нет (между кадрами) | Отдельная фича ($0.15/мин) | Да |
+| **Макс. длительность** | 4 часа (Marengo), 1 час (Pegasus) | ~6 часов (2M контекст) | ~6 часов | Ограничен кадрами | Без лимита | 12 часов (free tier) |
+| **Русская речь** | Да (36+ языков) | Да (сильный) | Да | Нет нативного аудио | 50+ языков | 50+ языков |
+| **Цена за 1 мин** | $0.063 (index+analyze) | $0.021 (≤200k) | **$0.005** | $0.026-0.23 | $0.025-0.15 (per feature) | Custom |
+| **Цена за 1 час** | $3.78 | $1.26 | **$0.36** | $1.56-13.80 | $1.50-9.00 | Custom |
+| **Повторные запросы** | $4/1000 (дёшево) | Пересчитываются (дорого) | Пересчитываются | Пересчитываются | — | — |
+| **Бенчмарки** | SOTA VideoMME-Long (30+ мин) | 85.2% VideoMME | Ниже Pro | 72% VideoMME | — | — |
+
+### Ключевой инсайт: «проиндексируй раз — ищи многократно»
+
+TwelveLabs заявляет ~36,000x дешевле Gemini для повторных запросов к тому же видео ($0.09/видео-час/месяц vs $4.50/1M токенов за запрос). Но для **одноразового анализа** (highlight detection для одного видео) — Gemini 2.5 Flash в 12x дешевле.
+
+---
+
+## 5. TwelveLabs — глубокий анализ
+
+### Актуальные модели (апрель 2026)
+
+| Модель | Статус | Назначение | Ключевые улучшения |
+|--------|--------|-----------|-------------------|
+| **Marengo 3.0** | GA (текущая) | Embeddings, Search | 512-dim (было 1024), composed text+image search, спорт, 36 языков, 4 часа видео, 2x быстрее |
+| **Pegasus 1.2** | GA (текущая) | Analyze, генерация | 1 час видео, меньше галлюцинаций, SOTA на VideoMME-Long |
+| Marengo 2.7 | **Sunset 30 марта 2026** | — | Устарела |
+| Pegasus 1.1 | **Discontinued** | — | Автообновлена до 1.2 |
+
+### Подтверждённые цены (Developer plan)
+
+| Компонент | Цена | Подтверждено |
+|-----------|------|-------------|
+| Video indexing (Marengo/Pegasus) | $0.042/мин ($2.52/час) | ✅ |
+| Infrastructure (хранение индексов) | $0.0015/мин ($0.09/час/мес) | ✅ |
+| Analyze API input (Pegasus) | $0.021/мин | ✅ |
+| Analyze API output | $7.50/1M токенов | ✅ |
+| Search API | $4/1000 запросов | ✅ |
+| Embed API (video) | $0.042/мин | ✅ |
+| **Embed API (audio only)** | **$0.0083/мин** | 🆕 |
+| **Embed API (image)** | **$0.10/1000 запросов** | 🆕 |
+| **Embed API (text)** | **$0.07/1000 запросов** | 🆕 |
+
+Free tier: 600 минут, 100 видео, 90 дней хранения.
+
+### SDK и интеграция
+
+**Python SDK** (`pip install twelvelabs`, v1.2.1):
+```python
+from twelvelabs import TwelveLabs
+client = TwelveLabs(api_key=API_KEY)
+
+# Highlight detection
+res = client.generate.summarize(video_id="...", type="highlight")
+for hl in res.highlights:
+    print(f"{hl.start}s-{hl.end}s: {hl.highlight}")
+
+# Chapter generation
+res = client.generate.summarize(video_id="...", type="chapter")
+for ch in res.chapters:
+    print(f"{ch.start}s-{ch.end}s: {ch.chapter_title}")
+
+# Structured JSON output (новое)
+result = client.analyze(
+    video_id="...",
+    prompt="Extract key moments",
+    response_format=ResponseFormat(type="json_schema", json_schema={...})
+)
+```
+
+**Node.js SDK**: `npm install twelvelabs-js` (production-ready).
+
+**OpenAPI spec**: 8,400 строк, доступен в [repo](https://github.com/twelvelabs-io/twelvelabs-developer-experience).
+
+### Ограничения и gotchas
+
+- Текстовый запрос: макс **77 токенов** (Marengo), **500 токенов** (Marengo 3.0)
+- Промпт Pegasus: макс **375 токенов**
+- Видео: 360x360 — 5184x2160, aspect ratio 1:1 — 2.4:1, мин 4 сек
+- Размер файла: макс 200 МБ (прямая загрузка), 4 ГБ (multipart/URL)
+- Индексация: только async, нужно poll status или webhook
+- **Webhooks только для индексации** — нет для analyze/search/embed
+- Rate limits: Free 8 RPM, Dev Tier 1 = 600 RPM (search), автоапгрейд при $200+/мес
+
+### Интеграции из repo
+
+- **Vector Store RAG**: ChromaDB, Weaviate, LanceDB, Oracle
+- **Real-time мониторинг**: VideoDB (RTSP feeds)
+- **Visual pipelines**: Langflow
+- **Chatbot**: Poe
+
+---
+
+## 6. Gemini 2.5 — ключевой новый игрок
+
+### Почему это важно
+
+Gemini 2.5 Flash при $0.005/мин — это **20-60x дешевле TwelveLabs** для одноразового видеоанализа. С 2M-токенным контекстом может обработать ~6 часов видео за один вызов. Это делает highlight detection доступным даже на free tier нашего продукта.
+
+### Pricing per minute video
+
+Видео потребляет **258 токенов/сек** (1 fps). Аудио добавляет **25 токенов/сек**.
+
+| Модель | $/мин (видео) | $/мин (видео+аудио) | $/час | Batch (50% скидка) |
+|--------|---------------|---------------------|-------|-------------------|
+| **Gemini 2.5 Flash** | **$0.005** | $0.006 | $0.36 | $0.18/час |
+| Gemini 2.5 Pro (≤200k) | $0.019 | $0.021 | $1.26 | $0.63/час |
+| Gemini 2.5 Pro (>200k) | $0.039 | $0.041 | $2.46 | $1.23/час |
+
+### Gemini vs TwelveLabs: когда что
+
+| Сценарий | Победитель | Почему |
+|----------|-----------|-------|
+| Одноразовый highlight detection | **Gemini Flash** | 12x дешевле ($0.005 vs $0.063/мин) |
+| Точные таймкоды для автоматической нарезки | **TwelveLabs** | Video-native модель, лучше temporal grounding |
+| Повторные запросы к библиотеке видео | **TwelveLabs** | Index once, query many ($4/1000 запросов) |
+| Object tracking cross-frame | **TwelveLabs** | Архитектурное преимущество |
+| Chapter generation | **Gemini Flash** | Достаточно качества, 12x дешевле |
+| Semantic search | **TwelveLabs** | Единственный с pre-indexed vector search |
+| Budget MVP | **Gemini Flash** | Минимальная стоимость входа |
+
+### GPT-4o/4.1 — не рекомендуется для видео
+
+- **Нет нативного видеовхода** — нужно извлекать кадры (OpenCV/ffmpeg)
+- 85 токенов/кадр (low detail), 765 токенов/кадр (high detail)
+- $0.026-0.23/мин — **дороже Gemini при худшем качестве**
+- Нет аудио из видео (отдельный Whisper)
+- Нет встроенных таймкодов
+- GPT-4.1: улучшен до 72% VideoMME, но фундаментальное ограничение (кадры) остаётся
+
+---
+
+## 7. Clipping-платформы
+
+### Сравнение API-доступности
+
+| Платформа | API | Цена API | Highlights | Captions | Reframe | Batch | RU |
+|-----------|-----|----------|-----------|----------|---------|-------|-----|
+| **OpusClip** | Enterprise only | Custom | ✅ 95%+ mAP | ✅ | ✅ | 50 concurrent | Нет |
+| **Reap.video** | Все планы ($9.99+) | Включена | ✅ Multi-signal | ✅ 98 языков | ✅ | 5-15 concurrent | ✅ |
+| **Vizard** | Paid планы ($20+) | Включена | ✅ | ✅ 100+ языков | ✅ | Minimal API | Неизвестно |
+| **Descript** | Нет public API | — | ✅ "Find Good Clips" | ✅ | ✅ | — | Нет |
+| **CapCut** | Нет public API | — | ✅ Smart Highlights | ✅ | ✅ | — | Частично |
+
+### OpusClip — подробнее
+
+- **ClipAnything**: мультисигнальный AI (визуал + аудио + сентимент), mAP 0.93
+- **Virality Score**: 0-100 эвристика, спорная точность (клипы с низким скором часто работают лучше)
+- **API**: Enterprise-only, 30 req/мин, макс 10 часов видео
+- **Цены SaaS**: Free 60 мин/мес → Starter $15 (150 мин) → Pro $14.50/мес (annual, 3600/год)
+- **Барьер**: API недоступен на обычных планах
+
+### Reap.video — неожиданно сильный
+
+- **API + CLI + MCP** за $9.99/мес — значительно доступнее OpusClip
+- **MCP Server** — прямая интеграция с Claude Code и другими AI-агентами
+- **Prompt-first clipping**: опиши какие клипы хочешь — AI найдёт
+- **98 языков** включая русский для субтитров
+- **80 языков** для дубляжа (русский включён)
+- **Romanized scripts** (Hinglish, Arabizi) — уникальная фича
+
+### Конкурентная карта (Product Lead)
+
+```
+                 ВЫСОКАЯ ЦЕНА
+                    |
+         Descript   |   (Enterprise)
+         $24-35/мес |
+                    |
+    OpusClip $29    |
+                    |
+    Vizard $20-30---+--- ☕ Coffee Project TARGET: $15-29/мес
+                    |     Субтитры + Клипы в одном
+                    |
+   Reap $9.99       |
+                    |
+         CapCut     |
+         $8-20      |
+                    |
+                 НИЗКАЯ ЦЕНА
+                    |
+   ТОЛЬКО СУБТИТРЫ -------------- ПОЛНЫЙ REPURPOSING
+```
+
+**Позиционирование Coffee Project**: «Единственный инструмент, где субтитры И клипы — first-class citizens в одном workflow, по цене ниже full-editor tax.»
+
+---
+
+## 8. B-Roll генерация
+
+### Text-to-Video модели: текущее состояние
+
+| Модель | Качество | Длительность | $/5-сек клип | Готово для B-Roll? |
+|--------|----------|-------------|-------------|-------------------|
+| **Runway Gen-4 Turbo** | Хорошее, быстрое | 5-10 сек | $0.25 | Почти, но артефакты |
+| **Runway Gen-4.5** | Выше | 5-10 сек | $0.60 | Ближе |
+| **Runway Gen-4 Aleph** | Наивысшее (Runway) | 5-10 сек | $0.75 | Ближе |
+| **Pika 2.2** (via fal.ai) | Хорошее для соцсетей | 5 сек | **$0.20** | Для некритичного контента |
+| **Kling 2.6** | Отличное для природы | 5-10 сек | $0.45-0.50 | Для ландшафтов да |
+| **Veo 3.1** (Runway API) | Сильное | 5-10 сек | $1.00 | Дорого |
+
+### Честная оценка ML/AI-инженера: генерация НЕ готова
+
+**Нет, ещё не для профессионального использования.** Причины:
+
+1. **Консистентность**: каждая генерация независима. Нельзя получить два клипа с одинаковым освещением, локацией, камерой.
+2. **Длительность**: 5-10 секунд. Реальный B-Roll — 15-60 секунд. Нужно цепочку генераций, что усиливает проблему консистентности.
+3. **Артефакты**: даже Runway Gen-4 даёт нарушения физики, несоответствие освещения, «AI-маркеры».
+4. **Стоимость**: 5-10 B-Roll клипов × $0.50 (+ 2-3 перегенерации) = $7.50-15 за видео. Стоковое видео дешевле.
+
+### Рекомендация: AI-powered поиск стокового видео
+
+| Сервис | Цена | Библиотека | API | Semantic Search |
+|--------|------|-----------|-----|-----------------|
+| **Pexels API** | **Бесплатно** | ~150K видео | Да, хорошая документация | Базовый keyword |
+| **Storyblocks API** | Подписка | 1M+ видео | Да | Лучшая категоризация |
+| **Shutterstock API** | Per-download / подписка | Крупнейшая | Да | AI-powered search |
+
+**Phase 1 (запустить сейчас): Pexels API.**
+
+Pipeline:
+1. Транскрипция даёт текстовые сегменты с таймкодами
+2. Gemini Flash анализирует сегменты → предлагает ключевые слова для B-Roll
+3. Pexels API ищет подходящее стоковое видео
+4. Пользователь выбирает из предложений
+
+Бесплатно, реальное видео выглядит профессионально, можно запустить за недели.
+
+**Phase 2 (когда модели созреют): AI-generated B-Roll как premium-опция.** Revisit в Q3 2026 с Runway Gen-5 / Veo 4.
+
+---
+
+## 9. Архитектура интеграции в Coffee Project
+
+### Текущий pipeline (recap)
+
+```
+Upload → S3 → Media Probe (ffprobe) → Transcription (Whisper/Google) → Captions (Remotion) → S3
+                                                                           ↕
+                                                               Silence Detection (pydub)
+```
+
+**Что есть:**
+- 2 STT-движка: LOCAL_WHISPER (default `tiny` — плохое качество), GOOGLE_SPEECH_CLOUD
+- Dramatiq actors для всех фоновых задач с webhooks + WebSocket notifications
+- Пустое поле `semantic_tags` в `WordNode` — готово для ML-аннотаций
+- Silence detection (pydub + librosa)
+
+**Чего нет:**
+- Highlight/chapter detection
+- Semantic search
+- Video intelligence интеграция
+- Монетизация (планы, квоты, биллинг)
+
+### Новый модуль: `video_intelligence`
+
+Backend-архитектор рекомендует **один новый модуль** со стандартной 6-файловой структурой:
+
+```
+cpv3/modules/video_intelligence/
+    __init__.py
+    models.py        # VideoIndex model
+    schemas.py       # Index, Highlight, Chapter, Search schemas
+    repository.py    # VideoIndexRepository
+    service.py       # Provider calls, business logic
+    router.py        # API endpoints
+```
+
+### Модель данных
+
+```python
+class VideoIndex(Base, BaseModelMixin):
+    user_id: UUID                    # FK users
+    project_id: UUID | None          # FK projects
+    source_file_id: UUID             # FK files
+    provider: str                    # "TWELVE_LABS" | "GEMINI"
+    provider_index_id: str           # Provider-specific ID
+    provider_video_id: str           # Provider video ref
+    highlights_json: dict | None     # Cached highlights (JSONB)
+    chapters_json: dict | None       # Cached chapters (JSONB)
+    index_status: str                # PENDING | INDEXING | READY | FAILED
+    video_duration_seconds: float
+    indexing_cost_cents: int | None   # Cost tracking
+```
+
+Highlights и chapters — JSONB-колонки (не отдельные таблицы), по аналогии с `Transcription.document`.
+
+### Расширенный pipeline
+
+```
+Upload → S3 → Media Probe
+                    |
+        +-----------+-----------+
+        |                       |
+   Transcription           Video Index (user-triggered)
+   (Whisper/Scribe)       (TwelveLabs/Gemini)
+        |                       |
+        |              +--------+--------+
+        |              |        |        |
+        |         Highlights  Chapters  Search
+        |         (Dramatiq)  (Dramatiq) (sync endpoint)
+        |              |        |
+        +------+-------+--------+
+               |
+          Shorts/Clips Rendering (Remotion)
+```
+
+### Режимы операций
+
+| Операция | Режим | Почему |
+|----------|-------|-------|
+| Video indexing | **Dramatiq (async)** | Минуты обработки |
+| Highlight detection | **Dramatiq (async)** | 30-60 сек |
+| Chapter generation | **Dramatiq (async)** | 30-60 сек |
+| Semantic search | **Sync endpoint** | 1-3 сек ответ |
+| B-Roll suggestions | **Sync endpoint** | Быстрый поиск |
+
+### Новые endpoints
+
+**Task endpoints** (async, в `tasks/router.py`):
+```
+POST /api/tasks/video-index/           → 202 Accepted
+POST /api/tasks/highlights-detect/     → 202 Accepted
+POST /api/tasks/chapters-generate/     → 202 Accepted
+```
+
+**Sync endpoints** (в `video_intelligence/router.py`):
+```
+GET  /api/video-intelligence/{id}/              → VideoIndexRead
+GET  /api/video-intelligence/{id}/highlights/   → HighlightsResult
+GET  /api/video-intelligence/{id}/chapters/     → ChaptersResult
+POST /api/video-intelligence/search/            → VideoSearchResponse
+POST /api/video-intelligence/broll-suggestions/  → BRollSuggestionResponse
+```
+
+### Квоты и контроль расходов
+
+Redis-based per-user quotas:
+```python
+# Проверка ПЕРЕД созданием Dramatiq task
+QUOTA_FREE_INDEX_MINUTES = 60
+key = f"vi_quota:{user_id}:indexed_minutes"
+
+# Кэш поисковых запросов (5 мин TTL)
+key = f"vi_search_cache:{video_index_id}:{sha256(query)[:16]}"
+```
+
+### Ключевые архитектурные решения
+
+1. **НЕТ автоматической цепочки задач.** Frontend контролирует workflow — каждая задача запускается явно.
+2. **НЕТ абстрактного провайдер-паттерна** (YAGNI). Простой string selector как в transcription engine.
+3. **Retry с backoff для внешних API** (`max_retries=3, min_backoff=15000`) — в отличие от текущих actors с `max_retries=0`.
+4. **Highlights/chapters кэшируются в БД** (JSONB). Search кэшируется в Redis (5 мин TTL).
+
+---
+
+## 10. Remotion Pipeline — эволюция
+
+### Shorts/Clips рендеринг
+
+**Гибридный подход FFmpeg + Remotion (2-3x быстрее чистого Remotion):**
+
+| Шаг | Инструмент | Время | Зачем |
+|-----|-----------|-------|-------|
+| 1. Вырезать клип | FFmpeg `-c copy` | ~1 сек | Stream copy, без перекодирования |
+| 2. Рендер с субтитрами | Remotion `ShortVideo` | 10-30 сек на клип | Каппинг + reframe + стили |
+| 3. Upload | S3 multipart | ~5 сек | В папку `shorts/` |
+
+**Сравнение для 10-мин видео → 5 Shorts по 1 мин:**
+
+| Подход | Общее время | Ресурсы |
+|--------|------------|---------|
+| Чистый Remotion (5 рендеров от полного видео) | 5-10 мин | Высокие: 5 Chromium процессов, каждый ищет в 10-мин видео |
+| **Гибрид** (FFmpeg нарезка + 5 лёгких рендеров) | **2-5 мин** | Средние: FFmpeg ~5 сек + 5 лёгких Remotion |
+| Чистый FFmpeg (без субтитров) | ~10 сек | Минимальные |
+
+### Новая композиция: `ShortVideo`
+
+```typescript
+type ShortCompositionProps = {
+  videoSrc: string;
+  transcription: Transcription;
+  fps: number;
+  styleConfig?: CaptionStyleConfig;
+  clipStart: number;          // Начало в секундах
+  clipEnd: number;            // Конец в секундах
+  cropConfig?: {
+    focusX: number;           // 0-1, центр кропа
+    focusY: number;
+    autoReframe: boolean;
+  };
+};
+```
+
+**Адаптация субтитров для вертикального формата:**
+- Шрифт: 60-70px (вместо 40)
+- Строки на экране: 1, макс 3-4 слова
+- Позиция: bottom с отступом 80-100px (UI YouTube Shorts/TikTok/Reels перекрывает низ)
+- Max width: 95% от 1080px
+- Фон: более непрозрачный
+
+**Auto-reframe:**
+- Phase 1: Center crop (простейший, 607x1080 из 1920x1080)
+- Phase 2: Speaker-position crop (per-segment `focusX` из ML)
+- Phase 3: Per-frame face tracking (future)
+
+### Chapter markers
+
+Простой overlay — НЕ реструктуризация видео:
+- `ChapterOverlay` компонент: fade-in заголовок, hold 2 сек, fade-out
+- `interpolate()` для анимации (не CSS transitions)
+- YouTube chapters metadata — ответственность backend, не Remotion
+
+### B-Roll в Remotion
+
+Самая сложная фича — мультиисточниковый таймлайн:
+
+```typescript
+type BRollSegment = {
+  src: string;              // S3 presigned URL
+  startTime: number;        // Когда показать
+  endTime: number;
+  mode: "cutaway" | "pip";  // Полная замена или overlay
+  transitionIn?: "fade" | "slide" | "cut";
+  audio: "mute" | "duck" | "replace";
+};
+```
+
+- Использовать `<OffthreadVideo>` (не `<Video>`) — декодирование off-thread
+- Docker может потребовать увеличение памяти: 4GB → 6-8GB
+- Горизонтальное масштабирование: N контейнеров на одной BullMQ очереди
+
+### Pre-existing bug
+
+`remotion_service/src/themes/default.css:23` — CSS `transition: transform 0.1s ease;` на `.word`. Это browser timer, не Remotion frame clock. В CSS theme mode анимация scale на `.current-word` рендерится непредсказуемо. Inline style mode (с `styleConfig`) не затронут — это основной продакшн-путь.
+
+---
+
+## 11. Продуктовая стратегия и монетизация
+
+### Критическая находка: нулевая инфраструктура монетизации
+
+В кодовой базе **нет**:
+- Поля `plan` / `subscription` в User модели
+- Трекинга использования (минуты рендера, транскрипции)
+- Квот и лимитов
+- Интеграции с платёжными системами
+- Pricing page / upgrade modal
+
+Это **блокер** для любых платных фич.
+
+### Рекомендуемая тарифная сетка
+
+| | Free | Starter ($15/мес) | Pro ($29/мес) | Agency ($79/мес) |
+|---|---|---|---|---|
+| Минуты обработки | 30/мес | 150/мес | 400/мес | 1,200/мес |
+| Транскрипция | Whisper base | Все движки | Все движки | + приоритет |
+| Стили субтитров | 3 базовых | 10 | Все | + кастомный бренд |
+| Клипы с видео | Preview only | 5/видео | Безлимит | Безлимит |
+| Chapters | Да (бесплатно) | Да | Да | Да |
+| Качество экспорта | 720p + watermark | 1080p | 4K | 4K |
+| Highlights engine | Transcript-based | Gemini Flash | TwelveLabs | TwelveLabs + analytics |
+| API доступ | Нет | Нет | Нет | Да |
+| Команда | 1 | 1 | 1 | 5 |
+
+### Unit economics
+
+**Стоимость за минуту обработки:**
+
+| Компонент | $/мин |
+|-----------|-------|
+| TwelveLabs indexing | $0.042 |
+| TwelveLabs infrastructure | $0.0015/мес |
+| TwelveLabs search | ~$0.004 |
+| Whisper STT (self-hosted) | ~$0.0005 |
+| Remotion render (clip) | ~$0.02 |
+| S3 storage (amortized) | ~$0.001 |
+| **С TwelveLabs** | **~$0.07** |
+| **Без TwelveLabs (Gemini)** | **~$0.03** |
+
+**Маржинальность по тарифам:**
+
+| Тариф | Revenue | Avg usage | Cost (с TwelveLabs) | Gross Margin |
+|-------|---------|-----------|--------------------|--------------|
+| Starter $15 | $15 | ~80 мин | $5.60 | **63%** |
+| Pro $29 | $29 | ~200 мин | $14.00 | **52%** |
+| Agency $79 | $79 | ~600 мин | $42.00 | **47%** |
+
+### Free tier: TwelveLabs НЕ использовать
+
+Free tier должен использовать **transcript-based highlights** (анализ энергии + ключевых слов из транскрипции) — почти нулевая стоимость. TwelveLabs — только для платных тарифов.
+
+10,000 free users × $2.10/мес TwelveLabs = $21,000/мес. Без TwelveLabs = ~$900/мес.
+
+### Конкурентное позиционирование
+
+| Инструмент | За ~150 мин/мес + субтитры + клипы | Coffee Project эквивалент |
+|------------|-----------------------------------|--------------------------|
+| OpusClip Starter | $15/мес (клипы, без субтитров) | $15/мес (субтитры + клипы) |
+| Vizard Creator | $14.50-30/мес | $15/мес (лучше субтитры) |
+| Descript Hobbyist | $24/мес (полный редактор) | $15/мес (focused workflow) |
+| Reap | $9.99/мес | $15/мес (больше обработки) |
+
+### Русский рынок
+
+- **Нет локальных конкурентов** в AI video clipping
+- Западные инструменты: проблемы с оплатой (Stripe недоступен)
+- Платёжные системы: ЮKassa, CloudPayments, Тинькофф
+- Цены: ₽990/мес (Starter), ₽1,990/мес (Pro) — на 30-50% ниже USD
+- Каналы: VK, Telegram, YouTube (через VPN)
+
+---
+
+## 12. Сводная таблица стоимости
+
+### Расчёт для 100 часов видео/мес (обновлённый)
+
+| Стек | $/мес | Что получаем |
+|------|-------|-------------|
+| **Gemini 2.5 Flash** (highlights + chapters) | **~$36** | Highlight detection + chapters. Без search |
+| **TwelveLabs** (index + infra + analyze + search) | ~$389 | Полный video understanding + semantic search |
+| **Gemini Flash + TwelveLabs search** (гибрид) | ~$180 | Flash для анализа, TL для поиска по библиотеке |
+| **DeepInfra Whisper** (STT draft) | ~$6 | Черновая транскрипция |
+| **ElevenLabs Scribe** (STT prod) | ~$40 | Продакшн транскрипция |
+| **Pexels API** (B-Roll search) | **$0** | Поиск стокового видео |
+| **Google Video Intelligence** (labels + shots) | ~$450-600 | Метаданные, без highlights |
+
+### Рекомендуемый стек по фазам
+
+| Фаза | Стек | $/мес (100 часов) |
+|------|------|-------------------|
+| **MVP** | Gemini Flash + DeepInfra Whisper + Pexels | **~$42** |
+| **Growth** | Gemini Flash + Scribe v2 + TwelveLabs search | **~$220** |
+| **Scale** | TwelveLabs full + Scribe v2 + Pexels + Runway | **~$470** |
+
+---
+
+## 13. Рекомендации и дорожная карта
+
+### Приоритеты (RICE-скоринг от Product Lead)
+
+| Приоритет | Фича | Движок | Effort (dev-weeks) | $/мес (100 users) |
+|-----------|-------|--------|--------------------|--------------------|
+| **P0** | Upgrade STT → Scribe v2 | ElevenLabs API | 2-3 дня | $40-80 |
+| **P0** | Draft STT tier | Whisper v3-turbo (DeepInfra) | 2-3 дня | $6-12 |
+| **P0** | Монетизация (планы, квоты, биллинг) | Stripe + ЮKassa | 4-6 недель | — |
+| **P1** | Highlight detection MVP | Gemini 2.5 Flash | 1 неделя | $5-15 |
+| **P1** | Shorts rendering | FFmpeg + Remotion ShortVideo | 2-3 недели | — |
+| **P2** | Chapter generation | Gemini 2.5 Flash | 1 неделя | $5 |
+| **P2** | B-Roll suggestions (stock) | Pexels API + Gemini Flash | 2 недели | $5 + $0 |
+| **P3** | Premium highlights | TwelveLabs Pegasus 1.2 | 1 неделя | $50-200 |
+| **P3** | Semantic video search | TwelveLabs Marengo 3.0 | 2 недели | $20-50 |
+| **P4** | AI-generated B-Roll | Runway Gen-4 API | 1 неделя | Variable |
+
+### Фазы реализации
+
+**Pre-Phase: Монетизация (4-6 недель, параллельно с Phase 1)**
+- `plan`, `plan_expires_at`, `usage_minutes_current/limit` в User модели
+- Usage tracking middleware
+- Quota enforcement в service layer
+- Stripe Checkout + ЮKassa
+- Pricing page + upgrade modal
+
+**Phase 1: «Clips» — Highlights + Smart Clipping (8-10 недель)**
+- `video_intelligence` модуль
+- Gemini Flash интеграция для highlight detection
+- Shorts rendering (ShortVideo composition + FFmpeg pre-cut)
+- Субтитры на клипах (существующие стили)
+- Free tier: transcript-based highlights (preview only, без экспорта)
+- Paid: Gemini Flash highlights + экспорт клипов
+
+**Phase 2: Chapters + B-Roll suggestions (4-6 недель)**
+- Chapter generation через Gemini Flash
+- Chapter overlay в Remotion
+- YouTube chapters metadata export
+- Pexels API для B-Roll suggestions
+- Chapters — бесплатно (activation feature)
+
+**Phase 3: Premium Video Intelligence (future)**
+- TwelveLabs для premium highlight detection
+- Semantic video search (enterprise)
+- Prompt-first clipping
+- Batch processing
+
+---
+
+## 14. Красные флаги в текущем коде
+
+Обнаружено агентами при анализе кодовой базы:
+
+### Backend
+
+1. **Whisper default model = `tiny`** (`schemas.py:122`, `service.py:325`). Минимум `base` или `small` для приемлемого качества.
+
+2. **Нет `time_limit` на Dramatiq actor** (`@dramatiq.actor(max_retries=0)`, `service.py:603`). Corrupted файл может заставить воркер висеть бесконечно. Добавить `time_limit=1800000` (30 мин).
+
+3. **Google Speech V1 API**. V2 API имеет модель Chirp — значительно лучше для мультиязычного контента.
+
+4. **Нет кэширования транскрипций**. Actor не проверяет, существует ли транскрипция для того же файла + движка + модели + языка. Повторная транскрипция = потеря денег.
+
+5. **Transcription router обходит service layer** (`transcription/router.py:30-38`) — прямой вызов `TranscriptionRepository` из router. Нарушает паттерн Router → Service → Repository.
+
+6. **Нет пагинации** на `list_all_transcriptions` — возвращает неограниченный список.
+
+7. **Inline error strings** (`transcription/router.py:65`: `detail="Не найдено"`) — нет `ERROR_` константы.
+
+8. **`tasks/service.py` уже 1400+ строк** — новые actors должны делегировать в `video_intelligence/service.py`.
+
+### Remotion
+
+9. **CSS `transition` в `default.css:23`** — `transition: transform 0.1s ease;` на `.word` класс. Browser timer, не Remotion frame clock. Непредсказуемый рендеринг в CSS theme mode.
+
+10. **`<Video>` вместо `<OffthreadVideo>`** — для B-Roll с множественными видеоисточниками нужен `<OffthreadVideo>` (декодирование off-thread).
+
+11. **Docker лимиты**: 2 CPU, 4GB RAM, `MAX_CONCURRENT_RENDERS=2`. Shorts batch + B-Roll потребуют увеличения до 6-8GB.
+
+---
+
+## 15. Источники
+
+### STT
+- [Artificial Analysis STT Leaderboard](https://artificialanalysis.ai/speech-to-text)
+- [ElevenLabs Scribe v2](https://elevenlabs.io/blog/introducing-scribe-v2)
+- [ElevenLabs Scribe v2 Realtime](https://elevenlabs.io/blog/scribe-v2-realtime-in-elevenlabs-agents)
+- [ElevenLabs API Pricing](https://elevenlabs.io/pricing/api)
+- [Deepgram Nova-3 Introduction](https://deepgram.com/learn/introducing-nova-3-speech-to-text-api)
+- [Deepgram Nova-3 Multilingual WER](https://deepgram.com/learn/nova-3-multilingual-major-wer-improvements-across-languages)
+- [Deepgram Models & Languages](https://developers.deepgram.com/docs/models-languages-overview)
+- [Deepgram Pricing](https://deepgram.com/pricing)
+- [Whisper large-v3-turbo (HuggingFace)](https://huggingface.co/openai/whisper-large-v3-turbo)
+- [Whisper large-v3-russian (fine-tuned)](https://huggingface.co/antony66/whisper-large-v3-russian)
+- [DeepInfra Whisper API](https://deepinfra.com/openai/whisper-large-v3-turbo/api)
+
+### Video Intelligence
+- [TwelveLabs Pricing](https://www.twelvelabs.io/pricing)
+- [TwelveLabs Docs](https://docs.twelvelabs.io)
+- [TwelveLabs Marengo 3.0](https://www.twelvelabs.io/blog/marengo-3-0)
+- [TwelveLabs Pegasus 1.2](https://www.twelvelabs.io/blog/introducing-pegasus-1-2)
+- [TwelveLabs Video-to-Text Arena](https://www.twelvelabs.io/blog/video-to-text-arena)
+- [TwelveLabs Developer Experience (GitHub)](https://github.com/twelvelabs-io/twelvelabs-developer-experience)
+- [Gemini 2.5 Video Understanding](https://developers.googleblog.com/en/gemini-2-5-video-understanding/)
+- [Gemini API Pricing](https://ai.google.dev/gemini-api/docs/pricing)
+- [GPT-4.1 Multimodal](https://blog.roboflow.com/gpt-4-1-multimodal/)
+- [Google Video Intelligence API](https://cloud.google.com/video-intelligence)
+
+### Clipping Platforms
+- [OpusClip API](https://help.opus.pro/api-reference/overview)
+- [OpusClip Pricing](https://www.opus.pro/pricing)
+- [Reap.video API](https://docs.reap.video/api-reference/1_introduction)
+- [Reap.video MCP](https://reap.video/mcp)
+- [Vizard API Docs](https://docs.vizard.ai/docs/introduction)
+- [Descript Pricing](https://www.descript.com/pricing)
+- [CapCut Pricing](https://www.gamsgo.com/blog/capcut-pricing)
+
+### B-Roll Generation
+- [Runway API Pricing](https://docs.dev.runwayml.com/guides/pricing/)
+- [Pika 2.2 on fal.ai](https://fal.ai/models/fal-ai/pika/v2.2/text-to-video)
+- [Kling AI Pricing](https://klingai.com/global/dev/pricing)
+- [Best Text-to-Video APIs 2026](https://wavespeed.ai/blog/posts/best-text-to-video-api-2026/)
+- [Pexels Free API](https://www.pexels.com/api/)
+
+### Market & Competition
+- [AI Video Generator Market (Grand View Research)](https://www.grandviewresearch.com/industry-analysis/ai-video-generator-market-report)
+- [Descript vs Veed vs Kapwing Growth (YipitData)](https://www.yipitdata.com/resources/blog/descript-vs-veed-vs-kapwing-ai-video-tools)
+- [OpusClip Highlight Accuracy](https://www.opus.pro/blog/ai-tools-for-precise-video-highlight-search-accuracy)
+- [SaaS Freemium Conversion Benchmarks](https://firstpagesage.com/seo-blog/saas-freemium-conversion-rates/)
+
+---
+
+*Документ подготовлен 8 параллельными исследовательскими агентами: 4 внешних ресёрчера (TwelveLabs repo, TwelveLabs pricing, Other Services, Coffee Architecture) + 4 доменных специалиста (ML/AI Engineer, Backend Architect, Product Lead, Remotion Engineer).*