openclip Agent工作流

使用 uv 安装依赖

uv sync

<a id="paraformer-installation"></a>
<details>
<summary>🈶 启用 Paraformer 中文本地 ASR（可选）</summary>

本地 ASR 会按语言自动路由：英文使用 Whisper，中文优先使用 Paraformer。若要启用 Paraformer，请安装额外依赖：

OpenClip 默认使用仓库内置的 helper：`third_party/funasr-paraformer`。通常不需要设置 `PARAFORMER_PROJECT_DIR`；只有当你把 helper 放在仓库外部时才需要设置：

如果 Paraformer 依赖或 helper 不可用，OpenClip 会自动回退到 Whisper。

</details>

手动安装

• uv（Python 包管理器）- 安装指南
• FFmpeg - 用于视频处理
• macOS: brew install ffmpeg
• Ubuntu: sudo apt install ffmpeg
• Windows: 从 ffmpeg.org 下载

<details> <summary>需要双语字幕烧录？点击查看带 libass 的安装方式</summary>

默认安装通常不包含 libass： - macOS: brew tap homebrew-ffmpeg/ffmpeg && brew install homebrew-ffmpeg/ffmpeg/ffmpeg（替换已有的 ffmpeg） - Ubuntu: sudo add-apt-repository ppa:savoury1/ffmpeg4 && sudo apt install ffmpeg - Windows: 从 gyan.dev 下载 full 版本 </details>

• LLM API Key / 接口配置（选择其一）
• Qwen API Key - 从阿里云获取密钥（默认使用 qwen3.6-plus 模型）
• OpenRouter API Key - 从OpenRouter获取密钥（默认使用 stepfun/step-3.5-flash:free 模型）
• GLM API Key - 从智谱AI获取密钥（默认使用 glm-4.7 模型）
• MiniMax API Key - 从MiniMax获取密钥（默认使用 MiniMax-M2.7 模型）
• Custom OpenAI 兼容接口 - 需要可访问的 OpenAI-compatible chat completions 接口；需配置 CUSTOM_OPENAI_BASE_URL 和 CUSTOM_OPENAI_MODEL，CUSTOM_OPENAI_API_KEY 可选

- Chrome / Firefox / Edge / Safari 浏览器（可选）- 当你选择使用浏览器 Cookie 时，可用于远程视频下载身份验证 - Deno 或 Node（可选，YouTube 下载可能会需要）- 提升 YouTube 下载稳定性。OpenClip 会自动检测并使用；如果你主要处理 YouTube，尤其是需要 cookies 的情况，建议安装 - 安装方式可参考 yt-dlp 官方 EJS 文档： Step 1: Install a supported JavaScript runtime - HuggingFace Token (可选，用于说话人识别) - 从 huggingface.co/settings/tokens 获取，并接受 pyannote 模型协议

🚀 快速开始

🎬 演示

3. 运行流水线

选项 A：使用 Streamlit 网页界面

启动 Streamlit 应用：

uv run python -m streamlit run streamlit_app.py

应用启动后，打开浏览器访问显示的 URL（通常是 http://localhost:8501）。

<a id="lan-shared-machine-mode"></a> <details> <summary>局域网/共享机器模式</summary>

如果需要从同一局域网内的其他设备访问 Streamlit，并让「Open in Editor」显示可访问的 Clip Editor 链接：

```bash export OPENCLIP_EDITOR_BASE_URL=http://HOST_LAN_IP:8765

示例

uv run python tools/extract_reference.py interview.mp4 00:01:23 00:01:50 "references/Host.wav" uv run python tools/extract_reference.py interview.mp4 00:03:10 00:03:40 "references/Guest.wav"

**步骤四：运行**

</details>

<a id="subtitle-burning"></a>
<details>
<summary>🔤 字幕烧录（可选）</summary>

将 SRT 字幕文件硬烧到视频画面中（即使没有字幕播放器也能看到字幕）。支持原始字幕烧录，或通过当前选定的 LLM 提供商翻译后同时烧录双语字幕。说话人标签（如 `[Sam Altman]`）会自动从画面中移除。

**前提：ffmpeg 需包含 libass**（详见上方安装说明）

**仅烧录原始字幕：**

**烧录原始 + 中文翻译字幕：**

输出文件在 clips_post_processed/ 目录，英文字幕显示在底部，中文字幕显示在英文上方。

</details>

<a id="cookie-guidance"></a>

🍪 Cookie 使用建议

远程视频下载有时会遇到登录验证、风控或平台限制。OpenClip 支持三种模式：

• 不使用 cookies：先尝试最简单的公开访问方式
• 浏览器 cookies：使用本机浏览器中的登录态
• Cookies 文件：使用导出的 Netscape 格式 cookies.txt

推荐尝试顺序：

1. 先试 不使用 cookies
2. 如果报登录、风控、not a bot、LOGIN_REQUIRED 等错误，再试 浏览器 cookies
3. 如果浏览器 cookies 仍不稳定，再试 Cookies 文件

YouTube 特别说明：

• 对于 YouTube，如果你使用 cookies，则很可能还需要安装 Deno 或 Node 这样的 JavaScript 运行时，否则可能只拿到不完整格式，甚至下载失败。安装说明可见前置要求

CLI 对应方式：

1. 不传任何 cookie 参数
2. 使用 --browser chrome（或你实际使用的浏览器）
3. 使用 --cookies /path/to/cookies.txt

注意：

• 仅在确实需要登录态访问内容时再使用 cookies，并尽量控制下载频率，或使用备用账号

导出 Cookies 文件：

- 如果你需要生成 cookies.txt，可参考 yt-dlp 官方教程： Exporting YouTube cookies - 虽然教程标题写的是 YouTube，但在 OpenClip 中，导出的 Netscape 格式 cookies.txt 同样可用于 YouTube 和 Bilibili

🔍 命令行示例

处理 Bilibili 视频，加载背景信息， 并使用霓虹风格处理Banner标题：

uv run python video_orchestrator.py \
  --title-style neon_glow \
  --use-background \
  "https://www.bilibili.com/video/BV1wT6GBBEPp"

仅分析，不生成剪辑：

uv run python video_orchestrator.py --skip-clips --skip-cover "VIDEO_URL"

说话人识别（预览版）：

uv run python video_orchestrator.py \
  --speaker-references references/ \
  "interview.mp4"

跳过下载，重新处理已有视频：

uv run python video_orchestrator.py --skip-download --title-style crystal_ice "VIDEO_URL"

使用自定义 OpenAI 兼容接口：

uv run python video_orchestrator.py \
  --llm-provider custom_openai \
  --llm-model Qwen/Qwen2.5-7B-Instruct \
  --llm-base-url http://127.0.0.1:8000/v1 \
  "VIDEO_URL"

1. 克隆和设置

```bash

2. 设置 API 密钥（用于 AI 功能）

根据你选择的 LLM 提供商，设置对应的环境变量（至少配置一组）：

export QWEN_API_KEY=your_api_key_here        # 通义千问
export OPENROUTER_API_KEY=your_api_key_here   # OpenRouter
export GLM_API_KEY=your_api_key_here          # 智谱AI GLM (bigmodel.cn 国内端点)
export MINIMAX_API_KEY=your_api_key_here      # MiniMax (minimaxi.com 国内端点)
export CUSTOM_OPENAI_API_KEY=your_api_key_here # custom_openai，可选
export CUSTOM_OPENAI_BASE_URL=http://127.0.0.1:8000/v1
export CUSTOM_OPENAI_MODEL=Qwen/Qwen2.5-7B-Instruct

说明：

• custom_openai 适合对接 LM Studio、vLLM、One API、New API 等 OpenAI 兼容服务
• CUSTOM_OPENAI_BASE_URL 可以是 API 根路径（如 .../v1），也可以直接写完整的 /chat/completions 接口
• 如果你的兼容接口不要求 Bearer 鉴权，CUSTOM_OPENAI_API_KEY 可以留空
• Streamlit 侧边栏支持按提供商覆盖 LLM Model 和 LLM Base URL；CLI 对应参数为 --llm-model 和 --llm-base-url

📖 命令行参数

<details> <summary>🎨 Banner 标题艺术风格</summary>

</details>

🔧 工作流程

OpenClip 会先找到候选高光片段，再生成字幕、剪辑、封面和可选后期处理。默认模式更快；开启 --deep-optimize 后，会增加额外的 AI 复审与边界优化流程，以换取更高的片段质量。

🔄 与 AutoClip 的对比

OpenClip 受 AutoClip 启发，但采用不同设计理念：

OpenClip 特点： 轻量（5K行代码）、快速启动、提示词可定制、易于维护和二次开发

感谢 AutoClip 为视频自动化处理做出的贡献。