v3.0.0

yt-dlp 下载后端

download 收敛为唯一的 yt-dlp 下载后端，支持 Twitch / YouTube 等更多平台的视频与直播回放。

新增

• 内置 yt-dlp 下载后端，默认下载最佳音频并提取为 MP3，直接复用转字幕 / 翻译 / 总结流水线
• 分片下载并发默认固定为 5
• 新增 --yt-dlp-args 与裸 -- 透传 yt-dlp 原生参数

破坏性变更（MAJOR）

• 移除 Twitch TS 直连与后端选择逻辑
• 移除 CLI 参数 --start / --end / --concurrent / --keep-ts / --mp3
• 删除公共类 TwitchDownloader、公共函数 parse_url_pattern
• download_from_url 改签名（异步→同步）、产物 key 由 mp4 / mp3 变为 audio

升级须知

• yt-dlp 按外部工具处理，不随 uv.lock 固定版本。请自行安装并保持最新：

  pip install -U yt-dlp

• 确认 yt-dlp --version 与 ffmpeg -version 均在 PATH 中可用。

Full Changelog: v2.3.0...v3.0.0

v2.3.0

2.3.0

新增「总结 Markdown 渲染为分享图片」功能。

总结渲染图片

summarize 子命令新增 --render-image：在总结 Markdown 写盘后，额外把它渲染成 PNG 分享图（Markdown → HTML → Playwright 无头浏览器截图）。

# 装 image 可选依赖 + chromium（一次性）
uv sync --extra image
uv run --extra image playwright install chromium

# 总结并渲染图片
uv run --extra image kits summarize -i live.srt --render-image
# 暗色主题 / 自定义输出
uv run --extra image kits summarize -i live.srt --render-image --image-theme dark --image-output live.png

选项：

• --image-output：图片输出路径（默认与 Markdown 同名 .png）
• --image-width：正文宽度（px，默认 1200）
• --image-theme：light / dark（默认 light）
• --image-scale：截图缩放（默认 2.0，高清）

图片渲染失败（如未装 Playwright / chromium）时，总结 Markdown 仍正常保留（优雅降级）。

依赖

新增 [image] 可选 extra（markdown-it-py + playwright），为可选依赖、不装不影响核心功能。无破坏性变更，SemVer minor（2.2.0 → 2.3.0）。

验证

• 全量测试 194 passed，ruff 干净，uv lock --check 通过
• markdown→PNG 截图管线本地实测出图（light/dark 双主题视觉确认）
• 修复了一个 CI 缺口：轻量测试环境补 markdown-it-py，使渲染测试在 CI 真跑而非静默跳过

完整改动见 v2.2.0...v2.3.0

v2.2.0

2.2.0

默认分段策略改为逐 VAD 人声窗口转录，根治 Whisper 前导静音漂移。

默认：逐 VAD 人声窗口

用 Silero VAD 探出一个个「话语级人声窗口」，只转人声窗口、丢弃窗口间静音，每个窗口以其真实起点做偏移锚点。时间戳锚定真实人声边界——实测人声 23.5s 才开始时，首条字幕正确落在 23.4s，而非旧版错标的 00:00:00。

⚠️ 唱歌延音会丢字幕：Silero VAD 按「说话」训练，对唱歌的持续长元音系统性漏判（不判为语音）→ 那段不建窗口、字幕整段丢失。实测调低 --vad-threshold 也救不回。歌枠 / 含大量唱歌请用 --full-transcribe。

--full-transcribe：整段连续转录（保留旧路径）

按非语音间隙把长音频切成大段、整段连续喂给 kotoba（段内含静音也一起转）。不靠 VAD 决定「转不转」，故唱歌延音也能识别出歌词、不丢字幕。代价：段首前导静音可能让首句时间戳偏早。

# 默认（纯说话场次 / 直播总结，对齐最准）
uv run kits subtitle -i live.mp3

# 歌枠 / 含唱歌（不丢唱歌字幕）
uv run kits subtitle -i live.mp3 --full-transcribe

兼容性

无移除已发布 CLI 参数，旧行为经 --full-transcribe 完全可达、旧路径代码保留。按 SemVer 为 minor（2.1.0 → 2.2.0）。

验证

全量测试 185 passed，ruff 干净，uv lock --check 通过。真实音频 A/B 对比、threshold 扫描、延音丢字幕诊断均本地实测确认。

完整改动见 v2.1.0...v2.2.0

v2.1.0

2.1.0

VAD 能力增强，均向后兼容。

VAD 人声边界修正 kotoba 虚高时间戳

kotoba 蒸馏模型的 chunk 结束时间戳常虚高（end 溢出到人声结束后的静音里）。本版对明显虚高的字幕（每字符时长 > 1.0 秒）用长音频转录时已探出的 VAD 人声区间 把 end 夹回「人声实际结束处」——这是真实测量，比单纯按语速估算更准（实测误差 0.10.3 秒 vs 字符速率 2.53.5 秒）。VAD 对不上时（短音频没跑 VAD、或人声边界落在句外）回退 --max-seconds-per-char 字符速率收缩，二者互斥、择一生效。

• segment_sentences 新增 speech 参数；speech=None（短音频/未传）时行为与引入前完全一致
• VAD 修正在已分离人声（--separate 或先用 separate 子命令）上最准
• 阈值 1.0 经两轮真实音频验证：轻度偏高句多是含正常停顿的合法长句，降阈值会被腰斩，故只夹极虚高者

separate 日志跟随 --verbose

separate / subtitle --separate 的 audio-separator（separator / common_separator / mdx_separator）INFO/WARNING 文本日志默认静默，--verbose 才放行，与转录链路一致。tqdm 进度条保留作分离反馈。

文档

README 新增「修正时间戳漂移」章节、参数表补 --max-seconds-per-char、--verbose help 补 audio-separator。

验证

全量测试 185 passed，ruff 干净，uv lock --check 通过。VAD 修正与 separate 日志均经真实数据 / 捕获 handler 实测确认。

完整改动见 v2.0.1...v2.1.0

v2.0.1

2.0.1

修复 2.0.0 引入的 VAD 长音频回归，并打磨 VAD 扫描体验。

修复

• VAD 长音频 GPU 卡死：2.0.0 的 VAD 跟随转录设备上了 CUDA，但 silero VAD 是 LSTM，隐状态在时间步上串行依赖（窗口 N 必须等 N-1 的 hidden state），架构上无法沿时间轴并行 / 批处理，放 GPU 反被同步 + kernel launch 开销拖垮、比 CPU 慢几个数量级。改为固定 CPU（实测 ~119x 实时，4 小时音频约 2 分钟扫完；silero 官方亦建议跑 CPU）。
• 日志错序 + 看似卡死：VAD 的加载与全程扫描原在转录生成器内部惰性执行，转录进度条已显示 0% 才轮到 VAD 跑。拆成 plan_audio()（探时长 + VAD 探间隙 + 规划，在转录进度条创建之前跑完）+ transcribe_segments()（拿预规划的段逐段转录）。

改进

• VAD 扫描改用 0~100% 进度条（替代逐行 VAD 扫描 N%），与转录进度条顺序出现、互不冲突；修了进度计数 off-by-one（结尾 101% → 正好 100%）。
• 断句逻辑优化。

说明

无对外 CLI / API 变更，按 SemVer 为 patch（2.0.0 → 2.0.1）。

验证

• 全量测试 175 passed，ruff 干净，uv lock --check 通过。
• VAD 端到端冒烟：CPU 路径 6s 扫完 720s 音频、进度条正好止于 100%、规划阶段先于转录阶段。

完整改动见 v2.0.0...v2.0.1

v2.0.0

新特性

长音频分段切点改用 Silero VAD (#56)

长音频分段转录的切点来源，从纯音量阈值（ffmpeg silencedetect）整体换成 Silero VAD 语音活动检测。VAD 能区分「人声 vs 音乐/噪音」，鹿乃长时间唱歌 / BGM 时也能找到真正的人声间隙，切点质量优于音量阈值，不易把语句拦腰截断。

• 新增 kits.vad：探出人声区间、反推非语音间隙作为分段切点
• 走 silero 默认 jit 后端，不装 onnxruntime extra，避开与 audio-separator[gpu] 的 onnxruntime-gpu 共目录冲突
• 音频解码复用 ffmpeg（16k 单声道裸流），不引入 torchaudio 读取路径
• VAD 设备跟随转录器：CUDA 复用提速，其余走 CPU
• 砍掉旧版「宽松阈值二次探测」那条退路——VAD 找间隙的能力本就覆盖了它

# VAD 灵敏度调节
uv run kits subtitle -i live.mp3 --vad-threshold 0.5 --min-silence 0.5

破坏性变更

VAD 替代 silencedetect 后，旧的音量阈值参数不再适用：

• 移除 --silence-db / --fallback-db
• 新增 --vad-threshold（语音概率阈值，0~1，默认 0.5；越大越严格）
• --min-silence 语义改为「短于此（秒）的停顿并入人声、不算切点间隙」

依赖被移除参数的脚本需迁移到 --vad-threshold。按 SemVer 不兼容变更升 MAJOR。

新增依赖 silero-vad + torchaudio，升级后请 uv sync。

完整改动见 v1.7.0...v2.0.0

v1.7.0

新特性

大模型调用泛化为 OpenAI 兼容端点 (#54)

translate / summarize 原本写死 DeepSeek，现泛化为可配置的任意 OpenAI 兼容端点。默认行为完全不变：不配置仍走 DeepSeek，老用户无感。

• 新增 --base-url（或环境变量 KITS_LLM_BASE_URL），可接入 OpenAI 官方、本地 Ollama、vLLM、LM Studio 等任意 OpenAI 兼容端点
• API Key 多级回退：--api-key > KITS_LLM_API_KEY > OPENAI_API_KEY > DEEPSEEK_API_KEY
• 自定义端点允许空 Key（本地模型常无需鉴权），空 Key 时不发 Authorization 头
• base_url 只需给到 /v1 这层，自动补 /chat/completions

# OpenAI 官方
uv run kits summarize -i live.srt --base-url https://api.openai.com/v1 --model gpt-4o-mini --api-key sk-xxxx
# 本地 Ollama（无需鉴权）
uv run kits summarize -i live.srt --base-url http://localhost:11434/v1 --model qwen2.5

破坏性变更

• 移除 kits.deepseek 模块及向后兼容层：DeepSeekClient / DeepSeekError / DeepSeekTranslator 不再存在，统一为 kits.llm.LLMClient / LLMError / LLMTranslator
• 本项目为 CLI 应用、无外部 import 者，对命令行使用无影响

其他

• 新增 tests/test_llm.py 覆盖 Key 回退 / base_url 规整 / 空 Key 策略
• README 新增「接入其他 OpenAI 兼容端点」小节与外发端点安全提示
• README / CONTRIBUTING / CLAUDE 文档同步更新

Full Changelog: v1.6.0...v1.7.0

v1.6.0

新特性

转录进度改用 tqdm 进度条，逐段日志收进进度条 (#47)

字幕转录原本每段刷多行日志（🎤 转录第 i/N 段、✍️ 已写入 X 条），长音频几十段时严重刷屏、把进度条冲乱。改用 tqdm 统一展示：

• 进度条自动显示在终端底部，日志走 tqdm.write() 逐行上滚不冲突
• 逐段信息收进进度条：段号进左侧描述、累计条数进右侧后缀，单行刷新无刷屏

  🎬 第 4/4 段: 100%|██████████| 1200.0/1200.0 [00:49<00:00, 24.11s/s, 累计 232 条]
  

• 进度按音频秒数推进

新增 --verbose / -v 日志开关

默认不限制其他日志，集中过滤掉转录链路的三类刷屏噪音（transformers logging、huggingface_hub 进度条、onnxruntime C++ 警告——这些非 Python warnings、旧的 filterwarnings 拦不住）。加 --verbose 放行全部底层日志 + 逐段边界明细，便于调试。各子命令通用。

其他

• 显式声明 tqdm 依赖
• 新增 tests/test_cli.py
• 支持 Apple Silicon (M 系列) MPS 加速 worked by @littleblacklb

Full Changelog: v1.5.2...v1.6.0

v1.5.2

修复

字幕被 15s 上限截断 (#21)

根因更正：被 max_duration 截断至 15s 的字幕，主因并非「长 chunk 内部缺少句末标点无法切分」，而是 Kotoba 蒸馏模型产出的 chunk 时间戳本身虚高（十几个字的短句被标注成十几二十秒）。这类条目句末标点断句正确、文本无误，只是 start/end 继承了母 chunk 的虚高跨度。

改动：

• 按「字符数 × --max-seconds-per-char（默认 0.5s/字）」对虚高时长进行二次压缩，仅缩短显示时长，不修改文本与起始时间；
• 增加 min_duration=0.5s 下限，避免 Kotoba 偶发将短 chunk 的 start/end 挤在同一点（近零时长导致播放器无法显示）；
• 新增段内重叠处理，消除因收缩及预留间隙产生的时间重叠；
• CLI 新增 --max-seconds-per-char 参数（≤0 时关闭）。

实测（test.mp3，693s 端到端）： 被截断至 15s 的比例由 8.44% 降至 1.31%，时间倒退 0 条，末条覆盖率达 98.6%。

---

Full Changelog: v1.5.1...v1.5.2

v1.5.1

v1.5.1

改进

• subtitle / download --srt 的 --beams 默认值从 1 改为 3 (#36)
  • 默认改用 beam search=3，难句转录更稳；CLI 默认与 Transcriber 函数默认对齐
  • 想要更快仍可显式 --beams 1 回到贪婪解码

内部

• 版本号 1.5.0 → 1.5.1，pyproject 与 uv.lock 同步