gingertea 0.1.0__py3-none-any.whl

gingertea/__init__.py

@@ -0,0 +1,15 @@
+"""gingertea: a terminal video downloader and converter built on yt-dlp."""
+
+
+def __getattr__(name: str):
+    # Looked up on first use: importlib.metadata adds ~15 ms to every launch otherwise.
+    if name == "__version__":
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            value = version("gingertea")
+        except PackageNotFoundError:  # pragma: no cover - running from a source tree
+            value = "0.0.0"
+        globals()["__version__"] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

gingertea/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

gingertea/app.py

@@ -0,0 +1,45 @@
+"""The Textual application."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from textual.app import App
+
+from . import config
+from .screens.main import MainScreen
+from .theme import THEMES
+
+
+class GingerTeaApp(App):
+    CSS_PATH = "styles.tcss"
+    TITLE = "gingertea"
+    ENABLE_COMMAND_PALETTE = True
+
+    def __init__(self, initial_url: str = "") -> None:
+        super().__init__()
+        self.initial_url = initial_url
+        # Set when PyPI has a newer gingertea; the CLI starts the upgrade after the app exits.
+        self.pending_app_update: str | None = None
+        self.settings = config.load()
+
+    def on_mount(self) -> None:
+        for theme in THEMES:
+            self.register_theme(theme)
+        saved = self.settings.theme
+        self.theme = saved if saved in self.available_themes else "tea-house"
+        self.theme_changed_signal.subscribe(self, self._remember_theme)
+
+    def _remember_theme(self, theme) -> None:
+        if theme.name != self.settings.theme:
+            self.save_settings(replace(self.settings, theme=theme.name))
+
+    def get_default_screen(self) -> MainScreen:
+        return MainScreen(self.initial_url)
+
+    def save_settings(self, settings: config.Settings) -> None:
+        self.settings = settings
+        try:
+            config.save(settings)
+        except OSError as exc:
+            self.notify(f"Couldn't save settings: {exc}", severity="error")

gingertea/cli.py

@@ -0,0 +1,100 @@
+"""Command-line entry point: `gingertea [URL or FILE]`, `gingertea setup`, `gingertea update`,
+`gingertea --version`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["update"]:
+        return _update()
+    if argv[:1] == ["setup"]:
+        return _setup()
+
+    parser = argparse.ArgumentParser(
+        prog="gingertea",
+        description="Download or convert videos from YouTube and 1,300+ other sites.",
+        epilog="Run `gingertea setup` to download ffmpeg now, `gingertea update` to update yt-dlp.",
+    )
+    parser.add_argument(
+        "url", nargs="?", default="", help="video link (or file to convert) to open straight away"
+    )
+    parser.add_argument("--version", action="version", version=_version_text())
+    args = parser.parse_args(argv)
+
+    from .app import GingerTeaApp
+
+    app = GingerTeaApp(initial_url=args.url)
+    app.run()
+    if app.pending_app_update:
+        from .engine import update
+
+        if update.start_self_upgrade():
+            print(
+                f"Updating gingertea {__version__} → {app.pending_app_update} in the background."
+                " It'll be ready next time you run gingertea."
+            )
+    return 0
+
+
+def _version_text() -> str:
+    from .engine.update import installed_version
+
+    return f"gingertea {__version__} (yt-dlp {installed_version()})"
+
+
+def _setup() -> int:
+    """Download gingertea's own ffmpeg now rather than on first use. The installers run this."""
+    from .engine import deps, local
+
+    if deps.bundled_ffmpeg_ready():
+        print("ffmpeg is already set up.")
+    else:
+        print("Getting ffmpeg for gingertea (one time, about 50 MB)…")
+    try:
+        tool = deps.fetch_bundled_ffmpeg(show_progress=True)
+    except Exception as exc:
+        print(f"Couldn't download ffmpeg: {exc}")
+        print("gingertea will try again the first time it needs ffmpeg.")
+        return 1
+    print(f"✓ ffmpeg is in {tool.path}")
+    if system := deps.system_ffmpeg():
+        print(f"  Your own ffmpeg in {system.path} is used too, for anything it can do.")
+
+    dirs = [t.path for t in deps.ffmpeg_candidates()]
+
+    def has(encoder: str) -> bool:
+        return any(deps.ffmpeg_has_encoder(d, encoder) for d in dirs)
+
+    for kind in ("video", "audio", "image"):
+        formats = local.formats_for(kind)
+        missing = [f.upper() for f in formats if local.missing_encoder(kind, f, has)]
+        line = f"  {len(formats) - len(missing)} {kind} formats ready"
+        print(line + (f" (not available: {', '.join(missing)})" if missing else ""))
+    return 0
+
+
+def _update() -> int:
+    from .engine import update
+
+    current = update.installed_version()
+    latest = update.latest_version()
+    if latest and update._key(latest) <= update._key(current):
+        print(f"yt-dlp {current} is already the latest version.")
+        return 0
+    print(f"Updating yt-dlp {current} → {latest or 'latest'}…")
+    print("$ " + " ".join(update.upgrade_command()))
+    ok, output = update.upgrade()
+    if output:
+        print(output)
+    print("Done." if ok else "Update failed.")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gingertea/config.py

@@ -0,0 +1,67 @@
+"""User settings, stored as TOML in the platform config directory."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+
+import platformdirs
+import tomli_w
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+APP_NAME = "gingertea"
+
+
+def default_download_dir() -> str:
+    return str(Path(platformdirs.user_downloads_dir()))
+
+
+def config_path() -> Path:
+    return Path(platformdirs.user_config_dir(APP_NAME, appauthor=False)) / "config.toml"
+
+
+@dataclass
+class Settings:
+    download_dir: str = ""
+    # Last choice made in the Convert dialog, so it opens where the user left it.
+    last_kind: str = "video"
+    last_video_format: str = "mp4"
+    last_video_quality: str = "best"
+    last_audio_format: str = "mp3"
+    last_audio_quality: str = "best"
+    last_image_format: str = "jpg"
+    last_image_quality: str = "best"
+    last_frames_format: str = "png"
+    last_frames_quality: str = "1"
+    # Browser cookies stay off until the user opts in for a login-only video.
+    cookies_browser: str = ""
+    theme: str = "tea-house"
+
+    def __post_init__(self) -> None:
+        if not self.download_dir:
+            self.download_dir = default_download_dir()
+
+    @property
+    def download_path(self) -> Path:
+        return Path(self.download_dir).expanduser()
+
+
+def load(path: Path | None = None) -> Settings:
+    path = path or config_path()
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return Settings()
+    known = {f.name for f in fields(Settings)}
+    return Settings(**{k: v for k, v in data.items() if k in known and isinstance(v, str)})
+
+
+def save(settings: Settings, path: Path | None = None) -> None:
+    path = path or config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(tomli_w.dumps(asdict(settings)), encoding="utf-8")

gingertea/engine/deps.py

@@ -0,0 +1,213 @@
+"""Locate ffmpeg/ffprobe and a JavaScript runtime.
+
+Binaries on PATH win. Otherwise fall back to gingertea's own copies: a static ffmpeg
+build (downloaded once, by `gingertea setup` or on first use) and the PyPI `deno` wheel.
+Converting local files can use both ffmpegs: whichever has the encoder a format needs.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import urllib.request
+import zipfile
+from dataclasses import dataclass
+from datetime import datetime
+from functools import cache
+from pathlib import Path
+
+# Static ffmpeg + ffprobe builds, one zip per platform holding a folder named after the key.
+# These are the builds the static-ffmpeg package (3.0) downloads; gingertea fetches them
+# itself so it doesn't install that package's unrelated dependencies (twine, keyring, ...).
+FFMPEG_ZIPS = {
+    "win32": "https://github.com/zackees/ffmpeg_bins/raw/main/v8.0/win32.zip",
+    "darwin": "https://github.com/zackees/ffmpeg_bins/raw/main/v8.0/darwin.zip",
+    "darwin_arm64": "https://github.com/zackees/ffmpeg_bins/raw/main/v8.0/darwin_arm64.zip",
+    "linux": "https://github.com/zackees/ffmpeg_bins/raw/main/v8.0/linux.zip",
+    "linux_arm64": "https://github.com/zackees/ffmpeg_bins/raw/main/v8.0/linux_arm64.zip",
+}
+CRUMB = "installed.crumb"
+
+
+@dataclass(frozen=True)
+class Tool:
+    path: str
+    bundled: bool
+
+
+def system_ffmpeg() -> Tool | None:
+    ffmpeg, ffprobe = shutil.which("ffmpeg"), shutil.which("ffprobe")
+    if ffmpeg and ffprobe and Path(ffmpeg).parent == Path(ffprobe).parent:
+        return Tool(str(Path(ffmpeg).parent), bundled=False)
+    return None
+
+
+def platform_key() -> str:
+    arm = platform.machine().lower() in ("arm64", "aarch64")
+    if sys.platform == "win32":
+        return "win32"
+    if sys.platform in ("darwin", "linux"):
+        return f"{sys.platform}_arm64" if arm else sys.platform
+    return sys.platform
+
+
+def bundled_dir() -> Path:
+    """Where the static build lives. Outside the app's environment, so it survives upgrades."""
+    import platformdirs
+
+    data = platformdirs.user_data_dir("gingertea", appauthor=False)
+    return Path(data) / "ffmpeg" / platform_key()
+
+
+def bundled_ffmpeg_ready() -> bool:
+    return (bundled_dir() / CRUMB).exists()
+
+
+def bundled_ffmpeg() -> Tool | None:
+    """The downloaded static build, if it's there."""
+    return Tool(str(bundled_dir()), bundled=True) if bundled_ffmpeg_ready() else None
+
+
+def ffmpeg_candidates() -> list[Tool]:
+    """Every ffmpeg gingertea can use, the system's first."""
+    return [t for t in (system_ffmpeg(), bundled_ffmpeg()) if t is not None]
+
+
+def fetch_bundled_ffmpeg(show_progress: bool = False) -> Tool:
+    """Download the static build if it isn't there yet (about 50 MB, once). Blocks.
+
+    `show_progress` prints a percentage; leave it off inside the TUI. Safe to run from two
+    processes at once: each unpacks into its own folder and the first to finish wins.
+    """
+    target = bundled_dir()
+    if (target / CRUMB).exists():
+        return Tool(str(target), bundled=True)
+    key = platform_key()
+    url = FFMPEG_ZIPS.get(key)
+    if url is None:
+        raise OSError(f"No ffmpeg build for {key}. Install ffmpeg yourself.")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    work = Path(tempfile.mkdtemp(prefix=".download-", dir=target.parent))
+    try:
+        archive = work / "ffmpeg.zip"
+        _download(url, archive, show_progress)
+        with zipfile.ZipFile(archive) as zf:
+            zf.extractall(work / "unpacked")  # zipfile keeps members inside this folder
+        archive.unlink()
+        unpacked = work / "unpacked" / key
+        exe = ".exe" if sys.platform == "win32" else ""
+        for name in ("ffmpeg", "ffprobe"):
+            path = unpacked / f"{name}{exe}"
+            if not path.is_file():
+                raise OSError(f"The ffmpeg download has no {path.name}.")
+            if not exe:
+                path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        (unpacked / CRUMB).write_text(f"installed from {url} on {datetime.now()}")
+        if target.exists() and not (target / CRUMB).exists():
+            shutil.rmtree(target, ignore_errors=True)  # a broken earlier attempt
+        try:
+            os.replace(unpacked, target)
+        except OSError:
+            if not (target / CRUMB).exists():  # not just another process winning the race
+                raise
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    return Tool(str(target), bundled=True)
+
+
+def _download(url: str, dest: Path, show_progress: bool) -> None:
+    request = urllib.request.Request(url, headers={"User-Agent": "gingertea"})
+    with (
+        urllib.request.urlopen(request, timeout=60, context=_tls()) as resp,
+        open(dest, "wb") as out,
+    ):
+        total = int(resp.headers.get("Content-Length") or 0)
+        done, shown = 0, -1
+        while chunk := resp.read(1 << 18):
+            out.write(chunk)
+            done += len(chunk)
+            if show_progress and total and (pct := done * 100 // total) != shown:
+                print(f"\r  {pct}% of {total / 2**20:.0f} MB", end="", flush=True)
+                shown = pct
+    if show_progress:
+        print()
+
+
+def _tls():
+    """certifi's CA bundle when it's there (it comes with yt-dlp), else the system's."""
+    import ssl
+
+    try:
+        import certifi
+
+        return ssl.create_default_context(cafile=certifi.where())
+    except ImportError:
+        return ssl.create_default_context()
+
+
+def find_ffmpeg(fetch: bool = True) -> Tool | None:
+    """Return the directory holding ffmpeg + ffprobe.
+
+    With `fetch`, downloads the bundled build if nothing else is available
+    (about 70 MB, once). That call blocks, so run it off the UI thread.
+    """
+    if tool := system_ffmpeg():
+        return tool
+    if not fetch:
+        return bundled_ffmpeg()
+    return fetch_bundled_ffmpeg()
+
+
+def find_deno() -> Tool | None:
+    if path := shutil.which("deno"):
+        return Tool(path, bundled=False)
+    try:
+        from deno import find_deno_bin
+
+        return Tool(str(find_deno_bin()), bundled=True)
+    except Exception:
+        return None
+
+
+def js_runtimes() -> dict[str, dict[str, str]]:
+    """yt-dlp `js_runtimes` option: needed for full YouTube support."""
+    if deno := find_deno():
+        return {"deno": {"path": deno.path}}
+    # Let yt-dlp try its own discovery (node, bun, ...) if Deno is somehow missing.
+    return {name: {} for name in ("deno", "node", "bun") if shutil.which(name)}
+
+
+@cache
+def ffmpeg_encoders(ffmpeg_dir: str) -> frozenset[str] | None:
+    """Every encoder this ffmpeg build has, or None if it couldn't be asked."""
+    exe = shutil.which("ffmpeg", path=ffmpeg_dir) or "ffmpeg"
+    try:
+        out = subprocess.run(
+            [exe, "-hide_banner", "-encoders"], capture_output=True, text=True, timeout=10
+        ).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return frozenset(parts[1] for line in out.splitlines() if len(parts := line.split()) > 1)
+
+
+def ffmpeg_has_encoder(ffmpeg_dir: str, encoder: str) -> bool:
+    names = ffmpeg_encoders(ffmpeg_dir)
+    return True if names is None else encoder in names
+
+
+class SilentLogger:
+    """yt-dlp logger that drops everything; errors still arrive as exceptions.
+
+    Without it yt-dlp writes "ERROR: ..." to stderr even in quiet mode, which
+    would scribble over the full-screen UI.
+    """
+
+    def debug(self, msg: str) -> None:
+        pass
+
+    info = warning = error = debug

gingertea/engine/errors.py

@@ -0,0 +1,130 @@
+"""Translate yt-dlp failures into plain language plus a suggested next step."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+LOGIN = "login"
+OUTDATED = "outdated"
+NETWORK = "network"
+UNAVAILABLE = "unavailable"
+UNSUPPORTED = "unsupported"
+PLAYLIST = "playlist"
+GENERIC = "generic"
+
+
+@dataclass(frozen=True)
+class FriendlyError:
+    kind: str
+    message: str
+    hint: str = ""
+    detail: str = ""  # yt-dlp's own first line, shown small so odd cases can be diagnosed
+
+
+_RULES: list[tuple[str, tuple[str, ...], str, str]] = [
+    (
+        UNSUPPORTED,
+        ("invalid data found when processing input", "isn't audio, video or an image"),
+        "gingertea can't read this file.",
+        "It may be damaged, or it isn't audio, video or an image.",
+    ),
+    (
+        PLAYLIST,
+        ("playlist or channel",),
+        "That's a playlist or channel.",
+        "Paste a link to a single video.",
+    ),
+    (
+        LOGIN,
+        ("not a bot",),
+        "YouTube wants to check you're not a bot.",
+        "Choose a browser where you are signed in to YouTube, then try again. "
+        "If it still fails, try again later.",
+    ),
+    (
+        LOGIN,
+        (
+            "sign in to confirm your age",
+            "age-restricted",
+            "inappropriate for some users",
+            "members-only",
+            "join this channel",
+            "sign in to confirm you",
+            "login required",
+            "requires authentication",
+            "use --cookies",
+        ),
+        "This video needs you to be signed in.",
+        "Use cookies from your browser to sign in.",
+    ),
+    (
+        UNAVAILABLE,
+        (
+            "private video",
+            "video unavailable",
+            "has been removed",
+            "not available in your country",
+            "this video is not available",
+            "premieres in",
+        ),
+        "This video isn't available.",
+        "It may be private, removed, region-locked or not out yet.",
+    ),
+    (
+        UNSUPPORTED,
+        ("unsupported url", "is not a valid url"),
+        "That link isn't a video gingertea can read.",
+        "Check the link and try again.",
+    ),
+    (
+        OUTDATED,
+        (
+            "http error 403",
+            "signature extraction failed",
+            "nsig extraction failed",
+            "unable to extract",
+            "requested format is not available",
+            "n challenge",
+            "please report this issue",
+            "only images are available",
+        ),
+        "The site may have changed how it serves videos.",
+        "Press u to update yt-dlp, then try again.",
+    ),
+    (
+        NETWORK,
+        (
+            "getaddrinfo",
+            "network is unreachable",
+            "timed out",
+            "connection refused",
+            "temporary failure in name resolution",
+            "nodename nor servname",
+            "connection reset",
+        ),
+        "Couldn't reach the site.",
+        "Check your internet connection and try again.",
+    ),
+]
+
+_PREFIX = re.compile(r"^(ERROR:\s*)?(\[[^\]]+\]\s*)?([\w-]+:\s+)?")
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def clean(text: str) -> str:
+    line = _ANSI.sub("", text).strip().splitlines()[0] if text.strip() else ""
+    return _PREFIX.sub("", line).strip() or "Something went wrong."
+
+
+def explain(exc: BaseException | str) -> FriendlyError:
+    text = str(exc)
+    low = text.lower()
+    for kind, needles, message, hint in _RULES:
+        if any(n in low for n in needles):
+            return FriendlyError(kind, message, hint, clean(text))
+    if "ffmpeg" in low and ("not found" in low or "not installed" in low):
+        return FriendlyError(
+            GENERIC, "ffmpeg is missing.", "Install ffmpeg, or reinstall gingertea."
+        )
+    return FriendlyError(GENERIC, clean(text))