VideoCaptioner Agent 化接入指南基于 CLI-Anything 的语音识别、字幕翻译与视频合成全流程【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读VideoCaptioner 是一款 AI 驱动的视频字幕工具提供从语音识别ASR到样式化字幕合成的完整流水线。本文以 VIDEOCAPTIONER.md 为核心骨架结合 CLI-Anything 仓库中videocaptioner/agent-harness的源码实现讲解如何通过子进程包装Subprocess Wrapper策略将 VideoCaptioner 生产级 CLI 接入 Agent 环境并逐层剖析transcribe识别、subtitle字幕处理、synthesize视频合成与process全流水线四大命令的完整用法、JSON 结构化输出、REPL 交互模式以及字幕/脚本一致性校验等实战能力。一、架构总览从 CLI 到 Agent 的桥接1.1 为什么选择子进程包装而非重新实现VideoCaptioner 本身已发布为独立 CLI 包pip install videocaptioner并提供清晰、稳定的命令接口。相比逆向解析内部格式CLI-Anything 采取四层包装策略详见 VIDEOCAPTIONER.md 的 CLI Strategy 一节Click 包装层提供 CLI-Anything 标准接口统一的子命令、选项、--help文本子进程后端所有实际工作委托给videocaptionerCLI 命令JSON 模式--json返回结构化输出供 Agent 直接消费REPL 模式交互式会话支持 tab 补全与历史记录。选择子进程包装的根本原因是上游 CLI 本身就是生产级交付物拥有 50 单元测试与 200 QA 测试用例以 7 个子命令覆盖完整流水线transcribe / subtitle / synthesize / process / styles / config / download提供清晰的--help文本与稳定的退出码如文件不存在时退出码为 3在 PyPI 上持续维护并自动化发布。包装而不重写可以完整继承这些质量属性。1.2 源码层面的桥接实现在仓库中这一策略被落实为两层结构命令层videocaptioner_cli.py 使用 Click 定义cli主组与全部子命令通过handle_error装饰器统一捕获RuntimeErrorJSON 模式下输出{error: ..., type: runtime_error}非 REPL 模式下以退出码 1 终止后端层vc_backend.py 是唯一与上游 CLI 交互的模块所有 core 模块都经由它调用videocaptioner命令。vc_backend.py的核心函数包括函数作用_find_vc()通过shutil.which定位videocaptioner可执行文件找不到时抛出带安装指引的 RuntimeErrorrun(args, timeout600)以subprocess.run执行命令并返回{exit_code, stdout, stderr, output_path, command}结构化结果run_quiet(args, timeout600)追加-q参数运行并以 stdout 返回输出文件路径非零退出码时抛 RuntimeErrorget_version()/get_config()透传--version与config showhas_subcommand(cmd)/get_styles()探测后端是否暴露style子命令用于样式能力探测运行环境限制务必注意上游videocaptioner1.4.1 声明Requires-Python: 3.10,3.13仓库中的vc_backend.py也硬编码了UPSTREAM_REQUIRES_PYTHON 3.10,3.13推荐使用 Python 3.10–3.12优先 3.12Python 3.13 对该技术栈并非安全默认值。session status命令会同时输出当前 Python 运行时版本与上游兼容性指引。二、安装与前置条件2.1 安装步骤python3.12 -m pip install videocaptioner click prompt-toolkit pip install cli-anything-videocaptioner其中cli-anything-videocaptioner是仓库中 setup.py 定义的分发包其install_requires声明click8.0.0、prompt-toolkit3.0.0与videocaptioner并通过console_scripts注册cli-anything-videocaptionercli_anything.videocaptioner.videocaptioner_cli:main入口。2.2 前置依赖Python3.10–3.12上游 1.4.1 要求videocaptioner 包必须单独安装harness 本身不内置上游实现FFmpeg视频合成烧录字幕必需硬字幕样式尤其依赖 FFmpegLLM 能力可选字幕优化、语义切分与 LLM 翻译需要 OpenAI 兼容 API Key。验证安装是否就绪videocaptioner --version cli-anything-videocaptioner --help仓库的端到端测试 test_full_e2e.py 在videocaptioner未安装时会整体跳过pytestmark pytest.mark.skipif(shutil.which(videocaptioner) is None, ...)这也印证了上游依赖的必要性。三、Transcription四引擎语音识别3.1 命令语法与参数cli-anything-videocaptioner transcribe input_path \ [--asr bijian|jianying|whisper-api|whisper-cpp] \ [--language CODE] [--format srt|ass|txt|json] \ [-o PATH] [--word-timestamps] \ [--whisper-api-key KEY] [--whisper-api-base URL] [--whisper-model NAME]3.2 四种 ASR 引擎对比源文档完整继承引擎语言支持特点bijian默认中文 英文免费、无需任何配置jianying中文 英文免费、无需任何配置whisper-api全部语言OpenAI 兼容 API需--whisper-api-keywhisper-cpp全部语言本地模型推理参数细节来自 videocaptioner_cli.py 与 transcribe.py--language源语言 ISO 639-1 代码默认auto自动检测--format输出格式srt默认/ass/txt/json--word-timestamps输出词级时间戳whisper 系引擎适用--whisper-api-key/--whisper-api-base/--whisper-model仅whisper-api引擎需要可自定义端点与模型名。3.3 实操示例# 免费中英文识别输出 srt cli-anything-videocaptioner transcribe video.mp4 --asr bijian -o output.srt # 本地 Whisper 模型识别带词级时间戳 cli-anything-videocaptioner transcribe video.mp4 --asr whisper-cpp --word-timestamps # OpenAI 兼容 API 识别 cli-anything-videocaptioner transcribe video.mp4 --asr whisper-api \ --whisper-api-key $KEY --whisper-model large-v3从源码看transcribe.py 只是按需拼装参数列表并调用run_quiet([transcribe, input_path, --asr, ...])最终经vc_backend追加-q以安静模式返回输出文件路径。四、SubtitleLLM 切分、优化与多引擎翻译4.1 命令语法与三步处理cli-anything-videocaptioner subtitle input_path \ [--translator llm|bing|google] [--target-language CODE] \ [--format srt|ass|txt|json] [-o PATH] \ [--layout target-above|source-above|target-only|source-only] \ [--no-optimize] [--no-translate] [--no-split] \ [--reflect] [--prompt TEXT] \ [--api-key KEY] [--api-base URL] [--model NAME]该命令默认执行三个步骤翻译默认关闭需显式指定Split切分通过 LLM 按语义边界重新分段Optimize优化通过 LLM 修复 ASR 误识别、标点与格式问题Translate翻译转换到目标语言需--translator或--target-language触发。三个--no-*开关可分别跳过对应步骤--reflect开启反思式翻译仅 LLM质量更高--prompt可自定义 LLM 提示词。4.2 翻译能力3 种翻译器llmOpenAI 兼容 LLM、bing免费、google免费38 种目标语言使用 BCP 47 代码如zh-Hans、zh-Hant、en、ja、ko、fr、de、es、ru、pt、it、ar、th、vi、id等双语布局target-above译文在上、source-above原文在上、target-only仅译文、source-only仅原文。4.3 实操示例# 免费 Google 翻译到日语 cli-anything-videocaptioner subtitle input.srt --translator google --target-language ja # 双语字幕原文在上、译文在下 cli-anything-videocaptioner subtitle input.srt --translator bing --target-language en \ --layout source-above # LLM 反思式翻译并跳过切分 cli-anything-videocaptioner subtitle input.srt --translator llm --target-language ja \ --reflect --no-split --api-key $OPENAI_KEY --model gpt-4o参数拼装逻辑见 subtitle.py只有显式提供的选项才会追加到上游参数列表未提供的保持上游默认行为。五、Synthesize软字幕 / 硬字幕与质量档位5.1 命令语法cli-anything-videocaptioner synthesize video_path -s subtitle_path \ [--subtitle-mode soft|hard] \ [--quality ultra|high|medium|low] \ [-o PATH] \ [--review-script PATH] [--max-script-diff-ratio FLOAT]5.2 关键选项--subtitle-modesoft软字幕作为可切换的嵌入轨道默认或hard硬字幕烧录进视频帧--quality四档画质 ——ultraCRF 18、highCRF 23、mediumCRF 28默认、lowCRF 32--review-script参考脚本/转写文本路径。提供后harness 会在最终合成前校验字幕与脚本的一致性drift--max-script-diff-ratio允许的字幕/脚本最大漂移比例默认0.12。当交付要求拷贝精度高于容错时应调低该值。5.3 样式控制与后端版本依赖源文档列出的样式能力包括ASS 风格传统描边/阴影带预设default、anime、verticalRounded 风格现代圆角背景框内联 JSON 覆盖可覆盖任意样式参数。需要特别说明的是这些高级样式属于上游后端能力。当前仓库实现中synthesize.py 刻意只暴露稳定的合成面subtitle-mode、quality、output并将layout、render_mode、style、style_override、font_file标记为废弃兼容参数——因为后端 1.4.x 不在合成期支持样式旗标样式由字幕资产本身与后端版本共同决定而不是由 harness 额外旗标控制。因此用styles子命令探测已安装后端是否暴露样式预设底层通过has_subcommand(style)判断不支持时给出明确说明在合成为永久交付物前务必用review或synthesize --review-script拦截字幕漂移。5.4 实操示例# 硬字幕烧录中档画质 cli-anything-videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard # 高画质软字幕轨道 cli-anything-videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode soft --quality high # 硬烧前先做脚本一致性校验漂移超过 10% 即失败 cli-anything-videocaptioner synthesize video.mp4 -s sub.srt \ --subtitle-mode hard \ --review-script approved_script.txt \ --max-script-diff-ratio 0.10从源码看synthesize在review_script提供时会先调用ensure_subtitle_consistency位于core/review模块做一致性检查通过后才执行烧录。六、Process一条命令跑完全流水线6.1 命令语法cli-anything-videocaptioner process input_path \ [--asr ...] [--language CODE] \ [--translator llm|bing|google] [--target-language CODE] \ [--subtitle-mode soft|hard] [--quality ultra|high|medium|low] \ [--layout ...] [-o PATH] \ [--no-optimize] [--no-translate] [--no-split] [--no-synthesize] \ [--reflect] [--prompt TEXT] [--api-key KEY] [--api-base URL] [--model NAME]6.2 流水线阶段Audio/Video → ASR 识别 → 语义切分 → LLM 优化 → 翻译(38 语言) → 视频合成process将 transcribe → optimize → translate → synthesize 四个阶段合并为一次调用。音频文件输入时会自动跳过视频合成阶段源码 docstring 明确说明 Audio files automatically skip video synthesis。6.3 实操示例# 中文视频 → 英文硬字幕全自动 cli-anything-videocaptioner process video.mp4 --asr bijian \ --translator bing --target-language en --subtitle-mode hard # 只跑识别翻译不合成视频 cli-anything-videocaptioner process video.mp4 --asr bijian \ --translator google --target-language ja --no-synthesize参数装配逻辑见 pipeline.py与各单步命令一致仅当选项被显式提供时才追加到上游参数列表最后通过run_quiet得到输出路径。七、一致性校验Review 命令与合成前置拦截7.1 review 命令cli-anything-videocaptioner review subtitle_path \ [--script PATH] [--max-diff-ratio FLOAT] \ [--preview-video PATH] [--preview-at TIMECODE] [--preview-output PATH]--script参考脚本/转写文本文件--max-diff-ratio允许的最大字幕/脚本漂移比例默认0.12--preview-video用于渲染预览帧的视频--preview-at预览帧时间戳默认00:00:05.000--preview-output预览帧输出 PNG/JPG 路径。review 命令会输出一致性报告JSON 模式下为结构化 report包含status字段pass/fail并且可以在不产出完整成片的情况下渲染单帧预览用于硬烧前的视觉确认。7.2 为什么需要 drift 校验硬字幕一旦烧录便不可撤销。字幕文件若与已批准的脚本approved script偏离过多漏句、乱序、翻译过度直接硬烧会造成不可挽回的交付事故。通过synthesize --review-script与review命令可以在烧录前自动拦截偏离。从 synthesize.py 可以看到该校验位于实际烧录命令之前是合成流程的内置安全阀。7.3 实操示例# 渲染第 5 秒的预览帧用于人工确认 cli-anything-videocaptioner review sub.srt \ --script approved_script.txt \ --preview-video video.mp4 \ --preview-output review_5s.png # 硬烧前置校验 cli-anything-videocaptioner synthesize video.mp4 -s sub.srt \ --subtitle-mode hard \ --review-script approved_script.txt八、Agent 交互模式JSON 输出、REPL 与实用工具8.1 JSON 结构化输出所有命令都支持在顶层使用--json获取机器可读输出这是 Agent 消费的核心接口cli-anything-videocaptioner --json transcribe video.mp4 --asr bijian # {output_path: /path/to/output.srt}错误场景下同样结构化返回{error: ..., type: runtime_error}。styles、config show、session status等命令在 JSON 模式下分别输出{styles: ...}、{config: ...}、包含版本号与运行时指引的字典。8.2 REPL 交互模式不带子命令直接启动即进入交互式 REPLcli-anything-videocaptionerREPL 基于prompt-toolkit实现见 repl_skin.py 的ReplSkin支持命令 tab 补全与历史记录内置命令表transcribe、subtitle、synthesize、review、process、styles、config show|set、download、session status、help、quit交互式输入经shlex.split解析后复用同一个cli.main分派见 videocaptioner_cli.py。REPL 模式下错误不会导致进程退出_repl_mode为真时handle_error只打印错误不sys.exit适合 Agent 多步操作同一会话。8.3 配置管理与视频下载# 查看当前配置TOML 配置 环境变量 cli-anything-videocaptioner config show # 设置配置项 cli-anything-videocaptioner config set key value # 下载在线视频YouTube、Bilibili 等 cli-anything-videocaptioner download URL [-o DIR] # 查看样式预设可用性 cli-anything-videocaptioner stylesconfig set底层透传videocaptioner config set key value非零退出码时抛 RuntimeError见 videocaptioner_cli.py。九、测试策略与已知限制9.1 测试策略源文档完整继承单元测试mock 子进程调用验证参数构造正确性端到端测试使用真实videocaptionerCLI 与测试媒体文件前置条件必须安装videocaptioner与ffmpegE2E 测试在缺失上游命令时自动跳过见 test_full_e2e.py。9.2 已知限制限制说明上游依赖需单独安装videocaptioner包免费 ASR 局限bijian/jianying仅支持中文与英文LLM 依赖优化/切分/LLM 翻译需要 OpenAI 兼容 API Key硬字幕样式依赖 FFmpeg样式预设可用性取决于后端版本Python 版本上游要求 Python 3.10–3.12Python 3.13 不建议十、典型实战流程串联将上述命令串成一个完整的视频 → 双语硬字幕成片工作流# 1) 下载在线视频可选 cli-anything-videocaptioner download URL -o ./media # 2) 一键流水线中文识别 Bing 免费翻译 中档画质硬字幕 cli-anything-videocaptioner process ./media/video.mp4 \ --asr bijian --translator bing --target-language en \ --subtitle-mode hard --quality high # 3) 交付前一致性复查 预览帧 cli-anything-videocaptioner review output.srt \ --script approved_script.txt \ --preview-video ./media/video.mp4 --preview-output review_frame.pngAgent 场景下建议全程使用--json输出并在硬烧前用--review-script增加一层安全阀。本文所有命令与参数均可在仓库的 videocaptioner_cli.py、skills/SKILL.md 与 README.md 中找到对应实现与说明可作为进一步深入源码的入口。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考