音乐播放器

音乐播放器现在支持两种音乐来源：电脑中的本地音乐，以及通过 Subsonic / OpenSubsonic 协议读取的 NAS 音乐。电脑端可以按使用场景选择来源，移动端则使用 NAS 音乐，并提供单独设计的全屏播放界面。

一、添加播放器与选择来源

1. 在主页添加一个个性化组件。
2. 打开组件内容设置，选择“日常工具 → 音乐播放器”。
3. 在“音乐来源”中选择“本地音乐”或“NAS 音乐”。
4. 完成对应来源的设置后保存组件。

二、使用本地音乐

选择“本地音乐”后，点击文件夹按钮选择电脑中的音乐目录。如果音乐按照歌手或专辑放在多级文件夹中，还需要开启“扫描子文件夹”。

当前支持的音频格式包括：

• MP3；
• WAV；
• OGG；
• FLAC；
• AAC；
• M4A。

建立音乐索引

启用“解析元数据”后，可以为当前目录建立轻量索引。索引只保存歌名、歌手、专辑和时长，不保存封面与歌词，也不会修改原音乐文件。

• 建立索引：适合首次使用或增加了少量音乐，只处理需要更新的内容。
• 重建索引：适合大规模移动、重命名音乐，或者索引信息明显错误时重新扫描。

三、配置 NAS 音乐服务

选择“NAS 音乐（Subsonic / OpenSubsonic）”后，点击“配置 NAS 音乐服务”，填写服务器地址与账号。

本地地址和远程地址可以只填写其中一个。两个地址都填写时，播放器会优先使用延迟更低的本地连接；本地连接不可用时自动切换到远程连接，网络恢复后也可以重新使用本地地址。

填写完成后，可以按实际需要使用三个测试按钮：

• 测试本地：只检查家庭局域网地址是否可以登录和读取服务器信息；
• 测试远程：只检查外网地址，适合在配置 HTTPS、反向代理或 VPN 后单独排查；
• 智能测试：同时检查两条线路，并确认它们是否指向同一台音乐服务器。

测试成功后，下方状态卡会显示线路是否在线、连接延迟和当前使用的地址。最下方的服务器信息用于确认服务端类型、API 版本与 OpenSubsonic 扩展能力；这些详细诊断信息只出现在配置界面，播放器主界面只保留精简的服务器名称。

密码会加密保存在插件共享的 NAS 音乐设置中，不会写入单个主页组件。密码框留空时会继续使用已经保存的密码；只有点击“清除密码”才会删除它。修改配置后，使用同一插件数据的音乐播放器会读取新的连接信息。

四、电脑端 NAS 音乐播放器

NAS 播放器可以按歌曲、专辑、艺术家、收藏和播放列表浏览音乐，也可以搜索服务器曲库。歌曲列表采用分页加载，音乐较多时点击“加载更多”继续读取。

播放器右上角会显示当前使用“本地”还是“远程”连接、服务器名称以及连接延迟。歌曲名称过长时会自动省略，连接状态不会挤占歌曲列表空间。

五、移动端播放器

移动端只使用 NAS 音乐，不读取本地文件夹。播放器采用独立的全屏界面，不会把电脑端弹窗直接缩小到手机屏幕。

手机端主要分为以下页面：

• 正在播放：查看封面、歌曲信息、连接方式和播放控制；
• 歌词：单独浏览同步歌词或普通歌词；
• 音乐库：逐级进入歌曲、专辑、艺术家、收藏、播放列表和搜索；
• 播放队列：查看、切换或移除即将播放的歌曲。

如果尚未配置 NAS，移动端会提示“手机端只支持 NAS 音乐”，此时需要先在电脑端或可打开组件设置的界面完成 NAS 配置。

六、悬浮快捷入口与后台播放

在移动端设置的“悬浮快捷按钮”中启用“音乐播放器”，即可通过耳机图标直接打开 NAS 播放器，不需要先打开移动主页。

播放器由插件级常驻实例负责运行。关闭音乐播放器页面或移动主页后，音乐仍可继续播放；再次点击悬浮入口会回到同一播放状态，不会重新启动一份音乐。

思源移动端插件目前无法稳定注册带播放控制和指定跳转动作的系统媒体通知，因此播放器不占用通知栏。音乐在后台播放时，悬浮主按钮会显示脉冲和均衡器动效，用于提示当前仍有音乐正在播放。

七、封面、歌词、时长与进度条

本地音乐优先读取音频文件内嵌的封面和歌词。如果文件中没有对应内容，播放器会继续查找同一文件夹中与音乐同名的图片和 .lrc 文件。

NAS 音乐的封面、歌词和时长由服务器接口提供。部分流媒体响应不会向浏览器返回可靠的总时长，此时播放器会使用服务器曲库中的歌曲时长，保证总时间正常显示并允许拖动进度条。

八、收藏与播放列表

两种音乐来源都支持收藏和播放列表，但保存位置不同：

• 本地音乐：收藏、播放列表和播放统计保存在插件本地；
• NAS 音乐：收藏和播放列表通过服务器接口管理，可以与其他 Subsonic 客户端共享。

本地歌单的 M3U8 与 JSON

本地音乐的单个歌单支持导出绝对路径或相对路径 M3U8，也可以从 .m3u、.m3u8 文件导入。插件 JSON 备份用于保存本地收藏、全部歌单和队列，不包含实际音频文件。

九、播放队列

播放器会按照当前活动队列继续播放。可以用当前列表替换队列，也可以把单首歌曲或整个列表追加到队列中。

使用 NAS 音乐时，播放器会将队列、当前歌曲和播放位置同步到服务器播放队列。关闭页面后再次打开，可以恢复上次的歌曲和进度。

十、电脑端全局迷你播放器

电脑端开启“显示右下角迷你播放器”后，即使离开主页，也可以继续控制播放、暂停、切换音乐和打开播放队列。

迷你播放器与主页组件共享同一个播放状态，不会另外启动一份音乐。移动端使用悬浮快捷按钮和全屏播放器，不显示电脑端迷你播放器。

十一、故障处理

本地音乐列表为空

请依次检查：

1. 当前运行环境是否为思源桌面端；
2. 音乐文件夹是否仍然存在；
3. 音频扩展名是否受支持；
4. 音乐位于子目录时是否开启“扫描子文件夹”；
5. 修改设置后是否重新保存组件。

NAS 音乐无法连接

1. 先分别测试本地地址和远程地址；
2. 检查 Navidrome 等服务器是否正在运行；
3. 检查用户名和密码是否正确；
4. 确认本地、远程地址指向同一台音乐服务器；
5. 移动端远程播放失败时，优先检查 HTTPS 配置。

出现两个声音或重复播放

正常情况下，一个设备只会保留一个活动播放器。遇到异常时先暂停播放并重新打开播放器；如果仍然存在，重载插件以清理旧音频实例，同时确认同一主页没有放置多个音乐播放器。

NAS 进度条不能拖动

先确认服务器曲库中已经识别出歌曲时长。如果列表中时长正常但播放器仍显示 --:--，重新播放一次并检查服务器是否允许流媒体分段请求。