Files

T

Jocay 676541457b feat: P7 在线播放（播放队列、媒体控制）与自建歌单

- 播放器：统一 PlayItem 队列，顺序 / 列表循环 / 单曲循环 / 随机，滚动歌词含翻译，Media Session，队列与进度存 localStorage
- 在线播放音质可在设置中选择；曲库已有的歌优先播放本地文件
- 自建歌单：混排在线曲目与本地文件，拖动排序，一键下载曲库缺失曲目

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-11 11:31:29 +08:00

5.2 KiB

Raw Blame History

声匣 · Sound Case

自托管的音乐下载 Web 服务：搜索、在线播放、批量下载网易云音乐与 QQ 音乐（VIP Cookie），自动写入歌词、封面与完整标签，按「歌手 / 专辑 / 序号. 歌名」归档，可直接被 Navidrome 等播放器识别。

由 163-music-dl CLI 重构而来，不再保留命令行模式。仅供个人对已购买 / 已订阅内容的备份使用。

功能

搜索：网易云 / QQ 音乐切换；粘贴任意分享链接（歌曲、专辑、歌单、歌手，含 QQ 短链）直接跳转
详情页：专辑、歌单（可筛选）、歌手（热门歌曲 + 专辑墙）；多选 / Shift 区间选 / 只选未下载
下载队列：并发、全局暂停、单曲暂停 / 继续 / 取消 / 重试，SSE 实时进度；重启后自动恢复
音质：标准 / 极高 / 无损 / Hi-Res / 超清母带 / 空间音频 / 高清臻品；不可用时自动降级
- QQ 音乐支持到 Hi-Res（RS01）；母带 / 全景声为加密格式，暂不支持
播放：在线曲目经服务端代理（标准 / 极高 / 无损可选），曲库文件直接播放；曲库里已有的歌优先放本地文件。播放队列、顺序 / 列表循环 / 单曲循环 / 随机、滚动歌词（含翻译）、系统媒体键与锁屏控制、空格暂停；队列与进度保存在本机，刷新后可继续
歌单：自建歌单可混排在线曲目与本地文件；从搜索、专辑、歌单、歌手、曲库文件夹或播放队列一键加入，拖动排序，一键下载曲库里还没有的在线曲目
曲库：浏览音乐目录（封面墙）、生成 M3U、打包 ZIP、移入回收站、批量补全标签与歌词
历史：统计（累计、占用、近 30 天、来源与音质分布）、搜索筛选、导出 CSV / JSON
设置：QQ 账号（扫码登录 / 导入 Cookie、VIP 校验、musickey 自动续期）、下载默认值、并发与间隔、访问密码、浅色 / 深色

本机运行

需要 Node.js ≥ 22.18（服务端直接以 TypeScript 运行，无需编译）。FLAC 写标签需要 ffmpeg（Windows：winget install Gyan.FFmpeg）。

npm install
npm run build        # 打包前端到 dist/web
npm start            # http://localhost:8066

开发模式：npm run dev（后端 :8066 --watch + Vite :5173 热更新，代理 /api）。

默认下载到 ./music、数据在 ./data。QQ 音乐 Cookie 会从 config.json 的 qq.cookieFile（默认 ../cookie.txt）自动导入，文件更新后重启即重新导入；也可在设置页粘贴。

配置

config.json（私有仓库，已包含 chksz apikey），环境变量优先：

环境变量	对应
`PORT` / `HOST`	`server.port`；监听地址默认 `0.0.0.0`
`MUSIC_DIR` / `DATA_DIR`	`paths.*`
`CHKSZ_API_KEY`	`netease.apikey`
`QQ_COOKIE_FILE`	`qq.cookieFile`
`DEFAULT_QUALITY`	`defaults.quality`：standard / high / lossless / hires / master / spatial / effect
`DEFAULT_LAYOUT`	`defaults.layout`：`album`（歌手/专辑/NN. 歌名）或 `flat`（歌手 - 歌名）
`LEGACY_HISTORY_FILE`	旧版 CLI 的 `download_history.json`，首次启动导入

config.json 中的 defaults 只是初始值，网页设置页修改后保存在数据库中。

数据目录内容：shengxia.db（历史、队列、设置、加密后的 Cookie）、secret.key（本机加密密钥，勿外传）、.trash/（曲库回收站）。

标签规则（沿用旧版）

标题、歌手、专辑取自音源；曲序 N/总数、碟号、专辑艺人、合辑标记、发行日期、流派、唱片公司取自平台专辑详情
作词 / 作曲 / 编曲 / 制作人 / 混音从歌词头部解析；编曲、制作人、混音写入 TXXX（MP3）或同名字段（FLAC）
歌词保存为 .lrc，有翻译时额外生成 .合并翻译.lrc，并内嵌到音频
专辑目录写入 cover.jpg；人名统一使用 / 分隔

Docker 部署（NAS）

cd /vol1/1000/dockercompose && git clone https://git.draws.qzz.io/jocay/music-hub.git shengxia && cd shengxia
docker compose up -d --build     # http://NAS:8066

更新：git pull && docker compose up -d --build（以 root 操作 jocay 的仓库时加 git -c safe.directory=$PWD pull）。

挂载与端口见 docker-compose.yml / .env.example；容器以 PUID:PGID（默认 1000:1001）运行
构建时 Alpine 走腾讯云源、npm 走 npmmirror（阿里云 Alpine 源在 NAS 容器内极慢）
运行时 chksz 等境外接口经 OUTBOUND_PROXY（默认 http://192.168.31.8:6152）访问，QQ / 网易云及其 CDN 直连 —— NAS 直连 Cloudflare 会卡 3–15 秒
QQ 音乐：网页「设置 → 扫码登录」，之后 musickey 自动续期

进度

P0 工程骨架、设计 token、Docker 配置
P1 下载核心与网易云 provider
P2 QQ 音乐 provider（VIP Cookie）
P3 下载队列、SSE 实时进度、设置、访问密码、曲库与历史接口
P4 完整前端
P5 QQ 扫码登录与 musickey 自动续期
P6 NAS 部署（飞牛 /vol1/1000/dockercompose/shengxia）
P7 在线播放（播放队列、媒体控制）与自建歌单

5.2 KiB Raw Blame History Unescape Escape

声匣 · Sound Case

功能

本机运行

配置

标签规则（沿用旧版）

Docker 部署（NAS）

进度

5.2 KiB

Raw Blame History