Discover NetEase MusicBox: A Python CLI for High‑Quality Cloud Music Playback

Project Overview

NetEase-MusicBox is a command‑line client for NetEase Cloud Music written in Python. It streams 320 kbps audio and provides search, playlists, charts, radio, desktop lyric display, and other typical music‑player features.

Features

320 kbps high‑quality audio

Search by song, artist, or album

Access to 22 NetEase music charts

New‑album recommendations

Curated playlists

Radio stations

Personal playlists and daily recommendations

DJ‑style mixing

Local favorites with love (like) support

Playback progress and mode display

Current track and desktop lyric display

Song comments

One‑click album view

Timed exit

Vim‑style shortcut keys

Numeric shortcut keys

Custom global shortcuts

Keyboard Shortcuts

Installation

PyPI

pip3 install NetEase-MusicBox

macOS

git clone https://github.com/darknessomi/musicbox.git && cd musicbox
python3 setup.py install

Ubuntu/Debian

sudo pip3 install NetEase-MusicBox
sudo apt-get install mpg123

Fedora

sudo dnf install musicbox

Arch Linux

pacaur -S netease-musicbox-git   # or yaourt -S musicbox

Optional Dependencies

aria2 – song caching

python-keybinder – global shortcut support

libnotify-bin – desktop notifications

pyqt, python-dbus, dbus, qt – desktop lyric support (macOS: brew install qt --with-dbus)

Configuration

The configuration file is located at ~/.netease-musicbox/config.json. It allows customizing cache directory, shortcut keys, notification settings, and desktop lyric options. Users outside mainland China must configure an HTTP proxy for the NetEase API.

Supported Systems

Error Handling

If playback fails, first verify that the mpg123 binary works in the current terminal, then test the player in another terminal. Include terminal type and error messages when reporting issues.

Known Issues & Solutions

#374 – Noise or fast‑forward problems in i3wm on Arch Linux; adjust mpg123 configuration.

#404 – Missing lxml in some environments; install via package manager or pip install lxml.

#405 – 32‑bit Python cookie timestamp overflow; use a 64‑bit Python interpreter or copy the cookie file.

#347 – After several minutes of pause, mpg123 stops output; this is a known mpg123 bug with no current fix.

Usage

musicbox

Repository

https://github.com/darknessomi/musicbox