Theme Format

Benben stores its themes in YAML format files within a special themes folder in its configuration directory. The location of the themes folder depends on your platform:

• On Linux/Unix: $XDG_CONFIG_HOME/benben/themes/ (this usually means ~/.config/benben/themes/).

Each theme is stored in its own file, and the filename of each theme must use the format theme-<theme name>.yaml. So for example, a theme named "dark-custom" must be in the themes directory and have the filename theme-dark-custom.yaml.

If this directory does not exist, Benben will create it at startup. If no theme is specified, Benben uses its default built-in theme.

Specifying a Theme

The theme to use is specified in your main configuration file in the ui-config section:

ui-config:
  theme: default

You can also change the theme on the command line:

benben --theme smooth-neon coolfile.mp3

To see a list of themes, use the --list-themes argument.

Color Values

Colors can be expressed in one of three ways:

• An integer between 0 and 255, inclusive. This acts as an index into the 8-bit ANSI color table, so for example a value of 33 would be a light blue color.
• An array of three integer values, each between 0 and 255, inclusive. This defines a 24-bit RGB color, where the first element is the red value, the second is the green, and the third is the blue.
• A string in the format #RRGGBB, which also defines a 24-bit RGB color. RR is a hex value between 00 and FF, inclusive, that defines the red value, GG is a hex value for green, and BB is a hex value for blue. Note that the leading # is required, and you'll need to enclose this in double quotes.

My Theme Isn't Working!

Are you using 24-bit color values? If you are, and you're sure your terminal supports 24-bit ANSI colors, then it may be that the underlying S-Lang library just isn't detecting support for it properly. Try doing this before launching Benben:

export COLORTERM=truecolor

This will force it to treat the terminal as support 24-bit colors.

Theme Keys

Key	Type	Description
version	The integer value 1	The version of the Theme Format specification this file conforms to. In all cases, this should be set to 1. The default is 1 if this key is not specified.
bg-color	A color value	The color of the background.
fg-color	A color value	The color of all text that isn't covered by another key. In other words, the default foreground color.
banner-color	A color value	The color of the banner text.
banner-lines	An array of color values	The colors of the lines above and below the banners. The last color is the one used when the banner is not animating. Note that the banner will cycle through these twice when animating. There can be a maximum of 15 colors, and there must be at least one.
banner-fade-down-bright	A color value	The color of bright lines when the banner text is doing its fade-down animation.
banner-fade-down-dim	A color value	The color of dim lines when the banner text is doing its fade-down animation.
header-color	A color value	The color of the field headers.
err-color	A color value	The color of the "Error: " text when displaying an error.
cur-song-color	A color value	The color of the currently playing song in the playback queue.
prev-song-color	A color value	The color of the previous song in the playback queue.
next-song-color-1	A color value	The color of the song that is next in the playback queue.
next-song-color-2	A color value	The color of the song that is two spots away in the playback queue.
next-song-color-3	A color value	The color of all songs three spots away and further in the playback queue.
song-queue-box-color	A color value	The color of the border of the playback queue box.
song-queue-header-color	A color value	The color of the "Song Queue" header text of the playback queue box.
progress-bar-char	A single character, or a string containing a single character.	The character used to draw the progress part (left-hand side) of the progress bar. This can be any UTF-8 encoded character as long as it's equivalent to a single Unicode code point (a single "character", essentially).
progress-bar-space-char	A single character, or a string containing a single character.	The character used to draw the right-hand side of the progress bar. This can be any UTF-8 encoded character as long as it's equivalent to a single Unicode code point (a single "character", essentially).
progress-bar-colors	An array of one or more color values	The colors for the progress bar. There must be at least one color, and there can be up to 38 different colors.
vu-clip-color	A color value	The color of the words "Left" and "Right" displayed next to the VU meters when a song clips).
vu-clipped-channel-time	An integer between 0 and 255, inclusive	How long in seconds the words "Left" and "Right" remain in their vu-clip-color when Benben detects that clipping has occurred.
vu-bar-character	A single character, or a string containing a single character.	The character used to draw the bar segments of the VU meter. This can be any UTF-8 encoded character as long as it's equivalent to a single Unicode code point (a single "character", essentially).
vu-tip-character	A single character, or a string containing a single character.	The character used to draw the tip of the VU meter. This can be any UTF-8 encoded character as long as it's equivalent to a single Unicode code point (a single "character", essentially).
vu-colors	An array of one or more color values	The colors for each VU meter segment. There must be at least one color, and there can be up to 70 different colors.

Example Theme Files

Example 1: theme-remilia.yaml

This is a complete theme file for YAML, and is the same as the "theme-remilia.yaml" that is in the themes directory in the repository.

bg-color: 0
fg-color: 250
header-color: 255
err-color: 196
cur-song-color: 201
prev-song-color: 242
next-song-color-1: 244
next-song-color-2: 239
next-song-color-3: 236
song-queue-box-color: 250
song-queue-header-color: 99

progress-bar-char: "*"
progress-bar-space-char: "-"
progress-bar-colors: [[170, 170, 170]]

vu-clip-color: 196
vu-clipped-channel-time: 1
vu-bar-character: "\u25A0"
vu-tip-character: "\u25B6"
vu-colors:
  - 105
  - 117
  - 119
  - 190
  - 206
  - 161

And this is how it looks:

Example 2: theme-semi-retro.yaml

The following is a separate example that's the same as the "theme-semi-retro.yaml" file in the themes directory of the repository. Note how this uses arrays to define most of its color values, but a few are integers or #RRGGBB format.

bg-color: [14, 15, 16]
fg-color: [174, 188, 211]
header-color: [31, 162, 131]
err-color: [192, 6, 11]
cur-song-color: [23, 169, 78]

prev-song-color: [58, 68, 142]
next-song-color-1: [26, 102, 96]
next-song-color-2: [44, 80, 88]
next-song-color-3: 236
song-queue-box-color: "#3B398D"
song-queue-header-color: "#B437FC"

progress-bar-char: "*"
progress-bar-space-char: "-"
progress-bar-colors: [[170, 170, 170]]

vu-clip-color: "#A9201B"
vu-clipped-channel-time: 1
vu-bar-character: "\u25A0"
vu-tip-character: "\u25B6"
vu-colors:
  - [59, 57, 141]
  - [13, 103, 171]
  - [36, 158, 75]
  - [194, 151, 7]
  - [175, 58, 58]

And this is how it looks: