tap

tap is a TUI audio player with fuzzy-finder. Quickly navigate to any album in your library!

Quick links: Options, Controls, Configuration, Installation.

Usage

> tap [options] [path]

Fuzzy-Finder

Run tap in a directory containing music folders to launch the fuzzy-finder:

> cd ~/path/to/my_music
> tap

Playback will begin on selection and you can return to the fuzzy-finder by pressing Tab.

If no path is specified, tap defaults to the current working directory.

Direct Playback

To skip the fuzzy-finder and directly open an audio file or album:

> tap ~/path/to/my_album

Options

Option	Description
-d --default	Run from the default directory, if set.
-p --print	Print the path of the default directory, if set.
-s --set	Set a default directory. Requires a tap.yml config file.
-b --term-bg	Use the terminal background color.
-t --term-color	Use the terminal background and foreground colors only.
-c --default-color	Ignore any user-defined colors.
--color <COLOR>	Set your own color scheme. See here for available names.
--cli	Play audio in CLI-mode (without the TUI).

Controls

Keyboard

Global	Binding
previous album	-
random album	=
fuzzy search	Tab
artist search	Ctrl + a
artist search (a-z)	A-Z
album search	Ctrl + d
depth search (1-4)	F1-F4
parent search	`
open file manager	Ctrl + o
quit	Ctrl + q

Note: Search results are shuffled by default. Sort with Ctrl + s.

Player	Binding
play or pause	h or ← or Space
next	j or n or ↓
previous	k or p or ↑
stop	l or → or Ctrl + j or Enter
randomize	* or r (next track is random from library)
shuffle	~ or s (current playlist order is shuffled)
seek << / >>	, / .
seek to second	0-9, "
seek to minute	0-9, '
volume down / up	[ / ]
toggle volume display	v
toggle mute	m
go to first track	gg
go to last track	Ctrl + g
go to track number	0-9, g
show keybindings	?
quit	q

Finder	Binding
select	Ctrl + j or Enter
next	Ctrl + n or ↓
previous	Ctrl + p or ↑
sort results	Ctrl + s
cursor right	Ctrl + f or →
cursor left	Ctrl + b or ←
cursor home	Home
cursor end	End
clear query	Ctrl + u
cancel search	Esc
page up	PageUp
page down	PageDown

Mouse

Global	Binding
fuzzy search	Middle Button

Player	Binding
play or pause	Left Click (in window)
select track	Left Click (on track)
seek	Left Hold (on slider)
volume	Scroll (in window)
next / previous	Scroll (over tracks)
stop	Right Click (anywhere)

Finder	Binding
cancel search	Right Click
scroll	Scroll
select	Left Click

Configuration

tap doesn't create the config file for you, but it looks for one in the following locations:

• $XDG_CONFIG_HOME/tap/tap.yml
• $XDG_CONFIG_HOME/tap.yml
• $HOME/.config/tap/tap.yml
• $HOME/.tap.yml

A example config file can be found here.

Colors

Colors can be set in the config file or using the --color command.

The following example will set a Solarized theme:

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

Default Path

The default path can be set in the config file. This allows you to load the default directory with the -d --default command and also provides faster load times by caching.

When setting a default path tap will write a small amount of encoded data to ~/.cache/tap. This is guaranteed to be at least as small as the in-memory data and will be updated everytime the default path is accessed. Using the -s --set command will update the path field in the tap.yml config file.

Without setting a default path tap is read-only.

Installation

You will need an ncurses distribution (with development headers) to compile tap. Installation instructions for each supported platform are below:

macOS

You can install with Homebrew

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

ncurses can be installed with:

> brew install ncurses

Arch Linux

You can install with an AUR helper, such as yay

The Arch package is not currently maintained. Please install with Rust.

> yay -S tap
> tap --version
0.5.0

ncurses can be installed with:

> yay -S ncurses

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.5.0/tap_0.5.0.deb
> sudo dpkg -i tap_0.5.0.deb
> tap --version
0.5.0

ncurses can be installed with:

> sudo apt install libncurses5-dev libncursesw5-dev

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

The binaries for each release are also available here.

Notes

Supports:

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

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