Metadata-Version: 2.4
Name: simpleplay
Version: 0.1.2
Summary: Terminal YouTube music player with vim-like bindings
Author: Geet
License-Expression: MIT
Project-URL: Homepage, https://github.com/geetrakala/simpleplay
Project-URL: Repository, https://github.com/geetrakala/simpleplay
Project-URL: Issues, https://github.com/geetrakala/simpleplay/issues
Keywords: terminal,music,youtube,mpv,player
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp
Dynamic: license-file

# 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:

```bash
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:

```bash
# 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:

```bash
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:

```bash
simpleplay
```

Start with an initial search:

```bash
simpleplay "daft punk"
```

Without installing:

```bash
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:

```bash
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.
