Video Agent Runtime

Агент-ориентированный видеомонтаж, построенный на устойчивых планах, версионируемых результатах и детерминированном рендеринге.

Редактируйте видео как структурированные данные — а не как непрозрачные shell-команды.

Быстрый старт · Агент и MCP · Речь и голос · Мобильный хост · Документация · Бенчмарки

Что это?

Video Agent Runtime — это headless-движок редактирования для агентов, таких как Claude Code, Codex или любой MCP-совместимый клиент.

Вместо того чтобы позволять модели напрямую формировать команды FFmpeg, он превращает медиа в устойчивые данные проекта:

Transcript → EditingStrategy → EditPlan / EditPatch → Timeline → Version → Preview → Approval → Export

Модель решает, что должно измениться. Рантайм проверяет, допустимо ли это изменение, применяет его транзакционно, рендерит результат и сохраняет каждую мутацию проверяемой и обратимой.

Он спроектирован в первую очередь для видео с говорящей головой, интервью, подкастов, лекций, записи экрана и рабочих процессов long-form-to-short-form.

[!NOTE] Это не десктопный NLE и не пытается воспроизвести Premiere или CapCut. Основной интерфейс — это агент, CLI, MCP-клиент или мобильный хост, ориентированный на ревью.

Related MCP server: ai-video-studio-agent

Как это работает

flowchart LR
    A[Source video] --> B[ASR + visual evidence]
    B --> C[Transcript / Timeline context]
    C --> D[LLM proposes EditingStrategy]
    D --> E{User approves?}
    E -- no --> D
    E -- yes --> F[Structured EditPlan]
    F --> G[Validate + Diff + Apply]
    G --> H[Immutable Version]
    H --> I[Preview render]
    I --> J{Review}
    J -- feedback --> K[EditPatch or Replan]
    K --> G
    J -- approve --> L[Final export]

Типичное взаимодействие выглядит так:

Import interview.mp4
↓
"剪成一分钟，开头抓人，删掉废话"
↓
Agent proposes a hook-first strategy
↓
User approves
↓
Runtime validates and applies an EditPlan
↓
Preview
↓
"前 20 秒还是太慢"
↓
Minimal EditPatch → new Version → new preview
↓
Final approval → export

Ключевые возможности

Речь и голос

Речь — это полноценная подсистема редактирования, а не дополнение для субтитров. ASR создаёт семантический таймлайн, используемый редактором; выходные данные TTS и VoiceProfile становятся явными ассетами проекта и клипами таймлайна.

ASR

TTS и голосовая идентичность

Клонирование голоса никогда не выполняется автоматически. Клонированный VoiceProfile требует явных доказательств авторизации, проверенного по качеству референса и — где провайдер это поддерживает — точного диапазона референса на основе транскрипта. Многоговорящие медиа не угадываются молча.

Код моделей, веса, голосовые ассеты и хостинговые API могут иметь разные лицензии или коммерческие условия. См. исследование речевых моделей и голосовую идентичность перед развёртыванием конфигурации провайдера.

Агент и MCP

Все публичные поверхности — это тонкие адаптеры поверх одного и того же VideoAgentCore; они не поддерживают отдельные модели проекта или таймлайна.

Подключение Claude Code / Codex

Соберите репозиторий, затем укажите MCP-совместимому клиенту на stdio-сервер:

npm install
npm run build

mcp.example.json содержит минимальную форму конфигурации. Секреты провайдеров читаются из окружения или защищённого хранилища хоста и никогда не записываются в JSON проекта.

Быстрый старт

Требования

• Node.js 22+

• FFmpeg / FFprobe для рендеринга реальных медиа

• Опционально: окружение Python для локальных речевых моделей

Установка и проверка

npm install
npm run typecheck
npm test
npm run build
npm run smoke:mcp
npm run demo

npm run demo создаёт синтетические исходные медиа локально и прогоняет реальный рабочий процесс проекта через транскрипт → стратегию → версии → превью → патч обратной связи → озвучку → финальный экспорт FFmpeg.

Проверьте текущую машину без платного вызова модели:

npm run cli -- doctor

Настройка провайдеров

Скопируйте соответствующие значения из .env.example в ваше окружение.

# Workspace
VIDEO_AGENT_WORKSPACE=./video-projects

# Planner
VIDEO_AGENT_PLANNER=openai
OPENAI_MODEL=gpt-5.4-mini
OPENAI_API_KEY=...

# Local ASR example
VIDEO_AGENT_ASR=qwen3-asr
VIDEO_AGENT_ASR_MODEL=Qwen/Qwen3-ASR-0.6B

# Local TTS / voice example
VIDEO_AGENT_TTS=qwen3-tts
VIDEO_AGENT_TTS_MODEL=Qwen/Qwen3-TTS-12Hz-0.6B-Base
VIDEO_AGENT_PYTHON=python

Другие поддерживаемые варианты задокументированы непосредственно в .env.example.

Валидация с реальными провайдерами

Обычный CI намеренно не скачивает большие речевые модели и не использует платные учётные данные. Реальные провайдеры проверяются через явный приёмочный харнесс:

VIDEO_AGENT_REAL_ACCEPTANCE=true \
VIDEO_AGENT_ASR=qwen3-asr \
VIDEO_AGENT_PLANNER=openai \
VIDEO_AGENT_TTS=qwen3-tts \
OPENAI_API_KEY=... \
npm run eval:speech-real

Харнесс записывает реальную задержку этапов, real-time factor ASR/TTS, метаданные провайдера/модели, RSS Node-контроллера и, при наличии, приблизительную память GPU. Приёмка авторизованного клонирования голоса должна включаться отдельно и не может молча выполняться на произвольном спикере.

После нескольких запусков агрегируйте сопоставимые результаты с помощью:

npm run benchmark:speech-summary

См. приёмку реальной речи, бенчмарки и исследование речевых моделей.

Мобильный хост

Мобильная цель спроектирована вокруг локальной, без единого сервера приложений, архитектуры:

Mobile App
  ├── VideoAgentCore
  ├── durable ProjectRepository
  ├── Workflow / Job Queue
  ├── Timeline / EditPatch / Version
  ├── native media adapters
  └── direct BYOK provider access when configured

Исходные медиа по умолчанию остаются на устройстве; удалённые провайдеры получают только одобренный ContextPack/доказательства, необходимые для инференса. Учётные данные API ссылаются через защищённое хранилище хоста, а не через JSON проекта.

[!WARNING] Текущая реализация iOS/Android — это всё ещё нативный прототип хоста на уровне исходного кода. Контракты TypeScript/mobile проверяются в CI, но нативные сборки Xcode/Gradle, корректность медиа на физических устройствах, тепловое поведение и надёжность фонового экспорта всё ещё требуют задокументированного прохода валидации на устройствах.

Начните с docs/mobile/README.md и статуса нативного хоста.

Архитектура

                 Agent / CLI / MCP / Mobile
                          │
                          ▼
                    VideoAgentCore
                          │
        ┌─────────────────┼──────────────────┐
        ▼                 ▼                  ▼
     Workflow          ProjectStore       Job Queue
        │                 │                  │
        └──────────┬──────┴──────────┬──────┘
                   ▼                 ▼
              Edit / Timeline    Provider contracts
                   │                 │
             Version / Diff     ASR / LLM / TTS
                   │                 │
                   └────────┬────────┘
                            ▼
                         Renderer
                            │
                         Preview
                            │
                      Review / Export

Главный инвариант прост: рантайм владеет состоянием; модели предлагают структурированные изменения.

О границах пакетов, структуре персистентности и семантике восстановления читайте в architecture.md.

Документация и разработка

README — это точка входа в продукт. Технические детали находятся в docs/.

Статус проекта

Node-рантайм — это проверенный основной путь: CLI, MCP, устойчивое состояние проекта, рендеринг FFmpeg, задачи, детерминированная оценка, адаптеры речевых провайдеров и инструменты приёмки реальных провайдеров реализованы и покрыты CI там, где они не требуют внешних весов моделей или платных учётных данных.

Реальное качество локальной модели, задержка, VRAM и поведение хостируемой модели должны по-прежнему измеряться на целевой машине через опциональный acceptance harness; CI не делает вид, что эти запуски происходили.

Мобильный хост остаётся прототипом на уровне исходного кода, пока не будут завершены нативная компиляция и валидация на реальном устройстве.

Принципы безопасности

• Агенты никогда не получают произвольное выполнение shell-команд через API редактирования.

• Сырые строки FFmpeg не являются авторитетным состоянием редактирования.

• Ключи API никогда не сохраняются в JSON проекта, записях ProviderCall или отчётах бенчмарков.

• Исходный медиафайл остаётся локальным, если рабочий процесс явно не разрешает удалённые доказательства.

• Клонирование голоса требует явной авторизации и подтверждения происхождения.

• Неподдерживаемые возможности рендерера/провайдера завершаются явной ошибкой, а не деградируют молча.

Полные границы см. в docs/security.md.

Лицензия

MIT. См. LICENSE.