A blazing-fast, keyboard-first audio player for the terminal — with built-in fuzzy search for an intuitive, seamless way to find and play your music.
Written in Rust, fully configurable, and cross-platform — tap puts powerful playback and search features in a minimal, distraction-free UI that runs smoothly even on modest hardware.
Quick links: Usage, Options, Controls, Configuration, Installation.
-
Fuzzy Finder Interface
- fzf-style search for albums, artists, or folders
- Launches into fuzzy mode by default when run in a music library
- Jump back to fuzzy search any time with
Tab - Search results are shuffled by default, with sorting toggle
-
Full Playback Control
- Play, pause, stop, skip and seek
- Shuffle and randomized playback modes
- Mute and volume controls
- Gapless playback support
- Jump to first/last track or a specific track number
-
Keyboard-First UI
- Vim-inspired, fully customizable keybindings
- Intuitive shortcuts for playback, search and navigation
- All functionality accessible via keyboard (mouse optional)
-
Mouse Support
- Full mouse navigation in the UI
- Supports scroll, click, and cursor movement
-
Cross-Platform Support
- Runs on macOS, Linux, and Windows
- Optimized for low resource usage
-
Customizable Appearance
- Configurable themes via CLI flags or config file
- Terminal background/foreground color support
- Fine-grained color control with named themes or hex values
-
Configurable Behavior
- Optional
tap.ymlconfig file with support for:- Custom keybindings
- Default start path
- Color themes
- Default music directory support with persistent caching
- Optional
-
Flexible CLI Options
- CLI-only playback mode (
--cli) - Set or print default path
- Launch with or without custom colors/themes
- CLI-only playback mode (
-
Wide Format Support
- Plays:
mp3,flac,aac,m4a,ogg,wav
- Plays:
> tap [options] [path]Run tap in a directory containing music folders to launch the fuzzy-finder:
> cd ~/path/to/my_music
> tapPlayback 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.
To skip the fuzzy-finder and directly open an audio file or album:
> tap ~/path/to/my_album| 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). |
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 backward / forward | , / . |
| 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 |
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.
Keybindings for the player can be set in the config file. You can bind multiple keys to an event.
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
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.
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.2/tap_0.5.2.deb
> sudo dpkg -i tap_0.5.2.deb
> tap --version
0.5.2Windows
You can install with Scoop
> scoop bucket add tap https://github.com/timdubbins/scoop-tap
> scoop install tap
> tap --version
0.5.2Arch 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.4.11The AUR package is available here.
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.2The binaries for each release are also available here.
Suggestions / bug reports are welcome!