GitHub - ravachol/kew: Music for the Shell.

kew (/kjuː/) is a terminal music player.

Features

Search a music library with partial titles from the command-line.
Creates a playlist automatically based on matched song, album or artist.
Private, no data is collected by kew.
Music without distractions or algorithmic manipulation.
Full color covers in sixel-capable terminals.
Visualizer with various settings.
Edit the playlist by adding, removing and reordering songs.
Gapless playback.
Explore the library and enqueue files or folders.
Search your music library and add to the queue.
Supports MP3, FLAC, MPEG-4/M4A (AAC), OPUS, OGG, Webm and WAV audio.
Supports desktop events through MPRIS.
Supports lyrics through .lrc files, embedded SYLT (Mp3) or Vorbis comments (Flac,Ogg,Opus).
Use themes or colors derived from covers.

⚠️ This repository has moved to Codeberg!

Active development and issue tracking now happens at Codeberg. Please open new issues and pull requests there.

Installing

Install through your package manager or homebrew (macOS). If you can't find it on your distro, or you want the bleeding edge, follow the Manual Installation Instructions.

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.

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 20 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.
d to seek forward.
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.

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 ~/.local/state/kewstaterc.

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.

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/.

Visulizations / Chroma

Starting with kew 4.0, you can add visualizations to kew by installing Chroma:

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

For the time being you need to install from the develop branch:

git clone https://github.com/yuri-xyz/chroma.git --single-branch --branch develop
cd chroma
cargo build --release --features audio

That's it!

Enable and cycle through them 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.

If Colors or Graphics Look Wrong

Cycle i until they look right.

Press v to turn off visualizer.

Press b for ASCII covers.

A terminal emulator that can handle TrueColor and sixels is recommended. See Sixels in Terminal.

Lyrics

Lyrics can be read from a provided .lrc file that matches the audio file in name and content, from Vorbis comment metadata or from SYLT embedded tags on mp3 files.

Timestamped lyrics will be shown automatically in track view. Press m show full page lyrics.