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](https://github.com/go-musicfox/go-musicfox/releases/latest) 下载 macOS 的可执行文件。
### Linux
#### 1. 使用发行版软件包(推荐)
##### Arch Linux
###### 从 [AUR](https://aur.archlinux.org/) 安装
$ paru -S go-musicfox # 下载源代码编译安装
$ paru -S go-musicfox-bin # 下载安装预编译好的二进制
###### 从 `archlinuxcn` 安装
首先[添加 archlinuxcn 仓库到系统](https://www.archlinuxcn.org/archlinux-cn-repo-and-mirror/)。
# pacman -S go-musicfox
##### Fedora Linux
###### 从 [Copr](https://copr.fedorainfracloud.org/coprs/poesty/go-musicfox/) 安装。
$ sudo dnf copr enable poesty/go-musicfox
$ sudo dnf install go-musicfox
##### Debian系发行版(Ubuntu、Deepin、UOS等)
###### 从 [星火商店](https://spark-app.store/) 安装。
$ sudo aptss install go-musicfox //二进制包部署,同步较慢
$ sudo aptss install go-musicfox-git //从源码编译,请保持网络通畅
##### Gentoo Linux
###### 从 [gentoo-zh Overlay](https://github.com/microcai/gentoo-zh) 安装
$ eselect repository enable gentoo-zh
$ emerge --sync
$ emerge -a media-sound/go-musicfox
##### NixOS
1. 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
2. 配置 configuration.nix 或使用 Home Manager(推荐)
# configuration.nix
environment.systemPackages = [
pkgs.go-musicfox
];
# home manager
home.packages = [
pkgs.go-musicfox
];
3. 从 Nixpkgs 安装
安装到本地 profile:
$ nix-env -iA nixos.go-musicfox
临时安装:
$ nix-shell -p go-musicfox
##### Void Linux
从 [void-packages-zh](https://github.com/voidlinux-zh-association/void-packages-zh#readme) 安装。
##### 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](https://github.com/go-musicfox/go-musicfox/releases/latest) 下载 Linux 的可执行文件。
### Windows
#### 1. 通过 scoop 安装
scoop bucket add go-musicfox https://github.com/go-musicfox/go-musicfox.git
scoop install go-musicfox
#### 2. 直接下载
在 [Release](https://github.com/go-musicfox/go-musicfox/releases/latest) 下载 Windows 的可执行文件。
### 手动编译
注:需要 Go v1.22 及以上版本
前往 [下载 Go ](https://go.dev/dl/)页面选择适合你的 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](https://github.com/go-musicfox/go-musicfox/issues/99))**
> macOS 用户推荐使用 [iTerm2](https://iterm2.com/) 或 [Kitty](https://sw.kovidgoyal.net/kitty/)
>
> Linux 用户推荐使用 [Kitty](https://sw.kovidgoyal.net/kitty/)
>
> Windows 用户推荐使用 [Windows Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701),使用体验更佳
- 如果在执行文件时遇到以下错误,说明你的操作系统内不包含 `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](https://github.com/microsoft/wslg/issues/864)
- XDG 支持:完整的 XDG 支持,部分文件路径变更,见 [XDG 支持说明](https://github.com/go-musicfox/go-musicfox/blob/HEAD/./docs/xdg_support.md)
- 配置文件格式:使用 [TOML](https://toml.io/) 格式
### 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]` 配置表
- 详细配置参见 [内置主题示例](https://github.com/go-musicfox/go-musicfox/blob/HEAD/./utils/filex/embed/themes/)
终端内实时显示音频频谱(仅 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](https://github.com/go-musicfox/go-musicfox/blob/HEAD/./utils/filex/embed/changelog.md)。
### 启动动画
支持 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二进制文件是不支持全局快捷键的
>
> 如果需要开启,请安装[依赖](https://github.com/go-vgo/robotgo#requirements)后手动进行编译:
>
> ```shell
> BUILD_TAGS=enable_global_hotkey make build
> ```
### 鼠标支持
完整的鼠标交互支持:
- **点击** - 选择菜单项、点击按钮
- **双击** - 快速进入子菜单或播放
- **滚轮** - 上下滚动列表
- **悬停** - 高亮显示可交互元素
- **右键菜单** - 上下文相关的操作菜单
**配置**:
[main]
enableMouseEvent = true # 启用鼠标支持
详见 [鼠标支持说明](https://github.com/go-musicfox/go-musicfox/blob/HEAD/./docs/mouse_support.md)
### 自定义分享模板
分享文本的内容是完全可定制的,它由一套模板系统驱动(使用 [text/template](https://pkg.go.dev/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/bubbletea:基于 bubbletea 进行部分定制
- go-musicfox/netease-music:fork 自 NeteaseCloudMusicApiWithGo ,在原项目的基础上去除 API 功能,只保留 service 和 util 作为一个独立的包,方便在其他 Go 项目中调用
感谢
感谢以下项目及其贡献者们(但不限于):