Configuration

Configuration

A configuration file is located at ~/.config/spotatui/config.yml.

Note: This is not to be confused with client.yml, which handles Spotify authentication.

You can point spotatui at a different file with spotatui --config /path/to/config.yml.

Sample Configuration

# Colours can be an rgb string of the form "255, 255, 255" or a terminal colour
# name: Reset, Black, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, DarkGray,
# LightRed, LightGreen, LightYellow, LightBlue, LightMagenta, LightCyan, White.
theme:
  preset: "Default (Cyan)"   # named preset; set to Custom to use the colours below
  active: Cyan               # current playing song in list
  banner: LightCyan          # the "spotatui" banner on launch
  error_border: Red          # error dialog border
  error_text: LightRed       # error message text
  hint: Yellow               # hint text in errors
  hovered: Magenta           # hovered pane border
  inactive: Gray             # borders of inactive panes
  playbar_background: Reset   # background of progress bar
  playbar_progress: LightCyan # filled-in part of the progress bar
  playbar_progress_text: White # song length and time indicator
  playbar_text: Reset        # artist name in player pane
  selected: LightCyan        # selected pane border, hovered item, track title
  text: Reset                # text in panes
  header: Reset              # header text in panes
  background: Reset          # pane background
  highlighted_lyrics: LightCyan # current line in the lyrics view

behavior:
  seek_milliseconds: 5000
  volume_increment: 10
  volume_percent: 100               # startup volume
  # Lower = higher FPS for audio visualization (but more expensive)
  tick_rate_milliseconds: 250
  animation_tick_rate_milliseconds: 16  # refresh cadence for animated views
  enable_text_emphasis: true
  show_loading_indicator: true
  enforce_wide_search_bar: false
  enable_global_song_count: true
  disable_mouse_inputs: false
  set_window_title: true
  shuffle_enabled: false            # persist shuffle state across sessions
  stop_after_current_track: false
  keepawake_enabled: true           # prevent the system sleeping while playing

  # Startup
  startup_behavior: continue        # continue | play | pause
  disable_auto_update: false
  auto_update_delay: "0"            # 0, 30s, 10m, 2h, 7d ...

  # Discord Rich Presence
  enable_discord_rpc: true
  # discord_rpc_client_id: "..."    # optional: override the built-in app id

  # In-app announcements
  enable_announcements: true
  # announcement_feed_url: "..."    # optional: override the feed

  # Audio visualizer
  visualizer_style: Equalizer       # Equalizer | BarGraph

  # Listening Party
  relay_server_url: "wss://spotatui-party.spotatui.workers.dev/ws"
  # sync_token: "..."               # spotatui.com token (for the Friends feature)

  # Layout (also adjustable live with { } ( ) and | )
  sidebar_width_percent: 20
  playbar_height_rows: 6
  library_height_percent: 30

  # Cover art (requires the `cover-art` build feature)
  draw_cover_art: true
  draw_cover_art_forced: false
  playbar_cover_art_size_percent: 100

  # Icons (require a patched nerd font)
  liked_icon: ♥
  shuffle_icon: 🔀
  repeat_track_icon: 🔂
  repeat_context_icon: 🔁
  playing_icon: ▶
  paused_icon: ⏸

keybindings:
  back: "q"
  jump_to_album: "a"
  jump_to_artist_album: "A"
  manage_devices: "d"
  decrease_volume: "-"
  increase_volume: "+"
  toggle_playback: " "
  seek_backwards: "<"
  seek_forwards: ">"
  next_track: "n"
  previous_track: "p"
  copy_song_url: "c"
  copy_album_url: "C"
  help: "?"
  shuffle: "ctrl-s"
  repeat: "ctrl-r"
  search: "/"
  audio_analysis: "v"
  jump_to_context: "o"
  lyrics_view: "B"
  add_item_to_queue: "z"
  show_queue: "Q"
  like_track: "F"
  listening_party: "ctrl-p"
  open_settings: "alt-,"

# Bind keys to Lua plugin commands (see the Lua Plugins page)
plugin_commands:
  # my_command: "ctrl-h"

See Keybindings for the full list of rebindable actions and their defaults.

Behavior Reference

Field	Default	Purpose
seek_milliseconds	5000	How far to seek per keypress
volume_increment	10	Volume step per keypress
volume_percent	100	Startup volume
tick_rate_milliseconds	250	Normal UI refresh cadence
animation_tick_rate_milliseconds	16	Refresh cadence for animated views
enable_text_emphasis	true	Bold/italic text styling
show_loading_indicator	true	Show spinner while loading
enforce_wide_search_bar	false	Always show the wide search bar
enable_global_song_count	true	Anonymous global play-counter increment
disable_mouse_inputs	false	Disable mouse click/scroll
set_window_title	true	Set terminal title to the current track
shuffle_enabled	false	Persist shuffle across sessions
stop_after_current_track	false	Pause after the current track ends
keepawake_enabled	true	Prevent system sleep while playing
startup_behavior	continue	continue / play / pause on launch
disable_auto_update	false	Skip the auto-update check
auto_update_delay	"0"	Delay before applying an available update
enable_discord_rpc	true	Discord Rich Presence
discord_rpc_client_id	built-in	Override the Discord application id
enable_announcements	true	Show in-app announcements
announcement_feed_url	built-in	Override the announcement feed
visualizer_style	Equalizer	Equalizer or BarGraph
relay_server_url	spotatui worker	Listening Party WebSocket relay
sync_token	(none)	spotatui.com token for Friends
sidebar_width_percent	20	Sidebar width (% of terminal)
playbar_height_rows	6	Playbar height (rows)
library_height_percent	30	Library pane height (% of left column)
draw_cover_art	true	Cover art in the playbar (cover-art feature)
draw_cover_art_forced	false	Force cover art without terminal image support
playbar_cover_art_size_percent	100	Cover art size (clamped 25–200)

In-App Settings

Press Alt-, (macOS: Ctrl-,) to open the Settings screen, where you can customize spotatui without editing config files. Press Alt-s to save changes back to config.yml.

Settings Categories

Category	Description
Behavior	Seek, volume, tick rate, icons, startup, toggles, sync token
Keybindings	View and rebind keys
Theme	Color presets and individual color customization