BBDown GUI 下载与转文字工具

这是一个基于 uv 管理的 Python/Tkinter 桌面工具，集成：

• BBDown 收藏夹 / 视频合集 / 单视频下载 GUI
• 下载前视频选择弹窗（全选 / 反选 / 搜索过滤，支持 Shift / Ctrl 多选）
• Faster-Whisper 音频/视频转文字
• Windows 文件夹版 exe 打包
• 同目录 bbdown.exe 自动检测

推荐使用

当前仓库推荐 源码运行优先。GitHub Release 仅提供 lite 版（仅下载功能，由 CI 自动构建发布）；full 版（含转文字依赖）体积过大，需本地打包，不通过 Release 分发。

原因：转文字功能依赖 Faster-Whisper、CUDA、cuBLAS、cuDNN、onnxruntime 等大文件。如果把完整 Windows 发布包上传到 GitHub Releases，压缩后仍可能超过 1GB，上传和下载都不稳定。

下载发布版

前往 GitHub Releases，下载对应版本的 BilibiliDownloaderUI-windows-x64-vX.Y.Z.zip：

1. 解压 zip（建议保留顶层 BilibiliDownloaderUI 文件夹完整，不要只复制 exe）。
2. 双击 BilibiliDownloaderUI\BilibiliDownloaderUI.exe 启动。
3. BBDown 不内置：把 bbdown.exe 放到 exe 同目录，或依赖 C:\Users\<用户名>\.dotnet\tools\BBDown.exe，或在 GUI 中手动选择。

需要转文字的用户请按下文源码运行（uv sync --extra transcribe），或维护者本地打包 full 版（流程见 docs/本地打包指南.md）。

1. 克隆源码

git clone https://github.com/cyforkk/bbdown-gui-transcriber.git
cd bbdown-gui-transcriber

2. 安装 uv

如果还没有安装 uv，请先安装 uv。

安装完成后确认：

uv --version

3. 安装 Python 依赖

如果只需要下载视频/音频，不需要转文字，使用轻量安装：

uv sync

轻量安装不会安装 Faster-Whisper、CUDA、cuBLAS、cuDNN 等转文字大依赖，安装更快，占用空间更小。

如果需要使用转文字功能，再安装 transcribe 可选依赖：

uv sync --extra transcribe

transcribe extra 会安装 Faster-Whisper 以及 CUDA 转文字相关依赖。

4. 安装或准备 BBDown

本项目不内置 BBDown。

如果使用 .NET global tool 安装 BBDown（此方式需要先安装 .NET SDK），可以执行：

dotnet tool install --global BBDown

确认 BBDown 可用：

bbdown --version

GUI 检测 BBDown 的顺序：

1. 当前工作目录下的 bbdown.exe / BBDown.exe（文件名忽略大小写）
2. 用户目录 .dotnet/tools（如 C:\Users\<用户名>\.dotnet\tools\BBDown.exe，忽略大小写）
3. exe 同目录的 bbdown.exe（源码运行时为项目根目录）
4. 系统 PATH 中的 bbdown
5. 用户手动点击 选择 bbdown

注意：.NET global tool 安装目录里的 bbdown.exe 不建议复制到项目目录或发布目录当便携版使用。检测链路已直接包含 .dotnet/tools 原始路径，无需复制。

5. 运行 GUI

推荐：

uv run bbdown-gui

或：

uv run python -m bbdown_gui.app

6. 转文字环境说明

转文字功能基于 Faster-Whisper，默认配置：

model=medium
device=cuda
compute_type=int8_float16

因此需要本机具备可用的 NVIDIA 显卡和驱动环境。

转文字前还会调用 ffprobe 预校验媒体文件（可选）。如果系统 PATH 中没有 ffprobe（通常随 ffmpeg 一起安装），会跳过预校验，损坏或无音频流的文件要等到 Whisper 转写阶段才报错。建议安装 ffmpeg 以获得更好的体验。

如果点击转文字时提示 当前未安装转文字依赖，请执行：uv sync --extra transcribe，请先安装 transcribe extra。

如果遇到 CUDA DLL、cuBLAS、cuDNN 相关错误，请优先确认：

• NVIDIA 驱动是否正常
• uv sync 是否成功完成
• 当前环境是否能正常加载 Faster-Whisper

7. 可选：自行打包 Windows 文件夹版

如果你希望在本机生成可双击运行的 Windows 文件夹版，可以按需求选择 lite 或 full 版本。

只需要下载功能时，打包轻量版：

uv run python scripts\build_exe.py --edition lite

需要转文字功能时，先安装转文字依赖，再打包 full 版：

uv sync --extra transcribe
uv run python scripts\build_exe.py --edition full

生成目录：

dist\BilibiliDownloaderUI\

启动文件：

dist\BilibiliDownloaderUI\BilibiliDownloaderUI.exe

文件夹版比单文件版启动更快，因为依赖不需要每次启动都解压。lite 版只包含下载功能，体积更小；full 版包含转文字相关依赖，体积明显更大。不建议把打包结果提交到 git。

完整打包流程、产物结构、验证与常见问题见 docs/本地打包指南.md。

当前目录结构

D:\bbdown脚本\
├─ src\
│  └─ bbdown_gui\
│     ├─ __init__.py
│     ├─ app.py                # Tkinter GUI（含视频选择弹窗）
│     ├─ downloader.py         # BBDown 下载逻辑（含 WBI 签名与风控重试）
│     └─ transcriber.py        # Faster-Whisper 转文字逻辑
├─ tests\
│  ├─ test_app.py
│  ├─ test_downloader.py
│  ├─ test_transcriber.py
│  └─ test_build_exe.py
├─ scripts\
│  ├─ build_exe.py             # PyInstaller 打包脚本
│  └─ release_readme.txt       # 发布说明模板（打包时复制为 README.txt）
├─ docs\
│  ├─ 功能总和文档.md
│  ├─ 问题总和文档.md
│  ├─ 本地打包指南.md
│  ├─ GitHubActions自动发布流程.md
│  ├─ GitHubRelease发布说明.md
│  └─ PyInstaller文件夹版和单文件版区别.md
├─ skills\
│  ├─ dev-playbook\            # 通用开发工作流 Skill
│  ├─ bbdown-map\              # 项目地图 Skill
│  └─ release-playbook\        # 提交与发布流程 Skill
├─ .github\
│  └─ workflows\
│     └─ release.yml           # Release 自动构建流水线
├─ README.md
├─ pyproject.toml
├─ uv.lock
├─ .python-version
└─ .gitignore

打包产物 build/、dist/、release/ 均在 .gitignore 排除，不提交进 git。

环境准备

首次拉取项目后执行：

uv sync

源码运行 GUI：

uv run python -m bbdown_gui.app

或：

uv run bbdown-gui

功能说明

下载功能

• 收藏夹批量下载
• 视频合集批量下载（链接形如 https://space.bilibili.com/<mid>/lists/<id>?type=season）
• 单个视频链接 / BV 号下载
• 下载前视频选择弹窗（默认全选，支持全选 / 全不选 / 反选 / 搜索过滤，Shift 范围选、Ctrl 追加切换）
• 音频 / 视频二选一
• 选择下载目录
• 自动检测或手动选择 BBDown
• 停止下载
• 隐藏 BBDown 子进程 CMD 窗口
• 大列表分页拉取（进度日志 + 去重 + 差额警告）

转文字功能

• 单个音频/视频文件转文字
• 文件夹批量转文字
• 支持 .m4a、.mp3、.wav、.flac、.aac、.mp4
• .mp4 视频转文字识别的是视频里的音频流，不是画面 OCR
• 默认模型：medium
• 默认设备：cuda
• 默认计算类型：int8_float16
• 输出同名 .txt
• 支持停止任务

批量转文字说明

选择文件夹批量转文字时，Faster-Whisper 模型只加载一次，后续文件复用同一个模型实例。

加载模型 1 次
处理文件 1
处理文件 2
处理文件 3
...

如果某个文件损坏或没有识别到文字，不会中断整个批量任务，会在最终统计里列出失败原因。

视频转文字说明

视频转文字流程：

视频文件 -> 读取音频流 -> Faster-Whisper 语音识别 -> 输出 txt

不支持：

• 识别画面文字
• OCR
• 无音频流视频

运行测试

uv run python -m unittest discover -s tests

常见问题

找不到 BBDown

把 bbdown.exe 放到 BilibiliDownloaderUI.exe 同目录，或在 GUI 中点击 选择 bbdown。

首次转文字很慢

Faster-Whisper 首次加载模型或下载模型缓存可能较慢，属于正常现象。

视频转文字没有结果

确认视频有音频流。当前不会识别画面字幕或画面文字。