Skip to content

AGENTS.md

Latest commit

 

History

History
41 lines (35 loc) · 2.15 KB

AGENTS.md

File metadata and controls

41 lines (35 loc) · 2.15 KB
Raw

AGENTS.md

Cursor Cloud specific instructions

NetEase-MusicBox is a Python 3.10+ command-line/curses TUI music player, managed with uv. There is a single package (NEMbox) and one product (the musicbox CLI/TUI). Dependencies are refreshed automatically by the startup update script (uv sync --frozen); you do not need to reinstall them.

Running the app

  • Interactive TUI: uv run musicbox — this uses curses and requires a real interactive terminal (TTY). It will not render in a non-TTY/headless shell; use the CLI subcommands below for scripted/agent verification instead.
  • Agent/CLI mode (no TTY needed): uv run musicbox <command>, e.g. search, song url, play, pause, status, queue, daemon, auth. Add --json for machine-readable output. See README.md for the full command list.
  • Playback runs through a background daemon; musicbox play --id <id> auto-starts it and musicbox daemon stop stops it.

Audio backends (system deps, NOT in update script)

  • mpg123 (MP3) and mpv (FLAC / Hi-Res) are OS packages installed via apt-get (sudo apt-get install -y mpg123 mpv). They are pre-installed in the snapshot; reinstall only if musicbox play reports a missing backend. Playback selects mpg123 by default.

Network / API note

  • Song search and playable URLs come from NetEase's public API, which only accepts China-region access. From other regions requests can fail or return empty; set an HTTP proxy (see README "配置") if search stops returning results. In this environment the API was reachable and returned live results.
  • Login is QR-code scan only (renders a QR block in the terminal); there is no username/password login and no test-login secret is required for search/playback.

Lint / test / build

Standard commands (already documented in .cursor/rules/pre-commit-validation.mdc and .github/workflows/ci.yml); run them via uv run:

  • uv run ruff check
  • uv run ruff format --check
  • uv run ty check — emits ~11 diagnostics that are configured as warn in pyproject.toml; it exits 0 and is not a failure.
  • uv run pytest -q --tb=short
  • uv build