simpleplay 0.1.0

Terminal YouTube music player with vim-like bindings

simpleplay

simpleplay is a terminal YouTube music player. It searches YouTube in a low-latency mode, plays audio-only through mpv, stops cleanly on Ctrl+C, keeps autoplaying similar songs from the current track's YouTube mix, and mirrors the queue into mpv's internal playlist so next/previous controls stay in sync.

Caveat

The entire thing is vibe-coded. Use at your own risk.

Dependencies

• python3 3.11+
• mpv

Optional:

• ffmpeg is not required for normal playback, but it is useful for local media debugging.
• A supported JavaScript runtime such as node may help yt-dlp on some YouTube videos.

Install

From PyPI:

pip install simpleplay

pip installs the Python yt-dlp dependency automatically. mpv is still a separate system binary, so pip cannot install it for you.

• mpv

Install mpv with your OS package manager:

# macOS
brew install mpv

# Debian / Ubuntu
sudo apt install mpv

# Fedora
sudo dnf install mpv

# Arch
sudo pacman -S mpv

# Windows
winget search mpv
winget install <mpv-package-id>

More options: https://mpv.io/installation

From this repo:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

If you do not want an editable install, you can still run the app directly with python3 -m simpleplay.

Run

Start the UI with no query:

simpleplay

Start with an initial search:

simpleplay "daft punk"

Without installing:

python3 -m simpleplay "khruangbin"

Keybindings

• / enter search mode with a fresh empty query
• typing in search mode starts a debounced live search automatically
• Enter leave search mode and keep the current results
• Esc leave search mode
• j / k move through the current list
• Enter on a search result starts playback
• after playback starts, the main list becomes Up Next, and Enter on a queued item jumps to it
• space or p pause or resume
• h / l seek backward or forward 10 seconds
• n play the next queued or similar track
• b go to the previous track, or restart the current track if more than 5 seconds in
• r cycle loop mode: off -> all -> one
• g / G jump to the top or bottom of the results list
• q quit
• Ctrl+C stop playback and exit cleanly

How autoplay works

When a track starts, simpleplay immediately seeds Up Next from the current search results so the queue is usable right away. In parallel, it asks YouTube for the current video's mix playlist (list=RD<video_id>). Those related tracks are added to the in-memory queue, shown in the Up Next list, and the next few are prefetched for faster transitions.

Notes

• The only non-Python runtime dependency is mpv. yt-dlp is installed automatically as a Python package dependency.
• mpv is kept alive as one long-running process and controlled over its IPC socket for better responsiveness.
• The app keeps its queue mirrored into mpv's internal playlist, so mpv's own next/previous controls can move through the same queue.
• Search uses a fast YouTube page parser first, with the bundled yt-dlp Python package as fallback when needed.
• Direct audio stream URLs are cached briefly in memory because YouTube stream URLs expire.
• The first few search results and queued tracks are prefetched in the background so selecting them is more likely to start from a cached direct audio URL.
• Playback start prefers a prefetched direct audio URL for a short grace window, then falls back to mpv loading the YouTube watch URL directly if the resolver is not ready yet.
• If yt-dlp starts failing on some videos due to YouTube extractor changes, update it first.

Commands

Run tests:

python3 -m unittest discover -s tests -v

Format or linting commands are not included because this project is stdlib-only and does not ship a formatter config yet.