💿 rpmdeck

PUI — Pickup User Interface A terminal music player with a spinning ASCII vinyl record. Zero dependencies.

╔══════════════════════════════════════════════════════════════════════════════╗
║           💿  r p m d e c k   PUI — Pickup User Interface             ║
╠═════════════════════════════════════╦══════════════════════════════════════╣
║           ███████████               ║  ▶  NOW PLAYING                      ║
║       ██▓▓▒░▒▒▒░▒▒▒░▒▓▓██           ║  ─────────────────────────────────  ║
║     █▓▓▒▒░▒▒▒▒▒░▒▒▒░▒▒▒▒▓▓█         ║  ♪  Bohemian Rhapsody              ║
║   █▓░▒▒▒▒▒░▒▒▒▒░▒▒▒▒▒▒▒▒▒▒░▓█       ║  ◎  Queen                          ║
║  █▓▒▒▒▒▒▒▒▒░▒▒▒▒░▒▒▒░▒▒▒▒▒▒▒▓█      ║  ◈  A Night at the Opera           ║
║ █▓▒▒▒▒▒▒▒▒░▒▒▒▒░▒▒▒░▒▒▒▒▒▒▒░▒▓█     ║                                    ║
║█▓░░░░▒▒▒░░▒░▒◉◉◈◈◈▒░▒▒░▒▒▒▒▒▒░▓█    ║  ████████████░░░░░░░░░░░░░░        ║
║█▓▒▒▒▒▒▒▒▒▒▒◒◓◓◉◈◈◇◇◆▒▒▒▒▒▒▒▒▒▒▓█    ║  2:15 ─────────────────── 5:55    ║
║█▓░░░░░░░░░░◒◒◒○·○◉◉◉░░░░░░░░░░▓█    ║                                    ║
║█▓▒▒▒▒▒▒▒▒▒▒◑◐◐◆◆◇◈◈◉▒▒▒▒▒▒▒▒▒▒▓█    ║  🔊 ████████░░  80%                ║
║█▓░▒▒▒▒▒▒░▒▒░▒◆◆◆◇◇▒░▒░░▒▒▒░░░░▓█    ║                                    ║
║ █▓▒░▒▒▒▒▒▒▒░▒▒▒░▒▒▒▒░▒▒▒▒▒▒▒▒▓█     ║  Queue: [1/3]                      ║
╠═════════════════════════════════════╩══════════════════════════════════════╣
║     [SPACE] Play/Pause  ·  [←/→] Seek ±5s  ·  [↑/↓] Volume  ·  [Q] Quit  ║
╚══════════════════════════════════════════════════════════════════════════════╝

Features

• 🎵 Plays MP3, FLAC, OGG, AAC, WAV and more (via mpv)
• 💿 Spinning ASCII vinyl record animation (16 frames, 10 FPS)
• 📋 Reads ID3 metadata — artist, title, album
• 📊 Live progress bar + timestamps
• 🔊 In-player volume control
• 📁 Queue support — play entire folders
• ⌨️ Full keyboard control
• 🎨 Beautiful ANSI color UI with box-drawing
• 📦 Zero npm dependencies

Install

npm install -g rpmdeck

# or run without installing
npx rpmdeck song.mp3

Requirement

rpmdeck uses mpv as its audio backend.

# Ubuntu / Debian
sudo apt install mpv

# macOS (Homebrew)
brew install mpv

# Arch Linux
sudo pacman -S mpv

# Windows (Scoop)
scoop install mpv

Usage

# Single file
rpmdeck song.mp3

# Queue (plays in order)
rpmdeck track1.mp3 track2.flac track3.ogg

# Play all mp3s in a folder
rpmdeck ~/Music/*.mp3

# Help
rpmdeck --help

Controls

| Key | Action | |-----|--------| | Space | Play / Pause | | ← → | Seek ±5 seconds | | ↑ ↓ | Volume up / down | | N | Next track | | P | Previous track | | Q / Ctrl+C | Quit |

Why PUI?

TUI = Terminal User Interface. GUI = Graphical User Interface. PUI = Pickup User Interface — because the needle drops and the music plays.

How It Works

• The vinyl animation is generated mathematically — 16 frames computed by rendering concentric ring patterns with sinusoidal groove textures and a rotating label.
• Audio is handled via mpv's IPC socket (--input-ipc-server), giving full playback control without any native bindings.
• The TUI is rendered using raw ANSI escape codes and Unicode box-drawing characters — no curses, no deps.

License

MIT © 2026 Yahya Efe Kurucay