VideoCaptioner 使用教程

📖 项目简介

VideoCaptioner（卡卡字幕助手）是 WEIFENG2333 开源的字幕工具，协议 GPL-3.0。一条命令把视频听写成字幕，再用大模型把同音字、错别字和专有名词改掉，最后烧进画面。仓库里自带一份 skills，Codex 可以直接调用。

它把这件事拆成四步：语音识别出带时间轴的字幕，按语义重新断句，大模型逐句校对，再按样式合成回视频。校对这一步可以带上你自己的提示词，把口播稿里的专有名词写进去，英文名和产品名不容易被听错。

识别引擎可以换。中文和英文可以用必剪或剪映，不用填接口；其他语言或想在本机识别，用 whisper-cpp。校对和断句要一个兼容 OpenAI 格式的大模型接口。做完的字幕可以只导出文件，也可以烧进视频另存，不覆盖原片。

📎 相关链接与下载地址（点击展开）

仓库： github.com/WEIFENG2333/VideoCaptioner
文档： weifeng2333.github.io/VideoCaptioner
更多教程：关注公众号 / 抖音 / 视频号「IT小圈」

✨ 核心亮点

🎙️

先听写，再改字

识别只负责出时间轴。同音字和专有名词交给大模型，按你写的提示词逐句改。

📄

自带 skills

仓库里有 SKILL.md。放进 Codex 的 skills 目录后，说人话就能跑完整条字幕流程。

🎬

字幕能烧进视频

描边、圆角底、竖屏样式都能选。合成时另存一份，原片不动。

🌐

也能翻译

校对完可以再翻成英文、日文等。必应和谷歌不用填接口，要更稳就用大模型。

🧩 它能做什么、输出什么

项目	说明
输入	本地视频或音频（mp4、mkv、mp3、wav 等）。命令行也可以先下载在线视频再处理。
适用类型	口播、教程、访谈。已经有字幕文件的，可以跳过识别，只做校对或翻译。
输出	srt、ass、txt、json；也可以把字幕烧进视频另存，或只嵌入软字幕。
语言 / 兼容	必剪、剪映识别支持中文和英文。其他语言用 whisper-api 或本机 whisper-cpp。翻译目标语言用 zh-Hans、en、ja、ko 这类代码。
规格 / 容量	一条命令走完识别、断句、校对、翻译、合成。批量时对一个文件夹里的视频逐条跑同一条命令。

🖥️ 环境要求

环境	建议配置
操作系统	Windows、macOS、Linux 都能装命令行。Windows 也可以下安装包用桌面版。
运行环境	本机有 Python 和 pip。命令行版：pip install videocaptioner
硬件	必剪、剪映识别不占显卡。本机 whisper-cpp 吃 CPU 或显卡，模型越大越慢。
无显卡方案	中英文走必剪或剪映。校对走云端大模型接口，电脑本身不用显卡。
关键依赖	合成字幕进视频需要 FFmpeg。校对需要一个兼容 OpenAI 格式的接口地址和 key。

🚀 如何使用

💡

先装上命令行，把仓库里的 SKILL.md 放进 Codex 的 skills 目录，再填一次大模型接口。之后把视频丢给它，说人话就行。

装上命令行

本机先有 Python 和 FFmpeg。FFmpeg 只在把字幕烧进视频时用到，只导出字幕文件可以后补。

                        bash
                        pip install videocaptioner
videocaptioner doctor
                    

放进 Codex 的 skills

在 GitHub 打开 VideoCaptioner 仓库，进入 skills 目录，把里面的 SKILL.md 复制到 Codex 的 skills 目录，每个 skill 单独一个文件夹。校对要用大模型，第一次把接口写进环境变量，兼容 OpenAI 格式的都能用。

                        bash
                        videocaptioner config set llm.api_key 你的key
videocaptioner config set llm.api_base 你的接口地址
videocaptioner config set llm.model 你的模型名
                    

先跑通一条

中文口播先识别，再只校对、不翻译。专有名词写进 --prompt，让它按你的稿子改。

                        bash
                        videocaptioner transcribe talk.mp4 --asr bijian -o talk.srt
videocaptioner subtitle talk.srt --no-translate --prompt "专有名词按口播稿：Codex、VideoCaptioner" -o talk-fixed.srt
videocaptioner synthesize talk.mp4 -s talk-fixed.srt --subtitle-mode hard --style vertical -o talk-sub.mp4
                    

常用参数说明：

参数	作用
`--asr bijian`	用必剪识别，中文和英文，不用填接口。换成 jianying 走剪映，换成 whisper-cpp 在本机识别。
`--no-translate`	只改错字和断句，不翻译。
`--prompt`	把专有名词、口播稿里的固定说法写进去，校对时按这个改。
`--style vertical`	竖屏字幕样式。横屏用默认样式，圆角底用 --render-mode rounded。
`-o`	输出到新文件。合成不要写成和原片同一个文件名。

一个文件夹一起做

对文件夹里每条视频重复同一套命令。想一次做完识别、校对和烧录，用 process，并加上 --no-synthesize 可以只出字幕文件。

                        bash
                        videocaptioner process talk.mp4 --asr bijian --no-synthesize -o ./subs/
videocaptioner subtitle ./subs/talk.srt --no-translate --no-split -o ./subs/talk-fixed.srt
                    

结合 Codex 使用

skills 放好、接口填过之后，直接说：给这个文件夹里的视频都加上中文字幕，专有名词按这份口播稿改，竖屏样式烧进去，原片别覆盖。Codex 会按 SKILL.md 去跑 transcribe、subtitle 和 synthesize。

✅

你只负责确认专有名词和成片。听写、改字、烧录都交给它，原片留着不动。

🎯 典型应用场景

🎙️

口播成片加字幕

录完直接出中文字幕，错字按口播稿改完再烧进去。

📚

教程视频

软件名、命令、英文缩写容易听错，写进提示词就按你的写法来。

🗣️

访谈和播客

先出整段字幕，再让它重新断句，一句不要拉得太长。

🌐

做成外语版

中文校对完再翻成英文或日文，可以双语，也可以只留译文。

📁

一批视频一起做

同一个文件夹、同一套专有名词，让 Codex 逐条跑完。

📱

竖屏成片

用 vertical 样式烧录，字幕位置适合手机全屏。

📈 和同类怎么选

做法	适合什么
只装 faster-whisper	只想要识别结果。没有断句、改专有名词和烧录。
VideoCaptioner	识别、改字、翻译、烧录在一条命令里，还能交给 Codex。
剪映里手改	条数少、想看着改。条数一多，专有名词还是容易漏。

🧠

识别负责把声音对上时间，大模型负责看上下文改字。两步分开，所以同音字不会只能听天由命。

❓ 常见问题

Q: 和剪映字幕有什么不一样？

剪映适合看着改几句。这个工具把识别、按提示词改专有名词、烧录连成命令，适合一批视频交给 Codex 跑。

Q: 支持哪些文件？

常见视频和音频都能进识别，例如 mp4、mkv、mp3、wav。已经有 srt 的，用 subtitle 命令接着校对，不用重新听写。

Q: 跑完提示缺依赖怎么办？

先跑 videocaptioner doctor。退出码 4 是缺 FFmpeg 这类依赖，退出码 5 多半是接口失败。看它打印的修复命令，不要凭感觉重装一遍。

Q: 没有显卡能用吗？

能。中英文用必剪或剪映识别，校对走云端接口，电脑不用显卡。只有本机 whisper-cpp 才吃算力。

Q: 识别引擎怎么选？

中文口播用 bijian。剪映账号侧用 jianying。日语等其他语言，或音频不想送出本机，用 whisper-cpp。必剪和剪映会把音频送到对应服务。

Q: 怎么和 Codex 一起用？

把仓库 skills 目录里的 SKILL.md 放进 Codex 的 skills 目录，接口用 config set 写好。之后用口语说要加字幕、按哪份稿改专有名词、竖屏烧录并且别覆盖原片。

Q: 专有名词还是错怎么办？

把正确写法放进 --prompt，再跑一遍 subtitle，加上 --no-translate。不要只靠识别引擎硬听。

Q: 原片会被盖掉吗？

不会，只要 -o 写成新文件名。软字幕用 --subtitle-mode soft，硬字幕烧进画面用 hard。

Q: 可以商用吗？

协议是 GPL-3.0。自己拿来做字幕没问题。如果你改了这个程序再发布，要按 GPL-3.0 把改过的源码一起公开。