music-tui

music-tui is a terminal music player client for MPD built with Ratatui. It drives an existing MPD daemon and adds a tabbed, mouse-friendly interface: queue, cover art, synced lyrics, metadata editing, and a spectrum visualizer.

2026-08-19_16-56-48.mp4

Features

• MPD playback control: play/pause, seek, next/previous, volume, repeat/random/single/consume.
• Tabbed interface with a configurable pane layout DSL (H(2:1, queue, V(2:1, cover, metadata))).
• Queue view with filtering, selection, keyboard and mouse navigation.
• Secondary detail view for any queue entry: large cover plus full metadata.
• Cover art rendering with Kitty, Sixel, and iTerm2 graphics protocols, Chafa symbols, and ASCII fallback.
• Synced lyrics (.lrc, including word-level timestamps) with karaoke highlighting, click-to-seek, and auto-follow; plain/embedded lyrics supported.
• Metadata viewer and editor (e opens a TOML draft in $EDITOR).
• Spectrum visualizer fed by the MPD fifo output.
• Which-key style hints, scrollable f1 key-binding help, command prompt (:).
• music-tui open subcommand for file-manager integration with four play modes.

Usage

music-tui              # connect to MPD (first-run local socket by default)
music-tui open ~/Music/album   # replace the queue with a folder
music-tui open song.flac      # see the open modes below

If MPD has no configuration yet, the first music-tui launch creates a minimal local Unix-socket config without a music_directory and points music-tui at that socket. Existing MPD configs and custom remote hosts are never replaced. The MPD daemon still needs to be started by the system service manager.

open modes (-m/--mode, default interrupt):

• append — append the file/folder to the queue.
• next — insert the file right after the currently playing song.
• interrupt — play the file immediately; when it ends, restore the previous queue and playback state.
• folder — play the file immediately and rebuild the queue from its folder.

Options: -r/--recursive recurses into subfolders; --no-play queues without starting playback.

Installation

Arch Linux (AUR)

yay -S music-tui-stable   # release build (from the v tag)
yay -S music-tui-git       # latest master
yay -S music-tui-bin       # prebuilt binary from the GitHub release

Note: the plain music-tui AUR name belongs to a different project; this one ships as music-tui-stable / music-tui-git / music-tui-bin (all provide: music-tui and conflict with each other).

Homebrew

brew tap WindustH/tap https://github.com/WindustH/homebrew-tap
brew install music-tui

A --HEAD build (from master) is available until the first bottled release lands.

From source

git clone --recurse-submodules https://github.com/WindustH/music-tui
cd music-tui
cargo install --path .

Requires mpd, chafa and sqlite.

Windows

See doc/windows.md for MPD setup and Windows-specific notes. In short: install MPD, create a mpd.conf with bind_to_address "127.0.0.1", register it as a Windows service (sc.exe create mpd ...), then run music-tui.

macOS

Apple's built-in Terminal.app implements no image protocol (Kitty, Sixel, or iTerm2), so cover art falls back to character art (symbols/ASCII). To see real images, use a protocol-capable terminal such as iTerm2, WezTerm, or kitty (protocols are auto-detected).

Documentation

doc/index.md.