music-cli is a background music daemon for developers. Radio streams, local MP3s, YouTube audio, and AI-generated music — all from one command. Stay in flow, skip the browser tab.
- You open Spotify or YouTube to play focus music. Twenty minutes later you're watching a video essay about fonts. Your flow state is gone.
- You want background music while coding, but you don't want another app eating RAM and competing for your audio output.
- You finally find the right playlist... and it ends. Or an ad plays. Or the stream dies. Now you're debugging your music instead of your code.
Developers deserve a music player that respects the way they work: in the terminal, in the background, uninterrupted.
- Zero context-switching. Start, pause, and skip tracks without leaving your terminal. Four keystrokes, not four clicks.
- Always playing. A persistent background daemon means your music survives terminal closes, SSH sessions, and IDE restarts.
- 40+ curated radio stations. Lo-fi, synthwave, deep house, jazz — ready out of the box. No account required.
- AI-generated music. Generate unique focus tracks with MusicGen, AudioLDM, or Bark. Your music, your mood, no subscription.
- YouTube audio streaming. Paste a URL, get audio. Tracks are cached automatically for offline replay.
music-cli play --mood focus # Start focus music
music-cli pause # Pause for a meeting
music-cli resume # Back to coding
music-cli status # What's playing + an inspirational quote- Install — one command, no config files to write.
curl -sSL https://raw.githubusercontent.com/luongnv89/music-cli/main/install.sh | bash - Play — pick a mode: radio, local files, YouTube, or AI.
music-cli play --mood focus
- Forget about it — the daemon runs in the background. Control it whenever you need.
music-cli pause # meeting time music-cli resume # back to work
- Explore — discover 40+ stations, generate AI tracks, or stream from YouTube.
music-cli radios # Browse stations music-cli ai play -p "jazz piano" # Generate a track music-cli play -m youtube -s "URL" # Stream YouTube audio
| Feature | Details |
|---|---|
| Background daemon | Music survives terminal closes and IDE restarts |
| 40+ radio stations | Lo-fi, synthwave, deep house, jazz, French, Spanish, Italian stations — no account needed |
| AI music generation | MusicGen, AudioLDM, Bark — generate unique tracks from text prompts |
| YouTube audio | Paste a URL, stream audio. Automatic offline caching (2GB LRU) |
| Context-aware | Auto-selects music based on time of day and your mood |
| Local MP3 playback | Shuffle your own library with --auto |
| Inspirational quotes | Every status check comes with a random music quote |
| Cross-platform | Linux, macOS, Windows 10+ |
curl -sSL https://raw.githubusercontent.com/luongnv89/music-cli/main/install.sh | bashOr with wget:
wget -qO- https://raw.githubusercontent.com/luongnv89/music-cli/main/install.sh | bashpip install coder-music-cli
# FFmpeg is required
brew install ffmpeg # macOS
sudo apt install ffmpeg # Ubuntu/Debian
choco install ffmpeg # Windows# YouTube streaming support (~10MB)
pip install 'coder-music-cli[youtube]'
# AI music generation (~5GB — PyTorch + Transformers + Diffusers)
pip install 'coder-music-cli[ai]'
# Both
pip install 'coder-music-cli[youtube,ai]'Prefer to inspect the install script first?
curl -sSL https://raw.githubusercontent.com/luongnv89/music-cli/main/install.sh -o install.sh
less install.sh # review
bash install.shIs it free? Yes, 100%. music-cli is MIT licensed, open source, and always will be. No accounts, no subscriptions, no ads.
Does it work on my OS? Linux, macOS, and Windows 10+ are all supported. You need Python 3.10+ and FFmpeg.
How much disk space does AI music need?
The base install is tiny. The [ai] extra downloads ~5GB (PyTorch + HuggingFace models). Models download on first use, not at install time.
How does it compare to Spotify/YouTube Music? music-cli is not a replacement for your music library. It's a lightweight, terminal-native player for background music while coding. No browser tabs, no electron apps, no accounts.
Is it actively maintained? Yes. The latest release is v0.8.14. Check the changelog for recent updates.
Can I add my own radio stations?
Absolutely. Run music-cli radios add or edit ~/.config/music-cli/radios.txt directly. Format: Station Name|stream-url.
What AI models are supported? MusicGen (small/medium/large/melody), AudioLDM (small/large), and Bark (standard/small). See the AI Playbook for examples and tips.
You're one command away from a focus soundtrack that never interrupts you. No signups, no ads, no browser tabs. MIT licensed, open source, and built for developers who live in the terminal.
curl -sSL https://raw.githubusercontent.com/luongnv89/music-cli/main/install.sh | bash && music-cli play --mood focus| Document | Description |
|---|---|
| User Guide | Complete usage instructions |
| AI Playbook | AI music generation guide with examples |
| Architecture | System design and diagrams |
| Development | Contributing guide |
| Changelog | Version history and release notes |
All Commands
| Command | Description |
|---|---|
play |
Start playing (radio/local/ai/history/youtube) |
stop / pause / resume |
Playback control |
status |
Current track, state, and inspirational quote |
next |
Skip track (auto-play mode) |
volume [0-100] |
Get/set volume |
radios |
Manage radio stations (list/play/add/remove) |
youtube |
Manage cached YouTube tracks (list/play/remove/clear) |
ai |
Manage AI-generated tracks (list/play/replay/remove) |
history |
Playback log |
moods |
Available mood tags |
config |
Show configuration file locations |
update-radios |
Update stations after version upgrade |
daemon start|stop|status |
Daemon control |
Play Modes
# Radio (default)
music-cli play # Time-based selection
music-cli play -s "deep house" # By station name
music-cli play --mood focus # By mood
# Local
music-cli play -m local -s song.mp3
music-cli play -m local --auto # Shuffle
# AI (requires [ai] extras)
music-cli play -m ai --mood happy -d 60
# YouTube
music-cli play -m youtube -s "https://youtube.com/watch?v=..."
music-cli play -m yt -s "https://youtu.be/..."
# History
music-cli play -m history -i 3 # Replay item #3Radio Station Management
# List all stations with numbers
music-cli radios
music-cli radios list
# Play by station number
music-cli radios play 5
# Add a new station interactively
music-cli radios add
# Remove a station
music-cli radios remove 1040 stations across multiple genres and languages:
- Chill/Lo-fi: ChillHop, SomaFM (Groove Salad, Drone Zone, Space Station)
- Electronic: Deep House, DEF CON Radio, Beat Blender
- Synthwave: Nightride FM, Chillsynth FM, Darksynth FM, Datawave FM, Spacesynth FM
- French: FIP Radio, France Inter, France Musique, Mouv
- Spanish: Salsa Radio, Tropical 100, Los 40 Principales, Cadena SER
- Italian: Radio Italia, RTL 102.5, Radio 105, Virgin Radio Italy
AI Music Generation
Generate unique audio with multiple AI models via HuggingFace:
# Install AI dependencies (~5GB: PyTorch + Transformers + Diffusers)
pip install 'coder-music-cli[ai]'
# Generate and manage AI music
music-cli ai play # Context-aware (default: musicgen-small)
music-cli ai play -p "jazz piano" # Custom prompt
music-cli ai play -m audioldm-s-full-v2 # Use AudioLDM model
music-cli ai play -m bark-small -p "Hello!" # Use Bark for speech
music-cli ai play --mood focus -d 30 # 30-second focus track
music-cli ai models # List available models
music-cli ai list # List all generated tracks
music-cli ai replay 1 # Replay track #1
music-cli ai remove 2 # Delete track #2| Model ID | Type | Best For | Size |
|---|---|---|---|
musicgen-small |
MusicGen | Music generation (default) | ~1.5GB |
musicgen-medium |
MusicGen | Higher quality music | ~3GB |
musicgen-large |
MusicGen | Best quality music | ~6GB |
musicgen-melody |
MusicGen | Melody-conditioned music | ~3GB |
audioldm-s-full-v2 |
AudioLDM | Sound effects, ambient audio | ~1GB |
audioldm-l-full |
AudioLDM | High-quality audio generation | ~2GB |
bark |
Bark | Speech synthesis, audio with voice | ~5GB |
bark-small |
Bark | Faster speech synthesis | ~1.5GB |
| Command | Description |
|---|---|
ai models |
List all available AI models |
ai list |
Show all AI-generated tracks with prompts |
ai play |
Generate music from current context |
ai play -m <model> |
Generate with specific model |
ai play -p "prompt" |
Generate with custom prompt |
ai play --mood focus |
Generate with specific mood |
ai play -d 30 |
Generate 30-second track (default: 5s) |
ai replay <num> |
Replay track by number (regenerates if file missing) |
ai remove <num> |
Delete track and audio file |
- Multiple models — MusicGen, AudioLDM, and Bark model families
- Smart caching — LRU cache keeps up to 2 models in memory (configurable)
- Download progress — Progress bar shown during model downloads
- GPU memory management — Automatic cleanup when switching models
- Context-aware — Uses time of day, day of week, and session mood
- Custom prompts — Generate exactly what you want with
-p - Seamless looping — All tracks engineered for infinite playback
- Track management — List, replay, and remove generated tracks
- Regeneration — Missing files can be regenerated with original prompt
- ~5GB disk space minimum (PyTorch + Transformers + Diffusers)
- ~8GB RAM minimum for generation (16GB recommended for larger models)
- Models are downloaded on first use
Configure in ~/.config/music-cli/config.toml:
[ai]
default_model = "musicgen-small" # Default model for generation
[ai.cache]
max_models = 2 # Max models to keep in memory (LRU eviction)
[ai.models.audioldm-s-full-v2.extra_params]
num_inference_steps = 10 # More = better quality, slower
guidance_scale = 2.5 # How closely to follow promptYouTube Audio Streaming & Cache
Stream audio directly from YouTube URLs with automatic offline caching:
# Play YouTube audio (automatically cached)
music-cli play -m youtube -s "https://youtube.com/watch?v=..."
music-cli play -m yt -s "https://youtu.be/..." # Short alias
# Manage cached tracks
music-cli youtube # List all cached tracks
music-cli youtube cached # Same as above
music-cli youtube play 3 # Play cached track #3 (works offline)
music-cli youtube remove 1 # Remove cached track #1
music-cli youtube clear # Clear entire cache| Command | Description |
|---|---|
youtube |
List all cached tracks (default) |
youtube cached |
List cached tracks with cache statistics |
youtube play <num> |
Play cached track by number (offline) |
youtube remove <num> |
Remove a cached track |
youtube clear |
Clear all cached tracks |
- Automatic caching — Audio cached in background while streaming
- Offline playback — Play cached tracks without internet
- LRU eviction — 2GB cache limit with automatic cleanup of oldest tracks
- M4A format — 192kbps quality for good balance of size and quality
- Instant replay — Cached tracks play immediately
Configure in ~/.config/music-cli/config.toml:
[youtube.cache]
enabled = true # Enable/disable automatic caching
max_size_gb = 2.0 # Maximum cache size in GB- Linux/macOS:
~/.config/music-cli/youtube_cache/ - Windows:
%LOCALAPPDATA%\music-cli\youtube_cache\
Moods
focus happy sad excited relaxed energetic melancholic peaceful
Configuration
Configuration files location:
- Linux/macOS:
~/.config/music-cli/ - Windows:
%LOCALAPPDATA%\music-cli\
| File | Purpose |
|---|---|
config.toml |
Settings (volume, mood mappings, version) |
radios.txt |
Station URLs (name|url format) |
history.jsonl |
Play history |
ai_tracks.json |
AI track metadata (prompts, durations) |
ai_music/ |
AI-generated audio files |
youtube_cache.json |
YouTube cache metadata |
youtube_cache/ |
Cached YouTube audio files |
When you update music-cli, you'll be notified if new radio stations are available:
# Check and update stations
music-cli update-radios
# Options:
# [M] Merge - Add new stations to your list (recommended)
# [O] Overwrite - Replace with new defaults (backs up old file)
# [K] Keep - Keep your current stations unchanged# Interactive
music-cli radios add
# Or edit directly: ~/.config/music-cli/radios.txt
ChillHop|https://streams.example.com/chillhop.mp3
Jazz FM|https://streams.example.com/jazz.mp3Status & Quotes
The status command shows playback info plus a random inspirational quote:
$ music-cli status
Status: ▶ playing
Track: Groove Salad [radio]
Volume: 80%
Context: morning / weekday
"Music gives a soul to the universe, wings to the mind, flight to the imagination." - Plato
Version: 0.3.0
GitHub: https://github.com/luongnv89/music-cli- Python 3.10+
- FFmpeg
- Supported Platforms: Linux, macOS, Windows 10+
Thanks to all contributors who have helped improve music-cli!
| Contributor | PR | Contribution |
|---|---|---|
| kylephillipsau | #5 | Improved YouTube livestream playback for radio stations by piping yt-dlp to ffplay for reliable HLS buffering and reconnections |
music-cli is built with these excellent open-source libraries:
| Library | Maintainer | Purpose |
|---|---|---|
| Click | Pallets | CLI framework for building commands and argument parsing |
| tomli | hukkin | TOML parser for reading configuration files |
| tomli-w | hukkin | TOML writer for saving configuration files |
| pyobjc | Ronald Oussoren | macOS framework bindings for media key support |
| dbus-next | altdesktop | D-Bus client for Linux MPRIS media controls |
| PyTorch | PyTorch Team | Deep learning framework powering AI music generation |
| Transformers | Hugging Face | Pre-trained models for MusicGen and Bark |
| Diffusers | Hugging Face | Diffusion models for AudioLDM audio generation |
| SciPy | SciPy Community | Scientific computing for audio signal processing |
| tqdm | tqdm developers | Progress bars for model downloads and generation |
| yt-dlp | yt-dlp Team | YouTube audio extraction and streaming |
MIT