tsetse 0.2.0__tar.gz

tsetse-0.2.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.

tsetse-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: tsetse
+Version: 0.2.0
+Summary: Terminal YouTube music player with vim-like bindings
+Author: Geet
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GeetRakala/tsetse
+Project-URL: Repository, https://github.com/GeetRakala/tsetse
+Project-URL: Issues, https://github.com/GeetRakala/tsetse/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
+
+# tsetse
+
+`tsetse` 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 tsetse
+```
+
+`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 tsetse`.
+For direct repo runs, `tsetse` can use either the Python `yt-dlp` package or an installed `yt-dlp` binary.
+
+## Run
+
+Start the UI with no query:
+
+```bash
+tsetse
+```
+
+Start with an initial search:
+
+```bash
+tsetse "daft punk"
+```
+
+Without installing:
+
+```bash
+python3 -m tsetse "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, `tsetse` 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, `tsetse` 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, and the resolved prefix of the queue is mirrored into `mpv` so its next/previous controls stay usable.
+- 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.

tsetse-0.2.0/README.md

@@ -0,0 +1,125 @@
+# tsetse
+
+`tsetse` 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 tsetse
+```
+
+`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 tsetse`.
+For direct repo runs, `tsetse` can use either the Python `yt-dlp` package or an installed `yt-dlp` binary.
+
+## Run
+
+Start the UI with no query:
+
+```bash
+tsetse
+```
+
+Start with an initial search:
+
+```bash
+tsetse "daft punk"
+```
+
+Without installing:
+
+```bash
+python3 -m tsetse "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, `tsetse` 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, `tsetse` 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, and the resolved prefix of the queue is mirrored into `mpv` so its next/previous controls stay usable.
+- 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.

tsetse-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tsetse"
+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/tsetse"
+Repository = "https://github.com/GeetRakala/tsetse"
+Issues = "https://github.com/GeetRakala/tsetse/issues"
+
+[project.scripts]
+tsetse = "tsetse.__main__:main"
+
+[tool.setuptools]
+packages = ["tsetse"]
+
+[tool.setuptools.dynamic]
+version = { attr = "tsetse.__version__" }

tsetse-0.2.0/setup.cfg

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

tsetse-0.2.0/tests/test_app.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+import unittest
+
+from tsetse.app import TsetseApp
+from tsetse.models import StreamCacheEntry, Track
+
+
+class TsetseAppTests(unittest.TestCase):
+    def test_starts_out_of_search_mode_without_initial_query(self) -> None:
+        app = TsetseApp()
+        self.assertFalse(app.search_mode)
+
+    def test_starts_out_of_search_mode_with_initial_query(self) -> None:
+        app = TsetseApp(initial_query="daft punk")
+        self.assertFalse(app.search_mode)
+
+    def test_slash_starts_fresh_search(self) -> None:
+        app = TsetseApp()
+        app.search_query = "old query"
+
+        app._handle_key(ord("/"))
+
+        self.assertTrue(app.search_mode)
+        self.assertEqual(app.search_query, "")
+
+    def test_typing_in_search_mode_schedules_live_search(self) -> None:
+        app = TsetseApp()
+        app.search_mode = True
+
+        app._handle_search_key(ord("d"))
+
+        self.assertEqual(app.search_query, "d")
+        self.assertIsNotNone(app.search_debounce_deadline)
+
+    def test_live_search_starts_when_debounce_expires(self) -> None:
+        app = TsetseApp()
+        started: list[str] = []
+        app.search_mode = True
+        app.search_query = "daft punk"
+        app.search_debounce_deadline = 0.0
+        app._start_search = lambda query: started.append(query)  # type: ignore[method-assign]
+
+        app._maybe_start_live_search()
+
+        self.assertEqual(started, ["daft punk"])
+
+    def test_enter_skips_duplicate_search_when_results_are_current(self) -> None:
+        app = TsetseApp()
+        started: list[str] = []
+        app.search_mode = True
+        app.search_query = "daft punk"
+        app.last_completed_search_query = "daft punk"
+        app._start_search = lambda query: started.append(query)  # type: ignore[method-assign]
+
+        app._handle_search_key(10)
+
+        self.assertFalse(app.search_mode)
+        self.assertEqual(started, [])
+
+    def test_uppercase_h_lowers_volume(self) -> None:
+        app = TsetseApp()
+        changes: list[int] = []
+
+        app.player.change_volume = lambda delta: changes.append(delta)  # type: ignore[method-assign]
+
+        app._handle_key(ord("H"))
+
+        self.assertEqual(changes, [-5])
+        self.assertEqual(app.volume, 95.0)
+        self.assertEqual(app.status_message, "Volume: 95%")
+
+    def test_uppercase_l_raises_volume(self) -> None:
+        app = TsetseApp()
+        changes: list[int] = []
+
+        app.player.change_volume = lambda delta: changes.append(delta)  # type: ignore[method-assign]
+
+        app._handle_key(ord("L"))
+
+        self.assertEqual(changes, [5])
+        self.assertEqual(app.volume, 105.0)
+        self.assertEqual(app.status_message, "Volume: 105%")
+
+    def test_load_track_starts_pending_playback_before_stream_resolve(self) -> None:
+        app = TsetseApp()
+        track = Track(video_id="abc123", title="Song")
+        resolved: list[str] = []
+
+        app._start_stream_resolve = lambda current: resolved.append(current.video_id)  # type: ignore[method-assign]
+
+        app._load_track(track)
+
+        self.assertEqual(resolved, ["abc123"])
+        self.assertEqual(app.pending_play_video_id, "abc123")
+        self.assertEqual(app.status_message, "Loading: Song")
+
+    def test_pending_playback_uses_cached_stream_when_ready(self) -> None:
+        app = TsetseApp()
+        track = Track(video_id="abc123", title="Song")
+        loads: list[tuple[str, str | None]] = []
+        synced: list[bool] = []
+
+        app.current_track = track
+        app.pending_play_video_id = track.video_id
+        app.stream_cache[track.video_id] = StreamCacheEntry(url="https://example.com/audio")
+        app.player.load = lambda url, media_title=None: loads.append((url, media_title))  # type: ignore[method-assign]
+        app._sync_mpv_playlist = lambda: synced.append(True)  # type: ignore[method-assign]
+
+        app._maybe_start_pending_playback()
+
+        self.assertEqual(loads, [("https://example.com/audio", "Song")])
+        self.assertEqual(synced, [True])
+        self.assertIsNone(app.pending_play_video_id)
+        self.assertEqual(app.status_message, "Playing: Song")
+
+    def test_pending_playback_waits_for_resolved_stream_url(self) -> None:
+        app = TsetseApp()
+        track = Track(video_id="abc123", title="Song")
+        loads: list[tuple[str, str | None]] = []
+
+        app.current_track = track
+        app.pending_play_video_id = track.video_id
+        app.status_message = "Loading: Song"
+        app.player.load = lambda url, media_title=None: loads.append((url, media_title))  # type: ignore[method-assign]
+
+        app._maybe_start_pending_playback()
+
+        self.assertEqual(loads, [])
+        self.assertEqual(app.pending_play_video_id, track.video_id)
+        self.assertEqual(app.status_message, "Loading: Song")
+
+    def test_play_selected_seeds_queue_from_search_results(self) -> None:
+        app = TsetseApp()
+        first = Track(video_id="one", title="One")
+        second = Track(video_id="two", title="Two")
+        third = Track(video_id="three", title="Three")
+
+        app.list_mode = "search"
+        app.results = [first, second, third]
+        app.selected_index = 1
+        app._load_track = lambda track: None  # type: ignore[method-assign]
+        app._start_related_prefetch = lambda track: None  # type: ignore[method-assign]
+        app._fill_queue_from_related = lambda track: None  # type: ignore[method-assign]
+        app._warm_queue_streams = lambda: None  # type: ignore[method-assign]
+
+        app._play_selected()
+
+        self.assertEqual(app.current_track.video_id, "two")
+        self.assertEqual(list(app.up_next), [first, third])
+        self.assertEqual(app.results, [first, third])
+
+    def test_related_error_does_not_override_current_playback_status(self) -> None:
+        app = TsetseApp()
+        track = Track(video_id="abc123", title="Song")
+
+        app.current_track = track
+        app.status_message = "Playing: Song"
+        app.pending_related.add(track.video_id)
+
+        app._process_event(
+            {
+                "type": "related-error",
+                "video_id": track.video_id,
+                "message": "[ERROR] video not found",
+            }
+        )
+
+        self.assertEqual(app.status_message, "Playing: Song")
+        self.assertNotIn(track.video_id, app.pending_related)
+
+    def test_stream_error_for_current_track_clears_pending_playback_and_surfaces_message(self) -> None:
+        app = TsetseApp()
+        track = Track(video_id="abc123", title="Song")
+        loads: list[tuple[str, str | None]] = []
+
+        app.current_track = track
+        app.pending_play_video_id = track.video_id
+        app.player.load = lambda url, media_title=None: loads.append((url, media_title))  # type: ignore[method-assign]
+
+        app._process_event(
+            {
+                "type": "stream-error",
+                "video_id": track.video_id,
+                "message": "Video is unavailable on YouTube.",
+            }
+        )
+
+        self.assertEqual(loads, [])
+        self.assertIsNone(app.pending_play_video_id)
+        self.assertEqual(app.status_message, "Video is unavailable on YouTube.")
+
+    def test_stream_error_removes_unplayable_track_from_queue(self) -> None:
+        app = TsetseApp()
+        current = Track(video_id="now", title="Now")
+        broken = Track(video_id="bad", title="Broken")
+        healthy = Track(video_id="good", title="Healthy")
+
+        app.current_track = current
+        app.list_mode = "queue"
+        app.up_next.extend([broken, healthy])
+        app.results = [broken, healthy]
+
+        app._process_event(
+            {
+                "type": "stream-error",
+                "video_id": broken.video_id,
+                "message": "Video is unavailable on YouTube.",
+            }
+        )
+
+        self.assertEqual([track.video_id for track in app.up_next], ["good"])
+        self.assertEqual([track.video_id for track in app.results], ["good"])
+
+    def test_core_idle_change_resumes_autoplay_when_waiting(self) -> None:
+        app = TsetseApp()
+        current = Track(video_id="now", title="Now")
+        healthy = Track(video_id="good", title="Healthy")
+        resumed: list[bool] = []
+
+        app.current_track = current
+        app.awaiting_autoplay = True
+        app.player_idle = False
+        app.up_next.append(healthy)
+        app._play_next = lambda *, auto: resumed.append(auto)  # type: ignore[method-assign]
+
+        app._handle_player_payload({"event": "property-change", "name": "core-idle", "data": True})
+
+        self.assertEqual(resumed, [True])
+
+    def test_volume_property_change_updates_state(self) -> None:
+        app = TsetseApp()
+
+        app._handle_player_payload({"event": "property-change", "name": "volume", "data": 72.0})
+
+        self.assertEqual(app.volume, 72.0)
+
+    def test_sync_mpv_playlist_uses_resolved_queue_prefix(self) -> None:
+        app = TsetseApp()
+        history = Track(video_id="hist", title="History")
+        current = Track(video_id="now", title="Now")
+        first = Track(video_id="next1", title="Next 1")
+        second = Track(video_id="next2", title="Next 2")
+        synced: list[tuple[list[tuple[Track, str]], list[tuple[Track, str]]]] = []
+        titles: list[str] = []
+
+        app.history = [history]
+        app.current_track = current
+        app.up_next.extend([first, second])
+        app.stream_cache = {
+            history.video_id: StreamCacheEntry(url="https://example.com/history"),
+            current.video_id: StreamCacheEntry(url="https://example.com/current"),
+            first.video_id: StreamCacheEntry(url="https://example.com/next1"),
+        }
+        app.player.sync_playlist = lambda history_entries, up_next_entries: synced.append(  # type: ignore[method-assign]
+            (history_entries, up_next_entries)
+        )
+        app.player.set_media_title = lambda title: titles.append(title)  # type: ignore[method-assign]
+
+        app._sync_mpv_playlist()
+
+        self.assertEqual(app.playlist_tracks, [history, current, first])
+        self.assertEqual(
+            synced,
+            [
+                (
+                    [(history, "https://example.com/history")],
+                    [(first, "https://example.com/next1")],
+                )
+            ],
+        )
+        self.assertEqual(titles, ["Now"])

tsetse-0.2.0/tests/test_models.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import unittest
+
+from tsetse.models import LoopMode, StreamCacheEntry, Track, format_duration
+
+
+class FormatDurationTests(unittest.TestCase):
+    def test_formats_short_values(self) -> None:
+        self.assertEqual(format_duration(65), "1:05")
+
+    def test_formats_hour_values(self) -> None:
+        self.assertEqual(format_duration(3661), "1:01:01")
+
+    def test_formats_missing_values(self) -> None:
+        self.assertEqual(format_duration(None), "--:--")
+
+
+class LoopModeTests(unittest.TestCase):
+    def test_cycle_order(self) -> None:
+        self.assertEqual(LoopMode.OFF.cycle(), LoopMode.ALL)
+        self.assertEqual(LoopMode.ALL.cycle(), LoopMode.ONE)
+        self.assertEqual(LoopMode.ONE.cycle(), LoopMode.OFF)
+
+
+class TrackTests(unittest.TestCase):
+    def test_default_watch_url_is_derived(self) -> None:
+        track = Track(video_id="abc123", title="Song")
+        self.assertEqual(track.watch_url, "https://www.youtube.com/watch?v=abc123")
+
+    def test_stream_cache_entry_is_fresh_initially(self) -> None:
+        entry = StreamCacheEntry(url="https://example.com/audio")
+        self.assertTrue(entry.is_fresh())