Appearance

发布日志 ​

本文档记录 MusicFree 各版本的变更摘要、升级注意事项与破坏性变更。功能细节请参阅 功能特性 与各功能模块文档。

阅读说明 ​

版本号规则 ​

  • 稳定版：V1.x.y（如 V1.1.5）
  • 预发布版：v1.x.y-alpha.nn（如 v1.2.0-alpha.09），功能可能仍在快速迭代，不建议直接用于生产环境

升级建议 ​

  1. 升级前备份 data/music.db 与配置文件
  2. 关注各版本 升级说明 中的扫描、插件、配置变更
  3. Alpha 版本之间可能包含数据库自动迁移；首次启动后观察日志是否正常
  4. 插件（尤其 mf-plugin-gomusicdl）版本与宿主需匹配，升级后建议在管理端确认插件已更新

Docker 升级示例：

bash
docker pull ansgoo/music-free:latest
docker compose up -d

V1.2.4 ​

发布日期：2026年8月30日

更新特性 ​

从音乐文件夹一键生成歌单 ​

在「歌单」页面，管理员可以指定音乐源和文件夹路径，一键将该文件夹下的歌曲生成为一张歌单（快照式，仅包含该文件夹直属的音乐文件，不递归子文件夹），歌单名默认取文件夹名，也可以手动指定。

非常适合把按照歌手、专辑、语种等整理的目录结构快速固化成歌单，方便后续播放与分享。

folder-playlist.webp

自动清理空专辑与空艺术家 ​

媒体库扫描完成后，会自动清理没有任何有效歌曲的专辑和艺术家，并同步清理关联数据（专辑-艺术家关系、歌曲-艺术家关系、用户收藏、评分等），让你的媒体库保持干净整洁。

专辑列表默认按创建时间倒序 ​

专辑列表的默认排序由名称正序调整为按创建时间倒序，最新入库的专辑排在最前面，更容易发现新添加的音乐。

DLNA 转码播放优化 ​

针对 TCL、海信等电视上 DLNA 渲染器（Vewd 栈）无法正确显示总时长、无法拖动进度条的问题，DLNA 转码改为先写入临时文件，再通过 http.ServeContent 提供流：

  • 返回精确的 Content-Length，并支持 HTTP Range（206）分段请求；
  • ffmpeg 写入完整的 Info/Xing 头，渲染器可以据此正确显示总时长并拖动进度；
  • 优先使用 FLAC STREAMINFO 的精确音频时长，避免元数据时长与实际不符导致 Content-Length 偏高、渲染器反复重拉。

修复 ​

  • 修复了歌单页面音乐源类型显示格式异常
  • 修复了部分 DLNA 设备转码播放时总时长显示为 00:00 的问题

V1.2.3 ​

发布日期：2026年8月17日

更新特性 ​

对Music Assistant 进行了支持 ​

什么是Music Assistant ​

Music Assistant 的核心优势在于打破了音乐生态的壁垒，赋予你对自己音乐库和播放设备的完全控制权。它像一个音乐界的“万能遥控器”或“音乐库管家”，让你能自由地将各种音乐源与各种播放设备组合起来 支持广泛协议：支持 AirPlay、Chromecast、DLNA、Snapcast、MQTT 等多种协议;兼容新老设备：无论是崭新的智能音箱，还是20年前的老式功放，甚至是 DIY 的树莓派播放器，都能成为 Music Assistant 的播放终端

device.webp

为什么选择Music Assistant ​

DLNA 是本项目原生支持的硬件设备，Airplay、Chromecast 等其他设备因为社区对其第三方库的实现有差别，导致本项目无法直接集成，但是通过Music Assistant可以集成任意硬件设备，可通过Music Free直接将单曲、专辑、歌单播放到Music Assistant 的Player。

在设备管理页面可以添加Music Assistant 的Player，并支持将其添加到设备列表中来，设备列表中的设备只有管理添加之后，并授权给某个普通用户，则普通用户可以正常使用该设备进行音乐播放

device.webp

如何使用 ​

  1. 部署Music Assistant,并获取Music Assistant 的访问授权token（一般Music Assistant 是docker Host 网络模式部署，web访问端口为8095）
  2. 打开Music Assistant 设置，添加音乐源，选择 OpenSubsonic Media Server Library插件,并配置Music Free 的地址、用户名、密码(MusicFree 支持所有的Opensubsnoic协议，Music Assistant默认用自己音乐库进行播放，因此你播放到Music Assistant的音乐必须在他的库里有)，等待同步完即可
  3. 打开Music Free 进入「系统配置」页面 配置Music Assistant的访问地址、账号、token，并选择启用Music Assistant
  4. 在设备发现页即可看到Music Assistant 发现的局域网设备

device.webp

DLNA 局域网设备连接异常 ​

如果是Docker 部署的需要将网络模式改为host 才能发现局域网设备，否则无法发现局域网设备，飞牛原生应用不存在这个问题，同时需要在配置项中配置部署的地址，否则发现设备之后，播放音乐会拉不到音乐流

yaml
services:
  music-free:
    image: ansgoo/music-free:V1.2.3
    container_name: music-free
    restart: unless-stopped
    network_mode: host
    volumes:
      - /vol1/docker/music-free:/app/data
      - /vol1/music:/app/music

修复 ​

  • 修复了 Docker 挂载只读音乐库文件夹是服务无限重启的异常
  • 修复了 插件配置项保存的异常
  • 修复了 配置项未更新导致DLNA无法启用的异常

V1.2.2 ​

发布日期：2026年7月26日

更新特性 ​

支持了播放音乐到DLNA设备 ​

适配了 DLNA 协议，支持发现局域网内的音频设备，可将音乐推送到 DLNA 兼容设备上播放。新增「设备管理」页面，可查看在线设备，支持将单曲、专辑、歌单在DLNA设备上进行播放等。

局域网设备只能管理员添加，管理员添加之后可将设备授权给某个普通用户，则普通用户可以正常使用该设备进行音乐播放

补全了 OpenSubsonic 接口规范 ​

补全了 OpenSubsonic 接口规范，新增了 star 收藏相关接口（star / unstar / getStarred 等），并修复了部分查询参数不生效的问题，第三方客户端兼容性更好。

增强了 Navidrome 客户端兼容 ​

新增 api/library、api/user/:id 等接口，api/songs 支持按艺术家过滤，并适配了评分接口，Navidrome 客户端可以正常使用,确保「箭头音乐」、「MusicAsistant」等客户端连接时同步信息失败的异常

增加了服务器版本信息 ​

API 响应中增加了服务器版本信息，方便第三方客户端及后续版本升级识别。

修复 ​

  • 修复了高并发扫描模式下创建多个相同专辑的异常
  • 修复了 subsonic 接口部分查询参数不生效的异常
  • 修复了 navidrome 部分接口不识别部分参数的异常

V1.2.1 ​

发布日期：2026年7月26日

更新特性 ​

增加了日志导出功能 ​

管理员在用户头像的下拉二级面板中可看到一个日志导出的按钮，点击可导出服务端日志，方便问题定位

修复 ​

  • 修复Symfoniym 连接OpenSubSonic协议时，音乐数据同步失败的异常

V1.2.0 ​

发布日期：2026年7月18日

更新特性 ​

音乐播放详情页 ​

新增歌曲播放详情页面,点击播放器的专辑封面跳转详情页，支持查看当前播放曲目的详细信息与专辑/艺术家上下文，提升播放体验。

播放详情页

播放详情页

远程搜索支持乐库音乐 ​

远程搜索插件结果页现已支持同时检索本地乐库，根据检索结果帮助用户决策是否下载。

心愿管理支持批量拒绝 ​

管理后台 心愿管理 新增批量拒绝功能，管理员可一键勾选并拒绝多条待处理心愿，提升处理效率。

艺术家头像优化 ​

插件排序逻辑优化，仅使用支持 GetArtistInfo 的插件匹配艺术家头像，提高头像匹配准确度与响应速度。

其他改进 ​

  • 默认主题色更新为新版视觉规范
  • 专辑卡片无封面占位背景与歌曲卡片风格统一，并随主题色联动
  • 图片接口浏览器缓存时间优化，二次加载更快
  • 页面宽度优化，提升大屏与小屏的显示效果
  • 依赖升级：Go 模块与前端依赖集中更新，提升稳定性

修复 ​

  • 修复并发刮削时 SQLite 锁死问题：优化数据库事务与锁竞争，批量与并发刮削不再因 SQLite busy 中断
  • 修复批量刮削 SQL 变量超限异常：大量文件同时创建刮削任务时不再报 SQL 变量数量错误
  • 修复专辑卡片占位与主题不一致的显示问题

V1.1.9 ​

更新特性 ​

音乐去重：三步向导 ​

管理后台 音乐管理 → 音乐去重 改为清晰的三步流程，降低误操作风险：

  1. 生成指纹 —— 为缺失指纹的曲目批量补算 Chromaprint（已有指纹自动跳过）
  2. 重复检测 —— 按可配置阈值比对全库，输出重复组与相似度分数
  3. 去重 —— 组内手动勾选假删除，或 按规则批量清理（同专辑内保留无损 > 码率 > 时长；跨专辑重复默认全部保留）

音乐去重三步流程

媒体源扫描与指纹：更快、更稳 ​

  • 扫描提速：并发 worker、目录 hash 增量跳过未变更路径；WebDAV 支持部分读取与单次 OpenStream 解析，减少远程 I/O
  • 指纹与扫描解耦：入库扫描不再强绑指纹计算；支持定时补指纹任务与管理端异步全库回填
  • 指纹引擎：内嵌 chromaprint.wasm + ffmpeg/ffprobe，不再依赖系统 fpcalc；WASM 堆内存可配置上限，大文件 / WebDAV 特殊格式拉取与运行时错误恢复更稳健，大幅降低了docker镜像体积
  • 指纹调度：支持任务中断与互斥锁，避免多任务争抢资源

ARM Docker 多架构镜像 ​

CI 构建并推送 amd64 + arm64 双架构镜像，标签与 V1.1.8 一致，ARM NAS / 单板机可直接使用官方镜像。

飞牛 fnOS 原生应用（FPK） ​

新增 飞牛应用中心 可安装的原生 .fpk 包（非 Docker 模板），支持桌面快捷方式启停与向导配置音乐库路径；Release 流水线同时产出 amd64 / arm64 安装包

其他改进 ​

  • WebDAV 媒体源：在开启「允许回写音乐源文件标签」时，清洗 / 刮削 / 元数据编辑可写回远程标签（需 WebDAV PUT 权限）
  • 标签清洗：内置 RULE-03 扩展支持标题前导下划线序号（如 _01.）清理
  • 远程搜索 / 下载：插件选项展示插件图标，远程曲目列表增加加载骨架屏
  • 默认策略：新装默认关闭「回写音频源文件标签」，降低误改 NAS 原文件风险（可在 系统设置 中开启）

升级说明 ​

场景建议操作
自旧版升级且已开启 fingerprint.enabled进入 音乐去重 执行「生成指纹」，或对媒体源全量扫描一次
飞牛用户可选用 Docker 镜像或从 Release 附件安装对应架构 FPK

升级前请备份 data/music.db

其他修复 ​

  • 优化指纹生成任务状态提示与进度展示（支持更细粒度进度）
  • 修正部分管理端路由重定向与守卫逻辑
  • 依赖与构建脚本小幅更新，提升稳定性

V1.1.7 ​

新功能 ​

歌曲许愿 ​

  • 用户可为尚未入库的曲目提交愿望（手动新建，或从外部歌单未匹配条目一键 / 批量许愿）
  • 愿望状态：pending（待处理）、fulfilled（已实现）、rejected（已拒绝）
  • 按归一化键 norm_key（作品名|艺术家|专辑）去重；管理员实现时同键下所有用户的待处理愿望批量闭环
  • 管理员 愿望管理（/admin/wish）：远程搜索、下载入库、拒绝；复用远程音乐搜索能力
  • 外部歌单详情展示当前用户的 wishStatus（none / wished / fulfilled）
  • 说明文档：许愿

歌单增强 ​

  • 公开歌单不可删除，返回明确错误提示
  • 新增未匹配曲目重链（RelinkUnmatchedPlaylistSongs）：库内已有对应歌曲时自动绑定外部歌单行
  • 前端歌单卡片与列表 UI 重构（PlaylistCard 组件）

歌曲清洗功能 ​

歌曲文件的元数据存在各种各样的脏数据，元数据清洗功能在扫描入库的时候会按照特定规则对歌曲文本进行清洗

修复 ​

  1. 修复了--gap-smCSS 变量丢失导致部分样式异常
  2. 修复了暗黑模式下，message消息看不清的样式异常
  3. 修复特定情况下播放器播放会有重音的问题
  4. 重构了歌单列表视图