## 1. Project Overview & Quickstart (WEIFENG2333/VideoCaptioner)

## File: README.md

## 安装

```bash
pip install videocaptioner          # 安装 CLI + GUI 桌面版
```

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

## CLI 命令行

```bash
# 语音转录（免费，无需 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：

```bash
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` 查看当前配置。


所有 CLI 命令一览

| 命令 | 说明 |
|------|------|
| `gui` | 打开桌面版。也可以直接运行 `videocaptioner-gui` |
| `transcribe` | 语音转字幕。引擎：`faster-whisper`、`whisper-api`、`bijian`（免费）、`jianying`（免费）、`whisper-cpp` |
| `subtitle` | 字幕优化/翻译。翻译服务：`llm`、`bing`（免费）、`google`（免费） |
| `dub` | 根据字幕生成配音音轨或配音视频 |
| `synthesize` | 字幕烧录到视频（软字幕/硬字幕） |
| `process` | 全流程处理 |
| `download` | 下载 YouTube、B站等平台视频 |
| `config` | 配置管理（`show`、`set`、`get`、`path`、`init`） |

运行 `videocaptioner <命令> --help` 查看完整参数。完整 CLI 文档见 [docs/cli.md](docs/cli.md)。



## GUI 桌面版

```bash
pip install videocaptioner
videocaptioner-gui                  # 显式打开桌面版
videocaptioner gui                  # 等价命令
videocaptioner                      # 无参数时也会打开桌面版
```


其他安装方式：Windows 安装包 / macOS 一键脚本

**Windows**：从 [Release](https://github.com/WEIFENG2333/VideoCaptioner/releases) 下载安装包

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









## LLM API 配置

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

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

| 服务商 | 官网 |
|--------|------|
| **VideoCaptioner 中转站** | [api.videocaptioner.cn](https://api.videocaptioner.cn) — 高并发，性价比高，支持 GPT/Claude/Gemini 等 |
| SiliconCloud | [cloud.siliconflow.cn](https://cloud.siliconflow.cn/i/HF95kaoz) |
| DeepSeek | [platform.deepseek.com](https://platform.deepseek.com) |

在软件设置或 CLI 中填入 API Base URL 和 API Key 即可。[详细配置教程](https://weifeng2333.github.io/VideoCaptioner/config/llm)

## Claude Code Skill

本项目提供了 [Claude Code Skill](https://code.claude.com/docs/en/skills.md)，让 AI 编程助手可以直接调用 VideoCaptioner 处理视频。

安装到 Claude Code：

```bash
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 语义理解断句，字幕阅读体验自然流畅
- 上下文感知翻译，支持反思优化机制
- 批量并发处理，效率高

## 开发

```bash
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](LICENSE)

[](https://star-history.com/#WEIFENG2333/VideoCaptioner&Date)

---

## File: docs/index.md

---
layout: page
title: VideoCaptioner - 基于LLM的智能视频字幕处理工具
titleTemplate: false
head:
  - - meta
    - name: keywords
      content: VideoCaptioner,卡卡字幕助手,视频字幕生成器,AI自动字幕,Whisper中文字幕,LLM字幕翻译,免费字幕工具,开源字幕软件,视频转文字,语音识别字幕,B站字幕生成,YouTube字幕工具,多语言字幕,字幕断句优化,视频字幕处理,自动生成字幕,字幕制作软件,视频配字幕
  - - meta
    - property: og:title
      content: VideoCaptioner - 基于LLM的智能视频字幕处理工具 | 免费开源
  - - meta
    - property: og:description
      content: 免费开源的AI视频字幕处理助手。支持Whisper语音识别、LLM智能断句与翻译、多语言字幕生成。适用于YouTube、B站等平台，支持99种语言。一键处理，专业质量。
  - - meta
    - property: og:url
      content: https://weifeng2333.github.io/VideoCaptioner/
  - - meta
    - property: og:type
      content: website
  - - meta
    - property: article:published_time
      content: 2024-01-01T00:00:00+08:00
  - - meta
    - property: article:modified_time
      content: 2025-01-25T00:00:00+08:00
  - - meta
    - name: twitter:title
      content: VideoCaptioner - AI Video Subtitle Tool | Free & Open Source
  - - meta
    - name: twitter:description
      content: Free AI-powered subtitle tool with Whisper & LLM. Supports 99 languages, intelligent segmentation, and professional translation.
---

<CustomHome />

---

## File: docs/README.md

# VideoCaptioner 文档

这是 VideoCaptioner 项目的文档源文件，使用 [VitePress](https://vitepress.dev/) 构建。

## 📚 在线查看

文档已自动部署到 GitHub Pages：

**[https://weifeng2333.github.io/VideoCaptioner/](https://weifeng2333.github.io/VideoCaptioner/)**

## 🚀 本地开发

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run docs:dev
```

访问 http://localhost:5173 查看文档

### 构建文档

```bash
npm run docs:build
```

构建产物位于 `docs/.vitepress/dist/`

### 预览构建结果

```bash
npm run docs:preview
```

## 📁 目录结构

```
docs/
├── .vitepress/
│   ├── config.mts          # VitePress 配置文件（含 SEO 优化）
│   └── theme/              # 自定义主题（可选）
├── public/                 # 静态资源（图片、Logo、robots.txt）
├── guide/                  # 中文使用指南
│   ├── getting-started.md
│   ├── configuration.md
│   └── ...
├── config/                 # 中文配置文档
│   ├── llm.md
│   ├── asr.md
│   └── ...
├── dev/                    # 中文开发者文档
│   ├── architecture.md
│   └── ...
├── en/                     # 英文文档（镜像中文结构）
│   ├── guide/
│   ├── config/
│   └── dev/
└── index.md                # 中文首页
```

## ✍️ 贡献文档

### 添加新页面

1. 在对应目录下创建 Markdown 文件
2. **添加 Frontmatter SEO 优化**（重要！）：

```markdown
---
title: 页面标题 - VideoCaptioner
head:
  - - meta
    - name: keywords
      content: 关键词1,关键词2,关键词3
---

# 页面标题

内容...
```

3. 在 `.vitepress/config.mts` 的 `sidebar` 中添加链接
4. 提交 PR

### 编辑现有页面

直接编辑 Markdown 文件即可，支持：

- **Markdown 扩展语法**：表格、代码块、提示框等
- **Vue 组件**：可在 Markdown 中使用 Vue 组件
- **自定义容器**：`::: tip`, `::: warning`, `::: danger`

示例：

```md
::: tip 提示
这是一个提示框
:::

::: warning 注意
这是一个警告框
:::

::: danger 危险
这是一个危险警告框
:::
```

### 文档规范

- **文件名**：使用小写字母和连字符（如 `getting-started.md`）
- **标题**：使用清晰的层级结构（# → ## → ###）
- **代码块**：标注语言类型以启用语法高亮
- **图片**：放在 `public/` 目录，使用 `/image.png` 引用
- **链接**：内部链接使用相对路径（如 `/guide/getting-started`）
- **SEO**：每个页面都应添加 title、description 和 keywords

## 🔍 SEO 优化

本文档系统已经过全面 SEO 优化，详情请查看 [SEO_OPTIMIZATION.md](../SEO_OPTIMIZATION.md)。

### 已实施的 SEO 功能

✅ **基础 SEO**

- Title 标签优化
- Meta Description 和 Keywords
- Open Graph（社交媒体卡片）
- Twitter Card
- JSON-LD 结构化数据
- Sitemap 自动生成
- robots.txt
- Canonical URL

✅ **技术 SEO**

- 响应式设计
- Clean URLs
- 快速加载（Vite 优化）
- HTTPS（GitHub Pages）

### 提交到搜索引擎

部署后需要手动提交到搜索引擎：

1. **Google Search Console**
   - 访问 https://search.google.com/search-console
   - 添加网站并验证
   - 提交 sitemap: `https://weifeng2333.github.io/VideoCaptioner/sitemap.xml`

2. **Bing Webmaster Tools**
   - 访问 https://www.bing.com/webmasters
   - 添加网站并验证
   - 提交 sitemap

3. **百度站长平台**
   - 访问 https://ziyuan.baidu.com/
   - 添加网站并验证
   - 提交 sitemap

### SEO 检查工具

- [Google PageSpeed Insights](https://pagespeed.web.dev/)
- [Google Rich Results Test](https://search.google.com/test/rich-results)
- [Open Graph Debugger](https://developers.facebook.com/tools/debug/)
- [Twitter Card Validator](https://cards-dev.twitter.com/validator)

## 🌐 多语言支持

文档支持中英双语：

- **中文**：`docs/` 根目录
- **英文**：`docs/en/` 目录

添加新语言：

1. 在 `docs/` 下创建语言目录（如 `ja/`）
2. 在 `.vitepress/config.mts` 中添加 locale 配置
3. 复制文档结构并翻译内容

## 🔧 技术栈

- **VitePress**: 基于 Vite 的静态站点生成器
- **Vue 3**: 组件化开发
- **TypeScript**: 类型安全的配置

## 📝 更新文档

文档更新会自动触发 GitHub Actions 部署：

1. 提交文档修改到 `docs/` 目录
2. 推送到 `master` 或 `main` 分支
3. GitHub Actions 自动构建并部署
4. 约 2-3 分钟后更新生效

## ❓ 常见问题

### 本地开发时看不到样式？

确保已安装依赖：

```bash
npm install
```

### 如何添加自定义样式？

在 `docs/.vitepress/theme/` 目录下创建自定义主题：

```ts
// docs/.vitepress/theme/index.ts
import DefaultTheme from "vitepress/theme";
import "./custom.css";

export default DefaultTheme;
```

### 如何配置搜索功能？

VitePress 默认提供本地搜索，已在 `config.mts` 中配置。

### 如何优化图片？

1. 使用图片压缩工具（如 TinyPNG）
2. 考虑使用 WebP 格式
3. 添加 `loading="lazy"` 属性

### 如何添加 Google Analytics？

在 `config.mts` 的 `head` 中添加：

```typescript
([
  "script",
  {
    async: true,
    src: "https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX",
  },
],
  [
    "script",
    {},
    `
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
`,
  ]);
```

---

更多 VitePress 使用方法请参考 [官方文档](https://vitepress.dev/)。

更多 SEO 优化细节请查看 [SEO_OPTIMIZATION.md](../SEO_OPTIMIZATION.md)。

## 2. Official Technical Reference & Guides (WEIFENG2333/WEIFENG2333.github.io)

## Welcome to GitHub Pages

You can use the [editor on GitHub](https://github.com/bkfeng/bkfeng.github.io/edit/main/README.md) to maintain and preview the content for your website in Markdown files.

Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files.

### Markdown

Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for

```markdown
Syntax highlighted code block

# Header 1
## Header 2
### Header 3

- Bulleted
- List

1. Numbered
2. List

**Bold** and _Italic_ and `Code` text

[Link](url) and 
```

For more details see [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/).

### Jekyll Themes

Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/bkfeng/bkfeng.github.io/settings). The name of this theme is saved in the Jekyll `_config.yml` configuration file.

### Support or Contact

Having trouble with Pages? Check out our [documentation](https://docs.github.com/categories/github-pages-basics/) or [contact support](https://github.com/contact) and we’ll help you sort it out.