MiraMusic

MiraMusic 是一个以 Windows 10/11 为主目标平台的 Flutter 音乐播放器，当前已具备：

• Windows 桌面壳层、自定义窗口与基础主题
• 本地音乐扫描、播放、封面显示
• 播放队列、顺序/循环/随机模式
• 用户播放列表（创建、添加、删除、播放全部、随机播放）
• 在线搜索 kw/kg/tx/mg/wy
• 多脚本 LX 音源管理与远程解析播放
• 基础歌词面板、LyricsIsland 投射
• flutter_lyric 动画歌词与逐字/逐行歌词解析
• Discover 完整数据页（网易云直连）

当前技术栈

• Flutter 3 / Dart 3
• flutter_bloc
• just_audio + audio_service
• flutter_js
• Isar + Hive + YAML（设置）
• flutter_lyric

快速开始

1. 安装 Flutter 依赖

flutter pub get

2. 本地运行

flutter run -d windows

常用命令

flutter analyze
flutter test
flutter build windows --debug

目录说明

• lib/app：应用启动、依赖装配、路由
• lib/core：播放、歌词、音源、平台、存储等基础设施
• lib/features：按功能划分的页面与状态层
• lib/shared：共享模型与通用组件
• test：单元测试与 Widget 测试

Windows 存储说明

• Windows 优先使用程序可执行文件同级的 mmdata/ 目录存储应用数据。
• 如果程序目录不可写（例如安装在 Program Files），会自动回退到系统应用支持目录下的 mmdata/。
• 当前统一目录结构为：
  • mmdata/config/settings.yaml：设置
  • mmdata/data/isar：资料库、播放列表、歌词缓存、音源元数据等 Isar 数据
  • mmdata/state/hive：播放队列恢复
  • mmdata/cache/artwork：封面缓存
  • mmdata/sources：音源脚本缓存
• 首次启动会自动从旧存储位置迁移数据到新结构，但不会删除旧数据。

当前阶段说明

歌词

• 本地 .lrc 继续走基础歌词链路
• 远程歌词优先解析 lxlrc / ttml / qrc / enhanced lrc / lrc
• 动画歌词默认开启，使用 flutter_lyric 原生渲染
• 关闭动画歌词后，会自动回退到基础歌词面板

Discover

• 首版使用网易云公开接口
• 当前展示：
  • 官方榜单
  • 精品歌单
  • 热歌榜试听
  • 新歌速递
• 榜单/歌单详情页支持：
  • 仅凭路由 id 直开
  • 播放全部
  • 随机播放
  • 完整曲目列表
• 首页各区块独立加载与错误恢复，单个接口失败不会拖垮整个 Discover

播放队列

• 本地资料库、播放列表详情、Discover 热门曲目点击播放时，会装入当前上下文队列
• 搜索结果点击播放时，默认只创建单曲队列
• 支持：
  • 顺序播放
  • 列表循环
  • 单曲循环
  • 随机播放
• 支持：
  • 下一首播放
  • 加入播放队列
  • 队列拖拽排序
  • 退出应用后恢复队列与播放模式
• 当前恢复行为仅恢复队列与模式，不自动播放，也不恢复播放进度

播放列表

• 支持创建、重命名、删除播放列表
• 支持从本地资料库、搜索结果、Discover、播放列表详情将曲目加入播放列表
• 播放列表详情页支持：
  • 播放全部
  • 随机播放
  • 从列表移除曲目

xm

• xm 在当前阶段未开放，不出现在搜索筛选项中

已知问题

• just_audio_windows 仍可能输出原生线程相关告警
• 目前未对 just_audio_windows 做本地 fork；该问题暂按上游限制处理
• 如果后续确认上游发布了修复版本，可优先考虑升级依赖而不是在仓库内维护插件分叉