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