Songloft播放器 V2.11.1 官方版

　　Songloft播放器是一款面向个人的、开源自托管的音乐服务器软件。它的核心理念是让你完全掌控自己的音乐数据。简单来说，你可以在自己的电脑、NAS（网络附加存储）或树莓派等设备上部署它，然后通过它来管理和播放你本地存储的音乐文件。它由轻量高效的 Go 语言编写，后端服务非常精悍，同时提供了功能丰富的跨平台客户端，让你能随时随地享受自己的音乐库。

【功能说明】

　　本地音乐管理 — 扫描本地目录，自动提取 MP3/FLAC/WAV/APE/OGG/Opus/M4A/M4B/WMA/AIF/AIFF/MKA 等格式的封面和元数据

　　视频支持 — 扫描 MP4/MOV/M4V/MKV/WebM/AVI/TS/MPG/MPEG/FLV/WMV/RM/RMVB/3GP 等视频容器并探测真实视频轨，客户端内渲染画面

　　JS 插件体系 — 基于 QuickJS 沙箱运行，支持权限模型、健康检查、热更新，可自由扩展音源 / 元数据 / 设备控制等能力

　　跨平台客户端 — Flutter 客户端支持 Android、iOS、macOS、Windows、Linux、Web 六端

　　Bundle 本地模式 — 客户端内嵌 Go 后端，无需部署服务器，手机/电脑直接播放本地音乐

　　Kodi 插件客户端 — 支持 Xbox、Apple TV、树莓派、Android TV 等大屏设备，专为遥控器操作优化，带来流畅的客厅影音体验

　　Web 界面 — 完整版内置 Web 前端，开箱即用

　　JWT 认证 — 双 Token 机制（Access Token + Refresh Token），支持多设备管理

　　网络歌曲 & 电台 — 支持添加网络音频 URL 与电台流，播放时透明缓存到服务端

　　完整 REST API — 内置 Swagger 文档，方便集成和二次开发

　　轻量高效 — Go 编写，CGO-free，无外部依赖，适合 NAS / 树莓派等低功耗设备

【Songloft播放器安装配置指南】

　　1、下载对应平台的二进制文件（默认即完整版），并重命名为 songloft.exe

　　例如Windows x86_64: songloft-windows-amd64.exe

　　2、创建必要目录

　　mkdir music

　　mkdir data

　　3、设置环境变量并启动（PowerShell）

　　$env:ADMIN_USERNAME = "admin"

　　$env:ADMIN_PASSWORD = "your_strong_password"

　　.\songloft.exe

【使用流程】

　　1、启动服务

　　服务启动后，访问 http://localhost:58091 即可打开 Web 界面（仅完整版内置；精简版请使用 Flutter 客户端 连接）。

　　2、登录系统

　　使用配置的管理员账号密码登录。

　　3、配置音乐目录

　　首次登录后，进入「设置」页面配置音乐文件目录（music_path）。Docker 部署时通常配置为 /app/music。

　　4、扫描音乐

　　在 Web 界面中点击"扫描"按钮，系统会自动扫描音乐目录中的音频文件并提取元数据。

　　5、播放音乐

　　扫描完成后，即可在界面中浏览和播放音乐。

【常见问题】

　　Q: 音乐文件无法播放怎么办？

　　A: 检查以下几点：

　　1、确认音乐文件格式是否受支持

　　2、确保音乐文件路径配置正确

　　3、检查文件权限是否允许读取

　　4、可选安装 ffprobe 以获取更完整的音频技术参数

　　5、网络歌曲检查 URL 是否可访问

　　Q: 电台（HLS 流）无法播放怎么办？

　　A: 部分电台源站有 Referer / User-Agent 防盗链，或在 Web 嵌入模式下受 CORS 限制，导致客户端直接拉流失败。可在客户端 设置 → HLS 代理 中打开该开关：

　　开启后，服务端会代拉并改写 .m3u8、代理所有切片 / key / init 段，规避源站防盗链与浏览器跨域限制。

　　代价：所有切片走服务器带宽，请留意流量成本；不需要时可关闭（默认关闭，此时电台 .m3u8 直接由客户端拉取源站）。

　　Q: 如何扫描音乐库？

　　A: 添加或修改音乐文件后，必须手动触发扫描才能在歌曲库中看到。在客户端的 设置 → 扫描管理 中点击扫描按钮（注意该按钮是长条形的，不是提示框）。扫描是异步执行的，可以通过进度接口查看状态，也可以取消正在进行的扫描。