A keyboard-driven, Winamp-style classic MP3 player for your terminal. Point it at a folder, it indexes every audio file inside, and you build a playlist with a couple of keystrokes. No mouse needed.
╔══════════════════════════════════════════════════════════════════════════════╗
║ ♪♫ M I N P A W T U I ♫♪ LIB:128 PL:4 DIR:~/Music ║
╚══════════════════════════════════════════════════════════════════════════════╝
╭─ NOW PLAYING ────────────────────────────────────────────────────────────────╮
│ ♪ Aphex Twin — Avril 14th ⢀⠀⠀⢀⡀⠀⠀⠀⢀⠀⠀⠀ │
│ Drukqs · 23 - aphex_twin_-_avril_14th.mp3 ⣿⡀⢀⣿⣧⠀⢀⡀⣿⠀⢀⡀ │
│ [▶] 01:23 / 02:05 ████████░░░░░░ VOL ▮▮▮▮▮▮▮▮▯▯ 80% ⣿⣧⣸⣿⣿⣆⣸⣧⣿⣄⣼⣷ │
│ [Space] pause [S] stop [[ / ] ] seek [N]ext ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿ │
╰──────────────────────────────────────────────────────────────────────────────╯
┌─ LIBRARY (128) ─────────────────────────┐┌─ PLAYLIST (4) ──────────────────┐
│ Title Artist Time ││ # Title Artist Time │
│ Avril 14th Aphex Twin 02:05 ││ 1. Strobe Deadmau5 10:32 │
│ Strobe Deadmau5 10:32 ││ 2. Selected... Aphex Twin 04:42 │
│▸ Selected Ambient Aphex Twin 04:42 ││ ♪ 3. Avril 14th Aphex Twin 02:05 │
│ Sandstorm Darude 03:45 ││ 4. Sandstorm Darude 03:45 │
└──────────────────────────────────────────┘└──────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ [Space] Play/Pause [N/P] Next/Prev [↑↓] Move [Enter] Play/Add ... [?] │
└──────────────────────────────────────────────────────────────────────────────┘
minpawtui is built on OpenTUI, which uses Bun's FFI.
You will need Bun to run it.
# Install Bun (once)
curl -fsSL https://bun.sh/install | bash # macOS / Linux
# or: brew install oven-sh/bun/bun
# Install minpawtui globally
bun install -g minpawtui
# or with npm (the launcher will still invoke bun under the hood):
npm install -g minpawtui
You also need an audio backend on your PATH:
| Backend | Visualizer | Pause / Seek | Install |
|---|---|---|---|
| ffmpeg + ffplay | 🟢 real FFT | ✅ precise | brew install ffmpeg · apt install ffmpeg |
| mpv | synthetic | ✅ full | brew install mpv · apt install mpv |
| ffplay only | synthetic | ⚠️ restart | brew install ffmpeg |
| afplay | synthetic | ❌ basic | built into macOS |
minpawtui auto-detects in this order. Install ffmpeg for the full
experience — it decodes audio through minpawtui, so the spectrum
visualizer is a real-time FFT of what you're hearing (not a simulation),
and pause/seek/volume are sample-accurate. The other backends still play
fine but drive the visualizer with a synthetic model.
minpawtui # scan the current folder
minpawtui ~/Music # scan a specific folder
minpawtui --help
On startup it walks the folder recursively, reads ID3 / Vorbis / MP4 tags via
music-metadata, and shows
everything it found in the Library panel.
The whole app is keyboard-driven. Press ? at any time for the cheatsheet.
| Key | Action |
|---|---|
Space | Play / Pause toggle |
S | Stop |
N / → | Next track |
P / ← | Previous track |
[ / ] | Seek −5 s / +5 s |
{ / } | Seek −30 s / +30 s |
+ / = / - | Volume up / down |
M | Mute toggle |
R | Cycle repeat (off → all → one) |
Z | Toggle shuffle |
V | Toggle spectrum visualizer |
| Key | Action |
|---|---|
Tab · 1 · 2 | Switch focus between Library / Playlist |
↑ / ↓ · k / j | Move cursor |
PgUp / PgDn | Move by page |
Home / End · g | Jump to top / bottom |
Enter (Library) | Add track to playlist and play |
A (Library) | Add highlighted track to playlist |
Shift+A (Library) | Add all library tracks to playlist |
Enter (Playlist) | Play highlighted track |
D (Playlist) | Remove track from playlist |
C (Playlist) | Clear playlist |
| Key | Action |
|---|---|
? / F1 | Toggle help overlay |
Q / Ctrl+C | Quit |
mp3, m4a, m4b, aac, flac, ogg, oga, opus, wav, wma,
aiff, aif. Whatever your backend can decode plays; whatever
music-metadata recognises gets proper tags.
A fine Braille dot-matrix spectrum, tucked into the right side of the
NOW PLAYING panel next to the volume meter. Each terminal cell is a 2×4
grid of Braille dots, so a single dot is ~1/8 of a character — the smallest
"pixel" a terminal can draw. The display is 16×4 cells = a 32×16 dot
grid, one thin bar per dot-column, with a slowly-falling peak dot on each.
Cell rows are colored in the classic Winamp gradient (red on top → amber →
bright LCD green → dim green at the bottom).
With the ffmpeg backend the spectrum is genuine. ffmpeg decodes the track to raw PCM, minpawtui meters that PCM to the ffplay "DAC" at exactly real-time rate, and taps every sample on the way through into a ring buffer. The UI runs a 2048-point Hann-windowed radix-2 FFT over that buffer ~20×/sec, buckets the power spectrum into log-spaced frequency bands (40 Hz–16 kHz), and feeds the dB-scaled magnitudes straight to the dots. Low notes light the left bars, highs light the right — because it's measuring the actual signal.
The magnitudes are amplitude-normalized and mapped from a dB floor, so the bars have real dynamic range (they don't just peg to the top). The tap also sits before the volume scaling, so turning the volume down doesn't shrink the visualizer — exactly like a hardware analyzer.
On the fallback backends (mpv / ffplay-only / afplay) the audio never passes through our process, so there's nothing to analyze; the bars use a synthetic model instead (per-band oscillators + envelope + noise + bass-biased beat spikes). Either way, pause/stop decays them to silence.
Toggle with V. On narrow terminals (inner width under 58 columns) the
dot column auto-collapses so the volume meter has room to breathe.
┌──────────────────┐
│ OpenTUI (Bun) │ ← rendering, key input
└────────┬─────────┘
│
┌────────▼─────────┐ ┌──────────────────┐
│ Store + State │◀──│ scanner │
└────────┬─────────┘ │ (music-metadata)│
│ └──────────────────┘
┌────────▼─────────┐
│ Player │ ── ffmpeg-tap : ffmpeg ─PCM→ [tap → FFT] ─→ ffplay
│ abstraction │ ── mpv : JSON IPC over Unix socket
│ │ ── ffplay/afplay : process restart on seek
└──────────────────┘
EventEmitter — every change re-renders.FfmpegTapPlayer (preferred) spawns ffmpeg to decode the track to
raw f32 PCM and meters it to ffplay at real-time rate. Because we
are the clock, position is bytesOut / byteRate, pause is SIGSTOP
on both processes, and seek re-spawns ffmpeg with -ss. Every metered
chunk is tapped into the Analyzer for the
real-time FFT spectrum.MpvPlayer spawns mpv --idle --input-ipc-server=… and talks JSON
commands over the socket, observing time-pos / duration / pause.SpawnPlayer spawns ffplay / afplay per track and approximates
pause/seek by killing and re-spawning with -ss <offset>.bun install
bun run dev ~/Music # auto-restart on save
bun run typecheck
The whole thing is TypeScript and shipped as TypeScript — Bun runs it natively, no build step required.
MIT
FAQs
A keyboard-driven, Winamp-style classic MP3 player for your terminal.
The npm package minpawtui receives a total of 3 weekly downloads. As such, minpawtui popularity was classified as not popular.
We found that minpawtui demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Product
Socket Threat Intel now shows which malware campaigns were blocked or detected in your organization, with links to scans and Firewall events.
Security News
Fixes for eMudhra and Brotli are out. Getting them everywhere they’re needed means tracking down bundled libraries, runtimes, and certificate stores.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.