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.
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 |
| Theater Mode | F11 | Show only the now-playing cover, visualizer and lyrics; the player bar slides in when the mouse moves. See Theater Mode |
Playback
Section titled “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 → MilkDrop |
| Next Preset | N | MilkDrop: jump to another preset (only while MilkDrop is playing on screen) |
| Previous Preset | P | MilkDrop: go back to the preset before this one |
| Lock Preset | Shift + M | MilkDrop: keep the current preset until pressed again |
| 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 lyrics over the Queue cover art; in Auto, for the playing song only |
| Toggle Bit-Perfect | B | Cycle bit-perfect output: off → strict → relaxed (turns off crossfade) |
| Seek Backward | Left | Jump back by the Seek Step (5s default, 1–60s). Hold to scrub — or step the focused Trawl control to its previous value |
| Seek Forward | Right | Jump ahead by the Seek Step. Hold to scrub — or step the focused Trawl control to its next value |
Navigation
Section titled “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 |
| Up / Down | Up / Down | Also move up and down the list, everywhere but Settings, Trawl and a search box you’re typing in (see Settings Navigation) |
| Activate / Enter | Enter | Play or open the focused item |
| Focus Navigation | Menu | Highlight the view tabs: the arrows move along them, Enter opens one, Escape goes back to the list. This is how a TV remote’s Menu button reaches the other views |
| 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
Section titled “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 |
| Similar Artists | Shift + R | Open the Similar Artists popup for the focused item’s artist. Press it again to close the popup |
| 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
Section titled “Sort & View”| Action | Shortcut | Description |
|---|---|---|
| Previous Sort Mode | Shift + Left | Cycle the sort mode backward — or step the focused Trawl control to its previous value |
| Next Sort Mode | Shift + 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
Section titled “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 |
Media Keys and TV Remotes
Section titled “Media Keys and TV Remotes”A keyboard’s media keys and a TV remote with a USB dongle (an air mouse like the G20S) work out of the box on a Wayland desktop. These are fixed, like Escape:
| Key | What it does |
|---|---|
| Play/Pause, Media Pause, Media Stop | Play, pause or stop playback, even with a popup open |
| Next Track / Previous Track | Skip to the next or previous track, even with a popup open |
| Home Page (a remote’s Home) | Go to Harbour (Plasma Bigscreen keeps this key for its own home screen) |
| A remote’s OK | Play or open the focused item, like Enter. Wayland only: X11 can’t carry this key |
| A remote’s Back | Back out of a popup, a menu, a search box or Theater Mode, like Escape. With nothing left to back out of, it highlights the view tabs |
On a remote, the D-pad’s Up / Down move through the list, Left / Right seek, OK plays the focused item and Back goes back. To switch views, press Back until there’s nothing left to back out of (a popup, a search, an expanded album): the next Back highlights the view tabs. Then Left / Right move along the top bar (Up / Down in the side bar), OK opens one, and Back or the arrow toward the list leaves. The Menu button does the same (Focus Navigation) on desktops that pass it through; Plasma Bigscreen keeps Menu, Home and Settings for its own screens. A press acts once even when the TV box is busy: Enter, Escape and the highlighted tabs don’t repeat.
Plasma, GNOME and most compositor configs take the media and volume keys for themselves. Nokkvi then gets play/pause, next and previous through MPRIS instead, so they still work. Where the desktop leaves them alone, the media keys reach nokkvi only while its window has focus.
Every other remote or media key can be bound to any action: Search, Favorites, Forward, Refresh, Rewind, Fast Forward, Volume Up, Volume Down and Mute. A button with no key name at all (a remote’s voice button, say) binds by its Linux key number and shows as Key 582. Press it while a row in Settings > Hotkeys is waiting for a key, or look for Key with no name pressed in nokkvi.log.
In Theater Mode, Escape leaves it. Keys that act on the hidden list (Tab, Enter, ratings, queue edits) leave it too without acting, and view keys leave it and then switch.
Settings Navigation
Section titled “Settings Navigation”In the Settings view, Up / Down edit values; everywhere else they move through the list, except in Trawl and while you’re typing in a search box. 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
Section titled “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
Section titled “Customizing Shortcuts”All shortcuts except Escape, Delete, the media keys and Home Page 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.
When two actions share a key
Section titled “When two actions share a key”Rebinding in the Settings UI can’t create a shared key: pressing a combo another action already holds swaps the two, and the row confirms it — Swapped with Seek Forward. Nothing is left double-bound.
Hand-editing config.toml can, and then Nokkvi picks one owner in a fixed order — the same on every launch, and the same answer the conflict check gives:
- A reserved action (
escape,reset_to_default) always wins, so nothing parked on one can shadow your way out of a screen. - Otherwise, an action moved off its default wins over one merely sitting where it shipped — you put it there on purpose.
- Otherwise, the action declared first wins.
Loading a config with a shared combo logs one warning per combo naming every claimant and the winner, so nokkvi.log tells you which one is live.
Key combo syntax
Section titled “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 |
| Remote and media key | Menu, Home Page, Search, Favorites, Forward, Refresh, Play/Pause, Media Pause, Media Stop, Next Track, Previous Track, Rewind, Fast Forward, Volume Up, Volume Down, Mute |
| Key with no name | Key 582 (its Linux key number, as evtest shows it) |
Multiple modifiers are combined with +: "Ctrl + Shift + S".
Key names are case-insensitive. "shift + l" and "Shift + L" are the same.
TOML action keys
Section titled “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 |
| Theater Mode | toggle_theater |
| 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 |
| Next Preset | next_visualizer_preset |
| Previous Preset | previous_visualizer_preset |
| Lock Preset | toggle_visualizer_preset_lock |
| Toggle Equalizer | toggle_eq_modal |
| Open Trawl | open_trawl |
| Toggle Crossfade | toggle_crossfade |
| Toggle Lyrics | toggle_lyrics |
| Toggle Bit-Perfect | toggle_bit_perfect |
| Seek Backward | seek_backward |
| Seek Forward | seek_forward |
| Slot List Up | slot_list_up |
| Slot List Down | slot_list_down |
| Activate | activate |
| Expand / Collapse | expand_center |
| Focus Navigation | focus_navigation |
| 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 |
| Similar Artists | similar_artists |
| 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 |
The fixed keys have TOML keys too, which only a direct edit to config.toml can move: escape, reset_to_default, media_play_pause, media_pause, media_stop, media_next_track, media_previous_track and go_home.
Example
Section titled “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 keycycle_visualization = "F2"
# Use Ctrl+Shift+S to save queue as playlistsave_queue_as_playlist = "Ctrl + Shift + S"
# A remote's voice button (Linux key 582) as play/pause (moves it off Space)toggle_play = "Key 582"