terpsi 0.0.2__py3-none-any.whl

terpsi/__init__.py

@@ -0,0 +1,57 @@
+"""terpsi: dance corpora from single-dancer videos.
+
+A clip (a YouTube URL, a Wikimedia Commons URL, a local file) is reduced to what a
+dance model needs and nothing that a video needs: a landmark time series (body, hands,
+face, with metric 3D world coordinates where the model gives them), the audio, the
+description and metadata, the subtitles, and the timestamped text that was on screen.
+The video itself is deleted after extraction. On top of the corpus: movement-versus-music
+analysis (kinematic beats, beat alignment, phase), for dance tutors, dance games and the
+study of how bodies move to music.
+
+Five seams, each one keyword argument with a working default:
+
+- ``downloader`` (:func:`terpsi.acquire.fetch`): ``yb`` over yt-dlp.
+- ``extractor`` (:func:`terpsi.pose.extract_landmarks`): MediaPipe ``HolisticLandmarker``.
+- ``ocr`` (:func:`terpsi.screen_text.read_screen_text`): an ``ocracy`` backend.
+- ``corpus`` (:class:`terpsi.store.Corpus`): a folder under ``~/.local/share/terpsi``.
+- ``tracker`` (:func:`terpsi.audio.track_beats`): librosa's beat tracker.
+
+>>> from terpsi import ingest, Corpus  # doctest: +SKIP
+>>> clip_id = ingest("https://youtu.be/q_TUyxUhoEw")  # doctest: +SKIP
+>>> Corpus()[clip_id].report["beat_alignment"]  # doctest: +SKIP
+"""
+
+from terpsi.config import data_dir, clips_dir
+from terpsi.store import Corpus, Clip
+from terpsi.pose import (
+    LandmarkSeries,
+    extract_landmarks,
+    POSE_LANDMARKS,
+    HAND_LANDMARKS,
+)
+from terpsi.analysis import (
+    motion_energy,
+    kinematic_beats,
+    beat_alignment_score,
+    phase_concentration,
+    alignment_report,
+)
+from terpsi.pipeline import ingest, screen_clip
+
+__all__ = [
+    "data_dir",
+    "clips_dir",
+    "Corpus",
+    "Clip",
+    "LandmarkSeries",
+    "extract_landmarks",
+    "POSE_LANDMARKS",
+    "HAND_LANDMARKS",
+    "motion_energy",
+    "kinematic_beats",
+    "beat_alignment_score",
+    "phase_concentration",
+    "alignment_report",
+    "ingest",
+    "screen_clip",
+]

terpsi/__main__.py

@@ -0,0 +1,17 @@
+# PYTHON_ARGCOMPLETE_OK
+"""CLI entry point: ``python -m terpsi`` / the ``terpsi`` script, over :mod:`terpsi.tools`."""
+
+from __future__ import annotations
+
+
+def main(argv=None) -> int:
+    """Dispatch a command from :data:`terpsi.tools._dispatch_funcs` and return its exit code."""
+    import cw
+
+    from terpsi.tools import _dispatch_funcs
+
+    return cw.dispatch(_dispatch_funcs, argv, prog="terpsi")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

terpsi/acquire.py

@@ -0,0 +1,222 @@
+"""Getting a clip and its sidecars: the ``downloader`` seam.
+
+:func:`fetch` turns a source (a YouTube URL or id, a Wikimedia Commons URL, a local
+file) into a :class:`ClipFiles`: the video path plus whatever sidecars exist (yt-dlp's
+info.json, the description, subtitles). The default downloader is ``yb`` (yt-dlp with
+sidecars); a local file passes through, picking up sidecars that sit next to it.
+
+:func:`search_youtube` lists candidate clips for a query, by default restricted to the
+Creative Commons licence filter of YouTube search, so licence-clear clips come first.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Iterable
+
+PathLike = "str | Path"
+
+_YT_ID = re.compile(r"(?:v=|youtu\.be/|/shorts/|^)([A-Za-z0-9_-]{11})(?:[&?#]|$)")
+_CC_FILTER = (
+    "EgIwAQ%253D%253D"  # YouTube search 'sp' parameter: Creative Commons licence
+)
+
+
+@dataclass
+class ClipFiles:
+    """A fetched clip: the video, its id, and the sidecars that came with it."""
+
+    video: Path
+    clip_id: str
+    source: str
+    info_json: Path | None = None
+    description: Path | None = None
+    subtitles: list[Path] = field(default_factory=list)
+    downloaded: bool = False  # True when fetch() downloaded it (so it may be deleted)
+
+    @property
+    def info(self) -> dict:
+        """The yt-dlp info dict (empty when there is no info.json)."""
+        if self.info_json and self.info_json.exists():
+            return json.loads(self.info_json.read_text())
+        return {}
+
+
+def youtube_id(source: str) -> str | None:
+    """The 11-character YouTube id in ``source``, or None."""
+    m = _YT_ID.search(source)
+    return m.group(1) if m else None
+
+
+def _sidecars_next_to(video: Path) -> dict:
+    import glob as _glob
+
+    stem = video.with_suffix("")
+    esc = _glob.escape(video.stem)
+    subs = sorted(
+        Path(p) for p in _glob.glob(str(video.parent / f"{esc}.*.vtt"))
+    ) + sorted(Path(p) for p in _glob.glob(str(video.parent / f"{esc}.*.srt")))
+    info = Path(f"{stem}.info.json")
+    desc = Path(f"{stem}.description")
+    return {
+        "info_json": info if info.exists() else None,
+        "description": desc if desc.exists() else None,
+        "subtitles": subs,
+    }
+
+
+def yb_downloader(
+    source: str,
+    dest: Path,
+    *,
+    subtitle_langs: tuple[str, ...] = ("en",),
+    max_height: int | None = 720,
+    **opts,
+) -> ClipFiles:
+    """The default downloader: ``yb`` over yt-dlp, with every sidecar it can write.
+
+    ``max_height`` caps the video resolution (720 by default: landmarks are detected on
+    a 640-px frame and captions read at 1280 px, so 1080p buys nothing but bandwidth).
+    """
+    from yb.download import download_youtube_video
+
+    if max_height and "fmt" not in opts:
+        # H.264 first: OpenCV decodes it everywhere, AV1 not always (an undecodable video is an empty series)
+        h = f"[height<={max_height}]"
+        opts["fmt"] = (
+            f"bestvideo{h}[vcodec^=avc1]+bestaudio/bestvideo{h}+bestaudio/best{h}/best"
+        )
+    r = download_youtube_video(
+        source,
+        download_dir=dest,
+        write_info_json=True,
+        write_description=True,
+        write_subtitles=True,
+        write_auto_subtitles=True,
+        subtitle_langs=subtitle_langs,
+        **opts,
+    )
+    video = Path(r.path)
+    found = _sidecars_next_to(video)
+    sc = r.sidecars or {}
+    subs = sc.get("subtitles") or []
+    subs = [Path(p) for p in (subs if isinstance(subs, (list, tuple)) else [subs])]
+    clip_id = (r.info or {}).get("id") or youtube_id(source) or video.stem
+    return ClipFiles(
+        video=video,
+        clip_id=clip_id,
+        source=source,
+        info_json=Path(sc["info_json"]) if sc.get("info_json") else found["info_json"],
+        description=Path(sc["description"])
+        if sc.get("description")
+        else found["description"],
+        subtitles=subs or found["subtitles"],
+        downloaded=True,
+    )
+
+
+def fetch(
+    source: str | Path,
+    *,
+    dest: Path | None = None,
+    downloader: Callable[..., ClipFiles] | None = None,
+    **opts,
+) -> ClipFiles:
+    """Fetch ``source`` into ``dest`` and return its :class:`ClipFiles`.
+
+    A path to an existing file is returned as is (with sidecars found next to it);
+    anything else goes through ``downloader`` (default :func:`yb_downloader`).
+    """
+    p = Path(source).expanduser()
+    if p.exists():
+        found = _sidecars_next_to(p)
+        clip_id = None
+        if found["info_json"]:
+            clip_id = json.loads(found["info_json"].read_text()).get("id")
+        clip_id = clip_id or youtube_id(p.name) or _content_id(p)
+        return ClipFiles(video=p, clip_id=clip_id, source=str(p), **found)
+    from terpsi.config import videos_dir
+
+    dest = Path(dest) if dest else videos_dir()
+    dest.mkdir(parents=True, exist_ok=True)
+    downloader = downloader or yb_downloader
+    return downloader(str(source), dest, **opts)
+
+
+def _content_id(path: Path) -> str:
+    """A stable id for a local file with no platform id: the sha256 prefix of its bytes."""
+    import hashlib
+
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return "local_" + h.hexdigest()[:12]
+
+
+def expand_playlist(url: str, *, n: int | None = None) -> list[str]:
+    """The video URLs of a YouTube playlist (flat extraction, nothing downloaded)."""
+    import yt_dlp
+
+    opts = {"quiet": True, "extract_flat": True, "no_warnings": True}
+    if n:
+        opts["playlistend"] = n
+    with yt_dlp.YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(url, download=False)
+    return [
+        f"https://www.youtube.com/watch?v={e['id']}"
+        for e in (info.get("entries") or [])
+        if e.get("id")
+    ]
+
+
+def is_playlist(source: str) -> bool:
+    """Whether ``source`` is a YouTube playlist URL (``list=`` without a video id)."""
+    return "list=" in str(source) and youtube_id(str(source)) is None
+
+
+def search_youtube(
+    query: str,
+    *,
+    n: int = 20,
+    creative_commons: bool = True,
+    min_s: float = 30,
+    max_s: float = 900,
+) -> list[dict]:
+    """Candidate clips for ``query`` from YouTube search, as flat dicts.
+
+    With ``creative_commons`` (default) the search carries YouTube's own CC-licence
+    filter, so every hit is declared reusable by its uploader (yt-dlp's ``license``
+    field on the full info confirms it per clip). Durations outside ``[min_s, max_s]``
+    (shorts, full classes) are dropped.
+    """
+    from urllib.parse import quote_plus
+
+    import yt_dlp
+
+    url = f"https://www.youtube.com/results?search_query={quote_plus(query)}"
+    if creative_commons:
+        url += f"&sp={_CC_FILTER}"
+    opts = {"quiet": True, "extract_flat": True, "playlistend": n, "no_warnings": True}
+    with yt_dlp.YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(url, download=False)
+    out = []
+    for e in info.get("entries") or []:
+        d = e.get("duration")
+        if d is None or not (min_s <= d <= max_s):
+            continue
+        out.append(
+            {
+                "id": e.get("id"),
+                "title": e.get("title"),
+                "duration": d,
+                "view_count": e.get("view_count"),
+                "channel": e.get("channel") or e.get("uploader"),
+                "url": f"https://www.youtube.com/watch?v={e.get('id')}",
+                "query": query,
+            }
+        )
+    return out