go-musicfox

go-musicfox

go-musicfox 是用 Go 写的又一款网易云音乐命令行客户端，支持各种音质级别、UnblockNeteaseMusic、Last.fm、MPRIS 和 macOS 交互响应（睡眠暂停、蓝牙耳机连接断开响应和菜单栏控制等）等功能特性，以及 DLNA 投送。

官网 | Icon

(The icon is based on kitty-icon)

预览

安装

macOS

1. 通过 Homebrew 安装

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

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

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

2. 直接下载

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

Linux

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

Arch Linux

从 AUR 安装

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

从 archlinuxcn 安装

首先添加 archlinuxcn 仓库到系统。

# pacman -S go-musicfox

Fedora Linux

从 Copr 安装。

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

Debian系发行版（Ubuntu、Deepin、UOS等）

从 星火商店 安装。

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

Gentoo Linux

从 gentoo-zh Overlay 安装

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

NixOS

…

临时运行:

$ 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

Void Linux

从 void-packages-zh 安装。

Termux(Android)

$ apt install go-musicfox

如果遇到卡顿，请切换到mpd播放引擎

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 的可执行文件。

Windows

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下

使用

$ musicfox

注意事项

• 请务必使用等宽字体，或将配置项 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 引擎允许你将音乐投送到兼容 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 中设置：

   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. 配置文件设置

   toml复制

   [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] 配置表
   • 详细配置参见 内置主题示例

终端内实时显示音频频谱（仅 macOS osx 播放引擎支持）。

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

配置

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

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

macOS 桌面歌词

配置

[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] 部分修改这些操作的快捷键。