simpleplay 0.1.2

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, and keeps autoplaying similar songs from the current track's YouTube mix.

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. For direct repo runs, simpleplay can use either the Python yt-dlp package or an installed yt-dlp binary.

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
• H / L lower or raise volume by 5%
• 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.
• If the Python yt-dlp module is missing, simpleplay falls back to the yt-dlp CLI when it is installed on your system.
• mpv is kept alive as one long-running process and controlled over its IPC socket for better responsiveness.
• Queue progression and autoplay are driven by the app over mpv IPC so playback stays on resolved audio stream URLs.
• 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.
• 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.