vtampv0.5.2

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.

Listen from another machine.

A server can run without an audio device and send what it plays as an Ogg Opus stream instead. Start it with --headless on the machine that holds the music, a Mac or a Linux box. The queue, the library, and the CLI work as before, and a server that plays through its own speakers can cast as well with --cast.

Listen with mpv or ffmpeg over SSH, open the stream in a player with --cast-http, or start a local vtamp with --remote: it plays the remote server through your speakers and shows its queue in the TUI.

Read about the headless server 
# On the machine with the music, macOS or Linux
vtamp server start --headless

# From any machine with mpv
ssh music-box vtamp cast listen | mpv -

# Or a local vtamp, after forwarding the socket over SSH
vtamp server start --remote /tmp/music-box.sock

Ogg Opus · 48 kHz stereo · 128 kbit/s · Each track start, seek, and resume begins a new logical stream.

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

A spectrum in fourteen styles.

Press v to show a read-only spectrum of what the server is playing, and V to switch between fourteen styles: bars, gradient, mono, mirror, dots, waterfall, radial, fire, ridge, sparks, squares, smooth, trail, and stereo.

Every style takes its colors from your theme. Audio is analyzed only while the spectrum is shown; when playback pauses or stops, it settles and stops redrawing.

See every spectrum style
Radial, fire, ridge, and sparks, five seconds each. Recorded in Ghostty at 100 × 25 cells in the Nord theme, without sound.

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 cast status --jsonCast format, URL, and listener count.
$ vtamp now --json
{
  "version": 14,
  "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? With Rust 1.90 or newer and cmake installed, clone the repository and install. On Linux the same commands build a headless server, or download the aarch64 build from the latest release.

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

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