ttyplayer 0.5.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ttyplayer
-Version: 0.5.0
+Version: 0.7.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
@@ -35,8 +35,10 @@ 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 play ... --source soundcloud   search SoundCloud instead of YouTube
 
 ttyplayer search <words...>          list results with durations
+ttyplayer search --source soundcloud <words...>   the same, on SoundCloud
 ttyplayer history                    recently played, newest first
 ttyplayer history --play             pick from history and play again
 ttyplayer history --clear            forget the history
@@ -46,15 +48,19 @@ 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.
 
+Search looks on YouTube or SoundCloud. `--source soundcloud` (on `play`, `search` and `playlist add`) picks SoundCloud for one search; `ttyplayer config set search_source soundcloud` makes it the default everywhere. SoundCloud rows carry an `SC` tag in every list, and history, favorites and playlists keep their SoundCloud link. Links from any site yt-dlp knows play as they are.
+
 While ttyplayer plays in one terminal, any other terminal can drive it:
 
 ```
@@ -62,9 +68,14 @@ ttyplayer pause                      pause / resume
 ttyplayer next                       next in the queue
 ttyplayer prev                       previous in the queue
 ttyplayer stop                       quit the player
+ttyplayer sleep 30m                  Sleeping in 30:00 (also 1h, 1h30m, 90 seconds)
+ttyplayer sleep end                  stop when the current track ends
+ttyplayer sleep off                  cancel it (no argument: show it)
 ttyplayer status                     1:23 / 4:56  Playing  <title>
 ```
 
+When the sleep timer runs out, the volume fades to nothing over 5 seconds and the player stops as if `q` was pressed; the volume is put back first, so the next play starts at the old level. Paused or idle, it stops at once. `ttyplayer status`, the TUI and the web remote show `zz 27:13` (or `zz end`) while a timer is armed.
+
 ## Playlists
 
 Playlists are named lists you keep, in the order you choose, separate from history and favorites. A name is 1 to 40 letters, digits, spaces, `_` or `-`.
@@ -102,9 +113,32 @@ 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.
+`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; start the search with `sc:` (`sc: boards of canada`) to search SoundCloud, or `yt:` for YouTube, whatever `search_source` says. The Search tab's heading then reads `SoundCloud results` or `YouTube results`. Ctrl-P opens the command palette (search, playlists, save queue as playlist, next theme, settings, help, quit, pause, next, previous, mute, sleep, and Textual's own theme picker); **Sleep…** asks for a sleep timer (`30m` filled in; `end`, `off`, `1h30m`, … work as on the command line; Esc leaves the timer alone); `?` 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 |
 |---|---|---|
@@ -157,6 +191,10 @@ ttyplayer keeps its preferences in `~/.config/ttyplayer/settings.toml` (`$XDG_CO
 | `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 |
+| `search_source` | `youtube` | where a search looks: `youtube` or `soundcloud`; `--source` and the TUI's `sc:` / `yt:` prefix override it once |
 
 ```
 ttyplayer config                     every setting, (default) when unchanged
@@ -165,7 +203,7 @@ 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
 
@@ -175,6 +213,7 @@ In the TUI, `S` (or Settings… in Ctrl-P) lists the settings: Enter on a true /
 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:
@@ -198,7 +237,7 @@ curl -H "Authorization: Bearer $TOKEN" -d '{"name": "volume", "value": -5}' http
 | 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 |
+| POST | `/api/command` | `{"name": "pause"\|"next"\|"prev"\|"stop"\|"mute"\|"sleep"\|"seek"\|"volume"\|"jump"\|"remove"\|"move"\|"clear_others", "value"?}`; `sleep` takes the text `ttyplayer sleep` does (`"30m"`, `"end"`, `"off"`), `seek` and `volume` 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 |
@@ -207,8 +246,29 @@ curl -H "Authorization: Bearer $TOKEN" -d '{"name": "volume", "value": -5}' http
 | 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.

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

@@ -10,8 +10,10 @@ 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 play ... --source soundcloud   search SoundCloud instead of YouTube
 
 ttyplayer search <words...>          list results with durations
+ttyplayer search --source soundcloud <words...>   the same, on SoundCloud
 ttyplayer history                    recently played, newest first
 ttyplayer history --play             pick from history and play again
 ttyplayer history --clear            forget the history
@@ -21,15 +23,19 @@ 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.
 
+Search looks on YouTube or SoundCloud. `--source soundcloud` (on `play`, `search` and `playlist add`) picks SoundCloud for one search; `ttyplayer config set search_source soundcloud` makes it the default everywhere. SoundCloud rows carry an `SC` tag in every list, and history, favorites and playlists keep their SoundCloud link. Links from any site yt-dlp knows play as they are.
+
 While ttyplayer plays in one terminal, any other terminal can drive it:
 
 ```
@@ -37,9 +43,14 @@ ttyplayer pause                      pause / resume
 ttyplayer next                       next in the queue
 ttyplayer prev                       previous in the queue
 ttyplayer stop                       quit the player
+ttyplayer sleep 30m                  Sleeping in 30:00 (also 1h, 1h30m, 90 seconds)
+ttyplayer sleep end                  stop when the current track ends
+ttyplayer sleep off                  cancel it (no argument: show it)
 ttyplayer status                     1:23 / 4:56  Playing  <title>
 ```
 
+When the sleep timer runs out, the volume fades to nothing over 5 seconds and the player stops as if `q` was pressed; the volume is put back first, so the next play starts at the old level. Paused or idle, it stops at once. `ttyplayer status`, the TUI and the web remote show `zz 27:13` (or `zz end`) while a timer is armed.
+
 ## Playlists
 
 Playlists are named lists you keep, in the order you choose, separate from history and favorites. A name is 1 to 40 letters, digits, spaces, `_` or `-`.
@@ -77,9 +88,32 @@ 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.
+`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; start the search with `sc:` (`sc: boards of canada`) to search SoundCloud, or `yt:` for YouTube, whatever `search_source` says. The Search tab's heading then reads `SoundCloud results` or `YouTube results`. Ctrl-P opens the command palette (search, playlists, save queue as playlist, next theme, settings, help, quit, pause, next, previous, mute, sleep, and Textual's own theme picker); **Sleep…** asks for a sleep timer (`30m` filled in; `end`, `off`, `1h30m`, … work as on the command line; Esc leaves the timer alone); `?` 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 |
 |---|---|---|
@@ -132,6 +166,10 @@ ttyplayer keeps its preferences in `~/.config/ttyplayer/settings.toml` (`$XDG_CO
 | `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 |
+| `search_source` | `youtube` | where a search looks: `youtube` or `soundcloud`; `--source` and the TUI's `sc:` / `yt:` prefix override it once |
 
 ```
 ttyplayer config                     every setting, (default) when unchanged
@@ -140,7 +178,7 @@ 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
 
@@ -150,6 +188,7 @@ In the TUI, `S` (or Settings… in Ctrl-P) lists the settings: Enter on a true /
 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:
@@ -173,7 +212,7 @@ curl -H "Authorization: Bearer $TOKEN" -d '{"name": "volume", "value": -5}' http
 | 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 |
+| POST | `/api/command` | `{"name": "pause"\|"next"\|"prev"\|"stop"\|"mute"\|"sleep"\|"seek"\|"volume"\|"jump"\|"remove"\|"move"\|"clear_others", "value"?}`; `sleep` takes the text `ttyplayer sleep` does (`"30m"`, `"end"`, `"off"`), `seek` and `volume` 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 |
@@ -182,8 +221,29 @@ curl -H "Authorization: Bearer $TOKEN" -d '{"name": "volume", "value": -5}' http
 | 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.

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

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

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

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