NeriPlayer 多源聚合音频播放器深度使用指南

导语

NeriPlayer 是由 cwuom 开发的开源原生 Android 音频播放器，基于 Jetpack Compose 与 Media3 构建。它不自建公共云端曲库，而是通过用户自己的网易云音乐、Bilibili 和 YouTube Music 账号，把三个平台的搜索、播放、歌单、收藏统一到一个应用内。

应用围绕「账号即能力 · 本地优先 · 数据自持」三条主线持续打磨：播放缓存、下载文件、歌单、历史、设置默认保存在设备本地；可选将歌单、收藏、最近播放和播放统计同步到用户自己的 GitHub 仓库或 WebDAV 远端，数据写入去中心化的用户自有空间，而非项目维护者的中心化服务。

产品档案速览

结构导览

下面按功能分组列出站内页面，便于快速定位你感兴趣的主题。

多源探索

「账号即能力」是 NeriPlayer 的核心理念——你需要自己持有网易云、Bilibili、YouTube Music 的账号才能启用各平台的搜索、播放和歌单能力。本分组覆盖三个平台的接入方式、分层搜索、链接识别，以及平台各自的兜底与跳过机制。

• [平台接入与账号授权]${1}01-platform-access.md${2} —— 三个平台的登录路径、授权方式和注意事项
• [分层搜索与链接识别]${1}02-search-link-detection.md${2} —— 跨平台搜索分类、粘贴分享文案一键识别
• [网易云自动兜底]${1}03-netease-fallback.md${2} —— 无权限时自动匹配 Bilibili 音源的评分算法
• [YouTube 取流多级回退]${1}04-youtube-fallback.md${2} —— Cookie、PoToken、player.js、EJS/HLS 四层缓存与回退
• [Bilibili SponsorBlock]${1}05-bilibili-sponsorblock.md${2} —— 公开接口 + 分 P 分时长的本地自动跳过
• [Bilibili 自定义跳过区间]${1}06-bilibili-custom-skip.md${2} —— 同一视频多个区间的本地规则与同步

播放核心

播放体验由 Media3 引擎驱动，自研 native DSP 处理音效，仿 Apple Music 的深度歌词系统支持逐词高亮、翻译、音译、悬浮与蓝牙输出，还包含 USB 独占播放和 GLSL 流体背景动效。

• [Media3 播放引擎]${1}01-media3-engine.md${2} —— PlayerManager 的音源解析、队列管理、失败恢复
• [逐词歌词系统]${1}02-word-lyrics.md${2} —— LRC/YRC/TTML 格式、逐词/逐字高亮、偏移调节
• [悬浮与蓝牙歌词]${1}03-floating-bluetooth-lyrics.md${2} —— 系统悬浮窗、状态栏歌词、SuperLyric、外部蓝牙输出
• [歌词卡片生成与分享]${1}04-lyrics-card.md${2} —— 逐行点选、范围选择、1080px 卡片导出
• [音效与均衡器]${1}05-dsp-eq.md${2} —— 29 种内置音效、10 段均衡器、AutoEQ、响度均衡
• [USB 独占播放]${1}06-usb-exclusive.md${2} —— UAC1.0/UAC2.0 Type I PCM、比特完美模式、32-bit 高解析
• [流体背景与动效]${1}07-fluid-background.md${2} —— GLSL RuntimeShader、音频响应、封面取色
• [迷你播放器手势]${1}08-mini-player-gestures.md${2} —— 底部 Mini Player 的横向滑动切歌

一起听房间

一起听是 NeriPlayer 相对独立的高级功能——客户端与 Cloudflare Worker 共同维护房间、角色、队列和播放状态，通过 WebSocket 做实时同步，还支持自建服务端和会话候选共享。

• [创建与加入房间]${1}01-create-join-room.md${2} —— 房主/听众角色、邀请链接、深链加入
• [成员权限与控制]${1}02-member-control.md${2} —— 成员控制开关、循环/随机同步、房主离线恢复
• [会话候选共享]${1}03-session-candidate-share.md${2} —— 房主解析结果临时缓存、听众直接取得
• [自建服务端部署]${1}04-self-host-deploy.md${2} —— Cloudflare Workers + Durable Objects 部署要点

本地音乐管理

本地优先意味着所有播放缓存、下载文件、歌单和历史都默认存在设备本地。本分组覆盖从外部分享导入、设备扫描、本地歌手分类到下载队列恢复的完整链路。

• [本地音频导入与扫描]${1}01-local-import-scan.md${2} —— 外部分享、授权文件夹扫描、歌词与封面 sidecar 识别
• [本地歌手分类]${1}02-local-artist.md${2} —— feat./with/和/顿号分隔识别、艺术家详情页
• [本地歌单操作]${1}03-local-playlist.md${2} —— 创建/重命名/删除/排序、「我喜欢的音乐」系统歌单
• [下载任务与恢复]${1}04-download-resume.md${2} —— 可调并发、Range 续传、应用重启后恢复未完成队列
• [可迁移下载目录]${1}05-download-dir-migrate.md${2} —— SAF 选择自定义目录、切换时迁移已有下载

统计与同步

NeriPlayer 的同步策略刻意保持去中心化——数据写入用户自己控制的 GitHub/WebDAV 远端，而不是上传到项目维护者的中心化服务。

• [播放统计]${1}01-playback-stats.md${2} —— 按歌曲稳定身份记录播放次数、累计时长、每日桶
• [流量统计与高风险提示]${1}02-traffic-stats.md${2} —— 播放/下载/Wi-Fi/移动/漫游分布
• [GitHub 同步配置]${1}03-github-sync.md${2} —— 私有仓库创建、凭据管理、同步内容选择
• [WebDAV 同步配置]${1}04-webdav-sync.md${2} —— WebDAV 服务器地址、路径、凭据
• [备份与恢复]${1}05-backup-restore.md${2} —— 歌单 JSON、完整配置导入/导出

个性化与联动

支持自动/浅色/深色模式、动态取色、Android 13+ 进阶高级模糊、桌面小组件（4x1/2x2/4x2）、启动器快捷方式、外部歌词设备联动和车载播放。

• [主题与动态取色]${1}01-theme-dynamic-color.md${2} —— 自动/浅色/深色、种子色、封面取色
• [进阶高级模糊]${1}02-advanced-blur.md${2} —— 12-64 dp 模糊度、质量调节、天玑设备默认超低
• [桌面小组件]${1}03-home-widget.md${2} —— 4x1 横条、2x2 迷你、4x2 播放卡片
• [启动器快捷方式]${1}04-launcher-shortcuts.md${2} —— 长按桌面图标直接继续播放或随机喜欢
• [外部歌词设备联动]${1}05-external-lyrics-linkage.md${2} —— Lyricon/SuperLyric/蓝牙歌词/魅族状态栏
• [车载播放]${1}06-car-playback.md${2} —— AVRCP 浏览、Android Auto、蓝牙车载模式

设置与诊断

• [通用设置项]${1}01-general-settings.md${2} —— UI 缩放、默认启动页、首页卡片开关、触感反馈
• [开发者模式与调试]${1}02-developer-mode.md${2} —— 连续点击版本号 7 次、Debug 底栏探针
• [安全模式与崩溃日志]${1}03-safe-mode.md${2} —— ANR watchdog、Native 崩溃、日志导出
• [缓存与存储清理]${1}04-cache-cleanup.md${2} —— 音频缓存、图片缓存、暂存区分组清理
• [脱机模式]${1}05-offline-mode.md${2} —— NetworkStatusMonitor 自动感知、脱机仍可播放本地内容
• [睡眠定时器]${1}06-sleep-timer.md${2} —— 自动暂停、与音频焦点配合