cwuom /NeriPlayer

A native Android audio player that combines multi-source streaming, local control, rich lyrics, and self-hosted sync. / ✨ 一个把多源在线播放、本地管理、歌词体验和自建同步做进原生 Android 的音频播放器 🎵

★ 4,260⑂ 166👁 7⑃ 235● 394▤ 98
KotlinGPL-3.0Created 2025-08-08neri.kano.kim
下载:NeriPlayer-09526815.11171823NeriPlayer-09526815.11171823 ↓09526815.111718232026-11-17
4,260
stars
166
forks
7
watchers
235
prs
394
issues
98
releases

README

English | 中文

NeriPlayer (音理音理!)



✨ 聚合多平台音源、本地曲库、自建音乐服务器(预览版)与逐字歌词的原生 Android 音频播放器 🎵

🖥️ 在找 PC 端吗? 前往 NeriPlayer Desktop 仓库 →


  
    
  
  
    
  
  
  
    
  
  
    
  



  



本项目的名称及图标灵感来源于《星空鉄道とシロの旅》中的角色「风又音理」。



项目采用原生 Android 开发,支持 Android 9 (API 28) 及以上设备,
围绕「多源探索、在线播放、本地可控、数据自持」持续打磨。


🛠️ Active development / 持续迭代中





 [!WARNING]
 自建音乐服务器功能目前为预览版本,缺乏充分测试。

---

 [!WARNING]
 本项目仅供学习与研究使用,请勿将其用于任何非法用途。
 请只在你拥有权利、授权或第三方平台规则允许的范围内访问、播放或保存内容。
 本项目不提供媒体内容、密钥、规避付费/DRM/地区限制的方案,也不提供公共媒体代理或再分发服务。

 NeriPlayer 不提供公共云端曲库或媒体分发服务。在线音频能力依赖用户在第三方平台上的账号授权,
 会员或受限内容仍需遵循原平台规则。文档中提到的 YouTube Music 相关能力仅指账号会话、
 播放兼容和错误恢复,不代表绕过平台限制、复制受保护内容或重新分发媒体。

 本项目及维护者不接受任何形式的赞助、捐赠或商业资助。

---

 快速定位 / Start here

| 快速导航 | 说明 |
| :--- | :--- |
| 快速体验 | 下载安装 APK、获取 CI 构建或从源码编译 |
| 核心特性 & 平台现状 | 了解播放、音效、歌词、本地管理能力与各平台支持范围 |
| 连接音乐服务器 | 接入 Navidrome / OpenSubsonic 自建音乐库(预览版) |
| 一起听服务端部署 | 使用 Cloudflare Workers 自建实时同步听歌房间 |
| docs/implementation.md | 架构、模块职责、启动链路与测试护栏等实现细节 |
| CONTRIBUTING.md | 开发环境配置、提交流程与代码贡献指南 |

| 能力维度 | 核心亮点 |
| :--- | :--- |
| 多源在线与自建库 | 网易云音乐、Bilibili、YouTube Music、本地音频与 Navidrome / OpenSubsonic(预览版)共用统一播放队列 |
| 高阶歌词体验 | LRC / YRC / TTML 逐行与逐字歌词、B 站 CC 字幕、翻译音译、多源匹配,支持悬浮窗、状态栏、蓝牙/车载与系统级歌词输出 |
| 专业音频与视觉 | Media3 播放引擎、自研 DSP、10 段 EQ、AutoEQ、32-bit 输出、USB 独占;Material You 与 Clean 主题、流体背景、桌面小组件、启动器快捷方式 |
| 本地优先与自有同步 | 缓存、下载、歌单、历史、统计与设置默认保存在本地;可选将元数据同步至你自己的 GitHub 仓库(新建时默认私有)或 WebDAV 远端 |
| 可恢复运行 | 内置脱机模式、安全模式、JVM/Native 崩溃日志、ANR 记录与调试探针 |

 项目简介 / About

NeriPlayer 是一个基于 Jetpack Compose + Media3 的原生 Android 音频播放器,将 网易云音乐、Bilibili、YouTube Music、自建音乐服务器 与 本地音乐 整合进统一的播放与管理体验中。本地播放无需第三方平台账号,在线平台的账号功能按对应授权启用。

- 账号授权:需要登录的在线功能使用你在对应平台上的账号授权。
- 自建音乐服务器(预览版):可连接 Navidrome / OpenSubsonic,在“资源库 → 音乐服务器”浏览和搜索专辑、单曲、歌手,复用现有播放器、封面与歌词组件,支持本地收藏、歌单操作和原文件离线下载(连接方式见连接音乐服务器)。
- 本地优先:缓存、下载文件、歌单、历史记录、设置与授权信息默认保存在设备本地。
- 可选同步:歌单、收藏、最近播放与播放统计可同步到你自己的 GitHub 仓库(应用内新建时默认私有)或 WebDAV 远端文件。
- 去中心化与账号安全:同步数据只写入你控制的远端,不经过维护者服务器。为避免触发第三方平台的风控或异常登录限制,NeriPlayer 不会向第三方平台回写本地播放历史和统计。

 💡 概念区分:「音乐服务器」用于接入你自建的 Navidrome / OpenSubsonic 曲库;「一起听服务端」用于多设备实时同步播放状态;「GitHub / WebDAV 同步」同步本地歌单与统计等元数据(不传音频文件,也不迁移音乐服务器配置与凭据),三者相互独立。

架构、启动链路与测试护栏等实现说明见 docs/implementation.md 与 CONTRIBUTING.md。

 连接音乐服务器

 [!WARNING]
 自建音乐服务器功能目前为预览版本,缺乏充分测试。不同服务器、曲库和网络环境下的兼容性与稳定性仍需验证。服务器回写、一起听和配置迁移尚未接入。

1. 在“设置 → 第三方平台登录 → 音乐服务器”添加名称、地址、用户名和密码,连接检查成功后保存。
2. 填写服务器基础地址,例如 https://music.example.com:4533/navidrome/;可含端口及反代子路径,不填 /app/ 或 /rest/。
3. 打开“资源库 → 音乐服务器”选择配置,浏览或搜索专辑、单曲、歌手;点击歌手可查看其专辑。切换分类保留关键词,专辑内搜索仅筛选当前专辑。
4. 点击歌曲播放,或收藏、加入队列及本地歌单。优先读取服务端结构化歌词,不支持时尝试标准歌词接口;播放格式和拖动能力取决于服务器及设备。
5. 长按歌曲或多选后点击“下载到本地”,在服务器允许下载时按原文件格式保存;下载进度与重试使用现有下载管理。完成后可从本地音乐的“已下载”分类播放,断网或移除服务器配置不影响已下载文件。

| 机制维度 | 行为与限制说明 |
| :--- | :--- |
| 目录缓存与刷新 | 首次打开自动加载专辑、单曲、歌手三类完整目录并缓存,之后优先使用本地目录搜索,24 小时内复用缓存;曲库变化后可手动刷新,刷新失败保留已有完整目录。 |
| 媒体与封面加载 | 目录缓存只保存元数据,封面按需加载,音频仍按播放或手动下载获取;浏览缓存和下一首预取不等于整曲离线下载。歌手头像优先使用服务器图片,无图时使用该歌手最后一首有封面歌曲的图片。 |
| 凭据安全与修改 | 配置和密码保存在本机加密存储中。编辑仅修改名称和密码;更换地址或用户名需新建配置,原歌单条目不会自动迁移,普通同步不迁移服务器凭据。 |
| 多端封面同步 | 服务器封面以不含认证信息的真实接口地址同步(不携

Top issues

Discussions

Latest release

NeriPlayer-09526815.11171823 NeriPlayer-09526815.11171823 2026-11-17
What's Changed
 feat(player): 支持从播放页收藏到网易云歌单 by @WhiteZeek in https://github.com/cwuom/NeriPlayer/pull/647
 fix(youtube): avoid startup crash on legacy WebView by @cwuom in https://github.com/cwuom/NeriPlayer/pull/653
 fix(playback): mitigate high-rate PCM underruns by @cwuom in https://github.com/cwuom/NeriPlayer/pull/656
 fix(icon): ship a real adaptive launcher icon with a monochrome layer for themed icons by @Isilsolme in https://github.com/cwuom/NeriPlayer/pull/654
 feat(netease): 支持云盘歌曲浏览与播放 by @Isilsolme in https://github.com/cwuom/NeriPlayer/pull/655
 fix(download): stream startu

Snapshot: 2026-11-17T21:58:29Z · Data license Apache-2.0 · JSON