一个 Python 视频处理工具链实战：下载、转录、摘要、字幕、诊断全打通 （已开源）

我做了一个 Python CLI 工具，把视频下载、AI 转录、AI 摘要全串起来了

现在很多人处理视频内容，真正想要的已经不只是"把视频下载下来"，而是把视频里的信息提取出来、整理出来、压缩出来。

比如先下载视频，再用 AI 做语音转文字；如果内容太长，再交给大模型生成摘要和关键词，最后把结果沉淀成可检索、可复用的文本资料。

平时遇到一条视频链接，如果想把里面的内容真正沉淀下来，往往还要经历好几个步骤：

• 先下载视频
• 再提取字幕
• 如果没有字幕，就跑 Whisper 转录
• 最后再调用大模型生成摘要和关键词

这些步骤听起来不复杂，但真实做起来往往很碎：

• 下载是一个脚本
• 转录是另一个脚本
• 摘要又是第三个脚本
• 字幕格式转换还得再找一个工具
• 出错时只能盯着控制台日志排查
• 环境稍微复杂一点，FFmpeg、cookies、Selenium 就开始掉链子

所以我做了一个本地 CLI 工具链：video-link-pipeline。

它的目标不是只解决某一个步骤，而是把视频下载、字幕获取、AI 转录、AI 摘要、字幕转换、环境诊断统一进一套命令里。

这篇文章主要不讲重构过程，而是重点介绍：这个项目现在能做什么、怎么用、以及它为什么比"几个脚本拼起来"更适合长期使用。

一、这个项目现在能做什么？

从能力上看，video-link-pipeline 已经覆盖了一条比较完整的 AI 视频内容处理链路：

• 下载视频、音频、字幕
• 只下载字幕和元数据
• 对本地视频或音频做 Whisper AI 转录
• 对 transcript 调用大模型生成 AI 摘要和关键词
• 在 srt 和 vtt 之间转换字幕格式
• 用一条命令串起整条流水线
• 在运行前检查 Python、FFmpeg、Selenium、cookies 配置

项目统一入口是 vlp，当前支持这些命令：

vlp download <url>
vlp download-subs <url>
vlp transcribe <path>
vlp summarize <transcript.txt>
vlp convert-subtitle <file-or-dir>
vlp run <url>
vlp doctor

也就是说，这个项目想解决的不是"某一步能不能跑"，而是把视频内容处理变成一条完整可用的本地流水线。

这里面的 AI 能力主要集中在两段：

一段是 Whisper AI 转录 ，负责把视频或音频里的语音内容转成结构化文本和字幕；另一段是 大模型 AI 摘要，负责把长 transcript 进一步压缩成摘要和关键词。也就是说，这个项目不只是把视频下载到本地，而是在尝试把视频一步步转成可阅读、可检索、可复用的知识内容。

二、功能 1：下载视频、音频、字幕

最基础的功能当然是下载。

项目支持从视频链接中下载视频，也支持：

• 只下载音频
• 指定字幕语言
• 按站点归类输出目录
• 配合浏览器 cookies 提高受限站点成功率

例如：

vlp download "https://www.bilibili.com/video/BV..."
vlp download "https://..." --audio-only
vlp download "https://..." --sub-lang zh --sub-lang en
vlp download "https://..." --cookies-from-browser chrome
vlp download "https://..." --group-by-site

这个能力适合的场景很多：

• 保存公开视频资料
• 下载课程、访谈、讲座内容
• 提前获取本地视频素材做后续处理
• 为转录和摘要做输入准备

如果只是"把视频下下来"，当然也能找到现成工具。

但这个项目的重点不只是下载本身，而是让下载结果能自然进入后面的字幕、转录、摘要流程。

三、功能 2：只下载字幕和元数据

真实使用中，有些站点会出现一种很常见的情况：

• 视频下载受限
• 但字幕和元数据其实还能拿到

这种场景下，如果还强行走完整下载流程，体验会比较差。

所以项目单独提供了 download-subs 模式。

vlp download-subs "https://www.bilibili.com/video/BV..."

这个命令适合：

• 你主要关心视频内容文本，而不是视频文件本身
• 某些站点媒体格式受限，但字幕仍然可访问
• 想先拿字幕做知识整理、摘要、翻译、归档

这个能力看起来不大，但很实用。

因为很多时候我们要的不是"视频文件"，而是"视频里的内容"。

四、功能 3：对本地视频或音频做 Whisper AI 转录

如果视频本身没有字幕，或者字幕质量不理想，那就需要转录。

项目支持直接对本地视频或音频做 Whisper AI 转录，输出包括：

• transcript.txt
• subtitle_whisper.srt
• subtitle_whisper.vtt
• transcript.json

比如：

vlp transcribe ./output/demo/video.mp4
vlp transcribe ./output/demo --model small --language auto
vlp transcribe ./output/demo/video.mp4 --engine faster --device cpu --compute-type int8

这个功能适合：

• 视频本身没有字幕
• 需要借助 AI 从音频中提取可编辑文本
• 想把长视频内容转成可检索资料
• 为后续摘要、关键词提取提供输入

和单独跑 Whisper 相比，这里的好处是：

• 输入输出目录更统一
• 产物命名更稳定
• 更容易和下载、摘要命令衔接
• 后续状态会被写入统一结果中

五、功能 4：对 transcript 生成 AI 摘要和关键词

拿到 transcript 之后，下一步通常就是"把长内容压缩成可读结果"。

项目支持直接对 transcript.txt 调用大模型生成 AI 结果：

• summary.md
• keywords.json

例如：

vlp summarize ./output/demo/transcript.txt --provider claude
vlp summarize ./output/demo/transcript.txt --provider deepseek --base-url https://api.deepseek.com --model deepseek-chat

这个功能特别适合：

• 长视频内容快速提炼
• 课程、访谈、播客的重点总结
• 二次创作素材整理
• 视频内容进入知识库前的结构化压缩

在实际工作里，很多人卡住的并不是"拿不到视频"，而是"视频太长，不知道怎么高效消化"。

所以下载和转录只是前半段，AI 摘要其实才是把内容真正变成可复用资料的关键一步。

六、功能 5：字幕格式转换

很多时候，字幕不是没有，而是格式不对。

常见问题包括：

• 下载下来是 vtt，但播放器或后续流程只认 srt
• 一批字幕文件想统一格式
• 转录结果要适配不同工具链

所以项目提供了字幕转换命令：

vlp convert-subtitle ./subtitle.vtt --format srt
vlp convert-subtitle ./subs --batch --format srt

它支持：

• 单文件转换
• 目录批量转换
• srt 和 vtt 双向处理

虽然这是一个小功能，但它让整个工具链更完整了。

因为真实使用中，最后卡住你的往往不是"大问题"，而是这类格式细节。

七、功能 6：一条命令串起整条流水线

如果你不想手动分步执行，也可以直接用 run。

vlp run "https://..."
vlp run "https://..." --do-transcribe
vlp run "https://..." --do-transcribe --do-summary

这个命令会把多个步骤串起来：

1. 先下载
2. 需要时执行转录
3. 需要时生成摘要
4. 每一步都持续更新结果状态

这类一键式命令特别适合：

• 想快速处理单个视频
• 想把流程封装进自己的自动化脚本
• 不想在多个命令之间手动切换
• 想尽量减少重复操作

如果从产品体验看，run 是非常重要的一步。

因为它代表这个项目已经不再只是"多个命令堆在一起"，而是开始具备完整任务流的味道了。

八、功能 7：运行前环境诊断

我觉得这个项目里一个很实用的命令是 vlp doctor。

vlp doctor
vlp doctor --config ./config.yaml

原因很简单：

很多时候，失败根本不是代码本身的问题，而是运行环境的问题，比如：

• Python 版本不对
• FFmpeg 没装好
• Selenium extra 没安装
• 浏览器驱动不可用
• cookies 配置冲突
• 浏览器还开着，cookies 数据库被锁住

所以这个命令会重点检查：

• Python runtime
• Python executable
• FFmpeg 是否可用，以及最终来源
• Selenium extra 是否完整
• 当前 cookies 配置
• 当前 effective download config
• 可能存在的配置风险

这一步对于真实使用体验非常重要。

因为一个命令行工具真正好不好用，不只看成功路径，也看失败时能不能快速定位问题。

九、这个项目的输出结果长什么样？

一个工具是否"工程化"，不仅看它能做什么，也要看它输出什么。

这个项目的输出根目录是 output/，每次任务都会落到独立 job 目录里。

如果开启按站点分类，目录结构会像这样：

output/
├─ bilibili/
│  └─ BVxxxx-demo-title/
├─ youtube/
│  └─ demo-title/
└─ douyin/
   └─ demo-title/

一个典型 job 目录里，可能会包含这些文件：

output/
└─ BVxxxx-demo-title/
   ├─ video.mp4
   ├─ audio.m4a
   ├─ subtitle.vtt
   ├─ subtitle.srt
   ├─ transcript.txt
   ├─ subtitle_whisper.srt
   ├─ subtitle_whisper.vtt
   ├─ transcript.json
   ├─ summary.md
   ├─ keywords.json
   └─ manifest.json

这里最值得单独提一下的是 manifest.json。

它记录的不是单个文件，而是整个 job 的执行状态，比如：

• 输入 URL
• 当前生效配置
• 产物路径
• 下载是否成功
• 转录是否成功
• 摘要是否成功
• 是否触发 fallback
• 如果失败，错误码和提示是什么

这意味着项目输出的不是"一堆零散文件"，而是一份有状态、有上下文、可追踪的结果集合。

十、它为什么比"几个脚本拼起来"更强？

到这里，其实已经能看出这个项目和普通脚本组合的区别了。

我觉得主要强在这几个方面。

1. 统一 CLI，而不是多个散乱入口

以前常见的做法是：

• 一个脚本下载
• 一个脚本转录
• 一个脚本做摘要
• 再加几个辅助脚本

这样短期很快，但后期会越来越乱。

现在所有能力统一收敛到 vlp，意味着：

• 用户心智更清晰
• 参数命名更统一
• 后续维护更容易

2. 配置优先级清晰

项目明确了配置来源的优先级：

1. CLI 参数
2. 环境变量和 .env
3. config.yaml
4. 内置默认值

这能有效避免"我明明改了配置，为什么没生效"这类常见问题。

3. 下载链路不是只有 happy path

下载这部分不是简单调用一次 yt-dlp 就结束。

项目内部会区分：

• 常规主路径
• Selenium fallback 准备阶段
• 带浏览器上下文的重试阶段

这让它在真实网站环境里更稳，也更容易排查问题。

4. 提供了专门的环境诊断能力

很多工具失败时只会把异常堆栈甩给用户。

但这个项目单独提供了 doctor 命令，能提前暴露：

• FFmpeg 问题
• Selenium 问题
• cookies 问题
• 配置风险

对真实使用者来说，这种能力的价值往往非常高。

十一、这个项目适合哪些使用场景？

从实际用途来看，我觉得它很适合下面这些场景：

• 把公开视频内容沉淀成文字资料
• 下载课程、讲座、访谈并提取字幕
• 对无字幕视频做 Whisper 转录
• 用大模型对长视频做内容摘要
• 把视频资料变成知识库输入
• 做个人学习资料整理
• 做本地批处理流水线前置环节
• 作为更大自动化系统中的一个 CLI 节点

换句话说，这个项目并不只是"下载工具"。

它更像是一个面向视频内容结构化处理的本地 AI 工具链。

十二、为什么最后要做成一个统一工具链？

如果只是为了功能跑通，几个脚本也完全能用。

但只要项目开始持续使用，问题就会越来越明显：

• 入口分散
• 配置漂移
• 输出不统一
• 错误难排查
• 失败后很难恢复

所以最后把它整理成一个统一 CLI 工具链，其实不是为了"看起来更专业"，而是为了让它真的更容易用、也更容易继续维护。

一个项目是否能持续演进，很多时候不取决于功能点本身，而取决于你有没有把这些基础能力补齐：

• 统一入口
• 稳定输出
• 环境诊断
• 失败状态记录
• 清晰配置模型

这个项目现在做的，就是把这些基础设施和具体功能一起收口。

十三、总结

如果只用一句话概括 video-link-pipeline，我会这样说：

它不是单独解决"下载"或"转录"某一个问题，而是把视频下载、字幕获取、Whisper AI 转录、大模型 AI 摘要、字幕转换和环境诊断统一成了一条本地 CLI 流水线。

它当前已经能完成这样一条完整链路：

• 从链接下载视频或字幕
• 在需要时补转录
• 把 transcript 压缩成摘要和关键词
• 把中间产物落成标准化目录
• 用 manifest.json 记录整个任务状态
• 用 doctor 提前暴露环境问题

如果你也在做类似的视频内容处理、资料归档、知识沉淀工具，我觉得这类统一 CLI 的方式很值得尝试。

因为它解决的不是"单一步骤能不能跑"，而是"整条流程能不能真正稳定地用起来"。

开源地址 ：

👉https://github.com/xiexikang/video-link-pipeline

代码完全开源，如果觉得好用或者对你有启发，求个 Star ⭐️ ！也欢迎大家提 PR 支持。