Skip to content

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

27 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BiliMuse 图标

BiliMuse

B 站深度定制的音乐下载器:歌词片段反查 + whisper 时间轴自动校准

搜索歌名/歌手/歌词 → 选版本 → 下载纯音频 → 自动打标签 → 自动配歌词 → 自动校准时间轴 → 内嵌封面,一键闭环。

演示

▶ B 站观看宣传视频(83s,实机操作 + AI 旁白)

目录

特性

  • 两跳搜索:输入一句歌词(如「窗外的麻雀 在电线杆上多嘴」)→ 网易云反查真实歌名 → B 站选版本
  • 一键闭环bilimuse get 搜索→选版本→下载→打标签→配歌词→校准→入库,全程结构化事件
  • 多源元数据:咪咕优先 + 网易云兜底,统一打分选最优(歌名/歌手/时长/版本惩罚);mutagen 打标签,webp 封面自动转 jpeg 内嵌
  • 多源歌词:LRCLIB → 网易云 → B 站 AI 字幕降级;外文歌自动配中文译文(网易云双语逐行合并)
  • whisper 时间轴校准:语言自动检测(日语歌自动用日语识别)、锚点线性拟合治前留白、置信度过低自动回退不瞎改;信任优先——平台歌词结构健康或官方原曲时不跑 whisper(轻度失配只做线性缩放),whisper 结果经可信度校验(相似度/锚点一致性/时间轴合理性)才采用
  • 三端界面:CLI / Textual TUI / Web(FastAPI + WebSocket 实时进度)
  • 下载后维护:Web「已下载」历史视图 + 换歌词"后悔药"(重拉候选 → 可选校准 → 重写 .lrc + 重打标签)
  • 决策模式auto 零打扰(默认)/ ai LLM 辅助决策(低置信自动升级人工确认)/ confirm 关键决策人工确认(元数据/歌词/写入终审)
  • 便携模式(安装默认):config/db/日志全在项目 data/,整个文件夹拷走即用、不污染系统
  • 模型管理bilimuse model 检测/下载/切换,ModelScope 国内高速下载;TUI ctrl+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 下载与字幕

  • 下载 MVbilimuse 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 隔离),互不占位。

决策模式(auto / ai / confirm)

下载过程中「匹配哪首元数据、用哪个源的歌词、校准后的歌词是否写入」三个决策点,由 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)
    1. 结构健康判定:时间戳单调、跨度覆盖音频主体、行距合理 → 平台歌词可信(LRCLIB/网易云对官方原曲是 CD 精确同步);
    2. 官方原曲(UP 主/标题含「官方/Official」):直接信任原样保存,不跑 whisper、不线性压缩(片头/片尾留白是视频特性);
    3. 轻度失配(末行偏差 ≤30s 或 20%):线性缩放修正,同样不跑 ASR;
    4. 强制对齐:仅当源歌词结构损坏(乱序/只覆盖前段/行距异常)或重度失配时才跑 lyric-align(whisper 转写 + 字符级模糊锚定)——翻唱/视频变速等原词能对上但时间轴不对的场景是主战场。
  • 语言自动检测:假名→日语、谚文→韩语、汉字→中文……日语歌自动用日语识别(硬编码 zh 会让匹配率从 96% 掉到 32%)。
  • 智能回退:whisper 对齐结果经可信度校验(匹配行平均相似度 ≥0.55、锚点偏移 MAD ≤5s、输出时间轴单调且在音频范围内),不达标降级锚点线性拟合(align_offset,治官方 MV 前留白),再不过保留原歌词并警告——宁回退不瞎改。
  • 进度可见:校准流式输出步骤(转写中/分段/匹配阈值/对齐行数/wrote out.json)。

whisper 模型管理

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)。

Web 界面

浏览器操作,适合批量/服务化。

1. 安装 Web 依赖

pip install -e ".[web]"        # fastapi / uvicorn / websockets

2. 启动

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/

TUI 界面

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 集成(MCP + Skill)

AI 助手可直接驱动 BiliMuse 搜索与下载(零额外依赖):

  • 启动 MCP serverbilimuse 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/)

License

本项目采用 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 附带源码与许可声明。

项目文档

About

Bilibili 音乐下载器:歌词/歌名/歌手搜索(含歌词正文反查)→ 选版本 → 下载纯音频 → 自动打标签/封面/歌词 → whisper 歌词时间轴自动校准 → 双语歌词。CLI / Textual TUI / Web 三端。

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages