VideoCaptioner 全流程视频字幕处理实战指南语音识别、字幕优化、翻译与配音合成一站式搞定【免费下载链接】VideoCaptioner 卡卡字幕助手 | VideoCaptioner - 基于 LLM 的智能字幕助手 - 视频字幕生成、断句、校正、字幕翻译全流程处理- A powered tool for easy and efficient video subtitling.项目地址: https://gitcode.com/gh_mirrors/vi/VideoCaptionerVideoCaptioner卡卡字幕助手是一个基于大语言模型LLM的视频字幕处理工具覆盖语音识别 → 字幕断句 → LLM 优化 → 翻译 → 视频合成的完整工作流。本文以项目根目录的 README.md 为主体结合 docs/cli.md 命令文档与核心源码实现系统讲解其安装方式、CLI 命令、GUI 桌面版、LLM 配置、Claude Code Skill 接入以及底层工作原理读完后你将能独立完成从一段原始视频到带优化字幕、多语言翻译乃至配音成片的完整处理管线。一、项目概览一条命令打通视频字幕全流程VideoCaptioner 的设计目标是安装即用、免费起步。其核心处理流水线在 README 中概括为音视频输入 → 语音识别 → 字幕断句 → LLM 优化 → 翻译 → 视频合成在此基础上项目还提供了字幕配音dub与在线视频下载download等延伸能力。从源码结构看这一流水线被拆分为多个独立的核心模块分别位于 videocaptioner/core/asr语音识别、videocaptioner/core/split断句、videocaptioner/core/optimize优化、videocaptioner/core/translate翻译以及 videocaptioner/core/subtitle字幕样式渲染等目录各模块既可独立使用也可由process命令一键串联。项目同时提供CLI 命令行与GUI 桌面版两种使用方式并额外内置Claude Code Skill允许 AI 编程助手直接调用 VideoCaptioner 处理视频。二、安装一条 pip 命令免费功能开箱即用pip install videocaptioner # 安装 CLI GUI 桌面版安装后即可使用所有免费功能无需任何 API Key 或额外配置必剪语音识别bijian免费 ASR 引擎必应翻译bing与谷歌翻译google免费翻译服务。只有需要 LLM 参与的功能字幕优化、大模型翻译、反思式翻译等时才需要配置 LLM API Key。GUI 桌面版的启动方式见下文Windows 用户还可以从官方 Release 下载独立安装包macOS 用户可通过仓库中的 scripts/run.sh 一键脚本安装。三、CLI 命令行核心命令与完整参数CLI 入口实现在 videocaptioner/cli/main.py通过argparse构建了gui、transcribe、subtitle、dub、synthesize、process、download、style、config、doctor共十个子命令。运行videocaptioner 命令 --help可查看每个命令的完整参数。3.1 transcribe — 语音转字幕将音视频文件转为字幕文件支持 mp3/wav/mp4/mkv 等格式视频会自动提取音频videocaptioner transcribe video.mp4 --asr bijian主要参数选项说明--asrASR 引擎bijian默认免费、jianying免费、whisper-api、whisper-cpp。bijian/jianying 仅支持中英文其他语言请用 whisper-api 或 whisper-cpp--language CODE源语言 ISO 639-1 代码如zh、en、ja或auto默认自动检测--word-timestamps输出词级时间戳配合字幕断句使用--whisper-api-key/--whisper-api-baseWhisper API 密钥与地址仅--asr whisper-api--whisper-modelWhisper 模型名whisper-api 默认whisper-1whisper-cpp 默认large-v2-o PATH输出文件或目录路径--format输出格式srt默认、ass、txt、json从源码看除上述公开参数外videocaptioner/cli/main.py 还以隐藏参数形式支持 Faster-Whisper 本地引擎的高级选项--fw-model、--fw-device、--fw-vad-method、--fw-vad-threshold、--fw-prompt、--fw-voice-extraction对应 videocaptioner/core/asr/faster_whisper.py 的实现可通过videocaptioner config set transcribe.faster_whisper.model ...等配置项使用。3.2 subtitle — 字幕优化与翻译对字幕文件进行最多三步处理断句Split— 按语义边界重新分割字幕LLM优化Optimize— 修正 ASR 识别错误、标点与格式LLM翻译Translate— 翻译到目标语言LLM / 必应 / 谷歌。默认开启优化与断句、关闭翻译指定--translator或--target-language即自动开启翻译# 翻译字幕免费必应翻译 videocaptioner subtitle input.srt --translator bing --target-language en # 使用大模型优化并反思式翻译 videocaptioner subtitle input.srt --translator llm --reflect --layout target-above主要参数选项说明--translator翻译服务llm默认、bing免费、google免费--target-language CODE目标语言 BCP 47 代码zh-Hans、en、ja、ko、fr、de等--no-optimize/--no-translate/--no-split分别跳过优化、翻译、断句--reflect反思式翻译仅 LLM质量更高但更慢--layout双语布局target-above、source-above、target-only、source-only--prompt TEXT自定义提示词辅助 LLM 优化/翻译--api-key/--api-base/--modelLLM 密钥、接口地址、模型名也可用环境变量--max-cjk/--max-english单行最大字符/单词数默认 CJK 18、英文 12--thread-num/--batch-size并发线程数默认 4与批处理大小默认 203.3 synthesize — 字幕合成到视频将字幕烧录到视频中支持软字幕嵌入轨道与硬字幕烧录画面两种模式videocaptioner synthesize video.mp4 -s subtitle.srt --subtitle-mode hard选项说明-s FILE必填字幕文件.srt/.ass--subtitle-modesoft默认嵌入可选字幕轨道或hard永久烧录进画面--quality视频质量ultra(CRF18)、high(CRF23)、medium(默认,CRF28)、low(CRF32)--layout双语字幕布局--style NAME样式预设运行videocaptioner style查看--style-override JSON内联 JSON 覆盖样式字段如{outline_color: #ff0000}--render-mode渲染模式ass默认描边样式或rounded圆角背景--font-file PATH自定义字体文件.ttf/.otf两种字幕渲染模式让硬字幕更美观ASS 模式默认— 传统描边/阴影样式支持自定义字体、颜色、描边宽度# 使用动漫风格预设 videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard --style anime # 自定义红色描边与字号 videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard \ --style-override {outline_color: #ff0000, font_size: 48}圆角背景模式— 现代圆角矩形背景支持自定义背景色、圆角半径、内边距videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard --render-mode rounded # 白字红底、圆角 12 videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard \ --style-override {text_color: #ffffff, bg_color: #ff000099, corner_radius: 12}样式选项仅对硬字幕--subtitle-mode hard生效软字幕由播放器自行渲染。圆角背景模式的默认参数定义在 videocaptioner/core/subtitle/styles.py背景色默认#191919C8半透明深灰、文字#FFFFFF、圆角半径 12、水平/垂直内边距 28/14、底部外边距 60、行间距 10均支持通过--style-override覆盖。3.4 dub — 字幕配音根据字幕时间轴生成配音音轨可选把音轨写回视频。普通 SRT 可直接使用多说话人场景可在字幕文本中标注说话人[Alice] 你好今天开始测试。 Bob: This line uses another voice.# Edge TTS默认无需 API key依赖网络 videocaptioner dub input.srt --preset edge-cn-female -o output.wav # SiliconFlow CosyVoice2 videocaptioner dub input.srt --preset siliconflow-cn-female \ --tts-api-key $VIDEOCAPTIONER_TTS_API_KEY -o output.wav # Gemini TTS videocaptioner dub input.srt --preset gemini-en-friendly \ --tts-api-key $VIDEOCAPTIONER_TTS_API_KEY -o output.wav # 多说话人音色映射并输出视频 videocaptioner dub input.srt --video video.mp4 \ --speaker-voice Aliceanna \ --speaker-voice Bobbenjamin \ -o video_dubbed.mp4选项说明--preset配音预设如siliconflow-cn-female、gemini-en-friendly、edge-cn-female--tts-api-keyTTS API key。SiliconFlow/Gemini 需要Edge TTS 不需要--voice默认音色。SiliconFlow 可用anna、alex、benjaminGemini 使用Kore、Achird等Edge 可用xiaoxiao、yunxi或完整 voice ID--speak auto/first/second双语字幕时选择朗读第一行还是第二行--speaker-voice NAMEVOICE给字幕中的说话人指定音色可重复--speaker-clone NAMEAUDIO\|TEXTSiliconFlow 音色克隆参考音频与对应文本--clone-audio/--clone-text给默认说话人使用 SiliconFlow 音色克隆Gemini/Edge 不支持--timing balanced/strict/natural/none时间轴策略默认balancedstrict更贴字幕natural更保留自然语速--adapt-length使用 LLM 缩短明显过长的台词--audio-mode replace/mix/duck输出视频时替换原声、混合原声或压低原声作为背景命令会额外生成*.dubbing.json报告记录每句使用的说话人、音色、生成时长、变速倍数和时间轴 warning。各 TTS 提供商的预设、模型与音色别名定义在 videocaptioner/core/dubbing/presets.py例如 SiliconFlow 使用 CosyVoice2 模型FunAudioLLM/CosyVoice2-0.5BGemini 使用gemini-3.1-flash-tts-preview并内置 Kore、Achird 等数十种音色Edge 则将xiaoxiao、yunxi等别名映射到zh-CN-XiaoxiaoNeural等完整 voice ID。3.5 process — 全流程处理一键完成转录 → 断句 → 优化 → 翻译 → 合成支持上述所有命令的参数videocaptioner process video.mp4 --target-language ja额外选项选项说明--no-synthesize跳过视频合成只输出字幕--dub在转录/处理字幕后生成配音音轨或配音视频--dub-only只输出配音结果跳过字幕烧录/嵌入典型场景示例# 英文视频配成中文视频 videocaptioner process talk.mp4 \ --asr bijian \ --translator bing --to zh-Hans \ --dub-only \ --timing strict # 中文视频配成英文视频 videocaptioner process input.mp4 \ --translator bing --to en \ --dub-only \ --preset gemini-en-friendly \ --tts-api-key $VIDEOCAPTIONER_TTS_API_KEY音频文件作为输入时会自动跳过视频合成步骤。3.6 download / style / config / doctordownload— 下载在线视频videocaptioner download URL [-o 目录]支持 YouTube、B站等 yt-dlp 支持的所有平台style—videocaptioner style列出全部样式预设及其配置参数ASS 与圆角背景两种模式config— 配置管理子命令包括show、set、get、path、init、edit详见下文配置管理doctor— 环境诊断videocaptioner doctor检查 Python、FFmpeg/FFprobe、yt-dlp、配置文件及 ASR/LLM/翻译/配音关键配置缺失项会给出对应修复命令--json输出机器可读结果便于 Agent/CI 集成--check-api可额外执行轻量的提供商 API 连通性检查。3.7 通用选项与退出码所有命令均支持选项说明-v/--verbose详细输出-q/--quiet静默模式仅输出结果路径适合管道使用--config FILE指定配置文件退出码定义见 videocaptioner/cli/exit_codes.py码含义0成功1一般错误2参数/配置错误3输入文件不存在4依赖缺失FFmpeg 等5运行时错误API 失败等四、GUI 桌面版pip install videocaptioner videocaptioner-gui # 显式打开桌面版 videocaptioner gui # 等价命令 videocaptioner # 无参数时也会打开桌面版从 videocaptioner/cli/main.py 的main()实现可以看到当不带任何子命令运行时CLI 会直接调用_run_gui启动桌面版若 GUI 依赖缺失未安装完整包则会提示安装官方包并返回依赖缺失退出码4。GUI 界面源码位于 videocaptioner/ui 目录包括任务创建、字幕编辑、批量处理、样式设置、日志查看等完整界面模块。五、LLM API 配置LLM 仅用于字幕优化和大模型翻译免费功能必剪识别、必应翻译无需任何配置。项目支持所有OpenAI 兼容接口的服务商包括 DeepSeek、SiliconCloud 等平台。在软件设置或 CLI 中填入 API Base URL 和 API Key 即可videocaptioner config set llm.api_key your-key videocaptioner config set llm.api_base https://api.openai.com/v1 videocaptioner config set llm.model gpt-4o-mini更完整的 LLM 配置说明可参考 docs/config/llm.md翻译器配置见 docs/config/translator.mdASR 配置见 docs/config/asr.md。六、Claude Code Skill让 AI 编程助手直接处理视频本项目提供了 skills/SKILL.md 作为 Claude Code Skill使 AI 编程助手可以直接调用 VideoCaptioner 处理视频。安装到 Claude Codemkdir -p ~/.claude/skills/videocaptioner cp skills/SKILL.md ~/.claude/skills/videocaptioner/SKILL.md然后在 Claude Code 中输入/videocaptioner transcribe video.mp4 --asr bijian即可让 AI 助手完成视频转录等操作。七、工作原理从源码看四个关键机制7.1 语音识别模板方法 磁盘缓存 公益限流所有 ASR 引擎都继承自 videocaptioner/core/asr/base.py 中的BaseASR基类采用模板方法模式子类只需实现_run()调用识别服务与_make_segments()将响应转为ASRDataSeg段列表。基类统一提供三项能力格式校验与 CRC32 文件指纹支持 flac/m4a/mp3/wav 音频格式读取文件后计算 CRC32 作为缓存键self.crc32_hex子类可通过重写_get_key()加入更多参数两级磁盘缓存run()方法先查缓存命中则直接返回未命中则调用_run()并将结果写入缓存有效期 2 天同一文件重复识别几乎零成本公益服务限流针对必剪、剪映等免费公共接口内置调用次数与总时长双重限制默认 100 次调用 / 360 分钟总时长 / 12 小时窗口通过 SQLite 缓存表记录每次调用的音频时长超出即抛出运行时错误防止滥用。识别结果统一封装为ASRData位于 videocaptioner/core/asr/asr_data.py携带时间戳、词级时间戳等结构化信息供下游断句、优化模块消费。7.2 字幕断句语义理解 规则兜底断句模块 videocaptioner/core/split/split.py 的核心目标是让字幕按语义自然断行而非机械按时间切分。其实现要点包括LLM 语义断句长文本超过约 500 字的片段交由 LLM 依据语义切分videocaptioner/core/split/split_by_llm.py规则兜底对短片段按时间间隔、词数等规则合并/分割源码中定义了丰富的阈值常量例如 CJK 单行最大 25 字、英文单行最大 18 词、允许的最大时间间隔 1500ms、短段合并阈值 200ms、规则分割时间间隔阈值 500ms 等预处理移除纯标点片段为英语、俄语等空格分隔语言补空格并支持大小写归一化对齐修复结合 videocaptioner/core/split/alignment.py 的SubtitleAligner在优化/断句后自动对齐原始时间轴避免文本错位。7.3 字幕优化Agent 循环自动验证与修正videocaptioner/core/optimize/optimize.py 中的SubtitleOptimizer使用 LLM 优化字幕内容支持Agent loop 自动验证与修正通过difflib对比优化前后文本发现异常如大量增删、编号错乱时最多自动重试修正MAX_STEPS 3并配合json_repair修复 LLM 返回的残缺 JSON并发批量处理基于ThreadPoolExecutor的线程池线程数与批大小可配置并在atexit注册清理函数确保进程退出时资源正确释放自适应拆分对超长字幕自动分组后再逐批优化兼顾质量与成本。7.4 翻译工厂模式统一接入四种服务videocaptioner/core/translate/factory.py 中的TranslatorFactory.create_translator()按类型创建翻译器实例统一封装 LLMOpenAI 兼容、Google、Bing、DeepLX 四种翻译器并提供线程数、批大小、目标语言、自定义提示词、反思模式等公共参数。其中LLM 翻译默认模型gpt-4o-mini支持上下文感知与反思式翻译--reflect对应提示词模板位于 videocaptioner/core/prompts/translate含 standard、reflect、single 三个模板Bing / Google免费翻译工厂内部自动调整批大小Google/DeepLX 为 5Bing 为 10并设置合理的请求超时。八、配置管理四级优先级与环境变量配置优先级为命令行参数 环境变量VIDEOCAPTIONER_* 配置文件 默认值。该优先级在 videocaptioner/cli/main.py 的_build_cli_overrides()与_load_config()中实现——每个命令的 CLI 参数被收集为嵌套 override 字典如llm.api_key、transcribe.asr、dubbing.preset再与配置文件、环境变量逐层合并。运行videocaptioner config show可查看最终生效的完整配置。8.1 配置文件位置与初始化配置文件位于~/.config/videocaptioner/config.tomlmacOS/Linux。推荐先运行videocaptioner config init videocaptioner doctor非交互环境Agent/CI可这样初始化videocaptioner config init --non-interactive --profile dubbing \ --translator bing \ --timing balanced --audio-mode replaceconfig init还支持--print-template输出带注释的模板、--force覆盖已有配置以及--llm-api-key、--asr、--dub-preset、--voice等完整初始化参数。8.2 环境变量变量说明OPENAI_API_KEY/OPENAI_BASE_URL/OPENAI_MODELLLM 密钥、地址、模型名VIDEOCAPTIONER_DUB_PRESET配音预设VIDEOCAPTIONER_TTS_API_KEY/VIDEOCAPTIONER_TTS_API_BASE/VIDEOCAPTIONER_TTS_MODEL/VIDEOCAPTIONER_TTS_VOICE配音 TTS 的密钥、地址、模型、默认音色VIDEOCAPTIONER_TTS_WORKERS并发 TTS 请求数VIDEOCAPTIONER_DUB_TIMING配音时间轴策略VIDEOCAPTIONER_DUB_AUDIO_MODE原声处理方式VIDEOCAPTIONER_TTS_MAX_SPEED配音最大变速倍数VIDEOCAPTIONER_TTS_REWRITE_TOO_LONG是否启用 LLM 缩短过长台词8.3 配置文件示例TOML[llm] api_key sk-xxx api_base https://api.openai.com/v1 model gpt-4o-mini [transcribe] asr bijian [subtitle] optimize true split true [translate] service bing [dubbing] preset edge-cn-female api_key voice xiaoxiao timing balanced audio_mode replace tts_workers 5运行videocaptioner config show可查看全部配置项config set key value支持点号路径直接写入如videocaptioner config set llm.api_key your-key。九、开发与测试仓库使用uv管理 Python 依赖与虚拟环境开发流程如下git clone https://github.com/WEIFENG2333/VideoCaptioner.git cd VideoCaptioner uv sync uv run videocaptioner # 运行 GUI uv run videocaptioner --help # 运行 CLI uv run pyright # 类型检查 uv run pytest tests/test_cli/ -q # 运行测试测试覆盖非常全面tests/test_asr覆盖必剪、剪映、Whisper API 等各 ASR 引擎及分块识别、块合并tests/test_translate覆盖 Bing、Google、DeepLX、LLM 翻译器与缓存校验tests/test_dubbing覆盖 Edge TTS 提供商、管线与预设另有tests/test_split、tests/test_optimize、tests/test_subtitle、tests/test_tts、tests/test_thread等分别验证断句、优化、ASS 渲染、TTS 与多线程流水线。测试夹具样例音频与字幕位于 tests/fixtures可用于快速验证各命令行为。十、许可证项目以 GPL-3.0 协议开源可自由查看源码、学习与二次开发。【免费下载链接】VideoCaptioner 卡卡字幕助手 | VideoCaptioner - 基于 LLM 的智能字幕助手 - 视频字幕生成、断句、校正、字幕翻译全流程处理- A powered tool for easy and efficient video subtitling.项目地址: https://gitcode.com/gh_mirrors/vi/VideoCaptioner创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考