video-use 视频编辑工具详细部署教程

video-use 是一个让您能通过自然语言与 AI 编程助手对话来编辑视频的开源工具。它通过分析音频转录和文字描述来理解视频内容，从而进行智能剪辑，无需使用复杂的非线性编辑软件。

📋 目录

  1. video-use 是什么
  2. 工作原理
  3. 安装前准备
  4. 一键安装（推荐）
  5. 手动安装步骤
  6. 配置 API 密钥
  7. 在 AI 助手中注册技能
  8. 首次使用工作流
  9. 高级功能与配置
  10. 更新与卸载
  11. 常见问题排查

video-use 是什么

video-use 是一个与编码 AI 助手（如 Claude Code、Codex）集成的视频编辑“技能”。您只需将原始视频素材放入文件夹，然后通过对话告诉 AI 您的编辑需求，它就能自动完成剪辑、调色、添加字幕、生成动画等复杂任务。

它能做什么：

  • 智能剪辑：自动识别并剪切掉视频中的填充词（如“嗯”、“啊”）和停顿间隙。
  • 自动调色：为每个片段应用色彩分级（如电影暖色调、中性鲜明色调），或执行自定义 FFmpeg 命令。
  • 无缝拼接：在每一个剪辑点自动添加 30ms 的音频淡入淡出，消除爆音。
  • 生成字幕：以您指定的样式（默认是两字一组的全大写格式）烧录字幕，完全可定制。
  • 生成动画覆盖层：通过 HyperFrames、Remotion、Manim 或 PIL 等工具，并行生成动画子代理。
  • 自我评估：在呈现给您之前，AI 会在每个剪辑点自行评估渲染输出，确保质量。
  • 会话记忆：编辑进度保存在 project.md 文件中，下次会话可接续工作。

工作原理

video-use 的设计核心是“高效理解”，避免 AI 陷入处理大量视频帧的困境。

  1. 第一层：音频转录（总是加载）
    • 使用 ElevenLabs Scribe 将视频的音频转换为带有单词级时间戳的文本。
    • 所有素材的转录会被压缩成一个约 12KB 的 Markdown 摘要文件 (takes_packed.md)，这是 LLM 理解视频内容的主要文本视图。
    • 这个视图包含了说话人、时间码和语气标签（如笑声、掌声），让 AI 能像阅读剧本一样“看”视频。
  2. 第二层：可视化合成（按需加载）
    • 只有在做出关键决策时（如判断模糊的停顿、比较不同素材、核对剪辑点），AI 才会调用 timeline_view 生成一张包含“胶片条+波形图+文字标签”的 PNG 图像。
    • 这种方式避免了处理成千上万帧图像的海量 token 消耗。

核心理念：文本为主，图像为辅。 通过这种方式，AI 能够以极高的效率和精度进行视频编辑。

安装前准备

软件依赖

  1. AI 编程助手：您需要安装并能够使用以下任一工具：
    • Claude Code
    • Codex (由 OpenAI 提供)
    • 或任何支持技能（Skills）且有 Shell 访问权限的类似代理。
  2. FFmpeg：视频处理的核心工具。
    • macOS: brew install ffmpeg
    • Windows/Linux: 请从 FFmpeg 官网 下载并配置到系统 PATH。
  3. Python 环境：建议使用 uv 或 pip 管理依赖。项目需要 Python 3.10+。
  4. Git：用于克隆仓库。
  5. ElevenLabs API 密钥：用于音频转录。可在 elevenlabs.io/app/settings/api-keys 免费获取。

一键安装（推荐）

让您的 AI 助手来处理所有安装步骤。这是最快捷的方式。

在 Claude Code、Codex 或您的 AI 代理中粘贴以下指令：

1
2
3
Set up https://github.com/browser-use/video-use for me.

Read install.md first to install this repo, wire up ffmpeg, register the skill with whichever agent you're running under, and set up the ElevenLabs API key — ask me to paste it when you need it. Then read SKILL.md for daily usage, and always read helpers/ because that's where the editing scripts live. After install, don't transcribe anything on your own — just tell me it's ready and wait for me to drop footage into a folder.

AI 代理会自动处理：克隆仓库、安装 Python 依赖、注册技能，并会提示您输入 ElevenLabs API 密钥。

手动安装步骤

如果您更倾向于手动控制安装过程，请按以下步骤操作：

1. 克隆仓库并建立软链接

选择一个存放项目代码的目录（例如 ~/Developer），然后为您的 AI 助手创建技能软链接。

1
2
3
4
5
6
7
8
9
# 1. 克隆项目到您的开发目录
git clone https://github.com/browser-use/video-use ~/Developer/video-use

# 2. 为您的 AI 助手创建软链接（二选一）
# 如果您使用 Claude Code:
ln -sfn ~/Developer/video-use ~/.claude/skills/video-use

# 如果您使用 Codex:
ln -sfn ~/Developer/video-use ~/.codex/skills/video-use

2. 安装 Python 依赖

进入项目目录，使用 uv 或 pip 安装依赖。

1
2
3
4
5
6
7
cd ~/Developer/video-use

# 推荐使用 uv (更快)
uv sync

# 或者使用 pip
pip install -e .

3. 安装 FFmpeg (如果尚未安装)

1
2
3
4
# macOS
brew install ffmpeg

# 其他系统请参考 FFmpeg 官网

4. 安装 yt-dlp (可选)
此工具用于从在线源下载视频。

1
brew install yt-dlp   # macOS

配置 API 密钥

您需要设置 ElevenLabs API 密钥用于音频转录。

1
2
3
4
5
6
7
cd ~/Developer/video-use

# 1. 复制环境变量示例文件
cp .env.example .env

# 2. 使用文本编辑器打开 .env 文件，填入您的 API 密钥
# ELEVENLABS_API_KEY=您的密钥

在 AI 助手中注册技能

根据您的 AI 助手，技能注册方式略有不同。

在 Claude Code 中注册

  1. 确保您已为 Claude Code 建立了技能软链接（如上所述）。
  2. 启动或重启 Claude Code 会话。
  3. Claude Code 会自动扫描 ~/.claude/skills/ 目录并加载技能。您可以通过输入 /help 查看 video-use 技能是否已加载。

在 Codex 中注册

  1. 确保您已为 Codex 建立了技能软链接（如上所述）。
  2. 启动或重启 Codex 会话，它会自动识别技能。

对于其他代理

  1. 将 ~/Developer/video-use 目录的路径添加到该代理的技能配置中。
  2. 或者，在每次会话中，指示 AI 代理读取 ~/Developer/video-use/SKILL.md 文件以了解可用功能。

首次使用工作流

安装和注册完成后，您可以开始编辑视频。

1. 准备素材
将所有原始视频文件（素材、B-roll 等）放入一个文件夹，例如 ~/Videos/my_project/。

2. 启动 AI 助手并导航
在终端中进入您的视频素材文件夹，然后启动 AI 助手。

1
2
cd ~/Videos/my_project/
claude   # 或 codex

3. 下达编辑指令
在 AI 助手的聊天界面中，使用自然语言描述您的需求。例如：

“帮我把这个文件夹里的视频素材剪辑成一个产品发布视频，时长控制在 1 分钟以内，添加电影级调色，并配上字幕。”

AI 助手会：

  1. 清点素材：读取文件夹中的所有视频文件。
  2. 提议策略：提出一个编辑计划（如使用哪些片段、顺序等），并请求您的确认。
  3. 执行编辑：在您确认后，进行转录、分析、剪辑、调色、渲染。
  4. 自我评估：检查渲染后的成品，确保质量。
  5. 输出结果：最终视频将保存在素材文件夹下的 edit/ 子目录中，名为 final.mp4。

高级功能与配置

  • 自定义调色：您可以指定任意的 FFmpeg 颜色滤镜链，例如 "colorize=#FFA500"。
  • 字幕样式：修改 SKILL.md 或 helpers/ 中的脚本，自定义字幕的字体、大小、颜色和显示方式。
  • 动画生成：通过配置，您可以让 AI 使用 HyperFrames、Remotion 或 Manim 在视频中生成动画覆盖层。
  • 自我评估循环：如果 AI 检测到视频存在问题（如视觉跳跃、音频爆音），它会自动尝试修复并重新渲染，最多尝试 3 次。

更新与卸载

更新 video-use

  1. 进入项目目录：cd ~/Developer/video-use
  2. 拉取最新代码：git pull
  3. 更新依赖：uv sync (或 pip install -e .)

卸载 video-use

  1. 移除 AI 助手的技能软链接：

    1
    2
    rm ~/.claude/skills/video-use   # 针对 Claude Code
    rm ~/.codex/skills/video-use    # 针对 Codex

  2. 删除项目目录（可选）：rm -rf ~/Developer/video-use

  3. 撤销环境变量：删除 .env 文件中配置的 API 密钥。

常见问题排查

问题：AI 助手找不到 video-use 技能。
解决：

  1. 确认软链接路径正确，且指向项目目录。
  2. 重启 AI 助手会话。
  3. 尝试在会话中手动指示：请阅读 ~/Developer/video-use/SKILL.md。

问题：转录失败或提示 API 密钥无效。
解决：

  1. 确认 .env 文件存在且 ELEVENLABS_API_KEY 设置正确。
  2. 检查 ElevenLabs 账户是否有足够额度（免费套餐每月有配额）。
  3. 确保网络可以访问 ElevenLabs API。

问题：ffmpeg 命令未找到。
解决：

  1. 确认 FFmpeg 已正确安装。
  2. 将 FFmpeg 的安装路径（如 /usr/local/bin）添加到您的系统 PATH 环境变量中。

问题：uv 命令未找到。
解决：

  1. uv 是一个快速的 Python 包管理器，您可以通过 pip install uv 安装它。
  2. 或者，直接使用 pip install -e . 替代 uv sync。

如需更多帮助，请查看项目内的 install.md 和 SKILL.md 文件，或在 GitHub Issues 页面搜索类似问题。