SPlayer 5 分钟上手指南支持逐字歌词、桌面歌词与 API 控制的跨平台音乐播放器【免费下载链接】SPlayer A cross-platform music player with Jellyfin / Navidrome / Emby media server support, word-by-word lyrics, desktop taskbar lyrics, cloud music drive, local library management, audio spectrum visualization and mobile-friendly UI. 简约的跨平台音乐播放器支持逐字歌词、桌面歌词、任务栏歌词、云盘音乐、本地音乐管理及流媒体播放项目地址: https://gitcode.com/GitHub_Trending/spl/SPlayerSPlayer 是一个基于 Vue 3 TypeScript Naïve UI Electron 的跨平台音乐播放器支持逐字歌词、桌面歌词、本地音乐管理、云盘音乐与 Subsonic 流媒体服务网页端和桌面客户端两种形态都能用适合普通用户自用也适合想自托管音乐站或做二次开发的玩家。项目采用 AGPL-3.0 协议开源运行需要 Node.js 20 与 pnpm 10。需要提醒一点仓库 README 开头明确标注项目已进入维护模式后续只做必要维护与重大问题修复不再主动开发新功能。想跟进新特性要去看 SPlayer-Next。但这不影响你现在部署和使用它。第一次打开 SPlayer 是什么体验启动后左侧导航把功能分得很清楚发现、歌单、搜索、流媒体、本地、历史、下载。登录网易云账号可以用扫码或手机号两种方式对应界面在 LoginQRCode.vue 和 LoginPhone.vue登录接口封装在 src/api/login.ts。登录之后私人 FM、每日推荐、云盘音乐的上传与删除这些功能才完整可用接口分别落在 src/api/radio.ts、src/api/rec.ts 和 src/api/cloud.ts。SPlayer 播放页面与逐字歌词效果播放页是 SPlayer 最能体现差异化的一块。歌词支持逐字高亮播放时一个字一个字亮过去类似 Apple Music 的效果底层用的是applemusic-like-lyrics组件封装在 src/components/AMLL/LyricPlayer.vue。歌词解析器放在 src/utils/lyric/ 下LRC、QRC 逐字格式、TTML 字幕各有一个解析文件另外还有翻译与屏蔽词过滤lyricProfanity.ts、lyricStripper.ts。桌面歌词是一个独立的置顶透明窗口可以拖动位置、调整字号窗口创建逻辑在 electron/main/windows/lyric-window.ts。在 Windows 上还有一项加分功能歌词直接渲染进任务栏由 native/taskbar-lyric/ 这个 Rust 原生模块实现通过 UI Automation 定位系统托盘区域嵌入歌词Windows 10 和 11 各有独立策略文件。SPlayer 本地音乐管理界面把光标停在歌曲上界面底色会悄悄向封面主题色靠拢这是全站着色。取色逻辑在 src/utils/color.ts配合material/material-color-utilities生成整套 Material 配色明暗模式Light / Dark / Auto由 src/stores/setting.ts 管理。本地音乐库支持目录扫描、按歌手/专辑/文件夹分类还能直接编辑 ID3 标签和替换封面。扫描与数据持久化在 LocalMusicService.ts 和 LocalMusicDB.tsbetter-sqlite3标签读写靠music-metadata库入口在 MusicMetadataService.ts。下载走 DownloadService.ts支持单曲和批量最高 Hi-Res 音质需要相应会员账号进度在 src/views/Download/ 下的页面里查看。5 分钟把 SPlayer 跑起来只想要网页版本地三条命令就够需要 Node.js 20 和 pnpm 10git clone https://gitcode.com/GitHub_Trending/spl/SPlayer cd SPlayer pnpm install cp .env.example .env pnpm build构建产物在out/renderer用任意静态服务器托管即可。注意默认构建会编译native/下的 Rust 原生模块如果不需要系统媒体控件、Discord RPC 这些能力设置环境变量SKIP_NATIVE_BUILDtrue再构建就可以省掉 Rust 工具链。Docker 一条命令启动 SPlayer Web 版 不想本地装 Node 环境的话Docker 路线更省事。Dockerfile 是两阶段构建node:22-alpine里构建前端同样跳过原生模块nginx:1.27-alpine-slim里托管页面并把网易云 API 和解锁服务作为运行时依赖一起装进镜像。docker build -t splayer . docker run -d --name SPlayer -p 25884:25884 splayer启动后访问http://localhost:25884。也可以直接docker-compose up -ddocker-compose.yml 里预置了一批可选环境变量比如UNBLOCK_SOURCES解锁音源示例为kugou kuwo bilibili、ENABLE_FLAC、SELECT_MAX_BR。给每个系统打包桌面客户端要出安装包按系统选命令产物落在dist/命令系统pnpm build:winWindowspnpm build:linuxLinuxpnpm build:macmacOS默认只构建当前架构需要同时出 x64 和 arm64 时追加参数pnpm build:win -- --x64 --arm64。云端部署走 Vercel 或服务器都行共同前提是SPlayer 依赖 NeteaseCloudMusicApi Enhanced 这类第三方 API 服务先把它部署好再把.env里的VITE_API_URL指向它。服务器部署时静态目录设为out/renderernginx.conf 里可以直接参考/api/netease/反代到 API 服务、/music/unblock/反代解锁源的写法。内部分工网页、主进程、本地服务与 Rust 模块SPlayer 的代码按运行位置分成四层各管一摊事渲染进程 src/Vue 3 Pinia Vue Router 的全部界面发现、歌单、搜索、本地、流媒体等页面都在src/views/。主进程 electron/main/窗口windows/、托盘、系统快捷键、本地 SQLite 数据库database/、下载与本地音乐等服务services/。本地服务 electron/server/基于 Fastify 的 HTTP 服务index.ts 里可以看到它注册了云音乐代理netease、解锁unblock、控制control和 QQ 音乐qqmusic四组路由监听127.0.0.1的 25884 端口可用VITE_SERVER_PORT覆盖端口被占用时由 port.ts 自动换端口。原生模块 native/Rust napi-rs 编译的 Node.js 扩展负责系统媒体控件、任务栏歌词等桌面深度集成docs/native.md 有完整说明。播放核心在 src/core/audio-player/定义了统一的IPlaybackEngine接口后挂了三套引擎AudioElementPlayer标准 HTML5 音频覆盖绝大多数在线音源FFmpegAudioPlayer基于 ffmpeg.wasm 在 Web Worker 里解码ffmpeg-engine/用来播 FLAC、ALAC 这类浏览器原生不支持的格式MpvPlayer客户端里调用外部 MPV 进程播放。README 功能列表里的音乐渐入渐出对应 src/core/automix/ 的 AutomixManager配合 Web Audio 做曲目切换时的交叉淡入淡出IPlaybackEngine.ts里的fadeIn/fadeOut/FadeCurve就是给这套机制用的。进阶集成HTTP API、WebSocket 与系统媒体控件SPlayer 把播放器本身当成一个本地服务来开放。完整清单见 API 文档 和 WebSocket 文档这里挑实际会用到的。HTTP 控制接口默认http://localhost:25884统一返回{ code, message, data }curl http://localhost:25884/api/control/play curl http://localhost:25884/api/control/status除play/pause/toggle/next/prev/status外还有/api/netease/*云音乐 API 代理和/api/unblock/*网易云 / 酷我 / 波点解锁源码在 electron/server/unblock/。API 文档特别警告不要用/api/control/song-info高频轮询获取进度实时进度应该走 WebSocket否则软件性能会异常。WebSocket 实时通道默认监听ws://localhost:25885端口可在设置里改实现是 SocketService.ts。连上后会先收到welcome之后播放器变化会主动广播status-change、song-change、progress-change约 500ms 一次、lyric-change反向控制发送一条 JSON 即可const ws new WebSocket(ws://localhost:25885); ws.onopen () ws.send(JSON.stringify({ type: control, data: { command: next } }));保持连接建议定期发PING服务端回PONG。系统级集成由 native/external-media-integration/简称 EMI承担Windows 接 SMTC任务栏缩略图按钮 锁屏控制、Linux 走 MPRISGNOME/KDE 都认、macOS 接控制中心与MPNowPlayingInfoCenter。播放状态、封面、进度双向同步系统的媒体按键也能反向控制播放器。另一块是 Discord RPC在个人资料里显示正在播什么还带一个 Listen 跳转按钮。接入自己的流媒体音乐库如果你有 Navidrome、Subsonic、Airsonic 这类自建音乐服务器docs/streaming.md在设置 → 流媒体服务里添加地址、用户名密码即可。渲染进程侧的适配在 src/api/streaming/除了 Subsonic 协议还有 Emby 和 Jellyfin 两套实现。几个实用细节支持配置多台服务器并自由切换启动时自动连回上次使用的那台服务端返回的 Plain / Structured 歌词会自动转成 LRC 显示流媒体歌曲可以像本地歌曲一样加歌单、收藏、播放服务端歌单可以读进来但客户端新建的歌单暂不同步回去。避坑与注意事项⚠️ 部署和二次开发前这几件事值得先看清楚维护模式README 与官网首页都声明了只修 bug 不加功能做深度二开前建议评估 SPlayer-Next协议约束AGPL-3.0 要求修改、分发、派生项目必须同样开源并保留版权信息商用或售卖有法律风险README 里有专门的严肃警告段落原生模块默认构建依赖 Rust 工具链Windows 还要 Visual Studio Build Tools 的 C 桌面开发组件与 Windows SDK报The specified module could not be found时先跑pnpm build:native确认 x64 / arm64 架构匹配端口占用HTTP 默认 25884、WebSocket 默认 25885改端口分别用VITE_SERVER_PORT环境变量和应用内设置第三方依赖在线功能依赖网易云音乐的第三方 API 服务仅供个人学习研究禁止商业用途Docker 镜像和 Web 部署都要先把 API 服务跑起来或配好VITE_API_URL。本地开发常用命令pnpm dev启动开发模式Electron Vite HMR含原生模块pnpm lint代码检查pnpm typecheck类型检查。更多排障macOS 签名、Windows 7 等可以看 docs/troubleshooting/ 目录下的文档。【免费下载链接】SPlayer A cross-platform music player with Jellyfin / Navidrome / Emby media server support, word-by-word lyrics, desktop taskbar lyrics, cloud music drive, local library management, audio spectrum visualization and mobile-friendly UI. 简约的跨平台音乐播放器支持逐字歌词、桌面歌词、任务栏歌词、云盘音乐、本地音乐管理及流媒体播放项目地址: https://gitcode.com/GitHub_Trending/spl/SPlayer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考