[!IMPORTANT] Это неофициальный форк involvex/youtube-music-cli, который добавляет локальный stdio MCP-сервер. Он не связан с вышестоящим проектом, YouTube или Google. Кастомный форк собирается из исходников и не является npm-пакетом, рекламируемым вышестоящим проектом.

См. mcp/README.md для установки MCP, инструментов, разрешений и настройки клиента.

🎵 youtube-music-cli

Мощный музыкальный плеер с терминальным интерфейсом (TUI) для YouTube Music

Возможности • Установка • Использование • Плагины • Документация

Возможности

• 🎨 Красивый TUI — Богатый терминальный интерфейс на React и Ink

• 🔍 Поиск — Находите песни, альбомы, исполнителей и плейлисты

• 📋 Управление очередью — Создавайте и управляйте очередью воспроизведения

• ❤️ Избранное — Отмечайте треки как избранные с помощью f и просматривайте их с помощью Shift+F

• 🔀 Перемешивание и повтор — Несколько режимов воспроизведения

• 🎚️ Регулировка громкости — Точная настройка громкости

• 💡 Умные рекомендации — Открывайте похожие треки

• 🎨 Темы — Темы Dark, Light, Midnight, Matrix

• 🔌 Система плагинов — Расширяйте функциональность с помощью плагинов

• ⌨️ Управление с клавиатуры — Эффективная навигация в стиле vim

• 🖥️ Иммерсивный режим — Полноэкранный TUI для Windows с визуализатором аудио и диско-эффектами

• 💾 Загрузки — Сохраняйте треки/плейлисты/исполнителей с помощью Shift+D

• 🏷️ Теги метаданных — Автоматическое добавление названия/исполнителя/альбома с опциональной обложкой

• ⚡️ Автодополнение в оболочке — ymc completions <bash|zsh|powershell|fish> выводит скрипты, которые можно подключить или сохранить, чтобы CLI (также доступен как ymc) дополнял подкоманды и флаги по табуляции

Поддержка вышестоящего проекта

Если вы находите youtube-music-cli полезным, рассмотрите возможность поддержать разработку вышестоящего проекта:

• ☕ Buy Me a Coffee

• 🪙 PayPal

• ⌨️ GitHub Sponsors

Ваша поддержка помогает проекту оставаться живым и развиваться!

Дорожная карта

Посетите SUGGESTIONS.md для полного списка задач и используйте docs/roadmap.md, чтобы понять текущий фокус реализации (crossfade + gapless playback) и следующие шаги, запланированные для эквалайзера/улучшений. Документ дорожной карты также объясняет, как выбрать задачу, чтобы рецензенты и контрибьюторы оставались согласованными.

Предварительные требования

Обязательные:

• mpv — Медиаплеер для воспроизведения аудио

• yt-dlp — Извлечение аудио с YouTube

Установка предварительных требований

# 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

Установка

Node.js (рекомендуется)

Требуется 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

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

Скрипт установки (bash)

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

Скрипт установки (PowerShell)

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

Из исходников

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

Использование

Интерактивный режим

Запустите TUI:

youtube-music-cli

Команды 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

Иммерсивный режим (Windows)

Запустите полноэкранный визуальный плеер с реальным воспроизведением, управлением очередью и визуализацией аудио. Требуются mpv и yt-dlp (как и для обычного воспроизведения).

# 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

Горячие клавиши в иммерсивном режиме:

В нижнем колонтитуле отображается статус перемешивания/повтора/диско на одной строке и приоритетные сочетания клавиш на следующей. Случайное избранное доступно из меню библиотеки (L). Щёлкните правой кнопкой мыши по значку в системном трее для Настроек или Выхода (используется assets/icon.ico).

Глобальные медиаклавиши (Alt+Media keys) также работают, когда терминал не в фокусе, в Windows с рантаймом Bun.

Устранение неполадок иммерсивного воспроизведения

• Информация о треке отображается, но время не идёт / нет звука: Нажмите Space, чтобы возобновить. Иммерсивный режим автоматически запускает последнюю сессию; если mpv был приостановлен извне (демонстрация экрана, потеря фокуса), интерфейс теперь синхронизируется с PAUSED — нажмите Space ещё раз.

• Демонстрация экрана (Discord, Teams, OBS): Удалённые зрители часто не слышат звук вашего ПК, если вы не включите «общий звук компьютера» / захват системного аудио. Это ограничение захвата Windows, а не то, что плеер направляет звук только вам.

• Требуется Bun для нативных функций Win32: Глобальные горячие клавиши и собственный заголовок консоли используют @bun-win32/* через Bun. Запускайте с bun run dev:win32 или скомпилированным бинарником ymc-win32.exe.

Автодополнение в оболочке

Создайте помощники автодополнения через лёгкий алиас ymc, который поставляется с CLI. Выполните ymc completions <bash|zsh|powershell|fish>, чтобы вывести скрипт автодополнения для вашей оболочки, затем подключите его или сохраните в профиле:

# 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

Если вы установили CLI глобально с алиасом или именем скрипта, убедитесь, что ymc указывает на тот же бинарник перед генерацией автодополнений, чтобы скрипт соответствовал вашему пути установки.

Параметры

Примеры

# 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

Сочетания клавиш

Глобальные

Воспроизведение

Навигация

Загрузки

Плагины

Расширяйте youtube-music-cli с помощью плагинов!

Управление плагинами

Режим TUI: Нажмите p, чтобы открыть менеджер плагинов.

Режим 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

Доступные плагины

Разработка плагинов

См. Руководство по разработке плагинов и Справочник API плагинов.

# 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

Конфигурация

Конфигурация хранится в ~/.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"
}

Качество потока

Настройки загрузки

• Включите/отключите загрузки в Настройках (,).

• Укажите каталог загрузки в Настройки → Папка загрузки.

• Выберите формат в Настройки → Формат загрузки (mp3 или m4a).

• Загрузки сохраняются как:

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

• Файлы MP3/M4A тегируются метаданными (title, artist, album) и включают обложку, если она доступна.

Устранение неполадок

mpv не найден

Убедитесь, что mpv установлен и находится в PATH:

mpv --version

При запуске CLI теперь проверяет наличие mpv и yt-dlp. В интерактивных терминалах он может предложить автоматически выполнить команду установки (с явным подтверждением).

Нет звука

1. Проверьте, что громкость не отключена (= для увеличения)

2. Убедитесь, что yt-dlp работает: yt-dlp --version

3. Попробуйте другой трек

Проблемы с отрисовкой TUI

Если отрисовка выглядит неправильно, попробуйте изменить размер окна терминала или перезапустить приложение.

Плагин не загружается

1. Проверьте, что синтаксис plugin.json корректен

2. Убедитесь, что плагин включён: youtube-music-cli plugins list

3. Проверьте журналы на наличие ошибок

Вклад в проект

Вклад приветствуется!

1. Сделайте форк репозитория

2. Создайте ветку для функции: git checkout -b feature/my-feature

3. Внесите изменения

4. Запустите тесты: bun run test

5. Закоммитьте: git commit -m 'feat: add my feature'

6. Запушьте: git push origin feature/my-feature

7. Откройте Pull Request

Разработка

# 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

Технологический стек

• Рантайм: Node.js 18+ / Bun

• UI-фреймворк: Ink (React для CLI)

• Язык: TypeScript

• Аудио: mpv + yt-dlp

• API: YouTube Music Innertube API

Лицензия

MIT © Involvex

Документация • Сообщить об ошибке • Запросить функцию

Сделано с ❤️ для любителей музыки