Skip to content
/ tap Public

An audio player for the terminal with fuzzy-finder.

License

Notifications You must be signed in to change notification settings

timdubbins/tap

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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