spotatui: Rust で記述されたターミナル音楽プレイヤー

Rust と Ratatui により駆動される、次世代のターミナル音楽プレイヤーです。Spotify ネイティブストリーミングや同期歌詞、リアルタイムオーディオビジュアライザーなど多機能を実現します。

概要

• コミュニティ開発:

  spotify-tui

  のフォーク版ですが、多方面で分岐しています。
• 主な違い:
  • バックエンド: 公式 Connect デバイスではなく、組み込みネイティブクライアントを使用します。
  • ソース対応: Spotify に限らず、以下の多様なソースをネイティブでサポートしています。
    • YouTube
    • ローカルファイル
    • Subsonic / Navidrome サーバー
    • インターネットラジオ
    • Qobuz
    • macOS 用 Apple Music

機能 (Features)

• 複数ソース対応
  • Spotify はオプションです（Premium アカウントが必要）。
  • キー

    d

    でソースを自由に切り替え可能。
  • 無料のソース（Spotify 以外）は登録なしで使用できます。
• ネイティブストリーミング
  • Spotify Connect デバイスとして認識され、公式アプリや

    spotifyd

    を介さずに直接再生します。
  • Electron クライアントよりも軽量です。
• 同期歌詞 (Synced Lyrics)
  • 行単位の歌詞を再生タイミングに合わせて表示します。
• リアルタイムオーディオビジュアライザー
  • システム全体の FFT ビジュアライザー（キー

    v

    ）。
  • Spotify 再生時は独自ピッチビューを表示します。
• クロスソースプレイキュー
  • キー

    z

    で任意のトラックをキューに追加し、ソースを越えて連続再生できます。
• プレイリスト同期
  • 1 つのプレイリストをマスターとして設定し、複数のソース間でミラーリングできます（例：

    spotatui sync

    コマンド）。
• Lua プラグイン
  • イベントフックやキーバインドを通じて UI を拡張・カスタマイズできます。
• リスニング履歴とサマリー
  • 演奏履歴を保持し、HTML のサマリー（

    spotatui history recap

    ）を生成して共有できます。
• フル CLI 対応
  • スクリプタブルなコマンドラインインターフェースを提供します（例：検索、プレイリスト操作、シェル補完）。

インストール

Spotify アカウントは初回起動時のソース選択で指定し、後から追加可能です。YouTube の使用には

yt-dlp

ワンラインインストーラー (推奨)

• macOS, Linux, WSL

  curl -fsSL https://spotatui.com/install.sh | bash
  

• Homebrew (macOS 限定)

  brew tap LargeModGames/spotatui
  brew install spotatui
  

• Cargo (コンパイルからインストール)

  cargo install --locked spotatui
  # またはプレビルトバイナリを使用
  cargo binstall spotatui
  

特定のリポジトリからのインストール

• Arch Linux (AUR)

  yay -S spotatui-bin  # プレビルトバイナリ（高速）
  # またはソースから構築
  yay -S spotatui
  

• Void Linux

  echo repository=https://raw.githubusercontent.com/Event-Horizon-VL/blackhole-vl/repository-x86_64 | sudo tee /etc/xbps.d/20-repository-extra.conf
  sudo xbps-install -S spotatui
  

• Windows PowerShell

  irm https://spotatui.com/install.ps1 | iex
  # または Winget を使用
  winget install spotatui
  

• NixOS

  inputs = {
    spotatui = {
      url = "github:LargeModGames/spotatui";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
  
  { inputs, ... }: {
    environment.systemPackages = with pkgs; [
      inputs.spotatui.packages.${pkgs.stdenv.hostPlatform.system}.default
    ];
  }
  

デスクトップアプリ (Preview)

ターミナルではなくウィンドウで動作するバージョンも提供されます。設定や履歴は共有されていますが、両者は同時に動作せず、ウィンドウ閉じで終了します。

• システム要件: glibc 2.39, WebKitGTK 4.1。
• 更新機能:

  behavior.disable_auto_update

  を設定して無効化可能です。

クイックスタート

spotatui

初回起動時、ソース選択メニューが表示されます：

Welcome to spotatui! Choose your music source:

  1) Spotify        (needs login, Premium required)
  2) YouTube        (free, needs yt-dlp)
  3) Subsonic       (free, needs server)
  4) Internet Radio (free)
  5) Local Files    (free)
  6) Qobuz          (paid subscription)
  7) Apple Music    (macOS only)

• 基本操作:

  • ?

    : キーバインドヘルプ

  • d

    : ソース・デバイス選択メニュー開閉（ソース切り替え）

  • z

    : 現在のトラックをプレイキューに追加

  • /

    : 検索モードへ切り替え

  • Ctrl+L

    : 検索クエリのクリア

• 検索方法:

  1. /

     を押してフレーズを入力。
  2. Enter で検索実行。
  3. 結果リストからトラックを選択し、Enter で再生（スペースキーでポーズ/再生）。

• コマンド例:

  spotatui --completions zsh          # シェル補完設定 (bash, powershell 対応)
  spotatui play --name "Name" --random  # ランダム再生
  spotatui history recap --period 30d # 過去 30 日分のサマリー生成
  

音楽ソース詳解

d

yt-dlp

ソース固有の設定例 (

config.yml

)

• ローカルファイル:

  behavior.local_music_path

  を指定。
• Subsonic:

  SPOTATUI_SUBSONIC_PASSWORD

  環境変数でのパスワード管理推奨。
• Qobuz:

  qobuz_quality

  で品質設定（例：

  6

  =FLAC 16/44.1）。
• Apple Music: macOS の自動化許可が必要です（System Settings > Privacy & Security > Automation）。

Apple Music の注意点

• カスタマイズ機能の一部（キュー、ランダム再生、リピート、ライク）は利用不可。
• Music アプリで他のソースが再生中は検出されません。
• 音楽アプリ側の不具合（ファイル欠落等）は spotatui 側でスキップ処理されます。

AI DJ

spotatui は AI を活用したプレイリスト作成機能を提供します。

MCP サーバー方式 (

--features mcp-server

)

• コーディングエージェント（Claude Code, Gemini CLI など）と連携し、AI が DJ を担当します。
• エージェントへの指示設定は

  docs/mcp-setup.md

  にあります。

組み込み TUI AI DJ (

--features ai-dj

)

• Ctrl-j

  でチャット・プロンプト画面を表示。
• 検索、キュー作成、再生の意思確認を AI が行います。
• ローカルモデル（Ollama など）や API キーに対応しています。

インストール:

cargo install --locked spotatui --features mcp-server,ai-dj

ネイティブストリーミング (Native Streaming)

• spotifyd

  や公式アプリの再起動不要で、Spotify Connect デバイスとして直接機能します。
• 最新の CDN 問題などの修正をバックポートした librespot フォークを使用しています。
• 要件: Spotify Premium アカウント必須。

オーディオビジュアライザー

キー

v

Spotify 再生中は、元々のピッチビュー（12 ピッチクラス表示）に切り替わります。

v

その他機能

Discord Rich Presence

• デフォルト有効（アプリ ID を使用）。
• 設定で無効化またはカスタマイズ可能です（

  discord_rpc_client_id

  指定など）。

匿名ソングカウンター

• グローバルな再生回数をカウントする機能をオプトインで使用できます。
• 個人情報を収集せず、30 秒再生完了時にのみカウントアップします。

GitHub Profile Widget

• spotatui.com のアカウント連携により、GitHub プロフィールで「現在聴いている曲」を表示可能です。
• カバーアートやピッチビューも表示されます。

設定 (Configuration)

設定ファイル:

config.yml

$XDG_CONFIG_HOME/spotatui/config.yml

• Alt-, キーで UI 内から設定画面を開くことも可能です。
• カバーアート用のダッティング処理、キーバインド変更、テーマ切り替えなどが可能です。

開発とビルド

• 言語: Rust
• UI Framework: Ratatui
• ライブラリ:

  rspotify

  ,

  librespot

  ,

  tokio

  などを使用。

プラットフォーム固有の要件

• Linux 開発: ALSA 開発パッケージ（

  pkg-config

  ）、PipeWire（ビジュアライザー用オプション）が必要です。
• Windows: PowerShell スクリプトでの自動インストール推奨。

Windows Subsystem for Linux (WSL)

リンクエラーが発生する場合は、以下の追加依存関係をインストールしてください：

sudo apt-get install -y -qq pkg-config libssl-dev libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev

バグ報告とサポート

• 問題発生時は

  --debug

  フラグで実行し、ログファイルを確認してください。
• バグ報告: Issue を作成し、再現手順とログを添付してください。
• コミュニティ: Discord や GitHub Discussions で交流可能です。

ロードマップ

目標は Spotify のほぼ全ての機能を実装することです。高優先度課題として「すべてのビューでの結果ページスクロール」などが計画されています。