Skip to content

Keybinds and Filters

MattiaPun edited this page Apr 23, 2026 · 6 revisions

Keybinds

All keybinds listed here are the defaults. Every one of them can be remapped in your ~/.config/subtui/config.toml under their respective sections.

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
ctrl+u Move selection half page up keybinds.navigation.go_half_page_up
ctrl+d Move selection half page down keybinds.navigation.go_half_page_down
Enter Play selection / Open album or artist keybinds.navigation.select
Alt+Enter Play album or playlist shuffled keybinds.navigation.play_shuffled
x Toggle multi selection keybinds.navigation.toggle_selection

Visual Multi-Select Mode

SubTUI features a Vim-style visual selection mode, allowing you to highlight contiguous blocks of tracks to perform bulk actions (like moving multiple songs in the queue or adding an entire album to a playlist at once).

  • Press x to enter visual selection mode and set your anchor point.
  • Use your standard list navigation keys (e.g., Up/Down) to expand or shrink the highlighted block.
  • To perform an action on the block (e.g., Move Up/Down, Queue Last, Rate, Delete), simply press the exact same keybind you have configured for that action normally. The action will automatically apply to all highlighted tracks.
  • Press Esc or x again to cancel the selection.

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 keybinds.library.go_to_album
gr Go to artist of selected song/album keybinds.library.go_to_artist
0 Rate 0 on selected song/album/artist keybinds.library.rate_0
1 Rate 1 on selected song/album/artist keybinds.library.rate_1
2 Rate 2 on selected song/album/artist keybinds.library.rate_2
3 Rate 3 on selected song/album/artist keybinds.library.rate_3
4 Rate 4 on selected song/album/artist keybinds.library.rate_4
5 Rate 5 on selected song/album/artist keybinds.library.rate_5

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
m Toggle media player keybinds.media.toggle_media_player

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.

Clone this wiki locally