SwingMusic 3.0.0 介绍与选型指南

目标：本文面向「自建本地音乐流媒体服务」的选型读者，介绍 SwingMusic 3.0.0 的定位、架构、功能特性与同类横向对比，并给出一套五步实测的最小可用验证闭环。软件信息以官方仓库 swingmx/swingmusic 为源（2026-10-30 联网实查并标注来源）；功能验证在 Ubuntu 24.04 服务器（服务端口 8154，曲库 4 首测试音频、2 张专辑、2 位艺术家）实测通过。

一、环境信息

• 操作系统：Ubuntu 24.04（x86_64）
• SwingMusic：v3.0.0（官方最新稳定版，swingmusic --version 实测输出 swingmusic v3.0.0）
• 服务端口：8154（进程内监听 1970，对外经 8154 访问）
• 曲库：/music 下 4 首 mp3（2 张专辑：Tidal Lines、晨雾专辑；2 位艺术家：Blue Harbor、秋日山道）
• 客户端工具：curl 8.x + python3（JSON 解析）
• 演示账号：admin / q1w2e3r4
• 信息溯源：GitHub 仓库 swingmx/swingmusic，2026-10-30 实查——2083 stars、AGPL-3.0 许可、主要语言 Python、最新稳定版 v3.0.0（2026-06-12 发布，v2.1.10 为预发布）

二、软件概述

SwingMusic（官方名 Swing Music）是一款开源（AGPL-3.0）的本地音乐流媒体服务器，使用 Python 编写：把服务器磁盘上的音频目录变成一个带 Web 界面与 REST API 的流媒体站点。首次启动时通过初始化向导创建管理员、选择音乐目录并扫描入库，之后即可用浏览器或官方移动 App 播放、检索、收藏与创建播放列表。

项目由 swingmx 组织维护，源码与发布均托管在 GitHub（https://github.com/swingmx/swingmusic）。版本节奏与 v3.0.0 主要变化（官方 Releases 说明，2026-10-30 实查）：

• 部署形态改进：新增一键安装脚本 curl -fsSL https://setup.swingmx.com | bash，官方发布 ghcr.io/swingmx/swingmusic 镜像（服务端口 1970），部署门槛显著降低；
• Mixes 转为 Premium：按听歌行为生成混音推荐的功能需要 licenseKey 激活（免费版其余功能完整）；
• 自然排序与冠词感知排序：曲名 02-xxx 按数字而非字典序排列；艺术家 The/A 等冠词开头时按主名排序（artistArticleAwareSorting）；
• Blurhash：专辑封面加载前先显示占位色块，弱网浏览体验更顺滑。

与同类的关键差异一句话：SwingMusic 把「按文件夹管理本地曲库」做成了一等公民（文件夹视图 + 多值艺术家拆分 + 专辑标题清洗），并自带官方移动 App 配对；它不兼容 Subsonic 协议，第三方客户端生态不如 Navidrome，细节见第七章对比。

💡 技术拓展：自托管音乐服务器的「第三方客户端协议」不止一种，选型前值得分清——

协议	说明	适用场景
Subsonic / Airsonic API	最普及的自建音乐协议，海量第三方客户端（Symfonium、DSub、play:Sub…）	重视移动客户端生态
Ampache API	老牌协议，部分客户端同时兼容 Subsonic	Ampache 系存量用户
厂商自有 API + 官方 App	服务端定义 REST 契约，官方移动 App 与 Web 端按契约对接	想要开箱即用、不折腾客户端

SwingMusic 属第三类：实测其 OpenAPI 规范（/docs/openapi.json，95 个操作）中无任何 subsonic 路径，移动端走官方 App 的配对码登录（/auth/getpaircode + /auth/pair）。若你的核心诉求是「用 Symfonium 等第三方 App 连接」，应优先看 Navidrome。

三、核心架构

SwingMusic 是典型的单体分层架构（归纳自 v3.0.0 源码结构与运行时实测）：

• 接入层：Flask 应用（flask_openapi3 提供带 OpenAPI 注解的路由）+ granian WSGI 服务器承载 HTTP；全站路由经 JWT 中间件鉴权（Web 静态资源与登录端点豁免）。
• 数据层：双 SQLite 库——swingmusic.db 存曲库元数据（专辑/艺术家/曲目/文件夹），userdata.db 存用户数据（账号、收藏、播放列表、插件配置）；曲库元数据启动时加载进内存 Store（AlbumStore/ArtistStore/TrackStore），检索与列表接口直接打内存，延迟极低。
• 扫描器：遍历 rootDirs → 抽取 ID3 元数据 → 生成专辑封面与艺术家图片（webp）与 Blurhash → 写入 SQLite 并刷新内存 Store；支持手动触发、周期扫描与文件看门狗三种节奏。
• 媒体层：音频文件按需直出（HTTP Range 支持）或经 ffmpeg 转码（quality 支持 original/1411/1024/512/320/256/128/96，容器 mp3/aac/flac/webm/ogg）。
• 客户端：Vue 3 PWA，静态资源随服务端分发，浏览器可「安装为应用」离线壳运行。

💡 技术拓展：流媒体服务的「音频转码策略」常见三种——原文件直出（零 CPU 开销，带宽/客户端解码器需支持格式）、按码率梯级转码（128k/320k 等，节省带宽）、统一转码为通用容器（兼容性最好，CPU 开销最大）。SwingMusic 采用「默认原文件直出 + 请求参数指定码率/容器时按需转码」的混合策略，实测播放接口 quality=original 直接返回原文件（见第五章第 5 步），无需常驻转码进程。

四、功能特性

以下特性均在本机 3.0.0 实例上实测可操作（对应 API 证据见《SwingMusic 3.0.0 API 使用详解》）：

• 三种曲库视图：专辑、艺术家、文件夹并列；文件夹视图按磁盘目录逐层浏览（实测 POST /folder 返回 /music 下 2 个艺术家目录及曲目计数）。
• 多值艺术家与标题清洗：artistSeparators（默认 / 与 ;）拆分合作艺术家，artistSplitIgnoreList 内置 70 余个不应拆分的组合名（如 Simon & Garfunkel）；cleanAlbumTitle 自动剥除专辑名的 (Deluxe Edition) 等尾巴。
• 全局检索：/search/top 返回 top_result 与分类结果（实测中文关键词「晨雾」命中专辑，评分 60.87），/search/ 按 tracks/albums/artists 分类 loadmore。
• 播放与转码：实测 GET /file/<trackhash>/legacy 返回 content-type: audio/mpeg、accept-ranges: bytes，Range 请求返回 206。
• 收藏与播放列表：收藏按曲目/专辑/艺术家三类；播放列表支持封面、置顶（实测创建「深夜电台」列表成功）。
• 插件体系：Last.fm scrobble（内置 apiKey/secret 与会话键）、歌词插件（trustCloudLyrics 控制是否信任云端歌词）、Mixes（Premium）。
• 多用户：管理员可创建多个 profile，usersOnLogin 控制登录页是否显示用户列表；移动 App 用配对码登录。
• 扫描节奏：enablePeriodicScans + scanInterval（默认 10 分钟）周期扫描，enableWatchdog 文件变更看门狗，手动触发为 GET /notsettings/trigger-scan。

五、快速开始（最小可用示例）

SwingMusic 的主流部署形态有两种：官方一键安装脚本（curl -fsSL https://setup.swingmx.com | bash，适合有 systemd 的 Linux 真机）与官方镜像编排部署（完整 0→1 步骤、曲库挂载与初始化向导实录见《SwingMusic 3.0.0 Docker Compose 部署指南》）。无论哪种形态，部署完成后的「5 分钟可用性验证闭环」相同，本节给出一套全部实测过的最小验证序列，读者部署完任一形态后照跑即可确认服务健康。

第 1 步：确认服务在线（首页应返回 200 且标题正确）：

curl -s -o /dev/null -w 'GET / -> %{http_code}\n' http://localhost:8154/
curl -s http://localhost:8154/ | grep -oE '<title>[^<]*</title>'

实测输出：

GET / -> 200
<title>Swing Music</title>

第 2 步：用演示账号登录拿令牌（未登录访问业务 API 会得到 401）：

curl -s -X POST http://localhost:8154/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' -c /tmp/sm-ck.txt | head -c 120; echo

实测输出（节选）：

{"accesstoken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTc5MzMyMjQ1Niwi...

第 3 步：确认曲库已被扫描入库（按标题排序列出专辑）：

curl -s -b /tmp/sm-ck.txt 'http://localhost:8154/getall/albums?start=0&sortby=title&reverse=0' \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print('total:', d['total'], '| albums:', [i['title'] for i in d['items']])"

实测输出：

total: 2 | albums: ['Tidal Lines', '晨雾专辑']

第 4 步：确认检索可用（中文关键词命中专辑）：

curl -s -b /tmp/sm-ck.txt 'http://localhost:8154/search/top?q=%E6%99%A8%E9%9B%BE' \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print('top:', d['top_result']['title'], '| score:', round(d['top_result']['_score'],2))"

实测输出：

top: 晨雾专辑 | score: 60.87

第 5 步：确认能按 Range 拉到音频流（拖动播放的基础）：

curl -s -b /tmp/sm-ck.txt -r 0-99 -o /dev/null \
  -w 'media -> %{http_code} type=%{content_type} got=%{size_download}B\n' \
  'http://localhost:8154/file/569f8c16c6488fad/legacy?filepath=%2Fmusic%2F%E7%A7%8B%E6%97%A5%E5%B1%B1%E9%81%93%2F%E6%99%A8%E9%9B%BE%E4%B8%93%E8%BE%91%2F01-%E6%99%A8%E9%9B%BE.mp3&quality=original&container=mp3'

实测输出：

media -> 206 type=audio/mpeg got=100B

五步全绿即最小可用：浏览器打开 http://<服务器IP>:8154 即可登录听歌。曲库目录规划、初始化向导与运维命令见 B2 部署指南，配置文件逐项说明见《SwingMusic 3.0.0 配置参数详解》。

六、适用场景与限制

适用场景（实测归纳）：

• 个人/家庭局域网音乐库：本地磁盘已有成体系目录结构（艺术家/专辑/曲目），想原样搬进 Web 与手机——文件夹视图直接映射磁盘目录，不会重组你的文件；
• 精致视觉体验需求：封面 Blurhash、主题色提取、自然排序，浏览器可直接 PWA 安装；
• 多人共用一台小服务器：多用户 + 收藏/播放列表互相隔离（userdata.db），Python + SQLite 的资源占用适合小内存机器。

限制（选型前必须知晓）：

• 不兼容 Subsonic 协议（实测 openapi.json 无 subsonic 路径）：移动端只能用官方 App，第三方客户端生态弱于 Navidrome（详见第七章）；
• Mixes 为 Premium：需购买 licenseKey（40 字符，每许可最多 3 台设备，实测状态接口 GET /notsettings/license/status），免费版无此功能；
• 单实例 SQLite：无集群/多节点形态，曲库元数据与用户数据都在本机双库文件中，超大曲库（数十万曲目级）与高并发场景需自行评估；
• 转码依赖 ffmpeg：按需转码功能要求服务器具备 ffmpeg（原文件直出播放则不需要）；
• 中文路径正常但封面内嵌依赖文件本身：测试曲库的中文艺术家/专辑目录扫描与检索全部正常，封面从音频内嵌图提取，无内嵌图时无封面。

七、同类选型对比

以下四款均为本平台已实测开发过完整文档体系的自托管音乐服务器（点击篇名可跳转对应介绍篇）：

选型建议（「如果……则……」）：

• 如果要用 Symfonium/DSub 等现成第三方 App、或家里已有 Subsonic 生态 → Navidrome（《Navidrome 0.64.2 介绍与选型指南》）；
• 如果要极低内存占用、一台 512MB 小机器只跑音乐服务 → Navidrome 或 mStream（《mStream 6.32.0 介绍与选型指南》）；
• 如果看重 Web 界面质感与个人音乐空间的交互细节 → koel（《koel 9.15.0 介绍与选型指南》）；
• 如果曲库按文件夹严整组织、想要文件夹即视图 + 内置转码 + 官方移动 App 的开箱体验，且能接受官方 App → SwingMusic（本文主角，部署见《SwingMusic 3.0.0 Docker Compose 部署指南》）。

💡 说明：四者的安装部署、配置详解与 API 面各有专篇（Navidrome/mStream/koel 各 4 篇见其专栏），对比表中「额外能力」仅列实测差异点，逐项功能以各自专栏文档为准。

八、参考链接

1. 官方仓库：https://github.com/swingmx/swingmusic （2026-10-30 实查：AGPL-3.0、v3.0.0 2026-06-12、2083 stars）
2. 发布页：https://github.com/swingmx/swingmusic/releases
3. 一键安装脚本：https://setup.swingmx.com （v3.0.0 起官方推荐 curl -fsSL https://setup.swingmx.com | bash）
4. 官方镜像：https://ghcr.io/swingmx/swingmusic （服务端口 1970）
5. 站内同类专栏：《Navidrome 0.64.2 介绍与选型指南》、《mStream 6.32.0 介绍与选型指南》、《koel 9.15.0 介绍与选型指南》