3.0.46

3.0.46 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.45..v3.0.46)

Bug 修复

• 077665d fix(preprobe): judge正缓存盲信补复核,同一把尺子

优化 / 重构 / 依赖

• 9a4e5c9 chore: 删除不完整的MA源码refs/music-assistant-server(18MB)

文档

• e937164 docs: 音频流水线对齐 Music Assistant 实施方案 + MA 参考源码入库

涉及文件与影响面

CHANGELOG.md | 10 +
SPEC.md | 6 +
backend/package.json | 2 +-
backend/src/services/player/QueueController.ts | 21 +-
backend/src/services/player/preProbeScheduler.ts | 15 +-
.../src/services/source/online/streamFallback.ts | 31 ++
backend/tests/player/preProbeScheduler.test.ts | 23 +-
docs/audio-pipeline-plan.md | 482 +++++++++++++++++++++
scripts/pull-240-monitor.sh | 110 +++++
scripts/sendspin-monitor-240.sh | 9 +-
10 files changed, 690 insertions(+), 19 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.46 (Docker Hub 同步: ray5378/musicflow:3.0.46)

升级步骤

• 加载项/容器直接拉取最新镜像重建重启即可;数据自动迁移保留。
• 若依赖上一版本新增索引/缓存,首次启动会自动补齐,无需手工操作。

3.0.45

3.0.45 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.44..v3.0.45)

文档

• 0009286 docs(spec): §1.8 补第三坑(回环 token 注册表跨进程落库) + §2.1 表清单补 raw_stream_tokens

其他

• 0e3a6cb test(sendspin): ffmpeg 输入契约回归锁 —— http 输入必须包回环 token URL(resolveFfmpegInput 抽出可测)

涉及文件与影响面

CHANGELOG.md | 21 +++
SPEC.md | 19 ++-
backend/package.json | 2 +-
backend/src/services/player/preProbeScheduler.ts | 6 +
backend/src/services/plugin/core/preProbe.ts | 10 +-
backend/src/services/sendspin/streamEngine.ts | 23 ++-
backend/tests/player/preProbeScheduler.test.ts | 31 +++-
backend/tests/sendspin/ffmpegInputContract.test.ts | 41 +++++
scripts/sendspin-monitor-240.sh | 175 +++++++++++++++++++++
9 files changed, 308 insertions(+), 20 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.45 (Docker Hub 同步: ray5378/musicflow:3.0.45)

升级步骤

• 加载项/容器直接拉取最新镜像重建重启即可;数据自动迁移保留。
• 若依赖上一版本新增索引/缓存,首次启动会自动补齐,无需手工操作。

3.0.44

3.0.44 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.43..v3.0.44)

Bug 修复

• 4260e0d fix(streaming): raw-stream 回环取流凭证落 SQLite —— 跨进程可见
• 48ad83d fix(streaming): ffmpeg 取流统一走回环 token URL(AirPlay 模式) —— Node 侧处理鉴权/302/优选,Dockerfile 恢复静态 ffmpeg

涉及文件与影响面

CHANGELOG.md | 20 ++++++++++
Dockerfile | 11 ++----
SPEC.md | 23 +++++++++++
backend/package.json | 2 +-
backend/src/db/index.ts | 9 +++++
backend/src/index.ts | 3 +-
backend/src/routes/rest/index.ts | 35 +++++++++++++---
backend/src/services/dlna/control.ts | 57 +++++++++++++++++++++++++++
backend/src/services/sendspin/streamEngine.ts | 14 +++++--
backend/tests/rest/dlnaOggFallback.test.ts | 10 ++++-
backend/tests/services/rawStreamToken.test.ts | 57 +++++++++++++++++++++++++++
11 files changed, 223 insertions(+), 18 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.44 (Docker Hub 同步: ray5378/musicflow:3.0.44)

升级步骤

1. 服务端：docker compose pull && docker compose up -d（HA Add-on 用户点更新后重启）。本次修复无需任何数据操作，直接拉新镜像即可。
2. Web 前端：升级后 Ctrl + Shift + R 强刷一次（清旧缓存）。
3. client 配套版本：与 MusicFlow-client v5.0.15 配套（MusicFlow-v5015-android.apk + MusicFlow-v5015-windows-setup.exe），建议同步升级。
4. 预览面板 / 功能开关：本次无新增预览面板与功能开关。

3.0.43

3.0.43 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.42..v3.0.43)

Bug 修复

• 958ebea fix(docker): runtime 装 musl 系统 ffmpeg 并设 FFMPEG_PATH —— ffmpeg-static(glibc 静态)在 Alpine 下 DNS 全坏,Sendspin/转码/投屏链路带域名直链一律解析失败

其他

• be63964 ci: check-builtins 内置插件清单补齐 13/18 → 18/18(能力/权限白名单同步对齐真相源)

涉及文件与影响面

CHANGELOG.md | 18 ++++++++++++++++++
Dockerfile | 8 +++++++-
backend/package.json | 2 +-
backend/scripts/check-builtins.mts | 25 ++++++++++++++++++-------
4 files changed, 44 insertions(+), 9 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.43 (Docker Hub 同步: ray5378/musicflow:3.0.43)

升级步骤

• 加载项/容器直接拉取最新镜像重建重启即可;数据自动迁移保留。
• 若依赖上一版本新增索引/缓存,首次启动会自动补齐,无需手工操作。

3.0.42

3.0.42 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.41..v3.0.42)

优化 / 重构 / 依赖

• 01eab78 chore: 修正两处名不副实的 CI 文案 + 一处与实现相反的代码注释
• 8c0f196 refactor(daily-recommend): 清掉旧表/旧设置兼容代码(自用项目,不考虑向后兼容)

文档

• 592451f docs: 全仓文档时效性修订(校准数字 / 纠错 / 标注历史快照)

涉及文件与影响面

.github/workflows/ci.yml | 2 +-
AUDIT.md | 2 +
CHANGELOG.md | 30 +++++
CONTRIBUTING.md | 26 +++-
README.md | 16 ++-
SPEC.md | 31 +++--
backend/package.json | 2 +-
backend/scripts/check-builtins.mts | 7 +-
backend/src/db/index.ts | 9 --
backend/src/services/plugin/dailyRecommend.ts | 73 ++---------
docs/API.md | 6 +-
docs/DEVELOPER.md | 118 +++++++++++++++---
docs/PLUGIN_ARCHITECTURE.md | 23 +++-
docs/PLUGIN_DEV.md | 25 ++--
docs/PROCESS_MODEL_AND_ISOLATION_PLAN.md | 134 +++++++++++++--------
docs/SENDSPIN_ESPHOME_FLAC_2026-09-17.md | 2 +
docs/SENDSPIN_MA_ALIGNMENT_AUDIT.md | 2 +
docs/SENDSPIN_MULTIROOM_STREAMING_PLAN.md | 6 +-
docs/SENDSPIN_PITFALLS_2026-09-18.md | 2 +
docs/memory-optimization-plan.md | 7 ++
docs/player-unification-plan.md | 18 +--
docs/sandbox-limits-and-plan.md | 20 +--
docs/sendspin-renderer-handoff-2026-09-13.md | 2 +
.../2026-08-05-dlna-ma-style-player-controller.md | 2 +
.../plans/2026-09-12-sendspin-renderer.md | 2 +
.../specs/2026-09-12-sendspin-renderer-design.md | 2 +
frontend/src/stores/player.ts | 7 +-
27 files changed, 376 insertions(+), 200 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.42 (Docker Hub 同步: ray5378/musicflow:3.0.42)

升级步骤

1. 服务端

• Docker / 容器：docker compose pull && docker compose up -d
• HA 加载项：点「更新」后重启加载项

2. Web 前端

• 浏览器 Ctrl + Shift + R 强刷一次，清掉旧的静态资源与卡片缓存

3. 客户端配套版本

• 本次未改动客户端契约，无需同步升级；当前 client 最新 v5.0.15（Android apk / Windows setup）
  可直接配用。

4. 预览面板 / 功能开关

• 本次无新增预览面板与功能开关。

本版为「清理 + 文档修订」版，无新功能。

• 删除每日推荐里最后的旧设置兼容分支（loadCandidatesFromSettings / 旧歌单认领 / 旧歌单改名，
  以及 daily_recommend_candidates、daily_recommend_retention 两个 settings 种子键）。
  这两个键已无任何代码读取，老库里留存无害、无需清理；候选池现在只由每日推荐插件自己的
  配置承载，PUT /v1/daily-recommend/candidates 的对外行为不变。
• 全仓文档时效性修订：校准硬数字、修正 4 处与实现相反的描述（含 1 处代码注释）、
  给 3 份方案文档回标落地状态、为 8 份历史文档加「⏳ 历史快照」横幅。
• 数据无需迁移：本版不增删任何表结构，也不依赖任何旧字段。

3.0.41

3.0.41 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.40..v3.0.41)

优化 / 重构 / 依赖

• 288be41 refactor: 删除 DB 字段迁移/兼容代码(自用项目,不考虑向后兼容)

涉及文件与影响面

CHANGELOG.md | 20 ++++++
backend/package.json | 2 +-
backend/src/db/index.ts | 19 ------
backend/src/services/sendspin/child.ts | 4 +-
backend/src/services/sendspin/deviceState.test.ts | 80 -----------------------
backend/src/services/sendspin/deviceState.ts | 63 ------------------
backend/src/services/sendspin/index.ts | 5 +-
7 files changed, 23 insertions(+), 170 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.41 (Docker Hub 同步: ray5378/musicflow:3.0.41)

升级步骤

• 加载项/容器直接拉取最新镜像重建重启即可;数据自动迁移保留。
• 若依赖上一版本新增索引/缓存,首次启动会自动补齐,无需手工操作。

3.0.40

3.0.40 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.39..v3.0.40)

文档

• 735ee13 docs: 进程模型规划同步——两项遗留标记完成，移除部署跟踪

其他

• 75b31e9 test(renderer)+feat(airplay): 补 fork 冒烟测试与推流节拍可观测指标;清理部署遗留

涉及文件与影响面

CHANGELOG.md | 30 ++++
backend/package.json | 2 +-
backend/src/services/airplay/control.ts | 13 +-
backend/src/services/airplay/raop.ts | 34 +++++
backend/src/services/airplay/sessionRuntime.ts | 41 +++++-
.../rendererHost/fixtures/stubRendererChild.mjs | 86 +++++++++++
backend/tests/rendererHost/supervisorFork.test.ts | 158 +++++++++++++++++++++
docs/PROCESS_MODEL_AND_ISOLATION_PLAN.md | 71 +++++----
8 files changed, 405 insertions(+), 30 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.40 (Docker Hub 同步: ray5378/musicflow:3.0.40)

升级步骤

• 加载项/容器直接拉取最新镜像重建重启即可;数据自动迁移保留。
• 若依赖上一版本新增索引/缓存,首次启动会自动补齐,无需手工操作。

3.0.39

3.0.39 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.38..v3.0.39)

优化 / 重构 / 依赖

• 95fcece refactor(renderer): 抽出常驻渲染器子进程通用宿主 + AirPlay 接入(默认关闭)

文档

• cd287a5 docs: 新增进程模型与隔离规划（进程边界实测 + P1/P2/P3 路线图）

涉及文件与影响面

.github/workflows/ci.yml | 17 +-
CHANGELOG.md | 65 ++++
backend/package.json | 2 +-
backend/scripts/check-renderer-host.mjs | 181 +++++++++
backend/src/services/airplay/child.ts | 57 +++
backend/src/services/airplay/childMain.ts | 96 +++++
backend/src/services/airplay/control.ts | 411 +++++++++++----------
backend/src/services/airplay/decoder.ts | 185 ++++++++++
backend/src/services/airplay/ipcProtocol.ts | 35 ++
backend/src/services/airplay/mode.ts | 23 ++
backend/src/services/airplay/sessionRuntime.ts | 266 +++++++++++++
backend/src/services/airplay/supervisor.ts | 62 ++++
.../src/services/rendererHost/childBootstrap.ts | 97 +++++
backend/src/services/rendererHost/childHost.ts | 127 +++++++
backend/src/services/rendererHost/front.ts | 44 +++
backend/src/services/rendererHost/index.ts | 26 ++
backend/src/services/rendererHost/ipcProtocol.ts | 73 ++++
backend/src/services/rendererHost/mode.ts | 29 ++
backend/src/services/rendererHost/paths.ts | 20 +
backend/src/services/rendererHost/supervisor.ts | 307 +++++++++++++++
backend/src/services/sendspin/child.ts | 81 ++--
backend/src/services/sendspin/childMain.ts | 120 ++----
backend/src/services/sendspin/ipcProtocol.ts | 87 +++--
backend/src/services/sendspin/mode.ts | 14 +-
backend/src/services/sendspin/proxy.ts | 11 +-
backend/src/services/sendspin/supervisor.ts | 337 ++++-------------
docs/PROCESS_MODEL_AND_ISOLATION_PLAN.md | 309 ++++++++++++++++
27 files changed, 2435 insertions(+), 647 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.39 (Docker Hub 同步: ray5378/musicflow:3.0.39)

升级步骤

• 加载项/容器直接拉取最新镜像重建重启即可;数据自动迁移保留。
• 若依赖上一版本新增索引/缓存,首次启动会自动补齐,无需手工操作。

3.0.38

3.0.38 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.37..v3.0.38)

新功能

• 13b7bd9 feat(groups): ESPHome 密钥独立弹窗 + 四区块统一「扫描」+ AirPlay 主动扫描
• 838b1e7 feat(sendspin): 升级迁移——旧版插件页全局密钥继承为已连接设备的密钥
• ea6828d feat(sendspin): ESPHome 6053 密钥/音量下放到每台设备,移除插件页全局配置
• af9659e feat(sendspin): 统一「解绑」语义——撤销记住但保留设备行
• 27e4bb4 feat(peer): Web 页面上下线语义——关掉即清内存态,重开原样恢复
• a62c17a feat(sendspin): 播放器页 Sendspin 设备行对齐 DLNA 显示语义

优化 / 重构 / 依赖

• b73ac64 perf(sendspin): 流式解码窗口高水位 60→30 秒,与 MA 对齐

涉及文件与影响面

CHANGELOG.md | 56 ++
backend/package.json | 2 +-
backend/src/db/index.ts | 23 +
backend/src/db/schema.ts | 5 +
backend/src/plugins/types.ts | 3 -
backend/src/routes/api/index.ts | 253 +++++-
backend/src/services/airplay/discovery.ts | 55 +-
backend/src/services/peer.ts | 59 +-
backend/src/services/playerPrefs.ts | 16 +
backend/src/services/plugin/renderers/sendspin.ts | 35 +-
backend/src/services/sendspin/child.ts | 12 +-
backend/src/services/sendspin/childMain.ts | 62 +-
backend/src/services/sendspin/deviceState.test.ts | 290 ++++++-
backend/src/services/sendspin/deviceState.ts | 233 +++++-
.../src/services/sendspin/esphomeBridge.test.ts | 124 ++-
backend/src/services/sendspin/esphomeBridge.ts | 281 +++++--
backend/src/services/sendspin/index.ts | 283 +++++--
backend/src/services/sendspin/ipcProtocol.ts | 8 +-
backend/src/services/sendspin/pluginConfig.test.ts | 41 +-
backend/src/services/sendspin/proxy.ts | 8 +-
backend/src/services/sendspin/streamSource.ts | 11 +-
backend/src/services/sendspin/supervisor.ts | 14 -
backend/src/services/ws/index.ts | 33 +-
backend/tests/airplay/rescan.test.ts | 14 +
backend/tests/routes/peerOffline.test.ts | 174 +++++
backend/tests/routes/sendspinEsphomeDevice.test.ts | 280 +++++++
backend/tests/sendspin/dialTargetForget.test.ts | 189 +++++
backend/tests/services/peerLifecycle.test.ts | 143 ++++
docs/SENDSPIN_MULTIROOM_STREAMING_PLAN.md | 22 +-
frontend/e2e/groups-sendspin.spec.ts | 220 ++++++
frontend/src/components/MfIcon.vue | 4 +-
frontend/src/layouts/MainLayout.vue | 10 +
frontend/src/locales/en-US.json | 54 +-
frontend/src/locales/zh-CN.json | 54 +-
frontend/src/stores/player.ts | 31 +
frontend/src/views/Groups/index.vue | 860 +++++++++++++++++++--
frontend/src/views/admin/Plugins/index.vue | 58 +-
37 files changed, 3514 insertions(+), 506 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.38 (Docker Hub 同步: ray5378/musicflow:3.0.38)

升级步骤

• 加载项/容器直接拉取最新镜像重建重启即可;数据自动迁移保留。
• 若依赖上一版本新增索引/缓存,首次启动会自动补齐,无需手工操作。

---

升级步骤（本版专用）

1. 服务端（Docker / HA 加载项）
   • Docker：docker compose pull && docker compose up -d
   • HA 加载项：点「更新」后重启加载项
   • 数据与插件配置自动迁移保留，无需手工操作。
2. Web 前端：升级后按 Ctrl + Shift + R 强刷一次。本版改了播放器页的按钮布局与弹窗结构，
   旧的 JS / 资源缓存会让页面停留在旧样子。
3. 客户端配套版本：client 当前最新为 MusicFlow-client v5.0.15（Android apk + Windows setup），
   建议同步升级。
4. 预览面板 / 功能开关：本次无新增预览面板与功能开关。插件配置页原有
   「流式解码(省内存)」开关保持默认开启 —— 本版只把它的滑动窗口高水位由 60 秒收到 30 秒
   （与 Music Assistant 的 30 秒对齐），内存上限随之从 ~23MB 降到 ~11.5MB。

本版需要你知道的两点变化

• Sendspin 设备行新增独立的「ESPHome 密钥」入口：原来密钥 / 端口 / 测试连接与设备音量滑杆
  挤在同一个弹窗里，现在拆成两个独立弹窗，行内两个按钮各自反映连接状态。
  已填过的密钥与设备音量原样保留，不需要重新填写（密钥明文只对具备播放器管理权限的账号回显）。
• seek 回跳的容错略微变小：窗口由 60 秒收窄到 30 秒后，回跳超出窗口会重建解码（约 1 秒空窗）。
  日常整曲播放无影响，长曲频繁回拖时可能更常听到这一下空窗。

3.0.37

3.0.37 发布说明

变更

由提交历史按类型自动生成:新功能 / Bug 修复 / 优化·重构·依赖 / 文档 / 其他。

变更日志 (v3.0.36..v3.0.37)

新功能

• 4d2ab9b feat(sendspin): 设备音量持久化 + 全端回显
• 039a02d feat(sendspin): 流式解码开关进插件配置页

文档

• 9806747 docs(sendspin): 补解码内存与MA对照结论

涉及文件与影响面

backend/src/db/index.ts | 9 ++
backend/src/db/schema.ts | 11 ++
backend/src/routes/api/index.ts | 37 ++++-
backend/src/services/access.ts | 16 +-
backend/src/services/group/index.ts | 19 ++-
backend/src/services/peer.ts | 12 ++
backend/src/services/plugin/renderers/sendspin.ts | 11 ++
backend/src/services/sendspin/childMain.ts | 5 +
backend/src/services/sendspin/deviceState.test.ts | 54 +++++++
backend/src/services/sendspin/deviceState.ts | 70 +++++++++
backend/src/services/sendspin/index.ts | 43 ++++++
backend/src/services/sendspin/peerVolume.test.ts | 61 ++++++++
backend/src/services/sendspin/peerVolume.ts | 85 +++++++++++
backend/src/services/sendspin/playerCore.ts | 17 ++-
backend/src/services/sendspin/pluginConfig.test.ts | 27 ++++
backend/src/services/sendspin/streamEngine.ts | 32 +++-
backend/src/services/ws/index.ts | 10 ++
backend/tests/sendspin/pumpFallback.test.ts | 8 +
backend/tests/source/resolveRowInput.test.ts | 98 +++++++++++++
docs/SENDSPIN_MULTIROOM_STREAMING_PLAN.md | 20 +++
frontend/src/locales/en-US.json | 3 +
frontend/src/locales/zh-CN.json | 3 +
frontend/src/stores/player.ts | 15 ++
frontend/src/views/Groups/index.vue | 163 +++++++++++++++++++--
24 files changed, 796 insertions(+), 33 deletions(-)

镜像

• ghcr.io/ray5378/musicflow:3.0.37 (Docker Hub 同步: ray5378/musicflow:3.0.37)

升级步骤

• 加载项/容器直接拉取最新镜像重建重启即可;数据自动迁移保留。
• 若依赖上一版本新增索引/缓存,首次启动会自动补齐,无需手工操作。