1. 通过 Homebrew 安装

$ brew install anhoder/go-musicfox/go-musicfox  // 指定 --head 使用master代码编译安装

如果你之前安装过 musicfox，需要使用下列命令重新链接:

$ brew unlink musicfox && brew link --overwrite go-musicfox

2. 直接下载

在 Release 下载 macOS 的可执行文件。

1. 使用发行版软件包（推荐）

$ paru -S go-musicfox # 下载源代码编译安装
$ paru -S go-musicfox-bin # 下载安装预编译好的二进制

# pacman -S go-musicfox

$ sudo dnf copr enable poesty/go-musicfox
$ sudo dnf install go-musicfox

$ sudo aptss install go-musicfox  //二进制包部署，同步较慢
$ sudo aptss install go-musicfox-git  //从源码编译，请保持网络通畅

$ eselect repository enable gentoo-zh
$ emerge --sync
$ emerge -a media-sound/go-musicfox

{
  description = "My configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    go-musicfox.url = "github:go-musicfox/go-musicfox";
  };

  outputs = { nixpkgs, go-musicfox, ... }:
    {
      nixosConfigurations = {
        hostname = nixpkgs.lib.nixosSystem
          {
            system = "x86_64-linux";
            modules = [
              {
                nixpkgs.overlays = [ go-musicfox.overlays.default ];
                environment.systemPackages = with pkgs;[
                  go-musicfox
                ];
              }
            ];
          };
      };
    };
}

$ nix run github:go-musicfox/go-musicfox

# configuration.nix
environment.systemPackages = [
  pkgs.go-musicfox
];

# home manager
home.packages = [
  pkgs.go-musicfox
];

$ nix-env -iA nixos.go-musicfox

$ nix-shell -p go-musicfox

$ apt install go-musicfox

2. 通过 Homebrew 安装

$ brew install anhoder/go-musicfox/go-musicfox  // 指定 --head 使用master代码编译安装

如果你之前安装过 musicfox，需要使用下列命令重新链接:

$ brew unlink musicfox && brew link --overwrite go-musicfox

3. 通过 Flatpak 安装

4. 直接下载

在 Release 下载 Linux 的可执行文件。

1. 通过 scoop 安装

scoop bucket add go-musicfox https://github.com/go-musicfox/go-musicfox.git

scoop install go-musicfox

2. 直接下载

在 Release 下载 Windows 的可执行文件。

注：需要 Go v1.22 及以上版本

前往 下载 Go 页面选择适合你的 Go 安装包体。

在 Linux 上编译

Linux 需要 libFLAC-dev 开发套件

请根据你的发行版，选择适合你的安装命令：

• APT (Debian, Ubuntu)

$ sudo apt install software-properties-common build-essential
$ sudo add-apt-repository ppa:longsleep/golang-backports //ubuntu默认go语言版本为1.18，需要更新到1.21
$ sudo apt install libflac-dev libasound2-dev golang-go

• pacman (Arch)

$ sudo pacman -S flac

• DNF (Fedora)

$ sudo dnf install flac-devel

其他发行版请根据相应文档寻找 libflac-dev 开发套件安装说明。

开始编译

$ git clone https://github.com/go-musicfox/go-musicfox
$ go mod download
$ make # 编译到 bin 目录下
$ make install # 安装到 $GOPATH/bin下

• 请务必使用等宽字体，或将配置项 doubleColumn 设为 false，否则双列显示排版可能会混乱

• 如果在使用时出现莫名奇妙的光标移动、切歌或暂停等现象，请将配置项 enableMouseEvent 设置为 false

• 本应用不对 macOS 原生终端和 Windows 的命令提示符（CMD）做兼容处理（#99）

  macOS 用户推荐使用 iTerm2 或 Kitty

  Linux 用户推荐使用 Kitty

  Windows 用户推荐使用 Windows Terminal，使用体验更佳

• 如果在执行文件时遇到以下错误，说明你的操作系统内不包含 libFLAC.so.8：

  ./musicfox: error while loading shared libraries: libFLAC.so.8: cannot open shared object file: No such file or directory
  

  例如 Ubuntu 23.10 及它的衍生版系列，libFLAC.so.12 已经将 libFLAC.so.8 替换。

  遇到这种问题，你可以：

  • 找到已安装的新版 libFLAC.so，将其软链为libFLAC.so.8: ln -s /xxx/libFLAC.so /xxx/libFLAC.so.8 （推荐）
  • 自行安装 libflac8 （不推荐）
  • 参照手动编译一节自行编译。

  这里之所以使用 FLAC8，主要是为了兼容大部分系统，因为FLAC是向前兼容的（也就是说 ≥ 8 的FLAC都可以使用）

• wsl 环境下使用 beep 须安装 libasound2-plugins，见 issues

• XDG 支持：完整的 XDG 支持，部分文件路径变更，见 XDG 支持说明

• 配置文件格式：使用 TOML 格式

DLNA 引擎允许你将音乐投送到兼容 DLNA 的设备（如智能电视、音响、游戏机等）。

1. 获取设备 URL

   • 安装 gupnp-tools：brew install gupnp-tools（macOS）或 sudo apt install gupnp-tools（Linux）
   • 运行 gupnp-universal-cp，扫描并复制设备的描述 URL（形如 http://192.168.1.100:49152/description.xml）

2. 配置 在 config.toml 中设置：

   [player]
   engine = "dlna"
   
   [player.dlna]
   deviceUrl = "http://你的设备IP:端口/description.xml"
   localIP = "本机局域网IP"  # 例如 192.168.1.50
   

3. 播放 启动应用后，选择歌曲即可自动投送到 DLNA 设备。

完整的主题配置系统，支持运行时切换、自定义配色和多种内置主题。

内置主题

• Default - 经典浅色主题
• Transparent - 透明主题，适配终端背景
• Dark Transparent - 深色透明主题
• Dracula - 流行的 Dracula 配色
• Nord - 北欧冷色调
• Gruvbox - 复古暖色调

使用方式

1. 配置文件设置

   [theme]
   activeTheme = "Dracula"  # 启动时加载的主题
   

2. 运行时切换

   • 通过右键菜单选择"切换主题"
   • 或在配置中绑定快捷键：switchTheme = "t"

3. 自定义主题

   • 在用户配置目录下创建 themes/ 子目录
   • 每个主题一个独立的 .toml 文件（例如：
     • macOS: ~/Library/Application Support/go-musicfox/themes/mytheme.toml
     • Linux: ~/.config/go-musicfox/themes/mytheme.toml
     • Windows: %AppData%\go-musicfox\themes\mytheme.toml）
   • 主题文件必须包含 name 字段和 [dark] 或 [light] 配置表
   • 详细配置参见 内置主题示例

终端 TUI 中的实时音频频谱可视化（仅 macOS osx 播放引擎支持）。

配置

[main.visualizer]
enable = true              # 启用频谱显示
maxHeight = 10             # 最大高度（行数），0 为自动填充
fullCharHalfBlock = "▌"    # 半填充字符
fullCharFullBlock = "█"    # 全填充字符
emptyCharBlock = " "       # 空白字符

频谱会显示在歌词和歌曲信息之间，低频在底部，高频在顶部，使用前景/背景双色渐变提供更高精度的幅度表现。

配置

[main.lyric.desktopLyrics]
enable = true                    # 启用桌面歌词
showSpectrum = true              # 显示频谱
spectrumStyle = "capsule"        # 频谱样式：bar/mirror/capsule/flame/circle/wave/ring/pulse/helix/dna/dualwave

# 外观定制
fontName = "PingFang SC"
fontSize = 40.0
textColor = "#FFFFFF"
strokeColor = "#000000"
shadowColor = "#000000"
backgroundColor = "#00000080"    # 支持透明度
cornerRadius = 16.0

功能

• YRC 逐字高亮 - 支持网易云的逐字歌词格式
• 拖拽定位 - 按住窗口可自由移动，位置自动保存
• 11种频谱样式 - 从经典柱状到创意 DNA 螺旋
• 完整视觉定制 - 字体、颜色、阴影、圆角、透明度

详细配置选项参见 changelog。

支持 8 种启动动画类型，可配置启动视觉效果：

• sequential - 经典序列动画（默认）
• wave - 波浪效果
• pulse - 脉冲效果
• typewriter - 打字机效果
• matrix - 黑客帝国字符雨
• glitch - 故障艺术
• neon - 霓虹灯效果
• none - 无动画

[startup]
style = "matrix"  # 选择启动动画

完整的上下文菜单系统，右键点击不同元素可触发相应操作：

• 菜单项右键 - 显示歌曲/专辑/歌单相关操作（喜欢、下载、收藏等）
• 状态栏右键 - 快速切换主题、播放模式
• 面包屑右键 - 菜单导航操作

可在配置中设置 enableMouseEvent = true 以启用完整鼠标支持。

upgrade-config 子命令用于同步新版本的配置项：

musicfox upgrade-config

该命令会：

• 将内嵌默认配置中用户文件缺失的叶子项追加到对应 table
• 保留用户已有的值、注释、布局和未知键
• 以原子操作写回，保持文件权限

建议在升级到新版本后运行一次。

应用内快捷键

不可自定义操作 (内置)

这些是程序核心框架提供的基础操作，其快捷键通常无法通过配置文件修改。

可自定义操作

你可以在配置文件的 [keybindings] 部分修改这些操作的快捷键。

注意：

• 非字符快捷键大小写不敏感，如 shift+tab 等同 Shift+Tab，但 a 与 A 不同
• 多次绑定同一个键的行为是未定义的，以程序最后读取的为准
• 不可自定义操作 不可自定义且其使用的键也不可用于自定义
• 与歌曲、歌单等存在关联的操作现已默认添加至 actionOfSelected 及 actionOfPlayingSong

示例配置：

[keybindings]
# 取消所有默认键绑定（须自定义键以确保正常使用）
useDefaultKeyBindings = false

# 应用内快捷键
[keybindings.app]
# 将“下一首”改为 Alt+N
next = "alt+n"

# 为“帮助”额外添加 Ctrl+H
help = ["?","ctrl+h"]

# 取消“心动模式”的默认 P 键
intelligence = ""

# 将“显示当前播放列表”改为 Ctrl+P
curPlaylist = "ctrl+p"

全局快捷键

默认不设置任何全局快捷键，如果需要请在配置文件中的global_hotkey下进行配置，例如：

[keybindings.global]
# 格式：键=功能
"ctrl+shift+space" = "toggle"

因为Linux下开启全局快捷键需要安装比较多的依赖，可能你并不需要这个功能，所以Releases中的Linux二进制文件是不支持全局快捷键的

如果需要开启，请安装依赖后手动进行编译:

BUILD_TAGS=enable_global_hotkey make build

完整的鼠标交互支持：

• 点击 - 选择菜单项、点击按钮
• 双击 - 快速进入子菜单或播放
• 滚轮 - 上下滚动列表
• 悬停 - 高亮显示可交互元素
• 右键菜单 - 上下文相关的操作菜单

配置：

[main]
enableMouseEvent = true  # 启用鼠标支持

详见 鼠标支持说明

分享文本的内容是完全可定制的，它由一套模板系统驱动（使用 text/template ，支持条件判断等高级用法）。

字段分组详解

注意：

• 对于 episode（播客节目）类型，由于其本质也是一首“歌曲”，因此它同时拥有 Episode、Song 和 Album 的所有字段。其中 EpisodeName 和 SongName 的值是相同的。

模板类型与可用字段

不同类型的分享项目，其可用的信息字段也不同。例如，分享一首“歌曲”时，您可以同时获取到“歌曲信息”和它所属的“专辑信息”；而分享一个“歌手”时，则只有“歌手信息”。 不支持自定义模板名

示例

[share]
song = "分享{{if .SongArtists}}{{.SongArtists}}的{{end}}单曲《{{.SongName}}》: {{.SongUrl}} (来自@网易云音乐)"