tap

tap is an audio player for the terminal. Jump to any album in your library with fuzzy-finder shortcuts!

Quick links: Bindings, Installation.

How to use

> tap [options] [path]

Run tap in a directory that contains music folders to open a fuzzy-finder, allowing you to select an album to play. Playback starts on selection and you can return to the fuzzy-finder by pressing Tab:

> cd ~/path/to/my_music
> tap

To open a player without the fuzzy-finder provide a path to an audio file or album:

> tap ~/path/to/my_album

path can be a file or directory. If it is omitted the current directory is used.

Option	Description
`-a` `--automate`	Run an automated player without the TUI. Quit with `Enter`.
`-d` `--default`	Run from the default directory, if set.
`-p` `--print`	Print the path of the default directory, if set.
`-s` `--set-default`	Set `path` as the default directory. This can significantly reduce the time it takes to load this directory. See Notes.
`-e` `--exclude`	Exclude all directories that don't contain audio files.
`-b` `--term-bg`	Use the terminal background color.
`-c` `--term-color`	Use the terminal background and foreground colors only.
`--color <COLOR>`	Set colors using <NAME>=<HEX>. See Notes for available names.

Bindings

Keyboard

Global	Keybinding	Includes
fuzzy search	`Tab`	all folders
depth search	`F1...F4`	folders at depth 1...4
filtered search	`A...Z`	artists beginning with A...Z
artist search	`Ctrl` + `a`	all artists, sorted alphabetically
album search	`Ctrl` + `s`	all albums, sorted alphabetically
parent search	`Ctrl` + `p`	folders up one level
previous album	`-`
random album	`=`
open file manager	`Ctrl` + `o`	See Notes.

Player	Keybinding
play or pause	`h` or `←` or `Space`
next	`j` or `↓`
previous	`k` or `↑`
stop	`l` or `→` or `Enter`
step forward	`.`
step backward	`,`
seek to sec	`0...9` + `"`
seek to min	`0...9` + `'`
random	`r`
volume up	`]`
volume down	`[`
show volume	`v`
mute	`m`
go to first track	`gg`
go to last track	`Ctrl` + `g`
go to track number	`0...9` + `g`
help	`?`
quit	`q`

Fuzzy	Keybinding
clear search	`Ctrl` + `u`
cancel search	`Esc`
page up	`Ctrl` + `h` or `PgUp`
page down	`Ctrl` + `l` or `PgDn`
random page	`Ctrl` + `z`

Mouse

Global	Keybinding
fuzzy search	`Middle Button`

Player	Keybinding	Where
play or pause	`Left Button`	Outside playlist
select track	`Left Button`	Inside playlist
seek	`Left Button Hold`	Inside progress bar
volume	`Scroll`	Outside playlist
next / previous	`Scroll`	Inside playlist
stop	`Right Button`	Anywhere

Fuzzy	Keybinding
cancel search	`Right Button`
scroll	`Scroll`
select	`Left Button`

Installation

macOS

You can install with Homebrew:

> brew install timdubbins/tap/tap
> tap --version
0.4.11

Arch Linux

You can install with an AUR helper, such as yay:

> yay -S tap
> tap --version
0.4.11

The AUR package is available here.

Debian (or a Debian derivative, such as Ubuntu)

You can install with a binary .deb file provided in each tap release:

> curl -LO https://github.com/timdubbins/tap/releases/download/v0.4.11/tap_0.4.11_amd64.deb
> sudo dpkg -i tap_0.4.11_amd64.deb
> tap --version
0.4.11

Rust

To compile from source, first you need a Rust installation (if you don't have one) and then you can use cargo:

> git clone https://github.com/timdubbins/tap
> cd tap
> cargo install --path .
> tap --version
0.4.11

The binaries for each release are also available here.

Notes

Supports:

Gapless playback.
aac, flac, mp3, m4a, ogg and wav.

Setting colors:

The following --color example will set a Solarized theme:

--color fg=268bd2,bg=002b36,hl=fdf6e3,prompt=586e75,header=859900,header+=cb4b16,progress=6c71c4,info=2aa198,err=dc322f

Setting an alias:

It can be useful to create an alias if you set a default directory or want to persist your color scheme. Put something like the following in your shell config (for zsh users this would be your .zshrc):

alias tap="tap -db --color fg=268bd2,bg=002b36,hl=fdf6e3,prompt=586e75,header=859900,header+=cb4b16,progress=6c71c4,info=2aa198,err=dc322f"

Running tap from any directory will now load the cached default path and set the colors to those defined in the alias (as well as setting the background color to use the terminal background). We can still use commands like tap . and tap <PATH> --color fg=ff9999 with this alias.

Setting the default directory:

This will write a small amount of encoded data to ~/.cache/tap. This is the only place that tap will write to and the data is guaranteed to be at least as small as the in-memory data. Changes in the default directory will be updated in ~/.cache/tap the next time it is accessed by tap.

As a benchmark, setting a directory that is 200GB as the default produces a ~/.cache/tap that has size 350KB (equivalent to an mp3 that is 2 seconds long) and decreases the load time by ~6x.

Opening your file manager:

You can open your preferred file manager from within tap with Ctrl + o Requires xdg-open on linux. From the fuzzy-finder this opens the currently selected directory. From the player it opens the parent of the loaded audio file.

Contributing

Suggestions / bug reports are welcome!

Inspired by

cmus - popular console music player with many features
fzf - command line fuzzy finder

Made possible by

cursive - TUI library for Rust with great documentation
rodio - audio playback library for Rust