Keybindings
Press ? in spotatui to see the help menu with all keybindings. Inside the
help menu, press the search key (/ by default) to filter rows by key,
description, or context; matching text is highlighted in the visible rows.
Press Enter to apply the filter and Esc to clear it.
The menu lists what the active source and your Spotify session can do. A
rebindable key that needs more stays listed with a suffix such as
(needs Spotify) or (not for Local Files); a fixed key of a screen the
source cannot reach is left out until you switch source or log in.
The same search key filters the Settings screen, so you can jump to a setting
instead of scrolling for it. The query is fuzzy: its characters only have to
appear in order, so volinc finds Volume Increment and skms finds
Seek Duration (ms). Rows are matched on their name and on their
config.yml key, and ranked best-first with the matched characters
highlighted. The filter applies to the tab you are on and survives ←/→, so
one query can be walked across tabs.
Default Keybindings
Every rebindable action has one row below, with its keybindings: config
key and its default from UserConfig::new. The five AI DJ keys live in the
AI DJ keys table further down.
| Action | Default | Config key |
|---|---|---|
| Go back / Quit | q |
back |
| Navigate up (vim-style) | k |
move_up |
| Navigate down (vim-style) | j |
move_down |
| Navigate left (vim-style) | h |
move_left |
| Navigate right (vim-style) | l |
move_right |
| Next page | Ctrl-d |
next_page |
| Previous page | Ctrl-u |
previous_page |
| Jump to start of list | Ctrl-a |
jump_to_start |
| Jump to end of list | Ctrl-e |
jump_to_end |
| Jump to album | a |
jump_to_album |
| Jump to artist's albums | A |
jump_to_artist_album |
| Jump to context | o |
jump_to_context |
| Switch music source / select playback device | d |
manage_devices |
| Volume down | - |
decrease_volume |
| Volume up | + |
increase_volume |
| Toggle play/pause | Space |
toggle_playback |
| Seek backward | < |
seek_backwards |
| Seek forward | > |
seek_forwards |
| Next track | n |
next_track |
| Previous track | p |
previous_track |
| Force previous track (skip position restore) | P |
force_previous_track |
| Show help | ? |
help |
| Toggle shuffle | Ctrl-s |
shuffle |
| Toggle repeat mode | Ctrl-r |
repeat |
| Search | / |
search |
| Confirm (not wired yet — rebinding it has no effect today) | Enter |
submit |
| Copy song URL | c |
copy_song_url |
| Copy album URL | C |
copy_album_url |
| Audio visualization | v |
audio_analysis |
Lyrics view (the old name basic_view still works) |
B |
lyrics_view |
| Toggle miniplayer view | T |
miniplayer_view |
Cover art view (cover-art builds — every released binary; a plain cargo run without the feature ignores it) |
G |
cover_art_view |
| Add to queue | z |
add_item_to_queue |
| Show queue | Q |
show_queue |
| Remove from queue | x |
remove_from_queue |
Open settings (Ctrl-, on macOS) |
Alt-, |
open_settings |
| Save settings | Alt-s |
save_settings |
| Listening party | Ctrl-p |
listening_party |
| Like / save track | F |
like_track |
| Generate recap | R |
generate_recap |
Pane keys
These keys arrange the views you detach beside the main layout. Alt with an
arrow key also moves the focus, and Alt-Shift with an arrow key swaps panes. See
Detached panes.
| Action | Default | Config key |
|---|---|---|
| Detach the open full-screen view into a pane, or put the focused pane back to full screen | Alt-d |
detach_pane |
| Close the focused pane, or hide the main layout when it has focus | Alt-x |
close_pane |
| Focus the pane on the left | Alt-h |
focus_pane_left |
| Focus the pane below | Alt-j |
focus_pane_down |
| Focus the pane above | Alt-k |
focus_pane_up |
| Focus the pane on the right | Alt-l |
focus_pane_right |
| Swap the focused pane with the pane on the left | Alt-H |
move_pane_left |
| Swap the focused pane with the pane below | Alt-J |
move_pane_down |
| Swap the focused pane with the pane above | Alt-K |
move_pane_up |
| Swap the focused pane with the pane on the right | Alt-L |
move_pane_right |
| Turn the split of the focused pane | Alt-r |
rotate_pane |
| Make the focused pane larger | Alt-= |
grow_pane |
| Make the focused pane smaller | Alt-- |
shrink_pane |
| Close every pane and show the main layout again | Alt-0 |
reset_panes |
A few keys in the help menu are fixed and have no config name: the sort menu
(,), the visualizer style picker (V), list jumps H / M / L, the
layout keys ({ / }, ( / ), |), s (save the selected track), and
w (add a track to a playlist). They cannot be rebound from
config.yml.
Customizing Keybindings
Edit config.yml in the spotatui app config directory ($XDG_CONFIG_HOME/spotatui
when XDG_CONFIG_HOME is set to an absolute path, or ~/.config/spotatui when
it is unset or not absolute):
keybindings:
back: "q"
jump_to_album: "a"
toggle_playback: " "
# ... etc
Every row in the tables above is a keybindings: entry: the config key names
the action and the value is its new default. Use the tables as the full list of
rebindable names — 40 actions, the 14 pane keys and the five AI DJ keys below.
Key Format
- Single keys:
"a","/"," "(or"space") - With Ctrl:
"ctrl-q","ctrl-s","ctrl--"(Ctrl and the-key) - With Alt:
"alt-,","alt-s","alt--","alt-H"for Alt with Shift, and"alt-left"or"alt-shift-left"for an arrow (left, right, up, down) - With Shift: use the capital letter,
"A","C"(Shift is not a modifier of its own) - Special keys:
"enter","tab","esc"(or"escape"),"backspace","del","left"/"right"/"up"/"down","pageup"/"pagedown","home"/"end","ins"(or"insert"), and"f0"through"f12"
All of these names are case-insensitive, so "ENTER" and "enter" both work.
A value that is a single character is taken as-is, so "A" means Shift+a.
Note: Three-key combinations like
ctrl-alt-qare not supported.
Watch out for
deletevsdel:"delete"maps to the Backspace key and"del"maps to the Delete key — the opposite of what most people expect.
Some keys are reserved and cannot be remapped through Settings: H, M and
L (jump to the top, middle and bottom of a list), up, down, left,
right, backspace and enter. The Settings screen refuses them with an
error, and a plugin_commands binding on one of them is skipped with a log
warning. Because "delete" counts as Backspace (see the note above), a plugin
command bound to delete is skipped too, and the log calls it backspace.
If a value cannot be parsed, the binding keeps its default and a warning is logged at startup. A name that is not one of the config keys in the table above (or the AI DJ keys below) is silently ignored — unknown names produce no warning, so check your spelling against the table.
AI DJ keys
Only present in builds with the ai-dj feature. All five are rebindable as
dj_open, dj_toggle_auto_queue, dj_vibe_shift, dj_toggle_fresh_only, and
dj_pick_model.
| Action | Default | Config key |
|---|---|---|
| Open the AI DJ screen | Ctrl-j |
dj_open |
| Toggle continuous auto-queue | Ctrl-t |
dj_toggle_auto_queue |
| Vibe shift (drop the DJ's queued tail, change direction) | Ctrl-y |
dj_vibe_shift |
| Toggle "only tracks I don't already have" | Ctrl-o |
dj_toggle_fresh_only |
| Choose which AI and model the DJ uses | Ctrl-g |
dj_pick_model |
On the DJ screen itself the prompt takes every printable key, so j/k type
rather than navigate; scroll the transcript with the arrow and page keys. Esc
clears a half-typed prompt, and leaves the screen when the prompt is already empty.
The four action keys other than dj_open still work while the prompt has focus,
because they carry a modifier. If you rebind one to a bare character, that character
types instead, since a typing surface has to be able to contain it.
While the AI/model picker is open it is modal and takes every key: ↑/↓ (or
j/k) move, 1-9 pick a numbered row, Enter chooses, and Esc steps back
one step at a time, closing the picker from the first step and keeping whatever
brain you already had. Nothing else reaches the DJ or the rest of the app, so a
keypress cannot start background work with the backend you are mid-way through
replacing.
See docs/ai-dj.md.