Keybinds and Filters

Keybinds

All keybinds listed here are the defaults. Every one of them can be remapped in your ~/.config/subtui/config.toml. See the Remapping Keybinds section below.

Tip: Press ? inside SubTUI at any time to view your current keybinds (including any custom remappings).

Global Navigation

Key	Action	TOML Key
Tab	Cycle focus forward (Search → Sidebar → Main → Footer)	keybinds.global.cycle_focus_next
Shift+Tab	Cycle focus backward	keybinds.global.cycle_focus_prev
Backspace / Esc	Go back / close popup	keybinds.global.back
?	Toggle help menu	keybinds.global.help
q	Quit (except when in search or login)	keybinds.global.quit
Ctrl+c	Force quit	keybinds.global.hard_quit

List Navigation

Key	Action	TOML Key
j / Down	Move selection down	keybinds.navigation.down
k / Up	Move selection up	keybinds.navigation.up
gg	Move selection to top	keybinds.navigation.top
G	Move selection to bottom	keybinds.navigation.bottom
Enter	Play selection / Open album or artist	keybinds.navigation.select
Alt+Enter	Play album or playlist shuffled	keybinds.navigation.play_shuffeled

Search

Key	Action	TOML Key
/	Focus the search bar	keybinds.search.focus_search
Ctrl+n	Cycle search filter forward (Songs → Albums → Artists)	keybinds.search.filter_next
Ctrl+b	Cycle search filter backward	keybinds.search.filter_prev

Library & Playlists

Key	Action	TOML Key
A	Add selection to a playlist	keybinds.library.add_to_playlist
R	Add/change rating on selection	keybinds.library.add_rating
ga	Go to album of selected song	not remappable
gr	Go to artist of selected song/album	not remappable

Limitation: The two-stroke g-prefixed keybinds (gg, ga, gr) are currently hardcoded and cannot be changed via config.toml.

Media Controls

Key	Action	TOML Key
p / P	Toggle play/pause	keybinds.media.play_pause
n	Next song	keybinds.media.next
b	Previous song	keybinds.media.prev
S	Shuffle queue (current song moves to first)	keybinds.media.shuffle
L	Cycle loop mode (None → All → One)	keybinds.media.loop
w	Restart current song	keybinds.media.restart
,	Rewind 10 seconds	keybinds.media.rewind
;	Forward 10 seconds	keybinds.media.forward
v	Volume up (+5%)	keybinds.media.volume_up
V	Volume down (-5%)	keybinds.media.volume_down

Queue Management

Key	Action	TOML Key
Q	Toggle queue view	keybinds.queue.toggle_queue_view
N	Queue song next (after current)	keybinds.queue.queue_next
a	Queue song last (end of queue)	keybinds.queue.queue_last
d	Remove song from queue	keybinds.queue.remove_from_queue
D	Clear entire queue	keybinds.queue.clear_queue
K	Move song up in queue	keybinds.queue.move_up
J	Move song down in queue	keybinds.queue.move_down

Favorites (Starred)

Key	Action	TOML Key
f	Toggle star/favorite on selection	keybinds.favorites.toggle_favorite
F	Open starred/liked songs	keybinds.favorites.view_favorites

Other

Key	Action	TOML Key
s	Toggle desktop notifications	keybinds.other.toggle_notifications
Ctrl+s	Create a shareable link for the selection	keybinds.other.create_share_link

Remapping Keybinds

Every keybind in SubTUI can be customized in the [keybinds] section of config.toml. Each action accepts an array of strings, allowing you to assign one or more keys.

Key format

Keys are specified as lowercase strings. Modifier keys are joined with +:

• Simple keys: 'j', 'k', 'enter', 'tab', 'backspace', 'esc'
• With modifiers: 'ctrl+c', 'shift+tab', 'alt+enter', 'ctrl+n'

Note: Custom multi-key sequences (like gg) without a modifier are not supported. Only single keys and modifier+key combinations can be used for custom bindings.

Example

[keybinds.media]
play_pause  = ['space']          # remap play/pause to spacebar
next        = ['n', 'ctrl+f']   # two keys for next song
volume_up   = ['=']
volume_down = ['-']

If you only want to add a key without removing the default, include the default in the array:

[keybinds.navigation]
up   = ['k', 'up', 'ctrl+p']    # adds ctrl+p alongside defaults
down = ['j', 'down', 'ctrl+n']

Filters

The [filters] section in config.toml lets you exclude songs from your library based on various criteria. Filters are applied locally — they hide matching songs from view without affecting your server data.

[filters]
titles         = []       # Exclude songs whose title contains any of these strings
artists        = []       # Exclude songs by these artists
album_artists  = []       # Exclude songs by these album artists
min_duration   = 0        # Exclude songs shorter than or equal to N seconds (0 = disabled)
genres         = []       # Exclude songs in these genres
notes          = []       # Exclude songs whose comments/notes contain these strings
paths          = []       # Exclude songs whose file path contains these strings
max_play_count = 0        # Exclude songs with play count <= N (0 = disabled)
exclude_favorites = false # Exclude songs marked as starred/favorite
max_rating     = 0        # Exclude songs with rating <= N (1-5, 0 = disabled)

Examples

Hide all songs shorter than 30 seconds (intros, interludes, etc.):

[filters]
min_duration = 30

Hide holiday music and spoken word:

[filters]
genres = ['Christmas', 'Spoken Word', 'Audiobook']

Hide songs from a specific folder path:

[filters]
paths = ['/audiobooks/', '/podcasts/']

Exclude low-rated songs (rating 2 or below):

[filters]
max_rating = 2

All string-based filters (titles, artists, album_artists, genres, notes, paths) perform substring matching — if the song's field contains any of the listed strings, it is excluded.