Keyboard Shortcuts

Nokkvi is designed to be fully navigable via keyboard. Every action below can be rebound — see Customizing Shortcuts at the bottom of this page.

Views

Switch between the different screens of the application.

Action	Shortcut	Description
Queue	1	Active playback queue
Albums	2	Browse library by album
Artists	3	Browse by artist
Songs	4	Flat, searchable track list
Genres	5	Browse by genre
Playlists	6	Navidrome playlists
Radios	7	Radio stations
Harbour	8	Home view — discovery shelves and whole-library search
Settings	` (Backtick)	Open the settings panel

Playback

Action	Shortcut	Description
Play / Pause	Space	Play or pause the current track
Toggle Random	X	Toggle random/shuffle mode
Toggle Repeat	Z	Cycle repeat mode: off → one → queue
Toggle Consume	C	Consume mode removes each track from the queue after it plays
Toggle SFX	S	Enable or disable UI sound effects
Cycle Visualizer	V	Cycle through visualizer modes: off → bars → lines → scope
Toggle Equalizer	Q	Open or close the 10-band graphic equalizer
Open Trawl	t	Open the Trawl mix-builder modal (works in any view except Settings)
Toggle Crossfade	F	Enable or disable gapless crossfading between tracks (enabling it turns off bit-perfect)
Toggle Lyrics	L	Show or hide synced lyrics over the Queue cover art
Toggle Bit-Perfect	B	Cycle bit-perfect output: off → strict → relaxed (turns off crossfade)

Navigation

The slot list is the scrollable item list in the center of each view.

Action	Shortcut	Description
Slot List Up	Backspace	Move the centered slot up in the list
Slot List Down	Tab	Move the centered slot down in the list
Activate / Enter	Enter	Play or open the focused item
Shuffle Play	Ctrl + Enter	Shuffle-play the focused item or selection (forced shuffle, ignores the Enter setting) — or, in the Trawl modal, play the mix (replaces the queue)
Expand / Collapse	Shift + Enter	Expand / collapse the focused item inline (albums, artists, playlists, genres)
Search	/	Focus the search bar in the current view
Center on Playing	Shift + C	Scroll the list to the currently playing track
Library Browser	Ctrl + E	Toggle the library browser panel alongside the Queue

Item Actions

Action	Shortcut	Description
Add to Queue	Shift + A	Append the focused item (album, song, artist, genre, or playlist) to the playback queue — or, in the Trawl modal, add the whole mix to the queue
Remove from Queue	Ctrl + D	Remove the focused item from the queue
Clear Queue	Shift + D	Remove all tracks from the queue
Love / Unlove	Shift + L	Toggle the Navidrome star (“love”) flag on the focused track
Increase Rating	=	Increase the star rating by one
Decrease Rating	-	Decrease the star rating by one
Get Info	Shift + I	Open the info panel for the focused item
Find Similar	Shift + S	Find songs similar to the currently playing track
Top Songs	Shift + T	Show top songs for the playing track’s artist
Move Track Up	Shift + Up	Move the focused queue track up by one position
Move Track Down	Shift + Down	Move the focused queue track down by one position
Save Queue as Playlist	Ctrl + S	Open the save-as-playlist dialog for the current queue
New Smart Playlist	Shift + N	Open the smart-playlist rules editor on a new blank playlist
Edit Centered Playlist	E	Edit the centered playlist (Playlists view) — rules editor for smart, track editor for manual
Trawl: Save Mix as Playlist	Shift + P	Save the current Trawl mix as an ordinary (static) playlist — mix builder only

Sort & View

Action	Shortcut	Description
Previous Sort Mode	Left	Cycle the sort mode backward — or step the focused Trawl control to its previous value
Next Sort Mode	Right	Cycle the sort mode forward — or step the focused Trawl control to its next value
Toggle Sort Order	Page Up	Toggle ascending / descending sort
Refresh View	R	Reload the current view’s data from the server
Roulette	Ctrl + R	Spin the wheel and play a random item from the current view

Global

Action	Shortcut	Notes
Escape / Back	Escape	Close overlays, clear search, or go back — not rebindable
Reset to Default	Delete	Reset the focused setting to its default value (Settings view only) — not rebindable

Settings Navigation

Up / Down edit values only in the Settings view. Shift + Tab / Shift + Backspace move between settings categories here, and do double duty inside the Trawl modal, where they step the controls-row focus ring.

Action	Shortcut	Description
Edit Value Up	Up	Toggle a setting on, or increment a value
Edit Value Down	Down	Toggle a setting off, or decrement a value
Next Settings Category	Shift + Tab	Move to the next category in the settings sidebar — or step the Trawl controls-row focus ring forward
Previous Settings Category	Shift + Backspace	Move to the previous category in the settings sidebar — or step the Trawl controls-row focus ring backward

Smart playlist rules editor

The smart-playlist rules editor is keyboard-first. Most of its keys are fixed context behaviors rather than rebindable actions — the exceptions are Save, which follows your Save Queue as Playlist binding (Ctrl + S by default), and the two entry-point actions above (Shift + N, E).

Building the rules (form pane):

Action	Shortcut
Move between rows	Up / Down
Step or cycle the focused cell	Left / Right
Next cell in the row	Tab
Switch between the form and the preview	Shift + Tab
Act on the focused cell — open a picker, toggle, add or remove a rule	Enter
Reorder a sort key	Shift + Up / Shift + Down
Remove the focused rule or sort key	Delete, Backspace, or x
Preview (re-evaluate on the server)	Ctrl + Enter
Save	Ctrl + S
Discard (confirms if there are unsaved edits)	Escape

While editing a text or number cell, Enter or Tab commits it and Escape reverts just that cell. In the preview pane, Up / Down move and Enter plays the evaluated list from the focused row.

Pickers and the calendar:

Action	Shortcut
Filter a list picker (field, operator, genre, playlist…)	type to filter, then Up / Down, Enter, Escape
Calendar — move by a day	Left / Right
Calendar — move by a week	Up / Down
Calendar — previous / next month	Page Up / Page Down
Calendar — pick the focused day	Enter

---

Customizing Shortcuts

All shortcuts except Escape and Delete can be rebound in the Settings UI. Nokkvi writes bindings under the [hotkeys] section of config.toml, and only non-default bindings are written, so you only need to list the ones you want to change.

A direct edit to config.toml can also override escape or reset_to_default — the loader accepts those action keys — but the in-app editor refuses to rebind them so you keep a way out of every screen.

Key combo syntax

A binding is a string in the form "Modifiers + Key". Modifiers are optional; the key name is required.

Part	Values
Modifier	Shift, Ctrl (or Control), Alt
Key	Any single character (a–z, 0–9, /, -, =, `, etc.)
Named key	Space, Enter, Escape, Backspace, Tab, Up, Down, Left, Right, Page Up, Page Down, Home, End, Delete, Insert, F1–F12

Multiple modifiers are combined with +: "Ctrl + Shift + S".

Key names are case-insensitive. "shift + l" and "Shift + L" are the same.

TOML action keys

Each action maps to a snake_case key under [hotkeys]:

Action	TOML key
Queue view	switch_to_queue
Albums view	switch_to_albums
Artists view	switch_to_artists
Songs view	switch_to_songs
Genres view	switch_to_genres
Playlists view	switch_to_playlists
Radios view	switch_to_radios
Harbour view	switch_to_harbour
Settings	switch_to_settings
Play / Pause	toggle_play
Toggle Random	toggle_random
Toggle Repeat	toggle_repeat
Toggle Consume	toggle_consume
Toggle SFX	toggle_sound_effects
Cycle Visualizer	cycle_visualization
Toggle Equalizer	toggle_eq_modal
Open Trawl	open_trawl
Toggle Crossfade	toggle_crossfade
Toggle Lyrics	toggle_lyrics
Toggle Bit-Perfect	toggle_bit_perfect
Slot List Up	slot_list_up
Slot List Down	slot_list_down
Activate	activate
Expand / Collapse	expand_center
Shuffle Play	shuffle_play
Library Browser	toggle_browsing_panel
Center on Playing	center_on_playing
Love / Unlove	toggle_star
Add to Queue	add_to_queue
Remove from Queue	remove_from_queue
Clear Queue	clear_queue
Search	focus_search
Increase Rating	increase_rating
Decrease Rating	decrease_rating
Get Info	get_info
Find Similar	find_similar
Top Songs	find_top_songs
Move Track Up	move_track_up
Move Track Down	move_track_down
Save Queue as Playlist	save_queue_as_playlist
New Smart Playlist	new_smart_playlist
Edit Centered Playlist	edit_centered_playlist
Trawl: Save Mix as Playlist	trawl_save_as_playlist
Previous Sort Mode	prev_sort_mode
Next Sort Mode	next_sort_mode
Toggle Sort Order	toggle_sort_order
Refresh View	refresh_view
Roulette	roulette
Edit Value Up	edit_up
Edit Value Down	edit_down
Next Settings Category	settings_category_next
Previous Settings Category	settings_category_prev

Example

[hotkeys]
# Rebind slot navigation to J/K (vim style)
slot_list_down = "J"
slot_list_up   = "K"

# Move the visualizer cycle to a function key
cycle_visualization = "F2"

# Use Ctrl+Shift+S to save queue as playlist
save_queue_as_playlist = "Ctrl + Shift + S"

Tip

Enable Verbose Config in Settings (or set verbose_config = "on" in config.toml) to write all default bindings to the file at once — useful as a starting point for customization.

Caution

Some keys may be captured by your window manager before Nokkvi sees them — common culprits are Super, Alt + F4, and certain Ctrl + Alt combinations. If a shortcut isn’t working, check your compositor or WM keybindings first.

Tip

To trigger Nokkvi from a WM hotkey (with or without the window focused), use the nokkvi CLI — nokkvi play-pause, nokkvi rate +1, etc. — bound through your compositor’s exec syntax. When the window isn’t focused, enable rating_change_notification_enabled to get a desktop notification confirming each rating change.