ytune

A terminal-based YouTube music player. Search, stream, and optionally save tracks to your local library — all from the command line.

Features

• Full-text YouTube search from the terminal
• Audio streaming via mpv (no video, no browser)
• Playback queue with auto-advance
• Volume control and seek
• Download selected track to local library (MP3 or FLAC with loudness normalization)
• Persistent settings and music library registry (library.json)

Installation

# System dependencies
sudo apt install mpv yt-dlp ffmpeg pipx

# Install ytune
pipx install -e .

ytune will be available globally. Because it's installed in editable mode (-e), any changes to the source are picked up automatically without reinstalling.

Usage

ytune

Keybindings

Key	Action
Type + Enter	Search YouTube
Tab / ↓	Switch to results
↑ ↓ / j k	Navigate
Enter / Space	Play selected track
a	Add selected track to queue
l	Open / close queue view
p	Pause / resume
s	Stop
← →	Seek ±10 seconds
+ -	Volume up / down
d	Download selected track to library
?	Show / hide help bar
/	Back to search
q / Esc	Quit

In queue view, d removes the selected track and c clears the entire queue.

Configuration

Settings are stored in settings.json (auto-created on first run):

{
  "volume": 0.8,
  "save_local": true,
  "library_dir": "~/Music/ytune",
  "audio_format": "mp3",
  "normalize": true,
  "max_search_results": 20
}

Saved tracks are registered in library.json with title, channel, URL, duration, format, file path, and timestamp.

Acknowledgments

Forked from youtube-audio-downloader by @paulamanosalva. The original script inspired this project — thanks for sharing it.