# bili_caption_tools

**Repository Path**: Coding-years/bili_caption_tools

## Basic Information

- **Project Name**: bili_caption_tools
- **Description**: B站字幕工具集
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-17
- **Last Updated**: 2026-05-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# bili-caption-tools

> B站视频字幕下载、语音转文字 (ASR) 与 AI 摘要工具

结合 **Bilibili API**、**Whisper**（本地 / API）与 **DeepSeek**，一站式处理 B 站视频内容：

1. 自动抓取 B 站 **CC 字幕**（外挂字幕）
2. 若无字幕，自动下载音频并调用 **Whisper** 进行语音转文字
3. 将字幕文本交给 **DeepSeek** 生成摘要、要点列表（支持中 / 原文双语输出）

---

## ✨ 功能特性

- ✅ **B 站 CC 字幕获取** — 自动选择最佳语言（en → zh-CN → ...）
- ✅ **音频下载** — 自动选择最高质量音频流（Hi-Res → 192K → 132K → 64K），支持断点续传式进度显示
- ✅ **双模式 ASR（语音转文字）**
  - **本地模式** — 使用 [faster-whisper](https://github.com/SYSTRAN/faster-whisper)，支持 GPU (CUDA) 加速与 CPU 推理，自动检测设备
  - **API 模式** — 调用 OpenAI 兼容的 Whisper API（如硅基流动、OpenAI Whisper API 等）
- ✅ **三级 DeepSeek 调用策略**
  1. `deepseek-v4-flash` + 思考模式（reasoning）
  2. `deepseek-v4-flash` + 非思考模式（降级）
  3. `deepseek-v4-pro` 终极兜底
- ✅ **智能语言判断** — 自动检测字幕语言，支持原文输出 +（非中文时）中文翻译双重输出
- ✅ **命令行参数全面覆盖** — 所有配置均可通过 CLI 覆盖环境变量
- ✅ **Windows CUDA 自动适配** — 自动将 nvidia CUDA DLL 目录加入系统搜索路径，免去手动配置
- ✅ **强制 Whisper ASR** — 可通过 `--force-whisper` 或 `FORCE_WHISPER=true` 跳过 CC 字幕，直接走音频 ASR 流程

---

## 📦 安装

### 前置要求

- **Python ≥ 3.14**（`.python-version` 中指定，此为作者本地实测通过的版本；3.13 或其他版本请自行测试）
- [uv](https://docs.astral.sh/uv/)（推荐）或 pip

### 安装步骤

```bash
# 克隆仓库
git clone https://github.com/your-username/bili-caption-tools.git
cd bili-caption-tools

# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -e .
```

> **GPU 加速**（可选）：如需本地 GPU 推理，确保已安装 [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit) 和 [cuDNN](https://developer.nvidia.com/cudnn)。faster-whisper 会自动检测并使用 GPU。

---

## ⚙️ 配置

复制并编辑 `.env` 文件：

```bash
# 直接编辑 .env 文件
```

### 必需配置（B 站 Cookie）

| 变量 | 说明 | 获取方式 |
|------|------|----------|
| `BILI_SESSDATA` | B 站登录凭证 | 浏览器 DevTools → Application → Cookies → bilibili.com |
| `BILI_BILI_JCT` | CSRF Token | 同上 |
| `BILI_BUVID3` | 设备标识 | 同上 |

### 可选配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `BILI_BVID` | `BV1xx411c7XU` | 要处理的视频 BVID |
| `DEEPSEEK_API_KEY` | — | DeepSeek API Key（不填则跳过 AI 摘要） |
| `DEEPSEEK_REASONING` | `true` | 是否启用 DeepSeek 思考模式 |
| `ASR_MODE` | `local` | ASR 模式：`local`（本地）或 `api`（远程 API） |
| `ASR_API_KEY` | — | Whisper API Key（API 模式必填） |
| `ASR_BASE_URL` | `https://api.siliconflow.cn/v1` | API 端点地址 |
| `ASR_API_MODEL` | `FunAudioLLM/SenseVoiceSmall` | API 模型名 |
| `ASR_MODEL` | `base` | 本地模型名称（tiny/base/small/medium/large-v3） |
| `ASR_LANGUAGE` | `zh` | 语言提示（本地模式下代码已硬编码为自动检测，此变量无效） |
| `ASR_DEVICE` | `auto` | 推理设备：`auto` / `cuda` / `cpu` |
| `FORCE_WHISPER` | `false` | 设为 `true` 跳过 CC 字幕，强制音频 ASR |

---

## 🚀 使用

### 基本用法

```bash
# 使用 .env 中的默认 BVID，自动处理
python caption_tool.py

# 指定视频
python caption_tool.py --bvid BV1xx411c7XU

# 强制下载音频 + Whisper ASR（跳过 CC 字幕）
python caption_tool.py --force-whisper
```

### 指定 ASR 模型

```bash
# 本地模式：使用 small 模型
python caption_tool.py --force-whisper --model small

# 本地模式：使用 CUDA GPU
python caption_tool.py --force-whisper --device cuda

# API 模式：调用硅基流动 ASR
python caption_tool.py --bvid BV1xx411c7XU --asr-api --api-key sk-xxx --api-model FunAudioLLM/SenseVoiceSmall
```

### 输出模式

```bash
# 默认输出：原文总结 + 原文要点 +（非中文时）中文总结 + 中文要点
python caption_tool.py

# 仅输出原文总结
python caption_tool.py --summary --original

# 仅输出原文要点
python caption_tool.py --bullet --original

# 原文总结 + 原文要点 +（非中文时）中文总结 + 中文要点（与默认相同）
python caption_tool.py --summary --bullet

# 仅原文总结 +（非中文时）中文总结
python caption_tool.py --summary

# 仅原文要点 +（非中文时）中文要点
python caption_tool.py --bullet
```

### 控制 DeepSeek 思考模式

```bash
# 启用思考模式（默认跟随 DEEPSEEK_REASONING 环境变量）
python caption_tool.py --reasoning

# 禁用思考模式（使用普通生成）
python caption_tool.py --no-reasoning
```

---

## 📋 完整命令行参数

| 参数 | 简写 | 说明 |
|------|------|------|
| `--bvid` | `-b` | 视频 BVID，覆盖 `BILI_BVID` 环境变量 |
| `--force-whisper` | `-fw` | 强制使用 Whisper ASR，跳过 CC 字幕 |
| `--model` | `-m` | Whisper 模型大小：`base` / `small` / `medium` / `large-v3` |
| `--language` | `-l` | 语言代码（zh/en/ja 等） |
| `--device` | `-d` | 推理设备：`auto` / `cuda` / `cpu` |
| `--asr-api` | `-a` | 使用 API 模式而非本地模型 |
| `--api-key` | | Whisper API Key |
| `--api-url` | | Whisper API Base URL |
| `--api-model` | | API 模型名 |
| `--summary` | `-S` | 输出原文总结 +（非中文时）中文总结 |
| `--bullet` | `-B` | 输出原文要点 +（非中文时）中文要点 |
| `--original` | `-O` | 所有输出仅用字幕原文语言 |
| `--reasoning` | | 启用 DeepSeek 思考模式 |
| `--no-reasoning` | | 禁用 DeepSeek 思考模式 |

---

## 🧠 程序流程图

```mermaid
%%{init: {"flowchart": {"wrappingWidth": 250}}}%%
flowchart TD
    A["开始\n输入 BVID"] --> B{"验证 Cookie"}
    B -->|有效| C{"FORCE_WHISPER\n== true ?"}
    B -->|无效| X["退出"]
    C -->|是| D["下载音频"]
    C -->|否| E["尝试获取 CC 字幕"]
    E -->|成功| F["CC 字幕"]
    E -->|失败| D
    D --> G["Whisper ASR\n（本地 / API）"]
    G --> H["字幕文本"]
    F --> H
    H --> I["DeepSeek 三级策略\n① v4-flash + 思考 → 首选尝试\n② v4-flash 非思考 → 降级方案\n③ v4-pro temp=0.3 → 终极兜底"]
    I --> J["输出：摘要 / 要点列表\n（原文 · 中文 · 双语）"]
```

### DeepSeek 三级策略

| 级别 | 模型 | 模式 | 说明 |
|------|------|------|------|
| 1️⃣ | `deepseek-v4-flash` | 思考模式 (reasoning) | 首选，速度快且质量高 |
| 2️⃣ | `deepseek-v4-flash` | 普通生成 | 降级，思考模式失败或服务器忙时 |
| 3️⃣ | `deepseek-v4-pro` | 普通生成 (temp=0.3) | 终极方案，语言不匹配时自动升级至此 |

**语言自适应**：启用原文模式时，若检测到输出语言与字幕原文不一致，自动升级到 v4-pro 保证语言正确性。

---

## 🗂️ 项目结构

```
bili-caption-tools/
├── caption_tool.py       # 主程序（CLI 入口）
├── main.py               # 占位入口
├── pyproject.toml        # 项目依赖与元信息
├── .env                  # 本地配置文件（不提交）
├── .gitignore            # Git 忽略规则
├── .python-version       # Python 版本约束 (3.14)
├── downloads/            # 音频下载目录（自动创建）
└── README.md
```

---

## 📦 依赖

- `bilibili-api-python` — Bilibili API 封装
- `faster-whisper` — 本地 Whisper 推理引擎（基于 CTranslate2）
- `httpx` — 异步 HTTP 客户端
- `openai` — OpenAI / DeepSeek API 客户端
- `python-dotenv` — 环境变量加载
- `imageio-ffmpeg` — FFmpeg 绑定（faster-whisper 音频解码依赖）

---

## 📝 注意事项

1. **Python 版本**：项目 `.python-version` 指定为 **Python 3.14**，此为作者本地实测通过的版本。3.13 或其他版本请自行测试。
2. **B 站 Cookie 有效期**：SESSDATA 通常有效期约 30 天，过期后需要重新从浏览器获取。
3. **GPU 推理**：首次运行时会自动下载模型（约 150MB~3GB），可通过 `HF_ENDPOINT=https://hf-mirror.com` 镜像加速。
4. **API 模式**：使用硅基流动等第三方 API 时，注意账户余额。
5. **音频清理**：ASR 完成后会自动删除临时音频文件，无需手动清理。

---

## 📄 License

MIT