mopytui

A full-featured terminal client for Mopidy — built around the native JSON-RPC API so it surfaces everything mopidy-mpd does and more, including Tidal browsing/search if the server has mopidy-tidal installed.

Renders cover art with the best protocol your terminal supports — Kitty graphics, iTerm2 inline images, Sixel, or unicode halfblocks — detected at runtime.

• Albums grid with real thumbnail covers (Spotify-style), with detail view showing tracks, MusicBrainz credits, and Wikipedia summary.
• Browse the entire Mopidy library tree (Local, Tidal, file-system, playlists, anything a backend exposes).
• Cross-source search (core.library.search) — local + Tidal together. Results are grouped under TIDAL / LOCAL and by albums · artists · tracks; the highlighted one gets a detail panel with its cover, facts and track list (→ to pick a track). Add albums to your Tidal library with f, play with p, queue with a, start a radio with o. Ctrl+F shows the advanced filters (artist, album, title, genre, date…).
• Queue management — add, reorder, remove, clear, shuffle.
• Playback control: play/pause/stop/next/prev/seek/volume/mute.
• All playback modes: random, repeat, single, consume.
• Stored playlists: list, load, delete; save the current queue as a playlist.
• Cover art in Now Playing and Queue, fetched via core.library.get_images, pre-resized to fill the panel cleanly and rendered via the best protocol your terminal supports.
• Synced lyrics from lrclib.net with the active line highlighted in real time (toggle with L).
• Audio chip — live sample rate / bit depth / channels from mopidy-mpd's status:audio (bit-perfect verification).
• Tidal Goodies stats (recently played, most played, top artists/albums, record labels, listening heatmap, genres, totals — filterable by week / month / year), Tidal radio (o on any track or artist) and Tidal review, artist bio & track credits in the Info view (for Tidal tracks and for local albums goodies can match to Tidal; preferred over Wikipedia, and the bio's picture is the artist avatar when no fanart.tv key is set) when the server has mopidy-tidal-goodies installed.
• Live updates via mpd idle subscription (player/mixer/options/playlist).

• A reachable Mopidy server with mopidy-http (always on by default) and mopidy-mpd enabled.
• Rust 1.86+ (uses 2024 edition, let-chains).
• A terminal. For best visuals, use one with Kitty graphics, iTerm2 inline images, or Sixel support:
  • Kitty, WezTerm, Ghostty → Kitty graphics (recommended — no flicker on multi-image grids)
  • iTerm2 → iTerm2 inline images (works, but multi-image grids may flicker because the protocol re-emits the full PNG on every redraw)
  • foot, mlterm, Windows Terminal → Sixel
  • Everything else → unicode halfblocks (always works)

cargo build --release
./target/release/mopytui

# remote server
./target/release/mopytui --host 192.168.1.10 --port 6680
# shorthand
./target/release/mopytui 192.168.1.10:6680
# pick a theme on the fly
./target/release/mopytui --theme solar

./target/release/mopytui --help    # show all flags

For better halfblocks rendering on terminals without native image protocols, opt in to chafa (requires libchafa):

# macOS
brew install chafa
# Linux (Debian/Ubuntu)
sudo apt install libchafa-dev

cargo build --release --features chafa

Edit ~/.config/mopytui/config.toml (or the platform-equivalent under directories::ProjectDirs):

host = "127.0.0.1"
http_port = 6680
mpd_port = 6600
theme = "midnight"  # midnight | soft-dark | daylight | solar
mpris = false       # Linux only

Pick at startup with --theme <name>:

• midnight (default) — analogous blue/violet palette anchored on periwinkle, warm amber reserved for the favorite star.
• soft-dark — neutral greys with soft blue accents.
• daylight — light theme.
• solar — Solarized-style.

All themes use 24-bit truecolor (16M colours), so make sure your terminal has truecolor support.

mopytui writes a debug log to the platform cache directory:

• macOS: ~/Library/Caches/mopytui/mopytui.log
• Linux: ~/.cache/mopytui/mopytui.log

Override the level with RUST_LOG=mopytui=debug. Useful targets:

• mopytui::lyrics=debug — lrclib lookups (artist, title, HTTP status, errors)
• mopytui::mopidy=debug — JSON-RPC traffic
• mopytui::mpd=debug — MPD idle events

MIT — see LICENSE.