Openclip

<p align="center"> <img src="./logo.png" alt="OpenClip" width="350"/> </p>

English | 简体中文

一个轻量化自动化视频处理流水线，用于识别和提取长视频（特别是口播和直播回放）中最精彩的片段。使用 AI 驱动的分析来发现亮点，生成剪辑，并添加标题和封面。

🎯 功能介绍

输入一个视频 URL 或本地文件，自动完成 下载 → 转录 → 分割 → AI 分析 → 剪辑生成 → 添加标题和封面 的全流程处理，输出最精彩片段。适合从长直播或视频中快速提取高光时刻。

💡 与 AutoClip 的区别？ 查看对比说明了解 OpenClip 的轻量级设计理念。

📢 最新动态

• 2026-04-04:
  • 新增 custom_openai 提供商，可在 Streamlit 或 CLI 中自定义 LLM Model 与 LLM Base URL，对接本地或自建 OpenAI 兼容接口
  • 新增 Paraformer 中文 ASR 支持，本地 ASR 会自动按语言路由，中文优先使用 Paraformer
• 2026-03-30:
  • 新增默认开启的剪辑边界修正，目标是让高光片段的开始和结束更自然，减少突兀截断
  • 在 Streamlit UI 中支持 Bilibili 多 P 视频一键创建任务、后台任务重试，以及重启后取消 pending 任务，感谢 @xenoamess
• 2026-03-25:
  • 新增 Cookie 使用建议 与更清晰的 Streamlit Cookie 模式；远程视频下载可按 不使用 cookies → 浏览器 cookies → Cookies 文件 的顺序尝试
• 2026-03-24:
  • 新增 GLM（智谱AI） 和 MiniMax 作为 LLM 提供商，现支持 Qwen、OpenRouter、GLM、MiniMax 与 custom_openai
• 2026-03-11:
  • OpenClip 现已上架 skills.sh，可通过 npx skills add https://github.com/linzzzzzz/openclip --skill video-clip-extractor 在任意目录安装为 Agent Skill，并让 Agent 调用
• 2026-03-08:
  • 新增 --user-intent 参数 — 用自然语言告诉 AI 你在找什么（如 --user-intent "关于 AI 风险的观点"），LLM 在片段筛选和排名时会优先考虑相关内容

<details> <summary>更早的更新</summary>

• 2026-03-04:
  • Git 历史变更通知：错误的减小 GitHub size 的尝试导致 Git 历史被重写，对现有用户造成不便，深感抱歉。已有克隆用户需运行 git fetch origin && git reset --hard origin/main 以同步最新历史
  • 新增字幕烧录功能 — 使用 --burn-subtitles 将 SRT 字幕直接烧录到剪辑视频中；可选 --subtitle-translation "Simplified Chinese" 同时烧录中英双语字幕（需要带 libass 的 ffmpeg）
  • OpenRouter 默认模型从 openrouter/free 切换至 stepfun/step-3.5-flash:free
• 2026-03-01:
  • Streamlit 界面支持后台任务处理和并发处理多个视频
  • 新增说话人识别功能（预览版）— 使用 --speaker-references 为访谈/座谈/播客视频自动标注说话人姓名
  • 优化 AI 提示词，减少时间戳格式混淆（如 00:01:55 vs 01:55:00）
• 2025-02-26:
  • 默认 Qwen 模型从旧版 qwen-turbo 切换至 qwen3.5-flash
  • 优化 AI 提示词，减少时间戳幻觉，提升标题质量

</details>

🎬 演示

网页页面

Agent Skills

<video src="https://github.com/user-attachments/assets/1ddf8318-f6ad-418c-9c4c-bbac0dedc668" controls width="600" height="450"></video>

✨ 特性

• 灵活输入：支持 Bilibili、YouTube URL 或本地视频文件
• 智能转录：优先使用平台字幕；本地 ASR 会自动按语言路由，英文使用 Whisper，中文使用 Paraformer
• 说话人识别（预览版）：自动识别谁在说话，将真实姓名标注到字幕中，适合访谈、座谈、辩论和播客
• AI 分析：基于内容、互动和娱乐价值识别精彩时刻；支持 --user-intent 引导 AI 聚焦特定关注点
• 剪辑生成：提取最精彩时刻为独立视频剪辑，自动生成字幕文件、标题和封面图片
• 字幕烧录（可选）：将 SRT 字幕硬烧到视频画面中，可选通过当前选定的 LLM 提供商翻译成目标语言后烧录双语字幕
• 背景上下文：可选的添加背景信息（如主播姓名等）以获得更好的分析
• 三界面支持：Streamlit 网页界面，Agent Skills 和命令行界面，满足不同用户需求
• Agent Skills：内置 Claude Code 和 TRAE agent skill，用自然语言即可处理视频

📋 前置要求

手动安装

• 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.5-flash 模型）
  • 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 模型协议

由 uv 自动管理

运行 uv sync 时会自动安装以下依赖：

• Python 3.11+ - 如果系统未安装，uv 会自动下载
• yt-dlp - 用于从 Bilibili、YouTube 等平台下载视频
• Whisper - 用于语音转文字
• 其他 Python 依赖（moviepy、streamlit 等）

可选 extra：

• uv sync --extra paraformer - 安装 Paraformer 中文本地 ASR 运行时依赖
• uv sync --extra speakers - 安装 WhisperX 说话人识别依赖

🚀 快速开始

1. 克隆和设置

# 克隆仓库
git clone https://github.com/linzzzzzz/openclip.git
cd openclip

# 使用 uv 安装依赖
uv sync

<a id="paraformer-installation"></a>

<details> <summary>🈶 启用 Paraformer 中文本地 ASR（可选）</summary>

如果你希望在本地 ASR 路径里优先使用 Paraformer 处理中文音频，请额外完成下面两步：

# 1) 安装 Paraformer 运行时依赖
uv sync --extra paraformer

# 2) 准备兼容的 Paraformer helper checkout
# 默认目录：
third_party/funasr-paraformer

推荐直接把 helper 仓库 checkout 到当前项目内，避免把开发机绝对路径写进配置：

mkdir -p third_party
git clone <funasr-paraformer-helper-repo> third_party/funasr-paraformer

OpenClip 当前会在这个 helper 目录里查找两个脚本：

• tools/transcribe_long_audio.py
• tools/funasr_json_to_srt.py

如果你的 helper 项目不在默认目录，可以设置：

export PARAFORMER_PROJECT_DIR=/path/to/funasr-paraformer

说明：

• 默认路径已经是仓库相对路径：third_party/funasr-paraformer
• 如果 helper 项目自带 .venv，OpenClip 会优先使用它
• 如果 helper 项目没有 .venv，OpenClip 会退回使用当前仓库通过 uv sync --extra paraformer 安装出来的环境
• 如果 helper 项目或依赖不可用，OpenClip 会自动回退到 Whisper

</details>

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

3. 运行流水线

选项 A：使用 Streamlit 网页界面

启动 Streamlit 应用：

uv run python -m streamlit run streamlit_app.py

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

使用流程：

1. 在侧边栏选择输入类型（视频 URL 或本地文件）
2. 配置处理选项（LLM 提供商、LLM Model、LLM Base URL、Cookie 模式等）
3. 点击「Process Video」按钮开始处理
4. 查看实时进度和最终结果
5. 在结果区域预览生成的剪辑和封面

如果选择 custom_openai，请在侧边栏填写 LLM Model 和 LLM Base URL；如果你的接口不需要鉴权，API Key 可以留空。

优势： 无需记住命令行参数，提供可视化操作界面，适合所有用户。

<a id="concurrent-processing"></a>

<details> <summary>🔄 并发处理与后台任务</summary>

Streamlit 界面支持后台任务处理和并发处理多个视频：

后台任务处理：

• 视频处理在后台运行，可以关闭浏览器
• 任务持久化保存，重新打开页面可继续查看
• 每个任务独立运行，互不干扰

并发处理多个视频：

• 点击「处理视频」启动第一个任务 → 自动跟踪进度
• 打开新标签页启动第二个任务 → 在新标签页中独立跟踪
• 每个标签页可独立跟踪不同任务

Watch Progress 功能：

• 在任务卡片中点击「👁️ Watch Progress」按钮可切换跟踪的任务
• 显示「✓ Watching」表示当前正在跟踪该任务
• 实时查看进度更新和当前处理步骤

任务管理：

• 查看所有任务状态（处理中、已完成、失败）
• 取消运行中的任务
• 删除已完成或失败的任务
• 查看任务详情（创建时间、处理时长等）

</details>

选项 B：使用 AI Agent 技能

如果你使用 Claude Code、TRAE、Cursor 或任何其他支持 skills 的 Agent，可以直接用自然语言处理视频，无需手动输入命令：

"帮我从这个视频里提取精彩片段：https://www.bilibili.com/video/BV1234567890"
"处理一下 ~/Downloads/livestream.mp4，用英语作为输出语言"

Agent 会自动完成环境配置、下载、转录、分析、剪辑和标题添加等全部流程。

选择安装方式：

| 场景 | 操作 | |------|------| | 已克隆本仓库 | 无需操作 — 在仓库目录内打开 Agent 时技能自动生效 | | 全局使用（任意目录、任意项目均可触发） | 在任意目录执行：npx skills add https://github.com/linzzzzzz/openclip --skill video-clip-extractor -g | | 仅在某个特定项目目录内使用 | 在该目录下执行：npx skills add https://github.com/linzzzzzz/openclip --skill video-clip-extractor |

技能定义位于 .claude/skills/video-clip-extractor/ 目录下。

选项 C：使用命令行界面

# 处理 Bilibili 视频
uv run python video_orchestrator.py "https://www.bilibili.com/video/BV1234567890"

# 处理 YouTube 视频
uv run python video_orchestrator.py "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# 处理本地视频
uv run python video_orchestrator.py "/path/to/video.mp4"

如需使用已有字幕，请将 .srt 文件放在同目录下，文件名保持一致（如 video.mp4 → video.srt）。

<a id="speaker-identification"></a>

<details> <summary>🎙️ 说话人识别（可选，预览版）</summary>

⚠️ 预览功能：说话人识别功能目前处于预览阶段，后续版本中行为或接口可能有所调整。

🐢 性能提示：说话人识别依赖 pyannote 模型，在 CPU 上运行较慢（长视频可能需要数分钟）。有 GPU 环境下速度会显著提升。

适用于访谈、座谈、辩论、播客等多人对话视频。启用后，字幕中每句话前会标注说话人姓名，例如 [Host] 欢迎来到今天的节目。这为 AI 的高光分析提供了更丰富的上下文——让它能更准确地识别特定说话人之间最精彩的交流片段，而非将所有语音一视同仁。

步骤一：安装额外依赖

uv sync --extra speakers

步骤二：设置 HuggingFace Token

export HUGGINGFACE_TOKEN=hf_your_token_here

并在 HuggingFace 上接受 pyannote 模型协议。

步骤三：提取参考音频

从视频中截取每位说话人的参考片段（10–30 秒，单人清晰语音）：

uv run python tools/extract_reference.py VIDEO 起始时间 结束时间 "references/姓名.wav"

# 示例
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"

步骤四：运行

uv run python video_orchestrator.py --speaker-references references/ "VIDEO_URL_OR_PATH"

</details>

<a id="subtitle-burning"></a>

<details> <summary>🔤 字幕烧录（可选）</summary>

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