openpod 0.1.0__py3-none-any.whl

openpod/__init__.py

@@ -0,0 +1,48 @@
+"""OpenPod — local-first briefings for long-form audio & video.
+
+Everything in this package runs on the user's own machine. Nothing is uploaded
+to an OpenPod server; the only "corpus" is the user's local library on disk.
+
+Public API surface (kept small on purpose):
+
+    from openpod import Transcript, Cue, SourceRef, Workspace, Library
+    from openpod import catch, search, clip
+"""
+
+from __future__ import annotations
+
+from .models import Cue, Idea, SearchHit, SourceRef, Transcript
+from .config import Workspace
+from .library import Library, LibraryEntry
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Cue",
+    "Transcript",
+    "SourceRef",
+    "Idea",
+    "SearchHit",
+    "Workspace",
+    "Library",
+    "LibraryEntry",
+]
+
+
+def __getattr__(name: str):
+    # Lazily expose the high-level verbs so importing the package doesn't drag
+    # in ingestion / search machinery until it's actually used.
+    if name == "catch":
+        from .catch import catch
+
+        return catch
+    if name == "search":
+        from .search import search
+
+        return search
+    if name == "clip":
+        from .clip import clip
+
+        return clip
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openpod/align.py

@@ -0,0 +1,249 @@
+"""Cross-source timestamp alignment — probe-and-bisect.
+
+A transcript fetched from the fastest source (usually YouTube captions)
+doesn't necessarily line up with the same episode's audio on the platform
+the user pasted: intros get trimmed, ads get inserted. The offset between
+two versions is **piecewise-constant** — it jumps at each ad break and is
+flat in between — so the whole map can be recovered with a handful of
+cheap probes:
+
+1. Probe ``offset(t)`` near the start and end (a probe = transcribe or
+   fingerprint a ~15s window of the target audio and locate its text in the
+   reference transcript).
+2. Equal offsets → constant in between; done in two probes.
+3. Different → binary-search the jump point and recurse. O(log n) probes
+   per ad break, ~10–20 probes for a typical episode.
+
+The map is computed once per (episode, source-pair) and cached on the
+crosswalk record. When alignment can't be trusted end-to-end (Spotify
+re-hosts audio and may inject per-listener ads — we can never fetch the
+exact stream a user hears), callers keep the ``approximate`` precision flag;
+alignment narrows the error, honesty stays.
+
+The probe is injected as a callable so the algorithm is testable without
+audio; :func:`asr_probe` builds the real one from ffmpeg + faster-whisper.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+from .models import Transcript
+
+# offset(t) for a probe time t in the *target* audio; None = probe failed
+# (silence, music, ad content not present in the reference transcript).
+ProbeFn = Callable[[float], Optional[float]]
+
+# Offsets closer than this are "the same" (caption timing jitter).
+TOLERANCE = 3.0
+# Don't bisect intervals shorter than this — pin the jump to the midpoint.
+MIN_INTERVAL = 30.0
+
+
+@dataclass
+class OffsetMap:
+    """Piecewise-constant mapping: target-audio time -> reference offset.
+
+    ``points`` is ``[(start_t, offset), ...]`` sorted by ``start_t``; the
+    offset applies from ``start_t`` until the next point. ``map_time(t)``
+    answers "reference transcript time t lands where in the target audio?"
+    via the inverse shift.
+    """
+
+    points: list = field(default_factory=list)   # [(t, offset), ...]
+    probes_used: int = 0
+    complete: bool = True    # False when some probes failed and gaps remain
+
+    def offset_at(self, t: float) -> Optional[float]:
+        chosen = None
+        for start_t, off in self.points:
+            if t >= start_t:
+                chosen = off
+            else:
+                break
+        return chosen
+
+    def to_target(self, reference_seconds: float) -> Optional[float]:
+        """Map a reference-transcript time onto the target audio."""
+        # points are in target-time; invert by scanning segments.
+        for start_t, off in reversed(self.points):
+            if reference_seconds >= start_t + off:
+                return reference_seconds - off
+        if self.points:
+            return reference_seconds - self.points[0][1]
+        return None
+
+    def to_list(self) -> list:
+        return [[round(t, 3), round(o, 3)] for t, o in self.points]
+
+    @classmethod
+    def from_list(cls, data: list) -> "OffsetMap":
+        return cls(points=[(float(t), float(o)) for t, o in data])
+
+
+def compute_offset_map(probe: ProbeFn, duration: float, *,
+                       tolerance: float = TOLERANCE,
+                       min_interval: float = MIN_INTERVAL,
+                       max_probes: int = 40) -> OffsetMap:
+    """Recover the piecewise-constant offset map with probe-and-bisect."""
+    state = {"probes": 0, "failed": 0}
+
+    def _probe(t: float) -> Optional[float]:
+        if state["probes"] >= max_probes:
+            return None
+        state["probes"] += 1
+        off = probe(t)
+        if off is None:
+            state["failed"] += 1
+        return off
+
+    lo_t = min(30.0, duration * 0.02)
+    hi_t = max(duration - 60.0, duration * 0.9)
+    lo = _probe(lo_t)
+    hi = _probe(hi_t)
+
+    points: list[tuple[float, float]] = []
+    complete = True
+
+    if lo is None and hi is None:
+        return OffsetMap(points=[], probes_used=state["probes"], complete=False)
+    if lo is None:
+        lo, complete = hi, False
+    if hi is None:
+        hi, complete = lo, False
+
+    points.append((0.0, lo))
+
+    def _bisect(t1: float, off1: float, t2: float, off2: float) -> None:
+        nonlocal complete
+        if abs(off1 - off2) <= tolerance:
+            return
+        if t2 - t1 <= min_interval:
+            # Pin the jump at the interval midpoint — good to ±min_interval/2.
+            points.append((round((t1 + t2) / 2, 3), off2))
+            return
+        mid = (t1 + t2) / 2
+        off_mid = _probe(mid)
+        if off_mid is None:
+            # Can't see into this interval; place the jump at mid but flag it.
+            complete = False
+            points.append((round(mid, 3), off2))
+            return
+        _bisect(t1, off1, mid, off_mid)
+        _bisect(mid, off_mid, t2, off2)
+
+    _bisect(lo_t, lo, hi_t, hi)
+    points.sort(key=lambda p: p[0])
+    # Collapse consecutive points with ~equal offsets.
+    deduped: list[tuple[float, float]] = []
+    for t, off in points:
+        if deduped and abs(deduped[-1][1] - off) <= tolerance:
+            continue
+        deduped.append((t, off))
+    return OffsetMap(points=deduped, probes_used=state["probes"],
+                     complete=complete)
+
+
+# --------------------------------------------------------------------------- #
+# The real probe: ffmpeg window -> ASR -> locate text in reference transcript
+# --------------------------------------------------------------------------- #
+
+_word_re = re.compile(r"[a-z0-9']+")
+
+
+def _words(text: str) -> list[str]:
+    return _word_re.findall(text.lower())
+
+
+def locate_text(reference: Transcript, words: list[str], *,
+                min_overlap: float = 0.6) -> Optional[float]:
+    """Find where a probe's word sequence occurs in the reference transcript.
+
+    Slides over cue windows comparing word overlap; returns the reference
+    time where the sequence starts, or None when nothing matches well
+    (music, an inserted ad, ASR noise).
+    """
+    if len(words) < 5:
+        return None
+    target = set(words)
+    best_t, best_score = None, 0.0
+    cues = reference.cues
+    for i, cue in enumerate(cues):
+        # A window of roughly the probe's own length: generous windows make
+        # the *preceding* cue score as well as the right one.
+        window_words: list[str] = []
+        j = i
+        while j < len(cues) and len(window_words) < len(words) + 3:
+            window_words.extend(_words(cues[j].text))
+            j += 1
+        if not window_words:
+            continue
+        overlap = len(target & set(window_words[:len(words) + 3])) / len(target)
+        if overlap > best_score:
+            best_score, best_t = overlap, cue.start
+    if best_score < min_overlap:
+        return None
+    return best_t
+
+
+def asr_probe(target_media: str, reference: Transcript, *,
+              window: float = 15.0, model: str = "base") -> ProbeFn:
+    """Build a real probe: cut ``window`` seconds at t from ``target_media``
+    (ffmpeg), transcribe it locally, and locate the words in ``reference``.
+
+    ``offset = reference_time - t``: positive offset means the reference
+    transcript runs *ahead* of the target audio at that point.
+    """
+    from .asr import transcribe
+
+    def probe(t: float) -> Optional[float]:
+        with tempfile.TemporaryDirectory(prefix="openpod-align-") as td:
+            snippet = Path(td) / "probe.wav"
+            cmd = ["ffmpeg", "-y", "-ss", f"{t:.2f}", "-t", f"{window:.2f}",
+                   "-i", target_media, "-ac", "1", "-ar", "16000",
+                   str(snippet)]
+            proc = subprocess.run(cmd, capture_output=True)
+            if proc.returncode != 0 or not snippet.exists():
+                return None
+            try:
+                heard = transcribe(str(snippet), model=model)
+            except Exception:
+                return None
+        words = _words(heard.text())
+        ref_t = locate_text(reference, words)
+        if ref_t is None:
+            return None
+        return ref_t - t
+
+    return probe
+
+
+def align_entry(entry, target_media: str, *,
+                source_kind: str = "youtube") -> Optional[OffsetMap]:
+    """Align a caught entry's transcript against a target audio file and
+    persist the map on the entry's crosswalk record (keyed by the
+    transcript-source kind)."""
+    transcript = entry.read_transcript()
+    if transcript is None or not len(transcript):
+        return None
+    duration = transcript.duration
+    probe = asr_probe(target_media, transcript)
+    omap = compute_offset_map(probe, duration)
+
+    meta = entry.read_meta()
+    key = meta.get("episode_key")
+    if key:
+        from .config import Workspace
+        from .crosswalk import Crosswalk
+
+        cw = Crosswalk(entry.workspace)
+        ident = cw.get(key)
+        if ident is not None:
+            ident.offset_maps[source_kind] = omap.to_list()
+            cw.put(ident)
+    return omap

openpod/asr.py

@@ -0,0 +1,164 @@
+"""Local ASR fallback and audio download.
+
+Transcription runs on the user's own hardware via ``faster-whisper`` (install the
+``asr`` extra). This keeps the free path at $0 company COGS — no audio ever
+leaves the machine. Both helpers raise a clear, actionable error when their
+optional dependency / system tool is missing.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+from .models import Cue, Transcript
+
+_UA = {"User-Agent": "OpenPod/0.1 (+https://github.com/openpodhq/openpod)"}
+
+
+class DependencyMissing(RuntimeError):
+    """Raised when an optional dependency needed for a path isn't installed."""
+
+
+def transcribe(audio_path: str, *, model: str = "base",
+               language: Optional[str] = None) -> Transcript:
+    """Transcribe a local audio/video file with faster-whisper.
+
+    Produces segment-level cues (good for navigation). For frame-accurate clip
+    cutting, ``clip`` re-aligns a narrow window at higher precision.
+    """
+    try:
+        from faster_whisper import WhisperModel  # type: ignore
+    except ImportError as e:  # pragma: no cover - depends on env
+        raise DependencyMissing(
+            "Local transcription needs faster-whisper. Install it with:\n"
+            "    pip install 'openpod[asr]'\n"
+            "or supply a transcript directly with --transcript."
+        ) from e
+
+    model_name = os.environ.get("OPENPOD_WHISPER_MODEL", model)
+    whisper = WhisperModel(model_name, device="auto", compute_type="auto")
+    segments, info = whisper.transcribe(audio_path, language=language, vad_filter=True)
+    cues = [
+        Cue(start=float(s.start), end=float(s.end), text=s.text.strip())
+        for s in segments
+        if s.text.strip()
+    ]
+    return Transcript(
+        cues=cues,
+        source=f"asr:whisper-{model_name}",
+        language=getattr(info, "language", language),
+        word_level=False,
+    )
+
+
+def download_audio(url: str, *, dest_dir: Optional[str] = None) -> str:
+    """Download audio to a local file, returning its path.
+
+    Uses ``yt-dlp`` for streaming sites (YouTube etc.) and a plain HTTP GET for
+    direct podcast enclosures.
+    """
+    dest_dir = dest_dir or tempfile.mkdtemp(prefix="openpod-audio-")
+    Path(dest_dir).mkdir(parents=True, exist_ok=True)
+
+    # Direct enclosure: validate the content type, then fetch the terminal
+    # URL (tracking redirectors resolved once, not on every request).
+    fetch_url, ext = url, None
+    if url.lower().split("?")[0].endswith((".mp3", ".m4a", ".aac", ".ogg", ".wav")):
+        ext = url.lower().split("?")[0].rsplit(".", 1)[-1]
+    elif url.lower().startswith(("http://", "https://")):
+        # No recognizable extension (e.g. a chrt.fm-style redirector): sniff
+        # what it actually serves instead of guessing.
+        from .ingest.validate import sniff
+
+        info = sniff(url)
+        if info.kind == "audio":
+            fetch_url = info.url
+            ext = (info.content_type or "audio/mpeg").split("/")[-1].split(";")[0]
+            ext = {"mpeg": "mp3", "mp4": "m4a", "x-m4a": "m4a"}.get(ext, ext)
+
+    if ext:
+        out = Path(dest_dir) / f"audio.{ext}"
+        req = urllib.request.Request(fetch_url, headers=_UA)
+        with urllib.request.urlopen(req, timeout=120) as resp, out.open("wb") as fh:  # noqa: S310
+            shutil.copyfileobj(resp, fh)
+        return str(out)
+
+    # Otherwise defer to yt-dlp.
+    try:
+        import yt_dlp  # type: ignore
+    except ImportError as e:
+        raise DependencyMissing(
+            "Downloading from this source needs yt-dlp. Install it with:\n"
+            "    pip install 'openpod[youtube]'"
+        ) from e
+
+    out_tmpl = str(Path(dest_dir) / "audio.%(ext)s")
+    opts = {
+        "format": "bestaudio/best",
+        "outtmpl": out_tmpl,
+        "quiet": True,
+        "no_warnings": True,
+        "noplaylist": True,
+    }
+    with yt_dlp.YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(url, download=True)
+        return ydl.prepare_filename(info)
+
+
+def estimate_transcription(duration: Optional[float],
+                           model: str = "base") -> dict:
+    """Rough wall-clock estimate for local Whisper on typical hardware.
+
+    Deliberately a *range* — CPU/GPU spread is wide. The point is honesty
+    at the moment of decision ("~9–25 min for this episode"), not precision.
+    """
+    # Realtime factors per model size (fraction of audio duration), low/high.
+    factors = {"tiny": (0.03, 0.10), "base": (0.05, 0.20),
+               "small": (0.10, 0.35), "medium": (0.25, 0.80),
+               "large": (0.5, 1.5)}
+    lo_f, hi_f = factors.get(model.split("-")[0], (0.05, 0.20))
+    if not duration:
+        return {"model": model, "human": "several minutes (unknown duration)"}
+    lo, hi = duration * lo_f, duration * hi_f
+
+    def _m(s: float) -> str:
+        return f"{max(1, round(s / 60))} min" if s >= 45 else f"{round(s)}s"
+
+    return {"model": model, "low_seconds": round(lo), "high_seconds": round(hi),
+            "human": f"{_m(lo)}–{_m(hi)}"}
+
+
+def has_ffmpeg() -> bool:
+    return shutil.which("ffmpeg") is not None
+
+
+_ffmpeg_caps: Optional[dict] = None
+
+
+def ffmpeg_capabilities(*, refresh: bool = False) -> dict:
+    """What this ffmpeg build can actually do, probed once.
+
+    Homebrew builds routinely ship without libass/drawtext; anything that
+    promises burned-in text must check here first and degrade honestly
+    (sidecar captions) instead of failing mid-encode.
+    """
+    global _ffmpeg_caps
+    if _ffmpeg_caps is not None and not refresh:
+        return _ffmpeg_caps
+    caps = {"ffmpeg": has_ffmpeg(), "subtitles": False, "drawtext": False}
+    if caps["ffmpeg"]:
+        try:
+            out = subprocess.run(["ffmpeg", "-hide_banner", "-filters"],
+                                 capture_output=True, text=True, timeout=15).stdout
+            caps["subtitles"] = " subtitles " in out
+            caps["drawtext"] = " drawtext " in out
+        except Exception:
+            pass
+    _ffmpeg_caps = caps
+    return caps

openpod/brand/banner.txt

@@ -0,0 +1,4 @@
+  ┌─────────────────────────────────────────────────────────┐
+  │  ▸ OpenPod   pull the ten minutes that matter — to you  │
+  └─────────────────────────────────────────────────────────┘
+     v0.1 · local & private · run  openpod skills  to begin

openpod/brand/brand-tokens.json

@@ -0,0 +1,69 @@
+{
+  "name": "OpenPod",
+  "wordmark": "OpenPod",
+  "cli_command": "openpod",
+  "tagline": "Pull the ten minutes that matter — to you.",
+  "principle": "Black, white, and one blue. The blue only ever marks the moment.",
+  "color": {
+    "ink": {
+      "hex": "#0E0E0E",
+      "role": "foreground on light / background on dark"
+    },
+    "paper": {
+      "hex": "#FCFCFB",
+      "role": "background on light"
+    },
+    "blue_light": {
+      "hex": "#0969DA",
+      "role": "accent on white (GitHub light link token)",
+      "ansi_256": 33,
+      "ansi_24bit": "38;2;9;105;218"
+    },
+    "blue_dark": {
+      "hex": "#58A6FF",
+      "role": "accent on near-black (GitHub dark link token)",
+      "ansi_256": 75,
+      "ansi_24bit": "38;2;88;166;255"
+    }
+  },
+  "accent_rule": "Reserve blue for timestamps, deep-links, the jump affordance, and the CTA. Nothing else.",
+  "type": {
+    "mono": {
+      "family": "IBM Plex Mono",
+      "weights": [
+        400,
+        500,
+        600
+      ],
+      "license": "OFL",
+      "role": "product's native tongue — CLI, timestamps, paths, UI labels"
+    },
+    "sans": {
+      "family": "IBM Plex Sans",
+      "weights": [
+        400,
+        500,
+        600,
+        700
+      ],
+      "license": "OFL",
+      "role": "headlines & captions"
+    }
+  },
+  "signature": {
+    "glyph": "▸",
+    "unicode": "U+25B8",
+    "pattern": "▸ m:ss",
+    "examples": [
+      "▸ 12:34",
+      "▸ 41:07"
+    ],
+    "rule": "Always blue, always a live deep-link. The one visual idea we own."
+  },
+  "logo": {
+    "concept": "playhead landing on a position line (jump-to-moment)",
+    "viewBox": "0 0 24 24",
+    "clear_space": "the height of the playhead triangle on every side",
+    "reproduction": "one-color first (black / white / blue); full-color is the exception"
+  }
+}

openpod/brand/card-template.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>{{EPISODE}} — OpenPod</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body { background: {{PAPER}}; }
+  .op-mono { font-family: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .op-sans { font-family: 'IBM Plex Sans', system-ui, -apple-system, sans-serif; }
+</style>
+</head>
+<body>
+<div class="op-mono" style="width:1200px; height:630px; background:{{PAPER}}; overflow:hidden;">
+  <div style="height:100%; padding:60px 64px; display:flex; flex-direction:column; justify-content:space-between;">
+    <div>
+      <div style="font-size:16px; letter-spacing:0.24em; text-transform:uppercase; color:{{INK}}; font-weight:600; margin-bottom:10px;">{{SHOW}}</div>
+      <div class="op-sans" style="font-size:22px; color:#4a4a48; font-weight:500;">{{EPISODE}}</div>
+      <div style="width:52px; height:2px; background:#d8d8d5; margin-top:22px;"></div>
+    </div>
+    <div style="max-width:940px;">
+      <div class="op-sans" style="font-weight:600; font-size:44px; line-height:1.16; letter-spacing:-0.018em; color:{{INK}};">&ldquo;{{QUOTE}}&rdquo;</div>
+    </div>
+    <div style="display:flex; align-items:flex-end; justify-content:space-between;">
+      {{MOMENT_BLOCK}}
+      <a href="{{BACKLINK}}" style="display:flex; align-items:center; gap:8px; color:#8a8a88; text-decoration:none;">
+        <svg viewBox="0 0 24 24" width="15" height="15" fill="none"><path d="M6 5 L15 12 L6 19 Z" fill="currentColor"></path><rect x="18" y="4" width="2.6" height="16" fill="currentColor"></rect></svg>
+        <span style="font-size:13px;">cited with <span style="color:#5a5a58; font-weight:500;">OpenPod</span></span>
+      </a>
+    </div>
+  </div>
+</div>
+</body>
+</html>