ttyplayer 0.3.0__py3-none-any.whl

ttyplayer/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from ttyplayer!")

ttyplayer/cli.py

@@ -0,0 +1,343 @@
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+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
+
+app = typer.Typer()
+
+# 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.
+MPV_INSTALL = {
+    "darwin": ["brew install mpv"],
+    "linux": [
+        "sudo apt-get install -y mpv",
+        "sudo dnf install -y mpv",
+        "sudo pacman -S --noconfirm mpv",
+        "sudo zypper install -y mpv",
+        "sudo apk add mpv",
+    ],
+    "win32": ["winget install -e --id shinchiro.mpv", "scoop install mpv", "choco install mpv"],
+}
+
+
+@app.callback()
+def callback():
+    """ttyplayer is a terminal YouTube player"""
+
+
+@app.command()
+def version():
+    """Print the version"""
+    typer.echo(f"{APP_NAME} {metadata.version(APP_NAME)}")
+
+
+@app.command()
+def doctor():
+    """Check that ttyplayer has everything it needs to play"""
+    passed = True
+    for ok, text in doctor_checks():
+        typer.echo(f"{'✓' if ok else '✗'} {text}")
+        passed = passed and ok
+    if not passed:
+        raise typer.Exit(code=1)
+
+
+def doctor_checks():
+    """(ok, text) per check; nothing here touches the network."""
+    python = ".".join(map(str, sys.version_info[:3]))
+    yield sys.version_info >= (3, 13), f"Python {python}"
+    yield True, f"{APP_NAME} {metadata.version(APP_NAME)}"
+    yield check_yt_dlp()
+    yield check_mpv()
+    yield check_data_dir()
+    yield check_control_dir()
+
+
+def check_yt_dlp():
+    try:
+        from yt_dlp.version import __version__
+    except ImportError as error:
+        return False, f"yt-dlp cannot be imported: {error}"
+    return True, f"yt-dlp {__version__}"
+
+
+def check_mpv():
+    path = shutil.which("mpv")
+    if path is None:
+        return False, f"mpv not found on PATH. {mpv_install_hint()}"
+    try:
+        return True, mpv_version(path)
+    except (OSError, subprocess.SubprocessError, IndexError) as error:
+        return False, f"mpv at {path} did not answer --version: {error}"
+
+
+def mpv_version(path):
+    """The first line `mpv --version` prints, e.g. mpv v0.39.0 Copyright ..."""
+    result = subprocess.run([path, "--version"], capture_output=True, text=True, timeout=5, check=True)
+    return result.stdout.splitlines()[0]
+
+
+def mpv_install_hint(platform=sys.platform):
+    """One line telling the user how to install mpv on this platform."""
+    for prefix, (command, *others) in MPV_INSTALL.items():
+        if platform.startswith(prefix):
+            alternatives = f" (or: {', '.join(others)})" if others else ""
+            return f"Install it with: {command}{alternatives}"
+    return "Install it from https://mpv.io/installation/"
+
+
+def check_data_dir():
+    directory = data_path("")
+    try:
+        os.makedirs(directory, exist_ok=True)
+        tempfile.TemporaryFile(dir=directory).close()
+    except OSError as error:
+        return False, f"data dir {directory} is not writable: {error}"
+    return True, f"data dir {directory}"
+
+
+def check_control_dir():
+    endpoint = control.control_endpoint()
+    directory = os.path.dirname(endpoint.path)
+    try:
+        endpoint.prepare()
+    except OSError as error:
+        return False, f"control socket dir: {error}"
+    return True, f"control socket dir {directory}"
+
+
+@app.command()
+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,
+    n next, p previous, q quit.
+    """
+    start_playback(resolve(target, limit), video)
+
+
+@app.command()
+def search(query: list[str], limit: int = 5):
+    """Search YouTube and list the results"""
+    from ttyplayer import youtube  # yt-dlp loads on use, so doctor runs without it
+
+    videos = lookup(youtube.search, " ".join(query), limit)
+    exit_if_empty(videos)
+    print_videos(videos)
+
+
+@app.command(name="history")
+def history_command(limit: int = 20, play: bool = False, video: bool = False, clear: bool = False):
+    """List recently played videos; --play to pick some and play them again, --clear to forget"""
+    if clear:
+        typer.echo(f"Forgot {history.clear()} plays")
+        return
+    videos = history.load(limit=limit)
+    if not videos:
+        fail("Nothing played yet")
+    if play:
+        start_playback(pick_from(videos), video)
+    else:
+        print_videos(videos)
+
+
+@app.command()
+def favorite(target: list[str], limit: int = 5):
+    """Add a YouTube link or playlist to favorites, or search and pick what to add"""
+    videos = resolve(target, limit)
+    exit_if_empty(videos)
+    for video in videos:
+        if favorites.add(video):
+            typer.echo(f"Favorited: {video.title}")
+        else:
+            typer.echo(f"Already a favorite: {video.title}")
+
+
+@app.command(name="favorites")
+def favorites_command(
+    play: bool = False, video: bool = False, remove: int | None = None, clear: bool = False
+):
+    """List favorites; --play to pick some and play them, --remove N to drop one, --clear to forget all"""
+    if clear:
+        typer.echo(f"Forgot {favorites.clear()} favorites")
+        return
+    if remove is not None:
+        removed = favorites.remove(remove)
+        if removed is None:
+            fail(f"No favorite number {remove}")
+        typer.echo(f"Removed: {removed.title}")
+        return
+    videos = favorites.load()
+    if not videos:
+        fail("No favorites yet")
+    if play:
+        start_playback(pick_from(videos), video)
+    else:
+        print_videos(videos)
+
+
+@app.command()
+def tui(video: bool = False):
+    """Open the full-screen player: search, pick and play in one screen.
+
+    Keys: / search, Enter play, a add to queue, f favorite, m more results,
+    space pause, , . seek 5s, < > seek 30s, - + volume, M mute, n next,
+    p previous, 1-4 tabs, t theme, ? help, Ctrl-P commands, q quit.
+    """
+    from ttyplayer import tui as screen  # Textual loads only for this command
+
+    screen.TtyplayerApp(client_factory=player.MpvClient, resolve=screen.resolve, video=video).run()
+
+
+@app.command()
+def pause():
+    """Pause or resume the ttyplayer playing in another terminal"""
+    remote("pause")
+
+
+@app.command(name="next")
+def next_command():
+    """Skip to the next video in the playing ttyplayer's queue"""
+    remote("next")
+
+
+@app.command()
+def prev():
+    """Go back to the previous video in the playing ttyplayer's queue"""
+    remote("prev")
+
+
+@app.command()
+def stop():
+    """Stop the ttyplayer playing in another terminal"""
+    remote("stop")
+
+
+@app.command()
+def status():
+    """Show what the playing ttyplayer is playing"""
+    typer.echo(player.status_line(remote("status")))
+
+
+def remote(name):
+    """Send name to the playing ttyplayer; its reply, or a one-line message and exit 1."""
+    try:
+        reply = control.send(name)
+    except control.ControlError:
+        fail("No ttyplayer is playing")
+    if not reply.get("ok"):
+        fail(reply.get("error", "The player refused"))
+    return reply
+
+
+def resolve(target, limit):
+    """Turn a link into its videos, or search words into the videos the user picks."""
+    from ttyplayer import youtube
+
+    target_text = " ".join(target)
+    if youtube.is_url(target_text):
+        return lookup(youtube.fetch, target_text)
+
+    def more(shown):
+        return unseen(lookup(youtube.search, target_text, len(shown) + limit), shown)
+
+    return pick_from(lookup(youtube.search, target_text, limit), more)
+
+
+def pick_from(videos, more=None):
+    """Show a numbered list and return the videos the user picked, in their order.
+
+    With more, the user can type m to list the next batch more(videos) returns.
+    """
+    exit_if_empty(videos)
+    videos = list(videos)
+    print_videos(videos)
+    return [videos[pick - 1] for pick in ask_for_picks(videos, more)]
+
+
+def ask_for_picks(videos, more=None):
+    """Prompt until the answer is valid picks; m appends more's batch to videos and lists it."""
+    prompt = "Pick one or more numbers (1 or 1 3 5)"
+    if more:
+        prompt += ", m for more"
+    while True:
+        answer = typer.prompt(prompt)
+        if more and answer.strip().lower() == "m":
+            show_more(videos, more)
+            continue
+        picks = parse_picks(answer, len(videos))
+        if picks is not None:
+            return picks
+        typer.echo(f"Enter numbers between 1 and {len(videos)}, separated by spaces.", err=True)
+
+
+def show_more(videos, more):
+    fresh = more(videos)
+    if not fresh:
+        typer.echo("No more results", err=True)
+        return
+    print_videos(fresh, start=len(videos) + 1)
+    videos.extend(fresh)
+
+
+def start_playback(videos, with_video):
+    exit_if_empty(videos)
+    try:
+        client = player.MpvClient(with_video, on_play=history.record)
+    except FileNotFoundError:
+        fail(f"mpv is not installed. {mpv_install_hint()}")
+    except RuntimeError as error:
+        fail(str(error))
+    for video in videos:
+        client.add(video)
+    client.play_current()
+    client.run()
+
+
+def print_videos(videos, start=1):
+    for number, video in enumerate(videos, start=start):
+        typer.echo(f"{number:>2}. {video.title}  ({format_time(video.duration)})  {video.uploader}")
+
+
+def lookup(func, *args):
+    """Run a youtube.* call, turning its errors into a one-line message and exit 1."""
+    from ttyplayer import youtube
+
+    began = time.monotonic()
+    try:
+        videos = func(*args)
+    except youtube.YouTubeError as error:
+        fail(f"YouTube lookup failed: {error}")
+    if player.timing():
+        typer.echo(f"lookup took {time.monotonic() - began:.1f}s", err=True)
+    return videos
+
+
+def exit_if_empty(videos):
+    if not videos:
+        fail("No videos found")
+
+
+def fail(message):
+    typer.echo(message, err=True)
+    raise typer.Exit(code=1)
+
+
+def utf8_streams():
+    """Pipes and redirects on Windows default to a legacy code page; the ticks and meters need UTF-8."""
+    for stream in (sys.stdout, sys.stderr):
+        if stream.encoding.lower().replace("-", "") != "utf8":
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def main():
+    utf8_streams()
+    app()

ttyplayer/control.py

@@ -0,0 +1,244 @@
+import hmac
+import json
+import os
+import secrets
+import socket
+import stat
+import sys
+import tempfile
+import threading
+
+from ttyplayer.utils import APP_NAME, WINDOWS, data_path
+
+CLIENT_TIMEOUT = 3  # seconds to wait for the player's reply
+CONNECTION_TIMEOUT = 1  # seconds the server waits for one request line
+ACCEPT_TIMEOUT = 0.2  # how often the server loop checks whether it was stopped
+
+
+class ControlError(Exception):
+    """No player answered on the control socket."""
+
+
+def control_path():
+    """$XDG_RUNTIME_DIR/ttyplayer/control.sock, or a per-user dir under the temp dir."""
+    runtime = os.environ.get("XDG_RUNTIME_DIR")
+    if runtime:
+        return os.path.join(runtime, APP_NAME, "control.sock")
+    return os.path.join(tempfile.gettempdir(), f"{APP_NAME}-{os.getuid()}", "control.sock")
+
+
+def control_endpoint(path=None):
+    """Where the player listens and clients connect: a Unix socket, or loopback TCP plus a token on Windows."""
+    return LoopbackEndpoint(path) if WINDOWS else SocketEndpoint(path)
+
+
+class SocketEndpoint:
+    """The control socket at path (control_path() by default), in a dir only this user can enter."""
+
+    def __init__(self, path=None):
+        self.path = path or control_path()
+        self.inode = None
+
+    def prepare(self):
+        private_dir(os.path.dirname(self.path))
+
+    def listen(self):
+        self.prepare()
+        if os.path.lexists(self.path):
+            os.unlink(self.path)  # left behind by a player that crashed
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        try:
+            sock.bind(self.path)
+            sock.listen()
+        except OSError:
+            sock.close()
+            raise
+        # A newer player may replace the file; remove() must not remove that one.
+        self.inode = os.stat(self.path).st_ino
+        return sock
+
+    def connect(self):
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(CLIENT_TIMEOUT)
+        try:
+            sock.connect(self.path)
+        except OSError:
+            sock.close()
+            raise
+        return sock
+
+    def request(self, name):
+        return {"command": name}
+
+    def authorize(self, request):
+        return True  # the dir's permissions already kept other users out
+
+    def remove(self):
+        try:
+            if os.stat(self.path).st_ino == self.inode:
+                os.unlink(self.path)
+        except FileNotFoundError:
+            pass
+
+
+class LoopbackEndpoint:
+    """127.0.0.1 on an ephemeral port; "<port> <token>" in path (%LOCALAPPDATA%\\ttyplayer\\control.txt).
+
+    Any local process can reach the port, so every request must carry the token,
+    which only processes that can read the user's profile can know.
+    """
+
+    def __init__(self, path=None):
+        self.path = path or str(data_path("control.txt"))
+        self.token = None
+        self.written = None
+
+    def prepare(self):
+        os.makedirs(os.path.dirname(self.path), exist_ok=True)
+
+    def listen(self):
+        self.prepare()
+        sock = socket.create_server(("127.0.0.1", 0))
+        self.token = secrets.token_hex(16)
+        self.written = f"{sock.getsockname()[1]} {self.token}"
+        try:
+            with open(self.path, "w") as file:
+                file.write(self.written)
+        except OSError:
+            sock.close()
+            raise
+        return sock
+
+    def connect(self):
+        with open(self.path) as file:
+            text = file.read()
+        try:
+            port, self.token = text.split()
+            address = ("127.0.0.1", int(port))
+        except ValueError:
+            raise OSError(f"{self.path} does not hold a port and a token") from None
+        return socket.create_connection(address, timeout=CLIENT_TIMEOUT)
+
+    def request(self, name):
+        return {"command": name, "token": self.token}
+
+    def authorize(self, request):
+        token = request.get("token")
+        if not isinstance(token, str):
+            return False
+        # As bytes: compare_digest refuses non-ASCII str, and JSON can carry lone surrogates.
+        return hmac.compare_digest(token.encode("utf-8", "surrogatepass"), self.token.encode())
+
+    def remove(self):
+        try:
+            with open(self.path) as file:
+                if file.read() != self.written:
+                    return  # a newer player wrote its own
+            os.unlink(self.path)
+        except FileNotFoundError:
+            pass
+
+
+def ok(**fields):
+    return {"ok": True, **fields}
+
+
+def failure(message):
+    return {"ok": False, "error": message}
+
+
+# --- client -------------------------------------------------------------
+
+
+def send(name, path=None):
+    """Send one command to the running player and return its reply."""
+    endpoint = control_endpoint(path)
+    try:
+        with endpoint.connect() as sock, sock.makefile("rw") as stream:
+            stream.write(json.dumps(endpoint.request(name)) + "\n")
+            stream.flush()
+            text = stream.readline()
+    except OSError as error:  # no socket file, refused, or no reply in time
+        raise ControlError(str(error)) from error
+    if not text:
+        raise ControlError("the player closed the connection")
+    return json.loads(text)
+
+
+# --- server -------------------------------------------------------------
+
+
+def private_dir(directory):
+    """Create directory 0o700, then refuse it unless it is a real dir only this user can enter."""
+    os.makedirs(directory, mode=0o700, exist_ok=True)
+    info = os.lstat(directory)  # lstat: a symlink could point anywhere
+    if not stat.S_ISDIR(info.st_mode):
+        raise OSError(f"{directory} is not a directory")
+    if info.st_uid != os.getuid():
+        raise OSError(f"{directory} belongs to another user")
+    if stat.S_IMODE(info.st_mode) & 0o077:
+        raise OSError(f"{directory} is open to other users")
+
+
+def reply_to(line, handler, authorize):
+    """The reply to one request line; a malformed or unauthorized line gets ok: false, never an exception."""
+    try:
+        request = json.loads(line)
+        name = request["command"]
+    except (ValueError, TypeError, KeyError):
+        return failure("malformed request")
+    if not isinstance(name, str):
+        return failure("malformed request")
+    if not authorize(request):
+        return failure("bad token")
+    return handler(name)
+
+
+class Server:
+    """Answers one request per connection on a daemon thread with handler(name) -> dict."""
+
+    def __init__(self, handler, path=None):
+        self.handler = handler
+        self.endpoint = control_endpoint(path)
+        self.path = self.endpoint.path
+        self.sock = self.endpoint.listen()
+        self.sock.settimeout(ACCEPT_TIMEOUT)
+        self.stopped = threading.Event()
+        self.thread = threading.Thread(target=self.serve, daemon=True)
+        self.thread.start()
+
+    def serve(self):
+        while not self.stopped.is_set():
+            try:
+                conn, _ = self.sock.accept()
+            except TimeoutError:
+                continue
+            except OSError:
+                break
+            with conn:
+                self.answer(conn)
+
+    def answer(self, conn):
+        conn.settimeout(CONNECTION_TIMEOUT)
+        try:
+            # Undecodable bytes become U+FFFD, so they fail as malformed JSON, not here.
+            with conn.makefile("rw", encoding="utf-8", errors="replace") as stream:
+                reply = reply_to(stream.readline(), self.handler, self.endpoint.authorize)
+                stream.write(json.dumps(reply) + "\n")
+        except OSError:
+            pass  # the client went away; wait for the next one
+
+    def stop(self):
+        self.stopped.set()
+        self.thread.join(timeout=1)
+        self.sock.close()
+        self.endpoint.remove()
+
+
+def serve(handler, path=None):
+    """Start a Server, or warn on stderr and return None: playing never depends on it."""
+    try:
+        return Server(handler, path)
+    except OSError as error:
+        print(f"Remote control is off: {error}", file=sys.stderr)
+        return None

ttyplayer/favorites.py

@@ -0,0 +1,90 @@
+"""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
+
+
+def favorites_path() -> Path:
+    return data_path("favorites.jsonl")
+
+
+def add(video: Video, path: Path | None = None) -> bool:
+    """Favorite a video. Returns False if it already was one."""
+    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")
+    return True
+
+
+def remove(number: int, path: Path | None = None) -> Video | None:
+    """Drop the `number`th favorite as load() lists it (1-indexed). None if out of range."""
+    path = path or favorites_path()
+    videos = load(path)
+    if not 1 <= number <= len(videos):
+        return None
+    removed = videos[number - 1]
+    remove_id(removed.id, path)
+    return removed
+
+
+def remove_id(video_id: str, path: Path | None = None) -> bool:
+    """Drop the favorite with this id. Returns False if it was not one."""
+    path = path or favorites_path()
+    entries = _entries(path)
+    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")
+    return True
+
+
+def ids(path: Path | None = None) -> set[str]:
+    """The id of every favorite."""
+    return {entry["id"] for entry in _entries(path or favorites_path())}
+
+
+def clear(path: Path | None = None) -> int:
+    """Forget every favorite. Returns how many there were."""
+    path = path or favorites_path()
+    count = len(load(path))
+    path.unlink(missing_ok=True)
+    return count
+
+
+def load(path: Path | None = None, limit: int | None = None) -> list[Video]:
+    """Most recently added first, each video once, at most `limit` of them (all if None)."""
+    path = path or favorites_path()
+    videos = [video_from_info(entry) for entry in _entries(path)]
+    return videos[:limit]
+
+
+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:
+            continue
+        seen.add(entry["id"])
+        entries.append(entry)
+    return entries