B 站深度定制的音乐下载器:歌词片段反查 + whisper 时间轴自动校准。
搜索歌名/歌手/歌词 → 选版本 → 下载纯音频 → 自动打标签 → 自动配歌词 → 自动校准时间轴 → 内嵌封面,一键闭环。
- 特性
- 安装
- 快速开始
- 命令行速查
- MV 下载与字幕
- 决策模式(auto / ai / confirm)
- 歌词时间轴校准(差异化能力)
- Web 界面
- TUI 界面
- 配置
- 便携模式
- 日志与状态显示
- AI 集成(MCP + Skill)
- 测试
- 项目结构
- License
- 项目文档
- 两跳搜索:输入一句歌词(如「窗外的麻雀 在电线杆上多嘴」)→ 网易云反查真实歌名 → B 站选版本
- 一键闭环:
bilimuse get搜索→选版本→下载→打标签→配歌词→校准→入库,全程结构化事件 - 多源元数据:咪咕优先 + 网易云兜底,统一打分选最优(歌名/歌手/时长/版本惩罚);mutagen 打标签,webp 封面自动转 jpeg 内嵌
- 多源歌词:LRCLIB → 网易云 → B 站 AI 字幕降级;外文歌自动配中文译文(网易云双语逐行合并)
- whisper 时间轴校准:语言自动检测(日语歌自动用日语识别)、锚点线性拟合治前留白、置信度过低自动回退不瞎改;信任优先——平台歌词结构健康或官方原曲时不跑 whisper(轻度失配只做线性缩放),whisper 结果经可信度校验(相似度/锚点一致性/时间轴合理性)才采用
- 三端界面:CLI / Textual TUI / Web(FastAPI + WebSocket 实时进度)
- 下载后维护:Web「已下载」历史视图 + 换歌词"后悔药"(重拉候选 → 可选校准 → 重写 .lrc + 重打标签)
- 决策模式:
auto零打扰(默认)/aiLLM 辅助决策(低置信自动升级人工确认)/confirm关键决策人工确认(元数据/歌词/写入终审) - 便携模式(安装默认):config/db/日志全在项目
data/,整个文件夹拷走即用、不污染系统 - 模型管理:
bilimuse model检测/下载/切换,ModelScope 国内高速下载;TUIctrl+m综合管理面板 - 真实网络 E2E 测试集:34 条用例 + 5 首人工标注基准
需要 Python 3.11+。
方式一:统一入口(推荐)
双击 bilimuse-start.cmd(Windows)/ 运行 ./bilimuse-start(Unix)——一个入口搞定「安装 → 配置 → 使用」:首次运行自动建 venv 装全量依赖、自动开启便携模式、自动打开配置向导,之后从菜单启动 TUI / Web / 命令行。
也可命令行安装:
# Windows
.\setup.ps1 # 全量安装,默认便携模式(推荐)
.\setup.ps1 -Standard # 标准模式(config/logs/db 放 %APPDATA%\bilimuse)
.\setup.ps1 -Lite # 轻量模式(仅 m4a)
.\setup.ps1 -Mirror "" # 使用官方 PyPI(默认清华镜像)
# Linux / macOS
./setup.sh # 全量安装,默认便携模式(推荐)
./setup.sh --standard # 标准模式(config/logs/db 放 ~/.config/bilimuse)
./setup.sh --lite # 轻量模式(仅 m4a)
MIRROR= ./setup.sh # 使用官方 PyPI(默认清华镜像)方式二:手动
python -m venv .venv
.venv\Scripts\activate # Windows;Linux/macOS: source .venv/bin/activate
pip install -e . # 轻量(m4a)
pip install -e ".[ffmpeg,align,tui,web,dev]" # 全量(mp3/flac + TUI/Web + 歌词校准)ffmpeg 说明:
.[ffmpeg]通过 PyPI 拉取imageio-ffmpeg(~60MB 静态 ffmpeg,内含 libmp3lame),装完即用、不依赖系统环境、不经 GitHub。仅下载 m4a 可不装。
| 方式 | 命令 |
|---|---|
| 统一入口(推荐) | 双击 bilimuse-start.cmd(Win)/ ./bilimuse-start(Unix):安装→配置→TUI/Web 菜单;也支持 bilimuse-start config|tui|web 直达 |
| 一键 TUI | 双击 bilimuse-tui.cmd(Win)/ ./bilimuse-tui(Unix) |
| 一键 Web | 双击 bilimuse-web.cmd(Win)/ ./bilimuse-web(Unix):启动后浏览器打开 http://127.0.0.1:8000 |
| 项目目录命令 | cmd: bilimuse tui;PowerShell: .\bilimuse tui;Unix: ./bilimuse.sh tui |
| 激活 venv | .\.venv\Scripts\Activate.ps1 后任意目录 bilimuse |
1. 配置(首次必做,向导免手编 json):
bilimuse config # 或双击 bilimuse-config.cmd / 统一入口首次运行自动打开向导设置:下载目录 / 格式 / 歌词源 / 校准开关 / whisper 模型(检测到本地模型自动填路径)/ 扫码登录 B 站 / 代理。建议勾选扫码登录(降风控、提音质)。
2. 一键下载:
bilimuse get "窗外的麻雀 在电线杆上多嘴" # 歌词片段 → 反查「七里香」→ B 站选版本 → 下载+打标签+配歌词校准
bilimuse get "周杰伦 晴天" # 歌名直搜,交互选版本
bilimuse get "周杰伦 晴天" --auto # 自动选第一条(脚本化)
bilimuse get "晴天" --index 2 # 直接选第 2 条3. 找到产物:downloads/ 下 <歌手> - <歌名>.m4a/.mp3 + 同名 .lrc 歌词侧车。
| 命令 | 说明 |
|---|---|
bilimuse get <歌名/歌手/歌词> [--index N|--auto] [--format m4a|mp3|flac] [--no-tag] [--no-lyric] [--align] [--force] [--mv] [--subtitle] |
一键闭环(推荐入口) |
bilimuse search <关键词> [--limit N] |
搜索 B 站版本(Bing 联想自动纠错) |
bilimuse info <BV号> |
查看视频详情 / 分 P |
bilimuse download <BV号> [--page N] [--format m4a|mp3|flac] [--no-tag] [--no-lyric] [--align] [--force] [--mv] [--subtitle] |
下载单曲(--mv 下载视频合流 mp4;--subtitle 附校准歌词 .srt 字幕) |
bilimuse tag <音频文件> [-q 关键词] |
按网易云反查为已有音频打标签 |
bilimuse list-downloads |
下载历史 |
bilimuse login / bilimuse logout |
B 站扫码登录 / 退出(降风控、提音质) |
bilimuse config |
交互式配置向导 |
bilimuse model list |
检测本地/HF 缓存模型 + 配置解析 |
bilimuse model download small [--source modelscope|hf] [--no-set] |
下载 whisper 模型 |
bilimuse model set small|<本地路径> |
设置 whisper_model |
bilimuse portable on|off |
便携模式开关(on 时迁移现有配置) |
bilimuse doctor [--network] |
环境诊断 + 数据源连通性探测 |
bilimuse tui |
Textual 交互式界面 |
bilimuse web [--host 0.0.0.0] [--port 9000] |
Web 界面 |
get/search支持歌词片段搜索:输入一句歌词,自动经网易云反查真实歌名(含原唱歌手信号),再去 B 站选版本;搜索前 Bing 联想自动纠错(打错歌名静默救回)。
- 下载 MV:
bilimuse get/download --mv(或 Web 预览卡片「下载 MV」)→ 视频流+音频流 ffmpeg 合流 mp4(清晰度自动最高,需 ffmpeg,pip install -e ".[ffmpeg]")。 - 字幕:
--mv --subtitle(或 Web 字幕开关)→ 生成.srt侧车。字幕时间轴 = 歌词 whisper 校准结果(MV 音频轨与音频版同流,零额外 ASR);无歌词时 B 站 AI 字幕兜底。 - 音频与 MV 去重独立(
downloads.db按 kind 隔离),互不占位。
下载过程中「匹配哪首元数据、用哪个源的歌词、校准后的歌词是否写入」三个决策点,由 mode 决定谁拍板:
| 模式 | 行为 | 适用 |
|---|---|---|
auto(默认) |
全自动,零打扰(现状行为) | 日常批量 |
ai |
LLM 决策(结构化 JSON),置信度低于阈值时自动升级弹窗问你;无 key/失败降级 auto | 想要省心又要有保障 |
confirm |
每个决策点弹窗确认,弹窗默认项 = AI 建议(有 key 时) | 追求精确 |
- LLM 免费:内置厂商预设(默认智谱 GLM-4-Flash,永久免费、国内直连,
bilimuse config向导或 TUI 面板里引导注册拿 key);也支持 DeepSeek(低价备选)/硅基流动/百炼/任意 OpenAI 兼容端点(含聚合网关)。 - 三端一致:confirm/ai 模式在 CLI(input 交互)、TUI(弹窗)、Web(弹窗,WS 双向回传)行为对齐;
ai低置信或无 key 时升级弹窗人工确认。 - Web 端评审弹窗:任务下载到决策点时弹出(元数据候选/歌词候选/写入终审,含歌词双栏对比),选项点击即回传,可「跳过(默认)」;多任务并发评审排队依次处理。
confirmation_threshold(默认 60):AI 置信度低于此值才升级人工确认。- CLI 下
--auto或非交互(管道/CI)自动跳过评审 = auto 行为;Esc(TUI)/Ctrl+D(CLI)同样选默认。
下载后自动配歌词并校准时间轴:
- 多源歌词降级:LRCLIB → 网易云 → B 站 AI 字幕(需登录兜底);外文歌自动反查网易云双语(原句 + 中文译文逐行交替)。
- 信任优先校准(v1.1):
- 结构健康判定:时间戳单调、跨度覆盖音频主体、行距合理 → 平台歌词可信(LRCLIB/网易云对官方原曲是 CD 精确同步);
- 官方原曲(UP 主/标题含「官方/Official」):直接信任原样保存,不跑 whisper、不线性压缩(片头/片尾留白是视频特性);
- 轻度失配(末行偏差 ≤30s 或 20%):线性缩放修正,同样不跑 ASR;
- 强制对齐:仅当源歌词结构损坏(乱序/只覆盖前段/行距异常)或重度失配时才跑 lyric-align(whisper 转写 + 字符级模糊锚定)——翻唱/视频变速等原词能对上但时间轴不对的场景是主战场。
- 语言自动检测:假名→日语、谚文→韩语、汉字→中文……日语歌自动用日语识别(硬编码 zh 会让匹配率从 96% 掉到 32%)。
- 智能回退:whisper 对齐结果经可信度校验(匹配行平均相似度 ≥0.55、锚点偏移 MAD ≤5s、输出时间轴单调且在音频范围内),不达标降级锚点线性拟合(
align_offset,治官方 MV 前留白),再不过保留原歌词并警告——宁回退不瞎改。 - 进度可见:校准流式输出步骤(转写中/分段/匹配阈值/对齐行数/wrote out.json)。
whisper_model 支持模型名或本地目录路径。国内推荐 ModelScope 下载后填本地路径:
bilimuse model list # 检测 models/ + HF 缓存
bilimuse model download small # ModelScope 下载到 models/faster-whisper-small(默认写入配置)
bilimuse model download large-v3-turbo --source hf # 或走 HF 镜像
bilimuse model set models/faster-whisper-small # 手动切换- 模型档位:
tiny/base/small/medium/large-v3-turbo(small 约 460MB,够用;更大更准更慢)。 - 更准但更慢可用
medium/large-v3-turbo;混音重伴奏歌可装pip install -e ".[separate]"并设"vocal_separate": true(Demucs 人声分离,需 torch)。
浏览器操作,适合批量/服务化。
1. 安装 Web 依赖:
pip install -e ".[web]" # fastapi / uvicorn / websockets2. 启动:
bilimuse web # 默认 http://127.0.0.1:8000
bilimuse web --port 9000 # 换端口
bilimuse web --host 0.0.0.0 # 局域网其他设备访问(cmd 下:.\bilimuse web;Unix:./bilimuse.sh web)
3. 浏览器打开 http://127.0.0.1:8000
- 首次使用:自动弹出引导(下载目录/格式),可跳过;登录/模型/更多配置在「设置」「模型」页
- 搜索:输入歌名 / 歌手 / 歌词片段(如「窗外的麻雀 在电线杆上多嘴」)回车 → 结果表显示来源(
歌词反查/直接)、BV 号、时长、播放量、UP 主、标题 - 预览:点击结果行 → 右侧显示封面并自动播放(B 站官方播放器);当前行高亮,可收起;「下载这首歌」/「下载 MV」(可勾选字幕)
- 批量下载:勾选多首(或全选)→「加入队列」→ 右侧队列面板实时显示每首状态(排队/下载中/完成/失败/连接中断)、进度条、来源与校准信息;可单独取消任务。任务完成/取消即从队列消失(toast 保留),失败任务保留可重试
- 已下载视图:「已下载」页 = 跨会话持久下载历史,行内「换歌词」打开候选弹窗(来源 radio + 歌词预览 + 可选校准)→ 应用后重拉候选防陈旧、重写
.lrc并重打标签("后悔药") - 搜索联想:输入后自动 Bing 纠错(打错歌名静默替换 + toast),结果上方「你可能想搜」建议条可点击重搜
- 设置页:下载目录/格式/歌词源/校准开关/决策模式/LLM(key 掩码显示,留空不覆盖)/代理等全字段编辑
- 扫码登录:设置页「扫码登录 B 站」→ 弹窗显示二维码 → 手机确认后自动写入登录态(提升音质、降风控)
- 模型页:检测本地/HF 缓存模型、下载 whisper 模型(ModelScope/HF,进度入队列)、设置 whisper_model
- 顶部信息栏:Python 版本、登录态、lyric-align/模型状态、已检测模型
- 并发:单连接内最多 2 个任务并行,其余排队;断线自动重连
4. HTTP API(可脚本化)
| 接口 | 说明 |
|---|---|
GET /api/search?q=晴天&limit=10 |
两跳搜索(含歌词反查) |
GET /api/doctor |
环境 + 模型解析 + 检测列表 + configured(是否已配置) |
GET /api/config / POST /api/config |
读取(敏感字段掩码)/ 更新配置(白名单校验,空 key 不覆盖) |
GET /api/login/qrcode |
扫码登录二维码(SVG data URI) |
GET /api/login/poll?key= |
轮询登录态(waiting/scanned/expired/success;成功写入 sessdata) |
GET /api/suggest?q= |
搜索联想/纠错(Bing,免费无 key):{corrected, suggestions} |
GET /api/model / POST /api/model/set |
模型信息 / 设置 whisper_model |
POST /api/lyric/candidates |
换歌词:候选歌词列表(按路径反查,重拉防陈旧) |
POST /api/lyric/apply |
应用候选歌词(可选校准)→ 写 .lrc 侧车 + 重打标签 |
WS /ws/download |
WebSocket 多任务:{"cmd":"start","id","bvid","page","format","mv","subtitle"}(旧协议兼容为 start)/ {"cmd":"cancel","id"} / {"cmd":"model_download","id","size","source"} → 事件带 task 字段(stage/progress/meta/lyric/warning/result/error/cancelled) |
提示:首次使用先 bilimuse config 向导里登录 B 站并配置本地 whisper_model,Web 端直接生效;下载产物默认在 downloads/。
Textual 交互式终端界面(pip install -e ".[tui]"):
bilimuse tui- 输入歌名/歌词搜索 → 结果表选中回车下载 → 进度条 + 阶段状态实时显示
ctrl+m打开综合管理面板:whisper 模型 list/download/set(带进度)、LLM 预设一键填充/配置、常规配置(下载目录/格式/歌词源/校准开关),保存即生效mode=confirm时下载过程弹出评审弹窗(元数据候选/歌词候选/写入前终审),↑↓选择、Enter确认、Esc选默认- Windows 中文输入:需在 Windows Terminal 中运行(conhost 不支持 IME);偶发打不出中文是系统级 IME 间歇 bug,切换输入法(
Win+空格)或重启终端即可恢复;持续失效可在 WT 设置profiles.defaults加"experimental.win32InputMode": true
配置文件位于 data/config.json(便携模式,默认)或 %APPDATA%\bilimuse\config.json(Windows)/ ~/.config/bilimuse/config.json(Linux/macOS):
{
"download_dir": "downloads",
"format": "m4a",
"sessdata": "",
"buvid3": "",
"proxy": "",
"ffmpeg_path": "",
"ua": "Mozilla/5.0 ...",
"filename_template": "{artist} - {title}.{ext}",
"lyric_sources": ["lrclib", "netease", "bilibili"],
"search_lyric_lookup": true,
"translation_enabled": true,
"align_enabled": true,
"whisper_model": "small",
"whisper_language": "zh",
"vocal_separate": false,
"log_level": "INFO",
"hf_mirror": "https://hf-mirror.com",
"mode": "auto",
"confirmation_threshold": 60,
"llm_base_url": "",
"llm_api_key": "",
"llm_model": ""
}| 字段 | 说明 |
|---|---|
download_dir |
下载目录 |
format |
输出格式 m4a(直拷,免 ffmpeg)/ mp3 / flac(需 ffmpeg;flac 仅当源为 VIP 无损流) |
sessdata |
B 站登录 cookie(bilimuse login 扫码写入),提升音质、降风控、解锁 AI 字幕歌词兜底 |
buvid3 |
B 站匿名设备标识(自动维护) |
proxy |
需要代理访问 B 站时填写 |
ffmpeg_path |
显式指定系统 ffmpeg,优先于内嵌版本 |
filename_template |
文件名模板,默认 {artist} - {title}.{ext} |
lyric_sources |
歌词源降级顺序 |
search_lyric_lookup |
搜索时是否经网易云按歌词正文反查歌名(默认开,歌词片段搜索的关键) |
translation_enabled |
外文歌自动配中文译文(网易云 tlyric 双语合并,默认开) |
align_enabled |
歌词时间轴校准(默认开;关则只做快速校准) |
whisper_model |
模型名或本地目录路径(ModelScope 下载后填路径) |
whisper_language |
ASR 语言兜底(自动检测失败时用,默认 zh) |
vocal_separate |
是否 Demucs 人声分离(需 .[separate],混音重伴奏歌更准) |
log_level |
日志级别 DEBUG/INFO/WARNING/ERROR(默认 INFO) |
hf_mirror |
HuggingFace 镜像(默认 hf-mirror.com) |
mode |
决策模式 auto/ai/confirm(默认 auto,见上文「决策模式」) |
confirmation_threshold |
AI 低置信升级人工的阈值 0-100(默认 60) |
llm_base_url |
LLM 端点(留空 = 默认预设 智谱 GLM-4-Flash) |
llm_api_key |
LLM API key(敏感,不落日志;doctor 只显示已配置/未配置) |
llm_model |
LLM 模型名(留空 = 预设 glm-4-flash) |
环境变量:MUSICALBILI_CONFIG_DIR(指定配置目录,优先级最高)、MUSICALBILI_PORTABLE=1(一次会话便携)、MUSICALBILI_LOG_LEVEL(覆盖日志级别)。
安装默认开启(setup / 统一入口自动创建 .portable):config.json/downloads.db/logs/ 全部落在项目内 data/,连同 downloads/、models/、.venv/ 都在项目目录里——整个文件夹拷走即用、即用即下即删即走,不污染系统环境。
bilimuse portable on # 手动开启:创建 .portable,并把现有配置(含登录态)复制到 data/
bilimuse portable off # 关闭:删除 .portable(数据保留在 data/)
bilimuse doctor # 查看当前 模式(便携/标准) + 配置目录- 不想要便携:安装时用
setup.ps1 -Standard/setup.sh --standard;或装后bilimuse portable off。 - 也可用环境变量
MUSICALBILI_PORTABLE=1(一次会话)触发。 .portable标记文件随目录走:拷到别处仍保持便携。
- 日志文件:
<配置目录>/logs/bilimuse.log(1MB×3 滚动;便携data/logs,标准%APPDATA%\bilimuse\logs或~/.config/bilimuse/logs)。 - 统一状态通道:CLI/TUI/Web 三端动态显示「系统在做什么」——搜索(含歌词反查)、解析元数据(按源:咪咕/网易云)、获取歌词(按源:LRCLIB/网易云/B 站字幕)、下载进度、whisper 校准(步骤级)、配置向导(等待输入/已设置)。同一条状态同时写入日志,方便排查。
- 排查:
bilimuse doctor显示日志路径;部署问题看setup.log。
AI 助手可直接驱动 BiliMuse 搜索与下载(零额外依赖):
- 启动 MCP server:
bilimuse mcp(stdio,换行分隔 JSON,无网络端口)。工具:search/info/get/download/list_downloads/config_get/config_set/doctor/model_list/model_download/model_set/suggest(12 个,映射现有服务,get/download走一键闭环)。 - Skill 文档:
.claude/skills/bilimuse/SKILL.md(Claude Code 技能形态,含工具表与两跳搜索示例)。 - 示例:
search歌词片段 →get取版本 → 返回本地文件路径与元数据摘要。
python -m pytest tests -q # 单元/集成(205 例,e2e 默认排除)
python -m ruff check bilimuse tests # Lint真实网络 E2E 集(tests/e2e/,34 条用例,YAML 驱动,机器校验 + 人工评审双轨):
python tests/e2e/run_testset.py # 全套(真实下载链路)
python tests/e2e/run_testset.py --only C01,C05 # 指定用例
python tests/e2e/run_testset.py --no-align # 关 whisper 校准(快速冒烟)
python tests/e2e/run_testset.py --config-dir <dir> # 隔离配置目录(含 sessdata/模型,避免污染真实配置)
python tests/e2e/align_bench.py # 校准基准:whisper 对齐 vs gold/ 人工标注,算中位误差
pytest -m e2e # 或以 pytest 运行(需真实网络)- 用例矩阵覆盖:中文经典 / 歌词片段反查 / 日英粤韩 / 格式(m4a/mp3/flac)/ 边界异常 / 校准专项 / Web 三端。
- 校准判定:中位误差 ≤1.5s 优、≤3.0s 通过、>3.0s 失败。详见 tests/e2e/README.md。
bilimuse/
├─ cli.py # typer CLI 入口 + 配置向导 + model/portable 子命令
├─ config.py # 配置加载/保存;便携模式单一枢纽 default_config_dir()
├─ db.py # SQLite 下载历史(bvid+cid 去重)
├─ logging_setup.py # 文件滚动日志 + console WARNING(filter 排除状态通道)
├─ status.py # 统一状态通道 emit(日志 + UI 双写)
├─ models.py # SongMeta / Lyric 数据模型
├─ providers/ # bilibili.py(Wbi 签名/搜索双端点/playurl/AI 字幕)、meta.py(咪咕→网易云)
├─ services/ # search.py(两跳)pipeline.py(事件化闭环)download.py tagger.py lyric.py aligner.py auth.py
├─ tui.py # Textual 交互式界面
├─ web.py # FastAPI + WebSocket(复用 pipeline 事件)
└─ web/static/ # 原生单页前端(零构建)
tests/ # 单元/集成测试
tests/e2e/ # 真实网络 E2E 集(cases.yaml + run_testset.py + align_bench.py + gold/)
本项目采用 GPL-3.0-or-later(见 LICENSE)。
许可说明:
- 核心依赖
mutagen(打标签)为 GPL-2.0-or-later,故本项目需 GPL 兼容;其余依赖(httpx BSD-3 / pydantic / typer / textual / fastapi / lyric-align / faster-whisper 等 MIT)均兼容 GPL-3.0。 - 可选
[ffmpeg]extra 内嵌的 ffmpeg(imageio-ffmpeg)含 GPL 组件,若未来打包独立可执行文件分发,需按 GPL 附带源码与许可声明。
- 需求与调研:idea.md | 技术方案:PLAN.md | 开发日志:docs/devlog | E2E 测试集:tests/e2e/README.md