本项目的名称及图标灵感来源于《星空鉄道とシロの旅》中的角色「风又音理」。
项目采用原生 Android 开发，当前支持 Android 9 (API 28) 及以上设备， 围绕「多源探索、在线播放、本地可控」持续迭代。
🚧 Work in progress / 开发中
Warning
本项目仅供学习与研究使用，请勿将其用于任何非法用途。
Note
NeriPlayer 不提供公共云端曲库或媒体分发服务。 在线音频能力依赖您在第三方平台上的账号授权， 会员或受限内容仍需遵循原平台规则。
NeriPlayer 是一个基于 Jetpack Compose + Media3 的原生 Android 音频播放器。当前实现重点不是构建公共云端服务，而是在用户已具备 第三方平台账号能力的前提下，整合 网易云音乐 与 Bilibili 的 在线内容，并提供 流媒体缓存、应用内下载、本地导入、本地歌单管理、 可选 GitHub 私有仓库同步 等能力。
- 账号即能力：通过用户在第三方平台的合法授权，启用在线播放、 搜索、歌单访问等能力。
- 默认本地存储：播放缓存、下载文件、歌单、历史记录、设置与授权 信息默认保存在设备本地。
- 可选自有仓库同步：可将歌单、收藏和历史等元数据同步到用户自己 的 GitHub 私有仓库。
- 单 Activity + Compose 架构：以
MainActivity为唯一对外入口， 通过 ComposeNavHost、Mini Player 与 Now Playing 覆盖层组织界面。 - 首次使用有免责声明阶段：应用启动流程为
Loading -> Disclaimer -> Main，首次进入需阅读并同意免责声明。
- 🎧 多源探索与播放：
Explore页当前支持网易云精选歌单， 并提供 网易云 / Bilibili 搜索入口。 - 🔍 分层搜索能力：页面搜索与播放页元数据补全是两套链路。
Explore使用 网易云 / Bilibili；SearchManager用 网易云 / QQ 音乐 补全封面、歌词与曲目信息。 - 🧠 基于 Media3 的自定义播放管理层：
PlayerManager负责音源解析、播放队列、随机/循环、状态持久化、 失败重试与恢复。 - 💾 可配置流媒体缓存：播放器使用
SimpleCache + LRU做音频缓存， 默认上限为 1 GB，支持在设置中手动清理缓存。 - ⬇️ 应用内下载与本地播放：支持将在线音源下载到应用专属目录， 同步保存歌词与封面，并在应用内查看进度、管理已下载歌曲。
- 📁 本地音频导入与扫描：支持系统
VIEW / SEND / SEND_MULTIPLE的audio/*，可从外部分享/打开音频后导入；也支持扫描设备本地音频。 - ☁️ GitHub 私有仓库同步：可选同步本地歌单、收藏歌单、最近播放与
删除记录，使用
WorkManager进行延迟与周期同步。 - 🛠️ 开发者模式与调试工具：设置页连续点击版本号 7 次 后，
底栏会出现独立
Debug页，内含 Bili / Netease / Search API 探针、 普通日志与崩溃日志查看器。 - 🌈 音频反应式动态背景：在 Android 13+ 的 Now Playing 页面，
可选启用基于
RuntimeShader的音频反应式背景效果。 - ♻️ 本地备份与恢复：支持本地歌单与收藏数据的 JSON 导入/导出， 用于设备迁移或手工备份。
- 网易云音乐：登录、搜索、精选歌单/专辑访问、播放、下载、歌词补全。
- Bilibili：登录、搜索、收藏夹访问、分 P 转音频播放、下载。
- QQ 音乐：当前仅用于播放页元数据/歌词补全，未实现登录、播放与库页。
- YouTube：仓库中存在部分资源占位，当前未实现可用入口。
compileSdk = 36targetSdk = 36minSdk = 28- Java 17 / Kotlin JVM 17
- 版本名格式：
<git短哈希>.<MMddHHmm> - Release APK 文件名：
NeriPlayer-<versionName>.apk
- 对外入口只有
MainActivity，同时处理应用启动与外部音频导入。 - 启动流程包含免责声明阶段；Android 13+ 首次启动时会申请通知权限。
- 主界面是 Compose NavHost + 动态底栏：
Home / Explore / Library / Settings为主路径。 Home只有在首页卡片启用时才显示；Debug只有开发者模式开启后才显示。Now Playing不是普通路由，而是覆盖在主导航之上的全屏播放层， 底部常驻Mini Player。
- 播放核心基于 Media3 ExoPlayer，由
PlayerManager统一管理。 AudioPlayerService提供前台播放服务、媒体通知与基础传输控制。- Bilibili 音频播放通过
ConditionalHttpDataSourceFactory动态附加Referer / User-Agent / Cookie。 - 播放状态会定期持久化，用于进程重启后的队列与状态恢复。
- UI 搜索：
ExploreViewModel当前接入Netease与Bilibili。 - 元数据补全搜索：
SearchManager当前使用CloudMusicSearchApi与QQMusicSearchApi。 - 当前 UI 层搜索是按平台切换，不是混合聚合结果列表。
- QQ 音乐目前主要用于播放页的元数据/歌词补全， Library 中的 QQ 音乐入口仍处于占位/开发中状态。
- 设置与平台 Cookie 使用
DataStore持久化。 - 播放历史、歌单、收藏快照与部分映射数据使用本地文件持久化。
- 本地歌单使用 JSON 文件存储，并通过临时文件实现原子写入。
- GitHub Token 使用 Android Keystore + EncryptedSharedPreferences 本地加密保存。
- GitHub 同步使用本地生成的 UUID 作为设备标识，不依赖
ANDROID_ID。
- 下载实现基于共享
OkHttpClient，不是系统DownloadManager。 - 下载文件存放在应用专属音乐目录，并配套保存歌词与封面。
LocalAudioImportManager支持导入外部音频，并复制附近的lrc/txt歌词文件与cover/folder/front封面图。BackupManager支持本地 JSON 备份、导入与差异分析。
想深入了解实现细节？请阅读 CONTRIBUTING.md。
NeriPlayer 支持将本地元数据同步到 用户自己的 GitHub 私有仓库， 当前同步目标主要包括：
- 本地歌单
- 收藏歌单
- 最近播放记录
- 最近播放删除记录
- 🔒 本地安全存储：GitHub Token 保存在
Android Keystore + EncryptedSharedPreferences中。 - 🔄 同步调度：本地数据变更后会触发一次 延迟 5 秒 的同步；同时存在 每小时一次 的周期同步。
- ⏱️ 最终一致性：这是后台双向同步，不是实时秒级推送。
- 🌐 网络要求：同步任务依赖
WorkManager，仅在存在 validated network 时执行。 - 🧩 冲突处理：同步采用三路合并，处理歌单、收藏、历史与删除记录。
- 🧯 冲突边界：当前以内建规则自动合并常见冲突，暂无手动冲突解决界面。
- 🪶 省流模式：同步模块内置 Data Saver 模式，默认开启。
- 📦 远端格式：远端备份文件为明文 JSON 或压缩二进制格式， GitHub 私有仓库并不等于端到端加密。
- 🚫 同步边界：同步的是歌单/收藏/历史等元数据，不会上传音频缓存、 下载文件、本地文件歌单、Cookie 或播放 Token。
- 打开设置页中的 GitHub 同步入口。
- 创建 GitHub Personal Access Token（需要
repo权限）。 - 在应用内完成 Token 校验与仓库配置。
- 开启自动同步。
- 前往 GitHub Action 下载最近一次构建成功的 Artifacts 并解压。
- 或访问 NeriPlayer CI Builds。
- 克隆仓库并使用 Android Studio（最新稳定版）打开：
git clone https://github.com/cwuom/NeriPlayer.git cd NeriPlayer - 同步依赖。
- 构建调试版：
./gradlew :app:assembleDebug
- 安装 APK（需要 Android 9+ 设备）：
adb install -r app/build/outputs/apk/debug/app-debug.apk
- 首次启动时先阅读并同意免责声明；Android 13+ 设备会申请通知权限。
- 如需调试工具，在设置页连续点击 版本号 7 次，
启用开发者模式后底栏会出现独立
Debug页面。
发布版构建与签名流程请参阅 CONTRIBUTING.md。
- 视频播放
- 评论区
- 清理缓存
- 添加到播放列表
- 平板适配
- 歌词悬浮窗
- 国际化
- 第三方平台持续扩展（YouTube、酷狗音乐等）
- 网易云音乐适配 / NetEase Cloud Music
- 哔哩哔哩适配 / BiliBili
⚠️ 当前 QQ 音乐主要用于播放页元数据补全。 完整账号能力、库页数据与更稳定的授权链路仍在开发中。
- 反馈前建议先开启开发者模式（设置页点击 版本号 7 次）。
- 开发者模式开启后，应用会启用普通文件日志；崩溃日志会单独落盘。
- 前往 Issues，提供： 系统版本、机型、应用版本、复现步骤与关键日志。
- Windows 可使用以下命令过滤日志：
adb logcat | findstr NeriPlayer - Linux / macOS 可使用：
adb logcat | grep NeriPlayer
- 请合理配置代理规则；全局代理可能导致部分第三方接口返回异常数据。
- 下载功能当前不依赖系统下载服务，也不提供断点续传。
Bilibili当前主要提供搜索与音频播放链路，不是完整的视频发现流。
- NeriPlayer 不提供自己的公共云端媒体分发服务，也不接入广告 SDK、 第三方统计或崩溃分析 SDK。
- 播放缓存、下载文件、本地歌单、历史记录、设置与授权信息默认保存在 用户设备本地。
- 如用户主动开启 GitHub 同步，仅会将歌单/收藏/历史等元数据同步到 用户自己的 GitHub 私有仓库。
- 不会将音频缓存、下载文件、Cookie、播放 Token 上传给开发者。
- 应用启用了 Android 系统备份 / 设备迁移能力； 具体是否备份以及备份范围取决于系统策略。
- 第三方平台侧的访问日志与风控策略，由对应平台按照其自身隐私政策处理。
| netease-cloud-music | ✨ 网易云音乐 Golang 实现 🎵 |
| bilibili-API-collect | 哔哩哔哩 API 收集整理 |
| HyperCeiler | HyperOS enhancement module - Make HyperOS Great Again! |
- 仅维护核心功能，其他能力欢迎社区贡献。
- 仓库可能因特殊原因暂停更新。
- 欢迎提交 PR 与反馈。
- 由于项目特殊性，暂不接受任何形式的捐赠。
- 欢迎通过提交 Issue、PR 或分享使用体验来支持项目发展。
NeriPlayer 使用 GPL-3.0 开源许可证发布。
这意味着：
- ✅ 你可以自由使用、修改和分发本软件。
⚠️ 分发修改版时须继续以 GPL-3.0 协议开源。- 📚 详细条款请参阅 LICENSE。
贡献前请先阅读完整的 CONTRIBUTING.md。
