bili-sub2txt 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bili_sub2txt-0.2.0/.gitignore +18 -0
- bili_sub2txt-0.2.0/LICENSE +21 -0
- bili_sub2txt-0.2.0/PKG-INFO +171 -0
- bili_sub2txt-0.2.0/README.en.md +143 -0
- bili_sub2txt-0.2.0/README.md +143 -0
- bili_sub2txt-0.2.0/pyproject.toml +50 -0
- bili_sub2txt-0.2.0/src/__init__.py +1 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/__init__.py +1 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/__main__.py +8 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/__init__.py +1 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/api.py +249 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/auth.py +148 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/fetcher.py +133 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/net.py +137 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/session.py +75 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/wbi.py +69 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/cli.py +155 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/converter.py +145 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/errors.py +49 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/naming.py +50 -0
- bili_sub2txt-0.2.0/src/bili_sub2txt/path_mapper.py +28 -0
- bili_sub2txt-0.2.0/tests/conftest.py +117 -0
- bili_sub2txt-0.2.0/tests/integration/test_conversion.py +315 -0
- bili_sub2txt-0.2.0/tests/integration/test_fetch.py +85 -0
- bili_sub2txt-0.2.0/tests/unit/test_api.py +181 -0
- bili_sub2txt-0.2.0/tests/unit/test_auth.py +117 -0
- bili_sub2txt-0.2.0/tests/unit/test_cli.py +185 -0
- bili_sub2txt-0.2.0/tests/unit/test_converter.py +181 -0
- bili_sub2txt-0.2.0/tests/unit/test_converter_bili.py +78 -0
- bili_sub2txt-0.2.0/tests/unit/test_errors.py +59 -0
- bili_sub2txt-0.2.0/tests/unit/test_fetcher.py +127 -0
- bili_sub2txt-0.2.0/tests/unit/test_main_module.py +43 -0
- bili_sub2txt-0.2.0/tests/unit/test_naming.py +41 -0
- bili_sub2txt-0.2.0/tests/unit/test_net.py +68 -0
- bili_sub2txt-0.2.0/tests/unit/test_path_mapper.py +81 -0
- bili_sub2txt-0.2.0/tests/unit/test_session.py +40 -0
- bili_sub2txt-0.2.0/tests/unit/test_wbi.py +57 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 folin (林惢朋)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: bili-sub2txt
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Convert Bilibili subtitles to plain text — local VTT conversion and BV-number download
|
|
5
|
+
Project-URL: Homepage, https://github.com/Lin-Ruipeng/bili-sub2txt
|
|
6
|
+
Project-URL: Repository, https://github.com/Lin-Ruipeng/bili-sub2txt
|
|
7
|
+
Project-URL: Issues, https://github.com/Lin-Ruipeng/bili-sub2txt/issues
|
|
8
|
+
Author-email: folin <Lin-Ruipeng@users.noreply.github.com>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: bilibili,bv,converter,subtitle,txt,vtt
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Multimedia :: Video
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: pytest>=7.0.0; extra == 'dev'
|
|
25
|
+
Provides-Extra: download
|
|
26
|
+
Requires-Dist: qrcode>=7.4; extra == 'download'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# bili-sub2txt
|
|
30
|
+
|
|
31
|
+
一款用于将 Bilibili 字幕转换为纯文本的 Python 工具。支持本地 VTT 文件批量转换,也可通过 BV 号直接下载 B 站字幕并转换。
|
|
32
|
+
|
|
33
|
+
## 功能特点
|
|
34
|
+
|
|
35
|
+
- 将 VTT 字幕文件转换为纯文本格式(去时间戳、去标记)
|
|
36
|
+
- 通过 BV 号或视频链接直接下载 B 站字幕(需登录)
|
|
37
|
+
- 扫码登录 B 站,登录态自动持久化
|
|
38
|
+
- 支持多 P 视频全量下载,文件名带序号前缀
|
|
39
|
+
- 支持指定字幕语言(`--lang`),未命中时列出所有可用轨道
|
|
40
|
+
- 字幕轨道自动选择(优先人工中文 → AI 中文 → 人工英文 → AI 英文)
|
|
41
|
+
- 递归处理整个目录结构,保留输出目录层级
|
|
42
|
+
- VTT 解析兼容规范变体(省略小时、逗号分隔符、cue 设置等)
|
|
43
|
+
|
|
44
|
+
## 安装
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# 基础安装(仅本地 VTT 转换,零第三方依赖)
|
|
48
|
+
pip install -e .
|
|
49
|
+
|
|
50
|
+
# 含下载功能(安装 qrcode 用于终端渲染二维码)
|
|
51
|
+
pip install -e ".[download]"
|
|
52
|
+
|
|
53
|
+
# 开发模式(含 pytest)
|
|
54
|
+
pip install -e ".[dev]"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## 使用方法
|
|
58
|
+
|
|
59
|
+
### 转换本地 VTT 文件
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
bili-sub2txt convert source_vtt/ target_txt/
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
- `source_vtt/`:含 `.vtt` 文件的输入目录(递归查找)
|
|
66
|
+
- `target_txt/`:TXT 输出目录(自动创建,保留目录结构)
|
|
67
|
+
|
|
68
|
+
### 下载 B 站字幕
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# 首次使用需扫码登录
|
|
72
|
+
bili-sub2txt login
|
|
73
|
+
|
|
74
|
+
# 通过 BV 号下载
|
|
75
|
+
bili-sub2txt fetch BV1jJ4m1J7ba
|
|
76
|
+
|
|
77
|
+
# 通过完整链接下载
|
|
78
|
+
bili-sub2txt fetch https://www.bilibili.com/video/BV1jJ4m1J7ba/
|
|
79
|
+
|
|
80
|
+
# 指定输出目录和字幕语言
|
|
81
|
+
bili-sub2txt fetch BV1jJ4m1J7ba --output my_output/ --lang zh-Hans
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**fetch 参数:**
|
|
85
|
+
- `target`:BV 号或视频链接(必需)
|
|
86
|
+
- `-o, --output DIR`:输出目录(默认 `target_txt/`,在其下建 `<BV号>/`)
|
|
87
|
+
- `--lang LAN`:指定字幕语言(如 `zh-Hans`、`ai-zh`、`ja`;未指定时自动选择)
|
|
88
|
+
|
|
89
|
+
### 其他
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
bili-sub2txt --help # 查看帮助
|
|
93
|
+
bili-sub2txt --version # 查看版本
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### 退出码
|
|
97
|
+
|
|
98
|
+
| 码 | 含义 |
|
|
99
|
+
|---|---|
|
|
100
|
+
| 0 | 成功 |
|
|
101
|
+
| 1 | 一般失败(无字幕、网络错误等) |
|
|
102
|
+
| 2 | 用法错误 |
|
|
103
|
+
| 3 | 需要登录 / 登录态失效 |
|
|
104
|
+
|
|
105
|
+
## 工作原理
|
|
106
|
+
|
|
107
|
+
### VTT 转换(convert)
|
|
108
|
+
|
|
109
|
+
1. CLI 递归查找输入目录中的所有 `.vtt` 文件
|
|
110
|
+
2. 解析 VTT 格式:按空行切分字幕块(块内多个时间戳再细分),丢弃 cue 标识符/`NOTE`/`STYLE`/`REGION` 块,剥离内联标记并解码 HTML 实体
|
|
111
|
+
3. 以单换行连接各字幕块,写入对应的 TXT 文件
|
|
112
|
+
|
|
113
|
+
### B 站下载(fetch + login)
|
|
114
|
+
|
|
115
|
+
1. `login`:调用 B 站 Web 端扫码登录接口,终端渲染二维码,扫码成功后提取 `SESSDATA` 并保存到配置文件
|
|
116
|
+
2. `fetch`:解析 BV 号 → 获取视频信息 → 对每个分 P 请求字幕列表 → 选择轨道 → 下载 JSON → 转换为纯文本 → 写入文件
|
|
117
|
+
3. 字幕时长与视频时长交叉校验(0.5–1.25 倍区间),超出则告警但不阻断
|
|
118
|
+
|
|
119
|
+
## 项目结构
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
bili-sub2txt/
|
|
123
|
+
├── src/bili_sub2txt/
|
|
124
|
+
│ ├── __init__.py # 版本信息
|
|
125
|
+
│ ├── __main__.py # python -m bili_sub2txt 入口
|
|
126
|
+
│ ├── cli.py # argparse 子命令(convert/fetch/login)
|
|
127
|
+
│ ├── converter.py # VTT 转 TXT + B站 JSON 转 TXT
|
|
128
|
+
│ ├── path_mapper.py # 路径转换工具
|
|
129
|
+
│ ├── errors.py # 异常体系、退出码、SESSDATA 脱敏
|
|
130
|
+
│ ├── naming.py # 文件名清洗与输出路径构造
|
|
131
|
+
│ └── bilibili/
|
|
132
|
+
│ ├── net.py # HTTP transport(可注入,支持离线测试)
|
|
133
|
+
│ ├── wbi.py # WBI 签名
|
|
134
|
+
│ ├── session.py # SESSDATA 持久化
|
|
135
|
+
│ ├── auth.py # 扫码登录状态机
|
|
136
|
+
│ ├── api.py # 视频信息、字幕轨道、下载
|
|
137
|
+
│ └── fetcher.py # fetch 编排与时长校验
|
|
138
|
+
├── tests/
|
|
139
|
+
│ ├── conftest.py # FakeTransport 测试 fixture
|
|
140
|
+
│ ├── unit/ # 单元测试
|
|
141
|
+
│ └── integration/ # 集成测试
|
|
142
|
+
├── source_vtt/ # 示例 VTT 文件
|
|
143
|
+
├── pyproject.toml # 项目配置
|
|
144
|
+
├── README.en.md # 英文文档
|
|
145
|
+
└── README.md # 中文文档
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## 运行测试
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
pip install -e ".[dev]"
|
|
152
|
+
pytest # 运行所有测试
|
|
153
|
+
pytest -v # 详细输出
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
所有测试离线运行(`FakeTransport` mock),不依赖真实网络与凭据。
|
|
157
|
+
|
|
158
|
+
## 安全说明
|
|
159
|
+
|
|
160
|
+
- `SESSDATA` 等同 B 站账号登录态,属于高敏凭据
|
|
161
|
+
- 登录态存储在 `~/.config/bili-sub2txt/session.json`(Windows 为 `%APPDATA%/bili-sub2txt/session.json`),仅含 SESSDATA,尽力设 `0600` 权限
|
|
162
|
+
- SESSDATA 只走 Cookie 请求头,绝不拼入 URL;日志和报错中自动脱敏
|
|
163
|
+
- 配置文件权限在 Windows 上保护有限,建议注意目录 ACL
|
|
164
|
+
|
|
165
|
+
## 免责声明
|
|
166
|
+
|
|
167
|
+
本工具为非官方项目,使用 B 站 Web 端内部接口,接口可能随时变更。字幕版权归 B 站与创作者所有,AI 字幕准确度有限,仅供个人学习与笔记使用。用户须自行遵守 B 站用户协议。
|
|
168
|
+
|
|
169
|
+
## 许可证
|
|
170
|
+
|
|
171
|
+
MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# bili-sub2txt
|
|
2
|
+
|
|
3
|
+
A Python tool to convert Bilibili subtitles to plain text. Supports both local VTT file batch conversion and direct download from Bilibili via BV number.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- Convert VTT subtitle files to plain text (strip timestamps and markup)
|
|
8
|
+
- Download Bilibili subtitles directly via BV number or video URL (requires login)
|
|
9
|
+
- QR-code login with persistent session
|
|
10
|
+
- Multi-part video support — all pages downloaded with indexed filenames
|
|
11
|
+
- Language selection (`--lang`); lists all available tracks when not found
|
|
12
|
+
- Automatic track selection (human Chinese > AI Chinese > human English > AI English)
|
|
13
|
+
- Recursive directory processing with preserved output structure
|
|
14
|
+
- VTT parser accepts spec variants (optional hours, comma separator, cue settings)
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
# Basic install (local VTT conversion only, zero third-party dependencies)
|
|
20
|
+
pip install -e .
|
|
21
|
+
|
|
22
|
+
# With download support (installs qrcode for terminal QR rendering)
|
|
23
|
+
pip install -e ".[download]"
|
|
24
|
+
|
|
25
|
+
# Development mode (includes pytest)
|
|
26
|
+
pip install -e ".[dev]"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
|
|
31
|
+
### Convert local VTT files
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
bili-sub2txt convert source_vtt/ target_txt/
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
- `source_vtt/`: input directory containing `.vtt` files (searched recursively)
|
|
38
|
+
- `target_txt/`: output directory for TXT files (auto-created, structure preserved)
|
|
39
|
+
|
|
40
|
+
### Download from Bilibili
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# First-time use requires QR-code login
|
|
44
|
+
bili-sub2txt login
|
|
45
|
+
|
|
46
|
+
# Download by BV number
|
|
47
|
+
bili-sub2txt fetch BV1jJ4m1J7ba
|
|
48
|
+
|
|
49
|
+
# Download by full URL
|
|
50
|
+
bili-sub2txt fetch https://www.bilibili.com/video/BV1jJ4m1J7ba/
|
|
51
|
+
|
|
52
|
+
# Specify output directory and subtitle language
|
|
53
|
+
bili-sub2txt fetch BV1jJ4m1J7ba --output my_output/ --lang zh-Hans
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**fetch options:**
|
|
57
|
+
- `target`: BV number or video URL (required)
|
|
58
|
+
- `-o, --output DIR`: output directory (default `target_txt/`, creates `<BV>/` inside)
|
|
59
|
+
- `--lang LAN`: subtitle language (e.g. `zh-Hans`, `ai-zh`, `ja`; auto-selected if omitted)
|
|
60
|
+
|
|
61
|
+
### Other
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
bili-sub2txt --help # show help
|
|
65
|
+
bili-sub2txt --version # show version
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Exit codes
|
|
69
|
+
|
|
70
|
+
| Code | Meaning |
|
|
71
|
+
|---|---|
|
|
72
|
+
| 0 | Success |
|
|
73
|
+
| 1 | Generic failure (no subtitles, network error, etc.) |
|
|
74
|
+
| 2 | Usage error |
|
|
75
|
+
| 3 | Login required / session expired |
|
|
76
|
+
|
|
77
|
+
## How it works
|
|
78
|
+
|
|
79
|
+
### VTT conversion (convert)
|
|
80
|
+
|
|
81
|
+
1. The CLI recursively finds all `.vtt` files in the input directory
|
|
82
|
+
2. Parses VTT: splits on blank lines into cues (further split on timestamps), drops cue identifiers / NOTE / STYLE / REGION blocks, strips inline markup and decodes HTML entities
|
|
83
|
+
3. Joins subtitle blocks with single newlines and writes to corresponding TXT files
|
|
84
|
+
|
|
85
|
+
### Bilibili download (fetch + login)
|
|
86
|
+
|
|
87
|
+
1. `login`: calls Bilibili's Web QR-code login API, renders QR in terminal, extracts `SESSDATA` on success and persists to config file
|
|
88
|
+
2. `fetch`: parses BV → fetches video info → for each page requests subtitle list → selects track → downloads JSON → converts to plain text → writes file
|
|
89
|
+
3. Duration cross-check (subtitle last `to` vs video `duration`, 0.5–1.25× range) — warns but does not block
|
|
90
|
+
|
|
91
|
+
## Project structure
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
bili-sub2txt/
|
|
95
|
+
├── src/bili_sub2txt/
|
|
96
|
+
│ ├── __init__.py # version
|
|
97
|
+
│ ├── __main__.py # python -m bili_sub2txt entry
|
|
98
|
+
│ ├── cli.py # argparse subcommands (convert/fetch/login)
|
|
99
|
+
│ ├── converter.py # VTT-to-TXT + Bilibili-JSON-to-TXT
|
|
100
|
+
│ ├── path_mapper.py # path mapping
|
|
101
|
+
│ ├── errors.py # exceptions, exit codes, SESSDATA redaction
|
|
102
|
+
│ ├── naming.py # filename sanitisation
|
|
103
|
+
│ └── bilibili/
|
|
104
|
+
│ ├── net.py # HTTP transport (injectable for offline testing)
|
|
105
|
+
│ ├── wbi.py # WBI signature
|
|
106
|
+
│ ├── session.py # SESSDATA persistence
|
|
107
|
+
│ ├── auth.py # QR-code login state machine
|
|
108
|
+
│ ├── api.py # video info, subtitle tracks, download
|
|
109
|
+
│ └── fetcher.py # fetch orchestration and duration check
|
|
110
|
+
├── tests/
|
|
111
|
+
│ ├── conftest.py # FakeTransport test fixture
|
|
112
|
+
│ ├── unit/ # unit tests
|
|
113
|
+
│ └── integration/ # integration tests
|
|
114
|
+
├── source_vtt/ # sample VTT files
|
|
115
|
+
├── pyproject.toml # project config
|
|
116
|
+
├── README.en.md # English docs
|
|
117
|
+
└── README.md # Chinese docs
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Running tests
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
pip install -e ".[dev]"
|
|
124
|
+
pytest # run all tests
|
|
125
|
+
pytest -v # verbose output
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
All tests run offline (`FakeTransport` mock) — no real network or credentials required.
|
|
129
|
+
|
|
130
|
+
## Security
|
|
131
|
+
|
|
132
|
+
- `SESSDATA` is equivalent to your Bilibili account login — treat as a high-sensitivity credential
|
|
133
|
+
- Session is stored at `~/.config/bili-sub2txt/session.json` (Windows: `%APPDATA%/bili-sub2txt/session.json`), containing only SESSDATA, with best-effort `0600` permissions
|
|
134
|
+
- SESSDATA is sent only via the Cookie header, never in URLs; automatically redacted in logs and error messages
|
|
135
|
+
- On Windows, file permission protection is limited — mind the directory ACL
|
|
136
|
+
|
|
137
|
+
## Disclaimer
|
|
138
|
+
|
|
139
|
+
This is an unofficial tool that uses Bilibili's internal Web APIs, which may change at any time. Subtitle copyright belongs to Bilibili and the content creators. AI subtitle accuracy is limited. For personal study and note-taking only. Users must comply with Bilibili's terms of service.
|
|
140
|
+
|
|
141
|
+
## License
|
|
142
|
+
|
|
143
|
+
MIT License - see [LICENSE](LICENSE)
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# bili-sub2txt
|
|
2
|
+
|
|
3
|
+
一款用于将 Bilibili 字幕转换为纯文本的 Python 工具。支持本地 VTT 文件批量转换,也可通过 BV 号直接下载 B 站字幕并转换。
|
|
4
|
+
|
|
5
|
+
## 功能特点
|
|
6
|
+
|
|
7
|
+
- 将 VTT 字幕文件转换为纯文本格式(去时间戳、去标记)
|
|
8
|
+
- 通过 BV 号或视频链接直接下载 B 站字幕(需登录)
|
|
9
|
+
- 扫码登录 B 站,登录态自动持久化
|
|
10
|
+
- 支持多 P 视频全量下载,文件名带序号前缀
|
|
11
|
+
- 支持指定字幕语言(`--lang`),未命中时列出所有可用轨道
|
|
12
|
+
- 字幕轨道自动选择(优先人工中文 → AI 中文 → 人工英文 → AI 英文)
|
|
13
|
+
- 递归处理整个目录结构,保留输出目录层级
|
|
14
|
+
- VTT 解析兼容规范变体(省略小时、逗号分隔符、cue 设置等)
|
|
15
|
+
|
|
16
|
+
## 安装
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
# 基础安装(仅本地 VTT 转换,零第三方依赖)
|
|
20
|
+
pip install -e .
|
|
21
|
+
|
|
22
|
+
# 含下载功能(安装 qrcode 用于终端渲染二维码)
|
|
23
|
+
pip install -e ".[download]"
|
|
24
|
+
|
|
25
|
+
# 开发模式(含 pytest)
|
|
26
|
+
pip install -e ".[dev]"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## 使用方法
|
|
30
|
+
|
|
31
|
+
### 转换本地 VTT 文件
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
bili-sub2txt convert source_vtt/ target_txt/
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
- `source_vtt/`:含 `.vtt` 文件的输入目录(递归查找)
|
|
38
|
+
- `target_txt/`:TXT 输出目录(自动创建,保留目录结构)
|
|
39
|
+
|
|
40
|
+
### 下载 B 站字幕
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# 首次使用需扫码登录
|
|
44
|
+
bili-sub2txt login
|
|
45
|
+
|
|
46
|
+
# 通过 BV 号下载
|
|
47
|
+
bili-sub2txt fetch BV1jJ4m1J7ba
|
|
48
|
+
|
|
49
|
+
# 通过完整链接下载
|
|
50
|
+
bili-sub2txt fetch https://www.bilibili.com/video/BV1jJ4m1J7ba/
|
|
51
|
+
|
|
52
|
+
# 指定输出目录和字幕语言
|
|
53
|
+
bili-sub2txt fetch BV1jJ4m1J7ba --output my_output/ --lang zh-Hans
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**fetch 参数:**
|
|
57
|
+
- `target`:BV 号或视频链接(必需)
|
|
58
|
+
- `-o, --output DIR`:输出目录(默认 `target_txt/`,在其下建 `<BV号>/`)
|
|
59
|
+
- `--lang LAN`:指定字幕语言(如 `zh-Hans`、`ai-zh`、`ja`;未指定时自动选择)
|
|
60
|
+
|
|
61
|
+
### 其他
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
bili-sub2txt --help # 查看帮助
|
|
65
|
+
bili-sub2txt --version # 查看版本
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### 退出码
|
|
69
|
+
|
|
70
|
+
| 码 | 含义 |
|
|
71
|
+
|---|---|
|
|
72
|
+
| 0 | 成功 |
|
|
73
|
+
| 1 | 一般失败(无字幕、网络错误等) |
|
|
74
|
+
| 2 | 用法错误 |
|
|
75
|
+
| 3 | 需要登录 / 登录态失效 |
|
|
76
|
+
|
|
77
|
+
## 工作原理
|
|
78
|
+
|
|
79
|
+
### VTT 转换(convert)
|
|
80
|
+
|
|
81
|
+
1. CLI 递归查找输入目录中的所有 `.vtt` 文件
|
|
82
|
+
2. 解析 VTT 格式:按空行切分字幕块(块内多个时间戳再细分),丢弃 cue 标识符/`NOTE`/`STYLE`/`REGION` 块,剥离内联标记并解码 HTML 实体
|
|
83
|
+
3. 以单换行连接各字幕块,写入对应的 TXT 文件
|
|
84
|
+
|
|
85
|
+
### B 站下载(fetch + login)
|
|
86
|
+
|
|
87
|
+
1. `login`:调用 B 站 Web 端扫码登录接口,终端渲染二维码,扫码成功后提取 `SESSDATA` 并保存到配置文件
|
|
88
|
+
2. `fetch`:解析 BV 号 → 获取视频信息 → 对每个分 P 请求字幕列表 → 选择轨道 → 下载 JSON → 转换为纯文本 → 写入文件
|
|
89
|
+
3. 字幕时长与视频时长交叉校验(0.5–1.25 倍区间),超出则告警但不阻断
|
|
90
|
+
|
|
91
|
+
## 项目结构
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
bili-sub2txt/
|
|
95
|
+
├── src/bili_sub2txt/
|
|
96
|
+
│ ├── __init__.py # 版本信息
|
|
97
|
+
│ ├── __main__.py # python -m bili_sub2txt 入口
|
|
98
|
+
│ ├── cli.py # argparse 子命令(convert/fetch/login)
|
|
99
|
+
│ ├── converter.py # VTT 转 TXT + B站 JSON 转 TXT
|
|
100
|
+
│ ├── path_mapper.py # 路径转换工具
|
|
101
|
+
│ ├── errors.py # 异常体系、退出码、SESSDATA 脱敏
|
|
102
|
+
│ ├── naming.py # 文件名清洗与输出路径构造
|
|
103
|
+
│ └── bilibili/
|
|
104
|
+
│ ├── net.py # HTTP transport(可注入,支持离线测试)
|
|
105
|
+
│ ├── wbi.py # WBI 签名
|
|
106
|
+
│ ├── session.py # SESSDATA 持久化
|
|
107
|
+
│ ├── auth.py # 扫码登录状态机
|
|
108
|
+
│ ├── api.py # 视频信息、字幕轨道、下载
|
|
109
|
+
│ └── fetcher.py # fetch 编排与时长校验
|
|
110
|
+
├── tests/
|
|
111
|
+
│ ├── conftest.py # FakeTransport 测试 fixture
|
|
112
|
+
│ ├── unit/ # 单元测试
|
|
113
|
+
│ └── integration/ # 集成测试
|
|
114
|
+
├── source_vtt/ # 示例 VTT 文件
|
|
115
|
+
├── pyproject.toml # 项目配置
|
|
116
|
+
├── README.en.md # 英文文档
|
|
117
|
+
└── README.md # 中文文档
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## 运行测试
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
pip install -e ".[dev]"
|
|
124
|
+
pytest # 运行所有测试
|
|
125
|
+
pytest -v # 详细输出
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
所有测试离线运行(`FakeTransport` mock),不依赖真实网络与凭据。
|
|
129
|
+
|
|
130
|
+
## 安全说明
|
|
131
|
+
|
|
132
|
+
- `SESSDATA` 等同 B 站账号登录态,属于高敏凭据
|
|
133
|
+
- 登录态存储在 `~/.config/bili-sub2txt/session.json`(Windows 为 `%APPDATA%/bili-sub2txt/session.json`),仅含 SESSDATA,尽力设 `0600` 权限
|
|
134
|
+
- SESSDATA 只走 Cookie 请求头,绝不拼入 URL;日志和报错中自动脱敏
|
|
135
|
+
- 配置文件权限在 Windows 上保护有限,建议注意目录 ACL
|
|
136
|
+
|
|
137
|
+
## 免责声明
|
|
138
|
+
|
|
139
|
+
本工具为非官方项目,使用 B 站 Web 端内部接口,接口可能随时变更。字幕版权归 B 站与创作者所有,AI 字幕准确度有限,仅供个人学习与笔记使用。用户须自行遵守 B 站用户协议。
|
|
140
|
+
|
|
141
|
+
## 许可证
|
|
142
|
+
|
|
143
|
+
MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "bili-sub2txt"
|
|
3
|
+
version = "0.2.0"
|
|
4
|
+
description = "Convert Bilibili subtitles to plain text — local VTT conversion and BV-number download"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
requires-python = ">=3.10"
|
|
8
|
+
authors = [
|
|
9
|
+
{ name = "folin", email = "Lin-Ruipeng@users.noreply.github.com" },
|
|
10
|
+
]
|
|
11
|
+
keywords = ["bilibili", "subtitle", "vtt", "txt", "converter", "bv"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"License :: OSI Approved :: MIT License",
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"Programming Language :: Python :: 3.10",
|
|
16
|
+
"Programming Language :: Python :: 3.11",
|
|
17
|
+
"Programming Language :: Python :: 3.12",
|
|
18
|
+
"Programming Language :: Python :: 3.13",
|
|
19
|
+
"Topic :: Multimedia :: Video",
|
|
20
|
+
"Environment :: Console",
|
|
21
|
+
"Intended Audience :: End Users/Desktop",
|
|
22
|
+
"Operating System :: OS Independent",
|
|
23
|
+
]
|
|
24
|
+
dependencies = []
|
|
25
|
+
|
|
26
|
+
[project.optional-dependencies]
|
|
27
|
+
dev = ["pytest>=7.0.0"]
|
|
28
|
+
download = ["qrcode>=7.4"]
|
|
29
|
+
|
|
30
|
+
[project.scripts]
|
|
31
|
+
bili-sub2txt = "bili_sub2txt.cli:main"
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://github.com/Lin-Ruipeng/bili-sub2txt"
|
|
35
|
+
Repository = "https://github.com/Lin-Ruipeng/bili-sub2txt"
|
|
36
|
+
Issues = "https://github.com/Lin-Ruipeng/bili-sub2txt/issues"
|
|
37
|
+
|
|
38
|
+
[build-system]
|
|
39
|
+
requires = ["hatchling"]
|
|
40
|
+
build-backend = "hatchling.build"
|
|
41
|
+
|
|
42
|
+
[tool.hatch.build.targets.wheel]
|
|
43
|
+
packages = ["src/bili_sub2txt"]
|
|
44
|
+
|
|
45
|
+
[tool.hatch.build.targets.sdist]
|
|
46
|
+
include = ["src", "tests", "README.md", "README.en.md", "LICENSE", "pyproject.toml"]
|
|
47
|
+
|
|
48
|
+
[tool.pytest.ini_options]
|
|
49
|
+
testpaths = ["tests"]
|
|
50
|
+
pythonpath = ["src"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""VTT to TXT converter package."""
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.2.0"
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Bilibili subtitle download subpackage."""
|