纯净音乐 PureMusic

一款干净整洁、无广告、无任何第三方版权代码的安卓本地音频播放器。原创实现（Kotlin），专为安卓 14 优化，最低支持安卓 8.0。当前版本 v1.2.1。

📄 文档导航：《需求文档》（需求与验收标准）｜《技术架构设计文档》（选型/架构/踩坑清单/验收清单）｜《CHANGELOG.md》（版本历史）

📦 产物：releases/ 目录保存版本化安装包；最新版同时放在仓库根目录。GitHub 上建议使用 Releases 页发布 APK。

功能清单

需求	实现
干净无广告	无 SDK、无广告、无统计，不申请多余权限
按文件夹增加音频	「文件夹」页 → 右上角 ⊕ 添加扫描目录，自动递归扫描其下音频
按文件夹屏蔽音频	「文件夹」页 → 每行开关即屏蔽/包含，屏蔽后其子目录歌曲一并隐藏
按歌手/歌曲/专辑排序	主界面右上角菜单「排序方式」，中文按拼音排序，选择被记住
随机/顺序/单曲循环	播放页左下按钮循环切换，状态持久保存
跟随系统暗色模式	Material 3 DayNight 主题，系统切换亮/暗色时自动跟随
原生支持 MP3 及无损	调用系统解码器：MP3 / FLAC / WAV / M4A(ALAC) / AAC / OGG / OPUS
最小化后台播放	前台服务 + 通知栏控制（上一首/播放暂停/下一首），耳机拔出自动暂停
在线歌词（手动）	播放详情页点击歌词区域 → 自动搜索下载（LRCLIB，兜底网易云）
本地歌词自动加载	启动时扫描媒体目录中的 .lrc，播放时按文件名模糊匹配自动加载
歌词同步显示	逐行高亮 + 自动居中滚动，同步歌词优先

打包

从源码构建（克隆本仓库后）

1. 准备环境：JDK 17、Android SDK（platforms;android-34 + build-tools;34.0.0）、Gradle 8.5（或直接用 Android Studio 打开 PureMusic/）。
2. 在 PureMusic/ 下创建 local.properties（可复制 local.properties.example 修改），写入你的 SDK 路径：

   sdk.dir=D\:\\你的SDK路径
   

3. 构建：

   cd PureMusic
   gradle assembleRelease    # 产物 app/build/outputs/apk/release/app-release.apk

4. 依赖仓库已配置阿里云镜像（settings.gradle.kts），国内无需代理。

本机环境参考（开发机）

• JDK 17：D:\AndroidDev\JDK\jdk-17
• Android SDK：D:\AndroidDev\SDK（platforms android-34/35、build-tools 34.0.0、platform-tools）
• Gradle 8.5：D:\AndroidDev\Gradle\gradle-8.5

签名说明（敏感文件不出库）

发布签名相关文件全部本地私有，不进入 git 仓库：

文件	位置	作用
签名密钥库	PureMusic/puremusic.keystore	构建 release 时使用（已 gitignore）
口令配置	PureMusic/signing.properties	密钥库路径与口令（已 gitignore）
离线备份	_local_private/（密钥+口令+旧历史）	防误删，恢复方法见其中《说明.txt》

• 作者本机已配置以上文件，gradle assembleRelease 直接出原签名包（可覆盖安装）。
• 克隆者：仓库中无密钥，release 构建会自动回退使用 debug 签名（APK 可安装试用，但与作者发布的包签名不同、不能覆盖安装）。需要自有签名时，复制 signing.properties.example 为 signing.properties 并填入你自己的密钥（keytool -genkeypair 生成）。
• ⚠️ 密钥库与口令文件请勿提交；一旦泄露应更换密钥并升版发布。

安装与首次使用

1. 将 APK 传到手机安装（首次会提示允许安装未知来源应用）。
2. 首次启动会显示红色提示条：点击「去授权」→ 允许「所有文件访问权限」。

   需要此权限的原因：歌词 .lrc 不是媒体文件，安卓 11+ 只有全文件权限才能读取/保存它；同时也用于按文件夹自由扫描音乐。

3. 默认扫描目录为 /storage/emulated/0/Music，如音乐放在别处，进入「文件夹」页点击 ⊕ 添加（可选整个内部存储）。
4. 建议允许通知权限（安卓 13+ 会弹窗），用于通知栏播放控制。

歌词说明

• 自动加载：启动时扫描扫描目录下所有 .lrc 文件建立索引；播放歌曲时按文件名模糊匹配（忽略大小写、空格、括号内容、曲目编号前缀，二元组相似度 ≥ 0.55），优先同目录同名。
• 手动下载：播放详情页点击封面切换到歌词视图；歌词区点击即自动搜索下载——若存在时长匹配（±3 秒）的同步歌词会自动应用，否则弹出候选列表供选择。
• 时间轴调整：歌词视图右上角「时间轴」按钮 → 以 0.5 秒为步长整体「提前 / 延后 / 归零」，实时生效（贴底弹窗不遮挡歌词，实时显示当前偏移与高亮行），按歌曲分别记忆；调整后按钮会显示当前偏移量（如 时间轴 -12.0s）。
• 保存位置：下载的歌词保存为 <歌曲所在目录>/<同名>.lrc；目录不可写时保存到 Android/data/com.gzm.puremusic/files/Lyrics/。
• 在线来源：LRCLIB（lrclib.net，开放免费）→ 失败时兜底网易云接口。
• 重新匹配：歌词区域长按可重新匹配本地歌词文件。

行为说明（已知设计）

• 「顺序播放」播到列表末尾即停止；「随机播放」无限循环；「单曲循环」重复当前曲目。
• APE / TTA / WavPack 等安卓系统不原生解码的格式不在支持范围（本机播放器依赖系统解码器）。
• 应用从最近任务划掉即停止播放并清空通知（stopWithTask）；仅退到桌面/切换应用时后台继续播放。
• 上次播放队列会在重启后恢复（不自动播放）。
• 全部代码为本项目原创，无第三方版权/许可证约束，可任意修改分发。
• 息屏/后台停止播放：请通过主界面提示条或菜单「电池优化设置」允许忽略电池优化（ColorOS/OnePlus 等深度管控机型必需）。
• 版本显示：主界面标题下方 v<版本号>，菜单「关于」查看详情。

仓库结构

安卓音频播放器/                  ← GitHub 仓库根目录
├─ README.md                    ← 本文件
├─ CHANGELOG.md                 ← 版本历史
├─ docs/
│  ├─ 需求文档.md                ← 需求与验收标准
│  └─ 技术架构设计文档.md        ← 选型/架构/21条踩坑清单/验收清单
├─ releases/                    ← 版本化 APK 归档
│  ├─ 纯净音乐-1.0.1-release.apk
│  ├─ 纯净音乐-1.1.0-release.apk
│  ├─ 纯净音乐-1.2.0-release.apk
│  └─ 纯净音乐-1.2.1-release.apk
├─ 纯净音乐-1.2.1-release.apk   ← 最新安装包（根目录直达）
├─ .gitignore / .gitattributes
├─ _local_private/              ← 敏感文件本地备份（gitignore 排除，不上传）
└─ PureMusic/                   ← Android 工程（Gradle 项目根）
   ├─ settings.gradle.kts / build.gradle.kts / gradle.properties
   ├─ local.properties.example  ← 本机 SDK 配置模板（local.properties 不入库）
   ├─ signing.properties.example← 签名口令模板（signing.properties 不入库）
   └─ app/src/main/…            ← 全部源码与资源

工程结构

PureMusic/
├─ app/src/main/java/com/gzm/puremusic/
│  ├─ App.kt                  # 应用入口 + 全文件权限检测
│  ├─ model/Models.kt         # Song/PlayMode/SortMode/歌词行 等模型与排序器
│  ├─ store/Prefs.kt          # 偏好（扫描目录/屏蔽/排序/播放模式/上次队列）
│  ├─ store/MusicScanner.kt   # 递归扫描音频与 .lrc，读取标签
│  ├─ store/MusicLibrary.kt   # 媒体库（包含/屏蔽过滤 + 排序 + 监听）
│  ├─ lyrics/LrcParser.kt     # LRC 解析（多时间标签/offset）
│  ├─ lyrics/LyricsRepo.kt    # 本地歌词模糊匹配与保存
│  ├─ lyrics/OnlineLyrics.kt  # LRCLIB + 网易云 在线歌词
│  ├─ playback/PlaybackService.kt  # 前台服务/MediaSession/通知/三种播放模式
│  ├─ ui/MainActivity.kt      # 主界面（歌曲/文件夹页签、排序菜单、迷你条）
│  ├─ ui/PlayerActivity.kt    # 播放详情页（封面/歌词同步/点击下载歌词）
│  ├─ ui/adapters.kt          # 列表适配器
│  └─ ui/FolderPickerDialog.kt# 目录选择对话框
├─ app/src/main/res/…         # Material 3 DayNight 主题、布局、矢量图标
├─ app/build.gradle.kts       # AGP 8.2.2 / Kotlin 1.9.22 / targetSdk 34
├─ signing.properties.example # 签名口令模板（signing.properties 本机私有，不入库）
└─ puremusic.keystore         # 签名密钥库（本机私有，不入库；备份见 _local_private/）