th-ch/youtube-music

⭐ 25,040 🍴 1,347 TypeScript📄 MIT License GitHubで見る →

主な特徴

**40以上の組み込みプラグイン**: 幅広い機能拡張を選択的に利用可能
**広告ブロック**: 複数の手法で広告をスキップまたは高速化
**Discord Rich Presence**: 再生中の曲をDiscordに表示
**音楽ダウンロード**: youtube-dlを使用したMP3ダウンロード
**歌詞表示**: 複数のソースからの同期歌詞表示
**オーディオエンハンスメント**: イコライザー、クロスフェード、コンプレッサー等
**ビジュアライザー**: 複数の音楽視覚化エフェクト
**テーマカスタマイズ**: アルバムアートベースの動的テーマ等
**グローバルショートカット**: キーボードショートカットとメディアキー対応
**SponsorBlock統合**: 非音楽セグメントの自動スキップ

リポジトリ解析: th-ch/youtube-music

基本情報

リポジトリ名: th-ch/youtube-music
主要言語: TypeScript
スター数: 25,040
フォーク数: 1,347
最終更新: バージョン3.9.0（継続的に更新中）
ライセンス: MIT License
トピックス: YouTube Music、Electron、デスクトップアプリ、プラグインシステム、オープンソース

概要

一言で言うと

YouTube MusicのWebインターフェースをElectronでラップし、40以上のカスタマイズ用プラグインをバンドルしたデスクトップアプリケーション。

詳細説明

YouTube Music Desktop Appは、YouTube Musicの公式Webインターフェースをベースに、Electronフレームワークを使用してデスクトップアプリ化したプロジェクトです。単なるラッパーではなく、強力なプラグインシステムを通じて、Web版では不可能な様々な機能拡張を可能にしています。

ユーザーは広告ブロック、Discord連携、曲のダウンロード、歌詞表示、オーディオエンハンスメント、ビジュアライザーなど、多彩な機能を自由に有効/無効化でき、自分好みの音楽体験を構築できます。

主な特徴

40以上の組み込みプラグイン: 幅広い機能拡張を選択的に利用可能
広告ブロック: 複数の手法で広告をスキップまたは高速化
Discord Rich Presence: 再生中の曲をDiscordに表示
音楽ダウンロード: youtube-dlを使用したMP3ダウンロード
歌詞表示: 複数のソースからの同期歌詞表示
オーディオエンハンスメント: イコライザー、クロスフェード、コンプレッサー等
ビジュアライザー: 複数の音楽視覚化エフェクト
テーマカスタマイズ: アルバムアートベースの動的テーマ等
グローバルショートカット: キーボードショートカットとメディアキー対応
SponsorBlock統合: 非音楽セグメントの自動スキップ

使用方法

インストール

前提条件

OS: Windows、macOS、Linux
アーキテクチャ: x64、arm64
メモリ: 2GB以上推奨

インストール手順

# Windows - Scoopを使用
scoop bucket add extras
scoop install extras/youtube-music

# Windows - Wingetを使用
winget install th-ch.YouTubeMusic

# macOS - Homebrewを使用
brew install th-ch/youtube-music/youtube-music

# Linux - AUR（Arch Linux）
yay -S youtube-music-bin

# AppImage、Flatpak、Snap、DEB、RPMパッケージも利用可能
# GitHub Releasesページから直接ダウンロードも可

基本的な使い方

初回起動時の設定

アプリを起動し、YouTube Musicにログイン
メニューバーの Options → Plugins から使用したいプラグインを有効化
一部のプラグインは再起動が必要

主要な機能の使用例

広告ブロック:

AdBlockプラグインを有効化するだけで自動的に広告がブロックされる

キーボードショートカット:

Ctrl/Cmd + L: 検索バーにフォーカス
F10: 音量50%リセット（Precise Volumeプラグイン）
Ctrl/Cmd + Shift + H: ビデオ表示/非表示切り替え

曲のダウンロード:

Downloaderプラグインを有効化
Options → Downloads でダウンロードフォルダを設定
曲のメニューから "Download" を選択

高度な使い方

カスタムCSSテーマの適用

Options → Visual Tweaks → Themes
カスタムCSSを入力またはファイルから読み込み
テーマの有効化

プラグインの組み合わせ例

完全な音楽体験セットアップ:

AdBlock + SponsorBlock: 広告と非音楽セグメントをスキップ
Discord + Scrobbler: ソーシャル共有と再生履歴記録
Lyrics + Visualizer: 歌詞表示と視覚効果
Equalizer + Crossfade: オーディオ品質の最適化

コマンドラインオプション

# 特定のURLで起動
youtube-music "https://music.youtube.com/playlist?list=..."

# デバッグモードで起動
youtube-music --enable-logging --log-level=debug

ドキュメント・リソース

公式ドキュメント

README.md: プロジェクト概要、インストール方法、プラグインリスト
changelog.md: バージョン履歴と更新内容
docs/index.html: プラグイン一覧ページ（ブラウザで閲覧可能）
GitHub Wiki: 詳細なプラグインドキュメント
Discordサーバー: コミュニティサポート

サンプル・デモ

src/plugins/: 40以上のプラグイン実装例
シンプルプラグイン: navigation.ts, shortcuts.ts
複雑なプラグイン: downloader/, visualizer/, discord/

チュートリアル・ガイド

プラグイン開発ガイド（README内）
ビルド手順（READMEの"Development"セクション）
プラグインAPIドキュメント（ソースコード内の型定義）

技術的詳細

アーキテクチャ

全体構造

Electronのマルチプロセスアーキテクチャを基盤に、YouTube MusicのWebインターフェースをラップし、プラグインシステムを通じて機能拡張を実現。

ディレクトリ構成

youtube-music/
├── src/              # ソースコード
│   ├── plugins/      # プラグイン実装（40+個）
│   │   ├── adblocker/    # 広告ブロック
│   │   ├── downloader/   # MP3ダウンロード
│   │   ├── discord/      # Discord連携
│   │   └── ...           # その他のプラグイン
│   ├── types/        # TypeScript型定義
│   ├── utils/        # ユーティリティ関数
│   ├── index.ts      # Mainプロセスエントリ
│   ├── preload.ts    # Preloadスクリプト
│   └── renderer.ts   # Rendererプロセス
├── vite-plugins/     # Viteカスタムプラグイン
│   ├── plugin-loader.mts   # プラグインローダー
│   └── i18n-importer.mts   # i18nリソースバンドラー
├── assets/           # アイコン、画像等
├── docs/             # ドキュメント
└── tests/            # テストファイル

主要コンポーネント

Mainプロセス (index.ts): Electronのメインプロセス、ウィンドウ管理
- 場所: src/index.ts
- 役割: アプリケーションのライフサイクル管理、メニュー生成
- インターフェース: BrowserWindow、Menu、Tray API
Preloadスクリプト (preload.ts): MainとRendererのブリッジ
- 場所: src/preload.ts
- 役割: IPC通信のラップ、セキュリティコンテキスト
- インターフェース: contextBridge API
Rendererプロセス (renderer.ts): YouTube Music UIの操作
- 場所: src/renderer.ts
- 役割: DOM操作、プラグインの初期化
- インターフェース: YouTube Player API、DOM API
プラグインシステム: 機能拡張の核心
- 場所: src/plugins/
- 役割: 各種機能のモジュラー実装
- インターフェース: PluginDef型に準拠

技術スタック

コア技術

言語: TypeScript、JavaScript
フレームワーク: Electron 37.1.0
UIフレームワーク: Solid.js（プラグインUIコンポーネント）
主要ライブラリ:
- electron-store: 設定の永続化
- custom-electron-prompt: カスタムダイアログ
- youtube-dl: 動画ダウンロード機能
- discord-rpc: Discord Rich Presence
- lastfm: Last.fmスクロブリング

開発・運用ツール

ビルドツール:
- Vite + electron-vite（高速ビルド）
- electron-builder（パッケージング）
- pnpm（パッケージマネージャー）
テスト:
- @electron/test
- プラグインの統合テスト
CI/CD:
- GitHub Actions
- マルチプラットフォームビルド
- 自動リリース
デプロイ:
- Windows: NSISインストーラー
- macOS: DMG、pkg
- Linux: AppImage、Snap、Flatpak、DEB、RPM

設計パターン・手法

プラグインアーキテクチャ:

コンテキスト分離: backend/preload/rendererで実行環境を分離
ライフサイクル管理: start/stop/onConfigChangeフック
型安全性: TypeScriptによる完全な型定義
ホットリロード: 一部プラグインは再起動不要

ビルド時最適化:

コード分割: コンテキストごとに不要コードを削除
仮想モジュール: プラグインの動的インポート
CSSインライン化: スタイルシートの効率的なバンドル

データフロー・処理フロー

プラグインの動作フロー:

起動時: プラグインローダーが全プラグインを発見・ロード
初期化: 各コンテキストでstart()メソッド実行
設定変更: onConfigChange()で動的に変更反映
IPC通信: Main-Renderer間でメッセージパッシング
終了時: stop()でクリーンアップ

YouTube Player API連携:

API初期化待機: onPlayerApiReadyフック
プレイヤー制御: 再生/停止/音量等の操作
メタデータ取得: 曲情報、アーティスト情報
イベントリスナー: 曲変更、状態変化の監視

API・インターフェース

公開API

プラグインAPI

目的: アプリケーションの機能を拡張するためのプラグインシステム
使用例:

import { createPlugin } from '@/utils';

export default createPlugin({
  name: 'My Plugin',
  restartNeeded: false,
  config: {
    enabled: false,
    myOption: 'default'
  },
  // バックエンドフック
  backend: {
    start({ window, ipc }) {
      // Electronウィンドウを操作
      window.setAlwaysOnTop(true);
      
      // IPC通信のハンドラー登録
      ipc.handle('my-event', (_, data) => {
        return processData(data);
      });
    },
    onConfigChange(newConfig) {
      // 設定変更時の処理
    }
  },
  // レンダラーフック
  renderer: {
    start(context) {
      // DOM操作やYouTube Music APIの利用
      document.querySelector('.ytmusic-player-bar')
        ?.insertAdjacentHTML('beforeend', '<div>Custom UI</div>');
    },
    onPlayerApiReady(api, context) {
      // YouTube Player APIが利用可能になった時
      api.getVolume(); // 音量取得
      api.pauseVideo(); // 一時停止
    }
  }
});

YouTube Player API

目的: 音楽プレイヤーの制御とメタデータ取得
主要メソッド:
- playVideo() / pauseVideo(): 再生制御
- nextVideo() / previousVideo(): 曲の切り替え
- setVolume(volume): 音量設定（0-100）
- getVideoData(): 現在の曲情報取得
- getDuration() / getCurrentTime(): 再生時間情報

設定・カスタマイズ

設定ファイル

// electron-storeによる設定管理
{
  "plugins": {
    "adblocker": { "enabled": true },
    "discord": { 
      "enabled": true,
      "hidePresence": false,
      "hideDuration": false
    },
    "downloader": {
      "enabled": true,
      "downloadFolder": "~/Music/YouTube Music",
      "preset": "mp3",
      "ffmpegArgs": []
    }
  },
  "options": {
    "hideMenu": false,
    "startAtLogin": true,
    "disableHardwareAcceleration": false
  }
}

拡張・プラグイン開発

プラグイン構造:

src/plugins/my-plugin/
├── index.ts      # プラグインエントリポイント
├── style.css     # カスタムスタイル
├── backend.ts    # バックエンド処理（オプション）
└── renderer.ts   # レンダラー処理（オプション）

利用可能なコンテキスト:

backend: Electronメインプロセスで実行（ファイルシステム、ネイティブAPI）
renderer: Webページコンテキストで実行（DOM操作、YouTube API）
preload: セキュアなブリッジコンテキスト（IPC通信）

プラグイン間通信:

// 他のプラグインとの連携
context.ipc.send('downloader:download', {
  videoId: api.getVideoData().video_id,
  title: api.getVideoData().title
});

## パフォーマンス・スケーラビリティ
### パフォーマンス特性
- **起動時間**: 2-4秒（プラグイン数により変動）
- **メモリ使用量**: 
  - 基本状態: 150-200MB
  - 動画再生時: 300-500MB
  - ビジュアライザー使用時: 400-600MB
- **CPU使用率**:
  - アイドル時: 1-3%
  - 音楽再生時: 5-10%
  - ビジュアライザー有効時: 15-25%

### 最適化手法
- **遅延ロード**: プラグインは必要時にのみロード
- **コード分割**: Viteによるコンテキスト別の最適化
- **GPU活用**: ハードウェアアクセラレーション対応
- **効率的なIPC**: バッチ処理とデバウンスによる通信最適化

### スケーラビリティ
**プラグインシステムのスケーラビリティ**:
- 40以上のプラグインを同時に有効化可能
- プラグイン間の依存関係管理
- 動的なプラグインロード/アンロード

**大規模プレイリスト対応**:
- 仮想スクロールによる大量アイテムの効率的表示
- 遅延読み込みによるメモリ使用量の最適化

### 制限事項
- **技術的な制限**:
  - Electron固有のメモリオーバーヘッド
  - YouTube Music WebAPIの制限に依存
  - 一部プラグインは再起動が必要
  - DRM保護コンテンツのダウンロード不可

- **運用上の制限**:
  - YouTube利用規約の遵守が必要
  - 公式APIではないため、YouTube側の変更で機能が停止する可能性
  - プラグイン間の競合可能性

## 評価・所感
### 技術的評価
#### 強み
- **モジュラーアーキテクチャ**: プラグインシステムによる高い拡張性と保守性
- **開発者フレンドリー**: TypeScript完全対応、明確なAPI設計、豊富なサンプル
- **コミュニティ駆動**: 40以上の実用的プラグイン、活発な開発コミュニティ
- **クロスプラットフォーム**: Windows/macOS/Linux完全対応、各OSネイティブ機能統合
- **パフォーマンス**: Viteによる高速ビルド、効率的なプラグインロード

#### 改善の余地
- **Electron依存**: ネイティブアプリと比較してメモリ使用量が多い
- **非公式実装**: YouTube側の変更により機能が停止するリスク
- **プラグイン管理**: 依存関係や競合の自動解決機能が不足
- **ドキュメント**: プラグイン開発の詳細なAPIドキュメントが不足

### 向いている用途
- **パワーユーザー向け音楽体験**: 広告ブロック、ダウンロード、高度なカスタマイズ
- **開発者向けプラットフォーム**: 独自プラグイン開発による機能拡張
- **マルチプラットフォーム環境**: 統一された音楽体験の提供
- **ストリーマー/コンテンツクリエイター**: OBS連携、Discord表示など

### 向いていない用途
- **軽量な音楽プレイヤーが必要な場合**: メモリ使用量が多い
- **公式サポートが必要な環境**: 非公式アプリのため保証なし
- **DRM保護コンテンツの利用**: 技術的制限により不可
- **モバイル環境**: デスクトップ専用設計

### 総評
YouTube Music Desktop Appは、Webベースの音楽サービスをデスクトップアプリ化する優れた実装例です。特筆すべきは、単なるラッパーに留まらず、強力なプラグインアーキテクチャを通じて、Web版では不可能な機能を多数実現している点です。

プラグインシステムの設計は秀逸で、backend/renderer/preloadの3つのコンテキストを適切に分離し、セキュリティと拡張性を両立しています。40以上の組み込みプラグインは、それぞれが独立したモジュールとして機能し、ユーザーは必要な機能だけを選択できます。

開発面では、TypeScriptの完全サポート、Viteによる高速ビルド、明確なプラグインAPIなど、モダンな開発体験を提供しています。コミュニティも活発で、継続的な機能追加と改善が行われています。

一方で、Electronベースであることによるリソース消費、YouTube側の変更への脆弱性など、構造的な課題も存在します。しかし、これらの制限を考慮しても、デスクトップ音楽プレイヤーとしての完成度は非常に高く、特にカスタマイズ性を重視するユーザーにとっては最良の選択肢の一つと言えるでしょう。