[!IMPORTANT] これは involvex/youtube-music-cli の非公式フォークであり、ローカル stdio MCP サーバーを追加したものです。アップストリーム、YouTube、Google とは無関係です。このカスタムフォークはソースからビルドされており、アップストリームが宣伝している npm パッケージではありません。

MCP のインストール、ツール、権限、クライアント設定については、mcp/README.md を参照してください。

🎵 youtube-music-cli

YouTube Music のためのパワフルなターミナルユーザーインターフェース（TUI）ミュージックプレイヤー

機能 • インストール • 使い方 • プラグイン • ドキュメント

機能

• 🎨 美しい TUI - React と Ink で構築されたリッチなターミナルインターフェース

• 🔍 検索 - 曲、アルバム、アーティスト、プレイリストを検索

• 📋 キューの管理 - 再生キューの構築と管理

• ❤️ お気に入り - f でトラックをお気に入りに登録し、Shift+F で表示

• 🔀 シャッフルとリピート - 複数の再生モード

• 🎚️ 音量調整 - きめ細かな音量調整

• 💡 スマート提案 - 関連トラックを発見

• 🎨 テーマ - Dark、Light、Midnight、Matrix テーマ

• 🔌 プラグインシステム - プラグインで機能を拡張

• ⌨️ キーボード駆動 - 効率的な vim スタイルのナビゲーション

• 🖥️ イマーシブモード - オーディオビジュアライザーとディスコエフェクトを備えたフルスクリーン Windows TUI

• 💾 ダウンロード - 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 を使用してください。ロードマップドキュメントには、レビュアーとコントリビューターの認識を一致させるための作業の引き継ぎ方も記載されています。

前提条件

必須：

• 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 Releases

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

イマーシブモードのホットキー：

フッターには、シャッフル/リピート/ディスコのステータスが 1 行に、優先ショートカットが次の行に表示されます。ライブラリメニュー（L）からランダムなお気に入りを利用できます。システムトレイアイコンを右クリックすると、設定 または 終了 が表示されます（assets/icon.ico を使用）。

グローバルメディアキー（Alt+メディアキー）は、Bun ランタイムで Windows のターミナルがフォーカスされていない場合にも機能します。

イマーシブ再生のトラブルシューティング

• トラック情報は表示されるが時間が進まない / 音が出ない： Space を押して再開します。イマーシブモードは最後のセッションを自動起動します。mpv が外部で一時停止された場合（画面共有、フォーカス喪失）、UI は PAUSED に同期されるようになりました — もう一度 Space を押してください。

• 画面共有（Discord、Teams、OBS）： リモートの視聴者は、「コンピューターのサウンドを共有」/ システムオーディオキャプチャを有効にしない限り、あなたの PC のオーディオを聞くことができないことがよくあります。これは Windows のキャプチャの制限であり、プレイヤーがオーディオをあなただけにルーティングしているわけではありません。

• Win32 ネイティブ機能には Bun が必要： グローバルホットキーとネイティブコンソールタイトルは、Bun 経由で @bun-win32/* を使用します。bun run dev:win32 またはコンパイル済みの ymc-win32.exe バイナリで実行してください。

シェル補完

CLI に同梱されている軽量な ymc エイリアスを使用して、シェル補完ヘルパーを生成します。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. プルリクエストを開きます

開発

# 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（CLI 用 React）

• 言語： TypeScript

• オーディオ： mpv + yt-dlp

• API： YouTube Music Innertube API

ライセンス

MIT © Involvex

ドキュメント • バグを報告 • 機能をリクエスト

音楽愛好家のために ❤️ を込めて作られました