{"id":44949512,"url":"https://github.com/involvex/youtube-music-cli","last_synced_at":"2026-04-02T17:02:25.510Z","repository":{"id":339117186,"uuid":"1157600927","full_name":"involvex/youtube-music-cli","owner":"involvex","description":"A powerful Terminal User Interface (TUI) music player for YouTube Music","archived":false,"fork":false,"pushed_at":"2026-03-28T20:21:30.000Z","size":3333,"stargazers_count":261,"open_issues_count":6,"forks_count":14,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-28T22:25:27.029Z","etag":null,"topics":["cli","youtube","youtube-cli","youtube-music","youtube-music-client"],"latest_commit_sha":null,"homepage":"https://involvex.github.io/youtube-music-cli/","language":"TypeScript","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/involvex.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"docs/support.md","governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["involvex"],"custom":["https://buymeacoffee.com/involvex","https://paypal.me/involvex","https://rewards.bing.com/welcome?rh=14525F68\u0026ref=rafsrchae\u0026form=ML2XE3\u0026OCID=ML2XE3\u0026PUBL=RewardsDO\u0026CREA=ML2XE3"]}},"created_at":"2026-02-14T02:46:01.000Z","updated_at":"2026-03-28T20:21:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/involvex/youtube-music-cli","commit_stats":null,"previous_names":["involvex/youtube-music-cli"],"tags_count":63,"template":false,"template_full_name":null,"purl":"pkg:github/involvex/youtube-music-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/involvex%2Fyoutube-music-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/involvex%2Fyoutube-music-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/involvex%2Fyoutube-music-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/involvex%2Fyoutube-music-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/involvex","download_url":"https://codeload.github.com/involvex/youtube-music-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/involvex%2Fyoutube-music-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31311017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["cli","youtube","youtube-cli","youtube-music","youtube-music-client"],"created_at":"2026-02-18T10:06:43.505Z","updated_at":"2026-04-02T17:02:25.503Z","avatar_url":"https://github.com/involvex.png","language":"TypeScript","funding_links":["https://github.com/sponsors/involvex","https://buymeacoffee.com/involvex","https://paypal.me/involvex","https://rewards.bing.com/welcome?rh=14525F68\u0026ref=rafsrchae\u0026form=ML2XE3\u0026OCID=ML2XE3\u0026PUBL=RewardsDO\u0026CREA=ML2XE3"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🎵 youtube-music-cli\n\nA powerful Terminal User Interface (TUI) music player for YouTube Music\n\n[![npm version](https://img.shields.io/npm/v/@involvex/youtube-music-cli.svg)](https://www.npmjs.com/package/@involvex/youtube-music-cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Plugins](#plugins) • [Documentation](https://involvex.github.io/youtube-music-cli)\n\n\u003c/div\u003e\n\n---\n\n## Features\n\n- 🎨 **Beautiful TUI** - Rich terminal interface built with React and Ink\n- 🔍 **Search** - Find songs, albums, artists, and playlists\n- 📋 **Queue Management** - Build and manage your playback queue\n- ❤️ **Favorites** - Mark tracks as favorites with `f` and view them with `Shift+F`\n- 🔀 **Shuffle \u0026 Repeat** - Multiple playback modes\n- 🎚️ **Volume Control** - Fine-grained volume adjustment\n- 💡 **Smart Suggestions** - Discover related tracks\n- 🎨 **Themes** - Dark, Light, Midnight, Matrix themes\n- 🔌 **Plugin System** - Extend functionality with plugins\n- ⌨️ **Keyboard-Driven** - Efficient vim-style navigation\n- 🖥️ **Headless Mode** - Run without TUI for scripting\n- 💾 **Downloads** - Save tracks/playlists/artists with `Shift+D`\n- 🏷️ **Metadata Tagging** - Auto-tag title/artist/album with optional cover art\n- ⚡️ **Shell Completions** - `ymc completions \u003cbash|zsh|powershell|fish\u003e` emits scripts you can source or save so the CLI (also available as `ymc`) tab-completes subcommands and flags\n\n## Roadmap\n\nVisit [`SUGGESTIONS.md`](SUGGESTIONS.md) for the full backlog and use `docs/roadmap.md` to understand the current implementation focus (crossfade + gapless playback) and the next steps planned for equalizer/enhancements. The roadmap doc also explains how to pick up work so reviewers and contributors remain aligned.\n\n## Prerequisites\n\n**Required:**\n\n- [mpv](https://mpv.io/) - Media player for audio playback\n- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - YouTube audio extraction\n\n### Installing Prerequisites\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindows\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# With Scoop\nscoop install mpv yt-dlp\n\n# With Chocolatey\nchoco install mpv yt-dlp\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003emacOS\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nbrew install mpv yt-dlp\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLinux\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Ubuntu/Debian\nsudo apt install mpv\npip install yt-dlp\n\n# Arch Linux\nsudo pacman -S mpv yt-dlp\n\n# Fedora\nsudo dnf install mpv yt-dlp\n```\n\n\u003c/details\u003e\n\n## Installation\n\n### npm (Recommended)\n\n```bash\nnpm install -g @involvex/youtube-music-cli\n```\n\n### Bun\n\n```bash\nbun install -g @involvex/youtube-music-cli\n```\n\n### Homebrew\n\n```bash\nbrew tap involvex/youtube-music-cli https://github.com/involvex/youtube-music-cli.git\nbrew install youtube-music-cli\n```\n\n### GitHub Releases\n\n```bash\nhttps://github.com/involvex/youtube-music-cli/releases\n```\n\n### Install Script (bash)\n\n```bash\ncurl -fssl https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.sh | bash\n```\n\n### Install Script (PowerShell)\n\n```powershell\niwr https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.ps1 | iex\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/involvex/youtube-music-cli.git\ncd youtube-music-cli\nbun install\nbun run build\nbun link\n```\n\n## Usage\n\n### Interactive Mode\n\nLaunch the TUI:\n\n```bash\nyoutube-music-cli\n```\n\n### CLI Commands\n\n```bash\n# Play a specific track\nyoutube-music-cli play \u003cvideo-id|youtube-url\u003e\n\n# Search for music\nyoutube-music-cli search \"artist or song name\"\n\n# Play a playlist\nyoutube-music-cli playlist \u003cplaylist-id\u003e\n\n# Get suggestions based on current track\nyoutube-music-cli suggestions\n\n# Playback control\nyoutube-music-cli pause\nyoutube-music-cli resume\nyoutube-music-cli skip\nyoutube-music-cli back\n```\n\n### Shell completions\n\nGenerate shell completion helpers through the lightweight `ymc` alias that ships with the CLI. Run `ymc completions \u003cbash|zsh|powershell|fish\u003e` to print the completion script for your shell, then source it or persist it in your profile:\n\n```bash\n# Bash\nsource \u003c(ymc completions bash)\nymc completions bash \u003e\u003e ~/.bash_completion\n\n# Zsh\nsource \u003c(ymc completions zsh)\n\n# PowerShell\nymc completions powershell | Out-File -Encoding utf8 $PROFILE\nInvoke-Expression (ymc completions powershell)\n\n# Fish\nymc completions fish \u003e ~/.config/fish/completions/ymc.fish\n```\n\nIf you installed the CLI globally with an alias or script name, make sure `ymc` points at the same binary before generating completions so that the script matches your install path.\n\n### Options\n\n| Flag         | Short | Description                                  |\n| ------------ | ----- | -------------------------------------------- |\n| `--theme`    | `-t`  | Theme: `dark`, `light`, `midnight`, `matrix` |\n| `--volume`   | `-v`  | Initial volume (0-100)                       |\n| `--shuffle`  | `-s`  | Enable shuffle mode                          |\n| `--repeat`   | `-r`  | Repeat mode: `off`, `all`, `one`             |\n| `--headless` |       | Run without TUI                              |\n| `--help`     | `-h`  | Show help                                    |\n\n### Examples\n\n```bash\n# Launch with matrix theme at 80% volume\nyoutube-music-cli --theme=matrix --volume=80\n\n# Search and play in headless mode\nyoutube-music-cli search \"lofi beats\" --headless\n\n# Play with shuffle enabled\nyoutube-music-cli play dQw4w9WgXcQ --shuffle\n```\n\n## Keyboard Shortcuts\n\n### Global\n\n| Key       | Action          |\n| --------- | --------------- |\n| `?`       | Show help       |\n| `/`       | Search          |\n| `p`       | Plugins manager |\n| `Shift+F` | Favorites view  |\n| `g`       | Suggestions     |\n| `,`       | Settings        |\n| `Esc`     | Go back         |\n| `q`       | Quit            |\n\n### Playback\n\n| Key       | Action            |\n| --------- | ----------------- |\n| `Space`   | Play / Pause      |\n| `n` / `→` | Next track        |\n| `b` / `←` | Previous track    |\n| `Shift+→` | Seek forward 10s  |\n| `Shift+←` | Seek backward 10s |\n| `=`       | Volume up         |\n| `-`       | Volume down       |\n| `f`       | Toggle favorite   |\n| `s`       | Toggle shuffle    |\n| `r`       | Cycle repeat mode |\n\n### Navigation\n\n| Key       | Action    |\n| --------- | --------- |\n| `↑` / `k` | Move up   |\n| `↓` / `j` | Move down |\n| `Enter`   | Select    |\n| `Esc`     | Back      |\n\n### Downloads\n\n| Key       | Action                                                  |\n| --------- | ------------------------------------------------------- |\n| `Shift+D` | Download selected song/artist/playlist or playlist view |\n\n## Plugins\n\nExtend youtube-music-cli with plugins!\n\n### Managing Plugins\n\n**TUI Mode:** Press `p` to open the plugins manager.\n\n**CLI Mode:**\n\n```bash\n# List installed plugins\nyoutube-music-cli plugins list\n\n# Install from default repository\nyoutube-music-cli plugins install adblock\n\n# Install from GitHub URL\nyoutube-music-cli plugins install https://github.com/user/my-plugin\n\n# Enable/disable\nyoutube-music-cli plugins enable my-plugin\nyoutube-music-cli plugins disable my-plugin\n\n# Update\nyoutube-music-cli plugins update my-plugin\n\n# Remove\nyoutube-music-cli plugins remove my-plugin\n```\n\n### Available Plugins\n\n| Plugin          | Description                             |\n| --------------- | --------------------------------------- |\n| `adblock`       | Block ads and sponsored content         |\n| `lyrics`        | Display synchronized lyrics             |\n| `scrobbler`     | Scrobble to Last.fm                     |\n| `discord-rpc`   | Discord Rich Presence integration       |\n| `notifications` | Desktop notifications for track changes |\n\n### Developing Plugins\n\nSee [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md) and [Plugin API Reference](docs/PLUGIN_API.md).\n\n```bash\n# Start from a template\ncp -r templates/plugin-basic my-plugin\ncd my-plugin\n\n# Edit plugin.json and index.ts\n# Install for testing\nyoutube-music-cli plugins install /path/to/my-plugin\n```\n\n## Configuration\n\nConfig is stored in `~/.youtube-music-cli/config.json`:\n\n```json\n{\n\t\"theme\": \"dark\",\n\t\"volume\": 70,\n\t\"shuffle\": false,\n\t\"repeat\": \"off\",\n\t\"streamQuality\": \"high\",\n\t\"downloadsEnabled\": false,\n\t\"downloadDirectory\": \"D:/Music/youtube-music-cli\",\n\t\"downloadFormat\": \"mp3\"\n}\n```\n\n### Stream Quality\n\n| Quality  | Description             |\n| -------- | ----------------------- |\n| `low`    | 64kbps - Save bandwidth |\n| `medium` | 128kbps - Balanced      |\n| `high`   | 256kbps+ - Best quality |\n\n### Download Settings\n\n- Enable/disable downloads in **Settings** (`,`).\n- Set your download directory in **Settings → Download Folder**.\n- Choose format in **Settings → Download Format** (`mp3` or `m4a`).\n- Downloads are saved as:\n  - `\u003cdownloadDirectory\u003e/\u003cartist\u003e/\u003calbum\u003e/\u003ctitle\u003e.mp3` (or `.m4a`)\n- MP3/M4A files are tagged with metadata (`title`, `artist`, `album`) and include cover art when available.\n\n## Troubleshooting\n\n### mpv not found\n\nEnsure mpv is installed and in your PATH:\n\n```bash\nmpv --version\n```\n\nOn startup, the CLI now checks for `mpv` and `yt-dlp`. In interactive terminals it can prompt to run an install command automatically (with explicit confirmation first).\n\n### No audio\n\n1. Check volume isn't muted (`=` to increase)\n2. Verify yt-dlp is working: `yt-dlp --version`\n3. Try a different track\n\n### TUI rendering issues\n\nIf rendering looks wrong, try resizing your terminal window or restarting the app.\n\n### Plugin not loading\n\n1. Check `plugin.json` syntax is valid\n2. Verify the plugin is enabled: `youtube-music-cli plugins list`\n3. Check logs for errors\n\n## Contributing\n\nContributions are welcome!\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Make your changes\n4. Run tests: `bun run test`\n5. Commit: `git commit -m 'feat: add my feature'`\n6. Push: `git push origin feature/my-feature`\n7. Open a Pull Request\n\n### Development\n\n```bash\n# Install dependencies\nbun install\n\n# Run in development mode\nbun run dev\n\n# Build\nbun run build\n\n# Lint and format\nbun run lint:fix\nbun run format\n\n# Type check\nbun run typecheck\n```\n\n## Tech Stack\n\n- **Runtime:** [Bun](https://bun.sh/) / Node.js\n- **UI Framework:** [Ink](https://github.com/vadimdemedes/ink) (React for CLI)\n- **Language:** TypeScript\n- **Audio:** mpv + yt-dlp\n- **API:** YouTube Music Innertube API\n\n## License\n\nMIT © [Involvex](https://github.com/involvex)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[Documentation](https://involvex.github.io/youtube-music-cli)** • **[Report Bug](https://github.com/involvex/youtube-music-cli/issues)** • **[Request Feature](https://github.com/involvex/youtube-music-cli/issues)**\n\nMade with ❤️ for music lovers\n\n\u003c/div\u003e\n\n## Supporting\n\n**[☕ Buymeacoffee](https://buymeacoffee.com/involvex)**\n\n**[🪙 Paypal](https://paypal.me/involvex)**\n\n**[⌨️ Github Sponsors](https://github.com/sponsors/involvex)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finvolvex%2Fyoutube-music-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finvolvex%2Fyoutube-music-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finvolvex%2Fyoutube-music-cli/lists"}