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.
Files changed (37) hide show
  1. bili_sub2txt-0.2.0/.gitignore +18 -0
  2. bili_sub2txt-0.2.0/LICENSE +21 -0
  3. bili_sub2txt-0.2.0/PKG-INFO +171 -0
  4. bili_sub2txt-0.2.0/README.en.md +143 -0
  5. bili_sub2txt-0.2.0/README.md +143 -0
  6. bili_sub2txt-0.2.0/pyproject.toml +50 -0
  7. bili_sub2txt-0.2.0/src/__init__.py +1 -0
  8. bili_sub2txt-0.2.0/src/bili_sub2txt/__init__.py +1 -0
  9. bili_sub2txt-0.2.0/src/bili_sub2txt/__main__.py +8 -0
  10. bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/__init__.py +1 -0
  11. bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/api.py +249 -0
  12. bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/auth.py +148 -0
  13. bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/fetcher.py +133 -0
  14. bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/net.py +137 -0
  15. bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/session.py +75 -0
  16. bili_sub2txt-0.2.0/src/bili_sub2txt/bilibili/wbi.py +69 -0
  17. bili_sub2txt-0.2.0/src/bili_sub2txt/cli.py +155 -0
  18. bili_sub2txt-0.2.0/src/bili_sub2txt/converter.py +145 -0
  19. bili_sub2txt-0.2.0/src/bili_sub2txt/errors.py +49 -0
  20. bili_sub2txt-0.2.0/src/bili_sub2txt/naming.py +50 -0
  21. bili_sub2txt-0.2.0/src/bili_sub2txt/path_mapper.py +28 -0
  22. bili_sub2txt-0.2.0/tests/conftest.py +117 -0
  23. bili_sub2txt-0.2.0/tests/integration/test_conversion.py +315 -0
  24. bili_sub2txt-0.2.0/tests/integration/test_fetch.py +85 -0
  25. bili_sub2txt-0.2.0/tests/unit/test_api.py +181 -0
  26. bili_sub2txt-0.2.0/tests/unit/test_auth.py +117 -0
  27. bili_sub2txt-0.2.0/tests/unit/test_cli.py +185 -0
  28. bili_sub2txt-0.2.0/tests/unit/test_converter.py +181 -0
  29. bili_sub2txt-0.2.0/tests/unit/test_converter_bili.py +78 -0
  30. bili_sub2txt-0.2.0/tests/unit/test_errors.py +59 -0
  31. bili_sub2txt-0.2.0/tests/unit/test_fetcher.py +127 -0
  32. bili_sub2txt-0.2.0/tests/unit/test_main_module.py +43 -0
  33. bili_sub2txt-0.2.0/tests/unit/test_naming.py +41 -0
  34. bili_sub2txt-0.2.0/tests/unit/test_net.py +68 -0
  35. bili_sub2txt-0.2.0/tests/unit/test_path_mapper.py +81 -0
  36. bili_sub2txt-0.2.0/tests/unit/test_session.py +40 -0
  37. bili_sub2txt-0.2.0/tests/unit/test_wbi.py +57 -0
@@ -0,0 +1,18 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.pyc
4
+ *.pyo
5
+ *.pyd
6
+
7
+ # Distribution / packaging
8
+ *.egg-info/
9
+ dist/
10
+ build/
11
+
12
+ # Test outputs
13
+ target_txt/
14
+ .pytest_cache/
15
+
16
+ # UV
17
+ uv.lock
18
+ .venv/
@@ -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,8 @@
1
+ """Entry point for python -m bili_sub2txt."""
2
+
3
+ import sys
4
+
5
+ from bili_sub2txt.cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())
@@ -0,0 +1 @@
1
+ """Bilibili subtitle download subpackage."""