使用指南
本指南介绍 SPlayer for Android 的安装、界面与全部设置项。设置入口为任意页面右上角的 设置 图标，共 7 个分类（快捷键设置仅桌面端存在，Android 版不显示）。
🚀 首次启动
1. 授予必要权限
首次启动会引导授予两类权限，也可以稍后在系统设置中补授：
| 权限 | 用途 | 是否必须 |
|---|---|---|
| 通知（POST_NOTIFICATIONS） | 通知栏音乐控制器、后台播放保活 | 建议授予 |
| 显示在其他应用上层（SYSTEM_ALERT_WINDOW） | 桌面歌词悬浮窗 | 使用桌面歌词时 |
本地音乐、本地歌词、音乐下载还会在对应功能首次使用时弹出 SAF 目录授权（系统文档选择器），按需授予即可。详见 权限与授权。
2. 选择音乐来源
应用支持三类曲库，可并存：
- 云音乐：扫码 / 手机号登录，内置网易云 API（
nodejs-mobile-cordova嵌入），离线可用； - 流媒体服务器：Jellyfin / Navidrome / Emby / Subsonic / OpenSubsonic / WebDAV，见 流媒体服务；
- 本地音乐：自动扫描 SAF 授权目录下的音频文件与内嵌封面。
📐 界面与布局
手机 / 平板双布局
- 手机端：全宽贴底底栏 + 圆角浮岛播放栏，底栏选中态带滑动指示器；列表 / 卡片 / 设置项整体轻度紧凑。
- 平板端：保留桌面版的侧边栏 + 内容区布局。
- 页面缩放：50%–150% 全局缩放，缩小后等效视口变宽，达到阈值可切换 Pad 布局（尚未完全适配）。入口在 外观设置 → 页面缩放优化。
播放器
- 卡片式播放器：上滑展开 / 下滑收起，带动画过渡与手势交互。
- 快捷操作菜单：一键切换音质、收藏、下载等常用操作。
- 横屏沉浸式：全屏封面 + 歌词的无干扰聆听模式，自动锁定横屏。
- 播放器样式：封面模式 / 唱片模式 / 全屏封面，背景可选流体效果 / 封面模糊 / 封面主色。
- 音乐频谱：播放页底栏频谱柱状图，数据来自原生 256 bin FFT（约 30Hz 刷新）。
⚙️ 设置详解
常规设置
| 分组 | 设置项 |
|---|---|
| 搜索设置 | 显示搜索历史、显示热搜榜、搜索关键词建议、搜索框行为、隐藏括号与别名、评论排除配置 |
| 其他设置 | 分享链接格式（网页版 / 移动版） |
| 备份与恢复 | 导出设置（选择 SAF 目录，生成 splayer-settings-YYYY-MM-DD.json）、导入设置（选择 .json 文件覆盖全部配置并重启） |
| 重置 | 重置所有设置、清除全部数据（清空 localStorage / IndexedDB 并退出登录） |
桌面端的「系统行为」分组（在线服务、关闭行为、自动检查更新等）在 Android 版中不显示。
外观设置
| 分组 | 设置项 |
|---|---|
| 主题与风格 | 主题模式（跟随系统 / 浅色 / 深色）、主题配置（主题色 / 自定义图片）、页面缩放优化（手机竖屏 / 平板竖屏 / 平板，50–200%）、全局字体、自定义代码注入（开发者模式） |
| 界面布局 | 侧边栏管理、首页栏目排序、歌单界面元素、全屏播放器元素、侧边栏显示歌单封面、显示播放列表数量、页面切换动画 |
| 播放器外观 | 播放器样式及封面 / 歌词占比、播放器背景样式及帧率 / 流速 / 渲染缩放、播放器展开动画、播放器主色跟随封面、动态封面、显示评论及评论显示模式、音乐频谱 |
| 界面元素显示 | 封面显示管理、播放器元素自动隐藏、展示播放状态信息、底栏显示歌词、显示歌曲音质、切换音质按钮、前奏倒计时、时间显示格式 |
| 歌曲列表显示 | 专辑 / 歌手 / 时长 / 操作 / 音质 / 特权标签 / 脏标 / 原唱翻唱标签 / 隐藏括号内容 |
播放设置
| 分组 | 设置项 |
|---|---|
| 播放控制 | 下一首歌曲预载、记忆上次播放位置、阻止系统息屏、进度条悬浮信息、进度调节吸附最近歌词、音乐渐入渐出及时长 |
| Android 系统设置 | 见下表 |
| 音频设置 | 在线歌曲音质（标准 128k → 杜比全景声共 11 档）、Fuck AI Mode、Fuck DJ Mode、Fuck *** Mode、音量平衡 ReplayGain |
Android 系统设置（仅 Android 版可见）：
| 设置项 | 说明 |
|---|---|
| 通知栏音乐控制器 | 开启时申请通知权限；启用后应用进后台仍继续播放，不会被系统快速回收 |
| 显示桌面歌词按钮 | 在通知栏上加一个桌面歌词一键开关 |
| 允许与其他应用同时播放 | 关闭时独占音频焦点（暂停其他应用）；开启后切换为 ExoPlayer 引擎且不再抢占焦点，切换时会重建音频引擎 |
| 显示系统状态栏 | 关闭后进入沉浸式全屏 |
| 隐藏底部导航栏 | 隐藏系统导航栏，上滑可临时唤出 |
桌面端的「音频处理引擎」（Web Audio / FFmpeg / MPV）在 Android 版中不显示：FFmpeg 需要跨域隔离，Android WebView 无法满足；MPV 仅桌面端可用。
歌词设置
| 分组 | 设置项 |
|---|---|
| 歌词设置 | 歌词预览、本地歌词覆盖在线歌词（SAF 歌词目录）、自适应歌词大小、歌词 / 翻译 / 音译字号、歌词字体与字重、切换动画、对齐、两侧边距、滚动位置、逐字歌词、翻译与音译显示、歌词自动模糊、混合模式 |
| 全局歌词偏移 | ±10000ms 偏移与快捷预设、始终启用偏移、双击歌词页封面应用偏移、时延调节步长 |
| 歌词内容 | 歌词源优先级（自动 / 本地优先 / QM 优先 / TTML 优先）、本地歌词匹配档位（严格 / 标准 / 宽松）、繁体中文及变体、在线 TTML 歌词与 AMLL TTML DB 地址、歌词排除配置、括号内容替换 |
| Apple Music-like Lyrics | 使用 AMLL、歌词弹簧效果、隐藏已播放歌词、文字动画渐变宽度、显示逐字音译 |
| 桌面歌词 | 见 桌面歌词 |
本地歌词匹配档位（Android 专属）：
- 严格：标题 + 专辑 + 歌手全部匹配；
- 标准：任意两项匹配；
- 宽松：任意一项包含即匹配。
本地与缓存
| 分组 | 设置项 |
|---|---|
| 本地歌曲 | 显示本地歌曲封面、本地文件夹显示模式、显示本地默认歌曲目录、本地歌曲目录（SAF 授权 + 自动扫描 + 实时同步）、本地歌词目录 |
| 缓存配置 | 启用缓存、缓存歌曲、缓存大小上限（最小 256MB，设备剩余空间不足时自动下调）、按类型清空（音频 / 歌词 / 封面 / 列表数据）、立即整理 |
| 下载配置 | 仅开发者模式可见，见 下载歌曲 |
网络与连接
| 分组 | 设置项 |
|---|---|
| 流媒体服务 | 启用流媒体、服务器管理（添加 / 连接 / 编辑 / 删除） |
| 网络代理 | 网易云 API 地址（覆盖内置 API）、网络代理（关闭 / HTTP / HTTPS）、代理服务器地址与端口、使用真实 IP 地址 |
| 第三方集成 | 启用 Last.fm、API Key / Secret、连接账号、Scrobble 播放记录、正在播放状态 |
Android 版的代理设置会作为
proxy=参数附加到内置逆向 API 的网易云请求上；桌面端的 WebSocket 配置、Discord RPC、系统音频集成（SMTC）在 Android 版中不显示。
关于与鸣谢
- 关于软件：版本号、检查更新（跳转 GitHub Releases）、更新日志；
- 问题反馈：Issue 入口、QQ 群链接；
- 特别鸣谢 / 上游项目 / 开发人员 / 社区与资讯 / 历史版本。
🔓 开发者模式
在 设置 → 关于与鸣谢 中连续点击版本号 8 次即可开关开发者模式（第 5–7 次会提示剩余次数）。开启后解锁：
- 本地与缓存 → 下载配置 分组与侧边栏 下载管理；
- 外观设置 → 自定义代码注入（CSS / JS）；
- 外观设置 → 页面缩放 滑条；
- 歌曲菜单与播放页的下载按钮、批量下载。
📂 本地音乐与歌词
本地歌曲
在 本地与缓存 → 本地歌曲目录 中通过系统文档选择器授权目录，应用自动扫描音频文件、读取内嵌封面与标签，并与在线曲库统一管理。
本地歌词
在 歌词设置 → 本地歌词覆盖在线歌词 中添加歌词目录，支持 .ttml / .yrc / .lrc 三种格式，匹配规则按优先级：
- 歌词目录内按
歌曲ID.ttml/歌曲ID.lrc命名； - 歌词目录内按
歌名.歌曲ID.ttml/歌名.歌曲ID.lrc命名； - TTML 文件内含
ncmMusicId元数据时自动匹配； - 音频同目录下与音频同名的歌词文件（如
歌曲名.lrc）。
添加目录后可手动重新扫描，界面会显示匹配统计。
🪟 桌面歌词
歌词设置 → 桌面歌词 → 开启桌面歌词，首次开启会引导授予悬浮窗权限。
- 悬浮窗为
WindowManager覆盖窗，支持逐字动画、拖拽移动； - 点击悬浮窗唤出控制栏：锁定 / 上一首 / 播放暂停 / 下一首 / 关闭；
- 锁定后点击穿透，并额外显示一个小解锁按钮；
- 可配置：双行歌词、对齐方式（左 / 居中 / 右 / 左右分离）、字体与字重、字号、已播放 / 未播放 / 描边颜色、文本背景遮罩、悬浮窗宽度（30–100%，默认 92%）、悬浮窗高度（48–240dp，默认 72dp）；
- 通知栏的桌面歌词按钮可一键开关。
🔔 通知栏与后台播放
开启 播放设置 → Android 系统设置 → 通知栏音乐控制器 后：
- 通知栏显示封面、歌名歌手、收藏、上一首 / 播放暂停 / 下一首、桌面歌词开关、收起按钮与播放进度；
- 基于原生
MediaSession，系统媒体面板与蓝牙 / 耳机线控均可控制； - 应用进入后台仍继续播放；拔掉耳机自动暂停。
⬇️ 下载歌曲
- 开启开发者模式；
- 设置 → 本地与缓存 → 下载配置 → 默认下载目录 选择 SAF 目录（首次使用需授权）；
- 在歌曲列表的歌曲菜单或播放页中选择下载，批量下载入口在下载管理页。
下载配置可选项：
| 设置项 | 说明 |
|---|---|
| 默认下载音质 | 与在线音质档位一致，受 Fuck AI Mode 过滤 |
| 下载线程数 | 1–32，默认 8，建议 4–16 |
| 下载歌曲元信息 | 总开关，控制以下附件项 |
| 同时下载封面 / 歌词 / 翻译 / 音译 | 按需勾选 |
| 音乐命名格式 | 歌曲名 / 歌手 - 歌曲名 / 歌曲名 - 歌手 |
| 文件智能分类 | 不分文件夹 / 按歌手分文件夹 / 按 歌手\专辑 分文件夹 |
| 逐字歌词另存 | 额外写出 YRC / TTML 侧车文件（歌曲文件内仍内嵌 LRC） |
| 另存为 ASS 文件 | 供第三方播放器使用 |
| 下载歌词转繁体 | 使用繁体变体设置 |
| 歌词文件编码 | UTF-8 / GBK / UTF-16 / ISO-8859-1 |
| 模拟播放下载 | Beta，走播放接口 |
| 使用解锁接口下载 | Beta，走解锁音源 |
合规提示
下载功能仅支持从官方途径合法合规地下载歌曲，云盘歌曲下载的是你上传的源文件。请尊重版权与相关服务的使用协议。
💾 设置导入 / 导出
常规设置 → 备份与恢复：
- 导出设置：选择 SAF 目录，写出
splayer-settings-YYYY-MM-DD.json； - 导入设置：选择
.json文件，覆盖全部配置后自动重启应用。
适合换机迁移或多设备同步配置。
❓ 常见问题
更多排查内容见 故障排查 章节。