mc                          # show status
mc play [SOURCE]            # smart play (auto-detects file/URL/station)
mc play -M focus            # mood-based radio
mc stop / mc s              # stop
mc pause / mc pp            # pause
mc resume / mc r            # resume
mc next / mc n              # next track
mc vol [0-100]              # get/set volume
mc status / mc st           # full status

mc radio                    # list stations
mc radio play N             # play station #N
mc radio add                # add station
mc radio remove N           # remove station
mc radio update             # update station list

mc yt play URL              # stream YouTube audio
mc yt / mc yt list          # list replay history
mc yt play N                # replay a history entry
mc yt remove N / clear      # manage history

mc ai play [-p PROMPT]      # generate AI music
mc ai play --lyrics LYRICS  # lyrics-conditioned models such as MiniMax Music 3
mc ai / mc ai list          # list generated tracks
mc ai replay N              # replay generated track
mc ai model                 # list/download/delete/default models

mc history / mc h            # show play history
mc history play N            # replay from history
mc mood [MOOD]              # list moods or play mood radio

mc config                   # show config paths
mc cloud key set gmi        # store GMI Cloud API key in the system keyring
mc cloud smoke              # one real call per free MiniMax model -> dist/_smoke/

> **API key requirement:** The GMI Cloud key must be authorized for the **audio queue endpoint**
> (`console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests`) — not just the text model endpoint
> (`api.gmi-serving.com`). A key scoped only for text models (e.g. `MiniMaxAI/MiniMax-M3` on the
> serving endpoint) will pass `mc cloud ping` but will fail with `HTTP 400` during `mc studio build`
> because Music 3.0 and Speech 2.8 run as async jobs on the queue endpoint. If your key works for
> text but not audio, you need a key with audio-model access.
>
> Check your key with `mc studio doctor` — it should show `OK: gmi key: stored in the OS keyring`.
mc daemon start|stop|status # manage daemon

Note: music-cli still works as the full command name for all commands.

Use -h or --help at any level for details (e.g. mc -h, mc play -h, mc radio -h).

All old command names continue to work as hidden aliases; they are simply no longer shown in --help.

# Smart play (auto-detects source)
mc play                              # Context-aware radio
mc play ~/song.mp3                   # Local file
mc play "https://youtube.com/..."    # YouTube URL
mc play "deep house"                 # Station name

# Mood-based
mc play -M focus                     # By mood

# Local shuffle
mc play -m local --auto              # Shuffle local files

# AI (requires [ai] extras)
mc ai play -p "happy jazz" -d 60    # Generate a 60s track

# YouTube
mc yt play URL                       # Stream YouTube audio

# History
mc history play 3                    # Replay item #3

# List all stations with numbers
mc radio
mc radio list

# Play by station number
mc radio play 5

# Add a new station interactively
mc radio add

# Remove a station
mc radio remove 10

Pre-configured Stations

100 stations across multiple genres and languages (music_cli/config.py:207-384), each checked to decode real audio with scripts/validate_radios.py:

• Chill/Lo-fi & Ambient: ChillHop, SomaFM (Groove Salad, Drone Zone, Deep Space One), Slow Focus [NTS], Ambient Sleeping Pill
• Electronic: Deep House, DEF CON Radio, Beat Blender, Techno [rautemusik], Radio FG
• Pop/Rock/Indie: Top Hits, 80s Hits, BBC Radio 1/2/6 Music, KEXP, Radio Caroline, Metal [SomaFM]
• Eclectic: Radio Paradise, KCRW Eclectic 24, WFMU, NTS Radio 1, Radio Nova, ByteFM
• Hip-Hop/Soul/Reggae: BBC Radio 1Xtra, Capital XTRA, Seven Inch Soul, Heavyweight Reggae, FIP Reggae
• Synthwave: Nightride FM, Chillsynth FM, Darksynth FM, Datawave FM, Spacesynth FM
• Jazz & Blues: Jazz24, Radio Swiss Jazz, WWOZ New Orleans, TSF Jazz, Jazz Radio Blues
• Country/Folk: Boot Liquor, 181.fm Kickin' Country, Celtic Music Radio
• Classical: Classical (Radio Swiss Classic), BBC Radio 3, Classic FM, Venice Classic Radio, Klassik Radio
• News/Talk: BBC World Service, NPR 24 Hour, Deutschlandfunk, France Inter
• French: FIP (Radio, Rock, Jazz, Electro, Groove, Monde), France Musique, Mouv
• Spanish/Latin: Los 40 Principales, Cadena SER, Cadena 100, Tropical 100 Salsa, Cumbias Inmortales, Argentine Tango Radio
• Italian: Radio Italia, RTL 102.5, Radio 105, Virgin Radio Italy, Radio Deejay, RDS, Radio Capital
• German/Dutch: 1LIVE, Radio Bob, NPO Radio 2, NPO 3FM
• Portuguese: Antena 1 Brasil, Bossa Jazz Brasil, Radio Comercial, Antena 1 Fado
• Asian & World: Listen.moe J-Pop/K-Pop, SBS PopAsia, Mirchi Top 20, Suburbs of Goa, LagosJump Radio, Trace FM, Radio Orient

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
mc ai play                              # Context-aware (default: musicgen-small)
mc ai play -p "jazz piano"              # Custom prompt
mc ai play -m audioldm-s-full-v2        # Use AudioLDM model
mc ai play -m bark-small -p "Hello!"    # Use Bark for speech
mc ai play -M focus -d 30              # 30-second focus track
mc ai model                             # List available models
mc ai list                              # List all generated tracks
mc ai replay 1                          # Replay track #1
mc ai remove 2                          # Delete track #2

Available AI Models

Sizes are the expected download sizes from the model registry (music_cli/sources/ai_models/model_config.py:240-363).

AI Command Suite

AI Features

• Multiple models — MusicGen, AudioLDM, Bark, and optional MiniMax Music 3
• 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

AI Requirements

• ~5GB disk space minimum (PyTorch + Transformers + Diffusers)
• ~8GB RAM minimum for generation (16GB recommended for larger models)
• MiniMax Music 3 uses pip install 'coder-music-cli[minimax]', requires CUDA, bfloat16, and approximately 24GB VRAM
• Models are downloaded on first use

AI Configuration

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 prompt

Stream audio directly from YouTube URLs; every video you play is recorded in a replay history:

# Stream audio from a URL (recorded in replay history)
mc play "https://youtube.com/watch?v=..."
mc play "https://youtu.be/..."

# Manage replay history
mc yt                    # List replay history
mc yt list               # Same as above
mc yt play 3             # Replay history entry #3 (re-extracts the stream)
mc yt remove 1           # Remove history entry #1
mc yt clear              # Clear entire history

YouTube Command Suite

How It Works

• Streaming playback — Audio is extracted with yt-dlp and piped straight into ffplay; nothing is downloaded to disk (music_cli/sources/youtube.py:112-120, music_cli/player/ffplay.py:156)
• Replay history — Played videos are recorded with title/artist/duration, newest first (music_cli/youtube_history.py:92-107)
• History cap — At most 1000 entries are kept (music_cli/youtube_history.py:96)
• Replay — mc yt play <num> re-extracts the stream from the stored URL; if a <video_id>.m4a file was placed manually in youtube_cache/, it is played directly instead (music_cli/daemon_handlers.py:686-708)
• Requires the [youtube] extra, pinned to yt-dlp ≥ 2026.7.4 (pyproject.toml:58-62)

Storage Location

• Linux/macOS: ~/.config/music-cli/youtube_cache.json (history metadata) and youtube_cache/ (music_cli/config.py:304, music_cli/platform/paths.py:88-90)
• Windows: %LOCALAPPDATA%\music-cli\youtube_cache\ (music_cli/platform/paths.py:130-140)

focus happy sad excited relaxed energetic melancholic peaceful

Configuration files location:

• Linux/macOS: ~/.config/music-cli/
• Windows: %LOCALAPPDATA%\music-cli\

Version Updates

When you update music-cli, you'll be notified if new radio stations are available:

# Check and update stations
mc radio update

# 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

Add Custom Stations

# Interactive
mc radio add

# Or edit directly: ~/.config/music-cli/radios.txt
ChillHop|https://streams.example.com/chillhop.mp3
Jazz FM|https://streams.example.com/jazz.mp3

The status command shows playback info plus a random inspirational quote:

$ mc 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.11.0
GitHub: https://github.com/luongnv89/music-cli