MusicBox (NetEase-MusicBox) is a Python command-line client for NetEase Cloud Music that searches the catalogue, plays tracks and controls playback from a terminal, built for Linux and macOS users who prefer a keyboard-driven player or want an AI agent to drive their music.

What it is

MusicBox is an open-source terminal client for NetEase Cloud Music, written in Python and released under the MIT licence. It renders the service's catalogue as an interactive terminal interface, with Vim-style navigation, playlists, lyrics and playback controls handled entirely from the shell. Its music API layer is provided by NeteaseCloudMusicApiEnhanced/api-enhanced, so the project concentrates on the client experience rather than reverse-engineering endpoints itself.

The concrete problem it solves is access to NetEase Cloud Music without a graphical application. Desktop music players normally require a window, a mouse and a heavier runtime; MusicBox replaces that with a single musicbox command that runs over SSH, on a headless Raspberry Pi, or inside a script. It also exposes the same operations to automation through JSON output, which turns a listening session into something an AI agent or shell script can invoke.

Key capabilities

• Multi-tier audio playback: MP3 at extreme, higher and standard quality, plus FLAC lossless, Hi-Res and ultra-clear master; the client switches to mpv automatically once it is installed.
• Fuzzy search across songs, artists, albums and the local list.
• Browsing surfaces for charts, new releases, curated playlists, DJ radio, my playlists, my cloud disk, personal FM and daily recommendations.
• Vim-style keybindings with numeric modifiers — num + j quick jump, num + Shift + g to jump to a numbered song — alongside custom global hotkeys.
• Scriptable CLI with JSON output, for example musicbox search 邓丽君 --type song --json, musicbox song url 1847408145 --quality lossless --quiet, musicbox status --json and musicbox queue list --json.
• Agent Skill installation through npx skills add darknessomi/musicbox -y, letting Codex, Claude Code and Cursor operate MusicBox directly.
• Local favourites, song comments, album jump, timed exit, play modes, current and history playlists, desktop lyrics, and downloads such as musicbox download --playlist 3778678 --path ./music --json.

Who users it and how

• Desktop Linux and macOS users on the verified systems Ubuntu 24.04 LTS x64 and macOS.
• Raspberry Pi 4 and other low-power devices running Ubuntu 22.04 arm64, where a reduced install of pipx and mpg123 with --no-install-recommends avoids pulling the full mpv graphics and video dependency set.
• Automation and agent workflows that need non-interactive operation, using musicbox auth login --no-wait --json and the --json flags on search, play, pause, status and queue commands.
• Terminal users with a window of at least 25 rows and a monospace font, since login renders the QR code as character blocks.
• NetEase Cloud Music account holders with the mobile app, because QR confirmation on the phone is the only supported login path.

Getting started

Install the system dependencies mpg123 for MP3 and optionally mpv for FLAC and Hi-Res, then install the client as a global command with uv tool install netease-musicbox or pipx install NetEase-MusicBox and run musicbox. Python 3.10 or newer is required.

How it compares

No similar tools are named in the facts, so in this registry MusicBox stands alone as a terminal client in its category. Its only named upstream relationship is the NeteaseCloudMusicApiEnhanced/api-enhanced project that supplies the API capability, which means the client depends on that separate service layer rather than reimplementing it.

When to use it — and when not to

A self-hoster must supply Python 3.10 or newer and the mpg123 playback binary, with optional mpv, aria2 for caching, libnotify-bin for Linux notifications, and a Qt plus dbus stack for desktop lyrics. Choose something else if a graphical player is wanted, if the catalogue must come from a service other than NetEase Cloud Music, or if the environment lacks a phone for QR login, since account and password login is no longer supported. Older Raspberry Pi OS or Debian systems still on Python 3.9 cannot install the current version at all, and the PyPI package may lag behind the source.

brew install mpg123 mpv uv

sudo apt-get install mpg123 mpv

sudo yum install -y python3-devel mpg123 mpv

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

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

sudo apt-get update
sudo apt-get install -y --no-install-recommends pipx mpg123
pipx ensurepath
pipx install NetEase-MusicBox
musicbox

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

npx skills add darknessomi/musicbox -y

export http_proxy=http://IP:PORT
export https_proxy=http://IP:PORT
curl -L ip.cn