NetEase-MusicBox
高品质网易云音乐命令行客户端，基于 Python 编写。
感谢为 MusicBox 的开发付出过努力的每一个人。
网易云音乐 API 能力由 NeteaseCloudMusicApiEnhanced/api-enhanced 提供支持。
Demo
功能特性
- 支持多档音质播放：MP3（极高/较高/标准）及无损、高清臻音、超清母带等 FLAC，安装
mpv后自动切换 - 支持歌曲、艺术家、专辑、本地列表模糊搜索
- 支持排行榜、新碟上架、精选歌单、主播电台、我的歌单、我的云盘、私人 FM 和每日推荐
- 支持本地收藏、歌曲评论、专辑跳转、随心打碟和定时退出
- 支持播放进度、播放模式、当前/历史播放列表和桌面歌词显示
- 支持 Vim 风格快捷键、数字快捷键和自定义全局快捷键
安装
推荐用 uv 或 pipx 安装为全局命令 musicbox；参与开发见下文「本地开发」。
环境要求
- Python 3.10 及以上
mpg123（MP3）、mpv（可选，FLAC / Hi-Res）
安装系统依赖
macOS:
brew install mpg123 mpv uv
Ubuntu/Debian:
sudo apt-get install mpg123 mpv
CentOS/Red Hat:
sudo yum install -y python3-devel mpg123 mpv
安装 MusicBox
PyPI（可能落后于源码）：
uv tool install netease-musicbox
# 或 pipx install NetEase-MusicBox源码（全局命令；改代码后需重装，开发期可用 -e）：
git clone https://github.com/darknessomi/musicbox.git cd musicbox uv tool install . # 或 pipx install . uv tool install -e . # 可编辑安装，源码改动即时生效
本地开发（不装全局命令）：
git clone https://github.com/darknessomi/musicbox.git
cd musicbox
uv sync
uv run musicbox可选依赖
aria2：缓存歌曲libnotify-bin：Linux 消息提示qtpy python-dbus dbus qt：桌面歌词。根据系统 Qt 版本，可能还需要安装pyqt4、pyside或pyside2
树莓派 / 老旧设备
Ubuntu 22.04 / 64 位树莓派系统自带 Python 3.10，可用 pipx 直接安装。低性能设备建议先只装 MP3 播放必需依赖，避免一次性拉取 mpv 的大量图形/视频依赖：
sudo apt-get update sudo apt-get install -y --no-install-recommends pipx mpg123 pipx ensurepath pipx install NetEase-MusicBox musicbox
注意：项目要求 Python 3.10 及以上；旧版 Raspberry Pi OS / Debian 如果仍是 Python 3.9，不能直接安装当前版本。
已验证系统
- Ubuntu 24.04 LTS x64
- macOS 26.5
- Raspberry Pi 4 / Ubuntu 22.04 arm64（Docker 镜像：
balenalib/raspberrypi4-64-ubuntu:jammy）
使用
启动 MusicBox：
musicbox
进入需要登录的功能时，终端会显示二维码。登录方式仅支持扫码登录，已不再支持账号密码登录。
- 用网易云音乐手机 App 扫描二维码，并在手机上确认。
- 登录成功后 Cookie 写入
~/.local/share/netease-musicbox/cookie.txt（未设置XDG_DATA_HOME时为~/.netease-musicbox/cookie.txt）。
终端以字符块渲染二维码，窗口建议 ≥25 行、等宽字体。必须使用网易云音乐 App 扫描二维码并在手机上确认，不支持打开 URL 完成登录。
CLI 与 AI Agent
MusicBox 支持命令行和 AI Agent 调用：搜索歌曲、获取播放链接、播放控制、查询状态和登录都可以通过 musicbox 命令完成。
musicbox search 邓丽君 --type song --json musicbox artist 6452 --limit 10 --json musicbox album 32311 --json musicbox song url 1847408145 --quality lossless --quiet musicbox play --id 1847408145 --json musicbox play --artist 6452 --limit 10 musicbox play --album 32311 musicbox play --songs 33894312 28258988 musicbox pause --json musicbox status --json musicbox queue list --json musicbox auth login --no-wait --json musicbox download --playlist 3778678 --path ./music --json
安装 Agent Skill 后，可直接让 Codex、Claude Code、Cursor 等 Agent 操作 MusicBox：
npx skills add darknessomi/musicbox -y
快捷键
带 num + 的快捷键支持数字修饰，先输入数字，再输入被修饰的按键。
| 按键 | 功能 | 说明 |
|---|---|---|
j |
Down | 下移 |
k |
Up | 上移 |
num + j |
Quick Jump | 快速向后跳转 n 首 |
num + k |
Quick Up | 快速向前跳转 n 首 |
h |
Back | 后退 |
l |
Forward | 前进 |
u |
Prev Page | 上一页 |
d |
Next Page | 下一页 |
f |
Search | 当前列表模糊搜索 |
[ |
Prev Song | 上一曲 |
] |
Next Song | 下一曲 |
num + [ |
Quick Prev Song | 快速前 n 首 |
num + ] |
Quick Next Song | 快速后 n 首 |
num + Shift + g |
Index for Song | 跳到第 n 首 |
= |
Volume + | 音量增加 |
- |
Volume - | 音量减少 |
Space |
Play/Pause | 播放/暂停 |
? |
Shuffle | 手气不错 |
m |
Menu | 主菜单 |
p |
Present/History | 当前/历史播放列表 |
i |
Music Info | 当前音乐信息 |
Shift + p |
Playing Mode | 播放模式切换 |
a |
Add | 添加曲目到打碟 |
Shift + a |
Enter Album | 进入专辑 |
g |
To the First | 跳至首项 |
Shift + g |
To the End | 跳至尾项 |
z |
DJ List | 打碟列表 |
s |
Star | 添加到收藏 |
c |
Collection | 收藏列表 |
r |
Remove | 删除当前条目 |
Shift + j |
Move Down | 向下移动当前项目 |
Shift + k |
Move Up | 向上移动当前项目 |
Shift + c |
Cache | 缓存歌曲到本地 |
, |
Like | 喜爱 |
. |
Trash FM | 删除 FM |
/ |
Next FM | 下一 FM |
q |
Quit | 退出 |
t |
Timing Exit | 定时退出 |
w |
Quit & Clear | 退出并清除用户信息 |
配置
配置文件位于 ~/.netease-musicbox/config.json，可配置缓存、快捷键、消息提示和桌面歌词。
无损播放相关配置：
-
music_quality：音质等级，可填数字或 level 名称。配置值 说明 jymaster超清母带，192kHz/24bit 4/hires高清臻音，96kHz/24bit 3/lossless无损，最高 48kHz/16bit 0/exhigh极高，最高 320kbps 1/higher较高，192kbps 2/standard标准，128kbps -
player_backend：默认mpg123；设为mpv则全程用mpv，否则仅 FLAC 自动切到mpv。 -
mpv_parameters: 传给mpv的额外参数列表。
由于歌曲 API 只接受中国大陆地区访问，非中国大陆地区用户需要自行设置代理。可用 polipo 将 socks5 代理转换成 http 代理：
export http_proxy=http://IP:PORT export https_proxy=http://IP:PORT curl -L ip.cn
确认显示 IP 属于中国大陆地区即可。
排错
- 某些歌曲不能播放且总时长为
00:01时，通常是版权问题。 - 特定终端不能播放时，先检查同一终端下
mpg123能否正常使用，再检查其他终端下musicbox能否正常使用。报告 issue 时请附上这些检查结果和终端报错。 - 可通过
tail -f ~/.local/share/netease-musicbox/musicbox.log查看日志。
更新日志
详见 CHANGELOG.md。