go-musicfox v5.0.0 发布：新增主题系统、桌面歌词、频谱可视化等多项更新

go-musicfox v5.0.0 于 2026 年 7 月 31 日正式发布。v5.0.0 包含 87 个 commit，从 v4.8.5 起历时三个多月，是 go-musicfox 历史上更新量最大的版本。本文将逐一介绍 v5.0.0 的主要改动和功能亮点。

启动页升级

启动页从简单的进度条升级为可配置的动画系统，内置 8 种动画：

动画	配置值	说明
Sequence	`sequence`（默认）	渐显 → 彩虹色扫描 → glitch 过渡 → 稳定 logo
Fade-in	`fade-in`	抖动模拟的渐显效果
Rainbow-wave	`rainbow-wave`	彩虹色波扫过 logo
Spinner	`spinner`	Logo + 旋转动画器
Slide-in	`slide-in`	EaseOutElastic 弹性滑入
Glitch	`glitch`	字符损坏 + RGB 颜色分离
Matrix-rain	`matrix-rain`	《黑客帝国》风格绿色字符雨
Particle-burst	`particle-burst`	粒子从四周汇聚成 logo

loadingSeconds 配置精确控制启动页持续时间，不再受初始化耗时影响。

[startup]
enable = true
loadingSeconds = 2
animation = "sequence"
progressOutBounce = true
reducedMotion = false
signIn = true
checkUpdate = true

macOS 桌面歌词 + 频谱显示

桌面歌词

macOS 桌面歌词在 v5.0.0 中基于原生 NSWindow 重写：borderless 浮动窗口，支持所有 Spaces、始终置顶。

YRC 逐字高亮：基于 NSMutableAttributedString 的逐字渐亮效果，与音频时间同步
超长歌词水平滚动：带初始延迟和末尾停顿
拖拽定位：鼠标拖拽移动窗口，位置按屏幕百分比因子保存到 BoltDB
单行/双行模式：oneLineMode 切换一行或两行显示
暂停隐藏：hideOnPause 暂停时自动隐藏

[main.lyric.desktopLyrics]
enable = true
fontSize = 24.0
textColor = "#FFFFFF"
backgroundColor = "#000000"
backgroundAlpha = 0.6
cornerRadius = 12.0
windowAlpha = 0.9
oneLineMode = false
hideOnPause = false
draggable = true
maxWindowWidth = 0.7

桌面频谱

桌面歌词窗口内嵌入频谱可视化，与音频实时同步，支持 11 种样式：

bar（柱状）、mirror（镜像）、capsule（胶囊）
dot（圆点）、fire（火焰渐变色）、led（复古 LED）
circular（圆形）、line（曲线）、waveform（波形）
ring_arc（环弧）、ripple（涟漪圈）

低频到高频的颜色渐变可配，刷新率 30fps。

spectrumEnabled = true
spectrumHeight = 60
spectrumBarCount = 64
spectrumFPS = 30
spectrumStyle = "bar"
spectrumColorLow = "#00FF00"
spectrumColorHigh = "#FF0000"

终端 TUI 频谱显示

终端内实时音频频谱可视化，支持多种渲染风格和高度配置。

频谱分析引擎

1024 点 FFT，汉宁窗处理，64 频段输出
临界阻尼弹簧（harmonica）平滑每个频段
EMA 加权平均，支持自定义帧叠加
Monstercat / Waves 后处理（cava 风格平滑）
可选对数刻度
立体声双通道，支持独立 L/R 或 mono 合并模式

渲染风格

样式	说明
`bar`（默认）	横向进度条，6 种方向（bottom/top/left/right/horizontal/vertical）
`line`	点阵盲文连曲线，支持 braille/block 双模式
`mirror_bar`	镜像柱状，独立 L/R 通道
`dot`	点阵盲文散点图
`oscilloscope`	时域原始波形（示波器）
`vectorscope`	L×R 李萨如散点图
`spectrogram`	频谱图热力显示

颜色配置

水平色渐变（主题色 start → end）
垂直渐变（顶部偏暗、底部明亮）
水平每行独立颜色插值
相位差可视化（spectrumPhaseDiff）：左右声道相位不同步时向橙色偏移

[main.visualizer]
enable = false
maxHeight = 0
style = "bar"
channelMode = "dual"
barOrientation = "bottom"
barVerticalGradient = false
barHorizontalGradient = false
showIdleBarHeads = true
monstercat = 0.0
spectrumAverage = 1
spectrumLogScale = false
spectrumPhaseDiff = false

注意：终端频谱目前仅支持 macOS osx 和 beep 播放引擎（通过 MTAudioProcessingTap 或内置 PCM 流水线获取音频数据）。mpv、mpd、dlna 引擎暂不支持。

Lipgloss 布局体系集成

底层 TUI 框架 foxful-cli 升级至 v1.0.1+，全面集成 lipgloss 布局引擎。

Markdown 弹窗

帮助页、更新日志以 Markdown 格式渲染，可滚动、可缩放，支持 Center/Top/Bottom/Left/Right 锚点定位，宽高按终端比例自适应。

通知栏（Toast）

终端内原生 toast 通知，4 种级别：Info（蓝）、Success（绿）、Warning（黄）、Error（红），支持操作按钮，自动消失时长可配（inAppTimeout）。

Tab 组件

登录页使用 Tab 切换手机号 / 二维码 / Cookie 登录方式，支持鼠标点击和键盘导航。

状态栏

面包屑导航路径 + 时间显示，终端过窄时渐进隐藏时间→中间模块。

鼠标支持

全面支持 bubbletea 鼠标事件，覆盖 click、wheel、motion 三种类型。

左键点击：

播放模式图标 → 切换播放模式
播放状态指示器 → 播放/暂停
喜欢按钮 → 切换喜欢/取消喜欢
歌曲名 → 弹出歌曲操作菜单
歌手名 → 跳转到歌手详情页
进度条 → 按点击位置 seek 跳转

滚轮：

菜单区：滚动列表
非菜单区：调节音量
Ctrl + 滚轮：细粒度音量调节（步长由 mouseVolumeStep 配置）

鼠标移动：

播放栏元素 hover（模式/状态/喜欢/歌曲名/歌手名）→ 切换指针
进度条、返回按钮、Tab、输入框 hover → 切换指针

其他：

中键返回上一级
侧键翻页
桌面歌词窗口拖拽移动

通知系统

双通道架构：TUI 内 toast + 桌面系统通知。

notify.Notify(NotifyContent{...})
    ├── TUI toast → UI 组件渲染
    └── 桌面通知 → macOS / Linux D-Bus / Windows

覆盖场景：点赞/取消点赞、下载歌曲、收藏/取消收藏、添加到播放列表、自动签到、更新检测等。

桌面通知支持专辑封面图片和点击跳转 URL。macOS 使用内置 musicfox-notifier.app，Linux 通过 D-Bus，Windows 使用 beeep。

[main.notification]
enable = true
inApp = true
inAppTimeout = 4
albumCover = true

右键菜单

基于 foxful-cli ContextMenu 的右键上下文菜单系统。

┌─ 当前选中项操作 ──────────────┐
│  ▲ 所属专辑                    │
│  ▲ 所属歌手                    │
│  ▲ 收藏/取消收藏               │
│  ▲ 下载 / 添加到播放列表       │
│  ────────────────────────────  │
│  ▶ 当前播放                    │
│  ▶ 相似歌曲 / 相似歌单         │
│  ▶ 在网页中打开                │
│  ────────────────────────────  │
│  ♪ 播放控制（播放/暂停/切歌）  │
│  ────────────────────────────  │
│  ↻ 刷新当前列表                │
│  ⚙ 切换主题                    │
└─────────────────────────────────┘

菜单按页面类型（歌曲/歌单/专辑/歌手）动态构建，使用 Nerd Font 图标，分隔线和分组标题区分不同操作区域。

主题系统

内置主题

6 种内置主题，每个主题包含深色/浅色双变体：

主题	Dark Primary	风格
Default	`#EA403F`	网易云经典红色
Gruvbox	`#d79921`	复古温暖色系
GitHub	`#58a6ff`	GitHub 官方配色
Dracula	`#bd93f9`	Dracula 紫色
Nord	`#88c0d0`	北极冰蓝风格
Transparent	`#EA403F`	透明背景

深色/浅色自动切换

跟随 macOS 系统外观自动切换亮/暗变体，切换时保持当前主题不变。

自定义主题

用户在 themes/ 目录下放置 TOML 文件，同名主题覆盖内置版本。所有颜色均可配置：调色板、菜单标题、选中项、进度条、弹窗、通知、状态栏、歌词颜色、频谱颜色、右键菜单背景等。支持十六进制颜色、ANSI 颜色名、random（每次随机生成）。

运行时切换

快捷键 switchTheme 键位绑定
右键菜单「切换主题」菜单项

[theme]
activeTheme = "Default"

更新日志弹窗

首次启动新版本时自动弹出 Markdown 格式的更新日志。版本号通过 BoltDB 记录，仅在增量更新时弹出。

弹窗尺寸按终端自适应（宽度 70%，高度 80%），延迟 1.5 秒弹出以确保启动页完成。

配置升级与迁移

v5.0.0 在配置管理方面有两项重要变化：

musicfox upgrade-config 命令：解析用户配置和内置默认配置，递归比较 TOML 键，按字母序追加缺失键到对应 section，保留用户已有的所有配置值、注释和文件权限。使用 pelletier/go-toml/v2 做无损编辑。

移除 INI 配置支持：v4.x 时代的 musicfox migrate（INI→TOML）命令在 v5.0.0 中已被移除。如果当前配置文件仍为 INI 格式，需要先通过 v4.x 版本完成迁移，再升级到 v5。

# 升级到 v5 后执行
go-musicfox upgrade-config

云盘歌词自动回退

对于网易云音乐云盘中的未匹配歌曲，自动尝试从云盘接口获取嵌入的 LRC 标签：

检测歌曲是否为云盘未匹配状态（UnMatched 标记）
调用 /api/cloud/lyric/get 获取云盘内嵌歌词
获取成功则返回，失败则回退到常规歌词接口

使用 singleflight 合并相同歌曲 + 相同用户的并发请求，歌词缓存键包含 cloudUserID 实现多账号隔离。

底层框架升级

v5.0.0 将三个核心依赖同时升级到了 v2：

Bubble Tea → v2.0.7
Bubbles → v2.1.0
Lipgloss → v2.0.4

底层 TUI 框架 foxful-cli 从 v1.0.1 迭代至 v1.0.5，主题系统、弹窗组件、状态栏、右键菜单等功能均依托于它。

其他修复包括：MPRIS Seek/SetPosition D-Bus 方法支持、Windows MPV 改用 named-pipe IPC、macOS SIGTRAP 崩溃修复、beep 引擎频谱支持等。

许可证变更

v5.0.0 的许可证从 MIT 切换为 GPL-3.0。变更原因是项目间接依赖了 GPL 协议的库（通过 beep 引擎），MIT + GPL 的静态链接组合在法律上需要统一为 GPL。

安装与升级

# macOS
brew install go-musicfox

# 从旧版升级后，先同步配置
go-musicfox upgrade-config

更多信息见 GitHub Release。