go-musicfox (QQ Music)

基于 go-musicfox 改造的 QQ 音乐命令行客户端。

UI 基于 charmbracelet/bubbletea，音频后端支持 AVFoundation (macOS)、Beep (跨平台)、MPV、MPD、DLNA 等。

• ✅ 二维码登录（QQ / 微信）
• ✅ 我的歌单 / 收藏歌单
• ✅ 歌单详情与播放
• ✅ 歌词显示
• ✅ 搜索歌曲
• ✅ 播放模式切换（顺序/循环/随机/单曲）
• ✅ 快捷键操作（按 ? 查看帮助）

无额外依赖，推荐使用 iTerm2 或 Kitty 终端。

# Debian/Ubuntu
sudo apt install libflac-dev libasound2-dev

# Arch
sudo pacman -S flac

# Fedora
sudo dnf install flac-devel

git clone https://github.com/go-musicfox/go-musicfox.git
cd go-musicfox
git checkout qq

# 确保 QQMusicApi 在本机可用（以下二选一）：
# 方式 A：使用 uv（推荐），项目放在相邻目录即可自动发现
git clone https://github.com/luren-dc/QQMusicApi.git ../QQMusicApi

# 方式 B：手动安装到 Python 环境
pip install qqmusic-api

# 编译
make

./bin/musicfox

启动时会自动拉起 Python 后端（hack/qqapi/app.py），退出时自动关闭。

进入主菜单 → 二维码登录 → 用 QQ 或微信扫码。

• 自动启动：Go 端启动时自动拉起 Python 后端
• 版本协商：通过 /api/version 检查已有后端版本，匹配则复用，不匹配则重启
• 自动退出：Go 端退出时通过 stdin pipe 断开 + /api/exit 接口 + 进程组 SIGKILL 三重保险确保 Python 后端退出
• 手动启动：也可单独运行 python hack/qqapi/app.py

按 ? 查看完整帮助。常用快捷键：

路径：

• macOS：$HOME/Library/Application Support/go-musicfox/config.toml
• Linux：$XDG_CONFIG_HOME/go-musicfox/config.toml
• Windows：%AppData%\go-musicfox\config.toml

详见 配置示例。

cmd/                    程序入口
hack/qqapi/             Python QQ 音乐 API 后端
  app.py                HTTP 服务（登录/歌单/播放/歌词/搜索）
  static/               调试用静态页面
internal/
  qqapi/                QQ API Go 客户端 + 后端进程管理
  ui/                   TUI 界面（菜单、播放器、歌词渲染）
  lyric/                歌词解析与服务
  player/               播放引擎（beep/osx/mpv/mpd/dlna）
  ...

• go-musicfox
• QQMusicApi
• bubbletea
• beep