{"id":35699361,"url":"https://github.com/luongnv89/music-cli","last_synced_at":"2026-01-13T21:49:01.335Z","repository":{"id":331034228,"uuid":"1124945647","full_name":"luongnv89/music-cli","owner":"luongnv89","description":"A command-line music player for coders. Background daemon with radio streaming, local MP3s, and AI-generated music.","archived":false,"fork":false,"pushed_at":"2026-01-10T22:53:46.000Z","size":3686,"stargazers_count":24,"open_issues_count":2,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T06:54:00.959Z","etag":null,"topics":["coder","music-player","programming","terminal"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luongnv89.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-29T22:28:06.000Z","updated_at":"2026-01-10T22:53:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luongnv89/music-cli","commit_stats":null,"previous_names":["luongnv89/music-cli"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/luongnv89/music-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fmusic-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fmusic-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fmusic-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fmusic-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luongnv89","download_url":"https://codeload.github.com/luongnv89/music-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fmusic-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28401061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coder","music-player","programming","terminal"],"created_at":"2026-01-06T01:12:44.142Z","updated_at":"2026-01-13T21:49:01.329Z","avatar_url":"https://github.com/luongnv89.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo/logo-mark.svg\" alt=\"music-cli logo\" width=\"80\" height=\"80\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003emusic-cli\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eCode. Listen. Iterate.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/coder-music-cli/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/coder-music-cli.svg\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pepy.tech/project/coder-music-cli\"\u003e\u003cimg src=\"https://static.pepy.tech/badge/coder-music-cli\" alt=\"PyPI Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10+-blue.svg\" alt=\"Python 3.10+\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"music-cli-ai.gif\" alt=\"music-cli AI demo\" width=\"600\"\u003e\n\u003c/p\u003e\n\nA command-line music player for coders. Background daemon with radio streaming, local MP3s, and AI-generated music.\n\n```bash\nmusic-cli play --mood focus    # Start focus music\nmusic-cli pause                # Pause for meeting\nmusic-cli resume               # Back to coding\nmusic-cli status               # Check what's playing + inspirational quote\n```\n\n## Installation\n\n```bash\n# Install from PyPI\npip install coder-music-cli\n\n# Or with uv (faster)\nuv pip install coder-music-cli\n\n# Install FFmpeg (required)\nbrew install ffmpeg       # macOS\nsudo apt install ffmpeg   # Ubuntu/Debian\nchoco install ffmpeg      # Windows (or: winget install ffmpeg)\n```\n\n### Optional: AI Music Generation\n\n```bash\npip install 'coder-music-cli[ai]'  # ~5GB (PyTorch + Transformers + Diffusers)\n```\n\nSupports multiple AI models via HuggingFace: MusicGen, AudioLDM, and Bark.\n\n### Optional: YouTube Audio Streaming\n\n```bash\npip install 'coder-music-cli[youtube]'  # ~10MB (yt-dlp)\n```\n\nStream audio directly from YouTube URLs with automatic offline caching:\n\n```bash\nmusic-cli play -m youtube -s \"https://youtube.com/watch?v=...\"\nmusic-cli play -m yt -s \"https://youtu.be/...\"  # Short alias\nmusic-cli youtube                               # List cached tracks\nmusic-cli youtube play 1                        # Play cached track offline\n```\n\n## Features\n- **Daemon-based** - Persistent background playback\n- **Multiple sources** - Local files, radio streams, AI generation, **YouTube audio streaming**\n- **Context-aware** - Selects music based on time of day and mood\n- **40+ Radio Stations** - Curated stations in English, French, Spanish, Italian, and Synthwave\n- **AI Music Generation** - Generate music with MusicGen, AudioLDM, or Bark models\n- **YouTube Streaming** - Extract and stream audio directly from YouTube URLs\n- **YouTube Offline Cache** - Automatically cache YouTube audio for offline playback\n- **Version-aware Updates** - Automatic notification when new stations are available\n- **Inspirational Quotes** - Random music quotes with every status check\n- **Simple config** - Human-readable text files\n\n## Quick Start\n\n```bash\n# Play\nmusic-cli play                    # Context-aware radio\nmusic-cli play --mood focus       # Focus music\nmusic-cli play -m local --auto    # Shuffle local library\nmusic-cli play -m youtube -s \"https://youtube.com/watch?v=...\"  # YouTube audio\nmusic-cli play -m yt -s \"https://youtu.be/...\"  # YouTube (short alias)\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `play` | Start playing (radio/local/ai/history/youtube) |\n| `stop` / `pause` / `resume` | Playback control |\n| `status` | Current track, state, and inspirational quote |\n| `next` | Skip track (auto-play mode) |\n| `volume [0-100]` | Get/set volume |\n| `radios` | Manage radio stations (list/play/add/remove) |\n| `youtube` | Manage cached YouTube tracks (list/play/remove/clear) |\n| `ai` | Manage AI-generated tracks (list/play/replay/remove) |\n| `history` | Playback log |\n| `moods` | Available mood tags |\n| `config` | Show configuration file locations |\n| `update-radios` | Update stations after version upgrade |\n| `daemon start\\|stop\\|status` | Daemon control |\n\n## Radio Station Management\n\n```bash\n# List all stations with numbers\nmusic-cli radios\nmusic-cli radios list\n\n# Play by station number\nmusic-cli radios play 5\n\n# Add a new station interactively\nmusic-cli radios add\n\n# Remove a station\nmusic-cli radios remove 10\n```\n\n### Pre-configured Stations\n\n40 stations across multiple genres and languages:\n\n- **Chill/Lo-fi**: ChillHop, SomaFM (Groove Salad, Drone Zone, Space Station)\n- **Electronic**: Deep House, DEF CON Radio, Beat Blender\n- **Synthwave**: Nightride FM, Chillsynth FM, Darksynth FM, Datawave FM, Spacesynth FM\n- **French**: FIP Radio, France Inter, France Musique, Mouv\n- **Spanish**: Salsa Radio, Tropical 100, Los 40 Principales, Cadena SER\n- **Italian**: Radio Italia, RTL 102.5, Radio 105, Virgin Radio Italy\n\n## Play Modes\n\n```bash\n# Radio (default)\nmusic-cli play                     # Time-based selection\nmusic-cli play -s \"deep house\"     # By station name\nmusic-cli play --mood focus        # By mood\n\n# Local\nmusic-cli play -m local -s song.mp3\nmusic-cli play -m local --auto     # Shuffle\n\n# AI (requires [ai] extras)\nmusic-cli play -m ai --mood happy -d 60\n\n# History\nmusic-cli play -m history -i 3     # Replay item #3\n```\n\n## AI Music Generation\n\nGenerate unique audio with multiple AI models via HuggingFace:\n\n```bash\n# Install AI dependencies (~5GB: PyTorch + Transformers + Diffusers)\npip install 'coder-music-cli[ai]'\n\n# Generate and manage AI music\nmusic-cli ai play                              # Context-aware (default: musicgen-small)\nmusic-cli ai play -p \"jazz piano\"              # Custom prompt\nmusic-cli ai play -m audioldm-s-full-v2        # Use AudioLDM model\nmusic-cli ai play -m bark-small -p \"Hello!\"    # Use Bark for speech\nmusic-cli ai play --mood focus -d 30           # 30-second focus track\nmusic-cli ai models                            # List available models\nmusic-cli ai list                              # List all generated tracks\nmusic-cli ai replay 1                          # Replay track #1\nmusic-cli ai remove 2                          # Delete track #2\n```\n\n### Available AI Models\n\n| Model ID | Type | Best For | Size |\n|----------|------|----------|------|\n| `musicgen-small` | MusicGen | Music generation (default) | ~1.5GB |\n| `musicgen-medium` | MusicGen | Higher quality music | ~3GB |\n| `musicgen-large` | MusicGen | Best quality music | ~6GB |\n| `musicgen-melody` | MusicGen | Melody-conditioned music | ~3GB |\n| `audioldm-s-full-v2` | AudioLDM | Sound effects, ambient audio | ~1GB |\n| `audioldm-l-full` | AudioLDM | High-quality audio generation | ~2GB |\n| `bark` | Bark | Speech synthesis, audio with voice | ~5GB |\n| `bark-small` | Bark | Faster speech synthesis | ~1.5GB |\n\n### AI Command Suite\n\n| Command | Description |\n|---------|-------------|\n| `ai models` | List all available AI models |\n| `ai list` | Show all AI-generated tracks with prompts |\n| `ai play` | Generate music from current context |\n| `ai play -m \u003cmodel\u003e` | Generate with specific model |\n| `ai play -p \"prompt\"` | Generate with custom prompt |\n| `ai play --mood focus` | Generate with specific mood |\n| `ai play -d 30` | Generate 30-second track (default: 5s) |\n| `ai replay \u003cnum\u003e` | Replay track by number (regenerates if file missing) |\n| `ai remove \u003cnum\u003e` | Delete track and audio file |\n\n### Features\n- **Multiple models** - MusicGen, AudioLDM, and Bark model families\n- **Smart caching** - LRU cache keeps up to 2 models in memory (configurable)\n- **Download progress** - Progress bar shown during model downloads\n- **GPU memory management** - Automatic cleanup when switching models\n- **Context-aware** - Uses time of day, day of week, and session mood\n- **Custom prompts** - Generate exactly what you want with `-p`\n- **Seamless looping** - All tracks engineered for infinite playback\n- **Track management** - List, replay, and remove generated tracks\n- **Regeneration** - Missing files can be regenerated with original prompt\n- **Animated feedback** - \"composing...\" animation while generating\n- **Persistent storage** - Tracks saved to config directory\n\n### Requirements\n- ~5GB disk space minimum (PyTorch + Transformers + Diffusers)\n- ~8GB RAM minimum for generation (16GB recommended for larger models)\n- Models are downloaded on first use\n\n### Configuration\n\nConfigure AI settings in `~/.config/music-cli/config.toml`:\n\n```toml\n[ai]\ndefault_model = \"musicgen-small\"  # Default model for generation\n\n[ai.cache]\nmax_models = 2  # Max models to keep in memory (LRU eviction)\n\n[ai.models.audioldm-s-full-v2.extra_params]\nnum_inference_steps = 10  # More = better quality, slower\nguidance_scale = 2.5      # How closely to follow prompt\n```\n\n## YouTube Offline Cache\n\nYouTube audio is automatically cached for offline playback. When you play a YouTube URL, the audio is downloaded in the background and stored locally.\n\n```bash\n# Play YouTube audio (automatically cached)\nmusic-cli play -m youtube -s \"https://youtube.com/watch?v=...\"\n\n# Manage cached tracks\nmusic-cli youtube                    # List all cached tracks\nmusic-cli youtube cached             # Same as above\nmusic-cli youtube play 3             # Play cached track #3 (works offline)\nmusic-cli youtube remove 1           # Remove cached track #1\nmusic-cli youtube clear              # Clear entire cache\n```\n\n### YouTube Command Suite\n\n| Command | Description |\n|---------|-------------|\n| `youtube` | List all cached tracks (default) |\n| `youtube cached` | List cached tracks with cache statistics |\n| `youtube play \u003cnum\u003e` | Play cached track by number (offline) |\n| `youtube remove \u003cnum\u003e` | Remove a cached track |\n| `youtube clear` | Clear all cached tracks |\n\n### Features\n- **Automatic caching** - Audio cached in background while streaming\n- **Offline playback** - Play cached tracks without internet\n- **LRU eviction** - 2GB cache limit with automatic cleanup of oldest tracks\n- **M4A format** - 192kbps quality for good balance of size and quality\n- **Instant replay** - Cached tracks play immediately\n\n### Configuration\n\nConfigure YouTube cache in `~/.config/music-cli/config.toml`:\n\n```toml\n[youtube.cache]\nenabled = true          # Enable/disable automatic caching\nmax_size_gb = 2.0       # Maximum cache size in GB\n```\n\n### Cache Location\n\nCached files are stored in:\n- **Linux/macOS**: `~/.config/music-cli/youtube_cache/`\n- **Windows**: `%LOCALAPPDATA%\\music-cli\\youtube_cache\\`\n\n## Moods\n\n`focus` `happy` `sad` `excited` `relaxed` `energetic` `melancholic` `peaceful`\n\n## Configuration\n\nConfiguration files location:\n- **Linux/macOS**: `~/.config/music-cli/`\n- **Windows**: `%LOCALAPPDATA%\\music-cli\\`\n\n| File | Purpose |\n|------|---------|\n| `config.toml` | Settings (volume, mood mappings, version) |\n| `radios.txt` | Station URLs (name\\|url format) |\n| `history.jsonl` | Play history |\n| `ai_tracks.json` | AI track metadata (prompts, durations) |\n| `ai_music/` | AI-generated audio files |\n| `youtube_cache.json` | YouTube cache metadata |\n| `youtube_cache/` | Cached YouTube audio files |\n\n### Version Updates\n\nWhen you update music-cli, you'll be notified if new radio stations are available:\n\n```bash\n# Check and update stations\nmusic-cli update-radios\n\n# Options:\n# [M] Merge   - Add new stations to your list (recommended)\n# [O] Overwrite - Replace with new defaults (backs up old file)\n# [K] Keep    - Keep your current stations unchanged\n```\n\n### Add Custom Stations\n\n```bash\n# Interactive\nmusic-cli radios add\n\n# Or edit directly: ~/.config/music-cli/radios.txt\nChillHop|https://streams.example.com/chillhop.mp3\nJazz FM|https://streams.example.com/jazz.mp3\n```\n\n## Status \u0026 Quotes\n\nThe `status` command shows playback info plus a random inspirational quote:\n\n```bash\n$ music-cli status\nStatus: ▶ playing\nTrack: Groove Salad [radio]\nVolume: 80%\nContext: morning / weekday\n\n\"Music gives a soul to the universe, wings to the mind, flight to the imagination.\" - Plato\n\nVersion: 0.3.0\nGitHub: https://github.com/luongnv89/music-cli\n```\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [User Guide](docs/user-guide.md) | Complete usage instructions |\n| [AI Playbook](docs/AI_PLAYBOOK.md) | AI music generation guide with examples |\n| [Architecture](docs/architecture.md) | System design and diagrams |\n| [Development](docs/development.md) | Contributing guide |\n| [Changelog](CHANGELOG.md) | Version history and release notes |\n\n## Requirements\n\n- Python 3.10+\n- FFmpeg\n- **Supported Platforms**: Linux, macOS, Windows 10+\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes.\n\n## Contributors\n\nThanks to all contributors who have helped improve music-cli!\n\n| Contributor | PR | Contribution |\n|-------------|-----|--------------|\n| [kylephillipsau](https://github.com/kylephillipsau) | [#5](https://github.com/luongnv89/music-cli/pull/5) | Improved YouTube livestream playback for radio stations by piping yt-dlp to ffplay for reliable HLS buffering and reconnections |\n\n## Acknowledgements\n\nmusic-cli is built with these excellent open-source libraries:\n\n| Library | Maintainer | Purpose |\n|---------|------------|---------|\n| [Click](https://github.com/pallets/click) | [Pallets](https://github.com/pallets) | CLI framework for building commands and argument parsing |\n| [tomli](https://github.com/hukkin/tomli) | [hukkin](https://github.com/hukkin) | TOML parser for reading configuration files |\n| [tomli-w](https://github.com/hukkin/tomli-w) | [hukkin](https://github.com/hukkin) | TOML writer for saving configuration files |\n| [pyobjc](https://github.com/ronaldoussoren/pyobjc) | [Ronald Oussoren](https://github.com/ronaldoussoren) | macOS framework bindings for media key support |\n| [dbus-next](https://github.com/altdesktop/python-dbus-next) | [altdesktop](https://github.com/altdesktop) | D-Bus client for Linux MPRIS media controls |\n| [PyTorch](https://github.com/pytorch/pytorch) | [PyTorch Team](https://github.com/pytorch) | Deep learning framework powering AI music generation |\n| [Transformers](https://github.com/huggingface/transformers) | [Hugging Face](https://github.com/huggingface) | Pre-trained models for MusicGen and Bark |\n| [Diffusers](https://github.com/huggingface/diffusers) | [Hugging Face](https://github.com/huggingface) | Diffusion models for AudioLDM audio generation |\n| [SciPy](https://github.com/scipy/scipy) | [SciPy Community](https://github.com/scipy) | Scientific computing for audio signal processing |\n| [tqdm](https://github.com/tqdm/tqdm) | [tqdm developers](https://github.com/tqdm) | Progress bars for model downloads and generation |\n| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | [yt-dlp Team](https://github.com/yt-dlp) | YouTube audio extraction and streaming |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluongnv89%2Fmusic-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluongnv89%2Fmusic-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluongnv89%2Fmusic-cli/lists"}