go-musicfox

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

官网 | Icon

GitHub repo size GitHub Last Tag GitHub last commit GitHub All Releases

(The icon is based on kitty-icon)

预览

安装

macOS

1. 通过 Homebrew 安装

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

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

$ brew unlink musicfox &amp;&amp; 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

flake support

下面是一个在nixos配置中使用它的例子

{
  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 或使用 Home Manager（推荐）

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

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

从 Nixpkgs 安装

安装到本地 profile：

$ 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 &amp;&amp; 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 的设备（如智能电视、音响、游戏机等）。

获取设备 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）

配置在 config.toml 中设置：

[player]
engine = "dlna"

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

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

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

主题系统

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

内置主题

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

使用方式

配置文件设置

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

运行时切换
- 通过右键菜单选择"切换主题"
- 或在配置中绑定快捷键：switchTheme = "t"
自定义主题
- 在用户配置目录下创建 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 桌面歌词

macOS 原生桌面歌词窗口，支持 YRC 逐字高亮、频谱可视化和完整的视觉定制。

配置

[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
保留用户已有的值、注释、布局和未知键
以原子操作写回，保持文件权限

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

快捷键

应用内快捷键

不可自定义操作 (内置)

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

配置标识符	操作说明	默认按键
`rerender`	重新渲染UI	`r`, `R`
`moveLeft`	左	`h`, `H`, `Left`
`moveRight`	右	`l`, `L`, `Right`
`moveUp`	上	`k`, `K`, `Up`
`moveDown`	下	`j`, `J`, `Down`
`moveToTop`	上移到顶部	`g`
`moveToBottom`	下移到底部	`G`
`enter`	进入	`n`, `N`, `Enter`
`goBack`	返回上一级	`b`, `B`, `Esc`
`search`	搜索当前列表	`/`, `／`, `、`
`quit`	退出	`q`, `Q`

可自定义操作

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

配置标识符	操作说明	默认按键
`help`	帮助信息	`?`, `？`
`pageUp`	上一页	`Ctrl+u`, `PgUp`
`pageDown`	下一页	`Ctrl+d`, `PgDown`
`playortoggle`	播放/暂停	`Space`, ,
`toggle`	切换播放状态	(无)
`previous`	上一首	`[`, `【`
`next`	下一首	`]`, `】`
`backwardOneSec`	快退1秒	`x`
`backwardFiveSec`	快退5秒	`X`
`forwardFiveSec`	快进5秒	`v`
`forwardTenSec`	快进10秒	`V`
`downVolume`	减小音量	`-`, `−`, `ー`
`upVolume`	加大音量	`=`, `＝`
`switchPlayMode`	切换播放模式	`p`
`intelligence`	心动模式	`P`
`clearSongCache`	清除音乐缓存	`u`, `U`
`logout`	注销并退出	`w`, `W`
`curPlaylist`	显示当前播放列表	`c`, `C`
`appendSongsToNext`	添加为下一曲播放	`e`
`appendSongsAfterCurPlaylist`	添加到播放列表末尾	`E`
`delSongFromCurPlaylist`	从播放列表删除选中歌曲	`\`, `、`
`likePlayingSong`	喜欢播放中歌曲	`,`, `，`
`dislikePlayingSong`	取消喜欢播放中歌曲	`.`, `。`
`trashPlayingSong`	标记播放中歌曲为不喜欢	`t`
`addPlayingSongToUserPlaylist`	将播放中歌曲加入歌单	`
`removePlayingSongFromUserPlaylist`	将播放歌曲从歌单中删除	`~`, `～`
`downloadPlayingSong`	下载播放中歌曲	`d`
`downloadPlayingSongLrc`	下载当前播放音乐歌词	`Ctrl+l`
`openAlbumOfPlayingSong`	播放中歌曲的所属专辑	`a`
`openArtistOfPlayingSong`	播放中歌曲的所属歌手	`s`
`openPlayingSongInWeb`	网页打开播放中歌曲	`o`
`simiSongsOfPlayingSong`	与播放中歌曲相似的歌曲	`f`
`likeSelectedSong`	喜欢选中歌曲	`<`, `〈`, `＜`, `《`, `«`
`dislikeSelectedSong`	取消喜欢选中歌曲	`>`, `〉`, `＞`, `》`, `»`
`trashSelectedSong`	标记选中歌曲为不喜欢	`T`
`addSelectedSongToUserPlaylist`	将选中歌曲加入歌单	`Tab`
`removeSelectedSongFromUserPlaylist`	将选中歌曲从歌单中删除	`Shift+Tab`
`downloadSelectedSong`	下载选中歌曲	`D`
`downloadSelectedSongLrc`	下载选中歌曲的歌词
`openAlbumOfSelectedSong`	选中歌曲的所属专辑	`A`
`openArtistOfSelectedSong`	选中歌曲的所属歌手	`S`
`openSelectedItemInWeb`	网页打开选中歌曲/专辑...	`O`
`collectSelectedPlaylist`	收藏选中歌单	`;`, `:`, `：`, `；`
`discollectSelectedPlaylist`	取消收藏选中歌单	`'`, `"`
`subscribeAlbumOfPlayingSong`	收藏播放中歌曲的专辑	(无)
`unsubscribeAlbumOfPlayingSong`	取消收藏播放中歌曲的专辑	(无)
`subscribeArtistOfPlayingSong`	收藏播放中歌曲的歌手	(无)
`unsubscribeArtistOfPlayingSong`	取消收藏播放中歌曲的歌手	(无)
`subscribeAlbumOfSelectedSong`	收藏选中歌曲的专辑	(无)
`unsubscribeAlbumOfSelectedSong`	取消收藏选中歌曲的专辑	(无)
`subscribeArtistOfSelectedSong`	收藏选中歌曲的歌手	(无)
`unsubscribeArtistOfSelectedSong`	取消收藏选中歌曲的歌手	(无)
`simiSongsOfSelectedSong`	与选中歌曲相似的歌曲	`F`
`actionOfSelected`	对于选中项或当前播放的操作	`m`
`actionOfPlayingSong`	对于当前播放的操作	`M`
`switchTheme`	切换主题样式	(无，可通过右键菜单触发)
`toggleSortOrder`	切换排序顺序（电台/播客列表）	`

注意：

非字符快捷键大小写不敏感，如 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二进制文件是不支持全局快捷键的 > > 如果需要开启，请安装依赖后手动进行编译: > > shell > BUILD_TAGS=enable_global_hotkey make build >

鼠标支持

完整的鼠标交互支持：

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

配置：

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

详见鼠标支持说明

自定义分享模板

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

字段分组详解

字段分组	包含字段
`Song`	`SongId`: 歌曲ID `SongName`: 歌曲名称 `SongArtists`: 歌曲的艺术家名 `SongUrl`: 歌曲链接
`Album`	`AlbumId`: 专辑ID `AlbumName`: 专辑名称 `AlbumUrl`: 专辑链接 `AlbumArtists`: 专辑的艺术家名
`Artist`	`ArtistId`: 歌手ID `ArtistName`: 歌手姓名 `ArtistUrl`: 歌手链接
`Playlist`	`PlaylistId`: 歌单ID `PlaylistName`: 歌单名称 `PlaylistUrl`: 歌单链接
`User`	`UserID`: 用户ID `UserName`: 用户昵称 `UserUrl`: 用户链接
`DjRadio`	`DjRadioId`: 播客电台ID `DjRadioName`: 播客电台名称 `DjRadioUrl`: 播客电台链接
`Episode`	`EpisodeId`: 播客节目ID `EpisodeName`: 播客节目名称 `EpisodeUrl`: 播客节目链接

注意：

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

模板类型与可用字段

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

模板名称	说明	可用字段分组
`song`	用于分享一首单曲。	`Song`, `Album`
`album`	用于分享一张专辑。	`Album`
`artist`	用于分享一位歌手。	`Artist`
`playlist`	用于分享一个歌单。	`Playlist`, `User`
`user`	用于分享一位用户。	`User`
`djRadio`	用于分享一个播客电台。	`DjRadio`, `User`
`episode`	用于分享播客中的一期节目。	`Episode`, `DjRadio`, `User`, `Song`, `Album`

示例

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

配置文件

配置文件路径为用户配置目录下的 config.toml 文件，详细可参见配置示例。

> 用户配置目录路径： > > macOS：$HOME/Library/Application Support/go-musicfox > > Linux：$XDG_CONFIG_HOME/go-musicfox 或 $HOME/.config/go-musicfox > > Windows：%AppData%\go-musicfox > > 你可以通过设置 MUSICFOX_ROOT 环境变量来自定义用户配置的存储位置

CHANGELOG

See CHANGELOG.md

感谢

感谢以下项目及其贡献者们（但不限于）：

go-musicfox

官网 | Icon

GitHub repo size GitHub Last Tag GitHub last commit GitHub All Releases

(The icon is based on kitty-icon)

预览

安装

macOS

1. 通过 Homebrew 安装

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

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

$ brew unlink musicfox &amp;&amp; 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

flake support

下面是一个在nixos配置中使用它的例子

{
  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 或使用 Home Manager（推荐）

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

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

从 Nixpkgs 安装

安装到本地 profile：

$ 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 &amp;&amp; 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 的设备（如智能电视、音响、游戏机等）。

获取设备 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）

配置在 config.toml 中设置：

[player]
engine = "dlna"

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

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

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

主题系统

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

内置主题

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

使用方式

配置文件设置

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

运行时切换
- 通过右键菜单选择"切换主题"
- 或在配置中绑定快捷键：switchTheme = "t"
自定义主题
- 在用户配置目录下创建 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 桌面歌词

macOS 原生桌面歌词窗口，支持 YRC 逐字高亮、频谱可视化和完整的视觉定制。

配置

[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
保留用户已有的值、注释、布局和未知键
以原子操作写回，保持文件权限

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

快捷键

应用内快捷键

不可自定义操作 (内置)

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

配置标识符	操作说明	默认按键
`rerender`	重新渲染UI	`r`, `R`
`moveLeft`	左	`h`, `H`, `Left`
`moveRight`	右	`l`, `L`, `Right`
`moveUp`	上	`k`, `K`, `Up`
`moveDown`	下	`j`, `J`, `Down`
`moveToTop`	上移到顶部	`g`
`moveToBottom`	下移到底部	`G`
`enter`	进入	`n`, `N`, `Enter`
`goBack`	返回上一级	`b`, `B`, `Esc`
`search`	搜索当前列表	`/`, `／`, `、`
`quit`	退出	`q`, `Q`

可自定义操作

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

配置标识符	操作说明	默认按键
`help`	帮助信息	`?`, `？`
`pageUp`	上一页	`Ctrl+u`, `PgUp`
`pageDown`	下一页	`Ctrl+d`, `PgDown`
`playortoggle`	播放/暂停	`Space`, ,
`toggle`	切换播放状态	(无)
`previous`	上一首	`[`, `【`
`next`	下一首	`]`, `】`
`backwardOneSec`	快退1秒	`x`
`backwardFiveSec`	快退5秒	`X`
`forwardFiveSec`	快进5秒	`v`
`forwardTenSec`	快进10秒	`V`
`downVolume`	减小音量	`-`, `−`, `ー`
`upVolume`	加大音量	`=`, `＝`
`switchPlayMode`	切换播放模式	`p`
`intelligence`	心动模式	`P`
`clearSongCache`	清除音乐缓存	`u`, `U`
`logout`	注销并退出	`w`, `W`
`curPlaylist`	显示当前播放列表	`c`, `C`
`appendSongsToNext`	添加为下一曲播放	`e`
`appendSongsAfterCurPlaylist`	添加到播放列表末尾	`E`
`delSongFromCurPlaylist`	从播放列表删除选中歌曲	`\`, `、`
`likePlayingSong`	喜欢播放中歌曲	`,`, `，`
`dislikePlayingSong`	取消喜欢播放中歌曲	`.`, `。`
`trashPlayingSong`	标记播放中歌曲为不喜欢	`t`
`addPlayingSongToUserPlaylist`	将播放中歌曲加入歌单	`
`removePlayingSongFromUserPlaylist`	将播放歌曲从歌单中删除	`~`, `～`
`downloadPlayingSong`	下载播放中歌曲	`d`
`downloadPlayingSongLrc`	下载当前播放音乐歌词	`Ctrl+l`
`openAlbumOfPlayingSong`	播放中歌曲的所属专辑	`a`
`openArtistOfPlayingSong`	播放中歌曲的所属歌手	`s`
`openPlayingSongInWeb`	网页打开播放中歌曲	`o`
`simiSongsOfPlayingSong`	与播放中歌曲相似的歌曲	`f`
`likeSelectedSong`	喜欢选中歌曲	`<`, `〈`, `＜`, `《`, `«`
`dislikeSelectedSong`	取消喜欢选中歌曲	`>`, `〉`, `＞`, `》`, `»`
`trashSelectedSong`	标记选中歌曲为不喜欢	`T`
`addSelectedSongToUserPlaylist`	将选中歌曲加入歌单	`Tab`
`removeSelectedSongFromUserPlaylist`	将选中歌曲从歌单中删除	`Shift+Tab`
`downloadSelectedSong`	下载选中歌曲	`D`
`downloadSelectedSongLrc`	下载选中歌曲的歌词
`openAlbumOfSelectedSong`	选中歌曲的所属专辑	`A`
`openArtistOfSelectedSong`	选中歌曲的所属歌手	`S`
`openSelectedItemInWeb`	网页打开选中歌曲/专辑...	`O`
`collectSelectedPlaylist`	收藏选中歌单	`;`, `:`, `：`, `；`
`discollectSelectedPlaylist`	取消收藏选中歌单	`'`, `"`
`subscribeAlbumOfPlayingSong`	收藏播放中歌曲的专辑	(无)
`unsubscribeAlbumOfPlayingSong`	取消收藏播放中歌曲的专辑	(无)
`subscribeArtistOfPlayingSong`	收藏播放中歌曲的歌手	(无)
`unsubscribeArtistOfPlayingSong`	取消收藏播放中歌曲的歌手	(无)
`subscribeAlbumOfSelectedSong`	收藏选中歌曲的专辑	(无)
`unsubscribeAlbumOfSelectedSong`	取消收藏选中歌曲的专辑	(无)
`subscribeArtistOfSelectedSong`	收藏选中歌曲的歌手	(无)
`unsubscribeArtistOfSelectedSong`	取消收藏选中歌曲的歌手	(无)
`simiSongsOfSelectedSong`	与选中歌曲相似的歌曲	`F`
`actionOfSelected`	对于选中项或当前播放的操作	`m`
`actionOfPlayingSong`	对于当前播放的操作	`M`
`switchTheme`	切换主题样式	(无，可通过右键菜单触发)
`toggleSortOrder`	切换排序顺序（电台/播客列表）	`

注意：

非字符快捷键大小写不敏感，如 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"

鼠标支持

完整的鼠标交互支持：

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

配置：

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

详见鼠标支持说明

自定义分享模板

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

字段分组详解

字段分组	包含字段
`Song`	`SongId`: 歌曲ID `SongName`: 歌曲名称 `SongArtists`: 歌曲的艺术家名 `SongUrl`: 歌曲链接
`Album`	`AlbumId`: 专辑ID `AlbumName`: 专辑名称 `AlbumUrl`: 专辑链接 `AlbumArtists`: 专辑的艺术家名
`Artist`	`ArtistId`: 歌手ID `ArtistName`: 歌手姓名 `ArtistUrl`: 歌手链接
`Playlist`	`PlaylistId`: 歌单ID `PlaylistName`: 歌单名称 `PlaylistUrl`: 歌单链接
`User`	`UserID`: 用户ID `UserName`: 用户昵称 `UserUrl`: 用户链接
`DjRadio`	`DjRadioId`: 播客电台ID `DjRadioName`: 播客电台名称 `DjRadioUrl`: 播客电台链接
`Episode`	`EpisodeId`: 播客节目ID `EpisodeName`: 播客节目名称 `EpisodeUrl`: 播客节目链接

注意：

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

模板类型与可用字段

模板名称	说明	可用字段分组
`song`	用于分享一首单曲。	`Song`, `Album`
`album`	用于分享一张专辑。	`Album`
`artist`	用于分享一位歌手。	`Artist`
`playlist`	用于分享一个歌单。	`Playlist`, `User`
`user`	用于分享一位用户。	`User`
`djRadio`	用于分享一个播客电台。	`DjRadio`, `User`
`episode`	用于分享播客中的一期节目。	`Episode`, `DjRadio`, `User`, `Song`, `Album`

示例

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

配置文件

配置文件路径为用户配置目录下的 config.toml 文件，详细可参见配置示例。

CHANGELOG

See CHANGELOG.md

感谢

感谢以下项目及其贡献者们（但不限于）：

go-musicfox go-musicfox

README

go-musicfox

预览

安装

macOS

1. 通过 Homebrew 安装

2. 直接下载

Linux

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

Arch Linux

从 AUR 安装

从 archlinuxcn 安装

Fedora Linux

从 Copr 安装。

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

从 星火商店 安装。

Gentoo Linux

从 gentoo-zh Overlay 安装

NixOS

Void Linux

Termux(Android)

2. 通过 Homebrew 安装

3. 通过 Flatpak 安装

4. 直接下载

Windows

1. 通过 scoop 安装

2. 直接下载

手动编译

在 Linux 上编译

开始编译

使用

注意事项

DLNA 投送

主题系统

内置主题

使用方式

配置

macOS 桌面歌词

配置

功能

启动动画

右键菜单

配置升级

快捷键

应用内快捷键

不可自定义操作 (内置)

可自定义操作

全局快捷键

鼠标支持

自定义分享模板

字段分组详解

模板类型与可用字段

示例

配置文件

CHANGELOG

相关项目

感谢

go-musicfox go-musicfox

README

go-musicfox

预览

安装

macOS

1. 通过 Homebrew 安装

2. 直接下载

Linux

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

Arch Linux

从 AUR 安装

从 archlinuxcn 安装

Fedora Linux

从 Copr 安装。

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

从 星火商店 安装。

Gentoo Linux

从 gentoo-zh Overlay 安装

NixOS

Void Linux

Termux(Android)

从 `archlinuxcn` 安装

从星火商店安装。

从 `archlinuxcn` 安装

从星火商店安装。