paces 0.0.12__tar.gz → 0.0.14__tar.gz

{paces-0.0.12 → paces-0.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.12
+Version: 0.0.14
 Summary: Turn instructional media into structured, interactive learning material
 Project-URL: Homepage, https://github.com/thorwhalen/paces
 Project-URL: Repository, https://github.com/thorwhalen/paces
@@ -20,8 +20,8 @@ Requires-Dist: argcomplete>=3; extra == 'cli'
 Requires-Dist: cw<0.2,>=0.1.1; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: cw<0.2,>=0.1.1; extra == 'dev'
-Requires-Dist: lacing>=0.0.40; extra == 'dev'
-Requires-Dist: mixing[audio,beats]>=0.0.39; extra == 'dev'
+Requires-Dist: lacing>=0.0.54; extra == 'dev'
+Requires-Dist: mixing[audio,beats,media]>=0.0.39; extra == 'dev'
 Requires-Dist: numba>=0.59; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
@@ -31,9 +31,9 @@ Provides-Extra: docs
 Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
 Requires-Dist: sphinx>=6.0; extra == 'docs'
 Provides-Extra: lacing
-Requires-Dist: lacing>=0.0.40; extra == 'lacing'
+Requires-Dist: lacing>=0.0.54; extra == 'lacing'
 Provides-Extra: media
-Requires-Dist: mixing>=0.0.39; extra == 'media'
+Requires-Dist: mixing[media]>=0.0.39; extra == 'media'
 Provides-Extra: pose
 Requires-Dist: onnxruntime; extra == 'pose'
 Requires-Dist: rtmlib<0.1,>=0.0.16; extra == 'pose'

{paces-0.0.12 → paces-0.0.14}/paces/__init__.py

@@ -72,6 +72,10 @@ from paces.segmenters import (
     segment,
 )
 
+# Segmenters in their own modules register on import (ADR-0003); importing
+# them here is what puts them in the catalog for every ``paces.*`` import.
+from paces import cues  # noqa: F401
+
 __all__ = [
     # the document (the contract)
     "StepDocument",

paces-0.0.14/paces/cues.py

@@ -0,0 +1,207 @@
+"""Lexical cue segmenters: subtitles and transcripts → proposed named spans.
+
+Instructional narration announces its own structure — "now", "next", "step
+two", "and finally". Over *timed text* those words are a near-free boundary
+detector with a name attached (``docs/alignment/07 §2.13(a)``, ``§6.3``): no
+ASR bill when the text already exists (uploader subtitles, auto-captions, a
+transcript from an earlier run).
+
+Two capabilities share one detector, because the *source* differs in how far
+it can be trusted, not in what is done with it:
+
+- ``subtitle-cues`` — ``metadata={"subtitles": ...}``: human-written or
+  auto-caption cues.
+- ``transcript-cues`` — ``transcript=...``: any transcript (ASR output).
+
+Both are *proposers*, not authorities: the result is graded
+``proposed-uncertain`` (``DFLT_CUES_CONFIDENCE``) and flagged so. When no cue
+word is found the result is the refused state, never an invented step list.
+The LLM rung over a transcript is ``mixing.chapters.detect_chapters``; it is
+a different capability and is not wrapped here.
+
+Accepted timed text: whatever :func:`paces.timed_text.normalize_timed_text`
+takes — SRT/WebVTT text or file, cue mappings, ``(start, end, text)`` triples,
+a Whisper ``{"segments": ...}`` result. Parsing subtitle *text* needs the
+optional ``mixing`` package; cue rows do not.
+
+Word-level transcripts (one cue per word) mostly yield *unnamed* steps: the
+marker is found but the name that follows it lives in later cues. Pass
+phrase- or sentence-level cues when you want names.
+
+Registration: these capabilities register when this module is imported, and
+``paces/__init__.py`` imports it — so any ``paces.*`` import (including
+``from paces.segmenters import segment``) sees them. ``paces.segmenters``
+does not import this module itself, which would be circular.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from paces.segmenters import (
+    Capability,
+    SegStep,
+    Segmentation,
+    register,
+    unique_slug_ids,
+)
+from paces.timed_text import normalize_timed_text
+
+__all__ = ["DFLT_CUE_PATTERNS", "detect_cues", "normalize_timed_text"]
+
+DFLT_CUES_CONFIDENCE = 0.5  # lexical cues are a hint, not a measurement
+DFLT_MIN_GAP_S = 8.0  # cues closer than this to the last boundary are one step
+DFLT_MAX_NAME_CHARS = 60
+
+#: Discourse markers that open a step, matched at the start of a cue (case-
+#: insensitive). Each may carry a leading "and"/"so"/"okay". Capture group 1
+#: is the marker, stripped from the step's name. Deliberately narrow: bare
+#: "then", "and then", "let's" and leading numerals ("2.") were dropped as
+#: too false-positive-prone in running speech.
+DFLT_CUE_PATTERNS: tuple[str, ...] = (
+    r"(?:(?:and|so|ok(?:ay)?|alright)[,\s]+)?(now|next|first\s+of\s+all|first(?:ly)?|second(?:ly)?"
+    r"|third(?:ly)?|finally|lastly)\b[,\s]*",
+    r"((?:step|number|part)\s+(?:\d+|one|two|three|four|five|six|seven|eight"
+    r"|nine|ten))\b[\s:.,)-]*",
+    r"(to\s+start|to\s+begin|moving\s+on|after\s+that)\b[,\s]*",
+)
+
+#: Speaker / sound-tag prefixes stripped before matching: "- ", ">> ", "[music] ".
+_PREFIX_RE = re.compile(r"^(?:\s*(?:-+|>>+|\[[^\]]*\])\s*)+")
+
+
+# ── the detector ────────────────────────────────────────────────────────────
+
+
+def detect_cues(
+    cues: Sequence[Mapping],
+    *,
+    patterns: Sequence[str] = DFLT_CUE_PATTERNS,
+    min_gap_s: float = DFLT_MIN_GAP_S,
+    max_name_chars: int = DFLT_MAX_NAME_CHARS,
+) -> list[dict]:
+    """Cue rows that open a step: ``{start, name, cue}`` (the matched marker).
+
+    A cue opens a step when its text — after any speaker or sound-tag prefix
+    ("- ", ">> ", "[music] ") — starts with one of *patterns*; one that lands
+    within *min_gap_s* of the previous accepted step is folded into it (and
+    lends it its name if that step had none). The name is the cue's text
+    without its lead-in marker, trimmed to *max_name_chars* at a word boundary
+    (a marker alone leaves the name empty — found, not named).
+
+    >>> rows = [{"start": 0, "end": 4, "text": "Hi everyone"},
+    ...         {"start": 10, "end": 14, "text": ">> Now we do the turn."}]
+    >>> detect_cues(rows)
+    [{'start': 10.0, 'name': 'we do the turn', 'cue': 'Now'}]
+    """
+    compiled = [re.compile(p, re.IGNORECASE) for p in patterns]
+
+    def _name(text: str) -> str:
+        name = text.strip(" ,.;:!?-")
+        if len(name) > max_name_chars:
+            name = name[:max_name_chars].rsplit(" ", 1)[0].rstrip(" ,.;:-")
+        return name
+
+    found: list[dict] = []
+    for cue in cues:
+        text = _PREFIX_RE.sub("", cue["text"])
+        match = next((m for m in (p.match(text) for p in compiled) if m), None)
+        if match is None:
+            continue
+        name = _name(text[match.end() :])
+        if found and cue["start"] - found[-1]["start"] < min_gap_s:
+            if not found[-1]["name"]:
+                found[-1]["name"] = name
+            continue
+        found.append(
+            {
+                "start": float(cue["start"]),
+                "name": name,
+                "cue": (match.group(1) if match.re.groups else match.group(0)).strip(),
+            }
+        )
+    return found
+
+
+def _segment_cue_source(cues: list[dict], *, source: str) -> Segmentation:
+    openers = detect_cues(cues)
+    end = max((cue["end"] for cue in cues), default=0.0)
+    flags: tuple[str, ...] = ()
+    if openers and openers[-1]["start"] >= end:
+        openers = openers[:-1]  # a marker on the very last instant opens nothing
+        flags += ("trailing-cue-dropped",)
+    if not openers:
+        return Segmentation(
+            flags=(
+                "no-signal",
+                "try: the other cue source via segmenter=, chapters in metadata, "
+                "boundaries=[...], or an LLM pass",
+                *flags,
+            ),
+        )
+    starts = [row["start"] for row in openers]
+    spans = zip(starts, starts[1:] + [end])
+    ids = unique_slug_ids([row["name"] for row in openers], fallback="cue")
+    steps = tuple(
+        SegStep(
+            id=step_id,
+            name=row["name"],
+            spans=(span,),
+            confidence=DFLT_CUES_CONFIDENCE,
+            source=source,
+            evidence={"cue": row["cue"]},
+        )
+        for step_id, row, span in zip(ids, openers, spans)
+    )
+    flags = ("proposed-uncertain", *flags)
+    if starts[0] > 0:
+        flags += (f"intro-before: {starts[0]:g}s",)
+    if not any(step.name for step in steps):
+        flags += ("naming-abstained",)
+    return Segmentation(
+        steps=steps,
+        boundaries=tuple(starts + [end]),
+        confidence=DFLT_CUES_CONFIDENCE,
+        flags=flags,
+    )
+
+
+def _segment_subtitles(inputs: Mapping[str, Any]) -> Segmentation:
+    return _segment_cue_source(inputs["subtitles"], source="subtitle-cues")
+
+
+def _segment_transcript(inputs: Mapping[str, Any]) -> Segmentation:
+    return _segment_cue_source(inputs["transcript"], source="transcript-cues")
+
+
+SUBTITLE_CUES = register(
+    Capability(
+        name="subtitle-cues",
+        gives="segmentation",
+        summary=(
+            "Propose named spans from a subtitle track by lexical step cues "
+            "('now', 'next', 'step two'). Free; a hint, not an authority."
+        ),
+        target="paces.cues:_segment_subtitles",
+        needs=frozenset({"meta.subtitles"}),
+        base=0.4,  # below chapters (0.75) and explicit boundaries (0.5)
+        resolution_s=DFLT_MIN_GAP_S,
+    )
+)
+
+TRANSCRIPT_CUES = register(
+    Capability(
+        name="transcript-cues",
+        gives="segmentation",
+        summary=(
+            "Propose named spans from any transcript by the same lexical "
+            "step cues. Free once the transcript exists."
+        ),
+        target="paces.cues:_segment_transcript",
+        needs=frozenset({"transcript"}),
+        base=0.35,  # an ASR transcript is a step less trustworthy than subtitles
+        resolution_s=DFLT_MIN_GAP_S,
+    )
+)

{paces-0.0.12 → paces-0.0.14}/paces/segmenters.py

@@ -21,6 +21,13 @@ Plus ``chapters`` (external, explicit): author-supplied chapter metadata — a
 yt-dlp info dict or ffprobe's ``-show_chapters`` output — is a complete named
 segmentation for ~0 cost, and most tutorial content on the web carries it.
 
+Plus ``subtitle-cues`` and ``transcript-cues`` (``paces/cues.py``): proposers
+that read step markers ("now", "next", "step two") out of timed text — uploader
+subtitles or any transcript — and return low-confidence, honestly flagged
+spans. Like ``grid-measured`` (``paces/measure.py``) they register when
+``paces`` is imported — the package ``__init__`` imports their module, so
+``from paces.segmenters import segment`` sees them too.
+
 Honesty rules (``docs/alignment/07 §9.5``): a segmenter may never return a
 step count it has no evidence for. Four legitimate return states — confident /
 found-unnamed / proposed-uncertain / refused — all expressed by the type, none
@@ -38,6 +45,7 @@ from pathlib import Path
 from typing import Any, Callable
 
 from paces.model import MetricGrid, seconds_per_unit
+from paces.timed_text import normalize_timed_text
 
 Span = tuple[float, float]  # seconds, half-open
 
@@ -160,6 +168,21 @@ def _slugify(text: str) -> str:
     return slug or "step"
 
 
+def unique_slug_ids(names: Sequence[str], *, fallback: str = "step") -> list[str]:
+    """One unique, git-readable id per name; unnamed ones get ``{fallback}-{i}``.
+
+    >>> unique_slug_ids(["Turn", "", "Turn"], fallback="cue")
+    ['turn', 'cue-2', 'turn-2']
+    """
+    seen: dict[str, int] = {}
+    ids = []
+    for index, name in enumerate(names):
+        slug = _slugify(name) if name else f"{fallback}-{index + 1}"
+        seen[slug] = seen.get(slug, 0) + 1
+        ids.append(slug if seen[slug] == 1 else f"{slug}-{seen[slug]}")
+    return ids
+
+
 def _normalize_steps(steps: Sequence | None) -> list[dict]:
     """Accept names, (name, duration) pairs, or mappings; emit uniform dicts.
 
@@ -257,6 +280,34 @@ def _normalize_chapters(metadata: Mapping | Sequence | None) -> list[dict]:
     return rows
 
 
+def _subtitle_cues(
+    metadata: Mapping | Sequence | None,
+) -> tuple[list[dict], str | None]:
+    """``(cues, problem)`` from ``metadata["subtitles"]``; cues ``[]`` if none.
+
+    Metadata is a bag of things the caller did not curate, so an unusable
+    ``subtitles`` value must not abort a segmentation another key could serve
+    (e.g. chapters): it is no fact, and *problem* names why (surfaced as a
+    flag).
+
+    Usable means timed text itself (SRT/VTT text, a file path, cue rows, a
+    Whisper ``{"segments": ...}`` result). A yt-dlp info dict's ``subtitles``
+    is a ``{lang: [{url, ext}]}`` index of tracks still to be fetched — not
+    text — and is no fact.
+    """
+    value = metadata.get("subtitles") if isinstance(metadata, Mapping) else None
+    if (
+        isinstance(value, (str, Path))
+        or (isinstance(value, Mapping) and "segments" in value)
+        or (isinstance(value, Sequence) and not isinstance(value, bytes))
+    ):
+        try:
+            return normalize_timed_text(value), None
+        except (ValueError, TypeError, ImportError) as error:
+            return [], f"subtitles-unusable: {error}"
+    return [], None
+
+
 def _facts(
     *,
     media: str | None,
@@ -265,6 +316,8 @@ def _facts(
     grid: MetricGrid | None,
     k: int | None,
     chapters: list[dict] | None = None,
+    subtitles: list[dict] | None = None,
+    transcript: list[dict] | None = None,
 ) -> frozenset[str]:
     """The free half of the fact vocabulary (docs/alignment/07 §9.3): what is
     present among the inputs. Probed (intrinsic) facts arrive with the first
@@ -291,6 +344,10 @@ def _facts(
         facts.add("k")
     if chapters:
         facts.add("meta.chapters")
+    if subtitles:
+        facts.add("meta.subtitles")
+    if transcript:
+        facts.add("transcript")
     return frozenset(facts)
 
 
@@ -305,6 +362,7 @@ def segment(
     boundaries: Sequence[float] | None = None,
     grid: MetricGrid | Mapping | None = None,
     metadata: Mapping | Sequence | None = None,
+    transcript: str | Sequence | None = None,
     k: int | None = None,
     catalog: Mapping[str, Capability] | None = None,
 ) -> Segmentation:
@@ -326,6 +384,9 @@ def segment(
     step_rows = _normalize_steps(steps)
     grid = _normalize_grid(grid)
     chapters = _normalize_chapters(metadata)
+    subtitles, subtitles_problem = _subtitle_cues(metadata)
+    problem_flags = (subtitles_problem,) if subtitles_problem else ()
+    transcript_cues = normalize_timed_text(transcript)
     facts = _facts(
         media=media,
         steps=step_rows,
@@ -333,6 +394,8 @@ def segment(
         grid=grid,
         k=k,
         chapters=chapters,
+        subtitles=subtitles,
+        transcript=transcript_cues,
     )
     inputs = {
         "media": media,
@@ -340,6 +403,8 @@ def segment(
         "boundaries": tuple(float(b) for b in boundaries) if boundaries else (),
         "grid": grid,
         "chapters": chapters,
+        "subtitles": subtitles,
+        "transcript": transcript_cues,
         "k": k,
     }
 
@@ -369,10 +434,12 @@ def segment(
         if not candidates:
             return Segmentation(
                 confidence=0.0,
-                flags=(
+                flags=problem_flags
+                + (
                     "no-signal",
                     "try: steps=[(name, duration), ...] with grid=, "
-                    "boundaries=[t0, t1, ...], or metadata= with chapters",
+                    "boundaries=[t0, t1, ...], metadata= with chapters or subtitles, "
+                    "or transcript=",
                 ),
                 elapsed_s=time.perf_counter() - started,
             )
@@ -399,6 +466,8 @@ def segment(
         "steps": "steps",
         "boundaries": "boundaries",
         "meta.chapters": "metadata (chapters)",
+        "meta.subtitles": "metadata (subtitles)",
+        "transcript": "transcript",
         "k": "k",
     }
     used = capability.needs | capability.reads
@@ -406,6 +475,7 @@ def segment(
         label for fact, label in ignorable.items() if fact in facts and fact not in used
     )
     extra_flags = (f"ignored: {', '.join(ignored)}",) if ignored else ()
+    extra_flags += problem_flags
 
     # A grid describes the media's own clock; any segmentation over that
     # media may carry it (and its unit) even when placement didn't use it —
@@ -550,12 +620,7 @@ def _segment_chapters(inputs: Mapping[str, Any]) -> Segmentation:
             f"step-count-mismatch: {len(step_rows)} steps vs "
             f"{len(chapters)} chapters (using chapter titles)",
         )
-    seen: dict[str, int] = {}
-
-    def _unique_id(title: str, index: int) -> str:
-        slug = _slugify(title) if title else f"chapter-{index + 1}"
-        seen[slug] = seen.get(slug, 0) + 1
-        return slug if seen[slug] == 1 else f"{slug}-{seen[slug]}"
+    chapter_ids = unique_slug_ids([c["title"] for c in chapters], fallback="chapter")
 
     def _step(i: int, chapter: dict) -> SegStep:
         if user_names:
@@ -563,7 +628,7 @@ def _segment_chapters(inputs: Mapping[str, Any]) -> Segmentation:
             name, step_id = row["name"], row["id"]
             evidence = {"chapter_title": chapter["title"]}
         else:
-            name, step_id = chapter["title"], _unique_id(chapter["title"], i)
+            name, step_id = chapter["title"], chapter_ids[i]
             evidence = {}
         return SegStep(
             id=step_id,

paces-0.0.14/paces/timed_text.py

@@ -0,0 +1,140 @@
+"""Timed-text normalisation: any subtitle/transcript shape → ``{start, end, text}`` rows.
+
+Depends on nothing else in ``paces`` — it is the input boundary of the cue
+segmenters (``paces/cues.py``) and of ``segment(transcript=...)``.
+
+Accepted shapes:
+
+- SRT or WebVTT *text* (VTT when it starts with ``WEBVTT``, after any BOM or
+  whitespace; hour fields optional) — parsed by the fleet's ``mixing.srt``,
+  which is an optional dependency here: only text parsing needs it.
+- a path (``str`` or :class:`~pathlib.Path`) to an ``.srt``/``.vtt`` file;
+- cue mappings ``{start, end, text}`` or ``(start, end, text)`` triples (the
+  shape ``paces.evidence`` takes for transcripts);
+- a Whisper result ``{"segments": [{start, end, text}, ...]}``.
+
+Simple markup (``<i>..</i>``, VTT ``<c>`` and inline timestamp tags, ASS
+overrides like ``{\\an8}``) is stripped from cue text.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+_MARKUP_RE = re.compile(r"<[^>]*>|\{\\[^}]*\}")
+_MAX_PATH_CHARS = 1024
+_MIXING_INSTALL_HINT = (
+    "Parsing SRT/VTT text needs the optional `mixing` package: "
+    "pip install mixing (or pass cue mappings / (start, end, text) triples)."
+)
+
+
+def _mixing_srt():
+    try:
+        from mixing import srt
+    except ImportError as error:
+        raise ImportError(_MIXING_INSTALL_HINT) from error
+    return srt
+
+
+def _parse_srt(text: str) -> list[dict]:
+    return [
+        {"start": c.start, "end": c.end, "text": c.text}
+        for c in _mixing_srt().parse_srt(text)
+    ]
+
+
+def _parse_vtt(text: str) -> list[dict]:
+    """Cue-level WebVTT via mixing's private helpers.
+
+    TODO: switch to a public ``mixing.srt.parse_vtt`` once it exists —
+    https://github.com/reeleehq/mixing/issues/79
+    """
+    srt = _mixing_srt()
+    return [
+        {"start": c.start, "end": c.end, "text": srt._vtt_clean(c.text)}
+        for c in srt._vtt_cues(text)
+    ]
+
+
+def _read_if_path(source: str | Path) -> str:
+    if isinstance(source, Path):
+        return source.read_text(encoding="utf-8")
+    if "-->" in source:
+        return source  # timed text itself
+    if len(source) < _MAX_PATH_CHARS and "\n" not in source:
+        try:
+            if Path(source).is_file():
+                return Path(source).read_text(encoding="utf-8")
+        except OSError:
+            pass
+    raise ValueError(
+        "timed text: not SRT/VTT (no '-->' timing line) and not an existing "
+        f"file: {source[:80]!r}"
+    )
+
+
+def _parse_text(text: str) -> list[dict]:
+    stripped = text.lstrip(" \t\r\n")
+    if stripped.startswith("WEBVTT"):
+        return _parse_vtt(stripped)
+    return _parse_srt(stripped)
+
+
+def _cue_row(i: int, item: Any) -> dict:
+    if isinstance(item, Sequence) and not isinstance(item, (str, bytes)):
+        if len(item) != 3:
+            raise ValueError(f"cues[{i}]: expected (start, end, text); got {item!r}")
+        item = dict(zip(("start", "end", "text"), item))
+    if not isinstance(item, Mapping):
+        raise TypeError(
+            f"cues[{i}]: expected a mapping or (start, end, text) — "
+            f"got {type(item).__name__}"
+        )
+    if item.get("text") is None or isinstance(item.get("start"), bool):
+        raise ValueError(f"cues[{i}]: needs numeric start and text; got {dict(item)!r}")
+    try:
+        start = float(item["start"])
+        end = float(item.get("end", start))
+        text = " ".join(_MARKUP_RE.sub("", str(item["text"])).split())
+    except (KeyError, TypeError, ValueError) as error:
+        raise ValueError(
+            f"cues[{i}]: needs numeric start (and end) plus text; got "
+            f"keys {sorted(item)} ({error})"
+        ) from None
+    if not (math.isfinite(start) and math.isfinite(end)) or start < 0 or end < start:
+        raise ValueError(f"cues[{i}]: unusable times start={start}, end={end}")
+    return {"start": start, "end": end, "text": text}
+
+
+def normalize_timed_text(source: str | Path | Sequence | Mapping | None) -> list[dict]:
+    """Uniform, sorted ``{start, end, text}`` rows from any accepted timed text.
+
+    >>> normalize_timed_text([(1, 3, "<i>Now</i> we turn")])
+    [{'start': 1.0, 'end': 3.0, 'text': 'Now we turn'}]
+    >>> normalize_timed_text({"segments": [{"start": 0, "end": 2, "text": " Hi"}]})
+    [{'start': 0.0, 'end': 2.0, 'text': 'Hi'}]
+    >>> normalize_timed_text(None)
+    []
+    """
+    if source is None:
+        return []
+    if isinstance(source, (str, Path)):
+        raw: Sequence = _parse_text(_read_if_path(source))
+    elif isinstance(source, Mapping):
+        if "segments" not in source:
+            raise ValueError(
+                "timed text: a mapping must be a Whisper result with 'segments'; "
+                f"got keys {sorted(source)}"
+            )
+        raw = list(source["segments"])
+    else:
+        raw = list(source)
+    rows = [_cue_row(i, item) for i, item in enumerate(raw)]
+    rows = [row for row in rows if row["text"]]
+    rows.sort(key=lambda row: (row["start"], row["end"]))
+    return rows

{paces-0.0.12 → paces-0.0.14}/paces/tools.py

@@ -39,6 +39,18 @@ def _structured(value, *, what: str = "argument"):
         ) from None
 
 
+def _timed_text(value):
+    """JSON cues parsed when the string *is* JSON; anything else passes through
+    (SRT/VTT text, or a path — even one like ``[draft].srt``)."""
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except ValueError:
+            return value
+        return parsed if isinstance(parsed, (list, dict)) else value
+    return value
+
+
 def _as_document(document) -> model.StepDocument:
     if isinstance(document, model.StepDocument):
         return document
@@ -114,6 +126,7 @@ def segment(
     boundaries=None,
     grid=None,
     metadata=None,
+    transcript=None,
     segmenter: str | None = None,
     k: int | None = None,
     output: str | None = None,
@@ -122,7 +135,10 @@ def segment(
 
     ``steps``, ``boundaries``, ``grid`` and ``metadata`` accept JSON values,
     JSON strings, or paths to JSON files — ``metadata`` notably takes a
-    yt-dlp ``.info.json`` (its ``chapters`` become a named segmentation).
+    yt-dlp ``.info.json`` (its ``chapters`` become a named segmentation) or
+    ``{"subtitles": <SRT text | .srt/.vtt path | cue list>}``. ``transcript``
+    is timed text — SRT text, an ``.srt``/``.vtt`` path, or JSON cues
+    ``[{"start", "end", "text"}]`` — read for step markers ("now", "next").
     Returns the segmentation as a JSON-ready dict (also written to
     ``output=`` when given) — honest about naming
     (``flags: ['naming-abstained']``) and about refusal
@@ -135,6 +151,7 @@ def segment(
         boundaries=_structured(boundaries, what="boundaries"),
         grid=_structured(grid, what="grid"),
         metadata=_structured(metadata, what="metadata"),
+        transcript=_timed_text(transcript),
         k=k,
     )
     payload = _segmentation_to_dict(result)

{paces-0.0.12 → paces-0.0.14}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paces"
-version = "0.0.12"
+version = "0.0.14"
 description = "Turn instructional media into structured, interactive learning material"
 readme = "README.md"
 license = "MIT"
@@ -57,7 +57,7 @@ media = [
     # all run on the pip-bundled imageio-ffmpeg binary — no system ffmpeg.
     # Floor 0.0.39: make_gif, crop_box= and path-accepting
     # get_video_dimensions ship there.
-    "mixing>=0.0.39",
+    "mixing[media]>=0.0.39",
 ]
 # The pointable subject_locator (issue #15, ADR-0005 §3): rtmlib pose boxes,
 # reached through `paces.pose:rtmlib_pose`. rtmlib is Apache-2.0 (a pure-Python
@@ -107,7 +107,7 @@ pose = [
 # unknown keys — both of which this layer's round trip relies on to fail loudly
 # instead of silently normalising.
 lacing = [
-    "lacing>=0.0.40",
+    "lacing>=0.0.54",
 ]
 dev = [
     "pytest>=7.0",
@@ -120,11 +120,11 @@ dev = [
     # synthesized audio; mirrored with [audio] so they run rather than skip.
     # The derivation tests do the same on synthetic video — mirrored with
     # [media] (the >=0.0.39 floor wins over [audio]'s >=0.0.36).
-    "mixing[beats,audio]>=0.0.39",
+    "mixing[beats,audio,media]>=0.0.39",
     "numba>=0.59",
     # The evidence-layer tests run against real, dict-backed lacing stores —
     # mirrored with [lacing] so they run rather than skip.
-    "lacing>=0.0.40",
+    "lacing>=0.0.54",
     # tests/test_pose.py reads pyproject.toml to guard the licence perimeter;
     # stdlib tomllib is 3.11+, and a skipped guard guards nothing.
     "tomli>=2.0; python_version < '3.11'",

{paces-0.0.12 → paces-0.0.14}/tests/data/body_schemas.json

@@ -27,6 +27,7 @@
       },
       "attrs": {
         "additionalProperties": true,
+        "default": {},
         "description": "Open bag.",
         "title": "Attrs",
         "type": "object"
@@ -146,6 +147,7 @@
     "properties": {
       "attrs": {
         "additionalProperties": true,
+        "default": {},
         "description": "Namespaced open bag, as on the document.",
         "title": "Attrs",
         "type": "object"
@@ -175,6 +177,7 @@
         "type": "string"
       },
       "flags": {
+        "default": [],
         "description": "The run's honesty flags (``Segmentation.flags``) — 'naming-abstained', 'origin-estimated: ...', and friends. Evidence about the run, never projected into the document.",
         "items": {
           "type": "string"
@@ -389,6 +392,7 @@
           "pattern": "^-?\\d+(\\.\\d+)?$",
           "type": "string"
         },
+        "default": {},
         "description": "Policy parameters the box was resolved under (aspect, pad). A change here re-locates an unlocked entry.",
         "title": "Params",
         "type": "object"
@@ -460,6 +464,7 @@
       },
       "attrs": {
         "additionalProperties": true,
+        "default": {},
         "description": "Open bag.",
         "title": "Attrs",
         "type": "object"
@@ -546,6 +551,7 @@
     "properties": {
       "attrs": {
         "additionalProperties": true,
+        "default": {},
         "description": "Namespaced open bag, as on the step.",
         "title": "Attrs",
         "type": "object"
@@ -610,6 +616,7 @@
       },
       "span_attrs": {
         "additionalProperties": true,
+        "default": {},
         "description": "Open bag on the span.",
         "title": "Span Attrs",
         "type": "object"
@@ -712,6 +719,7 @@
         "type": "string"
       },
       "tags": {
+        "default": [],
         "description": "Open tag vocabulary.",
         "items": {
           "type": "string"

paces-0.0.14/tests/test_cues.py

@@ -0,0 +1,255 @@
+"""The subtitle / transcript cue segmenters (issue #6)."""
+
+from __future__ import annotations
+
+import builtins
+from pathlib import Path
+
+import pytest
+
+from paces import tools
+from paces.cues import detect_cues, normalize_timed_text
+from paces.segmenters import capabilities, segment
+
+SRT = """1
+00:00:00,000 --> 00:00:05,000
+Hi everyone, welcome back.
+
+2
+00:00:12,000 --> 00:00:18,000
+Now we start with the basic step.
+
+3
+00:00:20,000 --> 00:00:24,000
+Keep your weight forward.
+
+4
+00:00:40,000 --> 00:00:46,000
+Step two: add the turn.
+
+5
+00:01:10,000 --> 00:01:15,000
+And finally, put it together.
+"""
+
+
+def test_srt_subtitles_become_proposed_named_spans():
+    seg = segment("v.mp4", metadata={"subtitles": SRT})
+    assert seg.method == "subtitle-cues"
+    assert [s.name for s in seg.steps] == [
+        "we start with the basic step",
+        "add the turn",
+        "put it together",
+    ]
+    assert seg.steps[0].spans == ((12.0, 40.0),)
+    assert seg.boundaries == (12.0, 40.0, 70.0, 75.0)
+    assert "proposed-uncertain" in seg.flags
+    assert seg.confidence < 0.9  # a proposer, not an authority
+
+
+def test_transcript_cue_dicts_use_the_transcript_capability():
+    cues = [
+        {"start": 0, "end": 5, "text": "Intro"},
+        {"start": 20, "end": 25, "text": "First, the stance."},
+        {"start": 60, "end": 65, "text": "Next, the turn."},
+    ]
+    seg = segment(transcript=cues)
+    assert seg.method == "transcript-cues"
+    assert [s.name for s in seg.steps] == ["the stance", "the turn"]
+    assert seg.steps[0].source == "transcript-cues"
+
+
+def test_srt_file_path_is_read(tmp_path):
+    path = tmp_path / "talk.srt"
+    path.write_text(SRT, encoding="utf-8")
+    seg = segment(transcript=str(path))
+    assert len(seg.steps) == 3
+
+
+def test_no_markers_is_the_refused_state_not_an_invention():
+    seg = segment(transcript=[{"start": 0, "end": 5, "text": "Just chatting."}])
+    assert seg.steps == () and seg.boundaries == ()
+    assert "no-signal" in seg.flags
+
+
+def test_close_cues_fold_into_one_step():
+    rows = [
+        {"start": 10, "end": 12, "text": "Now we begin."},
+        {"start": 14, "end": 16, "text": "Next keep going."},
+    ]
+    assert [r["start"] for r in detect_cues(rows)] == [10.0]
+    assert len(detect_cues(rows, min_gap_s=1)) == 2
+
+
+def test_marker_alone_is_found_but_unnamed():
+    seg = segment(transcript=[{"start": 5, "end": 9, "text": "Next."}])
+    assert seg.steps[0].name == "" and seg.steps[0].id == "cue-1"
+    assert "naming-abstained" in seg.flags
+
+
+def test_long_names_trim_at_a_word_boundary():
+    text = "Now " + "word " * 30
+    (row,) = detect_cues([{"start": 0, "end": 1, "text": text}], max_name_chars=20)
+    assert row["name"] == "word word word word"
+
+
+def test_ytdlp_subtitle_index_is_no_fact():
+    seg = segment(
+        "v.mp4", metadata={"subtitles": {"en": [{"ext": "vtt", "url": "http://x"}]}}
+    )
+    assert "no-signal" in seg.flags
+
+
+def test_priority_chapters_over_cues_and_cues_over_nothing():
+    chapters = [{"start": 0, "end": 10, "title": "A"}]
+    seg = segment(metadata={"chapters": chapters, "subtitles": SRT})
+    assert seg.method == "chapters"
+    assert "ignored: metadata (subtitles)" in seg.flags
+    seg = segment(transcript=SRT, metadata={"subtitles": SRT})
+    assert seg.method == "subtitle-cues"  # human cues outrank ASR
+    assert "ignored: transcript" in seg.flags
+
+
+def test_explicit_segmenter_pin_and_missing_input():
+    assert segment(transcript=SRT, segmenter="transcript-cues").steps
+    with pytest.raises(ValueError, match="needs inputs"):
+        segment(segmenter="transcript-cues")
+
+
+def test_malformed_cues_say_what_is_wrong():
+    with pytest.raises(ValueError, match="cues\\[0\\]"):
+        normalize_timed_text([{"start": "x", "text": "hi"}])
+    with pytest.raises(ValueError, match="unusable times"):
+        normalize_timed_text([{"start": 5, "end": 1, "text": "hi"}])
+
+
+def test_registered_and_listed():
+    assert {"subtitle-cues", "transcript-cues"} <= set(capabilities())
+
+
+VTT_NO_HOURS = """WEBVTT
+
+00:12.000 --> 00:15.000
+<c>Now</c> the <00:00:13.000><c>basic step</c>
+
+00:40.000 --> 00:44.000
+Next, the turn.
+"""
+
+
+VTT_HOURS = "\ufeff  " + VTT_NO_HOURS.replace("00:12", "00:00:12").replace(
+    "00:15", "00:00:15"
+).replace("00:40", "00:00:40").replace("00:44", "00:00:44")
+
+
+@pytest.mark.parametrize("vtt", [VTT_NO_HOURS, VTT_HOURS])
+def test_vtt_with_and_without_hours(vtt):
+    rows = normalize_timed_text(vtt)
+    assert rows[0] == {"start": 12.0, "end": 15.0, "text": "Now the basic step"}
+    assert [r["start"] for r in rows] == [12.0, 40.0]
+
+
+def test_markup_and_speaker_prefixes_are_stripped():
+    rows = normalize_timed_text(
+        [
+            (5, 9, "{\\an8}<i>- Now the stance</i>"),
+            (30, 34, ">> [music] Next, the turn"),
+        ]
+    )
+    assert rows[0]["text"] == "- Now the stance"
+    assert [r["name"] for r in detect_cues(rows)] == ["the stance", "the turn"]
+
+
+def test_text_that_is_neither_timed_text_nor_a_file_raises():
+    with pytest.raises(ValueError, match="not an existing file"):
+        normalize_timed_text("no-such-file.srt")
+
+
+def test_folded_cue_names_an_unnamed_opener():
+    rows = [
+        {"start": 10, "end": 11, "text": "Now."},
+        {"start": 12, "end": 16, "text": "Step two: the turn."},
+    ]
+    assert detect_cues(rows) == [{"start": 10.0, "name": "the turn", "cue": "Now"}]
+
+
+def test_zero_length_trailing_step_is_dropped():
+    seg = segment(transcript=[(5, 30, "First, the stance."), (30, 30, "Finally.")])
+    assert [s.name for s in seg.steps] == ["the stance"]
+    assert seg.boundaries == (5.0, 30.0)
+    assert "trailing-cue-dropped" in seg.flags
+
+
+def test_intro_before_first_cue_is_flagged_only_when_present():
+    assert "intro-before: 5s" in segment(transcript=[(5, 9, "Next, x")]).flags
+    flags = segment(transcript=[(0, 9, "Next, x")]).flags
+    assert not any(f.startswith("intro-before") for f in flags)
+
+
+def test_path_object_input(tmp_path):
+    path = tmp_path / "talk.srt"
+    path.write_text(SRT, encoding="utf-8")
+    assert len(segment(transcript=Path(path)).steps) == 3
+
+
+def test_triples_and_whisper_segments():
+    triples = [(0, 4, "Hi"), (20, 25, "First, the stance.")]
+    whisper = {"segments": [{"start": s, "end": e, "text": t} for s, e, t in triples]}
+    assert normalize_timed_text(triples) == normalize_timed_text(whisper)
+    assert segment(transcript=whisper).steps[0].name == "the stance"
+
+
+def test_missing_mixing_names_the_install(monkeypatch):
+    real_import = builtins.__import__
+
+    def no_mixing(name, *args, **kwargs):
+        if name == "mixing" or name.startswith("mixing."):
+            raise ImportError("No module named 'mixing'")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", no_mixing)
+    with pytest.raises(ImportError, match="pip install mixing"):
+        normalize_timed_text(SRT)
+    assert normalize_timed_text([(0, 1, "Now")])  # cue rows need no mixing
+
+
+def test_cli_timed_text_only_parses_real_json():
+    assert tools._timed_text("[draft].srt") == "[draft].srt"
+    assert tools._timed_text('[{"start": 0, "end": 1, "text": "x"}]')[0]["text"] == "x"
+
+
+# ── second-review regressions ───────────────────────────────────────────────
+
+
+def test_unusable_subtitles_do_not_break_the_chapters_path():
+    chapters = [{"start": 0, "end": 10, "title": "A"}]
+    seg = segment(metadata={"chapters": chapters, "subtitles": "en"})
+    assert seg.method == "chapters"
+    assert any(flag.startswith("subtitles-unusable") for flag in seg.flags)
+
+
+def test_custom_pattern_without_a_group_works():
+    rows = [{"start": 0, "end": 5, "text": "Right, go."}]
+    (hit,) = detect_cues(rows, patterns=[r"right[,\s]+"])
+    assert hit["cue"] == "Right," and hit["name"] == "go"
+
+
+def test_first_of_all_is_one_marker():
+    (hit,) = detect_cues([{"start": 0, "end": 5, "text": "First of all, the stance."}])
+    assert hit["name"] == "the stance"
+
+
+def test_null_text_and_bool_times_are_refused():
+    with pytest.raises(ValueError):
+        normalize_timed_text([{"start": 0, "end": 1, "text": None}])
+    with pytest.raises(ValueError):
+        normalize_timed_text([{"start": True, "end": 1, "text": "x"}])
+
+
+def test_cli_segment_end_to_end_on_a_transcript(tmp_path):
+    from paces import tools
+
+    path = tmp_path / "talk.srt"
+    path.write_text(SRT, encoding="utf-8")
+    out = tools.segment(transcript=str(path))
+    assert out["method"] == "transcript-cues" and len(out["steps"]) == 3

{paces-0.0.12 → paces-0.0.14}/tests/test_evidence_schemas.py

@@ -12,6 +12,12 @@ halves of that claim:
   migration; a *changed* one is a wire break for every already-written store,
   and this test is what makes that a decision rather than an accident.
 
+Annotation-only keywords a lacing upgrade starts exporting (``default``,
+``description``) may be re-snapshotted — they validate nothing, so no stored
+body changes meaning (lacing 0.0.54 added the ``default_factory`` defaults;
+the floor in pyproject follows). A change to a field, type or ``required`` is
+the wire break and needs ``/v2``.
+
 Regenerating the snapshot deliberately::
 
     python -m tests.test_evidence_schemas   # writes tests/data/body_schemas.json

{paces-0.0.12 → paces-0.0.14}/tests/test_pose.py

@@ -464,9 +464,7 @@ def test_check_pose_requirements_names_the_repair_when_both_cv2_providers_presen
     monkeypatch.setattr(importlib.metadata, "version", fake_version)
     report = check_pose_requirements()
     assert report["cv2_providers"] == ["opencv-python", "opencv-contrib-python"]
-    assert any(
-        "pip install --force-reinstall" in note for note in report["notes"]
-    )
+    assert any("pip install --force-reinstall" in note for note in report["notes"])
 
 
 # ── the licence perimeter (packaging facts, guarded because nothing else is) ─