vtampv0.1.0

A music player for the terminal that keeps playing after you detach.

Playback runs in a background server. Open the interface, pick a track, press q to close it, and reattach from any pane later.

Plays local files and live radio from one shared queue, with a JSON CLI and event stream for scripts and agents.

Install
brew install rath/tap/vtamp
Built with RustmacOS firstOpen source · MIT

Your soundtrack.
Not another window.

We loved the little player that lived on our desktop. These days, we live in a terminal. The music should feel at home here, too.

Album covers come through in high resolution with Sixel or Kitty graphics, automatically detected when you attach. Ghostty + tmux uses Kitty; Sixel in tmux requires support from both tmux and the outer terminal. Color halfblocks keep the artwork visible when pixel graphics aren’t available.

Make it feel like your terminal. Choose from nine color themes, including cozy Catppuccin Mocha, light Latte, Rosé Pine, and the original green Classic. Press t to preview, then Enter to save for your next attachment. Mocha is the default.

$ vtamp

Drop in.

A server starts if you need one. Your library, queue, and album art are right there.

q

Step out.

The interface closes. The server keeps playing. Get your pane back for the work in front of you.

$ vtamp

Pick up.

Attach again from another pane. Same music. Same queue. Exactly where it is now.

TUIPLAYBACK SERVERCLI / AGENTS

One shared queue. As many interfaces as you need.

Your Mac knows what’s playing.

Reach for the media keys you already know. Play, pause, or skip a track with the player tucked away—even after you detach from tmux.

Your track, artist, and album cover appear in macOS Now Playing. Control Center puts playback within reach, without opening a terminal.

Meet the macOS controls
F7Previous
F8Play / pause
F9Next
Built in on macOS. Start a track to join Now Playing.
Depending on your keyboard settings, hold Fn for media keys.

Now playing, in your tmux bar.

Close the player and keep the current track in sight. The optional tmux plugin shows the song title and elapsed / total time, right in your status bar.

Pause and the track stays visible. Stop playback or shut down the server and it disappears. Choose the width, add the artist, and place it wherever you like.

Set up the tmux plugin
"work"▶ Training Montage· 0:56 / 3:39
Example status bar · Your pane title, then your music.

Put #{vtamp} in your status format before loading the plugin. No clock or date required.

set -g status-right \
  '"#{=21:pane_title}" #{vtamp}'
TPM or direct loading

Good with keys.
Great with commands.

Agents can find tracks, line up what plays next, and edit the queue without interrupting the current song.

Preview a batch edit before applying it. Set a sleep timer and let the server handle the rest.

Explore the agent CLI

Local files. A local socket. No account, API key, or cloud in the middle.

FOR YOU AND YOUR AGENTCLI
vtamp now --jsonSee what’s playing.
vtamp library search --artist "DAY6" --jsonFind the right tracks.
vtamp sleep set 30mStop in 30 minutes.
$ vtamp now --json
{
  "version": 6,
  "ok": true,
  "data": {
    "status": "playing",
    "position_ms": 102000,
    "remaining_ms": 117000,
    "queue_revision": 42
  }
}
Response excerpt · current track and settings, without the full queue.

Press play.
Then get on with it.

Bring a folder of music and a terminal.
vtamp takes care of the rest.

macOS · Homebrew or Rust 1.90+ · local audio files
AAC / ALAC m4a, MP3, FLAC, WAV, Ogg Vorbis

HOMEBREW · APPLE SILICON

One command, no Rust toolchain. Then register a folder and attach:

# Install the player
brew install rath/tap/vtamp

# Register your music folder
vtamp library add ~/Music

# Attach. Pick a track. Press Enter.
vtamp

No permanent pane required. q to detach.

BUILD FROM SOURCE

Intel Mac, or no Homebrew? Clone the repository, then install with Rust 1.90 or newer:

# Get the source
git clone https://github.com/rath/vtamp.git
cd vtamp

# Install the player
cargo install --locked --path .