[!IMPORTANT] Esta es una bifurcación (fork) no oficial de involvex/youtube-music-cli que añade un servidor MCP local stdio. No está afiliada con el proyecto original, YouTube ni Google. La bifurcación personalizada se compila desde el código fuente y no es el paquete npm anunciado por el proyecto original.

Consulta mcp/README.md para la instalación de MCP, herramientas, permisos y configuración del cliente.

🎵 youtube-music-cli

Un potente reproductor de música con interfaz de usuario de terminal (TUI) para YouTube Music

Características • Instalación • Uso • Plugins • Documentación

Características

• 🎨 Hermosa TUI - Interfaz de terminal enriquecida construida con React e Ink

• 🔍 Búsqueda - Encuentra canciones, álbumes, artistas y listas de reproducción

• 📋 Gestión de cola - Construye y gestiona tu cola de reproducción

• ❤️ Favoritos - Marca pistas como favoritas con f y míralas con Shift+F

• 🔀 Aleatorio y repetición - Múltiples modos de reproducción

• 🎚️ Control de volumen - Ajuste fino del volumen

• 💡 Sugerencias inteligentes - Descubre pistas relacionadas

• 🎨 Temas - Temas oscuro, claro, medianoche, matrix

• 🔌 Sistema de plugins - Extiende la funcionalidad con plugins

• ⌨️ Basado en teclado - Navegación eficiente estilo vim

• 🖥️ Modo inmersivo - TUI de Windows a pantalla completa con visualizador de audio y efectos disco

• 💾 Descargas - Guarda pistas/listas/artistas con Shift+D

• 🏷️ Etiquetado de metadatos - Etiqueta automáticamente título/artista/álbum con carátula opcional

• ⚡️ Completado de shell - ymc completions <bash|zsh|powershell|fish> emite scripts que puedes cargar o guardar para que la CLI (también disponible como ymc) complete subcomandos y banderas con tabulación

Apoya el proyecto original

Si encuentras youtube-music-cli útil, considera apoyar el desarrollo del proyecto original:

• ☕ Buy Me a Coffee

• 🪙 PayPal

• ⌨️ GitHub Sponsors

Tu apoyo ayuda a mantener este proyecto vivo y en mejora.

Hoja de ruta

Visita SUGGESTIONS.md para ver el backlog completo y usa docs/roadmap.md para entender el enfoque de implementación actual (crossfade + reproducción sin interrupciones) y los próximos pasos planificados para ecualizador/mejoras. El documento de hoja de ruta también explica cómo tomar trabajo para que los revisores y contribuyentes permanezcan alineados.

Requisitos previos

Requerido:

• mpv - Reproductor multimedia para reproducción de audio

• yt-dlp - Extracción de audio de YouTube

Instalación de requisitos previos

# 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

Instalación

Node.js (Recomendado)

Requiere Node.js 18+ instalado.

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

Lanzamientos de GitHub

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

Script de instalación (bash)

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

Script de instalación (PowerShell)

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

Desde el código fuente

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

Uso

Modo interactivo

Inicia la TUI:

youtube-music-cli

Comandos CLI

# 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

Modo inmersivo (Windows)

Inicia un reproductor visual a pantalla completa con reproducción real, controles de cola y visualización de audio. Requiere mpv y yt-dlp (igual que la reproducción normal).

# 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

Atajos de teclado en modo inmersivo:

El pie de página muestra el estado de aleatorio/repetición/disco en una línea y los atajos priorizados en la siguiente. El favorito aleatorio está disponible desde el menú de biblioteca (L). Haz clic derecho en el icono de la bandeja del sistema para Ajustes o Salir (usa assets/icon.ico).

Las teclas multimedia globales (Alt+Teclas multimedia) también funcionan cuando la terminal no está enfocada en Windows con el runtime de Bun.

Solución de problemas de reproducción inmersiva

• La información de la pista se muestra pero el tiempo no avanza / no hay audio: Pulsa Space para reanudar. El modo inmersivo inicia automáticamente la última sesión; si mpv fue pausado externamente (compartir pantalla, pérdida de foco), la interfaz ahora se sincroniza con PAUSED — pulsa Space de nuevo.

• Compartir pantalla (Discord, Teams, OBS): Los espectadores remotos a menudo no oyen el audio de tu PC a menos que actives "compartir sonido del ordenador" / captura de audio del sistema. Es una limitación de captura de Windows, no que el reproductor enrute el audio solo hacia ti.

• Requiere Bun para funciones nativas de Win32: Los atajos globales y el título de consola nativo usan @bun-win32/* a través de Bun. Ejecuta con bun run dev:win32 o el binario compilado ymc-win32.exe.

Completado de shell

Genera ayudas de completado de shell a través del alias ligero ymc que viene con la CLI. Ejecuta ymc completions <bash|zsh|powershell|fish> para imprimir el script de completado para tu shell, luego cárgalo o persístelo en tu perfil:

# 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

Si instalaste la CLI globalmente con un alias o nombre de script, asegúrate de que ymc apunte al mismo binario antes de generar los completados para que el script coincida con tu ruta de instalación.

Opciones

Ejemplos

# 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

Atajos de teclado

Global

Reproducción

Navegación

Descargas

Plugins

¡Extiende youtube-music-cli con plugins!

Gestión de plugins

Modo TUI: Pulsa p para abrir el gestor de plugins.

Modo CLI:

# 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

Plugins disponibles

Desarrollo de plugins

Consulta la Guía de desarrollo de plugins y la Referencia de la API de plugins.

# 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

Configuración

La configuración se almacena en ~/.youtube-music-cli/config.json:

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

Calidad de transmisión

Ajustes de descarga

• Habilita/deshabilita descargas en Ajustes (,).

• Establece tu directorio de descargas en Ajustes → Carpeta de descargas.

• Elige el formato en Ajustes → Formato de descarga (mp3 o m4a).

• Las descargas se guardan como:

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

• Los archivos MP3/M4A se etiquetan con metadatos (title, artist, album) e incluyen carátula cuando está disponible.

Solución de problemas

mpv no encontrado

Asegúrate de que mpv esté instalado y en tu PATH:

mpv --version

Al iniciar, la CLI ahora verifica mpv y yt-dlp. En terminales interactivas puede solicitar ejecutar un comando de instalación automáticamente (con confirmación explícita primero).

Sin audio

1. Comprueba que el volumen no esté silenciado (= para subir)

2. Verifica que yt-dlp funcione: yt-dlp --version

3. Prueba con otra pista

Problemas de renderizado de la TUI

Si el renderizado se ve mal, intenta redimensionar la ventana de tu terminal o reiniciar la aplicación.

El plugin no carga

1. Comprueba que la sintaxis de plugin.json sea válida

2. Verifica que el plugin esté habilitado: youtube-music-cli plugins list

3. Revisa los registros para ver errores

Contribuciones

¡Las contribuciones son bienvenidas!

1. Haz un fork del repositorio

2. Crea una rama de características: git checkout -b feature/my-feature

3. Haz tus cambios

4. Ejecuta las pruebas: bun run test

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

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

7. Abre una Pull Request

Desarrollo

# 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

Pila tecnológica

• Runtime: Node.js 18+ / Bun

• Framework de UI: Ink (React para CLI)

• Lenguaje: TypeScript

• Audio: mpv + yt-dlp

• API: YouTube Music Innertube API

Licencia

MIT © Involvex

Documentación • Reportar error • Solicitar función

Hecho con ❤️ para los amantes de la música