BiliMusic

把哔哩哔哩里的声音，整理成一张属于你的播放桌面。

基于 Flutter 的 B 站音乐播放器 · 跨平台 · GUI/TUI · 漫游发现 · 局域网同步

BiliMusic 是一款围绕 B 站音频内容打造的跨平台音乐播放器。基于 Flutter 一次覆盖 Windows、Linux、Android，并对 macOS、Web 提供实验性支持。它不复制视频平台，只做播放器该做的事：搜索、整理、连续播放与跨设备同步。

• 安全
• 背景
• 平台支持
• 安装
  • 直接安装
  • 从源码运行
  • 构建发布版本
  • 终端客户端（TUI）
• 用法
  • 常用入口
  • 漫游模式
  • 设备同步
• 核心特性
• 界面预览
• 登录与数据
• 更新与版本
• 技术架构
• 代码导航
• 主要依赖
• 开发命令
• 维护者
• 致谢
• 如何贡献
• 许可证
• Star History

主流 B 站客户端是完整的视频平台，对「只想听声音」的场景并不友好：后台播放受限、歌单能力弱、跨设备体验割裂。BiliMusic 把 B 站视为音乐内容源，专注于播放器的本职——搜索、整理、播放、漫游、同步。

技术选型上，Flutter 提供一套代码覆盖桌面与移动端；Riverpod 承担状态管理与依赖注入；just_audio 与 libmpv 负责音频解码；局域网同步通过 mDNS 与 TCP 配对实现。代码按 UI / 状态 / 编排 / 领域模型 / 基础设施分层，核心网络与存储层保持纯 Dart，以便 TUI 复用。

作者本人也是重度听歌爱好者，软件的开发会注重使用体验，在上线新功能时会反复打磨（其实是听了半天），这一块不用担心。

关于应用内更新：Android / Windows / Linux 支持；Web 与 macOS 跳转 Releases（见更新与版本）。

前往 Releases 下载对应平台的最新版本，解压运行即可。

• Android / Windows / Linux：启动时自动检查更新。
• macOS / Web：需手动重新下载。

# Linux 用户需要先安装依赖
sudo apt install libmpv-dev

环境要求：Flutter 3.x · Dart SDK ^3.13.0

git clone https://github.com/NaivG/bilimusic.git
cd bilimusic
flutter pub get
flutter run               # 默认设备
flutter run -d <device-id> # 指定设备

flutter build windows
flutter build linux
flutter build apk
flutter build macos
flutter build ios

# Web 需先生成 sqlite 资源
flutter pub run sqflite_common_ffi_web:setup --force
flutter build web

Web 端 sqlite 资源（web/sqlite3.wasm、web/sqflite_sw.js）不入库，必须由 setup 命令生成，否则构建产物无法初始化本地数据库。

仓库附带一个实验性终端客户端，与 App 共享登录状态（当前基于 Windows 下的 libmpv）：

dart run bin/bilimusic_tui.dart            # 交互式 TUI
dart run bin/bilimusic_tui.dart --probe    # 网络与解码分层自检
dart run bin/bilimusic_tui.dart --smoke    # 无终端驱动完整循环
dart run bin/bilimusic_tui.dart --preview  # 静态设计预览（假数据，无网络无声）

典型路径：

搜索内容 → 加入歌单 → 开始播放 → 匹配歌词与主题 → 漫游扩展 → 局域网同步

1. 在个人中心进入漫游模式。
2. 选择歌单或歌曲作为种子。
3. 选择「相似 / 平衡 / 探索」风格。
4. 队列接近末尾时自动发现并补充相关歌曲。

同局域网内开启设备同步：应用通过 mDNS 发现设备，通过二维码或配对请求建立信任连接，之后可同步播放状态、队列与远程控制。

发现与推荐

• 支持 BV 号、AV 号与关键词搜索。
• 首页推荐、猜你喜欢、播放历史。
• 基于 simhash 的相关度排序与漫游补队列。
• 三种漫游风格：相似 / 平衡 / 探索。

播放体验

• 播放 / 暂停 / 上一首 / 下一首 / 进度跳转；定时关闭。
• 多 P 视频切换、顺序 / 随机 / 单曲循环。
• A/B 双播放器 + equal-power 曲线的交叉淡入淡出。
• 多档音质选择，DASH 音频流按选择取流并回显实际生效音质。
• 后台播放、系统媒体通知、音量持久化。
• 动态歌词：自动匹配、逐字点亮、辉光效果。
• 主题系统：Lucent / Nocturne / Verdant / Gruvbox / Nord / Solarized 六套主题，运行时切换并按封面主色适配。
• 离线缓存：歌曲可下载到本地，断网也能继续播放。

整理与同步

• 本地歌单：创建、编辑、删除、拖拽排序、滑动删除。
• B 站收藏夹导入并跟踪同步状态。
• mDNS 局域网发现 + TCP 二维码配对 + 远程播放控制。
• 支持手表、折叠屏外屏与近方形 PiP 窗口布局。

终端客户端（TUI）

• 主页与搜索结果两页布局，支持关键词 / BV / AV 搜索、播放、暂停与切歌，键盘与鼠标可用。
• FFI 直驱 libmpv（复用 media_kit 的 Windows 库产物），与 App 共享登录态与网络层。
• 附带 --probe / --smoke / --preview 自检、驱动与预览模式。

默认使用 Verdant 主题展示。

_{首页 · 推荐与播放历史}

_{播放页 · 封面、歌词与播放控制}

_{歌单 · 本地歌单与 B 站收藏夹}

部分 B 站功能需要登录：

• 移动端：通过 gt3_flutter_plugin 完成账号密码登录。
• 桌面端：使用 B 站 App 扫码登录。
• 数据迁移：可在数据管理中将移动端数据迁移到桌面端。

数据存储：歌单、收藏和历史保存在本地 SQLite；设置使用 shared_preferences；网络资源与歌词进入本地缓存；歌曲可另存为离线缓存，断网可播。迁移或清理前请做好备份。

应用启动后自动检查一次新版本，发现更新时弹出更新日志与「立即更新」按钮。检查与下载是两套独立操作：

各平台行为：

• Android：经 flutter_app_update 下载 APK 并拉起系统安装页；Android 13+ 会先申请通知权限以展示下载进度。
• Windows / Linux：下载便携版 zip，校验 sha256 后原地替换文件并重启。
• Web / macOS：不支持应用内更新，点击后跳转 Releases 页面手动下载。

UI / Riverpod Provider
        ↓
PlayerCoordinator  ←── RoamingService
        ↓
DualAudioService  ←── NotificationService / PiP / LAN Sync
        ↓
ApiService
        ↓
BiliClient  ←── Bilibili API

长生命周期服务统一在 lib/app/app_providers.dart 中创建与释放；UI 只消费 Provider，不直接实例化业务管理器。

lib/
├── main.dart                  # 应用入口：窗口、数据库、audio_service 初始化
├── app/                       # app_providers.dart 组合根 + shells/ 应用外壳与导航
├── core/                      # 无 UI 基础设施
│   ├── network/               # BiliClient、ApiService、PassportClient 与异常体系
│   └── storage/               # AppDatabase(SQLite) 与 CacheManager
├── domain/                    # 纯共享模型：Music、Playlist、BiliItem、PeerDevice 等
├── features/                  # 功能模块，内部按 logic/ models/ ui/ 分层
│   ├── player/                # PlayerCoordinator、DualAudioService、通知、PiP、正在播放页
│   ├── lyrics/                # 歌词检索、多源匹配与逐字渲染
│   ├── playlist/              # 歌单 / 收藏 / 历史的单一数据源
│   ├── roam/                  # 漫游模式：simhash 排序、种子多样性与风格策略
│   ├── lan_sync/              # 局域网同步：mDNS 发现、二维码配对、远程控制
│   ├── offline/               # 离线缓存：下载管理、断网播放与缓存清理
│   ├── auth/                  # 扫码登录、验证码与 Cookie 管理
│   ├── fav_sync/              # B 站收藏夹导入与同步状态跟踪
│   ├── home/ search/ profile/ # 首页推荐、搜索、个人中心
│   └── settings/ update/      # 设置、数据迁移；更新检查、Release 解析、应用内更新与更新日志
└── shared/                    # 跨模块共享：widgets/、theme/(Lucent/Nocturne/Verdant/Gruvbox/Nord/Solarized)、utils/

bin/
├── bilimusic_tui.dart         # 终端客户端入口（dart_tui + libmpv FFI）
└── tui/                       # TUI 内部实现：mpv_player(FFI)、tui_api、app_model、probe

flutter pub get       # 安装依赖
flutter analyze       # 静态分析（CI 使用 dart analyze --no-fatal-warnings）
dart format .         # 提交前必须执行，避免 CI 产生格式化噪声提交
flutter test          # 运行测试
flutter run           # 调试运行

提交改动前建议至少执行 flutter analyze 与 dart format .，并在目标平台完成一次构建验证。

• UI 设计灵感：Apple Music, 某云音乐, ParticleMusic
• 歌词获取：lyrics_now
• 歌词渲染：coriander_player, flutter_lyric
• GitHub Actions：FlutterHub
• README 规范：standard-readme

欢迎通过 Issue 报告问题，或提交 Pull Request 改进功能。提交前请尽量：

1. 说明复现环境、平台与具体步骤。
2. 保持改动聚焦，并遵循现有 Flutter / Dart 代码风格。
3. 执行 flutter analyze 和相关测试。
4. 不提交 Cookie、账号信息、构建产物或其他敏感数据。

本项目采用 GNU Affero General Public License v3.0 许可证。

Copyright (C) 2026 NaivG and contributors.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.