https://github.com/ravachol/kew
A marvelous terminal music player.
https://github.com/ravachol/kew
audio-player command-line kew linux macos music music-player player terminal
Last synced: 27 days ago
JSON representation
A marvelous terminal music player.
- Host: GitHub
- URL: https://github.com/ravachol/kew
- Owner: ravachol
- License: gpl-2.0
- Created: 2023-05-17T05:29:52.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-10-14T23:21:48.000Z (about 1 month ago)
- Last Synced: 2025-10-15T02:32:39.172Z (about 1 month ago)
- Topics: audio-player, command-line, kew, linux, macos, music, music-player, player, terminal
- Language: C
- Homepage: https://ko-fi.com/ravachol
- Size: 8.12 MB
- Stars: 2,061
- Watchers: 14
- Forks: 67
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: docs/SECURITY.md
Awesome Lists containing this project
- awesome-useful-projects - <img src="https://icon.horse/icon/github.com" height="20px" align="center"/>/ravachol/kew - Music player (CLI/TUI Apps / Other)
- awesome-github-repos - ravachol/kew - Music for the Shell. (C)
- awesome-tuis - kew
- awesome-cli-apps-in-a-csv - kew - A command-line music player with gapless playback and simple playlist management. (<a name="music"></a>Sound and music)
README
[](./LICENSE)
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.
* Use themes or colors derived from covers.
## 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](docs/MANUAL-INSTALL-INSTRUCTIONS.md).
## 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.
```bash
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 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 (sometimes, if names collide, it's necessary to specify it's a directory you want)
kew song (or a song)
kew list (or a playlist)
kew theme midnight (sets the 'midnight.theme' theme).
kew shuffle (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 , --quitonstop (exits after finishing playing the playlist)
kew -e , --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](#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/
## Themes
Press t to cycle available themes.
To set a theme from the command-line, run:
```bash
kew theme (ie 'kew theme midnight')
```
Put themes in \~/.config/kew/themes (\~/Library/Preferences/kew/themes on macOS).
## 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](https://www.arewesixelyet.com/).
## Lyrics
Lyrics can be read from a provided .lrc file that matches the audio file in name and content or from SYLT embedded tags on mp3 files.
Timestamped lyrics will be shown automatically in track view. Press m show full page lyrics.
## Playlists
To load a playlist: type kew list
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':
```bash
kew .
```
## License
Licensed under GPL. [See LICENSE for more information](./LICENSE).
## Attributions
Attributions
kew makes use of the following great open source projects:
Chafa by Hans Petter Jansson - https://hpjansson.org/chafa/
TagLib by TagLib Team - https://taglib.org/
Faad2 by fabian_deb, knik, menno - https://sourceforge.net/projects/faac/
FFTW by Matteo Frigo and Steven G. Johnson - https://www.fftw.org/
Libopus by Opus - https://opus-codec.org/
Libvorbis by Xiph.org - https://xiph.org/
Miniaudio by David Reid - https://github.com/mackron/miniaudio
Minimp4 by Lieff - https://github.com/lieff/minimp4
Nestegg by Mozilla - https://github.com/mozilla/nestegg
Img_To_Txt by Danny Burrows - https://github.com/danny-burrows/img_to_txt
## Authors
See [AUTHORS](./docs/AUTHORS.md).
## Contact
Comments? Suggestions? Send mail to kew-player@proton.me.