Usage

kew creates a playlist with the contents of the first directory or file whose name matches the arguments you provide in the command-line.

kew cure great

This creates and starts playing a playlist with ‘The cure greatest hits’ if it’s in your music library.

It works best when your music library is organized this way:

artist folder->album folder(s)->track(s).

Example commands

• kew (starting kew with no arguments opens the library view where you can choose what to play)
• kew all (plays all songs, up to 50 000, in your library, shuffled)
• kew albums (plays all albums, up to 2000, randomly one after the other)
• kew moonlight son (finds and plays moonlight sonata)
• kew moon (finds and plays moonlight sonata)
• kew beet (finds and plays all music files under “beethoven” directory)
• kew dir <album name> (sometimes, if names collide, it’s necessary to specify it’s a directory you want)
• kew song <song> (or a song)
• kew play "/home/joe/Musik/Fridge - (2007) The Sun/" (Plays this album, location can be anywhere)
• kew play "/home/joe/Musik/moonlight sonata.flac" (Plays moonlight sonata, location can be anywhere)
• kew play <album path> <album path> <song path> (play can take multiple album paths or song paths and add them all into temporary playlist)
• kew list <playlist> (or a playlist)
• kew theme midnight (sets the ‘midnight.theme’ theme).
• kew shuffle <album name> (shuffles the playlist. shuffle needs to come first.)
• kew artistA:artistB:artistC (plays all three artists, shuffled)
• kew --help, -? or -h
• kew --version or -v
• kew --nocover
• kew --noui (completely hides the UI)
• kew -q <song>, --quitonstop (exits after finishing playing the playlist)
• kew -e <song>, --exact (specifies you want an exact (but not case sensitive) match, of for instance an album)
• kew . loads kew favorites.m3u
• kew path "/home/joe/Musik/" (changes the path)

Key Bindings

Basic

• Enter to play or enqueue/dequeue.
• Space, p or right mouse to play or pause.
• Use + (or =), - keys to adjust the volume.
• Use ←, → or h, l keys to switch tracks.
• Alt+s to stop.
• F2 or Shift+z (macOS/Android) to show/hide playlist view.
• F3 or Shift+x (macOS/Android) to show/hide library view.
• F4 or Shift+c (macOS/Android) to show/hide track view.
• F5 or Shift+v (macOS/Android) to show/hide search view.
• F6 or Shift+b (macOS/Android) to show/hide key bindings view.
• i to cycle colors derived from kewrc, theme or track cover.
• t to cycle themes.
• Backspace to clear the playlist.
• Delete to remove a single playlist entry.
• r to cycle repeat settings (repeat, repeat list, off).
• s to shuffle the playlist.

Advanced

• u to update the library.

• m show full page lyrics in track view. See Lyrics

• v to toggle the visualizer.

• b to toggle album covers drawn in ascii or as a normal image.

• n to toggle notifications.

• a to seek back. keep pressed for a longer duration, it executes the seek when you release the key.

• d to seek forward. keep pressed for a longer duration, it executes the seek when you release the key.

• x to save the currently loaded playlist to a m3u file in your music folder.

• Tab to switch to next view.

• Shift+Tab to switch to previous view.

• f, g to move songs up or down the playlist.

• number + G or Enter to go to specific song number in the playlist.

• . to add currently playing song to kew favorites.m3u (run with “kew .”).

• Esc to quit.

Playlists

To load a playlist: type kew list <name>

To export a playlist, press x. This will save a file in your music path with the name of the first song in the queue.

There is also a favorites playlist function:

Add current song: press .

To load ‘kew list fav’: kew .

Themes

Press t to cycle available themes.

To set a theme from the command-line, run:

kew theme <themename> (ie 'kew theme midnight')

Put themes in ~/.config/kew/themes (~/Library/Preferences/kew/themes on macOS).

Do not edit the included themes as they are managed by kew. Instead make a copy with a different name and edit that.

Try the theme editor (by @bholroyd): https://bholroyd.github.io/Kew-tip/.

Configuration

Linux: ~/.config/kew/

macOS: ~/Library/Preferences/kew/

Key bindings can be added like this:

bind = +, volUp, +5%

If you have an old install of kew, delete the kewrc file to make this style of bindings appear.

kew state (for settings that can be changed in-app) is kept in ~/.config/kew/ke wstaterc.

If you change a setting in-app it will be tracked by kewstaterc and not kewrc.

kewrc is never changed by kew with the exception of when you run kew path.

If you delete your kewrc a new default one will be generated. You wont get newe r config options listed in your config file unless you do this.

Visulizations / Chroma

Starting with kew 4.0, you can add visualizations to kew by installing Chroma, an app by another developer.

You’ll need to install a specific commit, which is the latest one that works.

How to install Chroma:

git clone https://github.com/yuri-xyz/chroma.git

cd chroma

git checkout fb00b6e

cargo install --path . --features audio

Enable and cycle through the visualizations by pressing c in track view.

Disable by pressing b.

This works by kew being fed frames from Chroma and does not add bloat to kew.

Configuration

You can customize Chroma’s behavior in your kewrc file:

• chromaPath: Path to a custom Chroma preset file. If set, this preset will be used instead of the built-in ones.
• chromaDevice: Specify the audio device for Chroma to capture from (e.g., PipeWire Sound Server). Use chroma --list-audio-devices to find available devices.

[chroma]
chromaPath=/path/to/your/custom.preset
chromaDevice=PipeWire Sound Server

Scrobbling

kew’s private and offline nature means we don’t support Scrobbling/last.fm dire ctly. Instead tools such as PanoScrobbler are recommended. See: https://github. com/kawaiiDango/pano-scrobbler.

Security

Reporting a Bug

If you find a security related issue, please contact us at kew-player@proton.me.

When a fix is published, you will receive credit under your real name or bug tracker handle in Codeberg. If you prefer to remain anonymous or pseudonymous, you should mention this in your e-mail.

Disclosure Policy

The maintainer will coordinate the fix and release process, involving the following steps:

• Confirm the problem and determine the affected versions.
• Audit code to find any potential similar problems.
• Prepare fix for the latest release. This fix will be released as fast as possible.

You may be asked to provide further information in pursuit of a fix.