music-cli

🎵 Agent-ready music CLI — JSON output, batch pipe, zero config

English | 中文

---

Features

• 🎯 Multi-source — YouTube, Bilibili, SoundCloud, Bandcamp, Netease
• 📝 Lyrics embedded — Auto-fetch and write ID3 USLT into MP3
• ⚡ Sequential probing — Tries sources in order, stops at first hit
• 🔧 Self-diagnosis — doctor checks yt-dlp, ffmpeg, network
• 📦 Zero config — Works out of the box
• 🤖 Scriptable — All commands support --json for structured output

Install

npm install -g @aimtao/music-cli

Or build from source:

git clone <repo-url>
cd music-cli
bash setup.sh

Requires yt-dlp. ffmpeg is optional.

Usage

# Download a song
music-cli download "Song Name" "Artist Name"

# JSON output
music-cli download "Song Name" "Artist Name" --json

# List downloaded
music-cli list

# Diagnose environment
music-cli doctor

Commands

Command	Description
download	Download songs
list	List downloaded songs
lyrics	Fetch lyrics
doctor	Diagnose environment
sources	List available sources
info	Show system info

Configuration

./config.json

{
  "outputDir": "~/Music/music-cli",
  "sources": ["youtube", "bilibili", "soundcloud", "bandcamp", "netease"],
  "timeout": 10,
  "concurrency": 2,
  "embedLyrics": true
}

License

MIT

---

For AI / Scripts

All commands support --json for structured output.

download

music-cli download "Song Name" "Artist" --json

Batch via stdin:

echo '[{"name":"Song 1","artist":"Artist 1"},{"name":"Song 2","artist":"Artist 2"}]' | music-cli download --json

Success:

{
  "success": true,
  "file": "/Users/.../Music/music-cli/Song Name Artist.mp3",
  "source": "youtube",
  "size": 3856029,
  "lyrics": { "success": true }
}

Failure:

{
  "success": false,
  "error": "All sources failed",
  "tried": ["youtube", "bilibili", "soundcloud", "bandcamp", "netease"]
}

Sources are tried sequentially: YouTube → Bilibili → SoundCloud → Bandcamp → Netease.

list

music-cli list --json

{
  "success": true,
  "total": 5,
  "totalSize": 19281920,
  "songs": [
    { "name": "Song Name Artist", "file": "/path/to/song.mp3", "size": 3856029, "hasLyrics": true }
  ]
}

doctor

music-cli doctor --json

{
  "success": true,
  "tools": { "node": "v20.0.0", "npm": "9.0.0", "yt-dlp": "2024.01.01", "ffmpeg": "6.0" },
  "network": { "youtube": { "reachable": true, "latency": 120 } }
}

Configuration reference

Key	Type	Default	Description
outputDir	string	~/Downloads/music-cli	Download directory
sources	string[]	all 5	Enabled sources
timeout	number	10	Per-source timeout (seconds)
concurrency	number	2	Parallel probe count
embedLyrics	boolean	true	Auto-embed lyrics into MP3

MUSIC_OUTPUT_DIR env var overrides outputDir.

Output files

• MP3: {outputDir}/{song} {artist}.mp3
• Lyrics: embedded as ID3v2.4 USLT (UTF-8), .lrc deleted after embedding

Exit codes

• 0 — Success
• 1 — Failure (check JSON for details)