Skip to content

Home

Jump to bottom
MattiaPun edited this page Apr 23, 2026 · 4 revisions

Welcome to the SubTUI Wiki

This wiki is up to date as of v2.14.0.

SubTUI is a lightweight, terminal-based music player client for Subsonic-compatible servers like Navidrome, Gonic, and Airsonic. Built with Go and the Bubble Tea framework, it gives you a clean, fast, and highly customizable TUI to stream your music library.

Key Features

  • Subsonic-compatible: Connect and stream from any Subsonic-compatible server.
  • Format compatibility: Uses mpv to support various audio codecs and reliable playback.
  • Fully Customizable: Configure keybinds, color themes, and settings via a simple TOML file.
  • Vim-style Visual Multi-Select: Seamlessly highlight contiguous blocks of tracks to perform bulk actions (move, queue, rate, etc.).
  • Synced Lyrics: Follow along with your favorite tracks using the dedicated music player and lyrics view.
  • ReplayGain Support: Built-in support for Track and Album volume normalization.
  • Scrobbling: Automatically updates your play counts on your server and external services like Last.FM or ListenBrainz.
  • Gapless Playback: Enjoy your favorite albums exactly as intended with smooth, uninterrupted transitions.
  • Discord Integrations: Show off your listening activity with built-in Discord Rich Presence.
  • Album Art: Displays album art directly in the player footer.

Prerequisites

SubTUI requires mpv to be installed and available in your system PATH. You can verify your installation by running:

mpv --version

Installation

Method Command / Instructions
Debian / Ubuntu Download the .deb and run sudo dpkg -i subtui_*.deb
Fedora / RHEL Download the .rpm and run sudo rpm -i subtui_*.rpm
Alpine Download the .apk and run sudo apk add --allow-untrusted ./subtui_*.apk
Arch Linux (AUR) yay -S subtui-git
macOS (Homebrew) brew install MattiaPun/subtui/subtui
FreeBSD pkg install subtui
Nix nix profile install github:MattiaPun/SubTUI
Go Toolchain go install github.com/MattiaPun/SubTUI@latest
From Source git clone https://github.com/MattiaPun/SubTUI.git && cd SubTUI && go build .

Contributing

There are several ways to contribute to SubTUI:

  • Feature Requests — Open an issue on GitHub to suggest new features or improvements.
  • Code Contributions — Fork the repo, create a branch, and submit a pull request.
  • Sponsor — If you enjoy SubTUI, consider sponsoring.

Clone this wiki locally