videoxplainer 0.3.3__py3-none-any.whl

videoxplainer/__init__.py

@@ -0,0 +1,3 @@
+"""videoxplainer - token-budgeted, evidence-checked action briefs from videos."""
+
+__version__ = "0.3.3"

videoxplainer/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

videoxplainer/budget.py

@@ -0,0 +1,198 @@
+"""Token budgeting: fit a transcript into N tokens, spread across sections.
+
+Extractive and lossy by design: when the transcript exceeds the budget we keep
+the highest-information passages from every section of the video (TF-IDF
+within the transcript), in original order, with their timestamps. Sections are
+YouTube chapters when the video has them, otherwise auto-detected topics.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from typing import Dict, List, Set, Tuple
+
+from .model import Group, Paragraph
+from .textutil import words
+
+STOPWORDS = frozenset(
+    "the and but for with from are was were been this that these those you your "
+    "our their they them his her its not does did have has had will would can "
+    "could just like really very about into than then there here what which who "
+    "when how also because going know yeah okay right".split()
+)
+_TS_OVERHEAD = 4  # tokens for the "[mm:ss] " prefix
+_MIN_WORDS = 8  # shorter fragments ("the", "that went viral") are noise
+_MIN_INFO = 4  # ...and so are passages with fewer informative words than this
+HEADING_COST = 12  # tokens reserved per section heading
+
+
+def estimate_tokens(text: str) -> int:
+    """Cheap, deliberately conservative estimate; fine for budgeting, not billing.
+
+    Latin text is about 4 characters per token. Other scripts (Tamil, Hindi,
+    Cyrillic, CJK...) need many more tokens per character, so non-ASCII
+    characters are counted at 1.5 per token to stay under a budget.
+    """
+    if not text:
+        return 0
+    ascii_chars = sum(1 for ch in text if ord(ch) < 128)
+    return math.ceil(ascii_chars / 4 + (len(text) - ascii_chars) / 1.5)
+
+
+def _cost(text: str) -> int:
+    return estimate_tokens(text) + _TS_OVERHEAD
+
+
+def informative_words(text: str) -> List[str]:
+    return [w for w in words(text) if len(w) > 2 and w not in STOPWORDS]
+
+
+def _eligible(text: str) -> bool:
+    return len(text.split()) >= _MIN_WORDS and len(informative_words(text)) >= _MIN_INFO
+
+
+def _units(paragraphs: List[Paragraph], max_words: int = 60) -> List[Paragraph]:
+    units: List[Paragraph] = []
+    for para in paragraphs:
+        buf: List[str] = []
+        for sentence in re.split(r"(?<=[.!?])\s+", para.text):
+            words = sentence.split()
+            if not words:
+                continue
+            if len(words) > max_words:  # unpunctuated auto-captions
+                if buf:
+                    units.append(Paragraph(para.start, " ".join(buf)))
+                    buf = []
+                for i in range(0, len(words), max_words):
+                    units.append(Paragraph(para.start, " ".join(words[i : i + max_words])))
+                continue
+            if buf and len(buf) + len(words) > max_words:
+                units.append(Paragraph(para.start, " ".join(buf)))
+                buf = []
+            buf.extend(words)
+        if buf:
+            units.append(Paragraph(para.start, " ".join(buf)))
+    return units
+
+
+def _scores(units: List[Paragraph]) -> List[float]:
+    tokens = [informative_words(u.text) for u in units]
+    df: Counter = Counter()
+    for toks in tokens:
+        df.update(set(toks))
+    n = len(units)
+    out = []
+    for toks in tokens:
+        tf = Counter(toks)
+        raw = sum(c * math.log(1 + n / df[w]) for w, c in tf.items())
+        out.append(raw / (max(len(toks), 1) ** 0.7))
+    return out
+
+
+def _select(indices: List[int], alloc: float, scores, costs, eligible: Set[int], max_buckets: int) -> Tuple[Set[int], int]:
+    """Pick the best units within `alloc` tokens, spread over the index range."""
+    # never pad a section with junk: a section with nothing worth quoting is simply dropped
+    cand = [i for i in indices if i in eligible]
+    if not cand or alloc <= 0:
+        return set(), 0
+    avg = sum(costs[i] for i in cand) / len(cand)
+    # With a small allocation we cannot afford many slices: use as many as fit.
+    buckets = max(1, min(max_buckets, int(alloc // max(avg, 1))))
+    per = math.ceil(len(cand) / buckets)
+    share = alloc / buckets
+    chosen: Set[int] = set()
+    spent = 0
+    for k in range(buckets):
+        part = cand[k * per : (k + 1) * per]
+        used = 0
+        for rank, i in enumerate(sorted(part, key=lambda j: scores[j], reverse=True)):
+            # every slice gets its single best unit, so coverage never collapses
+            if (rank == 0 or used + costs[i] <= share) and spent + costs[i] <= alloc:
+                chosen.add(i)
+                used += costs[i]
+                spent += costs[i]
+    for i in sorted((j for j in cand if j not in chosen), key=lambda j: scores[j], reverse=True):
+        if spent + costs[i] <= alloc:
+            chosen.add(i)
+            spent += costs[i]
+    return chosen, spent
+
+
+def _merge(units: List[Paragraph], chosen_sorted: List[int]) -> List[Paragraph]:
+    merged: List[Paragraph] = []
+    prev = None
+    for i in chosen_sorted:
+        if prev is not None and i == prev + 1:
+            merged[-1] = Paragraph(merged[-1].start, merged[-1].text + " " + units[i].text)
+        else:
+            merged.append(Paragraph(units[i].start, units[i].text))
+        prev = i
+    return merged
+
+
+def fit_groups(groups: List[Group], budget: int, heading_cost: int = 0, max_buckets: int = 6) -> Tuple[List[Group], Dict[str, object]]:
+    """Condense sections to `budget` tokens; each section keeps a share of it."""
+    units: List[Paragraph] = []
+    owner: List[int] = []
+    for gi, g in enumerate(groups):
+        for u in _units(g.paragraphs):
+            units.append(u)
+            owner.append(gi)
+    costs = [_cost(u.text) for u in units]
+    full = sum(costs) + heading_cost * len(groups)
+    stats: Dict[str, object] = {"full_tokens": full, "budget": budget, "trimmed": False, "sections": len(groups)}
+    if budget <= 0 or full <= budget:
+        stats["kept_tokens"] = full
+        return groups, stats
+
+    scores = _scores(units)
+    eligible = {i for i, u in enumerate(units) if _eligible(u.text)} or set(range(len(units)))
+    members = [[i for i, o in enumerate(owner) if o == gi] for gi in range(len(groups))]
+    gcost = [sum(costs[i] for i in m) for m in members]
+    avail = budget - heading_cost * len(groups)
+
+    # Floor: roughly one average passage per section, biggest sections first while budget lasts.
+    floors = [0] * len(groups)
+    remaining = avail
+    for gi in sorted(range(len(groups)), key=lambda g: gcost[g], reverse=True):
+        if not members[gi]:
+            continue
+        floor = min(gcost[gi], math.ceil(gcost[gi] / len(members[gi])))
+        if floor <= remaining:
+            floors[gi] = floor
+            remaining -= floor
+    live = [gi for gi in range(len(groups)) if floors[gi]]
+    live_cost = sum(gcost[g] for g in live) or 1
+    chosen: Set[int] = set()
+    spent = 0
+    for gi in live:
+        alloc = floors[gi] + remaining * gcost[gi] / live_cost  # rest is proportional to length
+        c, s = _select(members[gi], alloc, scores, costs, eligible, max_buckets)
+        chosen |= c
+        spent += s
+    live_set = set(live)
+    for i in sorted((j for j in eligible if j not in chosen and owner[j] in live_set), key=lambda j: scores[j], reverse=True):
+        if spent + costs[i] <= avail:
+            chosen.add(i)
+            spent += costs[i]
+
+    out: List[Group] = []
+    for gi in live:
+        picked = sorted(i for i in chosen if owner[i] == gi)
+        if picked:
+            out.append(Group(groups[gi].title, groups[gi].start, _merge(units, picked)))
+    stats.update(
+        trimmed=True,
+        kept_tokens=spent + heading_cost * len(out),
+        kept_ratio=round(spent / max(full, 1), 2),
+        sections_kept=len(out),
+    )
+    return out, stats
+
+
+def fit(paragraphs: List[Paragraph], budget: int, buckets: int = 8) -> Tuple[List[Paragraph], Dict[str, object]]:
+    """Flat convenience wrapper: one section spread over the whole timeline."""
+    out, stats = fit_groups([Group("", 0.0, paragraphs)], budget, max_buckets=buckets)
+    return [p for g in out for p in g.paragraphs], stats

videoxplainer/captions.py

@@ -0,0 +1,132 @@
+"""Caption parsing and track selection (pure functions, no network)."""
+
+from __future__ import annotations
+
+import html
+import json
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from .model import Segment
+
+_TAG = re.compile(r"<[^>]*>")
+_TS = re.compile(r"(?:(\d+):)?(\d{1,2}):(\d{2})[.,](\d{3})")
+
+
+def _to_seconds(stamp: str) -> float:
+    m = _TS.search(stamp)
+    if not m:
+        return 0.0
+    hours, minutes, secs, millis = (int(m.group(1) or 0), int(m.group(2)), int(m.group(3)), int(m.group(4)))
+    return hours * 3600 + minutes * 60 + secs + millis / 1000.0
+
+
+def parse_json3(text: str) -> List[Segment]:
+    data = json.loads(text)
+    out: List[Segment] = []
+    for event in data.get("events", []):
+        segs = event.get("segs")
+        if not segs:
+            continue
+        line = "".join(s.get("utf8", "") for s in segs).replace("\n", " ").strip()
+        if line:
+            out.append(Segment(event.get("tStartMs", 0) / 1000.0, html.unescape(line)))
+    return out
+
+
+def parse_vtt(text: str) -> List[Segment]:
+    out: List[Segment] = []
+    for block in re.split(r"\n\s*\n", text.replace("\r\n", "\n")):
+        lines = [ln for ln in block.split("\n") if ln.strip()]
+        idx = next((i for i, ln in enumerate(lines) if "-->" in ln), None)
+        if idx is None:
+            continue
+        start = _to_seconds(lines[idx].split("-->")[0])
+        body = " ".join(_TAG.sub("", ln).strip() for ln in lines[idx + 1 :])
+        body = re.sub(r"\s+", " ", html.unescape(body)).strip()
+        if body:
+            out.append(Segment(start, body))
+    return out
+
+
+def parse(text: str, ext: str = "") -> List[Segment]:
+    if ext == "json3" or text.lstrip().startswith("{"):
+        try:
+            return parse_json3(text)
+        except (ValueError, AttributeError):
+            pass
+    return parse_vtt(text)
+
+
+Track = Tuple[str, bool, Dict[str, Any]]  # (language code, is_auto, yt-dlp format dict)
+
+
+def _pick_format(formats: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    by_ext = {f.get("ext"): f for f in formats if f.get("url")}
+    for ext in ("json3", "vtt"):
+        if ext in by_ext:
+            return by_ext[ext]
+    return None
+
+
+def _base(code: str) -> str:
+    return code.lower().split("-")[0]
+
+
+def _find(tracks: Dict[str, Any], predicates) -> Optional[str]:
+    for pred in predicates:
+        for key in tracks:
+            if pred(key.lower()):
+                return key
+    return None
+
+
+def choose_track(info: Dict[str, Any], lang: Optional[str] = None) -> Optional[Track]:
+    """Pick the best caption track from a yt-dlp info dict.
+
+    Preference: author-uploaded captions, then the video's *original* auto
+    captions. Machine translations are never chosen.
+    """
+    manual = info.get("subtitles") or {}
+    auto = info.get("automatic_captions") or {}
+    want = (lang or "").lower()
+    vid_lang = (info.get("language") or "").lower()
+
+    if want:  # an explicit request is never answered in another language
+        prefs = [lambda k: k == want, lambda k: _base(k) == _base(want)]
+    else:
+        prefs = []
+        if vid_lang:
+            prefs += [lambda k: k == vid_lang, lambda k: _base(k) == _base(vid_lang)]
+        prefs.append(lambda k: _base(k) == "en")
+
+    key = _find(manual, prefs)
+    if key is None and not want:
+        key = next(iter(manual), None)  # no preference: take whatever the author uploaded
+    if key:
+        fmt = _pick_format(manual[key])
+        if fmt:
+            return key, False, fmt
+
+    if want:  # an explicit request is never silently answered in another language
+        # only the speaker's original track: YouTube also lists machine *translations* under plain codes
+        auto_prefs = [lambda k: k.endswith("-orig") and _base(k) == _base(want),
+                      lambda k: k == want and _base(vid_lang) == _base(want)]
+    else:
+        auto_prefs = [lambda k: k.endswith("-orig")]
+        if vid_lang:
+            auto_prefs.append(lambda k: k == vid_lang)
+        auto_prefs.append(lambda k: k == "en")
+    key = _find(auto, auto_prefs)
+    if key:
+        fmt = _pick_format(auto[key])
+        if fmt:
+            return key.replace("-orig", ""), True, fmt
+    return None
+
+
+def available_languages(info: Dict[str, Any]) -> List[str]:
+    """Languages we could read: uploaded tracks plus original auto-captions."""
+    manual = [k for k, v in (info.get("subtitles") or {}).items() if _pick_format(v)]
+    auto = [k.replace("-orig", "") + " (auto)" for k, v in (info.get("automatic_captions") or {}).items() if k.endswith("-orig") and _pick_format(v)]
+    return sorted(manual) + sorted(auto)

videoxplainer/chapters.py

@@ -0,0 +1,126 @@
+"""Sections of a video: YouTube chapters, or topics detected from the text.
+
+Auto-detection is lexical cohesion (TextTiling-style): compare the vocabulary
+of the passages before and after each gap and cut where they differ most.
+No LLM involved, so it is free and offline.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from typing import Any, Dict, List, Optional, Tuple
+
+from .budget import STOPWORDS
+from .model import Chapter, Group, Paragraph, Segment
+from .normalize import merge_paragraphs
+from .textutil import words
+
+Section = Tuple[float, str]  # (start seconds, title)
+
+# Conversational filler that makes poor headings. Used for labels only, never for detection.
+_LABEL_STOP = frozenset(
+    "said says say think thing things people want wants going get gets got make makes made way one two "
+    "three four five many much come comes came look looks see saw little lot kind sort actually basically "
+    "something anything everything every still around back first even though maybe quite bit time "
+    "good great really thing's let's".split()
+)
+
+
+def from_info(info: Dict[str, Any]) -> List[Chapter]:
+    out: List[Chapter] = []
+    for c in info.get("chapters") or []:
+        try:
+            out.append(Chapter(float(c["start_time"]), float(c.get("end_time") or 0), str(c.get("title") or "").strip()))
+        except (KeyError, TypeError, ValueError):
+            continue
+    return sorted(out, key=lambda c: c.start)
+
+
+def _bag(text: str) -> Counter:
+    return Counter(w for w in words(text) if len(w) > 3 and w not in STOPWORDS)
+
+
+def _cosine(a: Counter, b: Counter) -> float:
+    if not a or not b:
+        return 0.0
+    dot = sum(c * b.get(w, 0) for w, c in a.items())
+    na = math.sqrt(sum(c * c for c in a.values()))
+    nb = math.sqrt(sum(c * c for c in b.values()))
+    return dot / (na * nb) if na and nb else 0.0
+
+
+def detect_sections(
+    paragraphs: List[Paragraph], target: Optional[int] = None, min_seconds: float = 480, min_gap_seconds: float = 90,
+    min_z: float = 1.0,
+    min_depth: float = 0.3,
+) -> List[Section]:
+    """Split into topical sections. Returns [] for short videos (not worth it)."""
+    n = len(paragraphs)
+    if n < 8 or paragraphs[-1].start - paragraphs[0].start < min_seconds:
+        return []
+    duration = paragraphs[-1].start - paragraphs[0].start
+    target = target or max(3, min(12, round(duration / 360)))
+    k = max(2, min(4, n // 10))
+    bags = [_bag(p.text) for p in paragraphs]
+    sims = {}
+    for i in range(k, n - k + 1):
+        sims[i] = _cosine(sum(bags[i - k : i], Counter()), sum(bags[i : i + k], Counter()))
+    if len(sims) < 3:
+        return []
+    idx = sorted(sims)
+    w = 3
+    depth = {}
+    for pos, i in enumerate(idx):
+        left = max(sims[j] for j in idx[max(0, pos - w) : pos + 1])
+        right = max(sims[j] for j in idx[pos : pos + w + 1])
+        depth[i] = (left - sims[i]) + (right - sims[i])
+    sep = max(2 * k, n // (2 * target))
+    # Only cut at *significant* topic shifts: a valley must stand out from the typical
+    # dip (min_z standard deviations above average), otherwise the video stays in one piece.
+    values = list(depth.values())
+    mean = sum(values) / len(values)
+    std = math.sqrt(sum((v - mean) ** 2 for v in values) / len(values))
+    # ...and the vocabulary must really change: an absolute drop in cohesion as well, so a
+    # uniform talk is never carved up just because some dips are bigger than others.
+    floor = max(mean + min_z * std, min_depth)
+    cuts: List[int] = []
+    for i in sorted(depth, key=lambda g: depth[g], reverse=True):
+        if depth[i] < floor or len(cuts) >= target - 1:
+            break
+        if all(abs(i - c) >= sep and abs(paragraphs[i].start - paragraphs[c].start) >= min_gap_seconds for c in cuts):
+            cuts.append(i)
+    if not cuts:
+        return []
+    cuts.sort()
+    starts = [0] + cuts
+    ends = cuts + [n]
+    section_bags = [sum(bags[a:b], Counter()) for a, b in zip(starts, ends)]
+    df: Counter = Counter()
+    for sb in section_bags:
+        df.update(set(sb))
+    m = len(section_bags)
+    sections: List[Section] = []
+    for a, sb in zip(starts, section_bags):
+        usable = [(w, c) for w, c in sb.items() if "'" not in w and w not in _LABEL_STOP]
+        ranked = sorted(usable, key=lambda kv: kv[1] * math.log(1 + m / df[kv[0]]) ** 2, reverse=True)
+        title = ", ".join(word for word, _ in ranked[:3]) or "section"
+        sections.append((0.0 if a == 0 else paragraphs[a].start, title))
+    return sections
+
+
+def build_groups(segments: List[Segment], sections: List[Section]) -> List[Group]:
+    """Cut cleaned segments into sections and paragraph-ise each one."""
+    if not sections:
+        return [Group("", 0.0, merge_paragraphs(segments))]
+    sections = sorted(sections)
+    if sections[0][0] > 0:
+        sections.insert(0, (0.0, "Intro"))
+    groups: List[Group] = []
+    for i, (start, title) in enumerate(sections):
+        end = sections[i + 1][0] if i + 1 < len(sections) else float("inf")
+        segs = [s for s in segments if start <= s.start < end]
+        if segs:
+            groups.append(Group(title, start, merge_paragraphs(segs)))
+    return groups