SubTUI

SubTUI

SubTUI is your next favorite lightweight music player for Subsonic-compatible servers like Navidrome, Gonic, and Airsonic. Built with Go and the Bubble Tea framework, it provides a clean terminal interface to listen to your favorite high-quality audio.

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

Installation

Prerequisites

You must have mpv installed and available in your system path.

• Ubuntu/Debian: sudo apt install mpv
• Arch: sudo pacman -S mpv
• macOS: brew install mpv

Linux & macOS (Releases)

You can download pre-compiled binaries for Linux and macOS directly from the Releases page.

• Debian/Ubuntu: Download the .deb file and run sudo dpkg -i subtui_*.deb
• Fedora/RHEL: Download the .rpm file and run sudo rpm -i subtui_*.rpm
• Alpine: Download the .apk file and run sudo apk add --allow-untrusted ./subtui_*.apk
• Generic: Download the release for your architecture, extract it, and run the binary.

macOS (Homebrew)

You can install SubTUI via the official Homebrew tap brew install MattiaPun/subtui/subtui

Arch Linux (AUR)

You can install SubTUI directly from the AUR: yay -S subtui-git

FreeBSD

You can install SubTUI directly via pkg: pkg install subtui Note that this will automatically install the mpv dependency

Nix

You can install SubTUI using the flake: nix profile install github:MattiaPun/SubTUI

GoLang Toolchain

You can install SubTUI directly using GoLang: go install github.com/MattiaPun/SubTUI@latest

From Source

# Clone the repo
git clone https://github.com/MattiaPun/SubTUI.git
cd SubTUI

# Build
go build .

# Run
./subtui

Configuration

On the first launch, SubTUI will generate default configuration files at: ~/.config/subtui/config.toml and ~/.config/subtui/credentials.toml. Security Note: Your credentials are stored in plaintext in the credentials.toml file

You can edit these files to save your credentials, change the color theme, or remap any keybind. You can find the default configuration templates in the repository at internal/api/config.toml and internal/api/credentials.toml

Default keybinds

Note: All keybinds below are the defaults. You can customize them in your config.toml.

Global Navigation

Search

Library & Playlists

Media Controls

Starred (liked) songs

Queue Management

Other

Screenshots

Contributing

Contributions are welcome! Please make use of Convention Commit Messages

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Sponsor

If you enjoy using SubTUI, please consider sponsoring the project to support its development.

License

Distributed under the MIT License. See LICENSE for more information.