v0.5.3 — Android app and tmux video fixes

An Android app in android/ plays the Library, its saved videos, and radio over
the HTTP API. Terminal video in tmux no longer flashes the cursor or splits rows
between frames in Ghostty 1.4.

Added

• An Android app in android/ for the HTTP API, for Android 10 and later. It
  browses and searches the Library with kind filters, shows the server's Queue
  read-only, and starts YouTube imports when the server offers yt-dlp. It plays
  Library files and radio on the phone with its own queue, background media
  controls, shuffle, and repeat, and never changes the server's playback or
  Queue. Saved video plays in step with the audio, keeps HDR output, and
  continues across fullscreen and rotation. ALAC uses bundled decoders pinned by
  checksum. The app has its own version, 0.1.0, and is built from source.

Fixed

• In tmux with Kitty graphics, video no longer flashes the terminal cursor at the
  top left while its pane has focus. tmux shows its outer cursor after every
  passthrough and, for the focused pane, synchronizes only commands that move
  the cursor. Each upload batch now starts by erasing and redrawing the pane's
  top-left cell, so tmux hides that reset inside its own synchronized update.
  Ghostty 1.4 draws as soon as output arrives, which made the reset visible on
  every frame. Covers and direct transmission over SSH can still show it briefly.
• Local tmux Kitty video keeps one terminal image and replaces its pixels for
  each frame instead of alternating between two images. The placeholder cells
  no longer change between frames, so Ghostty 1.4 no longer shows rows split
  between two frames. In a 101×30 fullscreen pane, each frame now writes about
  840 bytes instead of about 14 KB.

Upgrade notes

• Protocol remains 14, database version 9, and archive format 2.
• The video fixes are in the terminal client. They take effect when a TUI
  reattaches with the new binary; the server does not need a restart.
• The Android app is built separately from android/; see
  android/README.md. Like the iPhone app, it is not a
  release asset.

Install

brew install rath/tap/vtamp
# Existing installations:
brew update && brew upgrade vtamp

The video fixes take effect when you reattach a terminal client with the new
binary; the running server does not need a restart.

Or download the archive for your platform below. Verify it against SHA256SUMS
with shasum -a 256 -c --ignore-missing SHA256SUMS on macOS or
sha256sum --check --ignore-missing SHA256SUMS on Linux.

Both archives include the host binary, documentation, themes, Hello Panel,
and a prebuilt Pastel Transcript plugin. Examples are opt-in and are not
registered automatically. Python 3 is required only for Hello Panel.
The iPhone and Android apps are built from source; see
ios/README.md and
android/README.md.

Full changelog: v0.5.2...v0.5.3

v0.5.2 — Import controls and video fixes

YouTube excerpts keep audio and video in sync, and the iPhone Import screen
adds a video choice and paginated history. Terminal video uses less copying,
and live radio gains a spectrum on macOS 27.

Added

• The TUI spectrum works for live radio when the server runs macOS 27 or newer.
  An MTAudioProcessingTap on the mix of the native player item copies the
  decoded station audio into the same analysis as files, before volume; the
  sound is unchanged. Older systems cannot tap HTTP Live Streaming audio, so the
  panel names the requirement instead of an unexplained empty graph.
• Spectrum frames may carry an unavailable reason. The field is additive
  within protocol 14.
• imports_page provides cursor-based import history with a separate snapshot
  of all active jobs. The HTTP server advertises imports_pagination; the
  iPhone app loads 20 entries at a time and supports older protocol-14 servers.
• The iPhone Import screen offers Save video (up to 480p) for individual
  videos, excerpts, and playlists. The choice defaults to off and resets after
  a successful submission; failed submissions preserve the draft.

Changed

• The Import URL field uses a neutral placeholder and the standard iOS paste
  menu, with no separate Paste button.
• Kitty file transport reuses RGB frame buffers and writes RGB files directly,
  avoiding an RGBA conversion and reducing temporary frame-file size.

Fixed

• Video excerpts now encode the requested interval to H.264 with a zero-based
  clock, keeping the picture aligned with the audio instead of retaining
  keyframe preroll. Full-video imports still preserve the source codec.
• Explicitly re-importing an older excerpt with video repairs its timing and
  stale audio chapters while preserving track IDs, metadata overrides, and Queue
  entries. Failed repairs leave the existing media available.
• Returning to iPhone video playback holds the last picture while decoding
  catches up to the audio, preventing a burst of old frames and preserving
  full-screen orientation.

Upgrade notes

• Protocol remains 14, database version 9, and archive format 2.
  The API additions are backward compatible; no database migration is needed
  when upgrading from v0.5.1.
• Restart the server with the new binary when convenient to enable cursor
  paging, corrected excerpt imports, and the radio spectrum, then reattach TUIs.
  Installing a new binary does not replace a running server.
• Accurate video excerpts require FFmpeg with libx264. Existing excerpts are
  repaired only by an explicit re-import with video, never at startup.
• Radio spectrum requires macOS 27 or newer. Linux remains headless-only, with
  ARM64 release builds tested on Ubuntu 24.04 (glibc 2.39+).
• The iPhone app is built separately from ios/ and is not a release asset.

Install

brew install rath/tap/vtamp
# Existing installations:
brew update && brew upgrade vtamp

Restart the server when convenient to use the new server features (vtamp server stop, then start it again with your usual options), and reattach terminal
clients. Upgrading does not replace the running process.

Or download the archive for your platform below. Verify it against SHA256SUMS
with shasum -a 256 -c --ignore-missing SHA256SUMS on macOS or
sha256sum --check --ignore-missing SHA256SUMS on Linux.

Both archives include the host binary, documentation, themes, Hello Panel,
and a prebuilt Pastel Transcript plugin. Examples are opt-in and are not
registered automatically. Python 3 is required only for Hello Panel.
The iPhone app is built from source; see
ios/README.md.

Full changelog: v0.5.1...v0.5.2

v0.5.1 — HTTP API and iPhone app

A server can serve its Library to apps over HTTP, and an iPhone app in ios/
plays that Library, its saved videos, and radio on the phone. YouTube imports
take time ranges, and the Library filters by kind.

Added

• server start --api ADDR serves a JSON API for apps over plain HTTP:
  POST /api/rpc takes the local socket's request JSON, GET /api/server
  describes the server, and /api/library/ID/audio and /cover return a
  Library track's files with range requests and validators. Commands that name
  server paths, shutdown, and subscriptions stay on the local socket. There is
  no TLS or authentication; bind a private address such as a Tailscale one.
• /api/library/ID/video serves a track's saved silent video sidecar as the
  Matroska file it is, with the same range requests and validators, so apps can
  show the picture without the server re-encoding anything.
• server start --api tailscale detects the local Tailscale IPv4 address via
  tailscale ip -4 and serves the app API on port 8700. Failed lookups prevent
  startup; explicit --api IP:PORT addresses remain supported.
• An iPhone app in ios/ for that API: it browses and searches the Library,
  shows the server's Queue, starts YouTube imports with optional time ranges,
  and plays Library files on the phone with its own queue, background audio,
  shuffle and repeat, and lock-screen controls. Radio channels play from their
  registered URLs with the server's reconnect rules. Its home-screen icon sets
  the V-meter's bars on dark gray. Built with Xcode and XcodeGen; installed
  with your own Apple ID.
• The iPhone app shows a track's saved video in the player, in step with the
  audio: it demuxes the server's Matroska sidecar itself and hands the stored
  AV1, H.264, or HEVC samples to the phone's decoder, so nothing is re-encoded.
  A Cover / Video button keeps the choice, and the picture opens over the
  whole screen in landscape. VP9 sidecars decode in software with libvpx when
  the app is built with it.
• YouTube time ranges: single-video imports take Start/End fields in the TUI
  download options and library add --start/--end in the CLI (whole seconds,
  M:SS, or H:MM:SS). Excerpts and full downloads coexist as separate tracks,
  Library, Queue, and import history show the range, and retries, video
  upgrades, deletion, and archives keep it.
• Range downloads copy video packets without re-encoding, so the source codec
  is kept and boundaries fall on nearby source keyframes rather than exact
  frames. Imports show FFmpeg's progress while copying: media time copied,
  percentage, processing speed, and estimated time remaining.
• A Library kind filter: f cycles all → video → radio in the TUI, shown in
  the panel title and cleared with the search by Esc; A queues only the
  kinds the view shows. The CLI takes library list --kind and
  library search --kind with audio, video, or radio.
• Tracks carry video: true when their saved video sidecar exists, and Library
  and Queue rows show a · VIDEO suffix like the existing · LIVE. Scans,
  video publication, and archive restores keep the flag current.

Changed

• Protocol 14 and database version 9: the catalog stores a kind column,
  backfilled from existing sidecars in the catalog and the saved queue, and
  imports are identified by video ID plus normalized range instead of video ID
  alone. Track IDs, metadata, queue, and sessions are preserved. server_info
  reports the HTTP API's api_url.
• Archives are written as format 2, which carries source ranges. Format 1
  archives still restore.
• Video fullscreen continues into the next track when it also has a saved
  video, including natural endings where the video stops just before its audio.

Fixed

• On Linux, server start with --cast, --cast-http, or --api but without
  --headless started the server and then failed with a mode conflict. These
  options now start a headless server there, as server start alone does.
• Opening the selected track's YouTube link names that track when it has no
  source link, and asks for a selection in the Library or Queue when nothing is
  selected.

Upgrade notes

• Protocol is now 14, the database version 9, and the archive format
  2. Stop the running server with its current binary (vtamp server stop)
  before upgrading, then start the new binary and reattach TUIs; the new server
  migrates the database when it starts. Older binaries cannot open the migrated
  database or restore format 2 archives. Update both ends of a relay or a
  headless setup together.
• The HTTP API is off unless the server starts with --api. It has no TLS or
  authentication; bind it only to a private address such as a Tailscale one.
• The iPhone app is not a release asset: build it from ios/ with Xcode and
  XcodeGen and install it with your own Apple ID (ios/README.md).
• Prebuilt downloads cover Apple Silicon macOS and ARM64 Linux tested on
  Ubuntu 24.04 (glibc 2.39+). Linux remains a headless server without device
  playback, relay, media keys, radio, or terminal video.

Install

brew install rath/tap/vtamp
# Existing installations: stop the running server with the old binary first.
vtamp server stop
brew update && brew upgrade vtamp

Or download the archive for your platform below. Verify it against SHA256SUMS
with shasum -a 256 -c --ignore-missing SHA256SUMS on macOS or
sha256sum --check --ignore-missing SHA256SUMS on Linux.

Both archives include the host binary, documentation, themes, Hello Panel,
and a prebuilt Pastel Transcript plugin. Examples are opt-in and are not
registered automatically. Python 3 is required only for Hello Panel.
The iPhone app is built from source; see ios/README.md.

Full changelog: v0.5.0...v0.5.1

v0.5.0 — Client plugins and new spectrum styles

Client plugins let local programs extend vtamp with document panels and actions.
This release also adds four spectrum styles and logarithmic frequency labels.

Added

• Optional client plugins: register local programs, open their document/list
  panels with :, and run the same API from plugin run --json. The host owns
  themes, scrolling, timed highlights, cancellation, and bounded process I/O.
• A minimal Hello Panel Python example and plugin authoring walkthrough, with
  offline text/actions and a supported-video guide for the transcript example.
• A separately built Pastel Transcript example, adapted with credit from
  pastel-sketchbook's d4d0be3, keeps provider-specific fetch/parse/caption logic
  outside the default application.
• Four spectrum styles: squares, smooth, trail, and stereo, following the existing
  ten in the V cycle. Each has its own renderer and uses the current theme.
  Trail retains the six latest frame tops while paused; stereo labels L/R and
  falls back to combined bars on older servers or in small panes.
• Optional stereo channel data alongside the unchanged combined spectrum in
  protocol 11. Existing clients and servers remain compatible; restart the server
  with the new binary to enable the channel data, and reattach for new styles.
• Logarithmic frequency labels on horizontal spectrum graphs, positioned against
  their rendered bands and omitted when crowded; radial retains LOW / HIGH.
• Adapted from Pastel Sketchbook's spectrum contribution,
  preserving combined-channel analysis and correcting trail layering, fading,
  channel orientation, partial blocks, and narrow-pane band coverage.

Upgrade notes

• Protocol remains 11, database version remains 7, and the new client
  plugin API is 1. Reattach with the new binary to use plugins and spectrum
  styles; no playback-server restart is needed for plugins. Restart the server
  when convenient to enable stereo spectrum channel data.
• Release archives and Homebrew include the Hello Panel Python example and a
  prebuilt Pastel Transcript plugin. Plugins remain opt-in; see the
  plugin guide for registration and authoring instructions.
• Prebuilt downloads cover Apple Silicon macOS and ARM64 Linux tested on
  Ubuntu 24.04 (glibc 2.39+). Linux remains a headless server without device
  playback, relay, media keys, radio, or terminal video.

Install

brew install rath/tap/vtamp
# Existing installations:
brew update && brew upgrade vtamp

Or download the archive for your platform below. Verify it against SHA256SUMS
with shasum -a 256 -c --ignore-missing SHA256SUMS on macOS or
sha256sum --check --ignore-missing SHA256SUMS on Linux.

Both archives include the host binary, documentation, themes, Hello Panel,
and a prebuilt Pastel Transcript plugin. Examples are opt-in and are not
registered automatically. Python 3 is required only for Hello Panel.
See the packaged-example guide.

Full changelog: v0.4.3...v0.5.0

vtamp v0.4.3

Video playback in local Ghostty + tmux avoids bulk terminal uploads and stays
responsive through repeated pane swaps. Video preparation no longer flashes a
thumbnail while the next frame is loading.

Changed

• Local tmux Kitty video uses temporary-file transmission by default, preserving
  resolution while sending only short path and placement commands through the
  terminal. The worker bounds and cleans up pending files, including transfers
  discarded while a pane is hidden. Repeated debug and release swap tests no
  longer reproduced the sustained 1 fps slowdown in the tested environment.
• Automatic graphics selection inside tmux prefers Kitty, then native Sixel,
  then halfblocks. Clients started in parked windows retry detection when the
  window and pane become active, without requiring a new attachment.
• Pending or resized video leaves its picture area blank, including fullscreen,
  instead of briefly uploading cover art or displaying loading text. Missing,
  failed, or ended video and explicit cover mode still show the cover.

Fixed

• Video and spectrum no longer depend on an outer synchronized-update hold being
  released by a later tmux redraw. Graphics uploads precede text and caret drawing;
  tmux owns synchronization for its Kitty attachments.
• Batched Kitty commands and separated graphics uploads reduce cursor flicker
  and repeated outer-cursor resets during playback.
• Retired temporary files left by hidden-pane swaps no longer exhaust the file
  queue and stop subsequent video frames.

Added

• Optional VTAMP_TUI_TRACE timing logs for UI wakes, graphics writes, and video
  delivery. Logging runs on a separate thread and excludes key contents and
  media metadata.

Upgrade notes

• Protocol remains 11 and database version remains 7. Upgrading from
  v0.4.2 requires no migration or playback-server restart for these TUI changes;
  upgrade the binary and reattach the TUI. Existing audio can keep playing.
• SSH environments retain direct video transmission. Use
  VTAMP_KITTY_VIDEO_FILE=0 to force direct transfer, or 1 when the terminal
  and TUI share a filesystem. The validated default is local Ghostty + tmux;
  direct cover display can still briefly stall on a large upload.
• Prebuilt downloads cover Apple Silicon macOS and ARM64 Linux tested on
  Ubuntu 24.04 (glibc 2.39+). Linux remains a headless server without terminal
  video, device playback, relay, media keys, or radio.

Install

Apple Silicon macOS:

brew install rath/tap/vtamp

Existing v0.4.2 users can run brew update && brew upgrade vtamp and reattach
without restarting playback. For older versions, follow the protocol upgrade
notes in the changelog.

ARM64 Linux (Ubuntu 24.04 or newer, glibc 2.39+):

curl -LO https://github.com/rath/vtamp/releases/download/v0.4.3/vtamp-aarch64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/rath/vtamp/releases/download/v0.4.3/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf vtamp-aarch64-unknown-linux-gnu.tar.gz
install -D -m 755 vtamp-aarch64-unknown-linux-gnu/vtamp ~/.local/bin/vtamp

Or build from source with Rust 1.90+, a C compiler, and cmake:

git clone --branch v0.4.3 https://github.com/rath/vtamp.git
cd vtamp
cargo install --locked --path .

Assets

File	Contents
vtamp-aarch64-apple-darwin.tar.gz	Ad-hoc signed Apple Silicon macOS binary, license, documentation, and Pastel themes
vtamp-aarch64-unknown-linux-gnu.tar.gz	ARM64 Linux headless binary, license, documentation, and Pastel themes
SHA256SUMS	SHA-256 checksums of both archives

Homebrew verifies its download automatically. On macOS, verify archives with
shasum -a 256 -c --ignore-missing SHA256SUMS.

Full changelog: v0.4.2...v0.4.3

vtamp v0.4.2

Changes since v0.4.1. Custom JSON themes join the existing palettes, file
playback gains automatic loudness normalization, and import retries keep their
source titles.

Added

• Automatic per-file loudness normalization to −18 LUFS, with true-peak headroom
  and bounded amplification. Background measurements are cached without modifying
  music; playback never waits and new results apply on the next playback.
• normalize [on|off] reads or saves the server preference, analysis progress and
  current gain. Device playback and casts share the correction; relays do not
  apply it twice. Radio remains unchanged. Protocol 11 and database 7 preserve
  existing Library identities, queues, and session settings.
• Custom JSON palettes in the client data directory's themes/ folder, with
  the existing t preview/save/cancel controls and --theme overrides. New
  themes need no code changes or rebuild; reattach after editing files.
• vtamp theme install FILE... [--replace] validates and installs palettes
  without changing the saved default or starting the server. Invalid files
  produce diagnostics while other choices remain available.
• Sixteen optional Pastel examples in themes/pastel/, preserving the names
  and colors from pastel-sketchbook's contribution.
  Install them with vtamp theme install themes/pastel/*.json from a checkout
  or extracted release archive. Homebrew installs the examples under its
  package share directory. They are not enabled automatically.

Fixed

• Retried YouTube imports preserve their source titles instead of becoming
  YouTube import. Startup repairs historical placeholder titles using
  retained source/history data or the URL while preserving other job data.

Upgrade notes

• Protocol is 11 and database version is 7. Upgrading from v0.4.1
  transactionally adds loudness storage while preserving Library identities,
  Queue, and session settings. Clients and servers must use the same protocol.
• Before replacing an older protocol-10 binary, stop its server with that
  matching installed binary: vtamp server stop. Then run
  brew update && brew upgrade vtamp and attach again. The saved session is
  restored paused; installing a binary never replaces a running server.
• Custom themes are client-local. Once client/server protocols match, selecting
  or editing a theme only needs a new attachment, not a server restart.
  Older clients cannot resolve a saved custom theme ID.
• Prebuilt downloads cover Apple Silicon macOS and ARM64 Linux tested on
  Ubuntu 24.04 (glibc 2.39+). Intel Macs and other Linux architectures build
  from source. Release archives include theme documentation and Pastel examples.

Install

Apple Silicon macOS:

brew install rath/tap/vtamp

Existing users: follow the upgrade notes above before running
brew update && brew upgrade vtamp.

Install the optional Pastel examples from a Homebrew installation:

vtamp theme install "$(brew --prefix vtamp)/share/vtamp/themes/pastel/"*.json
vtamp --theme pastel-default

ARM64 Linux (Ubuntu 24.04 or newer, glibc 2.39+):

curl -LO https://github.com/rath/vtamp/releases/download/v0.4.2/vtamp-aarch64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/rath/vtamp/releases/download/v0.4.2/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf vtamp-aarch64-unknown-linux-gnu.tar.gz
install -D -m 755 vtamp-aarch64-unknown-linux-gnu/vtamp ~/.local/bin/vtamp

Or build from source with Rust 1.90+, a C compiler, and cmake:

git clone --branch v0.4.2 https://github.com/rath/vtamp.git
cd vtamp
cargo install --locked --path .

Assets

File	Contents
vtamp-aarch64-apple-darwin.tar.gz	Ad-hoc signed Apple Silicon macOS binary, license, documentation, and Pastel examples
vtamp-aarch64-unknown-linux-gnu.tar.gz	ARM64 Linux headless binary, license, documentation, and Pastel examples
SHA256SUMS	SHA-256 checksums of both archives

Homebrew verifies its download automatically. On macOS, verify archives with
shasum -a 256 -c --ignore-missing SHA256SUMS.

Full changelog: v0.4.1...v0.4.2

vtamp 0.4.1

Changes since v0.4.0. The Library exports to a portable archive of playable
media and restores from it, and the spectrum gains four styles.

Added

• vtamp library export writes a portable Library tarball: local audio and
  YouTube downloads with current tags and covers embedded, and video with sound.
  Media files sit at the archive root with readable artist/title names and their
  source modification times, and play directly after normal extraction; radio
  registrations and source metadata are kept in the manifest.
• library import, --dry-run, and library archive-status validate and merge
  archives while keeping existing tracks, Queue and playback intact. Interrupted
  publication is recovered on startup. Export, restore, and dry-run report
  stages, item counts, and byte progress on stderr, and library archive-status
  includes restore progress.
• Spectrum styles radial, fire, ridge, and sparks, after waterfall
  in the V cycle. Radial draws petals around a ring of braille dots, bass on
  the left and treble on the right, and sudden rises across the spectrum swell
  a glowing core and send waves outward; fire feeds flames on half-block
  pixels from the band levels; ridge stacks recent frames as lines in which
  nearer lines hide farther ones, and freezes while paused like the waterfall;
  sparks throws braille sparks from the bars when a band jumps. All four use
  the active theme's colors and stop animating once the audio stops.

Changed

• Deleting a managed YouTube download (d in Library or vtamp library delete)
  also removes its queued copies and play-next reservations and stops it if it
  is playing, instead of refusing tracks in Queue or playback.

Fixed

• Live radio with the spectrum shown no longer keeps the TUI redrawing 20 times
  a second; the panel's unavailable notice now lets the animation timer sleep.

Upgrade notes

• Protocol is 10; database version remains 6, so upgrading from v0.4.0
  needs no database migration. Protocol 10 adds the archive restoration
  commands. Clients and servers must use the same protocol.
• Before upgrading v0.4.0, stop its server with the matching installed binary:
  vtamp server stop. Then run brew update && brew upgrade vtamp (or replace
  the binary) and start vtamp again. The saved session is restored paused.
  Installing or rebuilding does not replace a running server.
• An older client reports invalid settings while ui.json names one of the new
  spectrum styles; saving a theme with t in that client repairs the file.
• Prebuilt downloads cover Apple Silicon macOS and ARM64 Linux with glibc 2.39+
  (tested on Ubuntu 24.04). Intel Macs and other Linux architectures build from source.

Install

Apple Silicon macOS:

brew install rath/tap/vtamp

For existing v0.4.0 installs, stop the old server before upgrading:

vtamp server stop
brew update && brew upgrade vtamp
vtamp

ARM64 Linux (Ubuntu 24.04 or newer, glibc 2.39+):

curl -LO https://github.com/rath/vtamp/releases/download/v0.4.1/vtamp-aarch64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/rath/vtamp/releases/download/v0.4.1/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf vtamp-aarch64-unknown-linux-gnu.tar.gz
install -D -m 755 vtamp-aarch64-unknown-linux-gnu/vtamp ~/.local/bin/vtamp

Or build from source with Rust 1.90+, a C compiler, and cmake:

git clone --branch v0.4.1 https://github.com/rath/vtamp.git
cd vtamp
cargo install --locked --path .

Assets

File	Contents
vtamp-aarch64-apple-darwin.tar.gz	Ad-hoc signed Apple Silicon macOS binary, LICENSE, README, and changelog
vtamp-aarch64-unknown-linux-gnu.tar.gz	ARM64 Linux headless server, LICENSE, README, and changelog
SHA256SUMS	SHA-256 checksums of both archives

On macOS, verify the downloaded archive with shasum -a 256 -c --ignore-missing SHA256SUMS. Homebrew verifies its download automatically.

Full changelog: v0.4.0...v0.4.1

vtamp 0.4.0

Changes since v0.3.0. Optional YouTube video now plays inside the terminal, with
pane-local fullscreen, lower graphics overhead, and stable seeking and input.

Added

• Optional YouTube video downloads up to 480p. The TUI asks for Audio only or
  Audio + video for each import; the CLI accepts library add URL --video.
  Existing audio imports can gain video without changing track identity or
  Queue. Failed or cancelled video downloads preserve successfully imported audio.
• Terminal video playback on macOS with installed FFmpeg/FFprobe and Kitty or
  Sixel graphics. Video follows the server's audio; w toggles video/cover,
  and F fills the current terminal pane with elapsed / total time below.
  F or Esc returns. Audio keeps playing when the TUI detaches.
• Video defaults to 15 fps; VTAMP_VIDEO_FPS=8 reduces terminal CPU usage.
  Kitty uploads use capability-detected compression and terminal-side scaling,
  including fullscreen. Frame buffers and image IDs remain bounded.
• Spectrum styles. V switches the visible spectrum between bars, gradient,
  mono, mirror, dots, and waterfall; the status row names the new style
  and ui.json remembers it as spectrum_style (older files default to bars).
  Every style uses the active theme's colors. The waterfall scrolls one row per
  analysis frame, freezes while paused, and resets on a track change.
• Deleting managed YouTube downloads: d in Library opens a confirmation, and
  vtamp library delete TRACK_ID removes the audio, video, cover, source metadata,
  and catalog entry. Local originals and tracks in Queue or playback are refused.

Fixed

• Pasted YouTube playlist URLs open the playlist preview instead of importing
  only the selected video.
• Idle or paused spectrum streams stay connected without repeated reconnects.
• Video fullscreen exits cleanly on track transitions, and seeks retain the
  last displayed frame until the target is ready instead of flashing the cover.
• Text input cursors stay at the field during video redraws, including Kitty
  passthrough through tmux to Ghostty.
• Relay mode spectrum frames now carry the remote's current_id, so an attached
  TUI shows the spectrum of the audio the relay plays instead of dropping every
  frame.

Upgrade notes

• Protocol is 9; database version remains 6, so upgrading from v0.3.0
  needs no database migration. Clients and servers must use the same protocol.
• Before upgrading v0.3.0, stop its server with the matching installed binary:
  vtamp server stop. Then run brew update && brew upgrade vtamp (or replace
  the binary) and start vtamp again. The saved session is restored paused.
  Installing or rebuilding does not replace a running server.
• Video is optional and requires installed yt-dlp, FFmpeg, and FFprobe for
  imports; tools are detected at runtime and are not installed automatically.
  Playback is local to the macOS TUI. Linux remains a headless server without
  device playback, relay, media keys, radio, or terminal video.
• Prebuilt downloads cover Apple Silicon macOS and ARM64 Linux with glibc 2.39+
  (tested on Ubuntu 24.04). Intel Macs and other Linux architectures build from source.

Install

Apple Silicon macOS:

brew install rath/tap/vtamp

For existing v0.3.0 installs, stop the old server before upgrading:

vtamp server stop
brew update && brew upgrade vtamp
vtamp

ARM64 Linux (Ubuntu 24.04 or newer, glibc 2.39+):

curl -LO https://github.com/rath/vtamp/releases/download/v0.4.0/vtamp-aarch64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/rath/vtamp/releases/download/v0.4.0/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf vtamp-aarch64-unknown-linux-gnu.tar.gz
install -D -m 755 vtamp-aarch64-unknown-linux-gnu/vtamp ~/.local/bin/vtamp

Or build from source with Rust 1.90+, a C compiler, and cmake:

git clone --branch v0.4.0 https://github.com/rath/vtamp.git
cd vtamp
cargo install --locked --path .

Assets

File	Contents
vtamp-aarch64-apple-darwin.tar.gz	Ad-hoc signed Apple Silicon macOS binary, LICENSE, README, and changelog
vtamp-aarch64-unknown-linux-gnu.tar.gz	ARM64 Linux headless server, LICENSE, README, and changelog
SHA256SUMS	SHA-256 checksums of both archives

On macOS, verify the downloaded archive with shasum -a 256 -c --ignore-missing SHA256SUMS. Homebrew verifies its download automatically.

Full changelog: v0.3.0...v0.4.0

vtamp 0.3.0

vtamp 0.3.0 makes the TUI queue easier to build, search, and navigate, with fixes for live-radio media keys and slow LLM CLI startup. Changes below are relative to v0.2.0.

Added

• / searches the focused list: title, artist, and album in Library, or the
  entries already in Queue. Queue filtering is instant; Library search follows
  typing after a 150 ms debounce. Enter keeps the draft, and Esc restores the
  previous filter and Library page. A filtered queue retains original positions
  and disables J/K reordering.
• A in Library appends every matching track across all result pages in one
  atomic edit, up to the 10,000-entry queue limit. It skips tracks already in
  Queue, reports added and skipped counts, and preserves playback, shuffle, and
  navigation. Repeating A does not add another copy; e still allows duplicates.
• X in Queue opens a confirmation with the current entry count before emptying
  it. Enter confirms and Esc cancels. Clearing stops queued playback; a direct
  track playing outside Queue continues.
• zz selects the now-playing queue entry from either panel and centers it when
  the list ends leave room. It clears a queue filter that hides the entry.
• > and < are next/previous shortcuts alongside n and b.

Changed

• Library and Queue appear side by side from 90 columns, down from 100, in panes
  with at least 28 rows. The compact player layout remains unchanged.
• Search, folder, and radio channel-name prompts are centered over the browser
  area and sized to their labels, keeping the player visible.
• Queue-all notices suggest only remaining actions: shuffle when it is off, play
  while stopped, or resume while paused.
• Live radio's cover slot reads Live stream instead of No album art.

Fixed

• macOS media keys can skip a live station while it is still connecting. Now
  Playing publishes the selected station before its first audio frame; local
  files still wait for audio output.
• Optional Codex and Claude CLI providers allow 15 seconds, up from 5, for each
  --help or --version probe. Slow first launches no longer trigger an early
  built-in-rules fallback. The model request deadline remains 60 seconds.

Upgrading from 0.2.0

• Protocol remains 7 and database version remains 6; upgrading from
  v0.2.0 requires no database migration.
• Upgrade Homebrew with brew update && brew upgrade vtamp, then reattach the
  TUI to use the new interface. To pick up server-side media-key and LLM fixes,
  run vtamp server stop when convenient, then start vtamp again. Installation
  never replaces a running server; a restart restores the session paused.
• Prebuilt downloads cover Apple Silicon macOS and ARM64 Linux with glibc 2.39+
  (tested on Ubuntu 24.04). Linux remains a headless server only, without device
  playback, relay, media keys, or radio. Intel Macs and other Linux architectures
  build from source.

Install

On Apple Silicon macOS:

brew install rath/tap/vtamp
# Existing installs:
brew update && brew upgrade vtamp

On ARM64 Linux with glibc 2.39 or newer (Ubuntu 24.04 or later):

curl -LO https://github.com/rath/vtamp/releases/download/v0.3.0/vtamp-aarch64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/rath/vtamp/releases/download/v0.3.0/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf vtamp-aarch64-unknown-linux-gnu.tar.gz
install -D -m 755 vtamp-aarch64-unknown-linux-gnu/vtamp ~/.local/bin/vtamp

Or build from source with Rust 1.90+, a C compiler, and cmake:

git clone --branch v0.3.0 https://github.com/rath/vtamp.git
cd vtamp
cargo install --locked --path .

Assets

File	Contents
vtamp-aarch64-apple-darwin.tar.gz	Ad-hoc signed Apple Silicon macOS binary, LICENSE, README, and changelog
vtamp-aarch64-unknown-linux-gnu.tar.gz	ARM64 Linux headless server (glibc 2.39+), LICENSE, README, and changelog
SHA256SUMS	SHA-256 checksums of both archives

To verify a macOS download, run shasum -a 256 -c --ignore-missing SHA256SUMS beside the archive. Homebrew verifies its download automatically. If a browser download is quarantined, extract it and run xattr -d com.apple.quarantine vtamp on the binary before the first launch.

Full changelog: v0.2.0...v0.3.0

vtamp 0.2.0

vtamp 0.2.0 lets a playback server run somewhere else: a headless server casts what it plays as Ogg Opus, a Mac can relay that server through its own speakers, and Linux ships as a headless server for the first time.

Install

On an Apple Silicon Mac:

brew install rath/tap/vtamp     # or: brew update && brew upgrade vtamp
vtamp server stop               # the next vtamp starts the new build

On 64-bit ARM Linux with glibc 2.39 or newer (Ubuntu 24.04 or later), download the headless server build:

curl -LO https://github.com/rath/vtamp/releases/download/v0.2.0/vtamp-aarch64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/rath/vtamp/releases/download/v0.2.0/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf vtamp-aarch64-unknown-linux-gnu.tar.gz
install -D -m 755 vtamp-aarch64-unknown-linux-gnu/vtamp ~/.local/bin/vtamp

Or build from source with Rust 1.90 or newer, a C compiler, and cmake (new in this release, for the bundled libopus):

git clone --branch v0.2.0 https://github.com/rath/vtamp.git
cd vtamp
cargo install --locked --path .

What is new in 0.2.0

• Headless server. vtamp server start --headless runs without an audio device and casts what it plays as Ogg Opus (48 kHz stereo, 128 kbit/s). The queue, library, and CLI work as before; vtamp cast listen | mpv - plays the cast on the same machine or over SSH, and vtamp cast status describes it.
• Relay. vtamp server start --remote SOCKET forwards every command to a remote server and plays its cast through the local audio device. The TUI and the CLI attach to the local socket as usual, media keys keep working, and vtamp server stop stops only the relay.
• Device casts. vtamp server start --cast casts the audio a device server plays, taken before the volume setting. --cast-http ADDR serves the cast over plain HTTP on a token path for mpv, VLC, ffmpeg, and Firefox; TLS and further authentication belong to a reverse proxy.
• Linux headless servers. The Linux build has no audio device backend, so every server it starts is headless; AAC decodes in software there. It needs no ALSA. Tested on Ubuntu 24.04 (aarch64) and covered by CI.
• Protocol 7. New cast_watch, cast_info, and server_info commands; doctor reports the server mode and the cast. The database stays at version 6, so no migration runs.

Upgrading from 0.1.0

• A running 0.1.0 server keeps running after the install. Run vtamp server stop, then the next vtamp starts 0.2.0. Protocol 7 clients need a protocol 7 server.
• Source builds now need cmake. The Homebrew formula installs the prebuilt binary and needs nothing new.
• Casts carry full-scale audio; the volume setting applies to the listening device, not to the stream.

Platform

macOS on Apple Silicon is the supported platform for playback. Linux is a headless server only: no device playback, relay, media keys, or radio. Intel Macs and other Linux architectures build from source. Named playlists, EQ, crossfade, gapless playback, and login-time startup are not implemented.

Assets

File	Contents
vtamp-aarch64-apple-darwin.tar.gz	vtamp binary for macOS on Apple Silicon, LICENSE, README.md
vtamp-aarch64-unknown-linux-gnu.tar.gz	vtamp headless server for 64-bit ARM Linux (glibc 2.39+), LICENSE, README.md
SHA256SUMS	Checksums of both archives

Verify a download with shasum -a 256 -c SHA256SUMS on macOS or sha256sum --check --ignore-missing SHA256SUMS on Linux. The macOS binary is ad-hoc signed. Homebrew downloads carry no quarantine flag; if you download the archive with a browser instead, clear it before the first run:

xattr -d com.apple.quarantine vtamp