paces 0.0.5__tar.gz → 0.0.6__tar.gz

{paces-0.0.5 → paces-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.5
+Version: 0.0.6
 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
@@ -81,6 +81,7 @@ Same thing from the shell:
 ```bash
 paces segment VIDEO_URL --steps steps.json --grid grid.json --output seg.json
 paces to-document seg.json --source VIDEO_URL --title "My routine" --output document.json
+paces suggest-excerpts document.json --output document.json   # mark each block's loop window
 paces derive document.json --media routine.mp4   # real loop clips + gifs + posters
 paces render document.json --output page.html
 ```

{paces-0.0.5 → paces-0.0.6}/README.md

@@ -47,6 +47,7 @@ Same thing from the shell:
 ```bash
 paces segment VIDEO_URL --steps steps.json --grid grid.json --output seg.json
 paces to-document seg.json --source VIDEO_URL --title "My routine" --output document.json
+paces suggest-excerpts document.json --output document.json   # mark each block's loop window
 paces derive document.json --media routine.mp4   # real loop clips + gifs + posters
 paces render document.json --output page.html
 ```

{paces-0.0.5 → paces-0.0.6}/paces/__init__.py

@@ -59,6 +59,7 @@ from paces.derivation import (
     resolve_crop_box,
 )
 from paces.edits import apply_edits, merge_regenerated
+from paces.excerpts import ExcerptResult, suggest_excerpts
 from paces.measure import GridMeasurement, measure_grid
 from paces.projection import to_document
 from paces.render import render_html
@@ -102,6 +103,8 @@ __all__ = [
     "GridMeasurement",
     "to_document",
     # media derivation (issue #1, ADR-0005)
+    "suggest_excerpts",
+    "ExcerptResult",
     "derive_document",
     "DeriveResult",
     "DirStore",

paces-0.0.6/paces/excerpts.py

@@ -0,0 +1,154 @@
+"""Excerpt suggestion: mark the loopable sub-window each step's clip is cut
+from.
+
+A :class:`~paces.model.SourceSpan` with an ``excerpt`` is what media
+derivation (ADR-0005) cuts; nothing upstream sets one. This module holds the
+v1 heuristic (issue #3's cost note): **a step's excerpt is its own grid
+window** — the span itself — or, with ``units=``, its first N metric units.
+Editorial window-picking (the POC spent ~11 min of LLM agents over contact
+sheets choosing windows by eye) is a later capability that replaces this
+default behind the same seam; corrections meanwhile are ordinary document
+edits, which a suggestion must never eat:
+
+- an existing excerpt is only replaced under ``overwrite=True``, and even
+  then only by a real new suggestion — **never by nothing** (a heuristic
+  that cannot compute a window keeps what the human picked, with a flag);
+- a step carrying any span-level lock that could denote an excerpt gets
+  **no suggestions at all**: lock paths are recorded in index form and a
+  regeneration merge reorders spans (``edits.py``'s own premise), so "which
+  span does ``/spans/0/excerpt`` mean now?" cannot be answered here —
+  abstaining loses a default; guessing can silently undo a locked edit.
+
+Honesty flags over silence: every span this module skips or cannot fill is
+flagged by name.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from fractions import Fraction
+
+from paces.model import (
+    SourceSpan,
+    Step,
+    StepDocument,
+    decimal_str,
+    seconds_per_unit,
+)
+
+#: The span role a clip is cut from by default — the at-tempo run-through.
+DFLT_EXCERPT_ROLE = "performance"
+
+#: A lock path that could denote a span's excerpt: the whole spans list, a
+#: whole span, or anything mentioning an excerpt. A narrower span field
+#: (caption, label) denotes that field under any reordering and never blocks.
+_SPAN_LOCK = re.compile(r"^/spans(/\d+)?$|^/spans/.*excerpt")
+
+
+@dataclass
+class ExcerptResult:
+    """The updated document plus the honesty flags."""
+
+    document: StepDocument
+    flags: list[str] = field(default_factory=list)
+    suggested: list[str] = field(default_factory=list)  # step ids touched
+
+
+def _walk_steps(steps: list[Step]):
+    for step in steps:
+        yield step
+        yield from _walk_steps(step.steps)
+
+
+def _excerpts_locked(step: Step) -> bool:
+    return any(_SPAN_LOCK.search(lock.path) for lock in step.locks)
+
+
+def suggest_excerpts(
+    document: StepDocument,
+    *,
+    units: float | None = None,
+    role: str = DFLT_EXCERPT_ROLE,
+    overwrite: bool = False,
+) -> ExcerptResult:
+    """Fill each step's first *role* span with a suggested ``excerpt``.
+
+    Args:
+        document: the committed document (worked on a deep copy).
+        units: ``None`` (default) → the excerpt is the span's whole window
+            (``start``..``end`` — for grid-placed segmentation that IS the
+            block's grid window, which is issue #3's acceptance). A number →
+            the first that-many metric units from the span's start, computed
+            through the document's grid and clipped to the span's end.
+        role: which span carries the clip (default ``"performance"`` — the
+            run-through). A step whose spans lack the role is flagged; a
+            step with SEVERAL role spans gets a suggestion on the first and
+            a ``multiple-<role>-spans:`` flag for the rest (the POC's b8
+            shape — the other moments still derive once excerpts are set by
+            hand or a future picker).
+        overwrite: replace existing excerpts with new suggestions. Off by
+            default; replacement never degrades to deletion, and a span-
+            locked step abstains entirely (see the module docstring).
+    """
+    if units is not None:
+        if not math.isfinite(units) or units <= 0:
+            raise ValueError(f"units must be a positive number, got {units}")
+    doc = document.model_copy(deep=True)
+    result = ExcerptResult(document=doc)
+    flags = result.flags
+
+    spu = None
+    if units is not None:
+        grid = doc.metric
+        spu = seconds_per_unit(grid) if grid is not None else None
+        if spu is None:
+            flags.append(
+                "no-grid: units= needs a metric grid with a tempo; "
+                "use units=None (the span's whole window) instead"
+            )
+            return result
+
+    for step in _walk_steps(doc.steps):
+        if not step.spans:
+            continue
+        role_spans = [span for span in step.spans if span.role == role]
+        if not role_spans:
+            flags.append(f"no-{role}-span:{step.id}")
+            continue
+        if len(role_spans) > 1:
+            flags.append(f"multiple-{role}-spans:{step.id}")
+        if _excerpts_locked(step):
+            flags.append(f"locked-excerpt-kept:{step.id}")
+            continue
+        span = role_spans[0]
+        if span.excerpt is not None and not overwrite:
+            continue
+        suggestion = _suggest_for_span(span, units=units, spu=spu)
+        if suggestion is None:
+            # nothing computable: keep whatever is there — replacement must
+            # never degrade to deletion — and say so
+            flags.append(f"no-extent:{step.id}")
+            continue
+        span.excerpt = suggestion
+        result.suggested.append(step.id)
+    return result
+
+
+def _suggest_for_span(
+    span: SourceSpan, *, units: float | None, spu: float | None
+) -> tuple[str, str] | None:
+    """One span's suggested window, as exact wire decimals — or ``None``
+    when the span records no extent to cut (inventing one would be data)."""
+    if units is None:
+        if span.end is None:
+            return None
+        return (span.start, span.end)
+    end_s = float(Fraction(span.start)) + units * spu
+    if span.end is not None:
+        end_s = min(end_s, float(Fraction(span.end)))
+    end = decimal_str(end_s)
+    if Fraction(end) <= Fraction(span.start):
+        return None
+    return (span.start, end)

{paces-0.0.5 → paces-0.0.6}/paces/measure.py

@@ -84,6 +84,34 @@ class GridMeasurement:
     evidence: Mapping[str, Any] = field(default_factory=dict)
 
 
+def _load_audio(path, *, sample_rate):
+    """Decode *path* to ``(samples, rate)`` — wav-family natively, anything
+    else through pydub's ffmpeg decode to a temp wav.
+
+    librosa reads only what soundfile can open (wav/flac/ogg); for an .mp4
+    or .mp3 it silently falls back to its DEPRECATED audioread path when
+    that package happens to be installed, and raises when it is not — which
+    is exactly how this worked on a dev machine and failed on CI. Routing
+    non-wav through pydub gives one decode path (the same ffmpeg pydub
+    already uses for ``find_segments`` on the same file) that survives
+    librosa 1.0.
+    """
+    import librosa
+
+    try:
+        return librosa.load(str(path), sr=sample_rate)
+    except Exception:
+        import tempfile
+
+        from pydub import AudioSegment
+
+        audio = AudioSegment.from_file(str(path))
+        with tempfile.TemporaryDirectory() as tmp:
+            wav_path = Path(tmp) / "decoded.wav"
+            audio.export(str(wav_path), format="wav")
+            return librosa.load(str(wav_path), sr=sample_rate)
+
+
 def _measured_tempo(beat_grid_result) -> tuple[str | None, float | None]:
     """The tempo as a wire decimal, or None when there is no beat structure.
 
@@ -168,7 +196,7 @@ def measure_grid(
     if music:
         region = max(music, key=lambda s: s.end - s.start)
         try:
-            samples, rate = librosa.load(str(path), sr=sample_rate)
+            samples, rate = _load_audio(path, sample_rate=sample_rate)
         except Exception as error:
             raise MediaDecodeError(
                 f"could not decode {media!r} as audio ({type(error).__name__})"

{paces-0.0.5 → paces-0.0.6}/paces/tools.py

@@ -15,6 +15,7 @@ from pathlib import Path
 
 from paces import (
     edits as edits_module,
+    excerpts as excerpts_module,
     model,
     projection,
     render as render_module,
@@ -402,6 +403,38 @@ def derive(
     }
 
 
+def suggest_excerpts(
+    document,
+    *,
+    units: float | None = None,
+    role: str = excerpts_module.DFLT_EXCERPT_ROLE,
+    overwrite: bool = False,
+    output: str | None = None,
+) -> dict:
+    """Mark each step's loopable sub-window (the ``excerpt`` derive cuts).
+
+    v1 heuristic (issue #3): the excerpt is the span's whole grid window;
+    ``units=N`` takes the first N metric units instead. Never overwrites an
+    existing excerpt unless ``overwrite`` (and never a locked one). Returns
+    ``{"document", "flags", "suggested"}``; writes to ``output=`` when given.
+    """
+    result = excerpts_module.suggest_excerpts(
+        _as_document(document),
+        # the CLI hands numbers over as strings
+        units=None if units is None else float(units),
+        role=role,
+        overwrite=overwrite,
+    )
+    text = model.dumps_document(result.document)
+    if output:
+        Path(output).write_text(text, encoding="utf-8")
+    return {
+        "document": json.loads(text),
+        "flags": result.flags,
+        "suggested": result.suggested,
+    }
+
+
 def list_segmenters() -> dict:
     """The registered segmentation capabilities: name → what it needs/gives."""
     return {
@@ -420,6 +453,7 @@ _dispatch_funcs = [
     segment,
     to_document,
     render,
+    suggest_excerpts,
     derive,
     edit,
     merge,

{paces-0.0.5 → paces-0.0.6}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paces"
-version = "0.0.5"
+version = "0.0.6"
 description = "Turn instructional media into structured, interactive learning material"
 readme = "README.md"
 license = "MIT"
@@ -78,6 +78,21 @@ docs = [
     "sphinx-rtd-theme>=1.0",
 ]
 
+# System ffmpeg (ADR-0005 §2's trigger, fired by the vertical slice test:
+# measure_grid on an .mp4 goes through pydub/librosa's PATH-ffmpeg, which the
+# pip-bundled imageio-ffmpeg binary cannot serve). Consumed by wads CI's
+# install-system-deps on the Linux AND Windows legs; install.macos serves
+# local dev. Shape mirrors mixing's block.
+[tool.wads.ops.ffmpeg]
+description = "Multimedia framework for video/audio processing"
+url = "https://ffmpeg.org/"
+check.linux = "which ffmpeg"
+check.macos = "which ffmpeg"
+check.windows = "which ffmpeg"
+install.linux = ["sudo apt-get update", "sudo apt-get install -y ffmpeg"]
+install.macos = "brew install ffmpeg"
+install.windows = "choco install ffmpeg -y --no-progress"
+
 [tool.hatch.build.targets.wheel]
 packages = ["paces"]
 

paces-0.0.6/tests/test_excerpts.py

@@ -0,0 +1,276 @@
+"""Excerpt suggestion (issue #3's v1 heuristic) — pure, no media."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from paces.excerpts import suggest_excerpts
+from paces.model import (
+    Lock,
+    Measure,
+    MetricGrid,
+    Source,
+    SourceSpan,
+    Step,
+    StepDocument,
+    dumps_document,
+)
+
+GRID = MetricGrid(unit="eight", subdivisions=8, tempo_bpm="120", origin="10")
+SPU = 4.0  # 8 * 60 / 120
+
+
+def _doc(steps, *, metric=GRID):
+    return StepDocument(
+        id="routine",
+        title="Routine",
+        metric=metric,
+        sources=[Source(id="perf", kind="video", uri="https://x")],
+        steps=steps,
+    )
+
+
+def _step(step_id="b1", *, spans=None, **kwargs):
+    return Step(
+        id=step_id,
+        name="Step",
+        duration=Measure(value="2", unit="eight"),
+        spans=spans
+        if spans is not None
+        else [SourceSpan(source="perf", start="10", end="18")],
+        **kwargs,
+    )
+
+
+def test_default_is_the_spans_whole_window():
+    result = suggest_excerpts(_doc([_step()]))
+    (span,) = result.document.steps[0].spans
+    assert span.excerpt == ("10", "18")
+    assert result.suggested == ["b1"] and result.flags == []
+
+
+def test_units_takes_the_first_n_grid_units():
+    result = suggest_excerpts(_doc([_step()]), units=1)
+    (span,) = result.document.steps[0].spans
+    assert span.excerpt == ("10", "14")  # 1 unit at 4 s/unit
+
+
+def test_units_is_clipped_to_the_spans_end():
+    result = suggest_excerpts(_doc([_step()]), units=5)
+    (span,) = result.document.steps[0].spans
+    assert span.excerpt == ("10", "18")  # 5 x 4 = 20s, clipped at end
+
+
+def test_units_without_a_grid_flags_and_suggests_nothing():
+    result = suggest_excerpts(_doc([_step()], metric=None), units=1)
+    assert any(f.startswith("no-grid") for f in result.flags)
+    assert result.document.steps[0].spans[0].excerpt is None
+    with pytest.raises(ValueError, match="positive"):
+        suggest_excerpts(_doc([_step()]), units=0)
+
+
+def test_deep_link_span_with_units_gets_a_window():
+    # end=None ("starts here, extent not recorded") + units: the grid knows
+    step = _step(spans=[SourceSpan(source="perf", start="10")])
+    result = suggest_excerpts(_doc([step]), units=2)
+    assert result.document.steps[0].spans[0].excerpt == ("10", "18")
+
+
+def test_deep_link_span_without_units_is_flagged_not_invented():
+    step = _step(spans=[SourceSpan(source="perf", start="10")])
+    result = suggest_excerpts(_doc([step]))
+    assert result.document.steps[0].spans[0].excerpt is None
+    assert "no-extent:b1" in result.flags
+
+
+def test_existing_excerpt_is_never_eaten_by_default():
+    step = _step(
+        spans=[SourceSpan(source="perf", start="10", end="18", excerpt=("11", "13"))]
+    )
+    result = suggest_excerpts(_doc([step]))
+    assert result.document.steps[0].spans[0].excerpt == ("11", "13")
+    assert result.suggested == []
+    overwritten = suggest_excerpts(_doc([step]), overwrite=True)
+    assert overwritten.document.steps[0].spans[0].excerpt == ("10", "18")
+
+
+def test_locked_excerpt_survives_even_overwrite():
+    step = _step(
+        spans=[SourceSpan(source="perf", start="10", end="18", excerpt=("11", "13"))],
+        locks=[
+            Lock(path="/spans/0/excerpt", by="user:thor", at="2026-08-31T00:00:00Z")
+        ],
+    )
+    result = suggest_excerpts(_doc([step]), overwrite=True)
+    assert result.document.steps[0].spans[0].excerpt == ("11", "13")
+    assert "locked-excerpt-kept:b1" in result.flags
+
+
+def test_missing_role_is_flagged_and_role_is_selectable():
+    step = _step(
+        spans=[SourceSpan(source="perf", role="instruction", start="10", end="18")]
+    )
+    result = suggest_excerpts(_doc([step]))
+    assert "no-performance-span:b1" in result.flags
+    by_role = suggest_excerpts(_doc([step]), role="instruction")
+    assert by_role.document.steps[0].spans[0].excerpt == ("10", "18")
+
+
+def test_child_steps_are_walked_and_the_original_is_untouched():
+    child = _step("b1-1", spans=[SourceSpan(source="perf", start="10", end="14")])
+    parent = _step("b1", spans=[])
+    parent.steps.append(child)
+    doc = _doc([parent])
+    result = suggest_excerpts(doc)
+    assert result.document.steps[0].steps[0].spans[0].excerpt == ("10", "14")
+    assert doc.steps[0].steps[0].spans[0].excerpt is None  # deep copy
+
+
+def test_wire_stays_float_free():
+    def fail(value):
+        raise AssertionError(f"float on the wire: {value}")
+
+    grid = MetricGrid(unit="eight", subdivisions=8, tempo_bpm="129.2", origin="51.2")
+    step = _step(spans=[SourceSpan(source="perf", start="95.8")])
+    result = suggest_excerpts(_doc([step], metric=grid), units=1.4)
+    json.loads(dumps_document(result.document), parse_float=fail)
+
+
+# ── review-round regressions ────────────────────────────────────────────────
+
+
+def test_overwrite_never_degrades_to_deletion():
+    # the review's blocker: overwrite=True on a span the heuristic cannot
+    # window (end=None, units=None) must KEEP the hand excerpt, not None it
+    step = _step(spans=[SourceSpan(source="perf", start="10", excerpt=("11", "13"))])
+    result = suggest_excerpts(_doc([step]), overwrite=True)
+    assert result.document.steps[0].spans[0].excerpt == ("11", "13")
+    assert "no-extent:b1" in result.flags and result.suggested == []
+
+
+def test_tiny_units_collapse_keeps_the_existing_excerpt():
+    # decimal rounding can collapse the window to zero length — same rule
+    step = _step(
+        spans=[SourceSpan(source="perf", start="10", end="18", excerpt=("11", "13"))]
+    )
+    result = suggest_excerpts(_doc([step]), units=0.0001, overwrite=True)
+    assert result.document.steps[0].spans[0].excerpt == ("11", "13")
+    assert "no-extent:b1" in result.flags
+
+
+def test_span_locks_abstain_even_when_reordered():
+    # the review's other blocker: lock paths are index-form and a merge
+    # reorders spans, so "/spans/0/excerpt" may denote a DIFFERENT span now.
+    # The suggestion abstains for the whole step rather than guess.
+    step = _step(
+        spans=[
+            SourceSpan(source="perf", role="instruction", start="5", end="9"),
+            SourceSpan(source="perf", start="10", end="18"),  # role span at 1
+        ],
+        locks=[
+            Lock(path="/spans/0/excerpt", by="user:thor", at="2026-08-31T00:00:00Z")
+        ],
+    )
+    result = suggest_excerpts(_doc([step]), overwrite=True)
+    assert all(span.excerpt is None for span in result.document.steps[0].spans)
+    assert "locked-excerpt-kept:b1" in result.flags
+
+
+def test_whole_span_lock_protects_its_excerpt():
+    # `paces edit` on a whole span records Lock(path="/spans/0") — the merge
+    # honors it for the whole span, so suggestion must too
+    step = _step(
+        spans=[SourceSpan(source="perf", start="10", end="18", excerpt=("11", "13"))],
+        locks=[Lock(path="/spans/0", by="user:thor", at="2026-08-31T00:00:00Z")],
+    )
+    result = suggest_excerpts(_doc([step]), overwrite=True)
+    assert result.document.steps[0].spans[0].excerpt == ("11", "13")
+    assert "locked-excerpt-kept:b1" in result.flags
+
+
+def test_locked_hand_cleared_excerpt_stays_cleared():
+    # a hand-CLEARED excerpt (edit to None writes a lock) must not be refilled
+    step = _step(
+        spans=[SourceSpan(source="perf", start="10", end="18")],
+        locks=[
+            Lock(path="/spans/0/excerpt", by="user:thor", at="2026-08-31T00:00:00Z")
+        ],
+    )
+    result = suggest_excerpts(_doc([step]))
+    assert result.document.steps[0].spans[0].excerpt is None
+    assert "locked-excerpt-kept:b1" in result.flags
+
+
+def test_caption_lock_does_not_block_suggestion():
+    # a narrower span-field lock denotes that field under any reordering
+    step = _step(
+        locks=[Lock(path="/spans/0/caption", by="user:thor", at="2026-08-31T00:00:00Z")]
+    )
+    result = suggest_excerpts(_doc([step]))
+    assert result.document.steps[0].spans[0].excerpt == ("10", "18")
+
+
+def test_multiple_role_spans_fill_first_and_flag_the_rest():
+    # the POC's b8 shape: two performance moments on one step. The first
+    # gets the suggestion; the second is FLAGGED, never silently skipped.
+    step = _step(
+        "b8",
+        spans=[
+            SourceSpan(source="perf", start="10", end="18"),
+            SourceSpan(source="perf", start="120", end="128"),
+        ],
+    )
+    result = suggest_excerpts(_doc([step]))
+    first, second = result.document.steps[0].spans
+    assert first.excerpt == ("10", "18") and second.excerpt is None
+    assert "multiple-performance-spans:b8" in result.flags
+
+
+def test_every_top_level_step_is_suggested():
+    # kills the walk-only-the-last-step mutant the e2e's membership assert let by
+    steps = [
+        _step("b1", spans=[SourceSpan(source="perf", start="0", end="8")]),
+        _step("b2", spans=[SourceSpan(source="perf", start="8", end="16")]),
+        _step("b3", spans=[SourceSpan(source="perf", start="16", end="24")]),
+    ]
+    result = suggest_excerpts(_doc(steps))
+    assert result.suggested == ["b1", "b2", "b3"]
+    assert result.flags == []
+
+
+def test_bad_units_raise_regardless_of_grid():
+    for bad in (0, -3, float("nan"), float("inf")):
+        with pytest.raises(ValueError, match="positive"):
+            suggest_excerpts(_doc([_step()], metric=None), units=bad)
+
+
+def test_computed_end_is_an_exact_clean_decimal():
+    # 95.8 + 1.4 x (8*60/129.2) = 101.0012... -> exactly "101.001" on the
+    # wire, never a float-repr tail (the parse_float gate cannot see string
+    # payloads, so pin the string itself)
+    grid = MetricGrid(unit="eight", subdivisions=8, tempo_bpm="129.2", origin="51.2")
+    step = _step(spans=[SourceSpan(source="perf", start="95.8")])
+    result = suggest_excerpts(_doc([step], metric=grid), units=1.4)
+    assert result.document.steps[0].spans[0].excerpt == ("95.8", "101.001")
+
+
+def test_container_steps_stay_flag_free():
+    child = _step("b1-1", spans=[SourceSpan(source="perf", start="10", end="14")])
+    parent = _step("b1", spans=[])
+    parent.steps.append(child)
+    result = suggest_excerpts(_doc([parent]))
+    assert result.flags == []
+
+
+def test_tools_verb_coerces_cli_string_units():
+    from paces import tools
+
+    doc = _doc([_step()])
+    payload = tools.suggest_excerpts(
+        json.loads(dumps_document(doc)),
+        units="1",  # argh hands strings over
+    )
+    span = payload["document"]["steps"][0]["spans"][0]
+    assert span["excerpt"] == ["10", "14"]

paces-0.0.6/tests/test_vertical_slice.py

@@ -0,0 +1,224 @@
+"""Issue #3: the vertical slice — raw audio-bearing video in, practice page
+with a real loop clip at the grid-computed boundaries out.
+
+This is the integration test of the whole pipeline — grid measurement (#2) →
+grid-placed segmentation → excerpt suggestion → media derivation (#1) →
+render — run through the SAME tool surface the CLI dispatches, on synthetic
+media whose ground truth is known (``audio_synth.practice_audio`` muxed onto
+the rect video). Deliberately NO new architecture: everything here is the
+shipped verbs composed. Fail — never skip — when deps are missing.
+
+``measure_grid`` on an .mp4 needs a SYSTEM ffmpeg (pydub/librosa read the
+audio track via PATH ffmpeg — the bundled moviepy binary cannot serve them),
+which is why paces now declares ``[tool.wads.ops.ffmpeg]`` (ADR-0005 §2's
+fired trigger). Everything derive does still runs bundled-only.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from fractions import Fraction
+from pathlib import Path
+
+import librosa  # noqa: F401 — fail loudly, never skip
+import mixing  # noqa: F401
+import moviepy  # noqa: F401
+import pytest
+
+from video_synth import FRAME_SIZE, practice_av
+
+#: The synthetic routine: 8 eights of music at the POC's tempo. The last
+#: block is the "Déhanchés" analog — the one whose card must carry a clip.
+BPM = 129.2
+STEPS = [["Intro", 2], ["Bras", 2], ["Déhanchés", 4]]
+TOTAL_UNITS = 8
+SPU_TRUTH = 8 * 60 / BPM  # ≈ 3.715 s per eight
+
+#: Measurement tolerances, from test_measure's proven bounds: tempo ±0.5 bpm
+#: and origin ≈ the music start. The block boundary inherits origin error
+#: plus 4 units of tempo drift — ±1.0 s is generous against those and still
+#: fails on a half-unit (1.86 s) placement error.
+BOUNDARY_TOLERANCE_S = 1.0
+
+SOURCE = {"id": "rt", "kind": "video", "uri": "https://example.com/run-through"}
+
+
+@pytest.fixture(scope="module")
+def av(tmp_path_factory):
+    path, truth = practice_av(
+        tmp_path_factory.mktemp("slice") / "run_through.mp4",
+        bpm=BPM,
+        music_s=32.0,  # 8 units ≈ 29.7 s + headroom for measurement drift
+    )
+    return path, truth
+
+
+def test_the_slice_end_to_end(tmp_path, av):
+    from paces import tools
+
+    video, truth = av
+
+    # 1. segment: measures the grid from the media, places the step list
+    seg = tools.segment(str(video), steps=STEPS)
+    grid = seg["grid"]
+    assert grid is not None, seg["flags"]
+    assert float(Fraction(grid["tempoBpm"])) == pytest.approx(BPM, abs=0.5)
+    assert float(Fraction(grid["origin"])) == pytest.approx(
+        truth["music_start_s"], abs=0.6
+    )
+
+    # 2. project into the committed document
+    doc_path = tmp_path / "document.json"
+    tools.to_document(
+        seg, doc_id="routine", title="Routine", source=SOURCE, output=str(doc_path)
+    )
+
+    # 3. suggest excerpts: each block's clip window IS its grid window —
+    # EVERY block, not just the asserted one
+    payload = tools.suggest_excerpts(str(doc_path), output=str(doc_path))
+    assert payload["suggested"] == ["intro", "bras", "dehanches"]
+    doc = json.loads(doc_path.read_text())
+    block = next(s for s in doc["steps"] if s["id"] == "dehanches")
+    excerpt = block["spans"][0]["excerpt"]
+    start_s, end_s = (float(Fraction(v)) for v in excerpt)
+
+    # the excerpt sits on the measured grid: block 3 spans units 4..8
+    origin = float(Fraction(grid["origin"]))
+    spu = 8 * 60 / float(Fraction(grid["tempoBpm"]))
+    assert start_s == pytest.approx(origin + 4 * spu, abs=0.01)
+    assert end_s == pytest.approx(origin + 8 * spu, abs=0.01)
+    # ...and on the TRUTH the media was synthesized with
+    assert start_s == pytest.approx(
+        truth["music_start_s"] + 4 * SPU_TRUTH, abs=BOUNDARY_TOLERANCE_S
+    )
+    assert end_s == pytest.approx(
+        truth["music_start_s"] + 8 * SPU_TRUTH, abs=BOUNDARY_TOLERANCE_S
+    )
+
+    # 4. derive: a real clip is cut at those boundaries
+    derived = tools.derive(str(doc_path), media=str(video))
+    assert not any(f.startswith("stale-artifact") for f in derived["flags"])
+    clip_path = tmp_path / "media" / "dehanches.mp4"
+    assert clip_path.is_file()
+    probed_w, probed_h = mixing.get_video_dimensions(str(clip_path))
+    assert (probed_w, probed_h) == FRAME_SIZE  # no-crop default: full frame
+    doc = json.loads(doc_path.read_text())
+    block = next(s for s in doc["steps"] if s["id"] == "dehanches")
+    clip_ref = next(a for a in block["artifacts"] if a["role"] == "clip")
+    assert clip_ref["uri"] == "media/dehanches.mp4"
+    assert float(Fraction(clip_ref["durationS"])) == pytest.approx(4 * spu, abs=0.05)
+
+    # 5. render: the card shows the looping clip
+    page_path = tmp_path / "page.html"
+    tools.render(str(doc_path), output=str(page_path))
+    page = page_path.read_text()
+    assert '<source src="media/dehanches.mp4"' in page
+    assert "<video controls loop muted playsinline" in page
+    assert 'poster="media/dehanches.jpg"' in page
+    assert "Déhanchés" in page
+
+    # 6. the caption is editorial content and arrives as a hand EDIT (which
+    # writes a Lock) — the POC card's caption path, exercised the house way
+    caption = "Jambes tendues, le bassin pulse"
+    tools.edit(
+        str(doc_path),
+        [
+            {
+                "op": "set",
+                "path": "/steps/dehanches/spans/0/caption",
+                "value": caption,
+            }
+        ],
+        by="user:test",
+        output=str(doc_path),
+    )
+
+    # 7. the crop is hand-tuned via the recipes sidecar (ADR-0005 §3's
+    # documented flow: edit box, set locked) — and the digest gate re-cuts
+    from paces.derivation import load_recipes, save_recipes
+
+    sidecar = tmp_path / "document.recipes.json"
+    recipes = load_recipes(sidecar)
+    span_start = block["spans"][0]["start"]
+    key = f"dehanches/rt/performance/{span_start}"
+    recipes.entries[key].box = (60, 40, 100, 80)
+    recipes.entries[key].locked = True
+    save_recipes(recipes, sidecar)
+    tools.derive(str(doc_path), media=str(video))
+    assert tuple(mixing.get_video_dimensions(str(clip_path))) == (100, 80), (
+        "the locked hand box must re-cut the existing clip"
+    )
+
+    tools.render(str(doc_path), output=str(page_path))
+    page = page_path.read_text()
+    assert caption in page  # the card carries the caption
+    assert '<source src="media/dehanches.mp4"' in page  # and still the clip
+
+
+def test_the_slice_via_the_cli(tmp_path, av):
+    """The kickoff's step 4 as literal shell commands — every seam on its
+    default, through ``python -m paces`` exactly as a user would type it."""
+    video, _truth = av
+    (tmp_path / "steps.json").write_text(
+        json.dumps(STEPS, ensure_ascii=False), encoding="utf-8"
+    )
+
+    def run(*args: str) -> None:
+        result = subprocess.run(
+            [sys.executable, "-m", "paces", *args],
+            cwd=tmp_path,
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0, result.stderr
+
+    run("segment", str(video), "--steps", "steps.json", "--output", "seg.json")
+    run(
+        "to-document",
+        "seg.json",
+        "--source",
+        json.dumps(SOURCE),
+        "--doc-id",
+        "routine",
+        "--title",
+        "Routine",
+        "--output",
+        "document.json",
+    )
+    run("suggest-excerpts", "document.json", "--output", "document.json")
+    run("derive", "document.json", "--media", str(video))
+    run("render", "document.json", "--output", "page.html")
+
+    assert (tmp_path / "media" / "dehanches.mp4").is_file()
+    assert (tmp_path / "media" / "dehanches.gif").is_file()
+    assert (tmp_path / "document.recipes.json").is_file()
+    page = (tmp_path / "page.html").read_text()
+    assert '<source src="media/dehanches.mp4"' in page
+
+
+def test_measure_decodes_mp4_without_librosas_deprecated_fallback(av, monkeypatch):
+    """CI regression: librosa reads only soundfile formats and silently leans
+    on its deprecated audioread fallback when that package happens to be
+    installed (dev machines) — and raises where it is not (CI). Simulate the
+    CI condition and prove the pydub decode path carries the mp4."""
+    import librosa
+
+    from paces import measure
+
+    video, truth = av
+    real_load = librosa.load
+
+    def no_fallback_load(path, **kwargs):
+        if str(path).endswith(".mp4"):
+            raise RuntimeError("simulated: soundfile cannot open mp4")
+        return real_load(path, **kwargs)
+
+    monkeypatch.setattr(librosa, "load", no_fallback_load)
+    samples, rate = measure._load_audio(video, sample_rate=22050)
+    assert rate == 22050 and samples.size > 20 * 22050  # ~41 s of audio
+    # and the full measurement still lands on the truth through this path
+    measurement = measure.measure_grid(str(video))
+    assert measurement.grid.tempo_bpm is not None
+    assert float(measurement.grid.tempo_bpm) == pytest.approx(truth["bpm"], abs=0.5)

paces-0.0.6/tests/video_synth.py

@@ -0,0 +1,74 @@
+"""Deterministic synthetic practice video for derivation and slice tests.
+
+A static green rectangle at a known, asymmetric position (x != y) on a blue
+background — spatially non-uniform on purpose: a solid-color clip cannot
+distinguish a correct crop origin from an x/y-swapped one. Written with
+moviepy, whose writer is the pip-bundled imageio-ffmpeg binary, so building
+these fixtures needs no system ffmpeg (ADR-0005 §2) — though READING the
+audio back out of :func:`practice_av`'s mp4 (what ``measure_grid`` does) is
+the system-ffmpeg channel.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+#: The subject's pixel box (x, y, w, h) and the frame size.
+RECT_XYWH = (60, 40, 100, 80)
+FRAME_SIZE = (320, 240)
+
+
+def _rect_frame():
+    import numpy as np
+
+    width, height = FRAME_SIZE
+    x, y, w, h = RECT_XYWH
+    frame = np.zeros((height, width, 3), dtype=np.uint8)
+    frame[:, :] = (0, 0, 255)  # blue background (RGB)
+    frame[y : y + h, x : x + w] = (0, 255, 0)  # green subject
+    return frame
+
+
+def practice_video(path: str | Path, *, duration_s: float = 2.0, fps: int = 24) -> Path:
+    """Write the (silent) fixture mp4 to ``path`` and return it."""
+    from moviepy.video.io.ImageSequenceClip import ImageSequenceClip
+
+    clip = ImageSequenceClip([_rect_frame()] * int(duration_s * fps), fps=fps)
+    clip.write_videofile(str(path), codec="libx264", audio=False, logger=None)
+    clip.close()
+    return Path(path)
+
+
+def practice_av(
+    path: str | Path,
+    *,
+    bpm: float = 129.2,
+    speech_s: float = 8.0,
+    silence_s: float = 1.5,
+    music_s: float = 30.0,
+    fps: int = 12,
+    seed: int = 0,
+) -> tuple[Path, dict]:
+    """One audio-bearing practice VIDEO — the vertical slice's raw input.
+
+    The audio track is :func:`audio_synth.practice_audio` (speech, a pause,
+    then kick-driven music at *bpm* — the POC's macro-structure), muxed onto
+    the rect visual. Returns ``(path, truth)`` with the synthesis ground
+    truth (music start/end, bpm).
+    """
+    import numpy as np
+    from moviepy.audio.AudioClip import AudioArrayClip
+    from moviepy.video.io.ImageSequenceClip import ImageSequenceClip
+
+    from audio_synth import practice_audio
+
+    samples, truth = practice_audio(
+        bpm=bpm, speech_s=speech_s, silence_s=silence_s, music_s=music_s, seed=seed
+    )
+    total_s = samples.size / truth["sample_rate"]
+    clip = ImageSequenceClip([_rect_frame()] * int(total_s * fps), fps=fps)
+    stereo = np.column_stack([samples, samples])
+    clip = clip.with_audio(AudioArrayClip(stereo, fps=truth["sample_rate"]))
+    clip.write_videofile(str(path), codec="libx264", audio_codec="aac", logger=None)
+    clip.close()
+    return Path(path), truth

paces-0.0.5/tests/video_synth.py

@@ -1,32 +0,0 @@
-"""Deterministic synthetic practice video for derivation tests.
-
-A static green rectangle at a known, asymmetric position (x != y) on a blue
-background — spatially non-uniform on purpose: a solid-color clip cannot
-distinguish a correct crop origin from an x/y-swapped one. Written with
-moviepy, whose writer is the pip-bundled imageio-ffmpeg binary, so building
-this fixture needs no system ffmpeg (ADR-0005 §2).
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-#: The subject's pixel box (x, y, w, h) and the frame size.
-RECT_XYWH = (60, 40, 100, 80)
-FRAME_SIZE = (320, 240)
-
-
-def practice_video(path: str | Path, *, duration_s: float = 2.0, fps: int = 24) -> Path:
-    """Write the fixture mp4 to ``path`` and return it."""
-    import numpy as np
-    from moviepy.video.io.ImageSequenceClip import ImageSequenceClip
-
-    width, height = FRAME_SIZE
-    x, y, w, h = RECT_XYWH
-    frame = np.zeros((height, width, 3), dtype=np.uint8)
-    frame[:, :] = (0, 0, 255)  # blue background (RGB)
-    frame[y : y + h, x : x + w] = (0, 255, 0)  # green subject
-    clip = ImageSequenceClip([frame] * int(duration_s * fps), fps=fps)
-    clip.write_videofile(str(path), codec="libx264", audio=False, logger=None)
-    clip.close()
-    return Path(path)