Configuration

Configuration File

SubTUI is configured through a single TOML file located at:

~/.config/subtui/config.toml

On first launch, a default configuration is generated automatically. When SubTUI updates and adds new configuration keys, they are merged into your existing file without overwriting your customizations.

The default configuration template is also available in the repository at internal/api/config.toml.

General App Settings

Setting	Type	Default	Description
replaygain	string	'track'	Volume normalization mode passed to mpv. Use 'track' for per-track normalization, 'album' to preserve album dynamics, or 'no' to disable.
desktop_notifications	bool	true	When enabled, a desktop notification is sent on each track change. Can also be toggled at runtime with the s key.
discord_rich_presence	bool	true	When enabled, SubTUI shows the currently playing track as your Discord activity ("Listening to...").
mouse_support	bool	false	Enables mouse interaction within the terminal UI. Disabled by default because it can interfere with terminal text selection.

Theming / Colors

Each color is specified as a two-element array of hex codes: the first value is used on light terminal backgrounds, and the second on dark backgrounds. SubTUI auto-detects your terminal's background.

Setting	Type	Default (Light / Dark)	Description
display_album_art	bool	true	Show album art in the player footer.
subtle	[string, string]	['#D9DCCF', '#6B6B6BFF']	Secondary text, inactive elements
highlight	[string, string]	['#874BFD', '#7D56F4']	Selected/focused items, active elements
special	[string, string]	['#43BF6D', '#73F59F']	Progress bar, accent highlights
filtered	[string, string]	['#A9A9A9', '#555555']	Filtered/dimmed content

Columns

Control which columns are visible in the main view. Set any column to true to show it or false to hide it. Columns can be specified separately for songs, albums and artists.

Keybinds

All keybinds can be remapped in the [keybinds] section. Each action accepts an array of key strings, so you can assign multiple keys to the same action. For the full default keybind reference, see Keybinds and Filters.

Example — remapping volume controls:

[keybinds.media]
volume_up   = ['v', '+']
volume_down = ['V', '-']

Filters

See the Filters section in the Keybinds and Filters page for detailed documentation on the [filters] block.