README

NetEase-MusicBox


!PyPI - Version
!PyPI - Python Version


高品质网易云音乐命令行客户端，基于 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:

bash
brew install mpg123 mpv uv


Ubuntu/Debian:

bash
sudo apt-get install mpg123 mpv


CentOS/Red Hat:

bash
sudo yum install -y python3-devel mpg123 mpv


 安装 MusicBox

PyPI（可能落后于源码）：

bash
uv tool install netease-musicbox
 或 pipx install NetEase-MusicBox


源码（全局命令；改代码后需重装，开发期可用 -e）：

bash
git clone https://github.com/darknessomi/musicbox.git
cd musicbox
uv tool install .       或 pipx install .
uv tool install -e .    可编辑安装，源码改动即时生效


本地开发（不装全局命令）：

bash
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 的大量图形/视频依赖：

bash
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：

bash
musicbox


进入需要登录的功能时，终端会显示二维码。登录方式仅支持扫码登录，已不再支持账号密码登录。

1. 用网易云音乐手机 App 扫描二维码，并在手机上确认。
2. 登录成功后 Cookie 写入 ~/.local/share/netease-musicbox/cookie.txt（未设置 XDG_DATA_HOME 时为 ~/.netease-musicbox/cookie.txt）。

终端以字符块渲染二维码，窗口建议 ≥25 行、等宽字体。必须使用网易云音乐 App 扫描二维码并在手机上确认，不支持打开 URL 完成登录。

 CLI 与 AI Agent

MusicBox 支持命令行和 AI Agent 调用：搜索歌曲、获取播放链接、播放控制、查询状态和登录都可以通过 musicbox 命令完成。

bash
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：

bash
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 | 上一