Skip to content

Home

Jump to bottom
Mattia edited this page Mar 12, 2026 · 3 revisions

Welcome to the SubTUI Wiki

This wiki is up to date as of v2.11.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 comaptiblity: Uses mpv to support various audio codecs and reliable playback
  • Fully Customizable: Configure keybinds, color themes, and settings via a simple TOML file
  • 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 intented with smooth, uninterrupted transitions
  • Discord Integrations: Show of your listing to 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. See Contributing for development guidelines.
  • Sponsor — If you enjoy SubTUI, consider sponsoring the developer to support continued development.

Clone this wiki locally