ai-promo-video

# AI Promo Video **AI 导演。MCP 执行。Revideo 和 FFmpeg 交付视频。** AI Promo Video 是一个开源的、无界面的专业宣传视频制作系统。没有图形编辑器、托管服务、本地 AI 模型或隐藏订阅。用户安装该项目后，他们已经在使用的 Codex、Claude Code 或 Cursor 中的 AI 将获得规划、捕捉、动画、渲染、审查和修订整个视频所需的工具和指令。 这不是一个幻灯片生成器。每个新制作都是一条可编辑的 Revideo 和 TypeScript 组合。AI 在广泛的词汇表中搜索可重复使用的动作系统，只组合适合当前故事的内容，并在需要时在同一场景中编写自定义代码。这使得视角相机、缩放和跟踪、接口逐元素组装、编排光标、动态字体、遮罩、滤镜、粒子、SVG、程序形状、图像、视频、着色器和 Three.js 场景成为可能，而不会将结果锁定到模板中。FFmpeg 处理编辑、音频分析和混音、检查和增量修订。 ## 查看它已经可以做的 下面的视频直接在 GitHub 上播放。完整分辨率的最终 MP4 文件也与可编辑的示例一起版本控制。 ### SignalNest — SaaS 动作基准 · 56 秒 https://github.com/user-attachments/assets/ca33b482-2330-46d2-a270-008b0d717a9a 一个完全程序化的合成，旨在测试精致的 SaaS 启动的视觉语言：每个单词和每个字母的动作、动画渐变、擦除和重写效果、文本推动其他文本、基于字体的遮罩、粒子、轨道系统、视角 UI、场景组装的卡片、自动化轨迹和最终的 CTA。音乐：“Synth/bass Short or Intro” by griffon_designs，CC0 1.0。 ### QANode — 产品组装和相机运动 · 9.6 秒 https://github.com/user-attachments/assets/09ed9971-f1de-4b95-8300-4b29ab71a49c 界面一开始是空的。相机锁定在左侧导航上，当每个菜单项被创建时，跟随 **Scenarios** 上的点击，转移焦点，并逐行显示列表。产品屏幕被重建为一个可动画的合成，而不是依赖于转换为截图的刚性过渡。 ### AINDA — 情感故事讲述 · 61 秒 https://github.com/user-attachments/assets/93ade655-8b51-44e9-9218-bf3950bd7ab7 在 SaaS 类别之外进行的测试，旨在证明叙事方向：自由许可的在线视频、音乐驱动的编辑、节奏、氛围、图像处理和情感字体。音乐：“Emotional Original Soundtrack — BETTER LIFE” by Magmi.Soundtracks，CC BY 4.0。完整的媒体署名与项目一起保留。 ## 为什么存在这个项目 录制应用程序只是一种原材料。强大的宣传片还需要故事、层次结构、节奏、相机运动、过渡、场景设计、音乐和通常分布在屏幕录制软件、After Effects 和视频编辑器上的数十个小决定。 该项目将这个问题分为两个部分： - **技能是导演。** 它教会 AI 如何将简报转化为独特的故事和艺术方向，选择要捕捉的内容，发现动作组件而不将其视为模板，比较音乐而不使用默认曲目，并审查自己的作品。 - **MCP 服务器是制作团队。** 它提供渐进式上下文帮助以及用于导航产品、记录产品、搜索动作库和免费媒体、分析音乐、编写场景、渲染、编辑、提取审查帧、替换受损区间和清理成品制作中可丢弃的工件的确定性操作。 项目中不捆绑任何 AI 模型。Codex、Claude 或 Cursor 使用用户已经选择的模型。对于无法发现文件系统技能的客户端，MCP 服务器通过提示和资源公开相同的导演指南。 ## 从请求到成品 MP4 当用户请求“为此 SaaS 创建 30 秒的宣传片”时，AI 遵循此制作周期： 1. 了解产品、受众、承诺、时长、格式和参考。 2. 检查实际应用程序并决定要记录哪些流程。 3. 捕捉干净的截图或产品视频，包括用户配置的身份验证会话。 4. 编写音乐意图，然后搜索本地或在线源的音乐、视频和资产，并附带已知的许可证。除非明确请求，否则捆绑的曲目是可选的，不会被包含。 5. 为此制作编写故事、艺术方向、节拍图、音乐强调和相机逻辑，而不是复制固定的场景弧线。 6. 搜索组件词汇，加载所选工具/组件/过渡的详细帮助，并从这些基元创建实际的 Revideo/TypeScript 合成。它永远不会渲染通用模板来替换。 7. 以 24-60 FPS 和高达 4K 的分辨率渲染 H.264/AAC 视频。 8. 从完整电影中提取帧，并在每个过渡处提取帧，以便 AI 可以检查自己的输出。 9. 修复视觉异常、时间、字体、相机运动或合成。如果问题被隔离，它会重新渲染并仅替换该区间。 10. 保留可编辑的项目、所需的渲染输入、署名和批准的交付成果；生成的审查、预览、缓存和中间渲染会在制作过程中删除。 AI 在不将生成变成黑盒的情况下获得自主权：场景保持可读代码，媒体保留归属声明，每个渲染都可以重现。 ## 安装 要求：macOS、Linux 或 Windows 上的 Node.js 20 或更高版本。 ### 快速安装 使用一条命令为 Codex、Claude Code、Claude Desktop 和 Cursor 安装 AI Promo Video： ```bash npx --yes @apptrix/ai-promo-video install ``` 安装程序下载稳定的本地运行时，安装生产依赖项和 Playwright Chromium，安装 `create-ai-promo-video` 技能，并注册 `ai-promo-video` MCP 服务器在所有四个客户端中。现有的无关技能和 MCP 服务器将被保留。 Claude 有两个本地表面，具有不同的扩展机制： - Claude Code，包括 Claude 应用的 **Code** 标签，接收 `~/.claude/skills` 中的文件系统技能和用户范围的 MCP 服务器。通过 `/create-ai-promo-video` 和 `claude mcp get ai-promo-video` 验证它。 - Claude Desktop 的 **Home** 聊天不读取文件系统技能。它通过本地 MCP 服务器接收相同的导演指南作为服务器指令、`create-ai-promo-video` 提示、`ai-promo://director-guide` 资源和 `load_director_guide` 工具适用于仅公开工具的客户端。在安装后完全退出并重新打开 Claude Desktop。 常规的 claude.ai 网络对话仍然使用单独上传的云技能，不读取本地文件或本地 MCP 配置。 重启代理客户端后，请求它创建一个专业的宣传视频。 仅为选定的客户端安装或预览计划的更改： ```bash npx --yes @apptrix/ai-promo-video install --clients codex,cursor npx --yes @apptrix/ai-promo-video install --clients claude npx --yes @apptrix/ai-promo-video install --clients claude-code npx --yes @apptrix/ai-promo-video install --clients claude-desktop npx --yes @apptrix/ai-promo-video install --dry-run ``` `claude` 别名配置了 Claude Code 和 Claude Desktop。 #### Windows 和 WSL 从原生 Windows PowerShell，使用 `npx.cmd` 避免 PowerShell 执行策略冲突与 `npx.ps1`： ```powershell npx.cmd --yes @apptrix/ai-promo-video install ``` 在与代理客户端相同的环境中运行安装程序。原生 Windows 客户端使用 `%USERPROFILE%` 和 `%LOCALAPPDATA%`；在 WSL 中启动的安装程序使用 Linux 主目录，并配置在 WSL 中运行的客户端。WSL 安装不会配置原生 Windows Codex、Claude 或 Cursor，反之亦然。 ### 从存储库安装 ```bash git clone https://github.com/MendesCorporation/ai-promo-video.git cd ai-promo-video npm run setup node plugins/ai-promo-video/dist/install.js install ``` `setup` 安装依赖项，应用固定的和幂等的 Revideo 0.11 着色器上下文兼容性补丁，安装 Playwright 使用的 Chromium 构建，并编译项目。第二个命令安装稳定的运行时并配置 Codex、Claude Code 和 Cursor。 此路线适用于贡献者和希望在安装前检查或修改引擎的任何人。要直接从检出运行而无需全局安装，请使用下面记录的 CLI 命令。 ### 手动安装技能 技能是一个常规文件夹，可以复制而不运行通用安装程序。从克隆的存储库中，运行仅适用于您的客户端的行： ```bash # Codex — 全局用户技能 mkdir -p "$HOME/.agents/skills" cp -R plugins/ai-promo-video/skills/create-ai-promo-video "$HOME/.agents/skills/" # Claude Code — 全局用户技能 mkdir -p "$HOME/.claude/skills" cp -R plugins/ai-promo-video/skills/create-ai-promo-video "$HOME/.claude/skills/" # Cursor — 全局用户技能 mkdir -p "$HOME/.cursor/skills" cp -R plugins/ai-promo-video/skills/create-ai-promo-video "$HOME/.cursor/skills/" ``` 对于存储库范围的安装，请将相同的目录复制到 `.agents/skills/`（适用于 Codex）、`.claude/skills/`（适用于 Claude Code）或 `.cursor/skills/`（适用于 Cursor），在存储库根目录。 在原生 Windows PowerShell 上，以下命令将技能复制到所有三个用户级发现位置： ```powershell $source = (Resolve-Path "plugins\ai-promo-video\skills\create-ai-promo-video").Path $destinations = @( (Join-Path $HOME ".agents\skills\create-ai-promo-video"), (Join-Path $HOME ".claude\skills\create-ai-promo-video"), (Join-Path $HOME ".cursor\skills\create-ai-promo-video") ) foreach ($destination in $destinations) { New-Item -ItemType Directory -Force (Split-Path $destination) | Out-Null Remove-Item $destination -Recurse -Force -ErrorAction SilentlyContinue Copy-Item $source $destination -Recurse -Force } ``` 这些位置遵循当前的 [Codex 技能](https://learn.chatgpt.com/docs/build-skills)、[Claude Code 技能](https://code.claude.com/docs/en/skills)和 [Cursor Agent 技能](https://cursor.com/docs/skills) 文档。 技能本身提供导演工作流、制作规则和质量控制过程。**它不** 提供捕获、搜索、渲染、编辑或视觉审查工具。要完成视频制作，使用快速安装程序，以便 MCP 服务器也安装。 复制技能后，如果它没有自动出现，请重启客户端。通过 `$create-ai-promo-video` 在 Codex 中显式调用它，在 Claude Code 或 Claude 应用的 Code 标签中通过 `/create-ai-promo-video` 调用，或通过 Cursor 的斜杠命令菜单调用。Claude Desktop Home 需要 MCP 安装，因为它不扫描此文件夹。 ### 安装程序配置的内容 - 在 macOS/Linux 上为 `~/.local/share/ai-promo-video` 或 Windows 上的 `%LOCALAPPDATA%\ai-promo-video` 下的运行时。 - 在 `~/.agents/skills`、`~/.claude/skills` 和 `~/.cursor/skills` 下的 `create-ai-promo-video` 技能。 - Codex、Claude Code、Claude Desktop 和 Cursor 中的 `ai-promo-video` stdio MCP 服务器。 - 生产依赖项和 Playwright Chromium。 在 Windows 上，用户 MCP 文件分别在 `%USERPROFILE%\.codex\config.toml`、 `%USERPROFILE%\.claude.json` 和 `%USERPROFILE%\.cursor\mcp.json` 下解析。Claude Desktop 使用 `%APPDATA%\Claude\claude_desktop_config.json`；Microsoft Store 版本在匹配的 `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude` 目录下检测。 FFmpeg 和 FFprobe 由 npm 依赖项提供，不需要单独的系统安装。 安装工件仅包含运行时、技能、所需资产和清单。演示视频和制作媒体不会由安装程序下载。 ## 如何请求视频 重启客户端后，初始请求可以很简单： ```text 为 http://localhost:3000 处的 SaaS 创建一个 30 秒的电影宣传片。 受众是 QA 领导者，核心承诺是减少检测和重现缺陷之间的时间。 使用产品的视觉身份，记录实际流程，找到自由许可的音乐，并以 1920x1080 的分辨率交付。 ``` 要获得更多控制，请提供： - 产品网址和身份验证说明，不要在提示或 Git 中放置机密信息。 - 受众、问题、承诺和行动号召。 - 时长、长宽比、分辨率和帧率。 - 节奏、相机运动、字体和颜色的参考。 - 授权的本地目录，包含音乐、视频、徽标和截图。 - AI 是否可以搜索在线内容以及哪些许可证是可接受的。 也可以用自然语言请求修订： ```text 在 7 到 11 秒之间，相机感觉是静态的。锁定缩放至左侧菜单，跟随项目组装的项目，然后将焦点滑动到列表。 保留视频的其他部分并检查转换帧，然后交付修订。 ``` AI 可以读取现有的源代码，编辑仅受影响的场景或区间，渲染补丁并替换 MP4 中的该范围。 ## 捕获、媒体和动作功能 - 来自本地或远程应用程序的干净截图和录音。 - AI 控制的点击、表单填写、按键、悬停、选择、滚动、导航和鼠标移动。 - 跨用户授权的本地目录的递归搜索。 - 通过本地文件夹和 Openverse 搜索音乐，包括下载和归属声明，无需默认或备用曲目。 - 通过 Openverse、Wikimedia Commons 和可选的 Pexels 搜索视频。 - 通过 Openverse、Wikimedia Commons 和可选的 Pexels 搜索图像和资产。 - Openverse 和 Wikimedia Commons 无需 API 密钥。Pexels 免费但需要 `PEXELS_API_KEY`。 - 图像、SVG、矢量路径、遮罩、原生 Revideo 线性/径向渐变、滤镜、着色器、粒子、Three.js 和视频剪辑在同一合成内。脚手架包括 `paint.ts` 助手，用于原生坐标和 CSS 角度转换；预飞行拒绝不支持的 CSS `linear-gradient(...)`/`radial-gradient(...)` 画字符串，并在 Chromium 启动前提供上下文帮助。 - 原生景观、肖像和方形合成配置文件，具有自适应阶段、焦点产品裁剪和 TikTok、Instagram Reels 和 YouTube Shorts 的可编辑安全区默认值。垂直输出通过重组而不是缩小景观场景来生成。 - 一个可搜索的动作词汇，涵盖背景、格式、布局、字幕、字体、产品演示、形状、过渡、相机、光标、粒子和效果；每个项目都可以重新样式化、组合或用自定义 TypeScript 替换。 - `transitions.ts` 和 `camera.ts` 中有十个可执行的过渡结构和七个可执行的相机结构，带有向量、重叠、模糊、深度、曲线、目标、边界、视角、确定性种子和定时的可类型化控件。它们是可编辑的起点，而不是模板或约束，AI 可以忽略它们、重写它们、组合它们或编写完全原创的 Revideo、SVG、GLSL 或 Three.js 系统。 - 按块、行、单词或字符的动态字体，包括跟踪、模糊、擦除/重写交换和基于字体的遮罩。 - 来自 SRT、WebVTT、提示 JSON 或精确字时 JSON 的跟随语音字幕，带有跟随字、卡拉 OK、击打、窗口期、说话者和自适应字幕车道系统。仅提示时间戳标记为近似插值，而不是呈现为精确对齐。 - 通过 OpenType.js 和 Flubber 的矢量字形轮廓和 SVG 路径变形；通过 Simplex Noise 的种子流场、吸引、溶解和冲击波；通过 Three.js 后处理可选的选定色调、深度、色差、颗粒和渐晕。 ## MCP 工具 服务器暴露了 37 种工具： - 进阶文档：`help`。无需参数调用以获取紧凑索引，带 `query` 以获取短候选项，或带精确目标，如 `component:liquid-glass-text`、`transition:camera-zoom-through` 或 `tool:render_advanced_video` 以获取参数类型、运行时默认值、校准范围（若可用）、编舞、示例、陷阱、源签名和验证规则。 - 产品：`inspect_saas`、`capture_saas`、`record_saas_flows`。 - 音乐：`list_music`、`generate_music_library`、`search_music`、`download_music`、`analyze_music`、`mix_music`。 - 免费媒体：`search_free_videos`、`download_free_video`、`search_free_assets`、`download_free_asset`。 - 格式和字幕：`list_format_profiles`、`prepare_caption_timing`、`review_caption_timing`。 - 运动合成：`list_motion_capabilities`、`search_motion_components`、`get_motion_component`、`scaffold_advanced_video`、`list_advanced_video_files`、`read_advanced_video_file`、`save_advanced_video_file`、`patch_advanced_video_file`、`render_advanced_video`。 - 编辑：`edit_capture_image`、`edit_video`、`replace_video_range`。 - 旧版 JSON 兼容性：`validate_video_plan`、`render_video`。 - 视觉 QA：`probe_video`、`extract_review_frames`、`create_visual_review_pack`、`read_visual_files`。 - 交付：`clean_delivery_output`。 上下文 `help` 工具保持例行调用的小巧：完整的目录从不自动注入，只有为请求的目标返回确切的文档。`create-ai-promo-video` MCP 提示、`ai-promo://director-guide` 和 `ai-promo://motion-library` 资源，以及十个详细的参考资源，即使在没有原生技能发现的情况下，也使完整的工作流程可用。捕获和审查表作为 MCP 图像内容返回，允许具有视觉能力的模型检查结果。高级渲染通过 MCP 进度和日志通知发布实时阶段和百分比更新。每个渲染都在一个隔离的进程组中运行，因此取消、启动失败、停滞和超时会自动清理其 Chromium 和 Vite 进程。 ## CLI 使用 MCP 中可用的所有内容也可以从终端调用： ```bash # 检查、捕获和记录产品 node plugins/ai-promo-video/dist/cli.js inspect http://localhost:3000 --screenshot ./inspect.png node plugins/ai-promo-video/dist/cli.js capture ./capture.local.json node plugins/ai-promo-video/dist/cli.js record ./capture.local.json # 搜索免费音乐和媒体 node plugins/ai-promo-video/dist/cli.js music:search "focused technology" --provider openverse node plugins/ai-promo-video/dist/cli.js music:analyze ./music/candidate.mp3 --review-dir ./music-review node plugins/ai-promo-video/dist/cli.js video:search --query "software team" --provider all --orientation landscape node plugins/ai-promo-video/dist/cli.js asset:search --query "abstract technology" --provider all --kind image # 创建和渲染无限制运动 node plugins/ai-promo-video/dist/cli.js motion:capabilities node plugins/ai-promo-video/dist/cli.js motion:search --query "camera follows interface assembly" --categories camera,product node plugins/ai-promo-video/dist/cli.js format:list node plugins/ai-promo-video/dist/cli.js advanced:init ./advanced --name "Launch promo" --format portrait --platform tiktok node plugins/ai-promo-video/dist/cli.js advanced:render ./advanced/project.tsx --output ./output/promo.mp4 # 准备跟随语音的字幕并审查其时序 node plugins/ai-promo-video/dist/cli.js caption:prepare ./captions.srt --output ./advanced/caption-timing.json node plugins/ai-promo-video/dist/cli.js caption:review ./advanced/caption-timing.json # 仅渲染和替换修订区间 node plugins/ai-promo-video/dist/cli.js advanced:render ./advanced/project.tsx --output ./output/patch.mp4 --start 4.5 --end 10 node plugins/ai-promo-video/dist/cli.js video:replace-range ./replace.json # 视觉检查和审查输出 node plugins/ai-promo-video/dist/cli.js probe ./output/promo.mp4 node plugins/ai-promo-video/dist/cli.js review ./output/promo.mp4 --output-dir ./review --times 2,8,14,20,27,29 # 保留已接受的最终版本并删除此生成过程中可丢弃的工件 node plugins/ai-promo-video/dist/cli.js clean ./delivery --keep promo.mp4,credits.json --project-dir . --temporary-paths official-promo-frames,custom-audit ``` `image:edit` 和 `video:edit` 接受 JSON 指令。凭证仅属于被 gitignore 的 `*.local.json` 文件。 ## 项目结构 ```text plugins/ai-promo-video/ ├── src/mcp/server.ts 服务器和代理合约 ├── src/install.ts 通用安装程序 ├── src/capture/ 产品检查和记录 ├── src/advanced/ 运动目录和可编辑的 Revideo 项目 ├── src/captions/ 字幕导入、词语时序和时序 QA ├── src/media/ 编辑和增量修订 ├── src/library/ 本地和在线免费媒体搜索 ├── assets/revideo-template/ 中立的脚手架和可重用的运动基元 └── skills/create-ai-promo-video/ 方向、工作流程和 QA 标准 ``` JSON 引擎仅用于现有版本 1 的兼容性。新制作直接从中立的 Revideo 组合开始，无论它们主要使用库基元还是广泛的自定义代码。 ## 许可和隐私 项目代码在 MIT 下许可。Revideo 和 Three.js 是开源的，Playwright 控制浏览器，FFmpeg 执行编码和媒体编辑。依赖项保留其自己的许可，包括打包的 FFmpeg 二进制文件。 该项目不会将其 SaaS 发送到自己的模型，因为它既不包含模型也不包含托管服务。但是，用户选择的代理可能会根据该客户端的策略接收提示、截图或审查帧。机密、令牌、私有 URL 和客户数据不得存储在场景、清单或提交中。 ## 开发和验证 ```bash npm run build npm test npm run test:revideo-shader ``` 着色器回归测试渲染源和目标纹理着色器，并带有跨两个工作线程的反应参数。`npm run revideo:patch:check` 验证本地 Revideo 兼容性补丁，而不更改文件。如果 Revideo 的固定版本或预期运行时形状发生变化，则安装会安全失败，而不是修改未知的构建。 对于相同的源、资产、版本和平台，渲染是确定的。Revideo 的遥测功能被高级渲染器禁用。CLI 将实时渲染进度打印到 stderr，同时在 stdout 上保留机器可读的结果。在交付之前，技能需要持续时间和编解码器检查、整部电影采样、过渡审查和视觉异常的纠正。