该项目使用还未停止服务的iflow开发的

软件简介

QQMusicBox 是一款基于终端的QQ音乐播放器，灵感来自网易云音乐命令行版本 musicbox。纯命令行界面，无需图形环境，适合喜欢在终端中操作的用户。

功能特性

• 搜索功能：支持搜索歌曲、专辑、歌手、歌单
• 播放控制：播放、暂停、上一首/下一首、音量调节
• 用户登录：支持二维码扫码登录（VIP会员可播放VIP歌曲）
• 个人中心：我喜欢、我的歌单
• 发现音乐：排行榜、推荐歌单、热门歌曲
• 播放模式：顺序播放、随机播放、单曲循环
• 歌词显示：实时歌词滚动显示

界面预览

  ╔═══════════════════════════════════════╗
  ║     QQ Music Box - 终端音乐播放器      ║
  ╚═══════════════════════════════════════╝

       > 扫码登录
         搜索歌曲
         搜索专辑
         搜索歌手
         热门歌曲
         推荐歌单
         排行榜
         播放列表

  ▶ 歌曲名 - 歌手名  02:30/04:00 [======---] [顺序播放]
  j/k:上下 l:进入 h:返回 空格:暂停 [/]:上下曲 P:模式 q:退出

依赖要求

Python 依赖

• Python >= 3.10
• qqmusic-api-python
• httpx
• rich
• python-dotenv

系统依赖（音频播放器，任选其一）

• mpv（推荐）
• mpg123
• ffmpeg

安装方式

方式一：安装 deb 包（推荐）

适用于 Debian/Ubuntu/Deepin 等 Debian 系发行版：

# 下载 deb 包
wget https://gitee.com/ysdlm/qqmusicbox/releases/download/v1.0.0/qqmusicbox_1.0.0-1_all.deb

# 安装
sudo dpkg -i qqmusicbox_1.0.0-1_all.deb

# 安装 Python 依赖
pip3 install qqmusic-api-python httpx rich python-dotenv --break-system-packages 

# 安装音频播放器
sudo apt install mpv

方式二：从源码安装

# 克隆仓库
git clone https://gitee.com/ysdlm/qqmusicbox.git
cd qqmusicbox

# 安装
pip3 install .

# 安装播放器
sudo apt install mpv

使用方法

启动

qqmusicbox

登录

1. 选择「扫码登录」
2. 用手机 QQ 音乐 APP 扫描二维码
3. 确认登录后即可使用完整功能

快捷键

按键	功能
j/k	上下移动
l	进入/选择
h	返回
空格	暂停/播放
[	上一首
]	下一首
P	切换播放模式
+/-	音量增减
f	搜索
q	退出

配置文件

• 配置文件：~/.config/qqmusicbox/config.json
• 登录凭证：~/.config/qqmusicbox/credential.json
• 缓存目录：~/.cache/qqmusicbox/

常见问题

Q: 无法播放 VIP 歌曲？
A: 请先登录 VIP 账号，选择「扫码登录」用 QQ 音乐 APP 扫码即可。

Q: 提示找不到播放器？
A: 请安装音频播放器：sudo apt install mpv

Q: 登录状态丢失？
A: 凭证保存在 ~/.config/qqmusicbox/credential.json，请检查文件是否存在。

项目地址

• Gitee: https://gitee.com/ysdlm/qqmusicbox

相关链接

• 灵感来源 musicbox: https://github.com/darknessomi/musicbox
• QQ音乐API: https://github.com/L-1124/QQMusicApi

开源协议

MIT License

---

欢迎试用反馈！如有问题或建议，欢迎在评论区留言或提交 Issue。

运行截图