VideoCaptioner

基于大语言模型的视频字幕处理工具 — 语音识别、字幕优化、翻译、视频合成一站式处理

在线文档 · CLI 使用 · GUI 桌面版 · Claude Code Skill

安装

pip install videocaptioner          # 仅安装 CLI（轻量，无 GUI 依赖）
pip install videocaptioner[gui]     # 安装 CLI + GUI 桌面版

免费功能（必剪语音识别、必应/谷歌翻译）无需任何配置，安装即用。

CLI 命令行

# 语音转录（免费，无需 API Key）
videocaptioner transcribe video.mp4 --asr bijian

# 字幕翻译（免费必应翻译）
videocaptioner subtitle input.srt --translator bing --target-language en

# 全流程：转录 → 优化 → 翻译 → 合成
videocaptioner process video.mp4 --target-language ja

# 字幕烧录到视频
videocaptioner synthesize video.mp4 -s subtitle.srt

# 下载在线视频
videocaptioner download "https://youtube.com/watch?v=xxx"

需要 LLM 功能（字幕优化、大模型翻译）时，配置 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

配置优先级：命令行参数 > 环境变量 (VIDEOCAPTIONER_*) > 配置文件 > 默认值。运行 videocaptioner config show 查看当前配置。

GUI 桌面版

pip install videocaptioner[gui]
videocaptioner                      # 无参数时自动打开桌面版

curl -fsSL https://raw.githubusercontent.com/WEIFENG2333/VideoCaptioner/master/scripts/run.sh | bash

LLM API 配置

LLM 仅用于字幕优化和大模型翻译，免费功能（必剪识别、必应翻译）无需配置。

支持所有 OpenAI 兼容接口的服务商：

在软件设置或 CLI 中填入 API Base URL 和 API Key 即可。详细配置教程

Claude Code Skill

本项目提供了 Claude Code Skill，让 AI 编程助手可以直接调用 VideoCaptioner 处理视频。

安装到 Claude Code：

mkdir -p ~/.claude/skills/videocaptioner
cp skills/SKILL.md ~/.claude/skills/videocaptioner/SKILL.md

然后在 Claude Code 中输入 /videocaptioner transcribe video.mp4 --asr bijian 即可使用。

工作原理

音视频输入 → 语音识别 → 字幕断句 → LLM 优化 → 翻译 → 视频合成

• 词级时间戳 + VAD 语音活动检测，识别准确率高
• LLM 语义理解断句，字幕阅读体验自然流畅
• 上下文感知翻译，支持反思优化机制
• 批量并发处理，效率高

开发

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      # 运行测试

许可证

GPL-3.0

VideoCaptioner 快速上手指南

VideoCaptioner 是一款基于大语言模型的视频字幕处理工具，提供语音识别、字幕优化、翻译及视频合成的一站式解决方案。支持免费引擎（必剪识别、必应/谷歌翻译）无需配置即可使用。

环境准备

• 操作系统：Windows / macOS / Linux
• Python 版本：建议 Python 3.8+
• 前置依赖：
  • 基础功能仅需安装 Python 环境。
  • 若使用 GUI 桌面版，需确保系统支持图形界面显示。
  • （可选）若需使用 LLM 高级功能（字幕润色、大模型翻译），需准备兼容 OpenAI 接口的 API Key。

安装步骤

方式一：通过 pip 安装（推荐）

仅安装 CLI 命令行版（轻量，无 GUI 依赖）：

pip install videocaptioner

安装 CLI + GUI 桌面完整版：

pip install videocaptioner[gui]

提示：国内用户若下载缓慢，可指定国内镜像源安装：

pip install videocaptioner[gui] -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：直接运行桌面版（Windows/macOS）

• Windows：前往 Release 页面 下载安装包直接安装。
• macOS：执行一键脚本安装：

  curl -fsSL https://raw.githubusercontent.com/WEIFENG2333/VideoCaptioner/master/scripts/run.sh | bash
  

基本使用

1. 启动 GUI 桌面版

安装完成后，直接在终端输入以下命令即可打开图形界面，适合新手可视化操作：

videocaptioner

2. CLI 命令行快速体验

场景 A：免费语音转录（无需 API Key） 使用必剪引擎将视频转为字幕：

videocaptioner transcribe video.mp4 --asr bijian

场景 B：免费字幕翻译 使用必应翻译将字幕译为英文：

videocaptioner subtitle input.srt --translator bing --target-language en

场景 C：全流程自动化处理 一键完成“转录 → 优化 → 翻译 → 合成”，目标语言设为日语：

videocaptioner process video.mp4 --target-language ja

场景 D：字幕烧录到视频 将字幕文件硬编码压制到视频中：

videocaptioner synthesize video.mp4 -s subtitle.srt

3. 配置 LLM（可选）

若需使用大模型进行字幕润色或高质量翻译，配置 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

推荐：可使用国内高速中转服务 https://api.videocaptioner.cn 作为 api_base，支持 GPT/Claude/Gemini 等模型。