Skip to main content
Glama
deenesjakoruzh
YansIlinta

video-agent-mcp

by YansIlinta
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Video Agent Runtime

面向智能体的原生视频编辑，构建于持久化计划、可审查版本与确定性渲染之上。

将视频编辑视为结构化数据——而非不透明的 shell 命令。

CI License: MIT Node.js TypeScript

快速开始 · 智能体与 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: 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

核心能力

领域

已实现内容

持久化编辑模型

整数微秒级 Timeline、一等公民 EditPlan 与 EditPatch、不可变 Versions、原子持久化与按项目锁定

审批工作流

策略提案 → 审批 → 计划验证 → 预览 → 反馈 → 诊断/重新规划 → 最终审批 → 导出

结构化规划

JSON-Schema 约束的 LLM 输出、独立 Zod 验证、修复重试、提供商调用溯源与取消

以转录为先的编辑

带时间戳的词/片段、说话人、对齐溯源、转录搜索与 LLM 可读的时间线上下文

语音与声音

本地与托管的 ASR/TTS、生成的旁白、时长适配、经授权的 VoiceProfile 克隆/设计、配音与溯源

视觉证据

按需检查镜头/关键帧，而非将整个源视频上传给模型

渲染

能力契约背后的 FFmpeg 预览/最终渲染器；不涉及智能体编写的 shell 字符串

持久化任务

有界并发、进度事件、重试分类、取消、幂等性与重启恢复

评估

确定性 CI 评估，外加可选的真实提供商 ASR/LLM/TTS/语音克隆验收与基准聚合

语音与声音

语音是一等编辑子系统，而非字幕附加功能。ASR 生成编辑器使用的语义时间线；TTS 与 VoiceProfile 输出成为显式的项目资产和时间线片段。

ASR

提供商 / 运行时

执行方式

最佳适用场景

备注

faster-whisper

本地

成熟的通用本地 ASR

轻量本地基线

Qwen3-ASR

本地

中文、多语言及本地高质量转录

使用时间戳对齐实现编辑安全输出

OpenAI transcription

托管 API

BYOK 云端转录

根据模型支持带说话人分离的片段模式或 Whisper 词级时间戳

WhisperX

本地可选增强

对齐 / 说话人分离

将对齐后的词与说话人区间融合回规范 Transcript

TTS 与声音身份

提供商 / 运行时

执行方式

能力

Kokoro

本地

轻量预设 TTS

Qwen3-TTS

本地

TTS、声音设计、经授权的零样本声音克隆、跨语言复用

OpenAI speech

托管 API

托管 TTS / 提供商声音

声音克隆永远不会自动进行。克隆的 VoiceProfile 需要明确的授权证据、经过质量检查的参考，以及（在提供商支持的情况下）精确的、基于转录的参考区间。多说话人媒体不会被静默猜测。

模型代码、权重、声音资产与托管 API 可能具有不同的许可证或商业条款。在部署提供商配置之前，请参阅语音模型研究与声音身份。

智能体与 MCP

所有公开表面都是同一 VideoAgentCore 之上的薄适配器；它们不维护独立的项目或时间线模型。

表面

入口点

使用场景

CLI

video-agent

本地开发、脚本编写、调试与显式工作流控制

项目 MCP

video-agent-mcp

面向 Claude Code、Codex 及其他 MCP 客户端的完整项目级编辑工具表面

语音 MCP

video-agent-speech-mcp

轻量 ASR → 结构化 LLM → TTS 工作流，无需构建完整编辑图

智能体技能

skills/video-editing/SKILL.md

推荐的智能体工作流、审查规则与安全边界

控制 API

docs/control-api.md

窄范围、bearer 认证的本地 HTTP 控制表面

移动端宿主

docs/mobile/

使用相同领域/运行时契约的零服务器原生宿主原型

连接 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/ 下。

主题

文档

架构与持久化状态

docs/architecture.md

安全与密钥处理

docs/security.md

语音 MCP

docs/speech-mcp.md

语音模型格局

docs/speech-models-2026.md

声音身份与克隆

docs/voice-identity.md

真实提供商验收

docs/real-speech-acceptance.md

基准测试

docs/benchmarks.md

移动端宿主

docs/mobile/README.md

先例 / 上游研究

docs/upstream-study.md

发布历史

CHANGELOG.md

项目状态

Node 运行时是已验证的主要路径：CLI、MCP、持久化项目状态、FFmpeg 渲染、任务、确定性评估、语音提供商适配器与真实提供商验收工具均已实现，并在不需要外部模型权重或付费凭据的范围内由 CI 覆盖。

真实的本地模型质量、延迟、VRAM 和托管模型行为仍必须通过可选验收测试框架在目标机器上测量；CI 不会假装这些运行已经发生。

在原生编译和真机验证完成之前，移动端宿主仍保持为源码级原型。

安全原则

  • 代理永远不会通过编辑 API 获得任意 shell 执行权限。

  • 原始 FFmpeg 字符串不是权威的编辑状态。

  • API 密钥永远不会持久化到项目 JSON、ProviderCall 记录或基准测试报告中。

  • 源媒体保持本地状态，除非工作流明确授权远程证据。

  • 语音克隆需要明确的授权和来源证明。

  • 不支持的渲染器/提供程序能力会显式失败，而不是静默降级。

完整边界请参阅 docs/security.md。

许可证

MIT。参见 LICENSE。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers