ttyplayer 0.4.0__tar.gz → 0.5.0__tar.gz

{ttyplayer-0.4.0 → ttyplayer-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ttyplayer
-Version: 0.4.0
+Version: 0.5.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
@@ -13,6 +13,8 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Sound/Audio :: Players
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: qrcode>=8
 Requires-Dist: textual>=8.2
 Requires-Dist: typer>=0.27.2
 Requires-Dist: yt-dlp>=2026.8.19
@@ -45,11 +47,14 @@ ttyplayer favorites --remove 2       drop the second favorite as listed
 ttyplayer favorites --clear          forget all favorites
 ttyplayer playlist ...               your own named playlists (see Playlists below)
 ttyplayer tui [--video]              full-screen: search box, results list, now-playing bar
+ttyplayer serve [--host] [--port]    play headless, driven over HTTP from any device (see Server below)
 ttyplayer config                     list the settings (see Settings below)
 ttyplayer doctor                     check Python, yt-dlp, mpv and ttyplayer's folders
 ttyplayer version
 ```
 
+Channels and playlists in search results are skipped; a track that cannot be played is reported and skipped.
+
 While ttyplayer plays in one terminal, any other terminal can drive it:
 
 ```
@@ -148,6 +153,10 @@ ttyplayer keeps its preferences in `~/.config/ttyplayer/settings.toml` (`$XDG_CO
 | `show_clock` | `true` | the clock in the TUI's header |
 | `theme` | `textual-dark` | the TUI's color theme; `t` in the TUI picks the next one and saves it |
 | `search_limit` | `10` | how many results a TUI search fetches, and `m` adds (1–50) |
+| `server_host` | `127.0.0.1` | the address `ttyplayer serve` listens on; `0.0.0.0` opens it to the network |
+| `server_port` | `7700` | the port `ttyplayer serve` listens on (1–65535) |
+| `server_token` | *generated* | the token every API request needs; `ttyplayer serve` makes one on first use |
+| `remote_url` | *none* | the server `ttyplayer tui` drives instead of playing itself, e.g. `http://host:7700` |
 
 ```
 ttyplayer config                     every setting, (default) when unchanged
@@ -158,6 +167,56 @@ ttyplayer config path                where the file is
 
 In the TUI, `S` (or Settings… in Ctrl-P) lists the settings: Enter on a true / false one flips it and saves it (the clock shows or hides at once); the others are set with `ttyplayer config set`.
 
+## Server
+
+`ttyplayer serve` runs the player headless on the machine with the speakers (no keyboard, no TUI) and lets any device on the network drive it through a small HTTP + WebSocket API. The other terminals' `ttyplayer pause`, `next`, `status` and `stop` keep working too.
+
+```
+ttyplayer serve                      listen on 127.0.0.1:7700 (this machine only)
+ttyplayer serve --host 0.0.0.0       listen on every address, so a phone on the LAN can reach it
+ttyplayer serve --port 8000          another port
+```
+
+It prints the address to open, with the token, and a QR code of it for a phone:
+
+```
+Serving ttyplayer at http://192.168.1.20:7700/?token=…
+```
+
+Open that address on a phone and it is a remote: what plays (with a moving progress bar), previous / play-pause / next, a volume slider and mute, a search box (a pasted link plays at once; each result has **Play** and **Queue**), the queue (tap a row to jump there, **×** removes it, **Clear** keeps only what plays), your favorites (the heart on any row adds or drops one) and your playlists. It follows the phone's dark or light mode, reconnects by itself when the server restarts, and "Add to Home Screen" makes it an app icon. The page keeps the token only for that browser tab; opened without one (from the home screen, say) it asks you to paste the token `serve` printed. Ctrl-C (or `ttyplayer stop`, or a `stop` command) stops the server and the player.
+
+Every `/api/…` request and the socket need the token, as `Authorization: Bearer <token>` or `?token=<token>`; without it the reply is `401 {"error": "unauthorized"}`. Replies are JSON; errors are `{"error": "…"}`.
+
+```
+curl -H "Authorization: Bearer $TOKEN" http://host:7700/api/status
+curl -H "Authorization: Bearer $TOKEN" -d '{"query": "lofi beats"}' http://host:7700/api/play
+curl -H "Authorization: Bearer $TOKEN" -d '{"name": "volume", "value": -5}' http://host:7700/api/command
+```
+
+| Method | Path | Body / reply |
+|---|---|---|
+| GET | `/api/status` | the player's status, plus `queue` (the videos) and `index` (1-based) |
+| POST | `/api/play` | `{"url": "…"}` or `{"query": "…"}`: the link's videos, or the first search result, replace the queue and play |
+| POST | `/api/queue` | `{"url": "…"}` or `{"query": "…"}`: appended to the queue (played at once when nothing plays) |
+| POST | `/api/command` | `{"name": "pause"\|"next"\|"prev"\|"stop"\|"mute"\|"seek"\|"volume"\|"jump"\|"remove"\|"move"\|"clear_others", "value"?}`; `seek` and `volume` take a number of seconds / steps, `jump` and `remove` a 0-based queue row, `move` two (`[from, to]`; the current track stays current); `clear_others` keeps only the current track → the new status |
+| GET | `/api/commands` | the command names `/api/command` takes |
+| GET | `/api/search?q=…` | the search results (`search_limit` of them) |
+| GET | `/api/favorites` | the favorites, newest first |
+| POST | `/api/favorites/<id>` | unfavorites that video, or favorites it (the body is the video: `{"title", "uploader", "duration"}`) → the favorites |
+| GET | `/api/playlists` | `[{"name": …, "count": …}]` |
+| POST | `/api/playlists/<name>/play` | that playlist becomes the queue |
+| GET, PATCH | `/api/settings` | every setting but the token; PATCH `{"key": value}` changes and saves them, checked like `config set` |
+| WS | `/ws?token=…` | sends the status on connect and on every change; takes the same `{"name", "value"?}` commands as `/api/command` and answers each with the status |
+| GET | `/` | the web remote (needs no token itself; it reads the token from its address); its files are under `/static/`, plus `/manifest.webmanifest` |
+
+### The TUI as a remote
+
+`ttyplayer tui --remote http://host:7700` opens the same screen, with the same keys and tabs, on another machine (a laptop, say) while the server plays: Enter on a result makes the *server's* speakers play, and the now-playing panel and the Queue tab follow the server over its socket (the header says `remote: host:7700`). The token is the `server_token` setting, so copy it into the laptop's settings with `ttyplayer config set server_token <token>`; `--token <token>` works too, but leaves it in your shell history. `ttyplayer config set remote_url http://host:7700` makes the remote the default, so a plain `ttyplayer tui` drives it.
+
+Searching still happens on the laptop; the server looks each picked video up again before it plays or queues it, so a long queue fills in over a few seconds. History stays the server's: the laptop records nothing. When the server cannot be reached the TUI says so once and keeps trying; a refused token says `Server rejected the token`.
+
+Security: the token is the only gate, and plain HTTP carries it in clear text. That is fine on a home network you trust; it is why `serve` listens on 127.0.0.1 unless told otherwise. To reach it beyond your LAN (a VPS, say), put it behind a reverse proxy with HTTPS. Anyone with the token can control the player, including stopping it; change the token with `ttyplayer config set server_token <new>` and restart.
+
 ## Install
 
 One command installs everything ttyplayer needs.

{ttyplayer-0.4.0 → ttyplayer-0.5.0}/README.md

@@ -22,11 +22,14 @@ ttyplayer favorites --remove 2       drop the second favorite as listed
 ttyplayer favorites --clear          forget all favorites
 ttyplayer playlist ...               your own named playlists (see Playlists below)
 ttyplayer tui [--video]              full-screen: search box, results list, now-playing bar
+ttyplayer serve [--host] [--port]    play headless, driven over HTTP from any device (see Server below)
 ttyplayer config                     list the settings (see Settings below)
 ttyplayer doctor                     check Python, yt-dlp, mpv and ttyplayer's folders
 ttyplayer version
 ```
 
+Channels and playlists in search results are skipped; a track that cannot be played is reported and skipped.
+
 While ttyplayer plays in one terminal, any other terminal can drive it:
 
 ```
@@ -125,6 +128,10 @@ ttyplayer keeps its preferences in `~/.config/ttyplayer/settings.toml` (`$XDG_CO
 | `show_clock` | `true` | the clock in the TUI's header |
 | `theme` | `textual-dark` | the TUI's color theme; `t` in the TUI picks the next one and saves it |
 | `search_limit` | `10` | how many results a TUI search fetches, and `m` adds (1–50) |
+| `server_host` | `127.0.0.1` | the address `ttyplayer serve` listens on; `0.0.0.0` opens it to the network |
+| `server_port` | `7700` | the port `ttyplayer serve` listens on (1–65535) |
+| `server_token` | *generated* | the token every API request needs; `ttyplayer serve` makes one on first use |
+| `remote_url` | *none* | the server `ttyplayer tui` drives instead of playing itself, e.g. `http://host:7700` |
 
 ```
 ttyplayer config                     every setting, (default) when unchanged
@@ -135,6 +142,56 @@ ttyplayer config path                where the file is
 
 In the TUI, `S` (or Settings… in Ctrl-P) lists the settings: Enter on a true / false one flips it and saves it (the clock shows or hides at once); the others are set with `ttyplayer config set`.
 
+## Server
+
+`ttyplayer serve` runs the player headless on the machine with the speakers (no keyboard, no TUI) and lets any device on the network drive it through a small HTTP + WebSocket API. The other terminals' `ttyplayer pause`, `next`, `status` and `stop` keep working too.
+
+```
+ttyplayer serve                      listen on 127.0.0.1:7700 (this machine only)
+ttyplayer serve --host 0.0.0.0       listen on every address, so a phone on the LAN can reach it
+ttyplayer serve --port 8000          another port
+```
+
+It prints the address to open, with the token, and a QR code of it for a phone:
+
+```
+Serving ttyplayer at http://192.168.1.20:7700/?token=…
+```
+
+Open that address on a phone and it is a remote: what plays (with a moving progress bar), previous / play-pause / next, a volume slider and mute, a search box (a pasted link plays at once; each result has **Play** and **Queue**), the queue (tap a row to jump there, **×** removes it, **Clear** keeps only what plays), your favorites (the heart on any row adds or drops one) and your playlists. It follows the phone's dark or light mode, reconnects by itself when the server restarts, and "Add to Home Screen" makes it an app icon. The page keeps the token only for that browser tab; opened without one (from the home screen, say) it asks you to paste the token `serve` printed. Ctrl-C (or `ttyplayer stop`, or a `stop` command) stops the server and the player.
+
+Every `/api/…` request and the socket need the token, as `Authorization: Bearer <token>` or `?token=<token>`; without it the reply is `401 {"error": "unauthorized"}`. Replies are JSON; errors are `{"error": "…"}`.
+
+```
+curl -H "Authorization: Bearer $TOKEN" http://host:7700/api/status
+curl -H "Authorization: Bearer $TOKEN" -d '{"query": "lofi beats"}' http://host:7700/api/play
+curl -H "Authorization: Bearer $TOKEN" -d '{"name": "volume", "value": -5}' http://host:7700/api/command
+```
+
+| Method | Path | Body / reply |
+|---|---|---|
+| GET | `/api/status` | the player's status, plus `queue` (the videos) and `index` (1-based) |
+| POST | `/api/play` | `{"url": "…"}` or `{"query": "…"}`: the link's videos, or the first search result, replace the queue and play |
+| POST | `/api/queue` | `{"url": "…"}` or `{"query": "…"}`: appended to the queue (played at once when nothing plays) |
+| POST | `/api/command` | `{"name": "pause"\|"next"\|"prev"\|"stop"\|"mute"\|"seek"\|"volume"\|"jump"\|"remove"\|"move"\|"clear_others", "value"?}`; `seek` and `volume` take a number of seconds / steps, `jump` and `remove` a 0-based queue row, `move` two (`[from, to]`; the current track stays current); `clear_others` keeps only the current track → the new status |
+| GET | `/api/commands` | the command names `/api/command` takes |
+| GET | `/api/search?q=…` | the search results (`search_limit` of them) |
+| GET | `/api/favorites` | the favorites, newest first |
+| POST | `/api/favorites/<id>` | unfavorites that video, or favorites it (the body is the video: `{"title", "uploader", "duration"}`) → the favorites |
+| GET | `/api/playlists` | `[{"name": …, "count": …}]` |
+| POST | `/api/playlists/<name>/play` | that playlist becomes the queue |
+| GET, PATCH | `/api/settings` | every setting but the token; PATCH `{"key": value}` changes and saves them, checked like `config set` |
+| WS | `/ws?token=…` | sends the status on connect and on every change; takes the same `{"name", "value"?}` commands as `/api/command` and answers each with the status |
+| GET | `/` | the web remote (needs no token itself; it reads the token from its address); its files are under `/static/`, plus `/manifest.webmanifest` |
+
+### The TUI as a remote
+
+`ttyplayer tui --remote http://host:7700` opens the same screen, with the same keys and tabs, on another machine (a laptop, say) while the server plays: Enter on a result makes the *server's* speakers play, and the now-playing panel and the Queue tab follow the server over its socket (the header says `remote: host:7700`). The token is the `server_token` setting, so copy it into the laptop's settings with `ttyplayer config set server_token <token>`; `--token <token>` works too, but leaves it in your shell history. `ttyplayer config set remote_url http://host:7700` makes the remote the default, so a plain `ttyplayer tui` drives it.
+
+Searching still happens on the laptop; the server looks each picked video up again before it plays or queues it, so a long queue fills in over a few seconds. History stays the server's: the laptop records nothing. When the server cannot be reached the TUI says so once and keeps trying; a refused token says `Server rejected the token`.
+
+Security: the token is the only gate, and plain HTTP carries it in clear text. That is fine on a home network you trust; it is why `serve` listens on 127.0.0.1 unless told otherwise. To reach it beyond your LAN (a VPS, say), put it behind a reverse proxy with HTTPS. Anyone with the token can control the player, including stopping it; change the token with `ttyplayer config set server_token <new>` and restart.
+
 ## Install
 
 One command installs everything ttyplayer needs.

{ttyplayer-0.4.0 → ttyplayer-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ttyplayer"
-version = "0.4.0"
+version = "0.5.0"
 description = "ttyplayer: a modern YouTube player for the terminal — search, queue, and play audio or video via mpv"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -27,6 +27,8 @@ classifiers = [
     "Topic :: Multimedia :: Sound/Audio :: Players",
 ]
 dependencies = [
+    "aiohttp>=3.10",
+    "qrcode>=8",
     "textual>=8.2",
     "typer>=0.27.2",
     "yt-dlp>=2026.8.19",

{ttyplayer-0.4.0 → ttyplayer-0.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ttyplayer"
-version = "0.4.0"
+version = "0.5.0"
 description = "ttyplayer: a modern YouTube player for the terminal — search, queue, and play audio or video via mpv"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -18,6 +18,8 @@ classifiers = [
     "Topic :: Multimedia :: Sound/Audio :: Players",
 ]
 dependencies = [
+    "aiohttp>=3.10",
+    "qrcode>=8",
     "textual>=8.2",
     "typer>=0.27.2",
     "yt-dlp>=2026.8.19",

{ttyplayer-0.4.0 → ttyplayer-0.5.0}/src/ttyplayer/cli.py

@@ -1,6 +1,7 @@
 import os
 import random
 import shutil
+import signal
 import subprocess
 import sys
 import tempfile
@@ -192,18 +193,83 @@ def favorites_command(
 
 
 @app.command()
-def tui(video: bool = False):
+def tui(
+    video: bool = False,
+    remote_url: str = typer.Option("", "--remote", help="Drive the ttyplayer serve at this URL (default: remote_url)"),
+    token: str = typer.Option("", help="The server's token (default: server_token)"),
+):
     """Open the full-screen player: search, pick and play in one screen.
 
     Keys: / search, Enter play, a add to queue, f favorite, m more results,
     space pause, , . seek 5s, < > seek 30s, - + volume, M mute, n next,
     p previous, 1-4 tabs, t theme, ? help, Ctrl-P commands, q quit.
+
+    With --remote (or the remote_url setting) the server plays and this screen drives it.
     """
     from ttyplayer import tui as screen  # Textual loads only for this command
 
-    screen.TtyplayerApp(
-        client_factory=player.MpvClient, resolve=screen.resolve, video=video, settings=load_settings()
-    ).run()
+    current = load_settings()
+    url = remote_url or current.remote_url
+    if url:
+        from ttyplayer.remote import RemoteApp  # aiohttp loads only for a remote
+
+        ui = RemoteApp(url, token or current.server_token, resolve=screen.resolve, video=video, settings=current)
+    else:
+        ui = screen.TtyplayerApp(client_factory=player.MpvClient, resolve=screen.resolve, video=video, settings=current)
+    ui.run()
+
+
+@app.command()
+def serve(host: str | None = None, port: int | None = None):
+    """Play headless and take commands over HTTP and WebSocket, gated by a token.
+
+    Prints the address to open (with its token) and a QR code of it; Ctrl-C stops.
+    """
+    from ttyplayer import server  # aiohttp loads only for this command
+
+    try:
+        current = server.ensure_token(load_settings())
+    except settings.SettingsError as error:
+        fail(str(error))
+    host = host or current.server_host
+    port = port or current.server_port
+    hub = server.Broadcaster()
+    client = start_mpv(False, on_state=hub)
+    remote = control.serve(client.handle_control)
+    try:
+        web = server.ServerThread(server.make_app(client, current, hub), host, port)
+    except OSError as error:
+        stop_serving(None, remote, client)
+        fail(f"Cannot serve on {host}:{port}: {error.strerror or error}")
+    address = server.url(host, port, current.server_token)
+    typer.echo(f"Serving ttyplayer at {address}")
+    print_qr(address)
+    old_handler = signal.signal(signal.SIGTERM, signal.default_int_handler)  # a kill stops it like Ctrl-C
+    try:
+        while True:
+            time.sleep(3600)  # Ctrl-C, SIGTERM and `stop` all land here as KeyboardInterrupt
+    except KeyboardInterrupt:
+        pass
+    finally:
+        signal.signal(signal.SIGTERM, old_handler)
+        stop_serving(web, remote, client)
+
+
+def stop_serving(web, remote, client):
+    """Stop the HTTP server (None if it never started), then remote control, then mpv."""
+    if web:
+        web.stop()
+    if remote:
+        remote.stop()
+    client.quit()
+
+
+def print_qr(text):
+    import qrcode
+
+    code = qrcode.QRCode(border=1)
+    code.add_data(text)
+    code.print_ascii()
 
 
 @config_app.callback(invoke_without_command=True)
@@ -454,16 +520,21 @@ def show_more(videos, more):
 
 def start_playback(videos, with_video):
     exit_if_empty(videos)
+    client = start_mpv(with_video)
+    for video in videos:
+        client.add(video)
+    client.play_current()
+    client.run()
+
+
+def start_mpv(with_video, on_state=None):
+    """An MpvClient that keeps history, or a one-line message and exit 1 when mpv cannot start."""
     try:
-        client = player.MpvClient(with_video, on_play=history.record)
+        return player.MpvClient(with_video, on_play=history.record, on_state=on_state)
     except FileNotFoundError:
         fail(f"mpv is not installed. {mpv_install_hint()}")
     except RuntimeError as error:
         fail(str(error))
-    for video in videos:
-        client.add(video)
-    client.play_current()
-    client.run()
 
 
 def print_videos(videos, start=1):

{ttyplayer-0.4.0 → ttyplayer-0.5.0}/src/ttyplayer/player.py

@@ -230,6 +230,8 @@ class MpvClient:
     loaded_at = None  # monotonic time of the last loadfile, until playback restarts
     started_in = None
     idle = True  # nothing loaded: before the first track, after the queue ran out
+    shown_error = None  # the error render() printed last
+    error = None  # "Could not play <title>: <reason>" for the last track mpv failed to load, until one starts
     request_id = 0  # of the last command sent
     poller = None
     volume_writer = None  # macOS only
@@ -318,9 +320,11 @@ class MpvClient:
         elif message.get("event") == "end-file" and message.get("reason") == "eof":
             # At the end of the queue this still notifies, to tell a UI it went idle.
             self._edit(self._next_or_idle)
+        elif message.get("event") == "end-file" and message.get("reason") == "error":
+            self._edit(self._skip_failed, message.get("file_error") or "unavailable")
 
     def _mark_started(self):
-        """Store started_in on the first restart after a loadfile; later ones are seeks.
+        """Store started_in, and clear error, on the first restart after a loadfile; later ones are seeks.
 
         Under queue_lock, so a track change can't land between reading the clock and
         reading the stamp it is measured from.
@@ -330,6 +334,7 @@ class MpvClient:
                 return False
             self.started_in = round(time.monotonic() - self.loaded_at, 1)
             self.loaded_at = None
+            self.error = None
             return True
 
     def poll_volume(self):
@@ -495,6 +500,7 @@ class MpvClient:
         self.send(["loadfile", url])
 
     def play_current(self):
+        self.error = None
         self._move(0)
 
     def next(self):
@@ -555,6 +561,11 @@ class MpvClient:
             self.idle = True
         return True
 
+    def _skip_failed(self, reason):
+        """Record why the current track failed to load, then move on as at its end."""
+        self.error = f"Could not play {self.current_title()}: {reason}"
+        return self._next_or_idle()
+
     def _remove(self, index):
         if not 0 <= index < len(self.queue):
             return False
@@ -642,6 +653,7 @@ class MpvClient:
             "up_next": self.up_next(),
             "started_in": self.started_in,
             "idle": self.idle,
+            "error": self.error,
         }
 
     def notify(self):
@@ -653,6 +665,10 @@ class MpvClient:
 
     def render(self):
         status = self.status()
+        if status["error"] and status["error"] != self.shown_error:
+            # One line of its own above the status line, which redraws below it.
+            print(f"\r{status['error']}\x1b[K", file=sys.stderr, flush=True)
+        self.shown_error = status["error"]
         line = status_line(status)
         if status["total"] > 1:
             up_next = status["up_next"]