overc-clips 0.1.0__tar.gz

overc_clips-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Bruce Ashfield
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

overc_clips-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: overc-clips
+Version: 0.1.0
+Summary: Cut volleyball analysis clips from video, locally or hosted. Web UI, no command line required.
+Author-email: Bruce Ashfield <bruce.ashfield@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://zedd.org/overc-clips/
+Project-URL: Source, https://gitlab.com/bruce-ashfield/volleyball
+Keywords: video,clips,volleyball,coaching,ffmpeg,yt-dlp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yt-dlp>=2024.1.1
+Requires-Dist: imageio-ffmpeg>=0.5
+Dynamic: license-file
+
+# overc-clips
+
+Cut analysis clips out of a YouTube video or a local file, through a web page,
+with no command line required.
+
+Built for volleyball coaches handing clips to video-review sites, but there is
+nothing sport-specific in it. Point it at a video, mark the spans you want, and
+it produces the clips.
+
+It runs two ways from one codebase:
+
+- **On your own machine.** It starts a small web server and prints an address.
+  Open that in a browser on the same machine, or on your phone if you are on the
+  same wifi. The video processing happens on your computer; the phone is only
+  the remote control.
+- **Hosted**, like any other internal web app.
+
+## What you need
+
+**Python 3.10 or newer. That is all.** ffmpeg and yt-dlp come with it — the
+install pulls a static ffmpeg build, so there is nothing to install separately
+and nothing to put on your PATH.
+
+Works on macOS, Linux and Windows.
+
+## Install
+
+```bash
+pip install overc-clips
+```
+
+On current macOS and most Linux distributions that will refuse with a message
+about an "externally managed environment" — that is the operating system
+protecting its own Python, not an error in this package. Use a virtualenv:
+
+```bash
+python3 -m venv ~/.local/share/overc-clips/venv
+~/.local/share/overc-clips/venv/bin/pip install overc-clips
+~/.local/share/overc-clips/venv/bin/overc-clips serve
+```
+
+or install it with `pipx`, which does the same thing for you:
+
+```bash
+pipx install overc-clips
+```
+
+## Use it
+
+```bash
+overc-clips serve              # start the web UI, print the address to visit
+overc-clips doctor             # what it found on this machine, and what is missing
+```
+
+`serve` prints a local address and, if it can, a second one for other devices on
+your network. Everything else happens in the browser: paste a video link, scrub
+to the start and end of each clip, and make them.
+
+Useful flags:
+
+```bash
+overc-clips serve --outdir ~/Movies/clips   # where clips are written
+overc-clips serve --port 8080               # default
+overc-clips serve --token secret            # require a token, for a shared network
+```
+
+Settings you would otherwise need a flag for — the output folder, how long clips
+are kept, the maximum clip length — are in the web UI itself, so someone who was
+handed a desktop shortcut can still change them.
+
+## Clips
+
+Clips are named after the source video and their timestamps, so two cuts from
+one match never collide. Where each clip came from is written into the file as
+mp4 metadata, which survives the file being moved or shared, and the built-in
+library can group, search and file them.
+
+Clips are deleted after 14 days by default, which the UI tells you on startup
+and lets you change or switch off.
+
+## Keeping it working
+
+YouTube changes things regularly and an out-of-date yt-dlp is the usual cause of
+a download that suddenly fails. Updating it is independent of this package:
+
+```bash
+pip install -U yt-dlp        # in whichever environment you installed into
+```
+
+`overc-clips doctor` reports the version it is using and where it came from.
+
+## Licence
+
+BSD 3-Clause. See `LICENSE`.

overc_clips-0.1.0/README.md

@@ -0,0 +1,94 @@
+# overc-clips
+
+Cut analysis clips out of a YouTube video or a local file, through a web page,
+with no command line required.
+
+Built for volleyball coaches handing clips to video-review sites, but there is
+nothing sport-specific in it. Point it at a video, mark the spans you want, and
+it produces the clips.
+
+It runs two ways from one codebase:
+
+- **On your own machine.** It starts a small web server and prints an address.
+  Open that in a browser on the same machine, or on your phone if you are on the
+  same wifi. The video processing happens on your computer; the phone is only
+  the remote control.
+- **Hosted**, like any other internal web app.
+
+## What you need
+
+**Python 3.10 or newer. That is all.** ffmpeg and yt-dlp come with it — the
+install pulls a static ffmpeg build, so there is nothing to install separately
+and nothing to put on your PATH.
+
+Works on macOS, Linux and Windows.
+
+## Install
+
+```bash
+pip install overc-clips
+```
+
+On current macOS and most Linux distributions that will refuse with a message
+about an "externally managed environment" — that is the operating system
+protecting its own Python, not an error in this package. Use a virtualenv:
+
+```bash
+python3 -m venv ~/.local/share/overc-clips/venv
+~/.local/share/overc-clips/venv/bin/pip install overc-clips
+~/.local/share/overc-clips/venv/bin/overc-clips serve
+```
+
+or install it with `pipx`, which does the same thing for you:
+
+```bash
+pipx install overc-clips
+```
+
+## Use it
+
+```bash
+overc-clips serve              # start the web UI, print the address to visit
+overc-clips doctor             # what it found on this machine, and what is missing
+```
+
+`serve` prints a local address and, if it can, a second one for other devices on
+your network. Everything else happens in the browser: paste a video link, scrub
+to the start and end of each clip, and make them.
+
+Useful flags:
+
+```bash
+overc-clips serve --outdir ~/Movies/clips   # where clips are written
+overc-clips serve --port 8080               # default
+overc-clips serve --token secret            # require a token, for a shared network
+```
+
+Settings you would otherwise need a flag for — the output folder, how long clips
+are kept, the maximum clip length — are in the web UI itself, so someone who was
+handed a desktop shortcut can still change them.
+
+## Clips
+
+Clips are named after the source video and their timestamps, so two cuts from
+one match never collide. Where each clip came from is written into the file as
+mp4 metadata, which survives the file being moved or shared, and the built-in
+library can group, search and file them.
+
+Clips are deleted after 14 days by default, which the UI tells you on startup
+and lets you change or switch off.
+
+## Keeping it working
+
+YouTube changes things regularly and an out-of-date yt-dlp is the usual cause of
+a download that suddenly fails. Updating it is independent of this package:
+
+```bash
+pip install -U yt-dlp        # in whichever environment you installed into
+```
+
+`overc-clips doctor` reports the version it is using and where it came from.
+
+## Licence
+
+BSD 3-Clause. See `LICENSE`.

overc_clips-0.1.0/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())