cwuom/NeriPlayer

English | 中文

NeriPlayer (音理音理!)

[!WARNING]

本项目仅供学习与研究使用，请勿将其用于任何非法用途。

请只在你拥有权利、授权或第三方平台规则允许的范围内访问、播放或保存内容。

本项目不提供媒体内容、密钥、规避付费/DRM/地区限制的方案，也不提供公共媒体代理或再分发服务。

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

---

[!NOTE]

NeriPlayer 不提供公共云端曲库或媒体分发服务。

在线音频能力依赖用户在第三方平台上的账号授权，

会员或受限内容仍需遵循原平台规则。

文档中提到的 YouTube Music 相关能力仅指账号会话、播放兼容和错误恢复，

不代表绕过平台限制、复制受保护内容或重新分发媒体。

---

快速定位 / Start here

如果你只是想体验应用，请看 快速体验。 如果你想了解项目能力，请看 项目亮点 和 核心特性。 如果你准备贡献代码，请直接阅读 CONTRIBUTING.md。 如果你要自建一起听服务端，请看 一起听服务端部署。

NeriPlayer
├── 多源在线播放：网易云 / Bilibili / YouTube Music
├── 本地优先数据：缓存、下载、歌单、历史、统计、设置
├── 可选自有同步：GitHub / WebDAV 元数据同步
├── 丰富播放体验：Media3、歌词、音效、流体背景、桌面小组件、启动器快捷方式、悬浮/状态栏歌词
└── 可恢复运行：安全模式、崩溃日志、ANR 记录、调试探针

项目简介 / About

NeriPlayer 是一个基于 Jetpack Compose + Media3 的原生 Android 音频播放器。它不构建公共云端服务，而是在用户具备第三方平台账号能力的前提下， 整合 网易云音乐、Bilibili 与 YouTube Music 的在线内容， 并提供本地播放、下载、缓存、歌单管理和多种同步/备份能力。

当前定位：

• 账号即能力：通过第三方平台授权启用搜索、播放、歌单和收藏夹访问。
• 本地优先：播放缓存、下载文件、歌单、历史记录、设置与授权信息默认保存在设备本地。
• 可选同步：可将歌单、收藏、最近播放、歌曲播放统计、歌单打开统计和

本地歌单播放统计同步到用户自己的 GitHub 仓库（应用内新建时默认使用私有仓库）或 WebDAV 远端文件。

• 尊重隐私与账号安全：同步策略刻意保持去中心化，

数据写入用户自己控制的 GitHub/WebDAV 远端，而不是上传到项目维护者的中心化服务。 应用并非没有能力把播放历史回写到第三方音乐平台；但中心化音乐平台的客户端 通常存在风控与行为采样机制，直接上报历史播放数据可能触发异常登录、异常播放 或账号冻结等风险。出于保护账号安全的考虑，NeriPlayer 暂不向这些平台上传 本地播放历史和播放统计。

• Compose 主界面：MainActivity 承载主导航与播放界面，

UI 由 Compose NavHost、动态底栏、Mini Player 与 Now Playing 覆盖层组织。

• 启动与恢复链路：正常启动流程为

Loading -> Disclaimer -> Onboarding -> Main； 如果上次启动发生崩溃或系统 ANR，会先进入 Safe Mode。

• 测试护栏：下载存储、同步合并、YouTube 播放兼容、一起听、歌词解析、

播放策略、配置备份与安全模式等关键链路都有对应单元测试或设备测试。

---

项目亮点 / Why it stands out

• 本地优先，也认真做脱机体验：

NetworkStatusMonitor 基于系统默认网络承载自动识别脱机状态， offlineCachedImageRequest 会在脱机时阻断远程图片请求并优先使用缓存； 首页、探索、播放页、歌词页、歌单和下载列表都会接收 offlineMode， 网络断开时仍能围绕本地文件、已下载音频、播放缓存、缓存封面和本地歌单继续使用。

• 多源播放不是简单入口堆叠：

PlayerManager 负责音源解析、队列和失败恢复；网易云不可播、无可用播放结果或 只返回试听片段时，会先尝试音质降级；启用 Bilibili 兜底后，再由 PlayerManagerNeteaseAutoSourceSwitch 按歌名、歌手和时长评分自动匹配 Bilibili 音源兜底；播放异常时还会刷新当前链接，连续失败再跳过或停止。

• YouTube 播放兼容有多级回退：

登录态会保留有效身份 Cookie，并与匿名 visitor 分别维护 bootstrap 和 PoToken 会话；Cookie 轮换、会话参数、player.js 和挑战结果会优先复用缓存，失效的 player.js 或被平台拒绝的播放候选会进入 EJS/HLS 回退，避免在同一候选上反复重试。

• GLSL/AGSL 高性能流体背景：

播放页动态背景由 BgEffectPainter 加载 assets/shaders/hyper_background_effect.glsl 并通过 RuntimeShader 逐帧渲染； shader 内部基于封面取色、动态色块和轻量颗粒噪声生成流体背景， 并接入 uMusicLevel / uBeat 做音频响应，不是简单把封面做高斯模糊。

• 仿 Apple Music 的深度歌词体验：

SyncedLyricsView 与 AdvancedLyricsView 支持逐行、逐词/逐字 LRC（含行尾 时间和方括号逐字时间戳）以及 YRC/TTML 歌词的高亮、翻译歌词、 音译显示、歌词偏移、点击跳转、长按分享、景深模糊、边缘渐隐和全屏歌词； 歌词页只显示当前歌曲可用的译/音选项，切歌后待歌词判定完成再渐入； 点击可在翻译、音译和关闭之间循环； LyricShareSheet 可选择歌词行，复制文本、分享歌曲或生成 1080px 歌词卡片； 歌词页遇到含假名的日语原文时，会为翻译行额外留出间距，避免日文字形和译文挤在一起； 悬浮歌词、状态栏歌词、SuperLyric、Lyricon、蓝牙歌词和歌词编辑 也复用同一条播放数据链路。 B 站来源的歌曲可以使用视频自带的 CC 字幕作为歌词：播放页的 CC 字幕面板 可以关闭字幕歌词、选择具体字幕轨道，并按需回退到自动生成的字幕； 默认偏移量里为这一来源保留了独立偏移。

• 完整的本地歌曲管理链路：

LocalAudioImportManager 支持外部分享/打开导入、授权文件夹扫描、 设备媒体库扫描和常见音频格式识别，并会处理附近的 lrc/txt 歌词与 cover/folder/front 封面；大批量扫描会先给出快速预览，再在后台补全 更完整的歌名、歌手、专辑和封面信息；LocalPlaylistRepository 负责本地系统歌单、普通歌单、收藏、排序、去重、备份和同步触发。

• 批量词图管理（词图管理）：

本地歌单顶栏或多选菜单可一键为本地歌曲匹配并嵌入歌词与封面，分析在后台进行、不影响播放； 搜索与写入默认各 10 首并行（每首歌的多个歌词来源也同时请求），可在开始前分别调整为 1~16。 匹配会核对 LRC 最后时间戳与歌曲时长、区分现场版与录音室版、参考 LRC 的 ar/al/ti 标签； 封面优先读取同目录 cover/folder/front/album 图片，其次使用与歌词同一曲目的在线封面， 可压缩为 500/1000 px JPEG，写入前预估空间增量并支持逐首核对、切换候选与失败重试。 标准歌词字段会降级为逐行 LRC 以兼容车机和蓝牙设备，完整逐字歌词保留在 NeriPlayer 私有字段。 分区存储下读取文件夹图片需要授权一次文件夹，修改其他应用创建的媒体文件会集中申请一次系统授权。

• 媒体库已经有“分类浏览”的骨架：

Library 不只是歌单列表，本地内容可在歌单/歌手之间切换， LocalArtistSummary 会按展示艺术家自动聚合歌曲、拆分常见合作歌手写法、 生成稳定身份和封面； 网易云歌曲还能进入艺术家详情页，查看热门歌曲和专辑；网易云歌手、B 站 UP 主和 YouTube 创作者都可关注到收藏页，按网易云 / B 站 / YouTube 分类浏览。 网易云和 YouTube Music 分类支持登录后手动拉取账号关注的歌手，保留已有本地关注。

• 大屏和日常操作都在补手感：

平板播放页、歌词页、设置页和艺术家页，以及手机横屏播放页会使用更稳定的宽度与底部操作布局； Clean 和 Material You 播放页在手机上共用容器形变动效，平板的两种主题均使用经典的纵向滑动和淡入淡出转场； 平板横屏固定使用完整歌词分栏，横滑不再切换歌词样式，返回一次即可关闭播放页；竖屏保留独立歌词页； Mini Player 支持横向滑动切到上一首/下一首，常用播放控制不用每次展开全屏； 桌面小组件提供 4x1 横条、2x2 迷你播放器和 4x2 播放卡片；使用封面取色的 Material You 圆角卡片，支持明暗主题、横竖屏和尺寸自适应。宽卡片显示歌曲、 封面、进度、收藏和桌面歌词入口；窄尺寸也保留上一首、播放与下一首，复用播放服务的控制链路； 启动器快捷方式可直接继续播放、打开探索、打开媒体库或随机播放我喜欢的音乐； 平板主标签使用可打断的居中缩放和淡入淡出，手机保留按标签顺序横向换页；转场中会同时保留出场与入场页面， 避免玻璃背景、滚动位置和页面状态在快速切换时闪断； 播放页长按封面可打开沉浸式大图预览，支持双指缩放、拖动与下载封面。

• 听感也能细调：

自研 native DSP 位于 Media3 音频输出前，不依赖系统 Equalizer； 「设置 → 音效与倍速」提供 29 种内置音效、10 段均衡器、参数均衡、AutoEQ 导入、 低音/高音、虚拟低音、人声、空间、混响、压缩、扬声器优化和防爆音限幅， 也支持按输出设备分别记忆音效、按歌曲实时响度均衡、 声道平衡、32-bit 高解析普通输出、淡入淡出、交叉淡入淡出、 蓝牙断连暂停、USB 独占播放和音频焦点策略。 USB 独占会由 native 驱动接管兼容 USB 音频设备，避免系统音和其他应用共用 USB 通道； 当前面向 UAC1.0 和兼容 UAC2.0 Type I PCM 设备，设备选择、 采样率/位深/缓冲策略、32-bit PCM、PCM float 软件转换、后台运行提醒、 UAC2 时钟拓扑与显式反馈端点解析、启动看门狗、前后台健康审计、 动态传输扩缩容和卡死自动恢复也都补齐了；前后台切换会按网络或本地来源选择 唤醒策略，USB 独占播放可在回到前台后恢复；长调度间隙后会重新捕获反馈时钟， 避免继续使用陈旧的速率估计。比特完美音量模式保持软件增益为 0 dB，交给 DAC 硬件控制音量。

• 下载链路已从“能下”进化到“能恢复”：

下载不走系统 DownloadManager，而是用共享 OkHttpClient、 可调并发、工作文件和 sidecar 元数据管理完整落盘流程； 直接 HTTP 传输、平台需要显式 Range 的传输和 HLS 都有对应续传策略，网络策略暂停后可继续， 启动时会恢复未完成队列，已落盘的缓存命中会直接结算， 手动取消则会清理半成品，语义边界很清楚；下载完成后即使标签写入失败，已落盘 音频仍会保留。

• 存储占用能看清，也能有边界地清理：

StorageUsageAnalyzer 会把音频缓存、图片缓存、下载暂存、分享暂存、 平台歌单缓存、下载内容、日志、崩溃报告和核心应用数据分组统计； 清缓存支持只清可再生成的缓存，不会把用户主动下载的歌曲当作缓存删掉。

• 去中心化同步与播放统计：

NeriPlayer 不提供公共云端曲库或开发者托管账号数据； GitHub/WebDAV 同步只在用户自己的远端保存歌单、收藏、最近播放和 播放统计等元数据。PlaybackStatsRepository 按歌曲稳定身份记录播放次数、 收听时长、最近播放和每日桶，并参与同步合并；播放和流量统计采用延迟批量写入， 在关键生命周期阶段 flush；播放累计与日桶不再按数量淘汰，流量统计保留自己的窗口策略。 远端同步快照读取时会兼容旧字段和异常缺字段数据，过滤缺少可解析歌曲身份的记录。

• 流量管理不是事后看数字：

TrafficStatsRepository 会区分播放流量、下载流量、Wi‑Fi、移动网络、 漫游和缓存命中；批量或单曲下载在高风险网络下还能主动弹出提示， 避免把“省流量”只做成设置页里的摆设；统计写入同样使用批量累积和生命周期 flush。

• 高个性化，不只是换主题色：

设置 schema 由 AutoSettingsSchema 管理，覆盖动态取色、种子色、 主题风格、自动/浅色/深色模式、UI 缩放、自定义背景、歌词字号、 歌词模糊、播放页流体背景、两级高级模糊、连贯反馈、首页卡片开关、默认启动页、触感反馈， 以及歌曲自定义名称、歌手和封面等细粒度选项。 应用内 UI 缩放默认 1.0x，手机范围为 0.6-1.2x，车载模式为 0.6-1.5x，步进为 0.05x。 平板上限按设备最小宽度动态计算，放大后仍保留至少 600dp，并向下取到 0.05x 档位，例如最小宽度 800dp 的平板最高为 1.3x。 升级后或首次安装完成引导后，会询问一次是否启用预览版主题；启用后立即生效， 也可随时在主题设置中切换，已启用或已作出选择后不再重复询问。 「界面风格」可选择默认的 Material You 或预览版「简洁（Clean）」；后者提供独立的明暗配色、 连续曲率圆角和控件样式，并可开启底栏与迷你播放器的液态玻璃效果。 OnePlus 的高密度屏幕（系统 densityDpi >= 500）会自动叠加 0.95x UI 修正， 普通密度机型不触发修正，用户手动设置值仍会作为额外乘数参与计算。 “进阶高级模糊”和“连贯反馈”默认关闭；关闭连贯反馈时，歌单等详情页使用抽屉式展开； “预测性返回预览”默认关闭，所有系统均可手动开启； 进阶高级模糊仅在 Android 13+ 且父级高级模糊开启时可用； 它会增强屏幕级顶部 Tab、底部 Tab 和设置结构卡片的实时玻璃材质， 并提供 12-64 dp 的模糊度调节，不改变文字、图标、布局与点击区域。 模糊质量可独立选择“超低、低、默认、高”：超低和低保持与默认相同的模糊范围， 通过局部区域渲染、动态下采样和 RenderNode 硬件缓存降低渲染开销。 检测到天玑 SoC 且尚未保存过选择时默认使用“超低”；前后台切换或更改质量时会 重建局部缓存，避免恢复后出现异常背景。“高”需要先开启进阶高级模糊。

• ANR、崩溃和安全模式都纳入诊断闭环：

AnrWatchdog 会读取 Android ApplicationExitInfo.REASON_ANR 并保存系统 ANR trace；ExceptionHandler 与 NativeCrashHandler 分别记录 JVM 和 Native 崩溃。上次启动异常时，SafeModeManager 可跳过完整应用初始化， 直接进入安全模式预览、复制或导出日志。

• 一起听不是“同步一个进度条”这么简单：

客户端和 Cloudflare Worker 共同维护房间、角色、队列、播放状态、 循环/随机模式、房主离线恢复、成员控制请求、会话播放候选共享、版本门控更新和自定义服务端地址； 客户端还会估算服务端时钟偏移、按漂移阈值校正进度，并在会话候选异步返回后 重载权威音源，避免本地待启动状态覆盖房间的暂停或播放指令； 邀请链接必须包含首次加入所需的房间密钥，成员密钥不会出现在公开房间状态中； 本地歌曲不能创建或替换一起听房间当前曲目；开启会话候选共享后，房主当前歌曲的候选播放地址会由 Durable Object 临时缓存，听众可在成员会话内取得当前候选而无需等待房主再次响应；当前曲目最多保留三条 经校验的候选，听众始终先按本机音质策略解析，失败后才在会话内回退，候选不会写入歌曲 或离线缓存；同一成员凭据重连不会触发成员变更暂停，房主和听众都会定期保活连接； 服务端使用 Durable Objects 持久化房间状态，并通过 WebSocket 做实时同步。

---

快速体验 / Getting Started

a. 下载 Release 版本（推荐）

1. 前往 GitHub Releases 2. 如何选择版本？

• 大部分手机请选择 arm64-v8a
• 老旧 32 位设备请选择 armeabi-v7a
• x86 / x86_64 主要用于模拟器、英特尔设备或 Chromebook

[!IMPORTANT]

Release 渠道不是严格意义上的稳定通道。版本通常在完成一批功能后手动发布，

仍可能包含未充分暴露的问题。

b. 下载 CI 版本

1. 前往 GitHub Actions 下载最近一次成功构建的 Artifacts 并解压。 2. 或访问 NeriPlayer CI Builds。

master 分支 CI 默认上传 arm64-v8a APK；手动 Release 流程会构建多 ABI APK。

c. 本地构建

1. 克隆仓库并初始化子模块：

   git clone --recursive https://github.com/cwuom/NeriPlayer.git
   cd NeriPlayer
   

2. 安装 JDK 17，并使用 Android Studio 最新稳定版打开项目、同步依赖； 建议将 Gradle JDK 设为 17；运行 :playback:runtime JVM 测试或全量模块门禁时，另需可被 Gradle 发现的 JDK 21，生产字节码仍以 17 为目标。 3. 构建调试版：

   ./gradlew :app:assembleDebug
   

4. 安装 APK：

   adb install -r app/build/outputs/apk/debug/app-debug.apk
   

5. 首次启动时先阅读免责声明并完成启动引导；引导页会说明通知与本地音乐权限， 仅在你主动点按后申请，跳过不影响继续使用。 6. 如需调试工具，在设置页连续点击 版本号 7 次启用开发者模式， 底栏会出现独立 Debug 页面。

DEBUG 构建仅用于测试，性能和体积不代表发布版。

DEBUG 包使用 moe.ouom.neriplayer.debug 和橙色启动图标，应用名称带有 DEBUG 标记，启用系统主题图标时也能区分；可与 Release 共存，应用数据各自独立。

DEBUG 分享的一起听邀请使用 neriplayer-debug://，避免打开正式版；仍可在应用内粘贴普通邀请链接加入。

完成启动引导后会提示 DEBUG 构建风险；确认后不再提醒，更新保留该状态，清除数据或重新安装后会再次提示。

在 Android Studio 中运行时，选择 app 运行配置，并确认 Build Variants 中 :app 使用 debug。更新包名配置或切换到包含该变更的分支后，先执行 Sync Project with Gradle Files；仅重新构建 APK 不会刷新 IDE 缓存的启动包名， 可能导致安装 DEBUG 包后仍启动已安装的正式版。运行窗口中的启动组件应为 moe.ouom.neriplayer.debug/moe.ouom.neriplayer.activity.MainActivity。

发布版构建与签名流程请参阅 CONTRIBUTING.md。

---

核心特性 / Key Features

• 🎧 多源探索与播放：

支持网易云音乐、Bilibili、YouTube Music 与本地音频播放。

• 🏠 首页推荐与继续播放：

首页支持最近常用歌单、网易云动态推荐源、雷达歌单与推荐卡片； 默认同时展示榜单、新歌、日推、私人 FM、精品歌单等可用来源，刷新会更新全部分区。 Bilibili 音乐分区提供热门榜、原创榜和热门视频，支持进入完整列表；榜单优先播放官方 MV， 缺少有效 MV 时使用榜单关联投稿，无有效音源的条目会明确标记。 国际化模式下优先展示 YouTube Music 首页歌单与歌曲货架。

• 🗂️ 媒体库分类浏览：

Library 提供本地、收藏、网易云、YouTube Music、Bilibili 等入口； 可在“设置 > 通用”中完全禁用 YouTube，关闭后不会展示相关入口或执行后台预热； 本地页支持歌单/歌手切换、搜索、歌手排序，收藏页支持歌单/歌手/热点切换， 网易云页支持歌单/专辑切换，Bilibili 页区分创建收藏夹、订阅收藏夹和合集。

• 🔍 分层搜索能力：

Explore 使用网易云 / Bilibili / YouTube Music 按平台独立搜索； 网易云支持歌曲、歌单和歌手分类，网易云与 Bilibili 搜索结果可在列表触底后 自动加载下一页；“链接识别”可直接粘贴链接或含标题、短链接的整段分享文案， 识别网易云歌曲/歌单/歌手、Bilibili 视频/收藏夹/合集/UP 主及 YouTube 视频/歌单/频道。项目已有详情页的类型可直接打开，暂无详情页的类型会明确提示； Bilibili 链接会尽量保留 p / cid 分 P 和 season_id 合集上下文， 分享合集时可直接解析到对应合集列表。 搜索框下方会显示本地搜索历史，默认记录防抖搜索过的关键词； 可在“设置 > 通用”关闭探索页搜索历史，关闭后不显示也不再记录新关键词， 已有记录不会被自动删除，重新开启后仍可显示； 播放页元数据补全使用网易云 / QQ 音乐，并接入 LRCLIB 外部歌词来源； 歌词编辑器可选择酷狗、网易云、QQ 音乐、AMLL TTML、LRCLIB 和 YouTube Music 后手动匹配歌词，逐字歌词优先但不隐藏普通歌词，并会自动清理 标题、制作信息等非歌词行。

• 🧠 Media3 播放核心：

PlayerManager 管理音源解析、队列、随机/循环、状态恢复、失败重试、 播放链接刷新、YouTube 预取与平台特殊请求策略。 随机播放会先生成真实乱序队列，再按该队列顺序播放、持久化和展示。

• YouTube 登录态会保留有效 Cookie，并支持 Cookie 轮换、匿名播放会话、bootstrap/

player.js/PoToken 缓存和优先级预取；签名或播放候选被拒时可回退 EJS/HLS。

• ⏩ 可选 BilibiliSponsorBlock 自动跳过：默认关闭。开启后仅向公开接口发送当前

BV 号的 SHA-256 前缀，按分 P 和时长筛选 intro、outro、sponsor、 music_offtopic、filler、padding 片段并在本地跳转；不会上传账号、播放历史或新片段。一起听期间保持关闭， 避免房间播放状态漂移。

• ⏭️ Bilibili 自定义跳过区间：可从正在播放的更多选项或 Bilibili 收藏夹/合集条目

管理同一视频分 P 的多个区间；规则按 BVID + CID 本地持久化，并通过 GitHub/WebDAV 同步。播放页可使用设为开始/结束、前后 5 秒及播放/暂停辅助定位；一起听期间不应用本地自动跳过，避免房间状态漂移。

• 🔁 网易云播放兜底：

网易云歌曲无权限、无可用播放结果或仅返回试听片段时，会先尝试降低音质； Bilibili 和本地音频兜底默认关闭，只有用户主动开启后，才会按歌曲名、歌手和时长 匹配 Bilibili 候选或按稳定元数据匹配可读的本地音频。

• 🧯 播放失败兜底：

播放异常时优先刷新当前播放链接；Bilibili 播放请求支持 DASH 音频重试和 html5/mp4 渐进流回退，连续失败时自动跳过或停止避免卡死。

• 🎚️ 播放音效：

「设置 → 音效与倍速」集中管理音效、倍速和音调。DSP 以 float 精度处理普通输出与 32-bit 高解析输出，提供风格/音色/场景/设备四类内置音效、可拖动的 10 段均衡器、 参数均衡与 AutoEQ 导入、自定义音效分享导入、扬声器优化，以及节能/均衡/高质量三档处理模式； 音效关闭或所有调节均为中性时旁路 DSP 处理。USB 独占默认旁路 DSP， 可在高级选项中手动允许 USB 输出也应用音效。 播放设置可开启按歌曲实时分析的响度均衡、声道平衡和 32-bit 高解析普通输出； 高解析普通输出会旁路响度均衡、声道平衡、音频可视化和应用内倍速等处理。

• 🎛️ 细粒度播放行为：

支持保留上次播放进度、恢复播放模式、淡入淡出、切歌交叉淡入淡出、 蓝牙断连暂停、USB 独占播放、混音播放和预抢占音频焦点。 长音频进度记忆默认开启，仅对时长不少于 15 分钟的内容保存位置；低于 5 秒的 位置不会写入，距离结尾 30 秒以内会视为已完成并清零，显式指定的播放位置优先于 记忆位置。该位置以 resumePositionMs 参与本地与可选同步，不代表第三方平台播放历史。

• 🔌 USB 独占播放：

支持 UAC1.0 和兼容 UAC2.0 Type I PCM 的 USB DAC 设备，支持设备选择、 采样率/位深/缓冲策略、兼容性开关、32-bit PCM、 PCM float 到设备格式的软件转换和后台运行提醒； 可选开启「悬浮窗保活」，在获得悬浮窗权限后于 USB 独占播放期间显示一个不可见、 不拦截触摸的 1 像素窗口，降低部分系统在后台冻结播放进程导致断联的概率； 插入 USB 设备时是否响应系统 USB_DEVICE_ATTACHED 事件可单独关闭， 用于避免不想接管 DAC 时反复唤起应用； 跟随歌曲采样率时会先按 USB 描述符尝试源采样率，精确格式不可用且兼容策略开启时， 再尝试设备上报的兼容采样率，此时用 Kaiser 窗 sinc 多相重采样（阻带约 -90 dB）， 不再用线性插值；只有多声道模式的声卡会把立体声送到前两个声道、其余补零； UAC2 终端经时钟选择器或倍频器连接时钟源时（如 XMOS 方案），会按选择器当前输入 走到最终时钟源再设置采样率； 对需要异步显式反馈的 UAC1/UAC2 设备，会解析时钟链和反馈端点（UAC1 同步端点按 bSynchAddress 匹配），根据设备反馈调度音频包，并在长调度间隙后重新进入反馈时钟捕获； 打开时会把播放路径上的 DAC 硬件静音解除、硬件音量设为 0 dB，关闭时写回原值， 避免 DAC 沿用系统留下的衰减；设置采样率后若回读暂时不一致，会等待时钟锁定再确认； 播放启动卡住、Native 传输背压卡住或前后台切换异常时，会通过原地重配置、 协调式 AudioSink 重建、动态传输扩缩容和软恢复尽量拉回， 必要时回退到系统播放避免整条链路卡死；播放器会按网络或本地来源选择唤醒策略， 前后台切换后可恢复 USB 独占；音量键、锁屏和系统音量面板都调节普通媒体音量， 原生输出即时跟随。开启比特完美输出时按音源采样率和位深申请 DAC 格式， 软件增益固定为 0 dB，不做音效、淡入淡出和重采样，DAC 带硬件音量时音量键改为调节 DAC 硬件音量，状态页会如实显示是否因 DAC 不支持音源格式而未达成比特完美。 高速显式反馈设备每个传输覆盖约 8 ms，USB 侧约有 128 ms 在途音频，后台调度抖动 不会直接断流；反馈值格式与总线速度不符时会像 Linux snd-usb-audio 一样自动校正； 传输运行后每次缓冲回调都会把 PCM 队列补到水位，高采样率音源不会因播放线程按 动态调度休眠而慢于实时。 设置页会显示后台行为是否受电池优化或后台权限限制；服务端播放保持时，后台音频锚点 跟随系统默认路由，只在路由到内置扬声器时写入零均值载波，不会把载波当作用户可听内容。

• 💾 可配置流媒体缓存：

使用 SimpleCache + LRU 缓存音频，默认上限 1 GB， 支持分别清理音频缓存、图片缓存、分享暂存和平台歌单缓存， 清理面板会先扫描分类容量，完成后刷新占用并显示实际释放空间。 清理音频和封面时，通过 0–1000 首、步进 50 首的滑块保留最近播放的不同歌曲，音频与封面共用名单； 两类缓存和合计的预计可清理容量会随选择平滑更新，计算中或无法估算时显示占位，并同时列出实际占用。 详情统计目录物理占用；预计释放排除当前歌曲（含暂停）、保留缓存和索引文件，缓存实例不可读取时不会误报为 0。 0 表示不保留历史歌曲缓存，当前播放的音频仍受保护，不会为保留名单补下载。 开启保留时，无法确认歌曲归属的旧缓存会保守保留，实际留下的缓存可能多于 X 首。 “其他缓存”目前可清理歌词分享卡片；同步、备份恢复、下载续传和未知用途文件单独列为受保护数据。 下载暂存包含续传与恢复凭据，由下载恢复管理；已下载歌曲、歌词和封面不会被普通缓存清理删除。

• 🛰️ 脱机模式：

自动感知系统默认网络承载状态，脱机时停用在线探索和首页远程刷新， 远程图片只走本地缓存；本地文件、已下载音频、播放缓存、歌单、 最近播放和播放统计仍可访问。

• ⬇️ 应用内下载与管理：

支持多平台音频下载、本地下载列表、任务进度、取消/重试， 并保存歌词、封面、元数据和音频标签；默认下载并发为 6， 可在设置中调整，最高 8。下载队列会持久化，应用重启后可恢复 未完成任务，已存在的完整下载会直接结算为完成状态；需要显式 Range 的平台传输会按分块 Range 并支持续传，下载完成后标签写入失败也不会删除已落盘音频。

• 📁 可迁移下载目录：

下载文件默认在应用管理目录，也可通过 SAF 选择自定义目录； 切换目录时会迁移已有下载，并支持自定义文件名模板。 出于性能考虑，不建议频繁切换到 SAF 目录。

• 🎵 本地音频导入与扫描：

支持系统 VIEW / SEND / SEND_MULTIPLE 的 audio/*， 也支持扫描设备本地音乐、按授权文件夹定向扫描， 并自动识别附近歌词与封面 sidecar 文件；大批量扫描会先快速预览， 可按“已有元信息”过滤预览结果，再在后台补全更完整的本地元信息；SAF 空目录结果 不会误清理已有目录索引。

• 👤 本地歌手分类与详情：

本地歌曲会按展示艺术家自动分组，并识别 feat.、with、和/与、 顿号、分号和常见斜杠分隔；本地歌手页支持播放全部、多选、 导出为歌单，以及对在线来源歌曲发起批量下载。

• 🩷 本地歌单与收藏：

内置「我喜欢的音乐」和「本地文件」系统歌单；「本地文件」按「手动添加」 和「已下载」分类；两类来源独立统计，手动添加的已下载歌曲会同时显示在两个分类中。 移除手动添加的歌曲只会移出歌单，确认删除已下载歌曲时会一并清理受管下载文件。 普通本地歌单支持创建、重命名、删除、排序和添加歌曲； 长按歌曲后，删除和下载常驻顶部，其余操作收纳到「更多」；可排序歌单支持将选中歌曲 按当前顺序整体插入到指定序号，先预览封面、歌曲和前后各 5 首上下文，确认后再保存， 并平滑定位到插入位置，通过提示条撤销本次移动。 删除歌单或歌曲后会提供撤销反馈，批量导出到本地歌单时也会确认目标并支持撤销新增内容； 详情会显示累计播放次数；收藏页提供歌单、歌手和热点分类，热点会按个人歌曲收听记录生成可播放的周榜和月榜。 「我喜欢的音乐」支持同步可识别歌曲到网易云我喜欢的音乐。

• 🧑‍🎤 网易云艺术家详情：

网易云歌曲可进入艺术家页，查看艺术家信息、热门歌曲与专辑分页， 并支持关注/取消关注；关注的艺术家会出现在媒体库收藏分类中。

• 🧺 网易云歌单详情缓存：

歌单详情会缓存 header 与曲目列表，二次进入可先展示本地缓存； 网络失败或解析失败时也能回退到最近一次成功加载的数据。

• 📖 歌曲百科：

在播放页「更多 → 歌曲百科」查看网易云提供的曲风、语种、BPM、发行信息、创作团队、 艺人资料、评论预览、相似歌曲、相关歌单与获奖收录；仅展示数据源实际返回的内容。 听歌记录来自本机统计，并非网易云账号完整历史；非网易云歌曲会显示暂不支持，失败时可重试。

• ☁️ GitHub / WebDAV 同步：

可选同步本地歌单、收藏歌单、最近播放、歌曲与歌单播放统计和删除记录， 使用 WorkManager 做延迟与周期同步，数据保存在用户自己的远端。

• 📊 播放统计：

按歌曲稳定身份记录播放次数、累计收听时长、首次/最近播放时间和每日统计桶； 支持按日/周/月/年/总计查看；周/月/年分别采用近 7/30/365 天窗口，并可参与 GitHub/WebDAV 同步； 歌单打开次数和本地歌单累计/每日播放同样参与按设备分片的同步合并；周/月热点歌单由同步后的歌曲收听统计动态生成，周榜仅收录累计收听不少于 10 分钟的歌曲，月榜门槛为 30 分钟； 同步合并会保留全量累计和每日桶，旧版 bucket-only 数据也会被提升为可见累计； 写入采用延迟批量策略， 在关键生命周期 flush，播放累计与每日桶不再按数量淘汰。

• 📶 流量统计与高风险提示：

记录播放/下载流量、Wi‑Fi/移动/漫游分布和缓存命中； 在移动网络或漫游环境下下载时可主动提示风险。

• ♻️ 备份与恢复：

支持歌单 JSON 导入/导出；也支持完整配置导入/导出， 可迁移设置、语言、平台授权、GitHub/WebDAV 配置与一起听设置。

• 🎧 一起听：

支持创建房间或加入他人房间，通过 WebSocket 实时同步播放状态， 支持房主/听众权限、成员控制开关、成员加入或显式离开时可自动暂停、同一成员重连不暂停、循环/随机模式同步、 可选共享房主解析的会话播放候选、邀请链接、深链加入、自定义服务端和房主离线检测；首次加入必须 提供邀请密钥，成员重连使用成员密钥。房主可分别复制邀请信息和邀请密钥；点击加入会从 剪贴板读取有效邀请，无有效邀请时不会入房。本地歌曲不能建房或替换房间当前曲目；会话候选共享 开启时，Worker 只公开并缓存当前曲目的房主候选，听众可直接取得缓存，关闭共享会清空缓存； 当前曲目最多保留 3 条候选，听众先按本机音质策略解析并优先尝试本机候选，本机候选 无法启动时再在本次会话内依次回退；候选不会写入歌曲或离线缓存。随机模式会提交并 复用发起端已经生成的真实队列顺序，关闭随机时恢复顺序；队列拖动、添加和删除会以 房间版本化操作合并，双方同时操作时保留可重放的意图，纯重排不会重载当前歌曲。 房间会按当前曲目时长推算服务端位置，单曲循环会按时长回绕，模式切换会重新锚定进度； 控制事件按客户端顺序过滤，REQUEST_SET_TRACK 只能选择当前队列歌曲，并继续校验稳定 曲目键和服务端时钟。

• 🌈 个性化与主题：

支持 Material You 与预览版简洁（Clean）界面风格、自动/浅色/深色模式、动态取色、种子色、主题配色、UI 缩放、 自定义背景图、触感反馈、歌词字号（封面页和歌词页可分别调整）、 歌词模糊、默认启动页和首页卡片开关；未设置高刷新率偏好时默认优先使用屏幕支持的最高刷新率， 已保存的关闭选择会保留，实际刷新率仍由系统调度； Android 13+ 还可按需开启默认关闭的“进阶高级模糊”，增强顶部/底部 Tab 与设置结构卡片材质；模糊度可在 12-64 dp 间调节，父级关闭时会保留 子级选择和模糊度但停止进阶绘制。模糊质量可独立选择超低、低、默认或高； 低和超低保持默认覆盖范围，以局部渲染、动态下采样和硬件缓存减轻开销， 天玑设备在未保存偏好时默认超低，并会在前后台恢复或切换质量后重建缓存。

• ✨ 播放页动效与歌词：

支持 RuntimeShader / GLSL 流体背景、音频反应式动态背景、封面模糊背景、 仿 Apple Music 歌词、高级歌词、逐词歌词、翻译歌词、歌词偏移、 音译显示、歌词长按分享、歌词卡片生成、歌词编辑、歌词字体调节， 且封面页与歌词页的歌词 / 翻译字号可分别调节， 歌词触感反馈和 Lyrics 全屏页。封面页逐行歌词与底部 Dock 工具栏可以分别关闭； 窄屏或高缩放的竖屏会自动切换为紧凑布局，并将操作按钮收缩到稳定的触控槽位。 歌词分享支持逐行点选和从起点到目标行的长按范围选择。RuntimeShader 动态背景仅在 Android 13+ 启用；封面模糊需要 Android 12+，高级模糊需要 Android 13+，低版本会降级。

• 👆 迷你播放器手势：

底部 Mini Player 支持横向滑动切换上一首/下一首，同时保留点击展开与播放暂停。

• 🧩 桌面小组件：

提供 4x1 横条、2x2 迷你播放器和 4x2 播放卡片； 迷你播放器以整张封面为背景，宽卡片将封面与文字分区显示， 背景和主播放键从封面取色，并适配明暗主题、大字体与横竖屏尺寸。空间充足时显示 收藏和桌面歌词入口；窄尺寸也保留上一首、播放与下一首。播放时本地按秒更新 已播放时间，进度条定期刷新；暂停和切歌立即刷新，无播放服务时保留歌曲并显示暂停。

• 🚀 启动器快捷方式：

长按桌面图标可继续播放上次队列、打开探索、打开媒体库或随机播放我喜欢的音乐； 没有可恢复队列或我喜欢的音乐为空时会给出反馈而不是静默失败。

• 🪟 悬浮歌词与状态栏歌词：

支持系统悬浮歌词，颜色、描边、字号、位置、对齐和翻译显示都可自定义； 也支持魅族状态栏歌词和 SuperLyric 输出， 应用前台可自动隐藏悬浮窗避免遮挡。

• 🔌 外部歌词/设备联动：

支持词幕适配（Lyricon Provider）、SuperLyric、外部蓝牙歌词、 蓝牙断连暂停和 USB 独占播放开关；外部歌词链路会同步当前歌曲、 播放状态、进度、逐字歌词和翻译；Lyricon/SuperLyric 进度由独立 200 ms 推送， 翻译行按时间匹配。蓝牙歌词的原文和翻译可独立开启；原有歌词兼容模式下同时开启时会分别写入 标题和艺术家字段，并在专辑/描述字段保留曲目信息。歌词卡片使用缓存， 歌曲分享支持 Xiaomi Super Island 链接。

• ColorOS 锁屏岛歌词（实验性）：

在“设置 → 外部歌词”中开启，向现有媒体会话发布 ColorOS 16/17 的完整逐行、逐字和翻译时间轴。 配置面板分别提供 Root 与 Shizuku 的检查、应用和恢复操作；不会因开启歌词输出而自动修改系统配置。 只更新现有厂商配置中的本应用条目，保存初始恢复记录，并在配置冲突或系统更新后停止写入。 厂商配置缺失、格式不兼容或 Shizuku 被系统权限限制时会报告原因；不能保证所有 ROM 都可解锁入口。 开启时媒体歌名、歌手保持稳定，只读取这些字段的蓝牙车机可能不再显示歌词；关闭后恢复原模式。 恢复发布更高版本的原策略，不保证所有后续厂商更新立即生效；系统更新后应重新检查。 再次应用已确认的配置可重试重载，不重复写入。冲突后可经确认丢弃已完成操作的本机恢复记录； 此操作不会改变系统配置，但将失去最初策略的恢复能力，结果未知的写入记录仍会保留。 本地测试和标准模拟器不代表 ColorOS 16/17 真机锁屏岛或 AOD 已验证。

• 🚗 车载播放：

向蓝牙媒体会话发布歌名、歌手、专辑、时长、曲序和封面。在设置的“歌词设置”中， “蓝牙车载显示模式”可选择歌曲信息优先、歌曲与歌词或原有歌词兼容模式； 原文和翻译仍可独立开关，默认使用“歌曲与歌词，保留歌手”，已保存的模式选择保持不变。 Android Auto 和支持 AVRCP 浏览的设备可浏览当前队列、本地歌单、最近播放和离线歌曲， 并搜索已有曲库、选择歌曲、继续上次队列及控制播放。连接曲库不会自动播放。 AVRCP 没有独立歌词字段，歌词借用标题区域；歌词刷新和封面传输取决于手机系统与车机能力， 不保证所有普通蓝牙车机支持。Android Auto 提供车机自己的播放界面， 当前不包含独立 Android Automotive OS 安装版本。

• 🛠️ 开发者模式与调试工具：

设置页连续点击版本号 7 次 后，底栏出现 Debug 页， 包含 YouTube / Bili / Netease / Search / Listen Together 探针、 普通日志与崩溃日志查看器。

• 🧾 登录与日志更友好：

支持网易云 / Bilibili 二维码登录与网页登录兜底； 开发者模式外也可开启持久文件日志，便于复现疑难问题。

• 🛟 安全模式与崩溃日志：

上次启动发生 JVM / Native 崩溃或系统 ANR 时，可直接进入安全模式预览或导出日志， 并按需清理设置、授权信息或崩溃标记。

---

平台现状 / Platform Status

• 网易云音乐：

登录、歌曲搜索、精选歌单、专辑、歌单/专辑列表搜索、播放、下载、歌词、播放页元数据补全， 无权限播放兜底、本地收藏同步到网易云我喜欢的音乐、艺术家详情、 热门歌曲/专辑分页、艺术家关注和歌曲百科；播放页评论支持热门（默认）、最新、推荐排序、被回复内容和楼中楼展开、 长按复制，以及登录后的点赞、取消点赞、发评论和回复。发送失败保留草稿，网络结果不确定时不自动重发。 评论优先显示当前登录会话的内存缓存，后台核对一致时不显示刷新动画；打开评论区不会自动唤起键盘。

• Bilibili：

Web 登录、二维码登录、视频搜索、创建收藏夹、订阅收藏夹、合集、 收藏夹/合集列表搜索、分 P 转音频播放、下载； 首页提供音乐热门榜、原创榜和音乐分区热门视频，可打开完整列表并播放有效音源； 链接识别会保留选中的分 P，并能从 season_id 或视频详情恢复合集上下文； 播放页评论支持热门（默认）和最新排序，以及登录后的点赞和取消点赞；最新列表及后续分页可能需要登录。 评论楼号按当前列表顺序显示，支持楼中楼分页、长按复制，以及登录后的发评论和回复。 同样支持按登录会话隔离的缓存优先显示和后台静默核对。

• YouTube Music：

登录、首页/媒体库歌单浏览、歌单详情、搜索和播放兼容， 并包含 PoToken / JS Challenge 相关支持；内容访问仍受平台规则和用户账号权限约束。

• QQ 音乐：

当前仅用于播放页元数据和歌词补全，未实现登录、播放和库页数据。

• 本地音频：

支持外部分享/打开导入、设备扫描、授权文件夹扫描、本地文件播放、 本地歌手分类、分享和本地歌单管理。

---

实现概览 / Implementation Notes

构建与版本

• compileSdk = 37
• targetSdk = 36
• minSdk = 28
• Java 17 / Kotlin JVM 17；Kotlin 2.4.10 / KSP 2.3.10
• AGP 9.4.1 / Gradle 9.6.1
• NDK 27.0.12077973
• CMake 3.22.1，由 Android 构建脚本固定指定
• 版本名格式：<git短哈希>.
• Release APK 文件名：NeriPlayer-[-abi].apk
• 默认 Release APK 只打包 arm64-v8a；多 ABI 输出需加

-PbuildAllReleaseAbis=true

• .github/workflows/android_native_ci.yml 会在 Native 相关变更时运行

Release + -Werror、ASan+UBSan、TSan 三组 host CTest，并单独编译 arm64-v8a、armeabi-v7a、x86、x86_64 四个 Android ABI。

模块结构

自有 Android 库按业务域组织，由 gradle/owned-modules.txt 统一登记，共 14 个。一级领域使用 modules/<领域>，播放和下载保留规则与运行实现两个独立构建边界。远程音乐、歌词和元数据来源集中在 :platform，api 表达同库内部的请求协议职责；公共能力契约由模型和宿主接口表达。

• :common：共享工具、日志、文案、图标、语言能力和测试夹具。
• :network：通用 HTTP、Range、网络解析和 Web 登录基础能力。
• :model：按业务分类的数据模型、枚举和跨模块状态契约，不依赖项目实现。
• :database：Room 数据库、实体、DAO、历史 schema 与版本升级。
• :native：Native 崩溃处理、DSP 音效、USB 协议与 PCM 计算、独占传输和第三方 libusb，生成并打包 lib_neri.so。
• :playback:logic：播放 policy、状态协调 runtime、PCM/audio 和队列 queue 规则，保持包级隔离。
• :playback:runtime：Media3 引擎、播放服务、音源解析、USB 输出、Native DSP 接入、浮窗与蓝牙歌词及宿主接入。
• :download:logic：下载准入、状态迁移、重试、调度、传输槽位、所有权、提交与元数据规则。
• :download:runtime：下载执行、Room 队列、受管文件、迁移与恢复，以及 Worker 和 JobService。
• :lyrics：LRC/YRC/TTML 解析、转换、时间轴、翻译对齐、时间偏移，以及词幕（Lyricon）和 SuperLyric 接入。
• :platform：Bilibili、网易云、YouTube 的协议、账号、缓存和业务能力，跨平台评论，以及歌词来源、元数据搜索、匹配与回退。
• :local：本地设置、媒体、歌单、历史与统计、备份、流量、存储统计与缓存清理，以及 Android 同步宿主适配。
• :sync：GitHub/WebDAV 传输、加密凭据状态、会话、兼容编解码、合并、并发保护与 Worker 策略。
• :listentogether：一起听协议、HTTP/WebSocket 传输、身份规则、会话、连接恢复、控制与播放同步。

:app 维护 Android 入口、Compose 页面和跨领域依赖组装。设置项生成由 :ksp-annotations / :ksp-processor 维护，上游歌词子模块为 :accompanist-lyrics-core / :accompanist-lyrics-ui；:hidden-api 只为播放运行模块提供编译期接口桩，不随应用打包；build-logic 提供构建逻辑。np-submodule/NeriPlayer-LTW 是一起听 Cloudflare Workers 服务端，np-submodule/miuix 是未参与主应用构建的上游源码与文档树。这些不计入 14 个自有 Android 库。

依赖按实际职责维护，不由目录分类推导层级。:model 不依赖项目实现，:common 不依赖业务领域；数据库、存储计算、歌词解析与播放/下载规则不得反向依赖仓库或 Android 运行实现。:platform 内的业务仓库消费对应协议，API 不反向读取账号仓库、Room 或播放器状态，各平台仍保持包级依赖边界。:local 消费数据库与领域服务，客户端的账号、凭据刷新和存储能力通过窄接口注入。所有库禁止依赖 app 或形成循环。

:playback:logic 的 policy 只包含 audio、command、offload、pending、progress、service、skip、storage、wake 九个叶子包，不引用 runtime、audio 或 queue 实现；USB policy 仍归 :playback:runtime。:platform 依赖并公开 :lyrics 的解析能力；歌词来源仓库、匹配和回退留在平台，:lyrics 不依赖平台。词幕 SDK、位置推送与异步请求代次由歌词库维护，播放器通过窄加载端口提供歌词、偏好快照和生命周期输入。

共享业务契约统一放入 modules/model，沿用 data.model.<业务> 等既有包名；页面私有状态随 UI 维护，Room 实体随数据库维护，私有算法中间状态随算法维护。物