overc-clips 0.1.0__py3-none-any.whl

overc_clips/cli.py

@@ -0,0 +1,335 @@
+"""Command line for overc-clips. The web service calls the same engine."""
+from __future__ import annotations
+
+import argparse
+import csv
+import os
+import json
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+from . import engine, preflight
+from .config import Config
+
+
+def _version() -> str:
+    try:
+        from importlib.metadata import version
+        return version("overc-clips")
+    except Exception:
+        return "0.1.0"
+
+
+def _rows_from_csv(path: Path, need_url: bool) -> list[dict]:
+    with open(path, newline="", encoding="utf-8-sig") as fh:
+        rows = [r for r in csv.DictReader(fh)]
+    out = []
+    for r in rows:
+        r = { (k or "").strip().lower(): (v or "").strip() for k, v in r.items() }
+        if not any(r.values()):
+            continue
+        if need_url and not r.get("url"):
+            print(f"SKIP row with no url: {r}", file=sys.stderr)
+            continue
+        out.append(r)
+    return out
+
+
+def cmd_doctor(a) -> int:
+    t = preflight.detect()
+    if a.json:
+        print(json.dumps(t.as_dict(), indent=2))
+    else:
+        print("overc-clips — tool check\n")
+        print(preflight.report(t))
+    return 0 if t.can_cut else 1
+
+
+def _emit(plans, a, produced=None):
+    if a.json:
+        print(json.dumps({"dry_run": a.dry_run,
+                          "clips": [c.as_dict() for c in plans],
+                          "produced": [str(p) for p in (produced or [])]}, indent=2))
+
+
+def cmd_cut(a) -> int:
+    t = preflight.detect()
+    if not t.can_cut:
+        print("ffmpeg not available — run `overc-clips doctor`", file=sys.stderr)
+        return 1
+    src = Path(a.input)
+    if not src.exists():
+        print(f"input not found: {src}", file=sys.stderr)
+        return 1
+
+    specs = []
+    if a.range:
+        s, e = a.range.split("-", 1)
+        specs.append({"name": a.name or f"clip_{s.replace(':','')}{e.replace(':','')}",
+                      "start": s, "end": e})
+    else:
+        specs = _rows_from_csv(Path(a.csv), need_url=False)
+
+    plans, produced = [], []
+    for sp in specs:
+        try:
+            cs = engine.plan_clip(sp.get("name", ""), sp["start"], sp["end"])
+        except (engine.ClipError, KeyError) as ex:
+            print(f"SKIP {sp.get('name','?')}: {ex}", file=sys.stderr)
+            continue
+        plans += cs
+        if not a.json and not a.quiet:
+            print(f"{sp.get('name','?')}: {len(cs)} clip(s)")
+        for c in cs:
+            if a.dry_run:
+                if not a.json and not a.quiet:
+                    print(f"  -> {c.name} ({c.start_hms}, {c.seconds:.0f}s)")
+                continue
+            try:
+                p = engine.encode(src, c, Path(a.outdir), t, encoder=a.encoder,
+                                  accurate=a.accurate, copy=a.copy)
+                produced.append(p)
+                if not a.json and not a.quiet:
+                    print(f"  -> {p}")
+            except engine.ClipError as ex:
+                print(f"  !! {ex}", file=sys.stderr)
+    _emit(plans, a, produced)
+    if not a.json and not a.quiet:
+        print(f"\n{len(plans)} clip(s) {'planned (dry run)' if a.dry_run else f'in {a.outdir}/'}")
+    return 0
+
+
+def cmd_grab(a) -> int:
+    t = preflight.detect()
+    if not a.dry_run and not t.can_grab:
+        print("need ffmpeg + yt-dlp — run `overc-clips doctor`", file=sys.stderr)
+        return 1
+
+    specs = ([{"url": a.url, "name": a.name, "start": a.range.split("-")[0],
+               "end": a.range.split("-")[1]}] if a.url
+             else _rows_from_csv(Path(a.csv), need_url=True))
+
+    plans, produced = [], []
+    for sp in specs:
+        try:
+            cs = engine.plan_clip(sp.get("name", ""), sp["start"], sp["end"])
+        except (engine.ClipError, KeyError) as ex:
+            print(f"SKIP {sp.get('name','?')}: {ex}", file=sys.stderr)
+            continue
+        plans += cs
+        if not a.json and not a.quiet:
+            print(f"{cs[0].source_name}: {sp['start']}-{sp['end']} -> {len(cs)} clip(s)")
+        if a.dry_run:
+            continue
+        out = Path(a.outdir)
+        tmpdir = Path(tempfile.mkdtemp(prefix="overc-clips-"))
+        try:
+            span = engine.fetch_span(sp["url"], sp["start"], sp["end"],
+                                     tmpdir / "span", t,
+                                     log=lambda m: print(m, file=sys.stderr))
+            if len(cs) == 1:
+                out.mkdir(parents=True, exist_ok=True)
+                dest = out / f"{cs[0].name}.mp4"
+                shutil.move(str(span), dest)
+                produced.append(dest)
+                if not a.json and not a.quiet:
+                    print(f"  -> {dest}")
+            else:
+                actual = engine.probe_duration(span, t) or cs[0].seconds * len(cs)
+                for c in engine.plan_clip(cs[0].source_name, "00:00:00",
+                                          engine.fmt_hms(actual)):
+                    p = engine.encode(span, c, out, t, encoder=a.encoder,
+                                      accurate=a.accurate, copy=a.copy)
+                    produced.append(p)
+                    if not a.json and not a.quiet:
+                        print(f"  -> {p}")
+        except engine.ClipError as ex:
+            print(f"  !! {ex}", file=sys.stderr)
+        finally:
+            shutil.rmtree(tmpdir, ignore_errors=True)
+    _emit(plans, a, produced)
+    if not a.json and not a.quiet:
+        print(f"\n{len(plans)} clip(s) {'planned (dry run)' if a.dry_run else f'in {a.outdir}/'}")
+    return 0
+
+
+def cmd_backfill(a) -> int:
+    """Give existing clips their provenance back.
+
+    Three sources, cheapest first: what the index already holds, what history
+    knows about the video id, and what the file says about itself. Clips made
+    before any of this existed have none of the three and stay unknown, which
+    is honest -- nothing here guesses.
+    """
+    from .history import History
+    from .library import Library
+
+    out = Path(a.outdir)
+    lib = Library(out)
+    hist = History(out / ".sources.json")
+    tools = preflight.detect()
+    titles = {(i.get("video_id") or i.get("url")): i.get("title", "")
+              for i in hist.list() if i.get("title")}
+
+    fixed = tagged = probed = 0
+    for c in lib.list():
+        rec = dict(lib._index.get(c["name"], {}))
+        before = dict(rec)
+
+        if not rec.get("title"):
+            key = rec.get("video_id") or rec.get("url") or ""
+            if key and titles.get(key):
+                rec["title"] = titles[key]
+
+        # Nothing known at all? Ask the file.
+        if not rec.get("title"):
+            got = engine.provenance_from_tags(
+                engine.read_metadata(out / c["name"], tools))
+            probed += 1
+            for k, v in got.items():
+                rec.setdefault(k, v)
+
+        if rec and rec != before:
+            lib.record(c["name"], **{k: v for k, v in rec.items() if k != "created"})
+            fixed += 1
+            print(f"  {c['name']}\n      title -> {rec.get('title','') or '(still unknown)'}")
+
+        if a.tag_files and rec.get("title"):
+            meta = engine.clip_metadata(rec.get("title", ""),
+                                        rec.get("url") or rec.get("path", ""),
+                                        rec.get("start", ""), rec.get("end", ""),
+                                        Path(c["name"]).stem)
+            if stamp(out / c["name"], meta, tools):
+                tagged += 1
+
+    print(f"\n{fixed} record(s) updated, {probed} file(s) probed"
+          + (f", {tagged} file(s) tagged" if a.tag_files else ""))
+    return 0
+
+
+def stamp(path: Path, meta: dict, tools) -> bool:
+    """Write tags into an existing clip without re-encoding it."""
+    import subprocess
+    tmp = path.with_suffix(".tagging.mp4")
+    r = subprocess.run([str(tools.ffmpeg), "-nostdin", "-hide_banner",
+                        "-loglevel", "error", "-y", "-i", str(path), "-c", "copy",
+                        *engine._meta_args(meta), "-movflags", "+faststart", str(tmp)],
+                       capture_output=True, text=True)
+    if r.returncode != 0 or not tmp.exists():
+        tmp.unlink(missing_ok=True)
+        return False
+    # Keep the original timestamp: mtime is what retention ages on, and
+    # re-tagging is not the clip being made again.
+    st = path.stat()
+    tmp.replace(path)
+    os.utime(path, (st.st_atime, st.st_mtime))
+    return True
+
+
+def cmd_update(a) -> int:
+    print("overc-clips — updating video tools\n")
+    r = preflight.update_tools()
+    if not r["ok"]:
+        print(f"  FAILED: {r['error']}")
+        return 1
+    if r.get("changed"):
+        print(f"  yt-dlp {r['before']} -> {r['after']}")
+    else:
+        print(f"  yt-dlp {r['after'] or 'installed'} — already current")
+    print("\n  Done.")
+    return 0
+
+
+def cmd_serve(a) -> int:
+    from . import server
+    cfg = Config()
+    given = set(sys.argv[1:])
+    def pick(flag, attr, key):
+        return getattr(a, attr) if flag in given else cfg.data.get(key, getattr(a, attr))
+    a.port = int(pick("--port", "port", "port"))
+    a.host = pick("--host", "host", "host")
+    a.token = pick("--token", "token", "token")
+    a.keep_days = int(pick("--keep-days", "keep_days", "keep_days"))
+    if "--outdir" not in given and cfg.data.get("outdir"):
+        a.outdir = cfg.data["outdir"]
+    auto = sys.stdout.isatty() if a.open is None else a.open
+    server.serve(Path(a.outdir), host=a.host, port=a.port, token=a.token,
+                 workers=a.workers, open_browser=auto, keep_days=a.keep_days,
+                 config=cfg)
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="overc-clips",
+                                 description="Cut analysis clips from video.")
+    ap.add_argument("--version", action="version",
+                    version=f"overc-clips {_version()}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    d = sub.add_parser("doctor", help="what is installed, what is missing")
+    d.add_argument("--json", action="store_true")
+    d.set_defaults(fn=cmd_doctor)
+
+    common = dict(outdir="clips", encoder="sw")
+    for name, fn, helptext in (("cut", cmd_cut, "cut a local video"),
+                               ("grab", cmd_grab, "fetch spans from a URL")):
+        p = sub.add_parser(name, help=helptext)
+        if name == "cut":
+            p.add_argument("input")
+            g = p.add_mutually_exclusive_group(required=True)
+            g.add_argument("--range", help="HH:MM:SS-HH:MM:SS")
+            g.add_argument("--csv", help="csv: name,start,end")
+        else:
+            p.add_argument("url", nargs="?")
+            p.add_argument("--range", help="HH:MM:SS-HH:MM:SS")
+            p.add_argument("--csv", help="csv: url,name,start,end")
+        p.add_argument("--name")
+        p.add_argument("--outdir", default=common["outdir"])
+        p.add_argument("--encoder", default=common["encoder"], choices=["sw", "hw"])
+        p.add_argument("--dry-run", action="store_true")
+        p.add_argument("--json", action="store_true")
+        p.add_argument("--accurate", action="store_true")
+        p.add_argument("--copy", action="store_true")
+        p.add_argument("--quiet", action="store_true")
+        p.set_defaults(fn=fn)
+
+    bf = sub.add_parser("backfill",
+                        help="restore provenance for clips already on disk")
+    bf.add_argument("--outdir", default="clips")
+    bf.add_argument("--tag-files", action="store_true",
+                    help="also write the tags into the clips (no re-encode)")
+    bf.set_defaults(fn=cmd_backfill)
+
+    up = sub.add_parser("update",
+                        help="update yt-dlp (the usual fix when downloads fail)")
+    up.set_defaults(fn=cmd_update)
+    sv = sub.add_parser("serve", help="run the web UI")
+    sv.add_argument("--host", default="0.0.0.0",
+                    help="0.0.0.0 lets a phone on the same wifi reach it")
+    sv.add_argument("--port", type=int, default=8080)
+    sv.add_argument("--outdir", default="clips")
+    sv.add_argument("--token", default="", help="require ?token=... (use when hosted)")
+    sv.add_argument("--workers", type=int, default=1)
+    sv.add_argument("--keep-days", type=int, default=14,
+                    help="delete clips older than this many days (0 = keep forever)")
+    # Opening the browser is the point for someone who was handed a launcher,
+    # so it is the default when a person is watching. Redirected output means a
+    # service manager is running us, and popping a browser there is wrong.
+    sv.add_argument("--open", action="store_true", default=None,
+                    help="open a browser on start (default when interactive)")
+    sv.add_argument("--no-open", dest="open", action="store_false",
+                    help="never open a browser")
+    sv.set_defaults(fn=cmd_serve)
+
+    a = ap.parse_args(argv)
+    if a.cmd == "grab" and not a.url and not a.csv:
+        ap.error("grab needs a URL with --range, or --csv")
+    if a.cmd == "grab" and a.url and not a.range:
+        ap.error("grab with a URL needs --range")
+    return a.fn(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

overc_clips/config.py

@@ -0,0 +1,133 @@
+"""Saved launch options.
+
+A desktop launcher is a fixed command line, so anything you can only set with a
+flag is unreachable to the person who was handed an icon. This keeps their
+choices in a small JSON file that the CLI reads as its defaults.
+
+Precedence is flag > file > built-in, so an explicit flag always wins and a
+saved preference never silently overrides what someone typed.
+
+Two kinds of setting live here and the difference matters to the UI: retention
+and the default encoder take effect immediately, while host, port and token are
+fixed when the socket is opened and cannot change without a restart. Presenting
+those the same way would promise something the running process cannot deliver.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+from pathlib import Path
+
+DEFAULTS = {
+    "keep_days": 14,        # live
+    "encoder": "sw",        # live
+    "clip_limit": 120,      # live — seconds; 0 means the platform has no limit
+    "recent_limit": 12,     # live — how many videos "recent" keeps
+    "autosave_points": False,  # live — keep a running record of clip points
+    "port": 8080,           # restart
+    "host": "0.0.0.0",      # restart
+    "token": "",            # restart
+    "outdir": "",           # restart; empty means "decide at launch"
+}
+LIVE_KEYS = ("keep_days", "encoder", "clip_limit", "recent_limit",
+             "autosave_points")
+RESTART_KEYS = ("port", "host", "token", "outdir")
+
+
+def config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config")
+    return Path(base) / "overc-clips" / "config.json"
+
+
+class Config:
+    def __init__(self, path: Path | None = None):
+        self.path = Path(path or config_path())
+        self._lock = threading.Lock()
+        self.data = dict(DEFAULTS)
+        self.data.update(self._read())
+
+    def _read(self) -> dict:
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        # Ignore unknown keys rather than carrying them forward: a typo in a
+        # hand-edited file should not look like it took effect.
+        return {k: v for k, v in raw.items() if k in DEFAULTS}
+
+    def save(self) -> None:
+        with self._lock:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            fd, tmp = tempfile.mkstemp(dir=str(self.path.parent), suffix=".tmp")
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                    json.dump(self.data, fh, indent=1)
+                os.replace(tmp, self.path)
+            except OSError:
+                Path(tmp).unlink(missing_ok=True)
+
+    def update(self, changes: dict) -> tuple[dict, list[str]]:
+        """Apply what is valid, report what was not. -> (applied, problems)"""
+        applied, problems = {}, []
+        for k, v in (changes or {}).items():
+            if k not in DEFAULTS:
+                problems.append(f"unknown setting: {k}")
+                continue
+            try:
+                if k == "keep_days":
+                    v = int(v)
+                    # Clamping a negative to 0 would quietly switch retention
+                    # off, which is a large behaviour change to infer from a
+                    # value the user got wrong. 0 has to be asked for.
+                    if v < 0:
+                        raise ValueError("must be 0 (never) or a positive number of days")
+                elif k == "clip_limit":
+                    v = int(v)
+                    if v < 0:
+                        raise ValueError("must be 0 (no limit) or a number of seconds")
+                    if 0 < v < 10:
+                        raise ValueError("a limit under 10s would split everything to nothing")
+                elif k == "autosave_points":
+                    v = bool(v)
+                elif k == "recent_limit":
+                    v = int(v)
+                    if not 1 <= v <= 200:
+                        raise ValueError("must be between 1 and 200")
+                elif k == "port":
+                    v = int(v)
+                    if not 1 <= v <= 65535:
+                        raise ValueError("port out of range")
+                elif k == "encoder":
+                    v = str(v)
+                    if v not in ("sw", "hw"):
+                        raise ValueError("encoder must be sw or hw")
+                elif k == "outdir":
+                    v = str(v).strip().strip('"').strip("'")
+                    if v:
+                        from pathlib import Path as _P
+                        pth = _P(v).expanduser()
+                        if not pth.is_absolute():
+                            raise ValueError("use a full path")
+                        # Saving a path that cannot be created would only fail
+                        # at the next launch, when the reason is long forgotten.
+                        try:
+                            pth.mkdir(parents=True, exist_ok=True)
+                        except OSError as ex:
+                            raise ValueError(f"cannot use that folder ({ex.strerror})") from ex
+                        v = str(pth)
+                else:
+                    v = str(v)
+            except (TypeError, ValueError) as ex:
+                problems.append(f"{k}: {ex}")
+                continue
+            self.data[k] = v
+            applied[k] = v
+        if applied:
+            self.save()
+        return applied, problems
+
+    def as_dict(self) -> dict:
+        return {"values": dict(self.data), "live": list(LIVE_KEYS),
+                "restart": list(RESTART_KEYS), "path": str(self.path)}