lectural 0.1.2__py3-none-any.whl

lectural/__init__.py

@@ -0,0 +1,24 @@
+"""LecturAL: complete study-note extraction from YouTube lectures.
+
+The package is import-safe without heavy runtime dependencies (faster-whisper,
+opencv, paddleocr, yt-dlp). Those are imported lazily inside the functions that
+need them, so deterministic logic can be unit-tested offline.
+"""
+
+from .config import (
+    DEDUP_HIST_THRESHOLD,
+    DEDUP_SSIM_THRESHOLD,
+    MAX_GAP_SEC,
+    SCENE_BINS_N,
+    SCHEMA_VERSION,
+)
+
+__all__ = [
+    "DEDUP_HIST_THRESHOLD",
+    "DEDUP_SSIM_THRESHOLD",
+    "MAX_GAP_SEC",
+    "SCENE_BINS_N",
+    "SCHEMA_VERSION",
+]
+
+__version__ = "0.1.2"

lectural/acquisition.py

@@ -0,0 +1,260 @@
+"""Acquire the speech track for a YouTube video.
+
+Strategy (captions-first, token-zero):
+  1. Try captions via youtube-transcript-api / yt-dlp (manual then auto).
+  2. If captions are absent/poor OR --force-stt, download audio for STT.
+
+The network/binary calls are isolated; the subtitle PARSERS below are pure
+functions over text and are unit-tested offline.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import warnings
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Segment:
+    """One timestamped utterance. `t` is the start time in seconds."""
+
+    t: float
+    text: str
+
+    def as_dict(self) -> dict:
+        return {"t": round(self.t, 3), "text": self.text}
+
+
+@dataclass
+class SpeechTrack:
+    segments: list[Segment]
+    source: str  # "caption" | "stt"
+    language: str | None = None
+    meta: dict = field(default_factory=dict)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.segments
+
+
+_URL_ID_PATTERNS = [
+    re.compile(r"(?:v=|/shorts/|youtu\.be/|/embed/)([0-9A-Za-z_-]{11})"),
+    re.compile(r"^([0-9A-Za-z_-]{11})$"),
+]
+
+
+def extract_video_id(url: str) -> str | None:
+    """Pull the 11-char video id out of a URL or bare id. Pure."""
+    url = url.strip()
+    for pat in _URL_ID_PATTERNS:
+        m = pat.search(url)
+        if m:
+            return m.group(1)
+    return None
+
+def _metadata_text(value: object) -> str | None:
+    text = str(value).strip() if value is not None else ""
+    return text or None
+
+
+def _positive_float(value: object) -> float | None:
+    if value in (None, ""):
+        return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if number > 0 else None
+
+
+def parse_ytdlp_metadata(text: str) -> dict:
+    """Parse `yt-dlp --dump-json` output into the metadata LecturAL needs."""
+    data = json.loads(text)
+    if not isinstance(data, dict):
+        raise ValueError("yt-dlp metadata JSON must be an object")
+
+    metadata: dict = {}
+    title = _metadata_text(data.get("title"))
+    if title:
+        metadata["title"] = title
+
+    duration = _positive_float(data.get("duration"))
+    if duration is not None:
+        metadata["duration"] = duration
+
+    video_id = _metadata_text(data.get("id") or data.get("display_id"))
+    if video_id:
+        metadata["video_id"] = video_id
+
+    return metadata
+
+
+def fetch_video_metadata(url: str) -> dict:
+    """Fetch title/duration/video id via yt-dlp without downloading media."""
+    proc = subprocess.run(
+        ["yt-dlp", "--skip-download", "--dump-json", url],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    metadata = parse_ytdlp_metadata(proc.stdout)
+    fallback_id = extract_video_id(url)
+    if fallback_id:
+        metadata.setdefault("video_id", fallback_id)
+    return metadata
+
+# --- Pure subtitle parsers --------------------------------------------------
+
+_TS_RE = re.compile(r"(\d{1,2}):(\d{2}):(\d{2})[.,](\d{1,3})")
+
+
+def _hms_to_seconds(h: str, m: str, s: str, ms: str) -> float:
+    return int(h) * 3600 + int(m) * 60 + int(s) + int(ms.ljust(3, "0")) / 1000.0
+
+
+def parse_vtt(text: str) -> list[Segment]:
+    """Parse WebVTT / SRT-ish caption text into ordered Segments. Pure.
+
+    Handles `HH:MM:SS.mmm --> HH:MM:SS.mmm` cue headers, strips inline tags
+    like <c> and positioning, and collapses blank-separated cue bodies.
+    """
+    segments: list[Segment] = []
+    lines = text.replace("\r\n", "\n").split("\n")
+    i = 0
+    n = len(lines)
+    while i < n:
+        line = lines[i].strip()
+        if "-->" in line:
+            m = _TS_RE.search(line)
+            start = _hms_to_seconds(*m.groups()) if m else 0.0
+            i += 1
+            body: list[str] = []
+            while i < n and lines[i].strip() and "-->" not in lines[i]:
+                body.append(lines[i].strip())
+                i += 1
+            cue = " ".join(body)
+            cue = re.sub(r"<[^>]+>", "", cue)  # strip <c>, <00:00:00.000> tags
+            cue = re.sub(r"\s+", " ", cue).strip()
+            if cue:
+                segments.append(Segment(t=start, text=cue))
+        else:
+            i += 1
+    return _dedupe_rolling(segments)
+
+
+def parse_json3(text: str) -> list[Segment]:
+    """Parse YouTube `json3` caption payload into Segments. Pure."""
+    data = json.loads(text)
+    segments: list[Segment] = []
+    for event in data.get("events", []):
+        segs = event.get("segs")
+        if not segs:
+            continue
+        start_ms = event.get("tStartMs", 0)
+        body = "".join(s.get("utf8", "") for s in segs)
+        body = re.sub(r"\s+", " ", body).strip()
+        if body:
+            segments.append(Segment(t=start_ms / 1000.0, text=body))
+    return _dedupe_rolling(segments)
+
+
+def _dedupe_rolling(segments: list[Segment]) -> list[Segment]:
+    """Drop consecutive duplicate cue text (common in auto-captions). Pure."""
+    out: list[Segment] = []
+    for seg in segments:
+        if out and out[-1].text == seg.text:
+            continue
+        out.append(seg)
+    return out
+
+
+def captions_are_usable(segments: list[Segment], min_segments: int = 3) -> bool:
+    """Heuristic for "captions present and not garbage". Pure."""
+    if len(segments) < min_segments:
+        return False
+    total_chars = sum(len(s.text) for s in segments)
+    return total_chars >= 20
+
+
+# --- Network/binary-backed acquisition (lazy) ------------------------------
+
+def fetch_caption_segments(video_id: str, languages: tuple[str, ...] = ("ko", "en")) -> list[Segment]:
+    """Fetch captions via youtube-transcript-api. Lazy import; may raise."""
+    from youtube_transcript_api import YouTubeTranscriptApi  # lazy
+
+    api = YouTubeTranscriptApi()
+    fetched = api.fetch(video_id, languages=list(languages))
+    segments = [
+        Segment(t=float(item.start), text=re.sub(r"\s+", " ", item.text).strip())
+        for item in fetched
+        if item.text.strip()
+    ]
+    return _dedupe_rolling(segments)
+
+
+def download_audio(url: str, out_dir: str) -> str:
+    """Download bestaudio as wav via yt-dlp+ffmpeg for STT. Returns path."""
+    from .deps import assert_acquisition_ready
+
+    assert_acquisition_ready()
+    import os
+
+    os.makedirs(out_dir, exist_ok=True)
+    out_template = os.path.join(out_dir, "audio.%(ext)s")
+    subprocess.run(
+        [
+            "yt-dlp", "-x", "--audio-format", "wav",
+            "-o", out_template, url,
+        ],
+        check=True,
+    )
+    wav = os.path.join(out_dir, "audio.wav")
+    if not os.path.exists(wav):
+        raise RuntimeError("Audio download did not produce audio.wav")
+    return wav
+
+
+def acquire_speech(
+    url: str,
+    out_dir: str,
+    force_stt: bool = False,
+    languages: tuple[str, ...] = ("ko", "en"),
+) -> SpeechTrack:
+    """Captions-first acquisition with STT fallback. Orchestration only."""
+    video_id = extract_video_id(url)
+    if not video_id:
+        raise ValueError(f"Could not extract a YouTube video id from: {url!r}")
+
+    fallback_reason: str | None = None
+    if force_stt:
+        fallback_reason = "force_stt requested"
+    else:
+        try:
+            segs = fetch_caption_segments(video_id, languages)
+            if captions_are_usable(segs):
+                return SpeechTrack(segments=segs, source="caption", meta={"video_id": video_id})
+            fallback_reason = f"captions present but unusable ({len(segs)} cues)"
+        except Exception as exc:  # noqa: BLE001
+            # youtube-transcript-api raises several distinct types
+            # (NoTranscriptFound, TranscriptsDisabled, network errors) that
+            # cannot be imported without the optional dep, so we catch broadly
+            # here -- but the reason is preserved and surfaced, never discarded.
+            fallback_reason = f"caption fetch failed: {type(exc).__name__}: {exc}"
+
+    # STT fallback (heavy; delegated to speech.py). Make the degradation
+    # observable, mirroring the OCR Paddle->Tesseract fallback warning.
+    warnings.warn(
+        f"Captions unavailable; falling back to CPU STT. Reason: {fallback_reason}",
+        RuntimeWarning,
+        stacklevel=2,
+    )
+    from .speech import transcribe_audio
+
+    audio_path = download_audio(url, out_dir)
+    track = transcribe_audio(audio_path)
+    track.meta.setdefault("video_id", video_id)
+    track.meta["caption_fallback_reason"] = fallback_reason
+    return track

lectural/cli.py

@@ -0,0 +1,286 @@
+"""`lectural` CLI: turn YouTube lecture URL(s) into complete study notes.
+
+Usage:
+    lectural doctor [--fix] [--json]
+    lectural <url> [<url> ...] [--force-stt] [--model medium] [--out ./output]
+
+Single URL or a SEQUENTIAL batch (AC-1, AC-2). The per-video pipeline is the
+real (lazy) module stack; orchestration (arg parsing, slugging, batch loop,
+run-state recording) is pure and unit-tested with an injected processor so it
+runs offline without ffmpeg/yt-dlp/models.
+"""
+
+from __future__ import annotations
+
+import argparse
+import inspect
+import os
+import re
+import sys
+
+from . import runstate
+from .config import DEFAULT_STT_MODEL
+
+
+def slugify(title: str, fallback: str = "video") -> str:
+    """Pure: filesystem-safe directory name from a video title."""
+    title = (title or "").strip()
+    slug = re.sub(r"[^\w\-가-힣]+", "-", title, flags=re.UNICODE).strip("-")
+    slug = re.sub(r"-{2,}", "-", slug)
+    return (slug or fallback)[:80]
+
+
+def output_dir_for(out_root: str, title: str, fallback: str = "video") -> str:
+    """Pure: ./out_root/<slug> path for a video's artifacts (AC-12)."""
+    return os.path.join(out_root, slugify(title, fallback))
+
+def _frame_link(image_path: str, out_dir: str) -> str:
+    """Pure: relative slide-image path as a POSIX markdown link (Windows-safe)."""
+    return os.path.relpath(image_path, out_dir).replace(os.sep, "/")
+
+
+def _run_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="lectural",
+        description="YouTube lecture -> complete study notes",
+        epilog="Command: lectural doctor [--fix] [--json]",
+    )
+    p.add_argument("urls", nargs="*", help="One or more YouTube URLs (processed sequentially)")
+    p.add_argument("--force-stt", action="store_true", help="Skip captions; always transcribe with STT")
+    p.add_argument("--model", default=DEFAULT_STT_MODEL, help="faster-whisper model size (default: medium)")
+    p.add_argument("--out", default="./output", help="Output root directory (default: ./output)")
+    p.add_argument(
+        "--keep-frames",
+        action="store_true",
+        help="Archive raw sampled frames under frames/raw/ instead of deleting extras",
+    )
+    return p
+
+
+def _doctor_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="lectural doctor", description="Validate LecturAL runtime and plugin distribution")
+    p.add_argument("--fix", action="store_true", help="Attempt safe bounded fixes for missing yt-dlp/ffmpeg")
+    p.add_argument("--json", action="store_true", help="Print a machine-readable JSON report")
+    return p
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    argv = list(argv)
+    if argv and argv[0] == "doctor":
+        args = _doctor_parser().parse_args(argv[1:])
+        args.command = "doctor"
+        return args
+
+    p = _run_parser()
+    args = p.parse_args(argv)
+    args.command = "run"
+    if not args.urls:
+        p.error("the following arguments are required: urls (or use `lectural doctor`)")
+    return args
+
+
+def run(
+    urls: list[str],
+    out_root: str = "./output",
+    force_stt: bool = False,
+    model: str = DEFAULT_STT_MODEL,
+    processor=None,
+    runstate_file: str | None = None,
+    keep_frames: bool = False,
+) -> list[dict]:
+    """Sequentially process each URL; pre-register and record EVERY run.
+
+    `processor(url, out_dir, force_stt, model) -> dict` is injectable; the
+    default uses the real pipeline. Each result dict must include output_dir,
+    coverage_json, notes_md, transcript_md, and overall_pass.
+
+    Every URL is pre-registered as `pending` so a failed or unproduced video
+    stays visible to the completeness hook (it cannot be hidden by aborting).
+    A processor failure is recorded and the batch CONTINUES to the next URL.
+    """
+    processor = processor or _default_processor
+    def _call_processor(url: str, out_dir: str) -> dict:
+        try:
+            signature = inspect.signature(processor)
+        except (TypeError, ValueError):
+            return processor(url, out_dir, force_stt, model)
+
+        accepts_keep = (
+            "keep_frames" in signature.parameters
+            or any(p.kind == inspect.Parameter.VAR_KEYWORD for p in signature.parameters.values())
+        )
+        if accepts_keep:
+            return processor(url, out_dir, force_stt, model, keep_frames=keep_frames)
+        return processor(url, out_dir, force_stt, model)
+
+    runstate.start_session(urls, runstate_file)
+    results: list[dict] = []
+    for i, url in enumerate(urls):
+        out_dir = os.path.join(out_root, f"video_{i + 1:02d}")  # provisional
+        try:
+            result = _call_processor(url, out_dir)
+            runstate.update_run(
+                i,
+                status="complete",
+                output_dir=result["output_dir"],
+                coverage_json=result["coverage_json"],
+                notes_md=result["notes_md"],
+                path=runstate_file,
+            )
+            results.append(result)
+        except Exception as exc:  # noqa: BLE001 - record + continue, do not hide failures
+            runstate.update_run(i, status="failed", error=f"{type(exc).__name__}: {exc}", path=runstate_file)
+            results.append({"output_dir": out_dir, "url": url, "overall_pass": False,
+                            "error": f"{type(exc).__name__}: {exc}"})
+    return results
+
+
+def _default_processor(
+    url: str,
+    out_dir_hint: str,
+    force_stt: bool,
+    model: str,
+    *,
+    keep_frames: bool = False,
+) -> dict:
+    """Real pipeline for one video (lazy heavy deps; smoke-tested, not unit)."""
+    from .acquisition import acquire_speech, extract_video_id, fetch_video_metadata
+    from .coverage import build_coverage, coverage_inputs_from_extraction, write_coverage
+    from .deps import assert_acquisition_ready
+    from .ocr import ocr_frames
+    from .synthesis import (
+        build_synthesis_input,
+        render_notes_md,
+        render_transcript_md,
+        write_synthesis_input,
+        write_text,
+    )
+    from .vad import detect_speech_spans
+    from .visual import cleanup_raw_frames, dedupe_frames, extract_candidate_frames
+
+    assert_acquisition_ready()
+    out_root = os.path.dirname(out_dir_hint) or "."
+
+    # 1. Metadata first: it determines the real artifact directory before any
+    # captions/STT path can be selected.
+    metadata = fetch_video_metadata(url)
+    fallback_title = metadata.get("video_id") or extract_video_id(url) or "video"
+    title_seed = metadata.get("title") or fallback_title
+    out_dir = output_dir_for(out_root, title_seed, fallback=fallback_title)
+    frames_dir = os.path.join(out_dir, "frames")
+    os.makedirs(frames_dir, exist_ok=True)
+
+    # 2. Speech track (captions-first, STT fallback) writes into the final
+    # title/video-id directory, not the provisional batch slot.
+    track = acquire_speech(url, out_dir, force_stt=force_stt)
+    track.meta.update({k: v for k, v in metadata.items() if v not in (None, "")})
+    title = track.meta.get("title") or fallback_title
+
+    # 3. Visual track: extract RAW candidate frames, dedupe to slides, OCR.
+    video_path = _download_video(url, out_dir)
+    raw_frames = extract_candidate_frames(video_path, frames_dir)
+    slides = dedupe_frames(raw_frames)
+    slide_frames, ocr_engine = ocr_frames(slides)
+
+    duration = float(track.meta.get("duration") or 0.0)
+    audio_path = track.meta.get("audio_path", os.path.join(out_dir, "audio.wav"))
+    speech_spans = detect_speech_spans(audio_path, duration) if os.path.isfile(audio_path) else [(0.0, duration)]
+
+    video = {"title": title, "url": url, "duration_sec": duration,
+             "language": track.language, "source": track.source}
+    segments = [s.as_dict() for s in track.segments]
+    # Frame links are markdown/web paths -> always POSIX separators (so the
+    # slide-link check and rendered links work on Windows too).
+    slide_dicts = [{"t": f.timestamp,
+                    "frame": _frame_link(f.image_path, out_dir),
+                    "ocr_text": f.ocr_text, "is_slide": True} for f in slide_frames]
+
+    # 4. Synthesis (deterministic, token-zero).
+    si = build_synthesis_input(video, segments, slide_dicts)
+    transcript_path = os.path.join(out_dir, "transcript.md")
+    notes_path = os.path.join(out_dir, "notes.md")
+    transcript_md = render_transcript_md(video, segments)
+    write_text(transcript_md, transcript_path)
+    write_synthesis_input(si, os.path.join(out_dir, "synthesis_input.json"))
+
+    # 5. Coverage (raw sample times enforce the carry-cap contract). Render
+    # notes before the final coverage write so artifact checks judge rendered
+    # content, not filesystem write ordering.
+    raw_sample_times = [f.timestamp for f in raw_frames]
+
+    def _cov_inputs(notes_md_text: str | None) -> "object":
+        return coverage_inputs_from_extraction(
+            video_title=title, duration_sec=duration, speech_spans=speech_spans,
+            segment_times=[s["t"] for s in segments],
+            raw_sample_times=raw_sample_times,
+            slides=slide_dicts, transcript_path=transcript_path, notes_path=notes_path,
+            ocr_engine=ocr_engine,
+            transcript_text=transcript_md, notes_text=notes_md_text,
+        )
+
+    draft_coverage = build_coverage(_cov_inputs(""))
+    draft_notes_md = render_notes_md(si, draft_coverage)
+    coverage = build_coverage(_cov_inputs(draft_notes_md))
+    notes_md = render_notes_md(si, coverage)
+    coverage = build_coverage(_cov_inputs(notes_md))
+    write_text(notes_md, notes_path)
+    coverage_path = write_coverage(coverage, os.path.join(out_dir, "coverage.json"))
+    cleanup_raw_frames(raw_frames, slide_frames, keep_frames=keep_frames)
+
+    return {
+        "output_dir": out_dir,
+        "coverage_json": coverage_path,
+        "notes_md": notes_path,
+        "transcript_md": transcript_path,
+        "overall_pass": coverage["overall_pass"],
+    }
+
+
+def _download_video(url: str, out_dir: str) -> str:
+    """Download the video (for frame extraction) via yt-dlp. Lazy/subprocess."""
+    import subprocess
+
+    os.makedirs(out_dir, exist_ok=True)
+    out_template = os.path.join(out_dir, "video.%(ext)s")
+    subprocess.run(["yt-dlp", "-f", "bestvideo[height<=720]+bestaudio/best",
+                    "-o", out_template, url], check=True)
+    for name in os.listdir(out_dir):
+        if name.startswith("video."):
+            return os.path.join(out_dir, name)
+    raise RuntimeError("Video download did not produce a video file")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+    if args.command == "doctor":
+        try:
+            from . import doctor
+
+            report = doctor.run(fix=args.fix)
+            doctor.print_report(report, json_output=args.json)
+            return int(report["exit_code"])
+        except Exception as exc:  # noqa: BLE001 - surface a clean CLI error
+            print(f"lectural doctor: internal failure — {exc}", file=sys.stderr)
+            return 1
+
+    try:
+        results = run(
+            args.urls,
+            out_root=args.out,
+            force_stt=args.force_stt,
+            model=args.model,
+            keep_frames=args.keep_frames,
+        )
+    except Exception as exc:  # noqa: BLE001 - surface a clean CLI error
+        print(f"lectural: 실패 — {exc}", file=sys.stderr)
+        return 1
+    ok = all(r.get("overall_pass") for r in results)
+    for r in results:
+        mark = "OK" if r.get("overall_pass") else "미달"
+        print(f"[{mark}] {r['output_dir']}")
+    print("완료 게이트는 Stop 훅(scripts/completeness_hook.py)이 최종 검증합니다.")
+    return 0 if ok else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lectural/config.py

@@ -0,0 +1,63 @@
+"""Named configuration constants for the LecturAL pipeline.
+
+These are the tunable knobs the consensus plan required to be explicit,
+named constants (not magic numbers scattered through the code).
+"""
+
+from __future__ import annotations
+
+# --- Synthesis contract ----------------------------------------------------
+# Bump when the synthesis_input.json shape changes incompatibly.
+SCHEMA_VERSION: int = 1
+
+# --- Frame dedup -----------------------------------------------------------
+# Two consecutive frames are considered the SAME slide when their colour
+# histogram correlation is at or above this threshold AND their structural
+# similarity (SSIM) is at or above DEDUP_SSIM_THRESHOLD. Range 0..1.
+DEDUP_HIST_THRESHOLD: float = 0.90
+DEDUP_SSIM_THRESHOLD: float = 0.92
+
+# --- Speech-gap coverage ---------------------------------------------------
+# A completeness FAIL occurs when there is a contiguous span of *speech*
+# (per the VAD/silence mask) longer than this many seconds that has no
+# transcript coverage. Silence does not count against coverage.
+MAX_GAP_SEC: float = 60.0
+# A single caption/STT cue is assumed to cover at most this many seconds of
+# speech. Beyond this, the span between cues counts as untranscribed (so a
+# long cue-less stretch during speech is detected as a real gap).
+CUE_MAX_COVER_SEC: float = 30.0
+
+# --- Scene coverage --------------------------------------------------------
+# The timeline is divided into this many equal bins. A bin that contains
+# speech must be covered by a keyframe: a keyframe covers its own bin and
+# carries forward to later bins, but only for up to FRAME_CARRY_MAX_SEC (so a
+# static slide passes when fed dense raw samples, while a real extractor stall
+# leaves a keyframe-less stretch uncovered and FAILs).
+SCENE_BINS_N: int = 20
+# Max seconds a keyframe carries forward before its bin coverage expires.
+# scene_coverage expects RAW sampled keyframe times (dense, ~SAMPLE_FPS),
+# pre-dedup; this cap then catches a stalled/missing visual pass.
+FRAME_CARRY_MAX_SEC: float = 120.0
+
+# --- Visual extraction -----------------------------------------------------
+# Temporal downsample cap (frames per second) before scene detection.
+SAMPLE_FPS: float = 2.0
+
+# --- Speech / STT ----------------------------------------------------------
+# Default faster-whisper model + compute type (CPU-friendly).
+DEFAULT_STT_MODEL: str = "medium"
+STT_COMPUTE_TYPE: str = "int8"
+# Warn (and let the caller decide) when a video to be transcribed by STT is
+# longer than this, because CPU transcription of long videos is slow.
+STT_LONG_VIDEO_WARN_SEC: float = 45 * 60.0
+
+# --- OCR -------------------------------------------------------------------
+# A frame is classified as a "slide" (and therefore expected to contain OCR
+# text) when its OCR text has at least this many non-whitespace characters.
+SLIDE_MIN_TEXT_CHARS: int = 12
+
+# --- Incremental-slide re-split --------------------------------------------
+# When a frame's OCR text is a superset of the previous frame's text and adds
+# at least this fraction of new characters, it is treated as a NEW
+# incremental slide rather than a duplicate of the previous one.
+INCREMENTAL_SLIDE_MIN_GROWTH: float = 0.15