# subtitle-tool

**Repository Path**: exfire/subtitle-tool

## Basic Information

- **Project Name**: subtitle-tool
- **Description**: 一键把视频变成可检索的文字，让知识获取更高效。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# subtitle-tool

<p align="center">
  <img src="june_logo.png" width="120" alt="logo"/>
</p>

<p align="center">
  本地视频与 B 站视频字幕生成工具 · 无需命令行 · 开箱即用
</p>

<p align="center">
  <img src="https://img.shields.io/badge/platform-Windows-blue"/>
  <img src="https://img.shields.io/badge/python-3.11+-blue"/>
  <img src="https://img.shields.io/badge/license-MIT-green"/>
</p>

---

## 为什么做这个工具

AI 时代，视频是最密集的知识载体之一。但大量有价值的内容——技术讲座、行业访谈、外语教程——要么没有字幕，要么字幕质量堪忧。

**没有字幕意味着：**
- 无法快速扫读、跳过已知内容
- 外语视频难以理解细节
- 内容无法被搜索、复制、整理进笔记

这个工具的目标是：**一键把视频变成可检索的文字**，让知识获取更高效。

---

## 主界面

![主界面截图](docs/screenshots/main.png)

---

## 功能特性

- **本地视频**：ffmpeg 提取音频 → Whisper 转录，支持多文件批量处理
- **B 站视频**：优先获取官方 / AI 字幕（毫秒级完成）；无字幕时自动降级为音频下载 + Whisper 转录
- **多分 P 支持**：有官方字幕的分 P 直接获取，无字幕的分 P 自动转录，互不干扰
- **输出格式**：TXT（带时间戳）和 / 或 SRT，可同时生成
- **进度可视**：下载阶段动态动画，转录阶段实时百分比，完成后弹窗提醒
- **日志保存**：自动追加至 `subtitle_log.txt`，也可手动导出

---

## 下载使用（普通用户）

前往 [Releases](../../releases) 页面下载最新版压缩包，解压后双击 `subtitle-tool.exe` 运行，无需安装 Python 或任何依赖。

**首次运行**会自动下载 Whisper 语音识别模型，请保持网络连接：

| 模型 | 大小 | 速度 | 适用场景 |
|------|------|------|----------|
| small | 461 MB | 快 | 日常使用，推荐 |
| medium | 1.5 GB | 中 | 准确度要求较高 |
| large | 3 GB | 慢 | 最高精度 |

---

## 开发者安装

```bash
git clone https://github.com/xjdezhanghao/subtitle-tool.git
cd subtitle-tool
uv sync
uv run python app.py
```

**系统依赖：** 需在 PATH 中安装 [ffmpeg](https://ffmpeg.org/download.html)

---

## 功能说明

### 本地视频

在「本地视频」标签页添加视频文件，支持 mp4 / mkv / avi / mov 等主流格式，配置转录参数后点击「开始转换」。

![本地视频标签页](docs/screenshots/local.png)

### 线上视频（B 站）

在「线上视频」标签页粘贴 BV 号或完整链接，每行一个，点击「开始转换」。

![线上视频标签页](docs/screenshots/online.png)

勾选「使用官方 / AI 字幕」时，优先通过 B 站 API 获取现成字幕，成功则跳过下载和转录；失败或无字幕时自动回退至音频转录流程。

**获取 AI 字幕需要填写账号凭证：**

浏览器登录 B 站 → F12 → Application → Cookies → `https://www.bilibili.com`，
找到 `SESSDATA`、`bili_jct`、`buvid3`，将 Value 列的值填入对应输入框。CC 字幕（UP 主上传）通常无需凭证。

### 转录设置

| 设置项 | 说明 |
|--------|------|
| Whisper 模型 | tiny（最快）→ large（最准），推荐 small / medium |
| 自动检测 | 由 Whisper 判断语言 |
| 智能（非英文→中文） | 检测到非英文时强制以中文转录，适合普通话 / 粤语，避免被转成拼音 |
| 手动指定语言 | 跳过探测，直接以指定语言转录 |

### 模型缓存目录

「路径与保存」面板中可以自定义 **Whisper 模型缓存目录**。

- 默认位置：`C:\Users\你的用户名\.cache\whisper`
- **建议固定到一个有足够空间的目录**（如 `D:\AI\whisper-models`）
- 同一目录下的模型文件在重装工具、更新版本后可直接复用，无需重复下载
- 切换模型时只下载尚未缓存的，不会重复占用空间

### 进度与日志

- **总进度条**：显示已完成文件数 / 总数
- **当前文件进度条**：下载阶段显示动态动画，转录阶段显示 0–100% 实时进度
- 用时计时器实时更新，完成后弹窗提示（任务栏闪烁）
- 日志自动追加保存至应用目录 `subtitle_log.txt`，也可点击「另存为…」手动导出

---

## 注意事项

- Whisper 仅使用 CPU，`small` 模型约 0.5× 实时速度（10 分钟音频约 5 分钟）
- 点击「中断」后，当前文件会处理完再停止——Whisper 无法中途打断，这是库的限制
- B 站大会员视频若 yt-dlp 报错，属于权限问题，与本工具无关
- `config.json` 存储所有配置（含账号凭证），已加入 `.gitignore`，请勿手动提交

---

## 后续计划

欢迎感兴趣的朋友共同改进以下方向，或提出新想法：

- [ ] **更多线上平台支持**：抖音、YouTube、微博等（yt-dlp 已支持，字幕获取待适配）
- [ ] **更换 faster-whisper**：在相同 CPU 条件下速度提升约 4×，显存占用更低
- [ ] **界面优化**：更现代的 UI 风格，深色模式支持
- [ ] **多语言界面**：支持英文等界面语言
- [ ] **多 P 逐条进度**：显示多分 P 视频每一 P 的单独进度
- [ ] **打包优化**：减小发布包体积，提升首次启动速度

---

## 参与贡献

这个工具从一个人的实际需求出发，欢迎所有对视频处理、AI 工具感兴趣的朋友参与改进。

1. Fork 本仓库
2. 创建功能分支：`git checkout -b feature/your-feature`
3. 提交改动：`git commit -m 'feat: 描述你的改动'`
4. 推送分支：`git push origin feature/your-feature`
5. 发起 Pull Request

如有 bug 或建议，直接开 [Issue](../../issues) 即可。

---

## 项目结构

```
subtitle-tool/
├── app.py            # GUI 主程序（tkinter）
├── core.py           # 业务逻辑：ffmpeg / yt-dlp / Whisper / B站字幕
├── pyproject.toml    # 依赖与项目配置
├── uv.lock           # 依赖锁文件（保证可复现构建）
├── subtitle-tool.spec  # PyInstaller 打包配置
└── cleanup_dist.py   # 打包后清理脚本
```

## 主要依赖

| 包 | 用途 |
|----|------|
| openai-whisper | 语音转录 |
| torch / torchaudio | Whisper 运行时（CPU 版，无需 CUDA） |
| yt-dlp | 线上视频音频下载 |
| bilibili-api-python | B 站字幕 API |
| aiohttp | bilibili-api HTTP 后端 |

---

## License

MIT © [xjdezhanghao](https://github.com/xjdezhanghao)