🎵 SPlayer for Android

基于 SPlayer 移植与重做的 Android 音乐播放器。保留原版精华，针对手机与平板彻底重构交互——一个能装进口袋的 SPlayer 🎶

---

📸 界面预览

📱 手机	💻 平板

---

✨ 特性一览

分类	描述
🎨 双端 UI	手机 / 平板自适应布局，沉浸式全屏，状态栏可切换
📐 手机端布局	全宽贴底底栏 + 圆角浮岛播放栏，底栏选中态滑动指示器；列表 / 卡片 / 设置项轻度紧凑
🔍 页面缩放	50%–150% 全局缩放，缩小后等效视口变宽，达到阈值可切换 Pad 布局（尚未完全适配）
🎵 播放引擎	原生 ExoPlayer + WebView 双引擎，长时间后台稳定，seek / gapless 切歌进度条同步
📝 逐字歌词	毫秒级插值高亮，翻译 / 罗马音，拖动吸附最近行，支持全局歌词偏移
📂 本地音乐	自动扫描本地歌曲，支持 TTML / LRC 歌词匹配（同目录 / 独立歌词目录），与桌面端行为对齐
☁️ WebDAV 音乐	通过 WebDAV 连接远程音乐，在线播放与浏览，扩展私人曲库
🪟 桌面歌词	WindowManager 悬浮窗，逐字动画、锁定穿透、拖拽、播控
🔔 通知栏	原生 MediaSession，完整播控，支持桌面歌词一键开关
🎚️ 精细控制	渐入渐出、进度吸附歌词、允许与其他应用同时播放
🌐 在线音乐	网易云 + Jellyfin / Navidrome / Emby / Subsonic / OpenSubsonic / Last.fm
🔗 网络代理	支持配置 HTTP/HTTPS 代理，内置逆向 API 请求可走代理访问网易云接口
⬇️ 音乐下载	开发者模式下可下载歌曲至 SAF 授权目录，支持自定义子目录分类、歌词/ASS 附件下载
🧩 内置 API	nodejs-mobile-cordova 嵌入网易云 API，离线可用
📦 分架构打包	arm64-v8a / armeabi-v7a / x86_64 / x86 独立 APK

---

📱 平台兼容性

最低要求：Android 10（API 29）

⚠️ 更早的 Android 版本（Android 9 及以下）没有计划去实现支持。原因是：

• 旧版 Android 性能不足以流畅运行本应用的 WebView 渲染和音频处理
• Android 10 以下可用的系统 API 较少，无法实现 SAF 文件访问、MediaStyle 通知、深色模式适配等核心功能
• 这些版本的设备硬件早已过时，完全不适合运行本应用

---

📦 下载与安装

前往 Releases 选择对应 CPU 架构的 APK：

ABI	适用设备	推荐度
arm64-v8a	绝大多数现代手机 / 平板	⭐⭐⭐⭐⭐
armeabi-v7a	2015 年前的老旧 32 位 ARM 设备	⭐⭐
x86_64	Intel 平板、Android 模拟器	⭐
x86	极少数 32 位 Intel 设备	⭐

💡 不清楚自己设备架构？装个 CPU-Z，或者无脑选 arm64-v8a——99% 都是它。

---

🆕 更新日志

完整更新记录请查看 CHANGELOG.md

v3.0.0-rc.3 主要更新：

• ☁️ 新增 WebDAV 音乐源 — 支持通过 WebDAV 连接并播放远程音乐
• 🎵 新增 本地歌曲 — 扫描本地音乐文件，与在线曲库统一管理
• 🔍 新增 页面缩放 — 50%–150% 全局缩放（尚未完全适配，欢迎 PR 帮忙完善；没有 PR 的话也尽量在下个版本彻底做好）
• 📂 新增本地 TTML/LRC 歌词支持（歌词目录扫描 + 同目录查找）
• 🔗 新增网络代理设置（HTTP/HTTPS 代理用于内置 API 请求）
• ⬇️ 新增音乐下载（开发者模式 + SAF 目录选择）
• 🌐 完善流媒体支持（Navidrome / Jellyfin / Emby / Subsonic / OpenSubsonic）
• 📐 重做手机端底栏 / 播放栏布局（全宽贴底底栏 + 圆角浮岛播放栏 + 滑动指示器）
• 🎯 手机端整体轻度紧凑约 -15%（平板保持原样）
• 🔧 修复显示系统状态栏滑动后自动隐藏的问题
• 🔧 修复允许与其他应用同时播放无效的问题
• 🔧 修复 Android 触控跳转异常
• 🔧 修复跳转后 seek 位置丢失回到 0:00
• 🔧 修复自动切下一首进度条跳到非 0:00 错误位置
• 🎚️ 新增全局歌词偏移设置（PR #11）
• 📱 最低兼容性调整为 Android 10

---

🚀 快速开始

环境要求

工具	版本
Node.js	>= 20
pnpm	>= 10
JDK	21
Android SDK / NDK	最新

一键构建

pnpm install
pnpm build:android
cd android && ./gradlew assembleDebug

产物：android/app/build/outputs/apk/debug/（按 ABI 分包）

分步构建

pnpm build:web                  # 前端 Vite 构建
pnpm build:android:node         # 内置 Node API Bundle
pnpm prepare:android:embedded   # 准备嵌入资源
npx cap sync android            # 同步 Capacitor 工程
npx cap open android            # Android Studio 打开

---

❓ FAQ

🔑 桌面歌词打不开，提示需要权限？

需要授予 SYSTEM_ALERT_WINDOW（显示在其他应用上层） 权限。首次启用会自动引导，如果拒绝过，可以去 系统设置 → 应用 → SPlayer → 权限 里手动开启。

🎧 想和其他应用同时播放？

进入 设置 → 播放 → 允许与其他应用同时播放。

⚠️ 注意：开启后将切换为 ExoPlayer 引擎（handleAudioFocus=false），不再抢占音频焦点，可与其他应用同时播放。

📦 我该下载哪个 APK？

无脑选 arm64-v8a。只有极老的设备（通常 2015 年前）才需要 armeabi-v7a。x86 / x86_64 几乎只用于模拟器。

🖥️ 能在电脑上运行吗？

本仓库已剥离 Electron 桌面端打包链路，仅保留 Android 构建。需要桌面版请前往 原版 SPlayer。

🔕 通知栏控制器不显示？

1. 设置 → 播放 里打开 "通知栏音乐控制器"
2. 系统设置里允许 SPlayer 发送通知（Android 13+ 首次启用会弹权限框）

🌙 支持后台播放吗？

支持。通知栏控制器启用后，应用进入后台仍会继续播放，不会被系统快速回收。

📂 本地歌词不显示？

1. 进入 设置 → 本地与缓存 → 本地歌词覆盖在线歌词，添加歌词所在目录
2. 歌词文件可按 歌曲ID.ttml / 歌曲ID.lrc 或 歌名.歌曲ID.ttml / 歌名.歌曲ID.lrc 命名
3. TTML 文件内含 ncmMusicId 元数据的也可自动匹配
4. 放在音乐同目录下、与音频同名的歌词文件（如 歌曲名.lrc）也会自动识别

⬇️ 如何下载歌曲？

1. 进入 设置 → 常规，连续点击版本号 5 次开启开发者模式
2. 在 设置 → 本地与缓存 → 下载配置 中选择下载目录（SAF 授权）
3. 在歌曲列表中点击菜单即可看到下载选项

---

💬 交流 & 反馈

SPlayer for Android 交流群 群号：602750631 一键加群：https://qm.qq.com/q/AjIqKftqgM 群内可讨论使用问题、交流经验，也欢迎反馈 Bug。 ⚠️ Bug 反馈仍建议优先 提交 Issue，便于跟踪与修复。

---

🤖 CI / 发布

手动触发 Android Release 工作流即可分架构构建 & 发布 APK。

签名所需 Secrets：

Secret	说明
ANDROID_KEYSTORE_BASE64	Keystore 的 Base64 编码
ANDROID_KEYSTORE_PASSWORD	Keystore 密码
ANDROID_KEY_ALIAS	Key 别名
ANDROID_KEY_PASSWORD	Key 密码

详细说明见 .github/ANDROID_RELEASE_SECRETS.md。

---

🧑‍💻 参与贡献

欢迎提 Issue 与 PR！提交前请先阅读 CONTRIBUTING.md，了解 Issue / PR / Commit 规范。

• 🐞 提交 Bug
• ✨ 提交功能建议
• 📮 发起 Pull Request

👥 贡献者

感谢每一位为本项目付出时间与代码的伙伴 ❤️

图片由 contrib.rocks 自动生成，随 GitHub 贡献图谱更新。

---

🤝 致谢

本项目基于 SPlayer 移植，向原作者 @imsyy 与所有贡献者致以最诚挚的感谢 ❤️

---

📄 许可证

AGPL-3.0 —— 与上游保持一致