ttyplayer 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ttyplayer
-Version: 0.3.1
+Version: 0.4.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
@@ -43,7 +43,9 @@ 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 playlist ...               your own named playlists (see Playlists below)
 ttyplayer tui [--video]              full-screen: search box, results list, now-playing bar
+ttyplayer config                     list the settings (see Settings below)
 ttyplayer doctor                     check Python, yt-dlp, mpv and ttyplayer's folders
 ttyplayer version
 ```
@@ -58,6 +60,25 @@ ttyplayer stop                       quit the player
 ttyplayer status                     1:23 / 4:56  Playing  <title>
 ```
 
+## 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 `-`.
+
+```
+ttyplayer playlist list                          every playlist and how many videos it holds
+ttyplayer playlist show <name>                   its videos, numbered
+ttyplayer playlist create <name>                 a new, empty playlist
+ttyplayer playlist add <name> <url | words...>   append a link, every entry of a playlist link, or search picks
+ttyplayer playlist remove <name> 3               drop the third video
+ttyplayer playlist move <name> 3 1               move the third video to the top
+ttyplayer playlist delete <name> [--yes]         delete it (asks first unless --yes)
+ttyplayer playlist play <name> [--video] [--shuffle]   queue the whole playlist, in order or shuffled
+ttyplayer playlist import <playlist url> [--as <name>] save a YouTube playlist, named after its title
+ttyplayer playlist save-queue <name>             save what the playing ttyplayer has queued, replacing <name>
+```
+
+`save-queue` works from another terminal while ttyplayer plays, like `pause` and `status`; it creates the playlist if there is none by that name. `import` refuses a name that is already taken; give another with `--as`.
+
 Keys in `ttyplayer play` (the terminal player; `ttyplayer tui` has its own table below):
 
 | Key | Action |
@@ -78,17 +99,19 @@ Picks accept several numbers at once: `1 3 5` queues those three in that order.
 
 ## 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.
+`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.
 
 | Where | Key | Action |
 |---|---|---|
 | table | `↑` / `↓` | move through the list (volume is `-` / `+`) |
 | 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 | `1` `2` `3` `4` `5` | Search / Queue / History / Favorites / Playlists tab |
 | anywhere | Ctrl-C | quit and stop mpv |
 | anywhere | Ctrl-P | command palette |
-| anywhere | `t` | next theme |
+| anywhere | `t` | next theme (remembered for next time) |
+| table | `P` | save the queue as a playlist (asks for a name; an existing playlist of that name is replaced) |
+| table | `S` | settings: Enter flips a true / false one, `esc` closes |
 | table | `q` | quit and stop mpv (in the search box it is just a letter) |
 | table | `space` | pause / resume |
 | table | `n` / `p` | next / previous |
@@ -99,15 +122,42 @@ Picks accept several numbers at once: `1 3 5` queues those three in that order.
 | 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 · History · Favorites · Queue row | `A` | add to a playlist (pick one, or New playlist…) |
 | 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 |
+| Playlists | Enter | open the playlist (`esc` or Backspace goes back to the list) |
+| Playlists | `d` | delete the playlist (asks first: `y` or Enter deletes, `esc` keeps it) |
+| playlist track | Enter | play the whole playlist from this track |
+| playlist track | `a` | add to the queue |
+| playlist track | `d` | remove from the playlist |
+| playlist track | `K` / `J` (or `shift+↑` / `shift+↓`) | move up / down in the playlist |
+| open playlist | `s` | shuffle-play the playlist |
 
 In the search box, letters, digits, `/` and `?` are typed as text; `esc` leaves it for the table.
 
+## Settings
+
+ttyplayer keeps its preferences in `~/.config/ttyplayer/settings.toml` (`$XDG_CONFIG_HOME/ttyplayer/` when that is set, `%APPDATA%\ttyplayer\` on Windows). Every key is optional; a missing file means the defaults.
+
+| Key | Default | What it does |
+|---|---|---|
+| `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) |
+
+```
+ttyplayer config                     every setting, (default) when unchanged
+ttyplayer config get <key>           one setting's value
+ttyplayer config set <key> <value>   change it: ttyplayer config set show_clock false
+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`.
+
 ## Install
 
 One command installs everything ttyplayer needs.
@@ -200,7 +250,7 @@ uv run pytest -q                                      # default suite, live test
 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.
+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`, and each playlist in `playlists/<name>.jsonl`. History and favorites kept under the player's earlier name are moved here on the first run.
 
 ### Releasing
 

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

@@ -20,7 +20,9 @@ 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 playlist ...               your own named playlists (see Playlists below)
 ttyplayer tui [--video]              full-screen: search box, results list, now-playing bar
+ttyplayer config                     list the settings (see Settings below)
 ttyplayer doctor                     check Python, yt-dlp, mpv and ttyplayer's folders
 ttyplayer version
 ```
@@ -35,6 +37,25 @@ ttyplayer stop                       quit the player
 ttyplayer status                     1:23 / 4:56  Playing  <title>
 ```
 
+## 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 `-`.
+
+```
+ttyplayer playlist list                          every playlist and how many videos it holds
+ttyplayer playlist show <name>                   its videos, numbered
+ttyplayer playlist create <name>                 a new, empty playlist
+ttyplayer playlist add <name> <url | words...>   append a link, every entry of a playlist link, or search picks
+ttyplayer playlist remove <name> 3               drop the third video
+ttyplayer playlist move <name> 3 1               move the third video to the top
+ttyplayer playlist delete <name> [--yes]         delete it (asks first unless --yes)
+ttyplayer playlist play <name> [--video] [--shuffle]   queue the whole playlist, in order or shuffled
+ttyplayer playlist import <playlist url> [--as <name>] save a YouTube playlist, named after its title
+ttyplayer playlist save-queue <name>             save what the playing ttyplayer has queued, replacing <name>
+```
+
+`save-queue` works from another terminal while ttyplayer plays, like `pause` and `status`; it creates the playlist if there is none by that name. `import` refuses a name that is already taken; give another with `--as`.
+
 Keys in `ttyplayer play` (the terminal player; `ttyplayer tui` has its own table below):
 
 | Key | Action |
@@ -55,17 +76,19 @@ Picks accept several numbers at once: `1 3 5` queues those three in that order.
 
 ## 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.
+`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.
 
 | Where | Key | Action |
 |---|---|---|
 | table | `↑` / `↓` | move through the list (volume is `-` / `+`) |
 | 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 | `1` `2` `3` `4` `5` | Search / Queue / History / Favorites / Playlists tab |
 | anywhere | Ctrl-C | quit and stop mpv |
 | anywhere | Ctrl-P | command palette |
-| anywhere | `t` | next theme |
+| anywhere | `t` | next theme (remembered for next time) |
+| table | `P` | save the queue as a playlist (asks for a name; an existing playlist of that name is replaced) |
+| table | `S` | settings: Enter flips a true / false one, `esc` closes |
 | table | `q` | quit and stop mpv (in the search box it is just a letter) |
 | table | `space` | pause / resume |
 | table | `n` / `p` | next / previous |
@@ -76,15 +99,42 @@ Picks accept several numbers at once: `1 3 5` queues those three in that order.
 | 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 · History · Favorites · Queue row | `A` | add to a playlist (pick one, or New playlist…) |
 | 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 |
+| Playlists | Enter | open the playlist (`esc` or Backspace goes back to the list) |
+| Playlists | `d` | delete the playlist (asks first: `y` or Enter deletes, `esc` keeps it) |
+| playlist track | Enter | play the whole playlist from this track |
+| playlist track | `a` | add to the queue |
+| playlist track | `d` | remove from the playlist |
+| playlist track | `K` / `J` (or `shift+↑` / `shift+↓`) | move up / down in the playlist |
+| open playlist | `s` | shuffle-play the playlist |
 
 In the search box, letters, digits, `/` and `?` are typed as text; `esc` leaves it for the table.
 
+## Settings
+
+ttyplayer keeps its preferences in `~/.config/ttyplayer/settings.toml` (`$XDG_CONFIG_HOME/ttyplayer/` when that is set, `%APPDATA%\ttyplayer\` on Windows). Every key is optional; a missing file means the defaults.
+
+| Key | Default | What it does |
+|---|---|---|
+| `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) |
+
+```
+ttyplayer config                     every setting, (default) when unchanged
+ttyplayer config get <key>           one setting's value
+ttyplayer config set <key> <value>   change it: ttyplayer config set show_clock false
+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`.
+
 ## Install
 
 One command installs everything ttyplayer needs.
@@ -177,7 +227,7 @@ uv run pytest -q                                      # default suite, live test
 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.
+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`, and each playlist in `playlists/<name>.jsonl`. History and favorites kept under the player's earlier name are moved here on the first run.
 
 ### Releasing
 

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "ttyplayer"
-version = "0.3.1"
+version = "0.4.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.3.1 → ttyplayer-0.4.0}/src/ttyplayer/cli.py

@@ -1,4 +1,5 @@
 import os
+import random
 import shutil
 import subprocess
 import sys
@@ -8,10 +9,16 @@ from importlib import metadata
 
 import typer
 
-from ttyplayer import control, favorites, history, player
-from ttyplayer.utils import APP_NAME, data_path, format_time, parse_picks, unseen
+from ttyplayer import control, favorites, history, player, playlists, settings
+from ttyplayer.utils import APP_NAME, data_path, format_time, parse_picks, unseen, video_from_info
 
 app = typer.Typer()
+config_app = typer.Typer()
+app.add_typer(config_app, name="config")
+playlist_app = typer.Typer()
+app.add_typer(playlist_app, name="playlist")
+
+shuffler = random.Random()  # playlist play --shuffle; tests swap in a seeded one
 
 # How to install mpv, per sys.platform prefix; the README's Install section and the
 # install.sh / install.ps1 scripts repeat these, and tests keep all three in step.
@@ -194,7 +201,164 @@ def tui(video: bool = False):
     """
     from ttyplayer import tui as screen  # Textual loads only for this command
 
-    screen.TtyplayerApp(client_factory=player.MpvClient, resolve=screen.resolve, video=video).run()
+    screen.TtyplayerApp(
+        client_factory=player.MpvClient, resolve=screen.resolve, video=video, settings=load_settings()
+    ).run()
+
+
+@config_app.callback(invoke_without_command=True)
+def config(context: typer.Context):
+    """List the settings, or get, set or locate them"""
+    if context.invoked_subcommand is not None:
+        return
+    current = load_settings()
+    for key in settings.KEYS:
+        value = getattr(current, key)
+        default = "  (default)" if value == getattr(settings.DEFAULTS, key) else ""
+        typer.echo(f"{key} = {settings.display(value)}{default}")
+
+
+@config_app.command(name="get")
+def config_get(key: str):
+    """Print one setting's value"""
+    try:
+        settings.check_key(key)
+    except settings.SettingsError as error:
+        fail(str(error))
+    typer.echo(settings.display(getattr(load_settings(), key)))
+
+
+@config_app.command(name="set")
+def config_set(key: str, value: str):
+    """Change one setting and save it"""
+    try:
+        changed = settings.update(key, value)
+    except settings.SettingsError as error:
+        fail(str(error))
+    typer.echo(f"{key} = {settings.display(getattr(changed, key))}")
+
+
+@config_app.command(name="path")
+def config_path():
+    """Print where the settings file lives"""
+    typer.echo(settings.settings_path())
+
+
+def load_settings():
+    """The saved settings, or a one-line message and exit 1 when the file is broken."""
+    try:
+        return settings.load()
+    except settings.SettingsError as error:
+        fail(str(error))
+
+
+@playlist_app.callback()
+def playlist():
+    """Make, edit and play your own playlists"""
+
+
+@playlist_app.command(name="list")
+def playlist_list():
+    """List the playlists and how many videos each holds"""
+    names = playlists.names()
+    if not names:
+        fail("No playlists yet")
+    for name in names:
+        typer.echo(f"{name}  ({len(on_playlist(playlists.load, name))} videos)")
+
+
+@playlist_app.command(name="show")
+def playlist_show(name: str):
+    """List a playlist's videos, numbered"""
+    videos = on_playlist(playlists.load, name)
+    if not videos:
+        typer.echo(f"{name} is empty")
+    print_videos(videos)
+
+
+@playlist_app.command(name="create")
+def playlist_create(name: str):
+    """Make a new, empty playlist"""
+    on_playlist(playlists.create, name)
+    typer.echo(f"Created playlist {name}")
+
+
+@playlist_app.command(name="add")
+def playlist_add(name: str, target: list[str], limit: int = 5):
+    """Add a YouTube link or playlist, or search picks, to the end of a playlist"""
+    on_playlist(playlists.require, name)
+    count = on_playlist(playlists.add, name, resolve(target, limit))
+    typer.echo(f"Added {count} videos to {name}")
+
+
+@playlist_app.command(name="remove")
+def playlist_remove(name: str, number: int):
+    """Drop the video at this position"""
+    removed = on_playlist(playlists.remove, name, number)
+    typer.echo(f"Removed: {removed.title}")
+
+
+@playlist_app.command(name="move")
+def playlist_move(name: str, source: int, target: int):
+    """Move the video at one position to another"""
+    moved = on_playlist(playlists.move, name, source, target)
+    typer.echo(f"Moved to {target}: {moved.title}")
+
+
+@playlist_app.command(name="delete")
+def playlist_delete(name: str, yes: bool = typer.Option(False, "--yes", help="Do not ask first")):
+    """Delete a playlist, after asking"""
+    on_playlist(playlists.require, name)
+    if not yes and not typer.confirm(f"Delete playlist {name}?", default=False):
+        typer.echo(f"Kept {name}")
+        return
+    on_playlist(playlists.delete, name)
+    typer.echo(f"Deleted playlist {name}")
+
+
+@playlist_app.command(name="play")
+def playlist_play(name: str, video: bool = False, shuffle: bool = False):
+    """Play a whole playlist, in order or shuffled"""
+    videos = on_playlist(playlists.load, name)
+    if shuffle:
+        shuffler.shuffle(videos)
+    start_playback(videos, video)
+
+
+@playlist_app.command(name="import")
+def playlist_import(url: str, name: str | None = typer.Option(None, "--as", help="Name it this, not its title")):
+    """Save a YouTube playlist as a playlist of your own"""
+    from ttyplayer import youtube
+
+    title, videos = lookup(youtube.fetch_playlist, url)
+    if title is None:
+        fail(f"Not a playlist link: {url}")
+    name = name or playlists.sanitize(title)
+    if not name:
+        fail("The playlist title has nothing to name it by; name it with --as")
+    exit_if_empty(videos)
+    on_playlist(playlists.create, name)
+    on_playlist(playlists.add, name, videos)
+    typer.echo(f"Imported {len(videos)} videos as {name}")
+
+
+@playlist_app.command(name="save-queue")
+def playlist_save_queue(name: str):
+    """Save the playing ttyplayer's queue as a playlist, replacing what it held"""
+    on_playlist(playlists.playlist_path, name)
+    videos = [video_from_info(entry) for entry in remote("queue")["videos"]]
+    if not videos:
+        fail("The queue is empty")
+    on_playlist(playlists.replace, name, videos)
+    typer.echo(f"Saved {len(videos)} videos to {name}")
+
+
+def on_playlist(func, *args):
+    """Run a playlists.* call, turning its errors into a one-line message and exit 1."""
+    try:
+        return func(*args)
+    except playlists.PlaylistError as error:
+        fail(str(error))
 
 
 @app.command()

{ttyplayer-0.3.1 → ttyplayer-0.4.0}/src/ttyplayer/favorites.py

@@ -1,11 +1,9 @@
 """Videos the user chose to keep, one JSON object per line, newest at the bottom."""
 
-import json
-from datetime import datetime, timezone
 from pathlib import Path
 
 from ttyplayer.models import Video
-from ttyplayer.utils import data_path, video_from_info
+from ttyplayer.utils import append_entries, data_path, read_entries, video_entry, video_from_info, write_entries
 
 
 def favorites_path() -> Path:
@@ -17,16 +15,7 @@ def add(video: Video, path: Path | None = None) -> bool:
     path = path or favorites_path()
     if any(entry["id"] == video.id for entry in _entries(path)):
         return False
-    path.parent.mkdir(parents=True, exist_ok=True)
-    entry = {
-        "id": video.id,
-        "title": video.title,
-        "uploader": video.uploader,
-        "duration": video.duration,
-        "favorited_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
-    }
-    with path.open("a", encoding="utf-8") as f:
-        f.write(json.dumps(entry) + "\n")
+    append_entries(path, [video_entry(video, "favorited_at")])
     return True
 
 
@@ -48,7 +37,7 @@ def remove_id(video_id: str, path: Path | None = None) -> bool:
     kept = [entry for entry in reversed(entries) if entry["id"] != video_id]
     if len(kept) == len(entries):
         return False
-    path.write_text("".join(json.dumps(entry) + "\n" for entry in kept), encoding="utf-8")
+    write_entries(path, kept)
     return True
 
 
@@ -74,16 +63,10 @@ def load(path: Path | None = None, limit: int | None = None) -> list[Video]:
 
 def _entries(path: Path) -> list[dict]:
     """Stored entries newest first, one per video id, skipping corrupt lines."""
-    if not path.exists():
-        return []
     seen = set()
     entries = []
-    for line in reversed(path.read_text(encoding="utf-8").splitlines()):
-        try:
-            entry = json.loads(line)
-        except json.JSONDecodeError:
-            continue
-        if not isinstance(entry, dict) or "id" not in entry or entry["id"] in seen:
+    for entry in reversed(read_entries(path)):
+        if entry["id"] in seen:
             continue
         seen.add(entry["id"])
         entries.append(entry)

ttyplayer-0.4.0/src/ttyplayer/history.py

@@ -0,0 +1,38 @@
+"""What has been played, one JSON object per line, newest at the bottom."""
+
+from pathlib import Path
+
+from ttyplayer.models import Video
+from ttyplayer.utils import append_entries, data_path, read_entries, video_entry, video_from_info
+
+
+def history_path() -> Path:
+    return data_path("history.jsonl")
+
+
+def record(video: Video, path: Path | None = None):
+    append_entries(path or history_path(), [video_entry(video, "played_at")])
+
+
+def clear(path: Path | None = None) -> int:
+    """Forget everything. Returns how many entries were there."""
+    path = path or history_path()
+    if not path.exists():
+        return 0
+    count = len(path.read_text(encoding="utf-8").splitlines())
+    path.unlink()
+    return count
+
+
+def load(path: Path | None = None, limit: int = 20) -> list[Video]:
+    """Most recently played first, each video once, at most `limit` of them."""
+    seen = set()
+    videos = []
+    for entry in reversed(read_entries(path or history_path())):
+        if entry["id"] in seen:
+            continue
+        seen.add(entry["id"])
+        videos.append(video_from_info(entry))
+        if len(videos) == limit:
+            break
+    return videos

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

@@ -11,6 +11,7 @@ import sys
 import tempfile
 import threading
 import time
+from dataclasses import asdict
 
 from ttyplayer import control
 from ttyplayer.models import Video
@@ -479,6 +480,8 @@ class MpvClient:
             interrupt_main()  # run()'s Ctrl-C path quits and restores the terminal
         elif name == "status":
             return control.ok(**self.status())
+        elif name == "queue":
+            return control.ok(**self.queue_listing())
         else:
             return control.failure(f"unknown command {name}")
         return control.ok()
@@ -589,6 +592,11 @@ class MpvClient:
         self.index = 0
         return True
 
+    def queue_listing(self):
+        """Every queued video and the 1-based index of the current one, as the control socket sends them."""
+        with self.queue_lock:
+            return {"videos": [asdict(video) for video in self.queue], "index": self.index + 1}
+
     def current_title(self):
         # The queue knows the title before mpv does, so no file-name flicker on load.
         if self.queue:

ttyplayer-0.4.0/src/ttyplayer/playlists.py

@@ -0,0 +1,99 @@
+"""Named lists the user curates, one JSON-lines file per playlist, in the order the user keeps."""
+
+import re
+from pathlib import Path
+
+from ttyplayer.models import Video
+from ttyplayer.utils import append_entries, data_path, read_entries, video_entry, video_from_info, write_entries
+
+NAME = re.compile(r"[A-Za-z0-9 _-]{1,40}")  # also keeps a name from escaping the playlists dir
+NAME_RULE = "1 to 40 letters, digits, spaces, _ or -"
+
+
+class PlaylistError(Exception):
+    """A bad playlist name, a missing playlist, or a position out of range."""
+
+
+def playlists_dir() -> Path:
+    return data_path("playlists")
+
+
+def playlist_path(name: str) -> Path:
+    if not NAME.fullmatch(name):
+        raise PlaylistError(f"Bad playlist name {name!r}: use {NAME_RULE}")
+    return playlists_dir() / f"{name}.jsonl"
+
+
+def require(name: str) -> Path:
+    """The path of an existing playlist; PlaylistError if there is none by that name."""
+    path = playlist_path(name)
+    if not path.exists():
+        raise PlaylistError(f"No playlist named {name}")
+    return path
+
+
+def sanitize(title: str) -> str:
+    """A playlist name made from a title: other characters dropped, spaces collapsed, cut to 40."""
+    kept = re.sub(r"[^A-Za-z0-9 _-]", " ", title)
+    return " ".join(kept.split())[:40].strip()
+
+
+def names() -> list[str]:
+    directory = playlists_dir()
+    if not directory.is_dir():
+        return []
+    return sorted(path.stem for path in directory.glob("*.jsonl"))
+
+
+def load(name: str) -> list[Video]:
+    """The playlist's videos in file order, repeats kept."""
+    return [video_from_info(entry) for entry in read_entries(require(name))]
+
+
+def create(name: str):
+    path = playlist_path(name)
+    if path.exists():
+        raise PlaylistError(f"A playlist named {name} already exists")
+    write_entries(path, [])
+
+
+def delete(name: str):
+    require(name).unlink()
+
+
+def add(name: str, videos: list[Video]) -> int:
+    """Append videos to the playlist. Returns how many were added."""
+    append_entries(require(name), [video_entry(video, "added_at") for video in videos])
+    return len(videos)
+
+
+def remove(name: str, number: int) -> Video:
+    """Drop the `number`th video (1-indexed) and return it."""
+    path = require(name)
+    entries = read_entries(path)
+    _check_position(name, number, entries)
+    removed = entries.pop(number - 1)
+    write_entries(path, entries)
+    return video_from_info(removed)
+
+
+def move(name: str, source: int, target: int) -> Video:
+    """Move the `source`th video (1-indexed) to position `target` and return it."""
+    path = require(name)
+    entries = read_entries(path)
+    _check_position(name, source, entries)
+    _check_position(name, target, entries)
+    moved = entries.pop(source - 1)
+    entries.insert(target - 1, moved)
+    write_entries(path, entries)
+    return video_from_info(moved)
+
+
+def replace(name: str, videos: list[Video]):
+    """Make the playlist exactly these videos, creating it if it does not exist."""
+    write_entries(playlist_path(name), [video_entry(video, "added_at") for video in videos])
+
+
+def _check_position(name, number, entries):
+    if not 1 <= number <= len(entries):
+        raise PlaylistError(f"No video number {number} in {name}")