🎵 ytmp

A fast, minimal, and beautiful YouTube & YouTube Music TUI player written in Go.

Features • Prerequisites • Installation • Authentication & Setup • Keybindings • Configuration • Known Edge Cases

---

🌟 Overview

ytmp is a high-performance terminal music player designed to bring your YouTube and YouTube Music playlists directly into your command line. Built with Charm's Bubble Tea v2 for a responsive TUI, mpv for robust audio streaming, and yt-dlp for metadata extraction, ytmp delivers a distraction-free and lightweight listening experience.

Note

ytmp currently supports Linux. macOS and Windows support are planned for a future release.

---

🖼️ Gallery

---

✨ Features

• ⚡ Gapless & Low-Latency Playback
  Asynchronously prefetches stream URLs for subsequent and preceding tracks in the background, eliminating buffering delays between songs.
• 💾 Dual-Tier Caching Architecture
  • Persistent SQLite Database (~/.cache/ytmp/cache.db): Automatically caches playlist and song metadata (titles, artists, durations, view counts, thumbnails) for instantaneous startup and offline navigation.
  • In-Memory Stream Hash Map: Caches direct audio stream URLs in memory to prevent repetitive network lookups during a session.
• 🔀 Flawless Queue Management
  Interactive queue screen with support for instant shuffling, "Play Next" priority insertion, appending songs on the fly, and seamless cursor tracking.
• ❤️ Favorites & Playlist Filtering
  Mark favorite playlists with a single keypress and toggle between viewing all playlists or only your starred favorites.
• 🎛️ Headless MPV IPC Engine
  Direct socket-based IPC communication with mpv allows smooth volume adjustments, real-time scrubbing/seeking, and event listening.
• 🛰️ Full MPRIS 2.2 & playerctl Integration (Linux)
  Seamlessly control playback, scrub tracks, adjust volume, and view metadata through media keys, status bars (Waybar, Polybar), desktop widgets, or playerctl.
• 🎨 Configurable & Minimal TUI
  Clean aesthetic with customizable ANSI themes, dynamic progress bars, duration indicators, and automatic terminal resizing.

---

📋 Prerequisites

Before running ytmp, ensure the following tools are installed on your system:

1. mpv — Command-line media player used as the playback engine.

   # Arch Linux
   sudo pacman -S mpv
   
   # Debian / Ubuntu
   sudo apt install mpv
   

2. yt-dlp — YouTube metadata and audio stream extractor.

   # Arch Linux
   sudo pacman -S yt-dlp
   
   # Debian / Ubuntu
   sudo apt install yt-dlp
   
   # Or via pip / pipx
   pipx install yt-dlp

---

🔐 yt-dlp Configuration (Authentication)

To allow yt-dlp (and ytmp) to fetch your personalized YouTube and YouTube Music playlists without login blocks or bot detection issues, you must configure authentication using browser cookies.

Create or edit the configuration file at:

mkdir -p ~/.config/yt-dlp
nano ~/.config/yt-dlp/config

Export cookies from a private/incognito window (Recommended)

YouTube rotates account cookies frequently on open YouTube browser tabs as a security measure. To export cookies that will remain working with yt-dlp, export them in a way that prevents them from being rotated.

Install Get cookies.txt LOCALLY, then:

1. Open a new private browsing/incognito window and log in to YouTube.
2. In that same window and tab, navigate to https://www.youtube.com/robots.txt. It should be the only private/incognito tab open.
3. Export the youtube.com cookies with the extension, then close the private browsing/incognito window so that session is never opened in the browser again.
4. Set ~/.config/yt-dlp/config to point to the exported cookie file:

--cookies /path-to-cookie.txt

Important

Keep the exported cookie file secure and private, as it contains active session credentials.

---

🚀 Installation

From Source

Make sure you have Go 1.27+ installed:

# Clone the repository
git clone https://github.com/zyncc/ytmp.git
cd ytmp

# Build binary
go build -o ytmp ./cmd/ytmp

# (Optional) Move to your PATH
sudo mv ytmp /usr/local/bin/

Go Install

go install github.com/zyncc/ytmp/cmd/ytmp@latest

---

⌨️ Keybindings

🎵 Playback & Audio

Key	Action
Space	Toggle Play / Pause
.	Next track
,	Previous track / Restart track (if > 10s elapsed)
→	Seek forward 5 seconds
←	Seek backward 5 seconds
+ / =	Increase volume
-	Decrease volume
r	Toggle repeat mode

---

🧭 Navigation & Scrolling

Key	Action
↑ / k	Move cursor up
↓ / j	Move cursor down
g / Home	Jump to top of list
G / End	Jump to bottom of list
Ctrl + u / PgUp	Scroll page up
Ctrl + d / PgDown	Scroll page down

---

🌐 General & Application

Key	Action
q	Toggle Queue screen / Back
?	Toggle Keybinds help overlay
Esc	Back / Return to previous view
Ctrl + c	Quit application

---

📂 Playlists Screen

Key	Action
Enter	Open selected playlist and load songs
f	Toggle Favorite status for selected playlist
Ctrl + f	Toggle Filter (Show All / Favorites Only)

---

🎵 Songs Screen

Key	Action
Enter	Play song immediately and load remaining playlist into queue
s	Shuffle all songs in current playlist and start playback
a	Add song to play next (inserted immediately after current track)
e	Enqueue song (append to the end of queue)
Esc	Return to Playlists screen

---

📑 Queue Screen

Key	Action
Enter	Jump to and play selected song
d	Remove selected song from queue
a	Duplicate and add song to play next
e	Duplicate and enqueue song at end of queue
Esc / q	Return to previous screen

---

⚙️ Configuration

ytmp automatically generates a default configuration file upon initial launch at:

~/.config/ytmp/config.toml

Default config.toml

[general]
toggle_favorites = false

[player]
default_volume = 100
volume_increment_amount = 5

[theme]
primary = "4"       # Primary accent color (ANSI or Hex)
secondary = "6"     # Secondary highlight color
text = "7"          # Standard text
subtle = "8"        # Subtle / dimmed labels and borders
border = "0"        # Table borders
success = "2"       # Success indicator
error = "1"         # Error indicator

---

🗄️ Cache & Storage

• Database: Metadata is cached locally in SQLite at ~/.cache/ytmp/cache.db with automated migrations.
• Logs: Production runtime logs are written for diagnostics and debugging.

To reset the database cache, run:

ytmp delete cache

---

⚠️ Known Edge Cases & Disclaimers

Warning

Stream URL Expiration (6-Hour YouTube CDN Limit):
YouTube's direct audio stream URLs (googlevideo.com) are cryptographically signed with a time-to-live (TTL) of approximately 6 hours.

Currently, ytmp caches these stream URLs in an in-memory map for instantaneous and gapless track switching. If you leave ytmp running continuously for more than 6 hours and attempt to play a track whose URL was cached at the start of the session, playback may fail due to URL expiration. A background token refresh mechanism is planned for a future update.

---

🛠️ Tech Stack

• Language: Go
• TUI Framework: Bubble Tea v2, Lipgloss v2, Bubbles v2
• Audio Engine: Headless mpv via Unix Domain Socket IPC
• Metadata Extraction: yt-dlp
• Database: Pure Go SQLite (modernc.org/sqlite) + golang-migrate

---

📄 License

This project is licensed under the MIT License.