ttyplayer 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ttyplayer
-Version: 0.4.0
+Version: 0.6.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
@@ -44,12 +46,17 @@ 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 playlist ...               your own named playlists (see Playlists below)
+ttyplayer spotify ...                bring Spotify playlists over, found on YouTube (see Spotify 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 serve --stream             the same, but the sound goes to the web remote, not the speakers
 ttyplayer config                     list the settings (see Settings below)
-ttyplayer doctor                     check Python, yt-dlp, mpv and ttyplayer's folders
+ttyplayer doctor                     check Python, yt-dlp, mpv, ffmpeg (optional) 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:
 
 ```
@@ -97,10 +104,33 @@ Picks accept several numbers at once: `1 3 5` queues those three in that order.
 
 `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.
 
+## Spotify
+
+ttyplayer can bring a Spotify playlist over as one of its own playlists. It reads only the playlist's *track list* from Spotify, never its audio (Spotify's audio is DRM-protected): each track is searched on YouTube as `<first artist> <title>`, and the first hit is added. A track YouTube has no hit for is reported and skipped; local files and podcast episodes in the playlist are skipped too. The result is a normal playlist: `ttyplayer playlist play <name>`, or the Playlists tab in the TUI.
+
+```
+ttyplayer spotify login                                      log in to Spotify in the browser, once
+ttyplayer spotify playlists                                  your Spotify playlists: name, tracks, id
+ttyplayer spotify import <link | id> [--as <name>] [--limit N]  find each track on YouTube and save it
+```
+
+`import` takes a playlist link (`https://open.spotify.com/playlist/<id>`), a `spotify:playlist:<id>` URI, or the bare id. It names the playlist after the Spotify one (unless `--as`), creating it, or appending to it if one by that name exists; it prints `[3/40] ✓ Artist – Title → <YouTube title>` (or `✗ … not found`) per track, and `Saved N of M tracks to <name>` at the end. Each YouTube search takes a second or two, so a long playlist takes a while; `--limit N` imports only the first N tracks. If the network fails part way, what was saved stays saved.
+
+Logging in needs a Spotify app of your own (free, once):
+
+1. Open the [Spotify developer dashboard](https://developer.spotify.com/dashboard), log in, and press **Create app**.
+2. Give it any name and description, set the **Redirect URI** to exactly `http://127.0.0.1:8765/callback`, tick **Web API**, and save.
+3. Open the app's **Settings**, copy its **Client ID**, and run `ttyplayer config set spotify_client_id <client id>`.
+4. Run `ttyplayer spotify login`: the browser opens Spotify's consent page; approve it, and the terminal says `Logged in as <your name>`.
+
+ttyplayer asks only for read access to your playlists (`playlist-read-private playlist-read-collaborative`) and uses no client secret (the login is OAuth with PKCE). The login is kept in `spotify.json` next to `settings.toml`, readable only by you; it holds a refresh token, so treat it like a password. To revoke ttyplayer's access, remove the app under **Manage apps** on your Spotify account page (spotify.com/account/apps) and delete `spotify.json`.
+
 ## TUI
 
 `ttyplayer tui` opens a full-screen player: a search box, Search / Queue / History / Favorites / Playlists tabs, and a now-playing panel. Type a search or paste a link and press Enter. Ctrl-P opens the command palette (search, playlists, save queue as playlist, next theme, settings, help, quit, pause, next, previous, mute, and Textual's own theme picker); `?` lists every key and command.
 
+Under the volume, the panel's level meter shows two bars, `L` and `R`, that follow the sound's peaks about ten times a second (empty at −60 dBFS and below, full at 0 dBFS; empty while paused). `ttyplayer config set show_levels false`, or Enter on `show_levels` in the Settings screen, hides them and takes mpv's measuring filter out.
+
 | Where | Key | Action |
 |---|---|---|
 | table | `↑` / `↓` | move through the list (volume is `-` / `+`) |
@@ -148,6 +178,13 @@ 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` |
+| `stream_enabled` | `false` | `ttyplayer serve` streams the sound to the web remote instead of playing it, as `--stream` does |
+| `spotify_client_id` | *none* | the Client ID of your own Spotify app, which `ttyplayer spotify login` needs (see Spotify above) |
+| `show_levels` | `true` | the TUI's level meter: mpv measures the sound's peaks and the now-playing panel shows them |
 
 ```
 ttyplayer config                     every setting, (default) when unchanged
@@ -156,7 +193,79 @@ ttyplayer config set <key> <value>   change it: ttyplayer config set show_clock
 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`.
+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 and the level meter show or hide 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
+ttyplayer serve --stream             no sound here: Listen here on the web remote plays it (see below)
+```
+
+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 | `/stream` | with `serve --stream`: the sound as an `audio/ogg` (Opus) stream, for as long as the client listens; 404 otherwise |
+| GET | `/` | the web remote (needs no token itself; it reads the token from its address); its files are under `/static/`, plus `/manifest.webmanifest` |
+
+### Listen on another device
+
+`ttyplayer serve --stream` is the "music box on a server" mode, for a machine with no speakers of its own (a Raspberry Pi, a VPS, a closet PC): nothing plays on the server; the web remote gets a **Listen here** button that plays what the server plays, in that browser, on any device. Press it again (**Stop listening**) to stop. Several devices can listen at once; one on a bad connection skips, the others do not. Pausing and changing tracks keep the stream open (you hear silence in between). What you hear runs a little behind the remote's controls: the server adds about half a second, the browser its own buffer. `ttyplayer config set stream_enabled true` makes it the default for `serve`.
+
+```
+ttyplayer serve --stream --host 0.0.0.0
+```
+
+It needs ffmpeg, which nothing else in ttyplayer does (`ttyplayer doctor` shows whether it is there), and runs on macOS and Linux, not Windows:
+
+| System | Install ffmpeg |
+|---|---|
+| macOS | `brew install ffmpeg` |
+| Debian, Ubuntu, Raspberry Pi OS | `sudo apt-get install -y ffmpeg` |
+| Fedora | `sudo dnf install -y ffmpeg-free` |
+| Arch | `sudo pacman -S --noconfirm ffmpeg` |
+| Alpine | `sudo apk add ffmpeg` |
+
+The stream is gated by the same token as the API and is plain HTTP; the security notes below apply to it too.
+
+### 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
 

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

@@ -21,12 +21,17 @@ 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 playlist ...               your own named playlists (see Playlists below)
+ttyplayer spotify ...                bring Spotify playlists over, found on YouTube (see Spotify 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 serve --stream             the same, but the sound goes to the web remote, not the speakers
 ttyplayer config                     list the settings (see Settings below)
-ttyplayer doctor                     check Python, yt-dlp, mpv and ttyplayer's folders
+ttyplayer doctor                     check Python, yt-dlp, mpv, ffmpeg (optional) 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:
 
 ```
@@ -74,10 +79,33 @@ Picks accept several numbers at once: `1 3 5` queues those three in that order.
 
 `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.
 
+## Spotify
+
+ttyplayer can bring a Spotify playlist over as one of its own playlists. It reads only the playlist's *track list* from Spotify, never its audio (Spotify's audio is DRM-protected): each track is searched on YouTube as `<first artist> <title>`, and the first hit is added. A track YouTube has no hit for is reported and skipped; local files and podcast episodes in the playlist are skipped too. The result is a normal playlist: `ttyplayer playlist play <name>`, or the Playlists tab in the TUI.
+
+```
+ttyplayer spotify login                                      log in to Spotify in the browser, once
+ttyplayer spotify playlists                                  your Spotify playlists: name, tracks, id
+ttyplayer spotify import <link | id> [--as <name>] [--limit N]  find each track on YouTube and save it
+```
+
+`import` takes a playlist link (`https://open.spotify.com/playlist/<id>`), a `spotify:playlist:<id>` URI, or the bare id. It names the playlist after the Spotify one (unless `--as`), creating it, or appending to it if one by that name exists; it prints `[3/40] ✓ Artist – Title → <YouTube title>` (or `✗ … not found`) per track, and `Saved N of M tracks to <name>` at the end. Each YouTube search takes a second or two, so a long playlist takes a while; `--limit N` imports only the first N tracks. If the network fails part way, what was saved stays saved.
+
+Logging in needs a Spotify app of your own (free, once):
+
+1. Open the [Spotify developer dashboard](https://developer.spotify.com/dashboard), log in, and press **Create app**.
+2. Give it any name and description, set the **Redirect URI** to exactly `http://127.0.0.1:8765/callback`, tick **Web API**, and save.
+3. Open the app's **Settings**, copy its **Client ID**, and run `ttyplayer config set spotify_client_id <client id>`.
+4. Run `ttyplayer spotify login`: the browser opens Spotify's consent page; approve it, and the terminal says `Logged in as <your name>`.
+
+ttyplayer asks only for read access to your playlists (`playlist-read-private playlist-read-collaborative`) and uses no client secret (the login is OAuth with PKCE). The login is kept in `spotify.json` next to `settings.toml`, readable only by you; it holds a refresh token, so treat it like a password. To revoke ttyplayer's access, remove the app under **Manage apps** on your Spotify account page (spotify.com/account/apps) and delete `spotify.json`.
+
 ## TUI
 
 `ttyplayer tui` opens a full-screen player: a search box, Search / Queue / History / Favorites / Playlists tabs, and a now-playing panel. Type a search or paste a link and press Enter. Ctrl-P opens the command palette (search, playlists, save queue as playlist, next theme, settings, help, quit, pause, next, previous, mute, and Textual's own theme picker); `?` lists every key and command.
 
+Under the volume, the panel's level meter shows two bars, `L` and `R`, that follow the sound's peaks about ten times a second (empty at −60 dBFS and below, full at 0 dBFS; empty while paused). `ttyplayer config set show_levels false`, or Enter on `show_levels` in the Settings screen, hides them and takes mpv's measuring filter out.
+
 | Where | Key | Action |
 |---|---|---|
 | table | `↑` / `↓` | move through the list (volume is `-` / `+`) |
@@ -125,6 +153,13 @@ 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` |
+| `stream_enabled` | `false` | `ttyplayer serve` streams the sound to the web remote instead of playing it, as `--stream` does |
+| `spotify_client_id` | *none* | the Client ID of your own Spotify app, which `ttyplayer spotify login` needs (see Spotify above) |
+| `show_levels` | `true` | the TUI's level meter: mpv measures the sound's peaks and the now-playing panel shows them |
 
 ```
 ttyplayer config                     every setting, (default) when unchanged
@@ -133,7 +168,79 @@ ttyplayer config set <key> <value>   change it: ttyplayer config set show_clock
 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`.
+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 and the level meter show or hide 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
+ttyplayer serve --stream             no sound here: Listen here on the web remote plays it (see below)
+```
+
+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 | `/stream` | with `serve --stream`: the sound as an `audio/ogg` (Opus) stream, for as long as the client listens; 404 otherwise |
+| GET | `/` | the web remote (needs no token itself; it reads the token from its address); its files are under `/static/`, plus `/manifest.webmanifest` |
+
+### Listen on another device
+
+`ttyplayer serve --stream` is the "music box on a server" mode, for a machine with no speakers of its own (a Raspberry Pi, a VPS, a closet PC): nothing plays on the server; the web remote gets a **Listen here** button that plays what the server plays, in that browser, on any device. Press it again (**Stop listening**) to stop. Several devices can listen at once; one on a bad connection skips, the others do not. Pausing and changing tracks keep the stream open (you hear silence in between). What you hear runs a little behind the remote's controls: the server adds about half a second, the browser its own buffer. `ttyplayer config set stream_enabled true` makes it the default for `serve`.
+
+```
+ttyplayer serve --stream --host 0.0.0.0
+```
+
+It needs ffmpeg, which nothing else in ttyplayer does (`ttyplayer doctor` shows whether it is there), and runs on macOS and Linux, not Windows:
+
+| System | Install ffmpeg |
+|---|---|
+| macOS | `brew install ffmpeg` |
+| Debian, Ubuntu, Raspberry Pi OS | `sudo apt-get install -y ffmpeg` |
+| Fedora | `sudo dnf install -y ffmpeg-free` |
+| Arch | `sudo pacman -S --noconfirm ffmpeg` |
+| Alpine | `sudo apk add ffmpeg` |
+
+The stream is gated by the same token as the API and is plain HTTP; the security notes below apply to it too.
+
+### 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
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "ttyplayer"
-version = "0.4.0"
+version = "0.6.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.6.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ttyplayer"
-version = "0.4.0"
+version = "0.6.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",