Video Agent Runtime

エージェントネイティブな動画編集。永続的なプラン、レビュー可能なバージョン、決定的なレンダリングを基盤に構築。

動画を不透明なシェルコマンドではなく、構造化されたデータとして編集する。

クイックスタート · エージェント & MCP · 音声 & ボイス · モバイル · ドキュメント · ベンチマーク

これは何か？

Video Agent Runtime は、Claude Code、Codex、その他 MCP 対応クライアントなどのエージェント向けのヘッドレス編集エンジンです。

モデルに直接 FFmpeg コマンドを書かせる代わりに、メディアを永続的なプロジェクトデータに変換します：

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

モデルは何を変更すべきかを決定します。ランタイムはその変更が許可されているかを検証し、トランザクション的に適用し、結果をレンダリングし、すべての変更をレビュー可能かつ元に戻せる状態に保ちます。

主に、トーキングヘッド動画、インタビュー、ポッドキャスト、講義、画面収録、ロングフォームからショートフォームへの変換ワークフロー向けに設計されています。

[!NOTE] これはデスクトップ NLE ではなく、Premiere や CapCut を再現しようとするものではありません。主要なインターフェースは、エージェント、CLI、MCP クライアント、またはレビュー指向のモバイルホストです。

Related MCP server: video-editor

仕組み

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

このハーネスは、実際のステージレイテンシ、ASR/TTS リアルタイムファクター、プロバイダー/モデルのメタデータ、Node コントローラーの RSS、可能な場合は大まかな 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/モバイル契約は 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、およびホステッドモデルの動作は、オプトインの受け入れハーネスを通じてターゲットマシン上で測定する必要があります。CIはそれらの実行が行われたふりをしません。

モバイルホストは、ネイティブコンパイルと実機検証が完了するまで、ソースレベルのプロトタイプのままです。

セキュリティ原則

• エージェントは編集APIを通じて任意のシェル実行を受け取ることはありません。

• 生のFFmpeg文字列は、権威ある編集状態ではありません。

• APIキーは、プロジェクトJSON、ProviderCallレコード、またはベンチマークレポートに永続化されることはありません。

• ワークフローが明示的にリモートエビデンスを許可しない限り、ソースメディアはローカルに留まります。

• 音声クローニングには明示的な承認と来歴（プロビナンス）が必要です。

• サポートされていないレンダラー/プロバイダーの機能は、静かに劣化するのではなく、明示的に失敗します。

完全な境界については、docs/security.mdを参照してください。

ライセンス

MIT。 LICENSEを参照してください。