From ef61c458e65c3d1dd0e57fe5012c59a53a2848f1 Mon Sep 17 00:00:00 2001
From: Ryan Yin <xiaoyin_c@qq.com>
Date: Fri, 2 Oct 2026 14:39:19 +0800
Subject: [PATCH] chore(go-musicfox): declare config.toml and reset it on
 rebuild

Manage ~/.config/go-musicfox/config.toml declaratively: the upstream default plus the mpv engine, ~/Music download dir, 2 GiB cache and cover art.

The app rewrites the file with a temp file plus rename, which would replace a plain symlink, so use force = true like fcitx5's profile: the repo copy is restored on every rebuild and runtime edits are ephemeral. Runtime data and state stay on the persistent volume.
---
 home/linux/gui/base/go-musicfox/config.toml | 457 ++++++++++++++++++++
 home/linux/gui/base/go-musicfox/default.nix |  12 +
 hosts/idols-ai/preservation.nix             |   6 +-
 3 files changed, 474 insertions(+), 1 deletion(-)
 create mode 100644 home/linux/gui/base/go-musicfox/config.toml
 create mode 100644 home/linux/gui/base/go-musicfox/default.nix

diff --git a/home/linux/gui/base/go-musicfox/config.toml b/home/linux/gui/base/go-musicfox/config.toml
new file mode 100644
index 00000000..3dbcb2e1
--- /dev/null
+++ b/home/linux/gui/base/go-musicfox/config.toml
@@ -0,0 +1,457 @@
+# ---------------------------------------------------------------- #
+#                  Go-Musicfox Configuration File                  #
+# ---------------------------------------------------------------- #
+# 本文件使用TOML格式。详细语法请参考: https://toml.io/             #
+# ---------------------------------------------------------------- #
+
+# 启动页相关配置
+[startup]
+# 是否显示启动页
+enable = true
+# 启动页进度条是否具有回弹效果
+progressOutBounce = true
+# 启动页的持续时长（秒）
+loadingSeconds = 2
+# 启动页欢迎语
+welcome = "musicfox"
+# 启动页动画：sequence、fade-in、rainbow-wave、typewriter、spinner、slide-in、glitch、matrix-rain、particle-burst
+animation = "sequence"
+# 是否停用启动页动画以减少动态效果
+reducedMotion = false
+# 启动时是否自动签到 (网易云有风控，建议关闭)
+signIn = false
+# 启动时是否检查应用更新
+checkUpdate = false
+
+
+# 主界面与核心功能配置
+[main]
+# altScreen 显示模式
+altScreen = true
+# 是否在界面中启用鼠标事件
+enableMouseEvent = true
+# 是否开启 Debug 模式
+debug = false
+# 播放时 UI 刷新帧率（更高帧率可使动画更平滑，但消耗更多cpu）
+frameRate = 10
+# 界面语言（影响 foxful-cli 内置文案，如帮助提示、弹窗按钮）
+# 可选："zh"（中文，默认）、"en"（英文）等；留空跟随中文
+locale = "zh"
+
+# 实时频谱显示（目前仅支持 osx, beep 播放引擎）
+# 调高 main.frameRate 更丝滑
+[main.visualizer]
+# 是否显示实时频谱
+enable = false
+# 频谱最大行数（0 表示不限制；会随可用空间自动缩小）
+maxHeight = 8
+# 频谱渲染样式：bar(柱状图), line(折线图), mirror_bar(镜像柱状图), dot(散点图),
+#   oscilloscope(示波器), vectorscope(向量示波器), spectrogram(滚动频谱图)
+style = "oscilloscope"
+# 声道模式：dual(左右声道分开显示，默认) / mono(左右声道合并显示)
+channelMode = "mono"
+
+# bar / mirror_bar 样式字符（仅使用首个 Unicode 字符）
+barHalfBlock = "▌"
+barFullBlock = "█"
+barEmptyBlock = " "
+barVerticalGradient = false
+# 启用条间水平渐变（每条独立颜色，默认false）
+barHorizontalGradient = false
+# 无声时显示微小顶部标记（cava 风格 idle bar heads）
+showIdleBarHeads = false
+# 条生长方向：bottom(从下往上，默认) / top / left / right / horizontal / vertical
+barOrientation = "bottom"
+
+# mirror_bar 样式字符（留空则沿用 bar 对应项）
+mirrorBarHalfBlock = "▌"
+mirrorBarFullBlock = "█"
+mirrorBarEmptyBlock = ""
+
+# line 样式：braille(盲文，细腻) / block(块字符，醒目)
+lineMode = "braille"
+# 波段交叉点：满格
+lineFullBlock = "•"
+# 插值线段：下半角，纵向填充分层
+lineHalfBlock = "•"
+lineEmptyBlock = "•"
+
+# dot 样式：braille(盲文，细腻) / block(块字符，醒目)
+dotMode = "braille"
+dotFullBlock = "•"
+dotHalfBlock = "•"
+dotEmptyBlock = " "
+
+# oscilloscope 示波器样式：braille(盲文，细腻) / block(块字符，醒目)
+oscilloscopeMode = "braille"
+oscilloscopeScatter = false
+oscilloscopeFullBlock = "█"
+oscilloscopeHalfBlock = "▌"
+oscilloscopeEmptyBlock = " "
+
+# vectorscope 向量示波器样式：braille(盲文，细腻) / block(块字符，醒目)
+vectorscopeMode = "braille"
+vectorscopeFullBlock = "•"
+vectorscopeHalfBlock = "•"
+vectorscopeEmptyBlock = " "
+
+# spectrogram 滚动频谱图设置
+# 滚动速度（1=慢, 10=快，默认4）
+spectrogramSpeed = 4
+
+# FFT 频谱增强（对 line/dot 等频谱样式生效）
+# FFT 帧平均数量（1 表示不平滑，越大越平滑但响应越慢）
+spectrumAverage = 1
+# 纵轴刻度：true=对数(dB，默认) / false=线性(原始振幅)
+spectrumLogScale = true
+# 叠加显示左右声道相位相关性（仅 dual 声道模式生效）
+spectrumPhaseDiff = false
+
+# cava 风格后处理平滑（对 bar/mirror_bar 样式生效）
+# monstercat 指数扩散平滑（0=关，>0=启用，典型值1.0-3.0，值越小条越融合）
+monstercat = 0
+# waves 二次扩散模式（与monstercat互斥，0=关，1=开）
+waves = false
+# 视觉超调百分比（0=关，典型值10-30）
+overshoot = 0
+
+
+# 桌面通知相关设置
+[main.notification]
+# 是否启用桌面通知
+enable = true
+# (Windows/Linux) 默认通知图标
+icon = "logo.png"
+# (Windows/Linux) 是否使用歌曲的专辑封面作为通知图标（如为否则使用默认通知图标）
+albumCover = false
+# 是否在 TUI 内显示原生 toast 通知（点赞、下载、订阅、签到等瞬时事件）
+# 独立于桌面通知开关，可与桌面通知同时启用
+inApp = true
+# TUI 内 toast 自动消失时长（秒，0 使用默认 4 秒）
+inAppTimeout = 4
+
+# 歌词显示相关设置
+[main.lyric]
+# 是否显示歌词
+show = true
+# 是否显示翻译歌词
+showTranslation = true
+# 歌词显示时间的全局偏移量（毫秒），正值表示歌词提前显示
+offset = 0
+# 忽略歌词解析错误
+skipParseErr = false
+# YRC 歌词渲染模式（仅对逐字歌词有效）
+# 可选: "simple"(简单，默认), "smooth"(平滑), "wave"(波浪), "glow"(发光)
+renderMode = "smooth"
+
+# 封面图显示设置（需要支持Kitty图形协议的终端，如Kitty、WezTerm、Ghostty等）
+[main.lyric.cover]
+# 是否显示封面图
+show = true
+# 封面图宽度占窗口宽度的比例（取值范围 0.1-0.8，默认 0.3）
+widthRatio = 0.1
+# 封面图圆角半径百分比（取值范围 0-100，默认 8 即 8%，0 则关闭，越大越圆）
+cornerRadius = 8
+# 是否启用旋转封面（需要更高的帧率支持平滑效果）
+spin = false
+# Kitty图形协议不支持角度变化目前只能以动画呈现，合成动画需要更高的CPU性能
+# 旋转封面帧率（取值范围 1-60，默认 30，更高帧率更流畅但消耗更多CPU）
+spinFPS = 30
+# 旋转一圈的时长（秒，取值范围 1-30，默认 6）
+# 时长和帧率挂钩：60fps*6s=360帧，30fps*6s=180帧，30fps*12s=360帧
+spinDuration = 6
+
+# 桌面歌词设置（目前仅支持 macOS）
+[main.lyric.desktopLyrics]
+# 是否启用桌面歌词
+enable = false
+# X 位置系数（0.0-1.0，0.5 表示居中，0.0 最左，1.0 最右）
+xPositionFactor = 0.5
+# Y 位置系数（0.0-1.0，0.0 底部，1.0 顶部，默认 0.5 居中）
+yPositionFactor = 0.5
+# 字体大小（默认 24 匹配系统标签字体）
+fontSize = 24
+# 字体名称（留空使用系统默认字体）
+fontName = ""
+# 文字颜色（十六进制）
+textColor = "#FFFFFF"
+# 文字阴影颜色（十六进制）
+shadowColor = "#EA403F"
+# 阴影模糊半径（像素）
+shadowRadius = 1.0
+# 背景颜色（十六进制）
+backgroundColor = "#000000"
+# 背景透明度（0.0-1.0，默认 0.60）
+backgroundAlpha = 0.60
+# 背景圆角半径（像素，0 使用默认胶囊形状 fontSize/2）
+cornerRadius = 0
+# 窗口整体透明度（0.0-1.0）
+windowAlpha = 1.0
+# 单行模式（只显示当前行）
+oneLineMode = false
+# 暂停时隐藏歌词
+hideOnPause = false
+# 允许拖拽移动歌词窗口
+draggable = true
+# 窗口最大宽度占屏幕比例（0.3-0.9，默认 0.7）
+maxWindowWidth = 0.7
+
+# 桌面歌词频谱可视化（GPU 加速，Core Animation 渲染）
+spectrumEnabled = false
+# 频谱区域高度（像素，默认 60）
+spectrumHeight = 60
+# 频段数量（2-64，默认 64）
+spectrumBarCount = 64
+# 频段间距（像素，默认 1）
+spectrumBarGap = 1
+# 频谱刷新帧率（默认 30）
+spectrumFPS = 30
+# 频谱渲染样式："bar" / "line" / "capsule" / "dot" / "mirror" / "waveform" / "fire" / "led" / "circular" / "ring_arc" / "ripple"
+spectrumStyle = "line"
+# 频谱整体透明度（0.0-1.0，默认 0.8）
+spectrumOpacity = 0.8
+# 低频颜色（十六进制）
+spectrumColorLow = "#00FF00"
+# 中频颜色（十六进制）
+spectrumColorMid = "#FFCC00"
+# 高频颜色（十六进制）
+spectrumColorHigh = "#FF0000"
+
+# Go性能分析工具pprof的相关设置
+[main.pprof]
+# pprof 服务监听的端口，通过 --pprof 命令行选项启用
+port = 9876
+
+# 账号相关配置
+[main.account]
+# 网易云音乐的登录 Cookie
+neteaseCookie = ""
+
+
+# 主题设置
+[theme]
+# 活跃主题名称（对应主题文件中的 name 字段，默认 "Default"）
+# 主题文件存放于 embed/themes/（内置）和 ~/.config/go-musicfox/themes/（用户自定义）
+activeTheme = "Default"
+# 是否在界面顶部显示标题
+showTitle = true
+# 菜单加载时显示的提示文字
+loadingText = "[加载中...]"
+# 是否使用双列布局（需要等宽字体以获得最佳体验）
+doubleColumn = true
+# 菜单行数是否根据终端高度动态变化
+dynamicMenuRows = false
+# 菜单内容起始行上限，限制菜单上方标题区域向下的最大偏移量（0 不限制）
+maxTitleStartRow = 12
+# 界面所有内容居中（实验性功能，未来版本中可能会大幅改动）
+centerEverything = false
+# 主题颜色
+# 随机
+# primaryColor = "random"
+# 经典网易云音乐红
+primaryColor = "#EA403F"
+# 是否显示底部状态栏（面包屑导航路径 + 时间）
+statusBar = true
+# 无障碍模式：高对比度主题 + 强调样式
+# 关闭时仍会依据终端 NO_COLOR/ACCESSIBLE 环境变量自动探测
+accessibleMode = false
+
+# 进度条字符样式配置
+[theme.progress]
+# 进度条渲染模式
+# 可选: "smooth"(平滑，默认), "wave"(波浪), "glow"(发光)
+renderMode = "smooth"
+# 进度条已加载字符
+fullChar = "#"
+fullCharWhenFirst = "#"
+fullCharWhenLast = "#"
+lastFullChar = "#"
+# 进度条未加载字符
+emptyChar = "·"
+emptyCharWhenFirst = "·"
+emptyCharWhenLast = "·"
+firstEmptyChar = "·"
+
+
+# 下载、缓存等文件存储相关配置
+[storage]
+# 下载目录
+# 若设置了 MUSICFOX_ROOT 变量，则默认为 ${MUSICFOX_ROOT}/download
+# 若未设置 MUSICFOX_ROOT 变量，则为相应系统的默认下载目录的 go-musicfox 子目录
+# 请使用绝对路径
+downloadDir = "/home/ryan/Music/go-musicfox"
+# 歌词文件的默认下载目录。如果为空，则与downloadDir保持一致。
+lyricDir = "/home/ryan/Music/go-musicfox"
+# 下载歌曲时是否同时下载歌词文件（仅当下载歌曲成功时）
+downloadSongWithLyric = true
+# 下载文件的命名模板
+# 可用字段参考 #自定义分享模板 中的 song 部分，FileExt 为自适应的后缀名
+# fileNameTpl = "{{.SongName}}-{{.SongArtists}}.{{.FileExt}}"
+
+# 音乐播放缓存相关设置
+[storage.cache]
+# 缓存目录
+# 若设置了 MUSICFOX_ROOT 变量，则默认为 ${MUSICFOX_ROOT}/cache
+# 若未设置 MUSICFOX_ROOT 变量，则为相应系统的默认缓存目录的 go-musicfox 子目录
+dir = ""
+# 音乐缓存路径，相对路径相对于 dir
+# 注意：如果使用 mpd，mpd 配置中的 "music_directory" 必须与 musicDir 路径一致
+musicDir = "music_cache"
+# 音乐缓存文件的总大小限制（单位：MB）
+# 0 为不使用缓存，-1 为不限制
+limit = 2048
+
+
+# 播放器引擎与行为配置
+[player]
+# 播放引擎，可选: "beep", "dlna", "mpd", "mpv", "osx", "win_media", "auto"（根据系统自动选择）
+# Mac 默认 "osx", Windows 默认 "win_media", 其他系统默认 "beep"
+engine = "mpv"
+# 允许的最大连续失败重试次数
+maxPlayErrCount = 3
+# 期望的歌曲音质
+# 可选: "standard", "exhigh", "higher", "lossless", "hires",
+#       "jyeffect"(高清环绕声), "sky"(沉浸环绕声), "jymaster"(超清母带)
+songLevel = "lossless"
+# 是否获取并显示歌单下的所有歌曲，默认前 1000 首
+# 开启后可能会占用更多内存（大量歌曲数据）和带宽（会同时发送多个请求获取歌单下歌曲数据）
+showAllSongsOfPlaylist = false
+# Ctrl + 鼠标滚轮单次滚动调节的音量值 (取值范围 1-20)
+mouseVolumeStep = 1
+
+# `beep` 引擎专属配置 (跨平台)
+[player.beep]
+# MP3解码器，可选: "go-mp3", "minimp3"
+# "minimp3" CPU占用更低，但稳定性可能稍逊于 "go-mp3"
+mp3Decoder = "go-mp3"
+
+# `mpd` 引擎专属配置，需要安装mpd
+[player.mpd]
+# mpd 可执行文件的路径，如果为空，则在系统 PATH 中查找
+bin = "mpd"
+# mpd配置文件的路径
+# 注意：配置文件中必须设置 pid_file，否则应用退出时无法正确关闭 mpd 进程
+configFile = ""
+# 与mpd服务的连接方式，可选: "tcp", "unix"
+network = "unix"
+# 连接地址
+# network 为 "tcp" 时，填写 "ip:port" (如 "127.0.0.1:6600")
+# network 为 "unix" 时，填写 socket 文件路径
+addr = ""
+# 是否在需要时自动启动 mpd 服务
+autoStart = true
+
+# `mpv` 引擎专属配置，需要安装 mpv
+[player.mpv]
+# mpv 可执行文件的路径，如果为空，则在系统 PATH 中查找
+bin = "mpv"
+
+# `dlna` 引擎专属配置
+[player.dlna]
+# DLNA 设备描述 URL，例如：http://192.168.1.100:49152/description.xml
+# 使用 gupnp-tools 的 gupnp-universal-cp 工具可扫描并获取设备 URL
+deviceUrl = ""
+# 本机局域网 IP（用于内置 HTTP server）
+localIP = ""
+
+
+# 启动时自动播放相关配置
+[autoplay]
+# 是否在启动后自动开始播放
+enable = false
+# 自动播放的歌单
+# 可选: "dailyReco", "like", "no", 或 "name:歌单名"
+# "no" 表示保持上次退出时的播放列表，无视 offset
+playlist = "dailyReco"
+# 播放列表的起始偏移量，0 为第一首，-1 为最后一首
+offset = 0
+# 播放模式
+# 可选: "listLoop", "order", "singleLoop", "random"（无视offset）, "intelligent"（心动）, "last"（上次退出时的模式）
+mode = "last"
+
+
+# UNM (Unlock NetEase Music) 相关配置，用于解锁灰色或无版权歌曲
+[unm]
+# 是否启用 UNM 功能
+enable = false
+# 音源匹配来源，可配置多个，用逗号分隔
+# 可选: "kuwo", "kugou", "migu", "qq"
+sources = ["kuwo"]
+# UNM搜索其他平台限制 0-3
+searchLimit = 0
+# 解除会员限制
+enableLocalVip = true
+# 解除音质限制
+unlockSoundEffects = true
+# 用于获取QQ音乐音源的Cookie文件路径
+qqCookieFile = ""
+# 检测到无效的歌（如提示酷我...）时跳过播放，该效果计入播放错误计数
+skipInvalidTracks = false
+# unm代理URL，"http://127.0.0.1:8080"，配置后会禁用内置的unm
+proxyURL = ""
+
+
+# 播放状态上报配置
+[reporter]
+# 是否将播放状态上报回网易云音乐（“听歌排行”）
+# 注意：可能存在风控风险
+[reporter.netease]
+enable = false
+
+# 上报至 Last.fm
+[reporter.lastfm]
+enable = false
+# Last.fm API Key
+key = ""
+# Last.fm API Shared Secret
+secret = ""
+# 播放一首歌的百分比达到多少时，才进行上报
+# 范围: 50-100
+scrobblePoint = 50
+# 是否只上报歌曲的第一位艺术家
+onlyFirstArtist = false
+# 是否跳过电台节目的上报
+skipDjRadio = false
+
+
+# 快捷键绑定配置
+[keybindings]
+# 是否使用应用内置的默认快捷键作为基础
+# 设置为false时，只有您在 [keybindings.app] 中定义的快捷键会生效。
+useDefaultKeyBindings = true
+
+# 全局快捷键，即使应用在后台也能响应
+# 格式: "快捷键组合" = "功能名"
+# 功能名列表请参考项目文档
+[keybindings.global]
+# "ctrl+shift+space" = "toggle"
+
+# 应用内快捷键
+# 格式: "功能名" = ["按键1", "按键2", ...]
+[keybindings.app]
+help = ["?", "？"]
+pageUp = ["ctrl+u", "pgup"]
+pageDown = ["ctrl+d", "pgdown"]
+# 空格
+playOrToggle = ["space"]
+# 空数组表示取消此功能的快捷键
+toggle = []
+previous = ["[", "【"]
+next = ["]", "】"]
+backwardFiveSec = ["X"]
+backwardOneSec = ["x"]
+forwardFiveSec = ["v"]
+forwardTenSec = ["V"]
+downVolume = ["-", "−", "ー"]
+upVolume = ["=", "＝"]
+switchPlayMode = ["p"]
+intelligence = ["P"]
+clearSongCache = ["u", "U"]
+logout = ["W"]
+curPlaylist = ["c", "C"]
+
+
+# 自定义分享模板
+# 格式: "名称" = "模板字符串"
+# 详细用法请参考项目文档（README）
+[share]
diff --git a/home/linux/gui/base/go-musicfox/default.nix b/home/linux/gui/base/go-musicfox/default.nix
new file mode 100644
index 00000000..8013ddb3
--- /dev/null
+++ b/home/linux/gui/base/go-musicfox/default.nix
@@ -0,0 +1,12 @@
+{ ... }:
+{
+  # go-musicfox rewrites config.toml at runtime (in-app theme switch, `musicfox
+  # upgrade-config`) with a temp file plus rename, which would replace a plain
+  # symlink with a regular file. Same approach as fcitx5's `profile`: force the
+  # declarative copy back on every activation. Runtime edits persist until the
+  # next rebuild and are then reset; copy them back here manually to keep them.
+  xdg.configFile."go-musicfox/config.toml" = {
+    source = ./config.toml;
+    force = true;
+  };
+}
diff --git a/hosts/idols-ai/preservation.nix b/hosts/idols-ai/preservation.nix
index 7b69a849..9361611c 100644
--- a/hosts/idols-ai/preservation.nix
+++ b/hosts/idols-ai/preservation.nix
@@ -313,7 +313,11 @@ in
         ".local/state/wireplumber"
 
         # go-musicfox - TUI NetEase Cloud Music client
-        ".config/go-musicfox" # config.toml + themes
+        # ~/.config/go-musicfox/config.toml is force-managed by Home Manager
+        # (see home/linux/gui/base/go-musicfox/default.nix) and reset on each
+        # rebuild; this keeps the runtime themes/ directory and the app's
+        # between-rebuild config edits.
+        ".config/go-musicfox"
         ".local/share/go-musicfox" # login cookie + library db
         ".local/state/go-musicfox" # logs