ttyplayer 0.3.0__py3-none-any.whl

ttyplayer/tui.tcss

@@ -0,0 +1,125 @@
+/* ttyplayer tui — layout per docs/tui-design.md. Theme variables only, so every theme fits. */
+
+#search-row {
+    height: 3;
+}
+
+#search-row SearchBox {
+    width: 1fr;
+}
+
+#search-row LoadingIndicator {
+    width: 6;
+    height: 3;
+    color: $accent;
+}
+
+TabbedContent {
+    height: 1fr;
+}
+
+ResultsTable {
+    height: 1fr;
+}
+
+NowPlaying {
+    height: 5;
+    border: round $primary;
+    border-title-color: $accent;
+    background: $surface;
+    padding: 0 1;
+}
+
+NowPlaying #np-idle {
+    display: none;
+    text-style: dim;
+}
+
+NowPlaying.-idle #np-idle {
+    display: block;
+}
+
+NowPlaying.-idle .np-line {
+    display: none;
+}
+
+.np-line {
+    height: 1;
+}
+
+#np-state {
+    width: 3;
+}
+
+#np-title {
+    width: auto;
+    max-width: 70%;
+    text-wrap: nowrap;
+    text-overflow: ellipsis;
+    text-style: bold;
+    color: $accent;
+}
+
+#np-uploader {
+    width: 1fr;
+    text-wrap: nowrap;
+    text-overflow: ellipsis;
+    text-style: dim;
+}
+
+#np-position {
+    width: auto;
+}
+
+#np-progress {
+    width: 1fr;
+}
+
+#np-progress Bar {
+    width: 1fr;
+}
+
+#np-time {
+    width: auto;
+    padding-left: 1;
+}
+
+#np-volume {
+    width: auto;
+}
+
+#np-next {
+    width: 1fr;
+    padding-left: 4;
+    text-wrap: nowrap;
+    text-overflow: ellipsis;
+}
+
+#np-timing {
+    width: auto;
+    text-style: dim;
+}
+
+HelpScreen {
+    align: center middle;
+}
+
+#help {
+    width: auto;
+    height: auto;
+    max-height: 90%;
+    border: round $primary;
+    border-title-color: $accent;
+    background: $panel;
+    padding: 1 2;
+}
+
+#help Static {
+    width: auto;
+}
+
+.help-heading {
+    text-style: bold;
+    color: $accent;
+    margin-top: 1;
+}

ttyplayer/utils.py

@@ -0,0 +1,80 @@
+import os
+import sys
+from pathlib import Path
+
+from ttyplayer.models import Video
+
+APP_NAME = "ttyplayer"  # the product name; every path, prefix and message derives from it
+OLD_NAME = "cli" "tube"  # the name before ttyplayer, split so the old-name grep guard stays clean
+WINDOWS = sys.platform == "win32"  # the one platform test; modules import it, tests patch theirs
+
+
+def data_path(filename):
+    """Where ttyplayer keeps `filename`: $XDG_DATA_HOME/ttyplayer, by default ~/.local/share/ttyplayer,
+    or %LOCALAPPDATA%\\ttyplayer on Windows."""
+    base = Path(os.environ.get("XDG_DATA_HOME") or default_data_home())
+    migrate_data_dir(base)
+    return base / APP_NAME / filename
+
+
+def migrate_data_dir(base):
+    """Carry the old name's data dir over, once: rename it when only it exists, else leave both alone."""
+    old, new = base / OLD_NAME, base / APP_NAME
+    if old.is_dir() and not new.exists():
+        old.rename(new)
+
+
+def default_data_home():
+    if WINDOWS:
+        return os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local"
+    return Path.home() / ".local" / "share"
+
+
+def format_time(seconds):
+    if seconds is None:
+        return "--:--"
+    mins, secs = divmod(int(seconds), 60)
+    return f"{mins}:{secs:02d}"
+
+
+def video_from_info(entry):
+    """Build a Video from one yt-dlp entry. Only id is guaranteed to be present."""
+    return Video(
+        id=entry["id"],
+        title=entry.get("title") or "Untitled",
+        uploader=entry.get("uploader") or entry.get("channel") or "Unknown",
+        duration=entry.get("duration"),
+    )
+
+
+def handle_many_entries(entries):
+    # yt-dlp leaves None in place of deleted or private playlist entries.
+    return [video_from_info(entry) for entry in entries if entry]
+
+
+def unseen(videos, shown):
+    """The videos whose id is not in shown (nor repeated), in the order given."""
+    seen = {video.id for video in shown}
+    fresh = []
+    for video in videos:
+        if video.id not in seen:
+            seen.add(video.id)
+            fresh.append(video)
+    return fresh
+
+
+def parse_picks(text, count):
+    """Turn "1 3 5" into [1, 3, 5], or None if anything is not a number in 1..count."""
+    pieces = text.split()
+    if not pieces:
+        return None
+    picks = []
+    for piece in pieces:
+        try:
+            number = int(piece)
+        except ValueError:
+            return None
+        if not 1 <= number <= count:
+            return None
+        picks.append(number)
+    return picks

ttyplayer/youtube.py

@@ -0,0 +1,57 @@
+from yt_dlp import YoutubeDL
+from yt_dlp.utils import DownloadError
+
+from ttyplayer.models import Video
+from ttyplayer.utils import handle_many_entries, video_from_info
+
+class _Silent:
+    """yt-dlp prints errors to stderr even when quiet; we report them ourselves."""
+
+    def debug(self, message):
+        pass
+
+    def info(self, message):
+        pass
+
+    def warning(self, message):
+        pass
+
+    def error(self, message):
+        pass
+
+
+# extract_flat: list playlist/search entries without fetching each video in full.
+OPTIONS = {"extract_flat": True, "quiet": True, "no_warnings": True, "logger": _Silent()}
+
+
+class YouTubeError(Exception):
+    """yt-dlp could not resolve the target: no network, bad link, private video."""
+
+
+def _extract(target):
+    try:
+        return YoutubeDL(OPTIONS).extract_info(target, download=False)
+    except DownloadError as error:
+        raise YouTubeError(_clean(str(error))) from error
+
+
+def _clean(message):
+    # yt-dlp prefixes its messages with "ERROR: "; the CLI adds its own framing.
+    return message.removeprefix("ERROR: ").strip()
+
+
+def search(query, limit=5) -> list[Video]:
+    info = _extract(f"ytsearch{limit}:{query}")
+    return handle_many_entries(info.get("entries", []))
+
+
+def fetch(url) -> list[Video]:
+    """A single video link gives a one-item list; a playlist link gives every entry."""
+    info = _extract(url)
+    if "entries" in info:
+        return handle_many_entries(info["entries"])
+    return [video_from_info(info)]
+
+
+def is_url(text):
+    return text.startswith("http")

ttyplayer-0.3.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: ttyplayer
+Version: 0.3.0
+Summary: ttyplayer: a modern YouTube player for the terminal — search, queue, and play audio or video via mpv
+Keywords: youtube,music,player,mpv,cli,terminal,tui,yt-dlp
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Players
+Requires-Dist: textual>=8.2
+Requires-Dist: typer>=0.27.2
+Requires-Dist: yt-dlp>=2026.8.19
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/webliftro/ttyplayer
+Project-URL: Repository, https://github.com/webliftro/ttyplayer
+Description-Content-Type: text/markdown
+
+# ttyplayer
+
+A modern YouTube player for the terminal. Search YouTube, queue videos and playlists, and play audio, or video too, through mpv: from the command line, or from a full-screen TUI. Keep a history and favorites, and drive the player from any other terminal.
+
+## Usage
+
+```
+ttyplayer play <url>                 play a video link, audio only
+ttyplayer play <playlist url>        queue every entry of a playlist
+ttyplayer play <words...>            search, pick one or more results, play them in order
+ttyplayer play ... --video           open a video window as well
+ttyplayer play ... --limit 10        show more search results
+
+ttyplayer search <words...>          list results with durations
+ttyplayer history                    recently played, newest first
+ttyplayer history --play             pick from history and play again
+ttyplayer history --clear            forget the history
+ttyplayer favorite <url | words...>  add a link, a playlist, or search picks to favorites
+ttyplayer favorites                  favorites, newest first
+ttyplayer favorites --play           pick from favorites and play them
+ttyplayer favorites --remove 2       drop the second favorite as listed
+ttyplayer favorites --clear          forget all favorites
+ttyplayer tui [--video]              full-screen: search box, results list, now-playing bar
+ttyplayer doctor                     check Python, yt-dlp, mpv and ttyplayer's folders
+ttyplayer version
+```
+
+While ttyplayer plays in one terminal, any other terminal can drive it:
+
+```
+ttyplayer pause                      pause / resume
+ttyplayer next                       next in the queue
+ttyplayer prev                       previous in the queue
+ttyplayer stop                       quit the player
+ttyplayer status                     1:23 / 4:56  Playing  <title>
+```
+
+Keys while playing:
+
+| Key | Action |
+|---|---|
+| space | pause / resume |
+| left / right, `,` / `.` | seek 5 seconds |
+| up / down | volume |
+| `n` / `p` | next / previous in the queue |
+| `q` or Ctrl-C | quit, restores the terminal and stops mpv |
+
+On Windows (Windows Terminal, PowerShell) the keys, arrows included, map the same way.
+
+The volume meter, and the volume keys here and in the TUI, follow the Mac's system volume on macOS (the Mac's own volume keys move the meter within 2 seconds) and mpv's device (per-app) volume on Linux and Windows.
+
+Picks accept several numbers at once: `1 3 5` queues those three in that order. After a search, `m` lists the next batch of results.
+
+`TTYPLAYER_TIMING=1 ttyplayer play <words>` prints how long the YouTube lookup took and adds `started in 2.4s` (from `loadfile` to the first sound) to the status line.
+
+## TUI
+
+`ttyplayer tui` opens a full-screen player: a search box, Search / Queue / History / Favorites tabs, and a now-playing panel. Type a search or paste a link and press Enter. Ctrl-P opens the command palette (search, next theme, help, quit, pause, next, previous, mute, and Textual's own theme picker); `?` lists every key and command.
+
+| Where | Key | Action |
+|---|---|---|
+| anywhere | `/` | focus the search box (`esc` returns to the table) |
+| anywhere | `?` | help: every key and command (`esc` closes) |
+| anywhere | `1` `2` `3` `4` | Search / Queue / History / Favorites tab |
+| anywhere | Ctrl-C | quit and stop mpv |
+| anywhere | Ctrl-P | command palette |
+| anywhere | `t` | next theme |
+| table | `q` | quit and stop mpv (in the search box it is just a letter) |
+| table | `space` | pause / resume |
+| table | `n` / `p` | next / previous |
+| table | `,` / `.` | seek −5 s / +5 s |
+| table | `<` / `>` | seek −30 s / +30 s |
+| table | `-` / `+` | volume −5 / +5 |
+| table | `M` | mute / unmute (🔇 in the panel) |
+| table | `f` | favorite / unfavorite this row (the track playing when there is no row) |
+| Search · History · Favorites row | Enter | play this one, then the rows after it |
+| Search · History · Favorites row | `a` | add to the queue |
+| Search | `m` | more results |
+| Queue row | Enter | jump to this item |
+| Queue row | `d` | remove from the queue |
+| Queue row | `K` / `J` (or `shift+↑` / `shift+↓`) | move up / down |
+| Queue | `c` | clear the queue (keeps the current track playing) |
+| Favorites row | `d` | remove from favorites |
+
+In the search box, letters, digits, `/` and `?` are typed as text; `esc` leaves it for the table.
+
+## Install
+
+One command installs everything ttyplayer needs.
+
+macOS and Linux:
+
+```
+curl -LsSf https://raw.githubusercontent.com/webliftro/ttyplayer/main/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```
+irm https://raw.githubusercontent.com/webliftro/ttyplayer/main/install.ps1 | iex
+```
+
+Or clone the repository and run `./install.sh` (macOS, Linux) or `powershell -ExecutionPolicy ByPass -File .\install.ps1` (Windows) inside it; that installs the checkout you cloned.
+
+The script:
+
+1. installs [uv](https://docs.astral.sh/uv/) with its official installer if `uv` is missing (uv brings its own Python 3.13+; it runs as you, without sudo),
+2. installs mpv if it is missing: Homebrew on macOS, your package manager on Linux (`apt-get`, `dnf`, `pacman`, `zypper` or `apk`, with `sudo`), winget on Windows,
+3. installs ttyplayer with `uv tool install`,
+4. runs `ttyplayer doctor`: every line should start with ✓.
+
+It prints every command before running it. `TTYPLAYER_INSTALL_DRY_RUN=1 ./install.sh` and `install.ps1 -DryRun` only print them. If Homebrew (macOS) or winget (Windows) is missing, the script tells you how to install it and stops. If `ttyplayer` is not found in a new terminal, run `uv tool update-shell`.
+
+<details>
+<summary>By hand</summary>
+
+Three steps on every system: install uv, install mpv, install ttyplayer. Then run `ttyplayer doctor`.
+
+macOS:
+
+```
+curl -LsSf https://astral.sh/uv/install.sh | sh
+brew install mpv
+uv tool install ttyplayer
+```
+
+Linux:
+
+```
+curl -LsSf https://astral.sh/uv/install.sh | sh
+sudo apt-get install -y mpv
+uv tool install ttyplayer
+```
+
+On Fedora use `sudo dnf install -y mpv`, on Arch `sudo pacman -S --noconfirm mpv`, on openSUSE `sudo zypper install -y mpv`, on Alpine `sudo apk add mpv`.
+
+Windows:
+
+```
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+winget install -e --id shinchiro.mpv
+uv tool install ttyplayer
+```
+
+Instead of winget, `scoop install mpv` (from the `extras` bucket) or `choco install mpv` work too.
+
+`uv tool install ttyplayer` installs from PyPI once ttyplayer is published there. Until then install straight from GitHub:
+
+```
+uv tool install git+https://github.com/webliftro/ttyplayer
+```
+
+</details>
+
+Upgrade with `uv tool upgrade ttyplayer`. Uninstall with `uv tool uninstall ttyplayer`.
+
+## Development
+
+Install from a checkout, with mpv installed as above:
+
+```
+uv tool install --editable .
+```
+
+The `--editable` flag means edits to the source are live without reinstalling.
+
+```
+uv run pytest        # unit tests, no network and no mpv needed
+uv run ttyplayer ...   # run from the checkout
+```
+
+The live tests talk to the real YouTube through `ttyplayer.youtube`, so a yt-dlp or YouTube change shows up as a failing test. They are skipped unless `TTYPLAYER_LIVE=1` is set:
+
+```
+uv run pytest -q                                      # default suite, live tests skipped
+TTYPLAYER_LIVE=1 uv run pytest -q tests/test_live.py    # live tests, needs network
+```
+
+History lives in `$XDG_DATA_HOME/ttyplayer/history.jsonl`, by default `~/.local/share/ttyplayer/history.jsonl` (`%LOCALAPPDATA%\ttyplayer\history.jsonl` on Windows). Favorites live next to it in `favorites.jsonl`. History and favorites kept under the player's earlier name are moved here on the first run.
+
+### Releasing
+
+CI (`.github/workflows/tests.yml`) runs the suite on Linux and macOS on every push. Pushing a `v*` tag runs `.github/workflows/release.yml`, which builds with `uv build` and publishes to PyPI through trusted publishing, so there is no token to store.
+
+One-time setup on PyPI: create an account, then under "Publishing" add a pending GitHub publisher for the project `ttyplayer` with owner `webliftro`, repository `ttyplayer` and workflow `release.yml`. The first tagged release creates the project.
+
+To release, bump the version (`uv version --bump minor`, or edit `version` in `pyproject.toml`), commit, then:
+
+```
+git tag v0.3.0 && git push --tags
+```
+
+## How it works
+
+yt-dlp resolves what to play: a search or a playlist becomes a list of videos, a link becomes one. mpv produces the sound, started in the background with a private IPC socket. ttyplayer talks to it in JSON over that socket, owns the keyboard, and redraws a one-line status. See `docs/architecture.md`.
+
+## License
+
+MIT. See `LICENSE`.

ttyplayer-0.3.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ttyplayer/__init__.py,sha256=Ixj3lj1latdXCZL7K_TZZKkn-Vls3FNkPDxjc-Kdx8M,55
+ttyplayer/cli.py,sha256=Zx4CHUd3K-jcJePpkRqIbrOJvDkAaiBLIXFBkv4OHok,10337
+ttyplayer/control.py,sha256=EjHdygzm7cvXvuD7bsCbbeCCPK6wZI7ojD19paKgvZ0,8043
+ttyplayer/favorites.py,sha256=v_wHQZvcEYd82kj9zIdDl2CeMKoGjO5WU6Lj8HJP3q0,3013
+ttyplayer/history.py,sha256=m21Ea-O30jXpvZuKFN0upUtrObh4uYgDYDnJLlm4RNw,1919
+ttyplayer/models.py,sha256=CjWg_HaEjs4xuSfe5-HS0SunU61Xa01TZiMoBohlIlE,287
+ttyplayer/player.py,sha256=iXCPzrOn6RYeYC5Ookfo65Y-bCD06KgxUOYRPADoWKc,23817
+ttyplayer/tui.py,sha256=7r_Sxdd5d8uwzbNO4csa0f8T4oSAZxpa6UmxMWzN8_Q,23139
+ttyplayer/tui.tcss,sha256=6nXouucTm5t1CSPVPMFepIpNPlRqjqHRK5FGTeuTl7I,1616
+ttyplayer/utils.py,sha256=_8mu7TAYF1n2JIEl5_L1e891cvnc7aNicpMrbPxDmKI,2492
+ttyplayer/youtube.py,sha256=aIY5C9ZsTfo8pr-v3e5gWc0etslJGkk0yW08lsnizIs,1552
+ttyplayer-0.3.0.dist-info/licenses/LICENSE,sha256=AQ3oquFLP9MqkykFhM-xegULu0DKVGGIfl3caMbqbvA,1068
+ttyplayer-0.3.0.dist-info/WHEEL,sha256=3iQx15CyXwGi4dbygedzA4M5T1eqO_SjwdPfUmqt2Cw,81
+ttyplayer-0.3.0.dist-info/entry_points.txt,sha256=yDHJQx-Xohn4cbq9y0ot_5a4rgW0_Y3R5rnECT9FzrQ,50
+ttyplayer-0.3.0.dist-info/METADATA,sha256=pRqyRKpb9aGsVjqgrRInwLDs6mc2UHUwjg1X-9AmAl0,9600
+ttyplayer-0.3.0.dist-info/RECORD,,

ttyplayer-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.24
+Root-Is-Purelib: true
+Tag: py3-none-any

ttyplayer-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ttyplayer = ttyplayer.cli:main
+

ttyplayer-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weblift SRL
+
+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.