[!IMPORTANT] Dies ist ein inoffizieller Fork von involvex/youtube-music-cli der einen lokalen stdio-MCP-Server hinzufügt. Er ist nicht mit dem Upstream, YouTube oder Google verbunden. Der benutzerdefinierte Fork wird aus dem Quellcode erstellt und ist nicht das npm-Paket, das vom Upstream beworben wird.

Siehe mcp/README.md für MCP-Installation, Tools, Berechtigungen und Client-Konfiguration.

🎵 youtube-music-cli

Ein leistungsstarker Musikplayer mit Terminal-Benutzeroberfläche (TUI) für YouTube Music

Funktionen • Installation • Verwendung • Plugins • Dokumentation

Funktionen

• 🎨 Schöne TUI – Reichhaltige Terminal-Oberfläche, erstellt mit React und Ink

• 🔍 Suche – Finde Songs, Alben, Künstler und Playlists

• 📋 Warteschlangenverwaltung – Erstelle und verwalte deine Wiedergabewarteschlange

• ❤️ Favoriten – Markiere Titel mit f als Favoriten und zeige sie mit Shift+F an

• 🔀 Zufallswiedergabe & Wiederholung – Mehrere Wiedergabemodi

• 🎚️ Lautstärkeregelung – Fein abgestimmte Lautstärkeeinstellung

• 💡 Intelligente Vorschläge – Entdecke verwandte Titel

• 🎨 Themes – Dunkel, Hell, Mitternacht, Matrix-Themes

• 🔌 Plugin-System – Erweitere die Funktionalität mit Plugins

• ⌨️ Tastaturgesteuert – Effiziente Navigation im Vim-Stil

• 🖥️ Immersiver Modus – Vollbild-Windows-TUI mit Audio-Visualizer und Disco-Effekten

• 💾 Downloads – Speichere Titel/Playlists/Künstler mit Shift+D

• 🏷️ Metadaten-Tagging – Automatisches Taggen von Titel/Künstler/Album mit optionalem Cover-Art

• ⚡️ Shell-Vervollständigung – ymc completions <bash|zsh|powershell|fish> erzeugt Skripte, die du einbinden oder speichern kannst, damit die CLI (auch als ymc verfügbar) Unterbefehle und Flags per Tab vervollständigt.

Unterstütze das Upstream-Projekt

Wenn du youtube-music-cli nützlich findest, erwäge, die Entwicklung des Upstream-Projekts zu unterstützen:

• ☕ Buy Me a Coffee

• 🪙 PayPal

• ⌨️ GitHub Sponsors

Deine Unterstützung hilft, dieses Projekt am Leben zu erhalten und zu verbessern!

Roadmap

Besuche SUGGESTIONS.md für das vollständige Backlog und nutze docs/roadmap.md, um den aktuellen Implementierungsschwerpunkt (Crossfade + nahtlose Wiedergabe) und die nächsten geplanten Schritte für Equalizer/Verbesserungen zu verstehen. Das Roadmap-Dokument erklärt auch, wie man Aufgaben übernimmt, damit Prüfer und Mitwirkende abgestimmt bleiben.

Voraussetzungen

Erforderlich:

• mpv – Medienplayer für die Audiowiedergabe

• yt-dlp – YouTube-Audioextraktion

Installation der Voraussetzungen

# With Scoop
scoop install mpv yt-dlp

# With Chocolatey
choco install mpv yt-dlp

brew install mpv yt-dlp

# Ubuntu/Debian
sudo apt install mpv
pip install yt-dlp

# Arch Linux
sudo pacman -S mpv yt-dlp

# Fedora
sudo dnf install mpv yt-dlp

Installation

Node.js (Empfohlen)

Erfordert installiertes Node.js 18+.

npm install -g @involvex/youtube-music-cli

Bun

bun install -g @involvex/youtube-music-cli

Homebrew

brew tap involvex/youtube-music-cli https://github.com/involvex/youtube-music-cli.git
brew install youtube-music-cli

GitHub Releases

https://github.com/involvex/youtube-music-cli/releases

Installationsskript (bash)

curl -fssl https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.sh | bash

Installationsskript (PowerShell)

iwr https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.ps1 | iex

Aus dem Quellcode

git clone https://github.com/involvex/youtube-music-cli.git
cd youtube-music-cli

# With bun (recommended for development)
bun install
bun run build
bun link

# With npm
npm install
npm run build
npm link

Verwendung

Interaktiver Modus

Starte die TUI:

youtube-music-cli

CLI-Befehle

# Play a specific track
youtube-music-cli play <video-id|youtube-url>

# Search for music
youtube-music-cli search "artist or song name"

# Play a playlist
youtube-music-cli playlist <playlist-id>

# Get suggestions based on current track
youtube-music-cli suggestions

# Playback control
youtube-music-cli pause
youtube-music-cli resume
youtube-music-cli skip
youtube-music-cli back

Immersiver Modus (Windows)

Starte einen Vollbild-Player mit visueller Darstellung, echter Wiedergabe, Warteschlangensteuerung und Audio-Visualisierung. Erfordert mpv und yt-dlp (wie bei der normalen Wiedergabe).

# Standard immersive mode
youtube-music-cli --win32

# Search and play immediately
youtube-music-cli --win32 --search "artist song"

# With disco mode enabled
DISCO_MODE=true youtube-music-cli --win32

# Standalone Windows binary (Bun compile)
bun run build:win32
dist/ymc-win32.exe

Hotkeys im immersiven Modus:

Die Fußzeile zeigt den Status von Zufallswiedergabe/Wiederholung/Disco in einer Zeile und priorisierte Tastenkürzel in der nächsten. Zufälliger Favorit ist über das Bibliotheksmenü (L) verfügbar. Klicke mit der rechten Maustaste auf das Symbol im System-Tray für Einstellungen oder Beenden (verwendet assets/icon.ico).

Globale Medientasten (Alt+Medientasten) funktionieren auch, wenn das Terminal unter Windows mit Bun-Laufzeit nicht fokussiert ist.

Fehlerbehebung bei immersiver Wiedergabe

• Titelinfo wird angezeigt, aber die Zeit bewegt sich nicht / kein Audio: Drücke Space, um fortzufahren. Der immersive Modus startet automatisch die letzte Sitzung; wenn mpv extern pausiert wurde (Bildschirmfreigabe, Fokusverlust), synchronisiert sich die UI jetzt auf PAUSED – drücke erneut Space.

• Bildschirmfreigabe (Discord, Teams, OBS): Remote-Zuschauer hören oft dein PC-Audio nicht, es sei denn, du aktivierst „Computersound teilen“ / Systemaudio-Erfassung. Das ist eine Windows-Erfassungsbeschränkung, nicht der Player, der Audio nur an dich leitet.

• Erfordert Bun für Win32-native Funktionen: Globale Hotkeys und der native Konsolentitel verwenden @bun-win32/* über Bun. Führe bun run dev:win32 oder die kompilierte ymc-win32.exe-Binärdatei aus.

Shell-Vervollständigung

Erzeuge Shell-Vervollständigungshelfer über den schlanken ymc-Alias, der mit der CLI geliefert wird. Führe ymc completions <bash|zsh|powershell|fish> aus, um das Vervollständigungsskript für deine Shell auszugeben, und binde es dann ein oder speichere es in deinem Profil:

# Bash
source <(ymc completions bash)
ymc completions bash >> ~/.bash_completion

# Zsh
source <(ymc completions zsh)

# PowerShell
ymc completions powershell | Out-File -Encoding utf8 $PROFILE
Invoke-Expression (ymc completions powershell)

# Fish
ymc completions fish > ~/.config/fish/completions/ymc.fish

Wenn du die CLI global mit einem Alias oder Skriptnamen installiert hast, stelle sicher, dass ymc auf dieselbe Binärdatei zeigt, bevor du Vervollständigungen generierst, damit das Skript zu deinem Installationspfad passt.

Optionen

Beispiele

# Launch with matrix theme at 80% volume
youtube-music-cli --theme=matrix --volume=80

# Search and play in headless mode
youtube-music-cli search "lofi beats" --headless

# Play with shuffle enabled
youtube-music-cli play dQw4w9WgXcQ --shuffle

Tastaturkürzel

Global

Wiedergabe

Navigation

Downloads

Plugins

Erweitere youtube-music-cli mit Plugins!

Plugins verwalten

TUI-Modus: Drücke p, um den Plugin-Manager zu öffnen.

CLI-Modus:

# List installed plugins
youtube-music-cli plugins list

# Install from default repository
youtube-music-cli plugins install adblock

# Install from GitHub URL
youtube-music-cli plugins install https://github.com/user/my-plugin

# Enable/disable
youtube-music-cli plugins enable my-plugin
youtube-music-cli plugins disable my-plugin

# Update
youtube-music-cli plugins update my-plugin

# Remove
youtube-music-cli plugins remove my-plugin

Verfügbare Plugins

Plugins entwickeln

Siehe Plugin-Entwicklungsleitfaden und Plugin-API-Referenz.

# Start from a template
cp -r templates/plugin-basic my-plugin
cd my-plugin

# Edit plugin.json and index.ts
# Install for testing
youtube-music-cli plugins install /path/to/my-plugin

Konfiguration

Die Konfiguration wird in ~/.youtube-music-cli/config.json gespeichert:

{
	"theme": "dark",
	"volume": 70,
	"shuffle": false,
	"repeat": "off",
	"streamQuality": "high",
	"downloadsEnabled": false,
	"downloadDirectory": "D:/Music/youtube-music-cli",
	"downloadFormat": "mp3"
}

Stream-Qualität

Download-Einstellungen

• Downloads in Einstellungen (,) aktivieren/deaktivieren.

• Lege dein Download-Verzeichnis unter Einstellungen → Download-Ordner fest.

• Wähle das Format unter Einstellungen → Download-Format (mp3 oder m4a).

• Downloads werden gespeichert als:

  • <downloadDirectory>/<artist>/<album>/<title>.mp3 (oder .m4a)

• MP3/M4A-Dateien werden mit Metadaten (title, artist, album) getaggt und enthalten, wenn verfügbar, Cover-Art.

Fehlerbehebung

mpv nicht gefunden

Stelle sicher, dass mpv installiert und in deinem PATH ist:

mpv --version

Beim Start prüft die CLI jetzt auf mpv und yt-dlp. In interaktiven Terminals kann sie automatisch zur Ausführung eines Installationsbefehls auffordern (mit vorheriger ausdrücklicher Bestätigung).

Kein Audio

1. Überprüfe, ob die Lautstärke nicht stummgeschaltet ist (= zum Erhöhen)

2. Verifiziere, dass yt-dlp funktioniert: yt-dlp --version

3. Versuche einen anderen Titel

TUI-Darstellungsprobleme

Wenn die Darstellung falsch aussieht, versuche, das Terminalfenster zu vergrößern oder die App neu zu starten.

Plugin wird nicht geladen

1. Überprüfe, ob die Syntax von plugin.json gültig ist

2. Verifiziere, dass das Plugin aktiviert ist: youtube-music-cli plugins list

3. Prüfe die Logs auf Fehler

Mitwirken

Beiträge sind willkommen!

1. Forke das Repository

2. Erstelle einen Feature-Branch: git checkout -b feature/my-feature

3. Nimm deine Änderungen vor

4. Führe Tests aus: bun run test

5. Committe: git commit -m 'feat: add my feature'

6. Pushe: git push origin feature/my-feature

7. Öffne einen Pull Request

Entwicklung

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build
bun run build

# Lint and format
bun run lint:fix
bun run format

# Type check
bun run typecheck

Technologie-Stack

• Laufzeit: Node.js 18+ / Bun

• UI-Framework: Ink (React für CLI)

• Sprache: TypeScript

• Audio: mpv + yt-dlp

• API: YouTube Music Innertube API

Lizenz

MIT © Involvex

Dokumentation • Fehler melden • Feature anfragen

Mit ❤️ für Musikliebhaber gemacht