A terminal music player and podcast client with YouTube Music search, synced lyrics, podcast transcripts, and 8 color themes.
Built on OpenTUI (Zig native rendering + React 19) with mpv as the audio engine.
Music Search (Tokyo Night theme)
╭──────────────────────────────────────────────────────────────────────────────────╮
│ TuiTunes ♪ Music │ 🎙 Podcast Search music... │
╰──────────────────────────────────────────────────────────────────────────────────╯
╭──────────────╮╭─Results (20)──────────────────────────────────────────────────────╮
│ ♪ Music ││ 1 ▸ Let Down 5:00 │
│ ▸ / Search ││ Radiohead — OK Computer │
│ Q Queue ││ 2 Creep 3:59 │
│ ♥ Favorites││ Radiohead — Creep │
│ ⟲ History ││ 3 No Surprises 3:49 │
│ ││ Radiohead — OK Computer │
│ ││ 4 Everything In Its Right Place 4:12 │
│ ││ Radiohead — Kid A │
╰──────────────╯╰──────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────────╮
│ ▶ ▃▆▅▇▂ Let Down — Radiohead 🔀 🔁 🔊80% 1.25x 2:07 / 5:00 │
│ ━━━━━━━━━━━━━━━━━●─────────────────────── │
╰──────────────────────────────────────────────────────────────────────────────────╯
Podcast Section
╭──────────────────────────────────────────────────────────────────────────────────╮
│ TuiTunes ♪ Music │ 🎙 Podcast Search podcasts... │
╰──────────────────────────────────────────────────────────────────────────────────╯
╭──────────────╮╭─Podcasts──────────────────────────────────────────────────────────╮
│ 🎙 Podcasts ││ 1 ▸ Lex Fridman Podcast ✓ │
│ ▸ / Search ││ Lex Fridman │
│ 📋 My Feeds││ 2 Huberman Lab │
│ 📜 Episodes││ Scicomm Media │
│ ││ 3 All-In Podcast │
│ ││ All-In Podcast, LLC │
╰──────────────╯╰──────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────────╮
│ ⏹ ▁▁▁▁▁ No track 🔊80% 0:00 / 0:00 │
│ ──────────────────────────────────────── │
╰──────────────────────────────────────────────────────────────────────────────────╯
Music
- YouTube Music search via youtubei.js (no API key needed)
- Audio streaming via mpv + yt-dlp (audio-only, ~83MB RAM)
- Synced lyrics from LRCLIB with per-line highlighting
- Queue management, favorites, play history (SQLite)
- Shuffle, repeat (off/track/all), playback speed (0.5x-2x)
Podcasts
- Podcast discovery via iTunes Search API
- RSS feed parsing with subscription management
- YouTube-backed playback for perfectly synced transcripts
- Flowing transcript display with inline phrase highlighting
- Smart paragraph splitting using sentence-ending punctuation
Interface
- 6 layout presets: Default, Compact, Minimal, Split, Wide, Focus
- 8 color themes: Tokyo Night, Catppuccin, Dracula, Nord, Gruvbox, Solarized, Rose Pine, Kanagawa
- Command palette (Ctrl+P) with 35 fuzzy-searchable commands
- Full Unicode support (CJK, Vietnamese, emoji)
- Vim-style navigation (j/k/g/G)
| Dependency | Version | Install |
|---|---|---|
| Bun | >= 1.2 | curl -fsSL https://bun.sh/install | bash |
| mpv | >= 0.35 | See below |
| yt-dlp | latest | See below |
Linux (Arch)
sudo pacman -S mpv yt-dlpLinux (Debian/Ubuntu)
sudo apt install mpv
pip install yt-dlpmacOS
brew install mpv yt-dlpWindows - See PLATFORM.md for status. Currently requires Unix socket support (TCP fallback planned).
WSL2 (Windows Subsystem for Linux)
# Works like native Linux. Requires WSLg (Win11 22H2+) for audio.
sudo apt install mpv
pip install yt-dlpcurl -fsSL https://raw.githubusercontent.com/5c0r/TuiTunes/main/install.sh | bashInstalls Bun (if needed), tui-tunes, and checks for mpv + yt-dlp.
bun install -g tui-tunes@alpha
tui-tunesgit clone https://github.com/5c0r/TuiTunes.git
cd TuiTunes
bun install
bun run start- Press
/to focus the search bar - Type a song name, press
Enter - Use
j/kto navigate results - Press
Enterto play - Press
Ctrl+2to switch to Podcasts
| Key | Action |
|---|---|
Ctrl+P |
Command palette |
Ctrl+L |
Cycle layout |
Ctrl+T |
Cycle theme |
Ctrl+1 |
Music section |
Ctrl+2 |
Podcast section |
Ctrl+Q |
Quit |
| Key | Action |
|---|---|
Space |
Play / Pause |
n / p |
Next / Previous (queue) |
> / < |
Seek +/- 10 seconds |
t |
Jump to specific time |
+ / - |
Volume up / down |
m |
Toggle mute |
] / [ |
Speed up / down |
s |
Toggle shuffle |
r |
Cycle repeat (off / all / track) |
| Key | Action |
|---|---|
j / k |
Move down / up |
g / G |
Go to top / bottom |
Enter |
Play selected / Browse episodes |
Tab |
Cycle focus: main / sidebar / search |
/ |
Focus search |
Escape |
Back to main |
? |
Help overlay |
| Key | Action |
|---|---|
q |
Add to queue |
x |
Remove from queue |
f |
Toggle favorite |
l |
Toggle lyrics / transcript |
L |
Load more results |
TuiTunes has two independent sections, each with its own sidebar and search routing:
- Search - YouTube Music search with pagination (Shift+L for page 2)
- Queue - User-controlled playlist (q to add, x to remove)
- Favorites - Saved tracks (f to toggle, persisted in SQLite)
- History - Recently played tracks
- Search - iTunes podcast discovery
- My Feeds - Subscribed podcasts (subscribe via command palette)
- Episodes - Browse and play episodes from a feed
Podcast episodes prefer YouTube-backed playback when available, giving perfectly synced auto-generated transcripts. Falls back to RSS audio when no YouTube match exists.
Cycle with Ctrl+T or via command palette:
- Tokyo Night - Cool blues (default)
- Catppuccin Mocha - Soft pastels
- Dracula - Classic purple
- Nord - Arctic frost
- Gruvbox - Warm retro
- Solarized Dark - Low contrast
- Rose Pine - Muted elegant
- Kanagawa - Japanese ink
Cycle with Ctrl+L or via command palette:
| Layout | Description |
|---|---|
| Default | Sidebar + main content + now-playing footer |
| Compact | No sidebar, full-width content |
| Minimal | Search + track list + footer only |
| Split | Queue on left, results on right |
| Wide | Extended now-playing with queue preview |
| Focus | Distraction-free, now-playing only |
Config file: ~/.config/tuimusic/config.json
{
"defaultProvider": "youtube",
"volume": 80,
"localMusicDirs": ["~/Music"],
"theme": "dark",
"poToken": null,
"visitorData": null
}Data stored in:
~/.config/tuimusic/tuimusic.db- Favorites, history, podcast subscriptions (SQLite)~/.config/tuimusic/debug.log- Debug log
bun run start # Launch
bun run dev # Watch mode (auto-restart on changes)
bun test # Run 196 tests
bunx tsc --noEmit # Type checkbun build --compile --minify src/index.tsx --outfile dist/tuimusic
./dist/tuimusicProduces a standalone ~105MB binary (includes Bun runtime). Still requires system mpv and yt-dlp.
src/
index.tsx Entry point: bootstrap + cleanup
app.tsx Root component: keyboard handler + layout rendering
commands.ts 35 commands for the command palette
player/ mpv JSON IPC over Unix socket
providers/ YouTube, podcast, lyrics, transcripts
store/ Jotai atoms (player, queue, UI, library, podcast)
ui/ OpenTUI React components (12 components)
db/ SQLite persistence (bun:sqlite)
utils/ Config, logging, formatting
See AGENTS.md for the full development guide, and PLATFORM.md for cross-platform details.
| Component | Technology |
|---|---|
| Runtime | Bun |
| TUI Framework | OpenTUI (Zig + React 19) |
| Audio Engine | mpv via JSON IPC |
| Streaming | yt-dlp |
| YouTube Search | youtubei.js |
| State Management | Jotai v2 |
| Database | bun:sqlite (WAL mode) |
| Lyrics | LRCLIB |
| Podcast Search | iTunes Search API |
MIT