taneko 0.1.1__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. taneko-0.1.1/LICENSE +21 -0
  2. taneko-0.1.1/PKG-INFO +340 -0
  3. taneko-0.1.1/README.md +322 -0
  4. taneko-0.1.1/pyproject.toml +34 -0
  5. taneko-0.1.1/setup.cfg +4 -0
  6. taneko-0.1.1/taneko/__init__.py +2 -0
  7. taneko-0.1.1/taneko/__main__.py +5 -0
  8. taneko-0.1.1/taneko/cli.py +62 -0
  9. taneko-0.1.1/taneko/config/asr.json +10 -0
  10. taneko-0.1.1/taneko/config/translate.json +22 -0
  11. taneko-0.1.1/taneko/core.py +113 -0
  12. taneko-0.1.1/taneko/doctor.py +68 -0
  13. taneko-0.1.1/taneko/flow.py +95 -0
  14. taneko-0.1.1/taneko/keys.py +112 -0
  15. taneko-0.1.1/taneko/project.py +89 -0
  16. taneko-0.1.1/taneko/ranges.py +215 -0
  17. taneko-0.1.1/taneko/srt.py +86 -0
  18. taneko-0.1.1/taneko/stages/__init__.py +1 -0
  19. taneko-0.1.1/taneko/stages/asr.py +70 -0
  20. taneko-0.1.1/taneko/stages/check.py +48 -0
  21. taneko-0.1.1/taneko/stages/fetch.py +336 -0
  22. taneko-0.1.1/taneko/stages/fix.py +48 -0
  23. taneko-0.1.1/taneko/stages/gates.py +26 -0
  24. taneko-0.1.1/taneko/stages/subs.py +48 -0
  25. taneko-0.1.1/taneko/stages/terms.py +45 -0
  26. taneko-0.1.1/taneko/stages/translate.py +181 -0
  27. taneko-0.1.1/taneko/stitch.py +242 -0
  28. taneko-0.1.1/taneko/workers/__init__.py +1 -0
  29. taneko-0.1.1/taneko/workers/asr_run.py +178 -0
  30. taneko-0.1.1/taneko.egg-info/PKG-INFO +340 -0
  31. taneko-0.1.1/taneko.egg-info/SOURCES.txt +35 -0
  32. taneko-0.1.1/taneko.egg-info/dependency_links.txt +1 -0
  33. taneko-0.1.1/taneko.egg-info/entry_points.txt +2 -0
  34. taneko-0.1.1/taneko.egg-info/requires.txt +1 -0
  35. taneko-0.1.1/taneko.egg-info/top_level.txt +1 -0
  36. taneko-0.1.1/tests/test_size.py +76 -0
  37. taneko-0.1.1/tests/test_taneko.py +637 -0
taneko-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nick
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.
taneko-0.1.1/PKG-INFO ADDED
@@ -0,0 +1,340 @@
1
+ Metadata-Version: 2.4
2
+ Name: taneko
3
+ Version: 0.1.1
4
+ Summary: Download part of a long video. If it stops, run it again and it picks up where it stopped.
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/coo1white/taneko
7
+ Project-URL: Issues, https://github.com/coo1white/taneko/issues
8
+ Keywords: video,download,resume,yt-dlp,ffmpeg
9
+ Classifier: Environment :: Console
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Topic :: Multimedia :: Video
13
+ Requires-Python: >=3.11
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: yt-dlp[default]>=2026.10.26
17
+ Dynamic: license-file
18
+
19
+ # Taneko
20
+
21
+ [![test](https://github.com/coo1white/taneko/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/coo1white/taneko/actions/workflows/test.yml)
22
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
23
+ [![Windows | macOS | Linux](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](https://github.com/coo1white/taneko#快速上手5-分钟)
24
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/coo1white/taneko/blob/main/LICENSE)
25
+
26
+ *Stay with me, even when the connection drops.*
27
+
28
+ > 下载长视频里的一段。断了接着下,不用重来。
29
+ > Download part of a long video. If it stops, run it again and it picks up where it stopped.
30
+
31
+ ## 它能做什么
32
+
33
+ - **只下你要的一段**:写好开始和结束时间,只下这段,速度和下整条一样。
34
+ - **断了接着下**:断网、关机、链接过期,再跑一次就行,已下的部分不会丢。
35
+ - **旧的半截文件接着用**:以前没下完的文件放进项目文件夹,Taneko 找到它对应的时间,只补缺的部分。
36
+ - **画质不变**:不重新编码。下完自动检查画面有没有断档、声音有没有空白。
37
+
38
+ ## 适合你吗?
39
+
40
+ - **适合**:只要长视频里的一段,比如 9 小时直播里的一局;或者网络不稳,下大文件常常断。
41
+ - **不太需要**:只下完整的短视频、网络也稳。直接用 [yt-dlp](https://github.com/yt-dlp/yt-dlp) 就够了,Taneko 本来也是用它取视频。
42
+
43
+ ## 快速上手
44
+
45
+ 下面是最常见的用法:只下视频,不做字幕。共 3 步。
46
+
47
+ ### 1. 安装
48
+
49
+ 先装 FFmpeg、deno 和 pipx,再用 pipx 装 Taneko。yt-dlp 会跟着 Taneko 一起装上。
50
+
51
+ **Windows**(PowerShell 或 cmd):
52
+
53
+ ```bash
54
+ winget install Python.Python.3.12 Gyan.FFmpeg DenoLand.Deno
55
+ ```
56
+
57
+ 关掉终端,重新打开一个,再运行:
58
+
59
+ ```bash
60
+ py -m pip install --user pipx
61
+ py -m pipx ensurepath
62
+ ```
63
+
64
+ 再关掉终端、重新打开,然后:
65
+
66
+ ```bash
67
+ pipx install taneko
68
+ ```
69
+
70
+ **macOS**:
71
+
72
+ ```bash
73
+ brew install ffmpeg deno pipx
74
+ pipx ensurepath
75
+ pipx install taneko
76
+ ```
77
+
78
+ **Linux**(Ubuntu / Debian):
79
+
80
+ ```bash
81
+ sudo apt install ffmpeg pipx
82
+ curl -fsSL https://deno.land/install.sh | sh
83
+ pipx ensurepath
84
+ pipx install taneko
85
+ ```
86
+
87
+ 装好后检查一遍:
88
+
89
+ ```bash
90
+ taneko doctor
91
+ ```
92
+
93
+ 缺什么,它会告诉你怎么装。Whisper 和 llm-subtrans 只有做字幕才要,可以不管。
94
+
95
+ Taneko 默认读取 Firefox 的登录信息(cookies),能下更多视频,比如会员视频。不用 Firefox 也能下。
96
+
97
+ ### 2. 建一个项目
98
+
99
+ ```bash
100
+ taneko init game3 "https://www.youtube.com/watch?v=..." --section 4:13:00-5:08:00
101
+ ```
102
+
103
+ - `game3`:项目名,也是下好的文件名(`game3.mkv`)。
104
+ - 网址:前后加英文引号,免得 `&` 之类的符号被终端误读。
105
+ - `--section`:开始-结束时间,可写 `4:13:00`、`13:00` 或 `780`(秒)。多短都行,比如 `4:13:00-4:14:00` 只下 1 分钟。不写就下整条视频。
106
+
107
+ 项目建在用户目录下的 `taneko/projects/game3/`(Windows 是 `C:\Users\你的用户名\taneko\projects\game3\`)。屏幕上会显示完整路径。
108
+
109
+ ### 3. 下载
110
+
111
+ ```bash
112
+ taneko run game3
113
+ ```
114
+
115
+ 屏幕最后会显示检查结果和文件位置,例如:
116
+
117
+ ```text
118
+ 检查结果:视频时长 64.5 秒;音频从 4.5 秒到 64.5 秒
119
+ 完成:C:\Users\你的用户名\taneko\projects\game3\game3.mkv
120
+ ```
121
+
122
+ 视频比你要的长几秒,这是正常的:画面要从开始时间之前最近的关键帧开始,才能不重新编码。声音正好从开始时间开始。检查没通过时,会显示“错误:”和原因,不会覆盖旧文件。
123
+
124
+ **中途断了?** 再跑一次同样的命令。
125
+
126
+ **卸载**:`pipx uninstall taneko`。下好的视频在 `taneko/projects/` 里,不会被删。
127
+
128
+ ## 常见问题
129
+
130
+ **怎么看下到哪了?**
131
+ `taneko status` 列出所有项目的进度。
132
+
133
+ **我有一个以前没下完的文件,能用吗?**
134
+ 能。把它改名成 `name` 写的名字(例如 `game3.mkv`),放进项目文件夹,再跑 `run`。
135
+
136
+ **不用 Firefox?**
137
+ 建项目时加 `--browser chrome`。写 `--browser none` 表示不读浏览器的登录信息。
138
+
139
+ **下载失败了?**
140
+ 看屏幕上“错误:”后面的说明,照着做,再跑一次。还不行就[提一个 issue](https://github.com/coo1white/taneko/issues),附上屏幕上的输出。
141
+
142
+ ## 进阶
143
+
144
+ <details>
145
+ <summary><b>所有命令</b></summary>
146
+
147
+ ```bash
148
+ taneko init game3 网址 --section 开始-结束 # 新建项目
149
+ taneko run game3 # 跑完所有步骤,已完成的跳过
150
+ taneko run . # 在项目文件夹里运行;也可以给完整路径
151
+ taneko status game3 # 一个项目的每一步
152
+ taneko status --json # 进度的 JSON 版,给脚本和 agent 读
153
+ taneko fetch game3 --jobs 2 # 只跑下载这一步
154
+ taneko doctor # 检查工具
155
+ ```
156
+
157
+ `fetch` 的常用选项:`--force` 重新下载,`--sections` 改用分段下载,`--keep` 保留中间文件。
158
+
159
+ 项目可以分组,最多 3 层:`init lol-worlds/game3 网址` 会建在 `projects/lol-worlds/game3/`,之后用 `run game3` 就行。
160
+
161
+ `init` 写出的 `meta.json` 也可以手动改:
162
+
163
+ ```json
164
+ {
165
+ "source_url": "https://www.youtube.com/watch?v=...",
166
+ "section": { "name": "game3", "download": "4:13:00-5:08:00" },
167
+ "subtitle": { "method": "none" },
168
+ "fetch": { "browser": "chrome" }
169
+ }
170
+ ```
171
+
172
+ `"method": "none"` 表示只下视频,不做字幕。
173
+
174
+ </details>
175
+
176
+ <details>
177
+ <summary><b>从源码运行(不用 pipx)</b></summary>
178
+
179
+ ```bash
180
+ git clone https://github.com/coo1white/taneko.git
181
+ python -m pip install yt-dlp
182
+ python taneko/taneko.py doctor
183
+ ```
184
+
185
+ 下面所有 `taneko` 命令都换成 `python taneko/taneko.py`。从源码运行时,项目放在代码文件夹旁边的 `projects/`。
186
+
187
+ </details>
188
+
189
+ <details>
190
+ <summary><b>下载是怎么做的</b></summary>
191
+
192
+ - 下整条视频时,交给 yt-dlp,它自己续传。
193
+ - 只下一段时,先读视频文件自带的索引(MP4 的 `sidx`、WebM 的 Cues),只下这段需要的字节;断了从已下的字节接着下。
194
+ - 没有索引的格式(例如直播流)改用分段下载:把时间范围切成小片(默认 600 秒),逐片下载、逐片检查,断了只补缺的片。
195
+ - 拼接时,视频在关键帧处接,音频在各自的起点处接,不重新编码。
196
+
197
+ YouTube 偶尔会对新地址返回 403,Taneko 会等几秒再试,再不行就换新地址,最后改用分段下载。
198
+
199
+ </details>
200
+
201
+ <details>
202
+ <summary><b>字幕(实验性,暂停开发)</b></summary>
203
+
204
+ 字幕能用,但不保证质量。流程:
205
+
206
+ `fetch → asr(或 subs)→ terms → ⏸术语校对 → fix → translate → check → ⏸抽查`
207
+
208
+ 本地 Whisper 转写,找出可能听错的专有名词,你校对,批量修正,按术语表翻译,检查,你抽查。停在 ⏸ 时,屏幕会告诉你看哪个文件、改哪里、下一条命令是什么。
209
+
210
+ 还要装:
211
+
212
+ - [faster-whisper](https://github.com/SYSTRAN/faster-whisper):单独的 venv,建议用 CUDA 显卡。在 `taneko/config/asr.json` 的 `home` 里写它的目录。
213
+ - [llm-subtrans](https://github.com/machinewrapped/llm-subtrans):翻译用,还要一个 OpenAI 兼容接口的密钥。
214
+
215
+ `meta.json` 的写法:
216
+
217
+ ```json
218
+ {
219
+ "source_url": "https://www.youtube.com/watch?v=...",
220
+ "section": { "download": "4:13:00-5:08:00", "name": "game3" },
221
+ "subtitle": { "method": "asr", "source_lang": "en" },
222
+ "translate": { "domain": "英雄联盟电竞", "names": [], "corrections": {} }
223
+ }
224
+ ```
225
+
226
+ - `method`:`asr` 是本地转写;`subs` 是抓视频自带的字幕。
227
+ - `source_lang` 写 `zh` 时,只转写,不翻译。
228
+
229
+ 检查点命令:
230
+
231
+ ```bash
232
+ taneko approve game3 terms # 术语校对完
233
+ taneko approve game3 spot # 抽查完
234
+ taneko translate game3 --test # 先试翻译风格
235
+ ```
236
+
237
+ 单个步骤也能单独跑:`fetch / subs / asr / terms / fix / translate / check`。
238
+
239
+ **API 密钥**只放在环境变量 `OPENCODE_API_KEY`,不写进项目文件:
240
+
241
+ ```bash
242
+ taneko key set # 保存(输入时不显示)
243
+ taneko key status # 只显示有没有、多长、从哪来
244
+ taneko key check # 问一次服务器密钥是否有效(用 1 个 token)
245
+ taneko key clear # 删除
246
+ ```
247
+
248
+ - Windows:`key set` 存进用户环境变量。它是明文,你账户下的程序都读得到。
249
+ - macOS / Linux:`key set` 不保存,请自己在 shell 配置里 `export OPENCODE_API_KEY=...`。
250
+ - 不保存也行:在终端里翻译时会问一次。脚本或 agent 运行时不问,直接报错退出。
251
+
252
+ 翻译步骤会给你本地的 llm-subtrans 打一个小补丁(支持额外的请求头和参数)。只改你电脑上那份,不分发它的代码。
253
+
254
+ </details>
255
+
256
+ <details>
257
+ <summary><b>退出码(给脚本和 agent)</b></summary>
258
+
259
+ | 退出码 | 含义 | 下一步 |
260
+ |---|---|---|
261
+ | `0` | 成功;`run` 表示全部完成 | 无 |
262
+ | `1` | 出错(输出里有“错误:”) | 看报错,修好再跑 |
263
+ | `2` | 命令参数不对 | 看 `--help` |
264
+ | `10` | `run` 停在人工检查点(不是失败) | 处理后 `approve`,再 `run` |
265
+
266
+ `status --json` 给出每个项目的 `next`(下一步)、`needs_human`(是否在等人)和每一步的 `state`(`done` / `skip` / `next` / `todo`)。
267
+
268
+ </details>
269
+
270
+ <details>
271
+ <summary><b>配置和目录</b></summary>
272
+
273
+ - 从源码运行时,项目默认在代码文件夹旁边的 `projects/`。用 pip 安装后,默认在用户目录下的 `taneko/projects/`(Windows 是 `C:\Users\你的用户名\taneko\projects`)。`doctor` 会显示实际位置。
274
+ - 翻译工具默认在项目目录旁边的 `workflow/vendor/`。
275
+ - 用环境变量改位置:`TANEKO_ROOT`、`TANEKO_PROJECTS`、`TANEKO_CONFIG`、`TANEKO_VENDOR`。
276
+ - 转写设置在 `taneko/config/asr.json`;翻译设置(接口、模型、分段大小)在 `taneko/config/translate.json`。
277
+
278
+ </details>
279
+
280
+ <details>
281
+ <summary><b>测过什么(诚实版)</b></summary>
282
+
283
+ | 在真实环境测过 | 还没测过 |
284
+ |---|---|
285
+ | 分段下载、半截文件对齐、拼接:一局 55 分钟的 1440p60 视频,复用 41 分钟的旧文件,对齐误差 0.00,视频无断档。2026-11-16 前拼的文件接缝处有 0.5~3.5 秒没声音,已修复(issue [#1](https://github.com/coo1white/taneko/issues/1)) | 转写、术语校对、翻译(实验性,暂停开发) |
286
+ | 按索引下载一段(issue [#8](https://github.com/coo1white/taneko/issues/8)):YouTube 1440p60,中途强行停掉再跑,从已下的 160 MiB 接着下;画面和整条下载逐字节相同,音画差 5~21 毫秒;约 8 MiB/s(分段下载约 2 倍实时) | B 站、X 等网站的按索引下载 |
287
+ | Windows 上按索引下载:用 Firefox 登录信息,格式 308+140 跑了 3 次都成功,每次约 50 秒(分段下载 176 秒);默认格式(AV1 + Opus)照快速上手走了一遍 | macOS、Linux 上的真实下载(只有自动测试) |
288
+ | 多片同时下载(`--jobs 2`):同一场比赛的另外 4 段 | |
289
+ | 流程、人工检查点、退出码、分段翻译:有自动测试 | |
290
+
291
+ 已知问题:
292
+
293
+ - 在新电脑上安装还不方便:issue [#5](https://github.com/coo1white/taneko/issues/5)。
294
+ - 字幕的已知问题随字幕一起暂停,见 [ROADMAP.md](https://github.com/coo1white/taneko/blob/main/ROADMAP.md) 的“暂停”一节。
295
+
296
+ 全部问题见 [Issues](https://github.com/coo1white/taneko/issues),计划见 [ROADMAP.md](https://github.com/coo1white/taneko/blob/main/ROADMAP.md),架构见 [ARCHITECTURE.md](https://github.com/coo1white/taneko/blob/main/ARCHITECTURE.md)。
297
+
298
+ </details>
299
+
300
+ <details>
301
+ <summary><b>技术栈</b></summary>
302
+
303
+ | 层 | 用到的东西 | 做什么 |
304
+ |---|---|---|
305
+ | 语言 | Python 3.11+,代码只用标准库 | 整个框架。唯一的依赖是 yt-dlp,pip 安装时一起装上,只作为命令调用 |
306
+ | 下载 | yt-dlp(Unlicense)+ deno + 浏览器登录信息 | 取视频地址,子进程调用 |
307
+ | 按索引下载 | HTTP Range 请求,读 MP4 `sidx` 和 WebM Cues(标准库自己写) | 只下需要的字节,断了接着下 |
308
+ | 媒体处理 | FFmpeg / ffprobe(LGPL 2.1+,视构建方式可能为 GPL) | 无损截取、拼接、检查,子进程调用 |
309
+ | 语音识别 | faster-whisper + CTranslate2,large-v3,CUDA,失败时退回 CPU | 本地转写 |
310
+ | 翻译 | llm-subtrans + OpenAI 兼容接口(只测过 OpenCode) | 按术语表翻译;每 200 条存一次,中断后只补没译完的 |
311
+ | 状态 | 每个项目一个 `meta.json`;`taneko/config/*.json` | 项目设置、术语表、检查点记录 |
312
+ | 质量 | `unittest`、Mermaid、Git | 测试、架构图、版本管理 |
313
+
314
+ Taneko 只调用这些工具,不打包它们的代码。请自行安装,并遵守各自的许可证。
315
+
316
+ </details>
317
+
318
+ ## 使用提醒
319
+
320
+ - 只下你有权下载的内容。遵守平台条款和当地法律;转载前确认版权。
321
+ - 默认读取本机 Firefox 的登录信息(cookies),只在本地用,不写文件、不上传。
322
+
323
+ ## 致敬 BitTorrent
324
+
325
+ 灵感来自 BitTorrent:把大事切成小片,每片单独检查,断了只补缺的。
326
+ 献给陪我们长大的 BT 下载,感谢 Bram Cohen 和 BitTorrent 社区。
327
+
328
+ 本项目没有 P2P,不会更快(价值在于不丢进度),不是 BitTorrent 的实现或客户端,与 BitTorrent, Inc. 无关。
329
+
330
+ > Inspired by BitTorrent: split a big job into small pieces, check each piece, and fetch only what is missing. Dedicated to the BT downloads we grew up with. Thanks to Bram Cohen and the BitTorrent community.
331
+ >
332
+ > Taneko has no P2P and is not faster; its value is that you never lose progress. It is not a BitTorrent implementation or client, and it is not affiliated with BitTorrent, Inc.
333
+
334
+ ## 许可证
335
+
336
+ [MIT 许可证](https://github.com/coo1white/taneko/blob/main/LICENSE):可以自由使用、修改、分发,保留版权声明即可。
337
+
338
+ 如果它帮你省了时间,欢迎点右上角的 ⭐ **Star**。这是请求,不是使用条件。
339
+
340
+ > If taneko saved you time, a ⭐ is the best thanks. It's a request, not a license condition.
taneko-0.1.1/README.md ADDED
@@ -0,0 +1,322 @@
1
+ # Taneko
2
+
3
+ [![test](https://github.com/coo1white/taneko/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/coo1white/taneko/actions/workflows/test.yml)
4
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
5
+ [![Windows | macOS | Linux](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](https://github.com/coo1white/taneko#快速上手5-分钟)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/coo1white/taneko/blob/main/LICENSE)
7
+
8
+ *Stay with me, even when the connection drops.*
9
+
10
+ > 下载长视频里的一段。断了接着下,不用重来。
11
+ > Download part of a long video. If it stops, run it again and it picks up where it stopped.
12
+
13
+ ## 它能做什么
14
+
15
+ - **只下你要的一段**:写好开始和结束时间,只下这段,速度和下整条一样。
16
+ - **断了接着下**:断网、关机、链接过期,再跑一次就行,已下的部分不会丢。
17
+ - **旧的半截文件接着用**:以前没下完的文件放进项目文件夹,Taneko 找到它对应的时间,只补缺的部分。
18
+ - **画质不变**:不重新编码。下完自动检查画面有没有断档、声音有没有空白。
19
+
20
+ ## 适合你吗?
21
+
22
+ - **适合**:只要长视频里的一段,比如 9 小时直播里的一局;或者网络不稳,下大文件常常断。
23
+ - **不太需要**:只下完整的短视频、网络也稳。直接用 [yt-dlp](https://github.com/yt-dlp/yt-dlp) 就够了,Taneko 本来也是用它取视频。
24
+
25
+ ## 快速上手
26
+
27
+ 下面是最常见的用法:只下视频,不做字幕。共 3 步。
28
+
29
+ ### 1. 安装
30
+
31
+ 先装 FFmpeg、deno 和 pipx,再用 pipx 装 Taneko。yt-dlp 会跟着 Taneko 一起装上。
32
+
33
+ **Windows**(PowerShell 或 cmd):
34
+
35
+ ```bash
36
+ winget install Python.Python.3.12 Gyan.FFmpeg DenoLand.Deno
37
+ ```
38
+
39
+ 关掉终端,重新打开一个,再运行:
40
+
41
+ ```bash
42
+ py -m pip install --user pipx
43
+ py -m pipx ensurepath
44
+ ```
45
+
46
+ 再关掉终端、重新打开,然后:
47
+
48
+ ```bash
49
+ pipx install taneko
50
+ ```
51
+
52
+ **macOS**:
53
+
54
+ ```bash
55
+ brew install ffmpeg deno pipx
56
+ pipx ensurepath
57
+ pipx install taneko
58
+ ```
59
+
60
+ **Linux**(Ubuntu / Debian):
61
+
62
+ ```bash
63
+ sudo apt install ffmpeg pipx
64
+ curl -fsSL https://deno.land/install.sh | sh
65
+ pipx ensurepath
66
+ pipx install taneko
67
+ ```
68
+
69
+ 装好后检查一遍:
70
+
71
+ ```bash
72
+ taneko doctor
73
+ ```
74
+
75
+ 缺什么,它会告诉你怎么装。Whisper 和 llm-subtrans 只有做字幕才要,可以不管。
76
+
77
+ Taneko 默认读取 Firefox 的登录信息(cookies),能下更多视频,比如会员视频。不用 Firefox 也能下。
78
+
79
+ ### 2. 建一个项目
80
+
81
+ ```bash
82
+ taneko init game3 "https://www.youtube.com/watch?v=..." --section 4:13:00-5:08:00
83
+ ```
84
+
85
+ - `game3`:项目名,也是下好的文件名(`game3.mkv`)。
86
+ - 网址:前后加英文引号,免得 `&` 之类的符号被终端误读。
87
+ - `--section`:开始-结束时间,可写 `4:13:00`、`13:00` 或 `780`(秒)。多短都行,比如 `4:13:00-4:14:00` 只下 1 分钟。不写就下整条视频。
88
+
89
+ 项目建在用户目录下的 `taneko/projects/game3/`(Windows 是 `C:\Users\你的用户名\taneko\projects\game3\`)。屏幕上会显示完整路径。
90
+
91
+ ### 3. 下载
92
+
93
+ ```bash
94
+ taneko run game3
95
+ ```
96
+
97
+ 屏幕最后会显示检查结果和文件位置,例如:
98
+
99
+ ```text
100
+ 检查结果:视频时长 64.5 秒;音频从 4.5 秒到 64.5 秒
101
+ 完成:C:\Users\你的用户名\taneko\projects\game3\game3.mkv
102
+ ```
103
+
104
+ 视频比你要的长几秒,这是正常的:画面要从开始时间之前最近的关键帧开始,才能不重新编码。声音正好从开始时间开始。检查没通过时,会显示“错误:”和原因,不会覆盖旧文件。
105
+
106
+ **中途断了?** 再跑一次同样的命令。
107
+
108
+ **卸载**:`pipx uninstall taneko`。下好的视频在 `taneko/projects/` 里,不会被删。
109
+
110
+ ## 常见问题
111
+
112
+ **怎么看下到哪了?**
113
+ `taneko status` 列出所有项目的进度。
114
+
115
+ **我有一个以前没下完的文件,能用吗?**
116
+ 能。把它改名成 `name` 写的名字(例如 `game3.mkv`),放进项目文件夹,再跑 `run`。
117
+
118
+ **不用 Firefox?**
119
+ 建项目时加 `--browser chrome`。写 `--browser none` 表示不读浏览器的登录信息。
120
+
121
+ **下载失败了?**
122
+ 看屏幕上“错误:”后面的说明,照着做,再跑一次。还不行就[提一个 issue](https://github.com/coo1white/taneko/issues),附上屏幕上的输出。
123
+
124
+ ## 进阶
125
+
126
+ <details>
127
+ <summary><b>所有命令</b></summary>
128
+
129
+ ```bash
130
+ taneko init game3 网址 --section 开始-结束 # 新建项目
131
+ taneko run game3 # 跑完所有步骤,已完成的跳过
132
+ taneko run . # 在项目文件夹里运行;也可以给完整路径
133
+ taneko status game3 # 一个项目的每一步
134
+ taneko status --json # 进度的 JSON 版,给脚本和 agent 读
135
+ taneko fetch game3 --jobs 2 # 只跑下载这一步
136
+ taneko doctor # 检查工具
137
+ ```
138
+
139
+ `fetch` 的常用选项:`--force` 重新下载,`--sections` 改用分段下载,`--keep` 保留中间文件。
140
+
141
+ 项目可以分组,最多 3 层:`init lol-worlds/game3 网址` 会建在 `projects/lol-worlds/game3/`,之后用 `run game3` 就行。
142
+
143
+ `init` 写出的 `meta.json` 也可以手动改:
144
+
145
+ ```json
146
+ {
147
+ "source_url": "https://www.youtube.com/watch?v=...",
148
+ "section": { "name": "game3", "download": "4:13:00-5:08:00" },
149
+ "subtitle": { "method": "none" },
150
+ "fetch": { "browser": "chrome" }
151
+ }
152
+ ```
153
+
154
+ `"method": "none"` 表示只下视频,不做字幕。
155
+
156
+ </details>
157
+
158
+ <details>
159
+ <summary><b>从源码运行(不用 pipx)</b></summary>
160
+
161
+ ```bash
162
+ git clone https://github.com/coo1white/taneko.git
163
+ python -m pip install yt-dlp
164
+ python taneko/taneko.py doctor
165
+ ```
166
+
167
+ 下面所有 `taneko` 命令都换成 `python taneko/taneko.py`。从源码运行时,项目放在代码文件夹旁边的 `projects/`。
168
+
169
+ </details>
170
+
171
+ <details>
172
+ <summary><b>下载是怎么做的</b></summary>
173
+
174
+ - 下整条视频时,交给 yt-dlp,它自己续传。
175
+ - 只下一段时,先读视频文件自带的索引(MP4 的 `sidx`、WebM 的 Cues),只下这段需要的字节;断了从已下的字节接着下。
176
+ - 没有索引的格式(例如直播流)改用分段下载:把时间范围切成小片(默认 600 秒),逐片下载、逐片检查,断了只补缺的片。
177
+ - 拼接时,视频在关键帧处接,音频在各自的起点处接,不重新编码。
178
+
179
+ YouTube 偶尔会对新地址返回 403,Taneko 会等几秒再试,再不行就换新地址,最后改用分段下载。
180
+
181
+ </details>
182
+
183
+ <details>
184
+ <summary><b>字幕(实验性,暂停开发)</b></summary>
185
+
186
+ 字幕能用,但不保证质量。流程:
187
+
188
+ `fetch → asr(或 subs)→ terms → ⏸术语校对 → fix → translate → check → ⏸抽查`
189
+
190
+ 本地 Whisper 转写,找出可能听错的专有名词,你校对,批量修正,按术语表翻译,检查,你抽查。停在 ⏸ 时,屏幕会告诉你看哪个文件、改哪里、下一条命令是什么。
191
+
192
+ 还要装:
193
+
194
+ - [faster-whisper](https://github.com/SYSTRAN/faster-whisper):单独的 venv,建议用 CUDA 显卡。在 `taneko/config/asr.json` 的 `home` 里写它的目录。
195
+ - [llm-subtrans](https://github.com/machinewrapped/llm-subtrans):翻译用,还要一个 OpenAI 兼容接口的密钥。
196
+
197
+ `meta.json` 的写法:
198
+
199
+ ```json
200
+ {
201
+ "source_url": "https://www.youtube.com/watch?v=...",
202
+ "section": { "download": "4:13:00-5:08:00", "name": "game3" },
203
+ "subtitle": { "method": "asr", "source_lang": "en" },
204
+ "translate": { "domain": "英雄联盟电竞", "names": [], "corrections": {} }
205
+ }
206
+ ```
207
+
208
+ - `method`:`asr` 是本地转写;`subs` 是抓视频自带的字幕。
209
+ - `source_lang` 写 `zh` 时,只转写,不翻译。
210
+
211
+ 检查点命令:
212
+
213
+ ```bash
214
+ taneko approve game3 terms # 术语校对完
215
+ taneko approve game3 spot # 抽查完
216
+ taneko translate game3 --test # 先试翻译风格
217
+ ```
218
+
219
+ 单个步骤也能单独跑:`fetch / subs / asr / terms / fix / translate / check`。
220
+
221
+ **API 密钥**只放在环境变量 `OPENCODE_API_KEY`,不写进项目文件:
222
+
223
+ ```bash
224
+ taneko key set # 保存(输入时不显示)
225
+ taneko key status # 只显示有没有、多长、从哪来
226
+ taneko key check # 问一次服务器密钥是否有效(用 1 个 token)
227
+ taneko key clear # 删除
228
+ ```
229
+
230
+ - Windows:`key set` 存进用户环境变量。它是明文,你账户下的程序都读得到。
231
+ - macOS / Linux:`key set` 不保存,请自己在 shell 配置里 `export OPENCODE_API_KEY=...`。
232
+ - 不保存也行:在终端里翻译时会问一次。脚本或 agent 运行时不问,直接报错退出。
233
+
234
+ 翻译步骤会给你本地的 llm-subtrans 打一个小补丁(支持额外的请求头和参数)。只改你电脑上那份,不分发它的代码。
235
+
236
+ </details>
237
+
238
+ <details>
239
+ <summary><b>退出码(给脚本和 agent)</b></summary>
240
+
241
+ | 退出码 | 含义 | 下一步 |
242
+ |---|---|---|
243
+ | `0` | 成功;`run` 表示全部完成 | 无 |
244
+ | `1` | 出错(输出里有“错误:”) | 看报错,修好再跑 |
245
+ | `2` | 命令参数不对 | 看 `--help` |
246
+ | `10` | `run` 停在人工检查点(不是失败) | 处理后 `approve`,再 `run` |
247
+
248
+ `status --json` 给出每个项目的 `next`(下一步)、`needs_human`(是否在等人)和每一步的 `state`(`done` / `skip` / `next` / `todo`)。
249
+
250
+ </details>
251
+
252
+ <details>
253
+ <summary><b>配置和目录</b></summary>
254
+
255
+ - 从源码运行时,项目默认在代码文件夹旁边的 `projects/`。用 pip 安装后,默认在用户目录下的 `taneko/projects/`(Windows 是 `C:\Users\你的用户名\taneko\projects`)。`doctor` 会显示实际位置。
256
+ - 翻译工具默认在项目目录旁边的 `workflow/vendor/`。
257
+ - 用环境变量改位置:`TANEKO_ROOT`、`TANEKO_PROJECTS`、`TANEKO_CONFIG`、`TANEKO_VENDOR`。
258
+ - 转写设置在 `taneko/config/asr.json`;翻译设置(接口、模型、分段大小)在 `taneko/config/translate.json`。
259
+
260
+ </details>
261
+
262
+ <details>
263
+ <summary><b>测过什么(诚实版)</b></summary>
264
+
265
+ | 在真实环境测过 | 还没测过 |
266
+ |---|---|
267
+ | 分段下载、半截文件对齐、拼接:一局 55 分钟的 1440p60 视频,复用 41 分钟的旧文件,对齐误差 0.00,视频无断档。2026-11-16 前拼的文件接缝处有 0.5~3.5 秒没声音,已修复(issue [#1](https://github.com/coo1white/taneko/issues/1)) | 转写、术语校对、翻译(实验性,暂停开发) |
268
+ | 按索引下载一段(issue [#8](https://github.com/coo1white/taneko/issues/8)):YouTube 1440p60,中途强行停掉再跑,从已下的 160 MiB 接着下;画面和整条下载逐字节相同,音画差 5~21 毫秒;约 8 MiB/s(分段下载约 2 倍实时) | B 站、X 等网站的按索引下载 |
269
+ | Windows 上按索引下载:用 Firefox 登录信息,格式 308+140 跑了 3 次都成功,每次约 50 秒(分段下载 176 秒);默认格式(AV1 + Opus)照快速上手走了一遍 | macOS、Linux 上的真实下载(只有自动测试) |
270
+ | 多片同时下载(`--jobs 2`):同一场比赛的另外 4 段 | |
271
+ | 流程、人工检查点、退出码、分段翻译:有自动测试 | |
272
+
273
+ 已知问题:
274
+
275
+ - 在新电脑上安装还不方便:issue [#5](https://github.com/coo1white/taneko/issues/5)。
276
+ - 字幕的已知问题随字幕一起暂停,见 [ROADMAP.md](https://github.com/coo1white/taneko/blob/main/ROADMAP.md) 的“暂停”一节。
277
+
278
+ 全部问题见 [Issues](https://github.com/coo1white/taneko/issues),计划见 [ROADMAP.md](https://github.com/coo1white/taneko/blob/main/ROADMAP.md),架构见 [ARCHITECTURE.md](https://github.com/coo1white/taneko/blob/main/ARCHITECTURE.md)。
279
+
280
+ </details>
281
+
282
+ <details>
283
+ <summary><b>技术栈</b></summary>
284
+
285
+ | 层 | 用到的东西 | 做什么 |
286
+ |---|---|---|
287
+ | 语言 | Python 3.11+,代码只用标准库 | 整个框架。唯一的依赖是 yt-dlp,pip 安装时一起装上,只作为命令调用 |
288
+ | 下载 | yt-dlp(Unlicense)+ deno + 浏览器登录信息 | 取视频地址,子进程调用 |
289
+ | 按索引下载 | HTTP Range 请求,读 MP4 `sidx` 和 WebM Cues(标准库自己写) | 只下需要的字节,断了接着下 |
290
+ | 媒体处理 | FFmpeg / ffprobe(LGPL 2.1+,视构建方式可能为 GPL) | 无损截取、拼接、检查,子进程调用 |
291
+ | 语音识别 | faster-whisper + CTranslate2,large-v3,CUDA,失败时退回 CPU | 本地转写 |
292
+ | 翻译 | llm-subtrans + OpenAI 兼容接口(只测过 OpenCode) | 按术语表翻译;每 200 条存一次,中断后只补没译完的 |
293
+ | 状态 | 每个项目一个 `meta.json`;`taneko/config/*.json` | 项目设置、术语表、检查点记录 |
294
+ | 质量 | `unittest`、Mermaid、Git | 测试、架构图、版本管理 |
295
+
296
+ Taneko 只调用这些工具,不打包它们的代码。请自行安装,并遵守各自的许可证。
297
+
298
+ </details>
299
+
300
+ ## 使用提醒
301
+
302
+ - 只下你有权下载的内容。遵守平台条款和当地法律;转载前确认版权。
303
+ - 默认读取本机 Firefox 的登录信息(cookies),只在本地用,不写文件、不上传。
304
+
305
+ ## 致敬 BitTorrent
306
+
307
+ 灵感来自 BitTorrent:把大事切成小片,每片单独检查,断了只补缺的。
308
+ 献给陪我们长大的 BT 下载,感谢 Bram Cohen 和 BitTorrent 社区。
309
+
310
+ 本项目没有 P2P,不会更快(价值在于不丢进度),不是 BitTorrent 的实现或客户端,与 BitTorrent, Inc. 无关。
311
+
312
+ > Inspired by BitTorrent: split a big job into small pieces, check each piece, and fetch only what is missing. Dedicated to the BT downloads we grew up with. Thanks to Bram Cohen and the BitTorrent community.
313
+ >
314
+ > Taneko has no P2P and is not faster; its value is that you never lose progress. It is not a BitTorrent implementation or client, and it is not affiliated with BitTorrent, Inc.
315
+
316
+ ## 许可证
317
+
318
+ [MIT 许可证](https://github.com/coo1white/taneko/blob/main/LICENSE):可以自由使用、修改、分发,保留版权声明即可。
319
+
320
+ 如果它帮你省了时间,欢迎点右上角的 ⭐ **Star**。这是请求,不是使用条件。
321
+
322
+ > If taneko saved you time, a ⭐ is the best thanks. It's a request, not a license condition.