kew(5)

Usage

~/.config/kew/kewrc (Linux/FreeBSD/Android), ~/Library/Preferences/kew/kewrc (macOS)

Overview

kewrc is the configuration file for kew(1), a terminal music player. It is written in INI-style syntax, divided into named sections enclosed in square brackets, each containing key=value pairs. Lines beginning with # are comments.

kew does not write to this file except when the path command is run. Runtime changes made from within the application are instead tracked in kewstaterc(5), whose settings take precedence over the corresponding values in kewrc.

If kewrc is deleted, kew regenerates it on next launch with all available settings and their defaults.

Miscellaneous section

Settings in the [miscellaneous] section.

path path: Path to the music library directory. Default: ~/Music.

useArtistsDb bool: Enable the artist database, which provides clickable artist links in track view. Default: 1.

allowNotifications bool: Enable desktop notifications. Default: 1.

stripTrackNumbers bool: Remove leading track numbers from file names as displayed in the library and playlist views. Default: 1.

searchHierarchy bool: Allow search terms to match in order across directory and file names. Default: 0.

hideLogo bool: Hide the kew logo. Default: 0.

hideHelp bool: Hide the help line. Default: 0.

hideFooter bool: Hide the footer. Default: 0.

hideTimeStatus bool: Hide the track time line from track view. Default: 0.

simpleTimeStatus bool: Toggle display of kHz and bitrate alongside the time status. Default: 1.

hideSideCover bool: Hide the cover art shown on the left-hand side when a song is playing, in most views. Default: 0.

collapseTopLevel bool: Show only top-level folders in the library view. Default: 0.

autoCloseFolders bool: Close opened folders when navigating away in Library and Search. Set to 0 to keep multiple folders open until each is closed. Default: 1.

autoResume bool: Resume the last playing song automatically when kew starts. Default: 0.

titleDelay bool: Enable the animated (scrolling) song title. Set to 0 to disable. Default: 1.

quitOnStop bool: Exit kew after the whole playlist has finished playing. Equivalent to the --quitonstop command-line flag. Default: 0.

clearListClearsAll bool: Whether clearing the playlist also removes the currently playing song. Default: 1.

hideGlimmeringText bool: Hide the glimmering text effect on the bottom row. Default: 0.

replayGainCheckFirst int

Which ReplayGain value to check first.

0: track

1: album

2: disabled

3: auto

: Default: 3.

saveRepeatShuffleSettings bool: Persist the repeat and shuffle state between sessions. Default: 0.

repeatState int

Repeat mode.

0: off

1: repeat track

2: repeat list

: Default: 0.

shuffleEnabled bool: Enable shuffle playback. Default: 0.

trackTitleAsWindowTitle bool: Set the terminal window title to the title of the currently playing track. Default: 1.

Colors section

Settings in the [colors] section.

theme name: Name of the theme file to load, located in ~/.config/kew/themes (Linux/FreeBSD/Android) or ~/Library/Preferences/kew/themes (macOS). Empty selects the default theme.

colorMode int

Selects the source of the color palette.

0: 16-bit color palette from the default theme

1: colors derived from the One Album Color theme

2: colors derived from the TrueColor theme

3: colors derived from the Album Colors theme

4: neutral, devoid of color

: Default: 3.

Crossfade section

Settings in the [crossfade] section.

`alwaysCrossfade bool`	Crossfade at the end of every song. Default: 0.
`fadeEnterSongMs ms`	Fade in a song starting at this track time, in milliseconds. Default: 0.
`fadeQuickMs ms`	Duration, in milliseconds, of a quick fade. Default: 3000.
`fadeMediumMs ms`	Duration, in milliseconds, of a medium fade. Default: 5000.
`fadeSlowMs ms`	Duration, in milliseconds, of a slow fade. Default: 10000.

Track cover section

Settings in the [track cover] section.

coverEnabled bool: Enable rendering of cover art. Default: 1.

coverAnsi bool: Render covers using ASCII/ANSI art mode. Default: 0.

coverStyle style: Cover art render style. One of auto, kitty, sixels, block, braille, ascii, dot, vhalf, or quad. Default: auto.

Mouse section

Settings in the [mouse] section.

mouseEnabled bool: Enable mouse support. Default: 1.

Discord section

Settings in the [discord] section.

discordRPCEnabled bool: Show now-playing status via Discord Rich Presence. Note that enabling this reveals your listening habits to Discord. Default: 0.

Chroma section

Settings in the [chroma] section.

chromaPath path: Path to visualizer presets.

chromaDevice name: Name of the audio device that Chroma should use, for example Pipewire Server.

visualizationsMode bool: Preferred visualizations mode. Either 0 for ASCII or 1 for sixels. Chroma is ASCII only.

visualizationsFps int: Visualizations frame per second.

visualizationsShowPresetInfo bool: Show preset author and name, works for pmstream. Either 1 for show or 0 for not showing.

Visualizer section

Settings in the [visualizer] section.

visualizerColorType int

Visualizer color mode.

0: lighten

1: flat

2: reversed lighten

3: party

4: vibrant

5: lum vibrant

6: binning

7: two color gradient

8: off

: Default: 3.

visualizerHeight n: Height of the visualizer, in rows. Default: 6.

visualizerBrailleMode bool: Render the visualizer using Braille dots instead of bars. Default: 0.

visualizerBarWidth int

Bar width mode.

0: thin bars

1: bars twice the width

2: auto (depends on window size)

: Default: 2.

Progress bar section

Settings in the [progress bar] section, controlling the appearance of the track progress bar. Each character setting takes a single glyph (which may be an empty space); even/odd variants let the bar alternate between two glyphs across its length. When editing, always supply every value, including any that are blank spaces, or the bar's appearance will be corrupted.

`progressBarElapsedEvenChar char`	Glyph for even-indexed positions already elapsed. Default: −(U+2501).
`progressBarElapsedOddChar char`	Glyph for odd-indexed positions already elapsed. Default: −(U+2501).
`progressBarApproachingEvenChar char`	Glyph for even-indexed positions not yet reached. Default: −(U+2501).
`progressBarApproachingOddChar char`	Glyph for odd-indexed positions not yet reached. Default: −(U+2501).
`progressBarCurrentEvenChar char`	Glyph for the current position when on an even index. Default: −(U+2501).
`progressBarCurrentOddChar char`	Glyph for the current position when on an odd index. Default: −(U+2501).

Commented-out presets are provided in the generated file as examples, including a "pill muncher" style (using • (ᗧ) glyphs) and a dotted style using □ characters; uncomment and adapt a full set of six values to switch styles.

Key bindings section

The [key bindings] section holds custom key binding assignments.

Enter is bound to expandFolder by default. It opens a selected folder; pressing it again enqueues or dequeues that folder. If both actions are explicitly bound to the same key, expandFolder takes precedence so the first press still opens the folder. The collapseFolder and switchSearchFocus actions have no default binding. The latter toggles between editing the search query and navigating results with printable keys. To enable them, add bindings such as:

bind = Shift+e, collapseFolder
bind = Ctrl+f, switchSearchFocus

Note: Ctrl+h , Ctrl+i , and Ctrl+m are indistinguishable from Backspace, Tab, and Enter respectively at the terminal level, and cannot be bound separately from them.

Files

~/.config/kew/kewrc: Configuration file on Linux, FreeBSD, and Android.

~/Library/Preferences/kew/kewrc: Configuration file on macOS.

~/.config/kew/themes ~/Library/Preferences/kew/themes: Directories where theme files are looked up.