simpleplay 0.1.0__tar.gz

simpleplay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simpleplay-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: simpleplay
+Version: 0.1.0
+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`, 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:
+
+```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`.
+
+## 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
+- `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:
+
+```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.

simpleplay-0.1.0/README.md

@@ -0,0 +1,123 @@
+# 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:
+
+```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`.
+
+## 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
+- `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:
+
+```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.

simpleplay-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simpleplay"
+dynamic = ["version"]
+description = "Terminal YouTube music player with vim-like bindings"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["yt-dlp"]
+authors = [{ name = "Geet" }]
+keywords = ["terminal", "music", "youtube", "mpv", "player"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Players",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/geetrakala/simpleplay"
+Repository = "https://github.com/geetrakala/simpleplay"
+Issues = "https://github.com/geetrakala/simpleplay/issues"
+
+[project.scripts]
+simpleplay = "simpleplay.__main__:main"
+
+[tool.setuptools]
+packages = ["simpleplay"]
+
+[tool.setuptools.dynamic]
+version = { attr = "simpleplay.__version__" }

simpleplay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simpleplay-0.1.0/simpleplay/__init__.py

@@ -0,0 +1,5 @@
+"""simpleplay package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

simpleplay-0.1.0/simpleplay/__main__.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .app import SimplePlayApp
+from .player import PlayerError
+from .youtube import YouTubeError, require_binary
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Search and play YouTube music from the terminal.")
+    parser.add_argument("query", nargs="*", help="Optional initial search query")
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    initial_query = " ".join(args.query).strip()
+
+    try:
+        require_binary("mpv")
+        app = SimplePlayApp(initial_query=initial_query)
+        app.run()
+    except KeyboardInterrupt:
+        return 0
+    except (YouTubeError, PlayerError) as exc:
+        print(f"simpleplay: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())