Configuration Documentation

Table of Contents

• General
  • Notes
  • Media control
  • Player event hook command
  • Client id command
  • Device configurations
  • Layout configurations
• Themes
  • Use script to add theme
  • Palette
  • Component Styles
• Keymaps

Configuration files are located in the application's configuration directory, which defaults to $HOME/.config/spotify-player.

General

A sample app.toml is available at examples/app.toml.

spotify_player uses app.toml for application settings. Available options:

Notes

• By default, spotify-player uses ncspot's client ID for compatibility with Spotify's API. See this issue for details.
• ap_port and proxy are passed to Librespot for session configuration. Librespot uses its defaults if unset.
• Setting a positive app_refresh_duration_in_ms increases API usage and may trigger rate limits. By default, playback_refresh_duration_in_ms=0 refreshes playback only on events or commands.
• enable_streaming accepts Always, Never, or DaemonOnly. For backward compatibility, true/false are also accepted.
• border_type, progress_bar_type, and progress_bar_position accept only the values listed in the table above.
• explicit_icon can be set to any Unicode character or an empty string to disable explicit markers.

Media control

Media control (enable_media_control) is enabled by default on Linux but disabled on macOS and Windows. On these platforms, the OS requires an open window to receive media events, which may cause the terminal to lose focus on startup.

Player event hook command

player_event_hook_command is an object with command and args fields. On each player event, the command executes with the event data passed as arguments.

A player event is represented as a list of arguments with either of the following values:

• "Changed" NEW_TRACK_ID
• "Playing" TRACK_ID POSITION_MS
• "Paused" TRACK_ID POSITION_MS
• "EndOfTrack" TRACK_ID

Note: If args is specified, these arguments precede the event arguments.

For example, with player_event_hook_command = { command = "a.sh", args = ["-b", "c", "-d"] }, a Changed event with NEW_TRACK_ID=id executes:

a.sh -b c -d Changed id

Example script that reads event data from arguments and logs to a file:

#!/bin/bash

set -euo pipefail

case "$1" in
    "Changed") echo "command: $1, new_track_id: $2" >> /tmp/log.txt ;;
    "Playing") echo "command: $1, track_id: $2, position_ms: $3" >> /tmp/log.txt ;;
    "Paused") echo "command: $1, track_id: $2, position_ms: $3" >> /tmp/log.txt ;;
    "EndOfTrack") echo "command: $1, track_id: $2" >> /tmp/log.txt ;;
esac

Client id command

To securely store your client_id, use client_id_command with a command and optional args. Example:

client_id_command = { command = "cat", args = ["/full/path/to/file"] }

Note: Use absolute paths; ~ is not expanded.

Device configuration

Device options are configured in the [device] section:

See the Librespot wiki for more details on these options.

Layout configuration

The [layout] section configures the UI layout:

Example:

[layout]
library = { album_percent = 40, playlist_percent = 40 }
playback_window_position = "Top"

Themes

spotify_player uses theme.toml for custom themes.

Sample themes are available at examples/theme.toml.

Select a theme by setting theme in app.toml or using the -t <THEME> / --theme <THEME> CLI flag.

A theme consists of:

• name (required): Theme name.
• palette (optional): Color palette.
• component_style (optional): Styles for UI components.

Omitted palette values use terminal colors. Omitted component_style values use default styles.

Component Styles

The component_style table customizes UI component appearance. All fields are optional:

Each style accepts optional fields:

• fg: Foreground color
• bg: Background color
• modifiers: List of style modifiers

Defaults use palette values or remain unset if not specified.

Example

[[themes]]
name = "my_theme"
[themes.component_style]
block_title = { fg = "Magenta", modifiers = ["Bold"] }
border = { fg = "White" }
selection = { modifiers = ["Reversed", "Bold"] }

Default Component Styles

block_title = { fg = "Magenta"  }
border = {}
playback_status = { fg = "Cyan", modifiers = ["Bold"] }
playback_track = { fg = "Cyan", modifiers = ["Bold"] }
playback_artists = { fg = "Cyan", modifiers = ["Bold"] }
playback_album = { fg = "Yellow" }
playback_genres = { fg = "BrightBlack", modifiers = ["Italic"] }
playback_metadata = { fg = "BrightBlack" }
playback_progress_bar = { bg = "BrightBlack", fg = "Green" }
playback_progress_bar_unfilled = { bg = "BrightBlack" }
current_playing = { fg = "Green", modifiers = ["Bold"] }
page_desc = { fg = "Cyan", modifiers = ["Bold"] }
playlist_desc = { fg = "BrightBlack", modifiers = ["Dim"] }
table_header = { fg = "Blue" }
selection = { modifiers = ["Reversed", "Bold"] }
secondary_row = {}
like = {}
lyrics_played = { modifiers = ["Dim"] }
lyrics_playing = { fg = "Green", modifiers = ["Bold"] }

Accepted Colors

Colors can be:

• Black, Blue, Cyan, Green, Magenta, Red, White, Yellow
• BrightBlack, BrightWhite, BrightRed, BrightMagenta, BrightGreen, BrightCyan, BrightBlue, BrightYellow
• Hex codes: #RRGGBB (e.g., #ff0000)

Style Modifiers

Supported modifiers:

• Bold
• Dim
• Italic
• Underlined
• RapidBlink
• Reversed
• Hidden
• CrossedOut

Specify multiple modifiers as a list: modifiers = ["Bold", "Underlined"].

Use script to add theme

The theme_parse Python script (requires toml and requests) converts iTerm2/alacritty color schemes to compatible theme format.

Example:

./theme_parse "Builtin Solarized Dark" "solarized_dark"  >> ~/.config/spotify-player/theme.toml

This converts the Builtin Solarized Dark color scheme to a theme named solarized_dark.

Palette

A theme's palette table can include:

• background
• foreground
• black
• blue
• cyan
• green
• magenta
• red
• white
• yellow
• bright_black
• bright_blue
• bright_cyan
• bright_green
• bright_magenta
• bright_red
• bright_white
• bright_yellow

Omitted fields use terminal defaults. Values can be color names or hex codes. See ANSI color reference.

Keymaps

spotify_player uses keymap.toml to add or override default key mappings. Add a keymaps entry to define a new mapping, or set the command to None to remove one. Example:

[[keymaps]]
command = "NextTrack"
key_sequence = "g n"
[[keymaps]]
command = "PreviousTrack"
key_sequence = "g p"
[[keymaps]]
command = "Search"
key_sequence = "C-c C-x /"
[[keymaps]]
command = "ResumePause"
key_sequence = "M-enter"
[[keymaps]]
command = "None"
key_sequence = "q"
[[keymaps]]
command = { VolumeChange = { offset = 1 } }
key_sequence = "-"
[[keymaps]]
command = { SeekForward = { duration = 10 } }
key_sequence = "E"
[[keymaps]]
command = { SeekBackward = { } }
key_sequence = "Q"

A complete list of actions is available here.

Actions

Actions are defined in keymap.toml and triggered by unbound key sequences. Actions target the selected item by default, but can be configured with target set to PlayingTrack or SelectedItem. See the README for available actions.

Example:

[[actions]]
action = "GoToArtist"
key_sequence = "g A"
[[actions]]
action = "GoToAlbum"
key_sequence = "g B"
target = "PlayingTrack"
[[actions]]
action="ToggleLiked"
key_sequence="C-l"