Keybindings

Keybindings

Press ? in spotatui to open the help menu with all keybindings.

All bindings in the first table are rebindable via ~/.config/spotatui/config.yml (see Configuration). The defaults are shown below.

Playback & Navigation

Key	Action	Config name
Space	Toggle play/pause	toggle_playback
n	Next track	next_track
p	Previous track	previous_track
P	Force previous track	force_previous_track
+ / -	Volume up / down	increase_volume / decrease_volume
< / >	Seek backward / forward	seek_backwards / seek_forwards
F	Like / unlike track	like_track
Ctrl-s	Toggle shuffle	shuffle
Ctrl-r	Cycle repeat mode	repeat
Enter	Select / confirm	submit
q	Go back / quit	back

Lists & Jumping

Key	Action	Config name
/	Search	search
a	Jump to album of current track	jump_to_album
A	Jump to current artist's albums	jump_to_artist_album
o	Jump to playback context	jump_to_context
d	Manage devices	manage_devices
c	Copy song URL	copy_song_url
C	Copy album URL	copy_album_url
z	Add item to queue	add_item_to_queue
Q	Show queue	show_queue
Ctrl-d	Page down	next_page
Ctrl-u	Page up	previous_page
Ctrl-a	Jump to start of list	jump_to_start
Ctrl-e	Jump to end of list	jump_to_end

Views & Screens

Key	Action	Config name
v	Audio visualization	audio_analysis
B	Lyrics view	lyrics_view
T	Mini-player view	miniplayer_view
G	Cover art view (cover-art feature)	cover_art_view
Ctrl-p	Listening Party	listening_party
R	Generate listening recap	generate_recap
Alt-,	Open settings (macOS: Ctrl-,)	open_settings
Alt-s	Save settings to config	save_settings
?	Show help	help

The lyrics_view action accepts the legacy YAML alias basic_view for backwards compatibility.

Global (non-rebindable)

These keys are handled globally and cannot be remapped:

Key	Action
Esc	Context-sensitive back (close modal / pop view)
Ctrl-f	Search tracks within the current playlist
{ / }	Decrease / increase sidebar width
( / )	Decrease / increase playbar (or library) pane height
|	Reset all pane sizes to defaults
W	Add the currently playing track to a playlist

Customizing Keybindings

Edit ~/.config/spotatui/config.yml:

keybindings:
  back: "q"
  jump_to_album: "a"
  toggle_playback: " "
  repeat: "ctrl-r"
  # ... etc

You can also bind keys to Lua plugin commands in a separate plugin_commands section — see Lua Plugins.

plugin_commands:
  my_command: "ctrl-h"

Key Format

• Single keys: "a", "/", " " (space)
• With Ctrl: "ctrl-q", "ctrl-s"
• With Alt: "alt-,", "alt-s"
• With Shift: use the capital letter "A", "C"
• Special keys: "enter", "esc", "tab"

Note: Three-key combinations like ctrl-alt-q are not supported. Plugin command keys that collide with a built-in action or a reserved navigation key (h j k l, arrows, Enter, Backspace) are ignored.