ttyplayer 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ttyplayer
-Version: 0.3.0
+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,13 +60,32 @@ ttyplayer stop                       quit the player
 ttyplayer status                     1:23 / 4:56  Playing  <title>
 ```
 
-Keys while playing:
+## 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 |
 |---|---|
 | space | pause / resume |
 | left / right, `,` / `.` | seek 5 seconds |
-| up / down | volume |
+| up / down, `-` / `+` | volume |
 | `n` / `p` | next / previous in the queue |
 | `q` or Ctrl-C | quit, restores the terminal and stops mpv |
 
@@ -78,16 +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 |
@@ -98,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.
@@ -199,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.0 → 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,13 +37,32 @@ ttyplayer stop                       quit the player
 ttyplayer status                     1:23 / 4:56  Playing  <title>
 ```
 
-Keys while playing:
+## 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 |
 |---|---|
 | space | pause / resume |
 | left / right, `,` / `.` | seek 5 seconds |
-| up / down | volume |
+| up / down, `-` / `+` | volume |
 | `n` / `p` | next / previous in the queue |
 | `q` or Ctrl-C | quit, restores the terminal and stops mpv |
 
@@ -55,16 +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 |
@@ -75,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.
@@ -176,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.0 → ttyplayer-0.4.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 [project]
 name = "ttyplayer"
-version = "0.3.0"
+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.0 → 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.
@@ -118,7 +125,7 @@ def check_control_dir():
 def play(target: list[str], video: bool = False, limit: int = 5):
     """Play a YouTube link or playlist, or search and pick what to play.
 
-    Keys while playing: space pause, left/right or , . seek, up/down volume,
+    Keys while playing: space pause, left/right or , . seek, up/down or - + volume,
     n next, p previous, q quit.
     """
     start_playback(resolve(target, limit), video)
@@ -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.0 → 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.0 → 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
@@ -40,6 +41,9 @@ KEYS = {
     "right": ("seek", SEEK_SECONDS),
     "up": ("change_volume", VOLUME_STEP),
     "down": ("change_volume", -VOLUME_STEP),
+    "+": ("change_volume", VOLUME_STEP),
+    "=": ("change_volume", VOLUME_STEP),  # the + key without shift
+    "-": ("change_volume", -VOLUME_STEP),
     "n": ("next",),
     "p": ("prev",),
 }
@@ -476,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()
@@ -586,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: