paces 0.0.3__tar.gz → 0.0.4__tar.gz

{paces-0.0.3 → paces-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.3
+Version: 0.0.4
 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
@@ -11,11 +11,17 @@ License-File: LICENSE
 Keywords: dance,instructional-video,learning-material,practice,segmentation,steps,tutorial
 Requires-Python: >=3.10
 Requires-Dist: pydantic>=2.6
+Provides-Extra: audio
+Requires-Dist: audioop-lts; (python_version >= '3.13') and extra == 'audio'
+Requires-Dist: mixing[audio,beats]>=0.0.36; extra == 'audio'
+Requires-Dist: numba>=0.59; extra == 'audio'
 Provides-Extra: cli
 Requires-Dist: argcomplete>=3; extra == 'cli'
 Requires-Dist: argh>=0.30; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: argh>=0.30; extra == 'dev'
+Requires-Dist: mixing[audio,beats]>=0.0.36; extra == 'dev'
+Requires-Dist: numba>=0.59; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
@@ -101,6 +107,9 @@ content (`OpenQuestion`), and human edits are protected from regeneration
 |---|---|
 | cut media into steps | `segment(media, steps=..., grid=...)` → `Segmentation` |
 | explicit/human boundaries | `segment(media, boundaries=[...], steps=[names])` |
+| use the video's own chapters | `segment(media, metadata=<yt-dlp info.json>)` |
+| measure the grid from the media | `segment(local_media, steps=[(name, counts), ...])` — no grid needed; tempo + structure measured, origin estimated and flagged (`pip install paces[audio]`) |
+| protect edits from regeneration | `apply_edits(doc, patches, by="user:you")` + `merge_regenerated(committed, fresh)` |
 | the committed artifact | `to_document(seg, ...)` → `StepDocument` |
 | a practice page | `render_html(doc)` |
 | wall-clock times from counts | `resolve(doc)` |

{paces-0.0.3 → paces-0.0.4}/README.md

@@ -75,6 +75,9 @@ content (`OpenQuestion`), and human edits are protected from regeneration
 |---|---|
 | cut media into steps | `segment(media, steps=..., grid=...)` → `Segmentation` |
 | explicit/human boundaries | `segment(media, boundaries=[...], steps=[names])` |
+| use the video's own chapters | `segment(media, metadata=<yt-dlp info.json>)` |
+| measure the grid from the media | `segment(local_media, steps=[(name, counts), ...])` — no grid needed; tempo + structure measured, origin estimated and flagged (`pip install paces[audio]`) |
+| protect edits from regeneration | `apply_edits(doc, patches, by="user:you")` + `merge_regenerated(committed, fresh)` |
 | the committed artifact | `to_document(seg, ...)` → `StepDocument` |
 | a practice page | `render_html(doc)` |
 | wall-clock times from counts | `resolve(doc)` |

{paces-0.0.3 → paces-0.0.4}/paces/__init__.py

@@ -49,6 +49,7 @@ from paces.model import (
     validate_document,
 )
 from paces.edits import apply_edits, merge_regenerated
+from paces.measure import GridMeasurement, measure_grid
 from paces.projection import to_document
 from paces.render import render_html
 from paces.segmenters import (
@@ -87,6 +88,8 @@ __all__ = [
     "Capability",
     "register",
     "capabilities",
+    "measure_grid",
+    "GridMeasurement",
     "to_document",
     # editing & regeneration
     "apply_edits",

paces-0.0.4/paces/measure.py

@@ -0,0 +1,322 @@
+"""Measure a :class:`~paces.model.MetricGrid` from the media itself.
+
+Roadmap issue #2: when no grid is supplied, the media can often supply its
+own — the fleet's ``mixing`` package owns the primitives (speech/music
+segmentation, beat tracking) and this module composes them, in the cost order
+the POC proved out (``docs/01-what-was-built.md §3.1``):
+
+1. **Macro-structure** — ``find_segments(strategy="speech_music")`` splits
+   talk from music; the longest music region is where a routine lives.
+2. **Tempo** — ``beat_grid`` on that region (librosa under the hood).
+3. **Origin** — the weak link, stated honestly: tempo alone cannot give the
+   phase. v1 anchors on the first detected beat of the music region, reports
+   LOW confidence, and flags the estimate for confirmation — per ADR-0003, a
+   default chosen automatically must be reported with its confidence and
+   overridable by one keyword (``grid=``).
+
+Honesty under failure (adversarial review, PR #13): media with no beat
+structure — silence, ambience, an empty file — yields a grid whose tempo is
+honestly ``None`` (never ``"0"``: :class:`~paces.model.MetricGrid` refuses
+non-positive tempi) plus a ``tempo-unmeasured`` flag, and the ``segment()``
+facade keeps its returns-a-Segmentation-always contract.
+
+The ``grid-measured`` capability wires this into :func:`~paces.segmenters.
+segment`: media + a step list with durations, no full grid → measure, then
+place exactly as ``grid-placed`` would. A *partial* ``grid=`` is honoured as
+"what the caller knows" — unit and subdivisions always, and a caller-supplied
+tempo or origin **wins over the measured value** (explicit beats inferred),
+with a ``tempo-disagreement`` flag when the media measurably disagrees — the
+POC's doc-said-100-video-says-129 lesson, surfaced as a diff instead of
+silently resolved either way.
+
+Everything heavy is imported lazily — ``import paces`` never pulls librosa —
+and the capability preflights ``mixing``/``librosa`` (the ``[audio]`` extra).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from fractions import Fraction
+from pathlib import Path
+from typing import Any
+
+from paces.model import MetricGrid, decimal_str, seconds_per_unit
+from paces.segmenters import (
+    Capability,
+    Segmentation,
+    _segment_grid_placed,
+    register,
+)
+
+DFLT_UNIT = "eight"
+DFLT_SUBDIVISIONS = 8
+DFLT_SAMPLE_RATE = 22050
+
+#: The origin estimate is the honest weak link: "first beat of the music
+#: region" is right when the routine starts on bar one, and wrong by an intro.
+DFLT_MEASURED_CONFIDENCE = 0.5
+#: A caller-supplied origin removes the weak link; the tempo half is reliable.
+KNOWN_ORIGIN_CONFIDENCE = 0.75
+#: Earned when the declared routine length fits inside the music region.
+FIT_BONUS = 0.2
+FIT_TOLERANCE = 1.15  # the routine may overrun the region by 15% before we flag
+UNMEASURED_CONFIDENCE = 0.2
+#: A caller tempo further than this (relative) from the measured one is flagged.
+TEMPO_DISAGREEMENT_RTOL = 0.02
+
+
+class MediaDecodeError(ValueError):
+    """The file exists but could not be read as audio."""
+
+
+def _dec(value: float, *, places: int = 2) -> str:
+    return decimal_str(value, places=places)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class GridMeasurement:
+    """A measured grid, how much to trust it, and the evidence why."""
+
+    grid: MetricGrid
+    confidence: float
+    flags: tuple[str, ...] = ()
+    evidence: Mapping[str, Any] = field(default_factory=dict)
+
+
+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.
+
+    mixing's ``beat_grid`` reports ``tempo_bpm = 0.0`` when librosa finds no
+    tempo; zero is 'unmeasured', never a value (a zero tempo is
+    unrepresentable in :class:`MetricGrid`, deliberately).
+    """
+    tempo = float(beat_grid_result.tempo_bpm)
+    if tempo <= 0 or not len(beat_grid_result.beat_times):
+        return None, None
+    return _dec(tempo, places=1), tempo
+
+
+def measure_grid(
+    media: str,
+    *,
+    unit: str = DFLT_UNIT,
+    subdivisions: int = DFLT_SUBDIVISIONS,
+    tempo_bpm: str | float | None = None,
+    origin: str | float | None = None,
+    total_units: float | None = None,
+    sample_rate: int = DFLT_SAMPLE_RATE,
+) -> GridMeasurement:
+    """Measure tempo, macro-structure and (estimated) origin from *media*.
+
+    *media* is a local audio (or audio-bearing) file. *tempo_bpm* and
+    *origin*, when given, are what the caller already knows: they WIN over
+    the measured values (a disagreement is flagged, never silently resolved).
+    *total_units* (the sum of a step list's durations) buys a sanity check: a
+    routine that cannot fit inside the detected music region is flagged.
+
+    Returns a :class:`GridMeasurement`; whatever could not be measured stays
+    honestly ``None`` on the grid, with a flag naming it.
+    """
+    try:
+        import librosa
+        from mixing.audio import beat_grid, find_segments
+    except ImportError as error:
+        raise ImportError(
+            "measure_grid needs the [audio] extra — pip install 'paces[audio]'"
+        ) from error
+
+    path = Path(media)
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"measure_grid needs a local media file; {media!r} is not one "
+            "(download first — e.g. with yb — or supply grid= yourself)"
+        )
+    # A caller-supplied string is already a valid wire decimal: pass it
+    # through untouched so the declared value round-trips verbatim; only
+    # numbers get formatted.
+    known_tempo = (
+        tempo_bpm
+        if isinstance(tempo_bpm, str)
+        else None
+        if tempo_bpm is None
+        else _dec(float(tempo_bpm), places=1)
+    )
+    known_origin = (
+        origin
+        if isinstance(origin, str)
+        else None
+        if origin is None
+        else _dec(float(origin))
+    )
+
+    try:
+        segments = find_segments(str(path), strategy="speech_music")
+    except Exception as error:
+        raise MediaDecodeError(
+            f"could not read {media!r} as audio ({type(error).__name__}) — "
+            "is it an audio/video file? Non-wav formats need ffmpeg installed."
+        ) from error
+    evidence: dict[str, Any] = {
+        "segments": [
+            [round(s.start, 2), round(s.end, 2), s.label or ""] for s in segments
+        ]
+    }
+    music = [s for s in segments if s.label == "music"]
+    flags: tuple[str, ...] = ()
+
+    if music:
+        region = max(music, key=lambda s: s.end - s.start)
+        try:
+            samples, rate = librosa.load(str(path), sr=sample_rate)
+        except Exception as error:
+            raise MediaDecodeError(
+                f"could not decode {media!r} as audio ({type(error).__name__})"
+            ) from error
+        region_samples = samples[int(region.start * rate) : int(region.end * rate)]
+        bg = beat_grid(region_samples, sample_rate=rate)
+        measured_tempo, tempo_value = _measured_tempo(bg)
+        evidence.update(
+            music_span=[round(region.start, 2), round(region.end, 2)],
+            beat_count=len(bg.beat_times),
+        )
+        if measured_tempo is not None:
+            evidence["tempo_bpm"] = tempo_value
+            measured_origin = _dec(region.start + float(bg.beat_times[0]))
+            tempo_unmeasured_note = None
+        else:
+            tempo_unmeasured_note = "no beat structure in the music region"
+            measured_origin = None
+    else:
+        region = None
+        bg = beat_grid(str(path), sample_rate=sample_rate)
+        measured_tempo, tempo_value = _measured_tempo(bg)
+        measured_origin = None
+        if measured_tempo is not None:
+            evidence["tempo_bpm"] = tempo_value
+            tempo_unmeasured_note = None
+        else:
+            tempo_unmeasured_note = "no beat structure found"
+        flags += ("no-music-region",)
+    if tempo_unmeasured_note is not None:
+        suffix = " — using your tempoBpm" if known_tempo is not None else ""
+        flags += (f"tempo-unmeasured: {tempo_unmeasured_note}{suffix}",)
+
+    # Explicit beats inferred — but a disagreement is a finding, not a secret.
+    final_tempo = known_tempo or measured_tempo
+    if (
+        known_tempo is not None
+        and measured_tempo is not None
+        and abs(float(known_tempo) - float(measured_tempo))
+        > float(measured_tempo) * TEMPO_DISAGREEMENT_RTOL
+    ):
+        flags += (
+            f"tempo-disagreement: you said {known_tempo} bpm, the media "
+            f"measures {measured_tempo} — using yours; drop tempoBpm from "
+            "grid= to use the measured value",
+        )
+    final_origin = known_origin or measured_origin
+    if known_origin is None and measured_origin is not None:
+        flags += (
+            f"origin-estimated: first beat of the music region "
+            f"({measured_origin} s) — override with grid= if the routine "
+            "starts later",
+        )
+
+    grid = MetricGrid(
+        unit=unit,
+        subdivisions=subdivisions,
+        tempo_bpm=final_tempo,
+        origin=final_origin,
+    )
+    if final_origin is None:
+        flags += ("origin-unknown: pass grid= with an origin, or boundaries=",)
+        confidence = UNMEASURED_CONFIDENCE
+    elif region is None:
+        # The grid is only complete because the caller supplied the origin,
+        # and any tempo here was measured from a no-music recording (speech
+        # rhythm) — a placement can proceed, but not with real confidence.
+        confidence = UNMEASURED_CONFIDENCE
+    else:
+        confidence = (
+            KNOWN_ORIGIN_CONFIDENCE if known_origin else DFLT_MEASURED_CONFIDENCE
+        )
+
+    spu = seconds_per_unit(grid)
+    if total_units and total_units > 0 and spu and final_origin and region:
+        routine_s = total_units * spu
+        region_s = region.end - float(Fraction(final_origin))
+        evidence.update(routine_s=round(routine_s, 2), region_s=round(region_s, 2))
+        if routine_s > region_s * FIT_TOLERANCE:
+            flags += (
+                f"duration-mismatch: {_dec(total_units)} × {unit} = "
+                f"{routine_s:.1f} s but the music region holds {region_s:.1f} s "
+                "— the step list or the tempo may be wrong",
+            )
+        else:
+            confidence += FIT_BONUS
+    return GridMeasurement(
+        grid=grid, confidence=min(confidence, 0.95), flags=flags, evidence=evidence
+    )
+
+
+def _segment_grid_measured(inputs: Mapping[str, Any]) -> Segmentation:
+    """Measure what the caller's partial ``grid=`` left unknown, then place
+    like ``grid-placed``.
+
+    With no grid at all the dance default is assumed — and flagged, because
+    an assumed unit is a guess, not a measurement. Whatever still cannot be
+    known (a beatless recording's origin) yields the honest partial result,
+    never an exception and never an invented placement.
+    """
+    partial: MetricGrid | None = inputs["grid"]
+    unit = partial.unit if partial is not None else DFLT_UNIT
+    subdivisions = partial.subdivisions if partial is not None else DFLT_SUBDIVISIONS
+    total_units = sum(row["duration"] for row in inputs["steps"])
+    measurement = measure_grid(
+        inputs["media"],
+        unit=unit,
+        subdivisions=subdivisions,
+        tempo_bpm=partial.tempo_bpm if partial is not None else None,
+        origin=partial.origin if partial is not None else None,
+        total_units=total_units,
+    )
+    flags = measurement.flags
+    if partial is None:
+        flags += (
+            f"assumed-unit: {DFLT_UNIT} ({DFLT_SUBDIVISIONS} beats) — pass "
+            "grid={'unit': ..., 'subdivisions': ...} to change",
+        )
+    grid = measurement.grid
+    if grid.tempo_bpm is None or grid.origin is None:
+        return Segmentation(grid=grid, confidence=measurement.confidence, flags=flags)
+    placed = _segment_grid_placed({**inputs, "grid": grid})
+    return Segmentation(
+        steps=placed.steps,
+        boundaries=placed.boundaries,
+        unit=placed.unit,
+        grid=grid,
+        confidence=min(placed.confidence, measurement.confidence),
+        flags=placed.flags + flags,
+    )
+
+
+GRID_MEASURED = register(
+    Capability(
+        name="grid-measured",
+        gives="segmentation",
+        summary=(
+            "Measure the metric grid from the media itself (speech/music "
+            "split + beat tracking, via mixing), then place the step list "
+            "on it. Origin is estimated and flagged for confirmation."
+        ),
+        target="paces.measure:_segment_grid_measured",
+        needs=frozenset({"media.local", "steps", "steps.durations"}),
+        requires=("mixing", "librosa"),
+        # Explicit information outranks inference: a full grid (1.2) and
+        # author chapters (0.75) both beat a measured guess.
+        base=0.7,
+        s_per_min=2.0,
+        resolution_s=0.5,
+    )
+)

{paces-0.0.3 → paces-0.0.4}/paces/model.py

@@ -27,7 +27,7 @@ from __future__ import annotations
 from fractions import Fraction
 from typing import Annotated, Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 from pydantic.alias_generators import to_camel
 
 SCHEMA_VERSION = "0.1.0"
@@ -63,14 +63,28 @@ class MetricGrid(_Base):
 
     Optional by design: a "reps" domain has no grid; a dance routine does —
     and the grid is what drives the metronome and :func:`resolve`.
+
+    A non-positive tempo or subdivision count is unrepresentable, not merely
+    discouraged: a zero tempo makes every duration infinite and every
+    ``seconds_per_unit`` division a crash, so "tempo unknown" is spelled
+    ``tempo_bpm=None``, never ``"0"``.
     """
 
     unit: Slug  # "eight"
-    subdivisions: int = 1  # beats per unit (8 for an 8-count)
+    subdivisions: int = Field(default=1, ge=1)  # beats per unit (8 for an 8-count)
     tempo_bpm: Decimal | None = None  # "129.2"
     origin: Decimal | None = None  # seconds into origin_source where unit 0 starts
     origin_source: Slug | None = None
 
+    @field_validator("tempo_bpm")
+    @classmethod
+    def _tempo_must_be_positive(cls, value: str | None) -> str | None:
+        if value is not None and Fraction(value) <= 0:
+            raise ValueError(
+                "tempo_bpm must be positive; spell 'tempo unknown' as None"
+            )
+        return value
+
 
 # ── sources & spans ─────────────────────────────────────────────────────────
 
@@ -235,6 +249,19 @@ class StepDocument(_Base):
     attrs: dict[str, Any] = Field(default_factory=dict)
 
 
+def decimal_str(value: float, *, places: int = 3) -> str:
+    """A clean wire decimal from a number ('95.78', never '95.78000000001').
+
+    The one shared serialisation helper for computed values entering the
+    document's no-floats wire format.
+
+    >>> decimal_str(72.60000000000001, places=3)
+    '72.6'
+    """
+    text = f"{float(value):.{places}f}".rstrip("0").rstrip(".")
+    return text or "0"
+
+
 # ── serialisation (the git rules of docs/07 §6.5) ───────────────────────────
 
 

{paces-0.0.3 → paces-0.0.4}/paces/projection.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 
 from paces.model import (
+    decimal_str,
     Measure,
     Origin,
     Source,
@@ -28,9 +29,7 @@ DECIMAL_PLACES = 3
 
 
 def _dec(value: float, *, places: int = DECIMAL_PLACES) -> str:
-    """A clean decimal string from a float ('95.78', never '95.78000000001')."""
-    text = f"{value:.{places}f}".rstrip("0").rstrip(".")
-    return text or "0"
+    return decimal_str(value, places=places)
 
 
 def _as_source(source, *, default_id: str = "source") -> Source:

{paces-0.0.3 → paces-0.0.4}/paces/segmenters.py

@@ -34,6 +34,7 @@ import math
 import time
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import Any, Callable
 
 from paces.model import MetricGrid, seconds_per_unit
@@ -271,6 +272,11 @@ def _facts(
     facts = set()
     if media:
         facts.add("media")
+        try:
+            if Path(media).is_file():  # a directory is not measurable media
+                facts.add("media.local")  # intrinsic measurement needs bytes
+        except OSError:
+            pass
     if steps:
         facts.add("steps")
         if all(row["duration"] is not None for row in steps):

{paces-0.0.3 → paces-0.0.4}/paces/tools.py

@@ -250,6 +250,42 @@ def merge(committed, fresh, *, output: str | None = None) -> dict:
     return json.loads(text)
 
 
+def measure_grid(
+    media: str,
+    *,
+    unit: str = "eight",
+    subdivisions: int = 8,
+    total_units: float | None = None,
+    output: str | None = None,
+) -> dict:
+    """Measure a metric grid (tempo, macro-structure, estimated origin) from
+    a local media file. Needs the [audio] extra.
+
+    Returns ``{"grid", "confidence", "flags", "evidence"}`` — origin is an
+    estimate (first beat of the music region) and the flags say so; override
+    with an explicit ``grid=`` on ``segment`` when it is wrong.
+    """
+    from paces.measure import measure_grid as _measure_grid
+
+    measurement = _measure_grid(
+        media, unit=unit, subdivisions=subdivisions, total_units=total_units
+    )
+    payload = {
+        "grid": measurement.grid.model_dump(
+            mode="json", by_alias=True, exclude_none=True
+        ),
+        "confidence": measurement.confidence,
+        "flags": list(measurement.flags),
+        "evidence": dict(measurement.evidence),
+    }
+    if output:
+        Path(output).write_text(
+            json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+    return payload
+
+
 def list_segmenters() -> dict:
     """The registered segmentation capabilities: name → what it needs/gives."""
     return {
@@ -272,5 +308,6 @@ _dispatch_funcs = [
     merge,
     resolve,
     validate,
+    measure_grid,
     list_segmenters,
 ]

{paces-0.0.3 → paces-0.0.4}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paces"
-version = "0.0.3"
+version = "0.0.4"
 description = "Turn instructional media into structured, interactive learning material"
 readme = "README.md"
 license = "MIT"
@@ -37,6 +37,20 @@ paces = "paces.__main__:main"
 
 [project.optional-dependencies]
 cli = ["argh>=0.30", "argcomplete>=3"]
+audio = [
+    # Grid measurement (issue #2): the fleet's `mixing` owns speech/music
+    # segmentation and beat tracking; [beats] pulls librosa, [audio] pulls
+    # soundfile. Floor 0.0.36: `beat_grid` and `find_segments(strategy=
+    # "speech_music")` ship there.
+    "mixing[beats,audio]>=0.0.36",
+    # librosa resolves numba transitively; without an explicit floor uv can
+    # backtrack to unbuildable numba 0.53/llvmlite 0.36 when the newest
+    # numpy outruns numba's caps.
+    "numba>=0.59",
+    # pydub (via mixing[audio]) imports the stdlib `audioop`, removed in
+    # Python 3.13; the official backport keeps 3.13+ installs working.
+    "audioop-lts; python_version>='3.13'",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
@@ -44,6 +58,10 @@ dev = [
     # The CLI smoke test runs `python -m paces ...`; without argh in dev it
     # would fail rather than silently skip — keep it mirrored with [cli].
     "argh>=0.30",
+    # The grid-measurement tests exercise the real mixing/librosa path on
+    # synthesized audio; mirrored with [audio] so they run rather than skip.
+    "mixing[beats,audio]>=0.0.36",
+    "numba>=0.59",
 ]
 docs = [
     "sphinx>=6.0",

paces-0.0.4/tests/audio_synth.py

@@ -0,0 +1,74 @@
+"""Synthesize practice-video-shaped audio for the grid-measurement tests.
+
+The shape mirrors the POC's macro-structure (docs/01 §3.1): the teacher talks
+(amplitude-modulated noise at a syllabic ~4 Hz), a beat of silence, then the
+run-through — music with a sub-bass kick on a known tempo. Everything is
+deterministic (seeded) and synthesized at test time: no media files in the
+repo, no network, no cost.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+SAMPLE_RATE = 22050
+
+
+def practice_audio(
+    *,
+    bpm: float = 129.2,
+    speech_s: float = 8.0,
+    silence_s: float = 1.5,
+    music_s: float = 30.0,
+    sample_rate: int = SAMPLE_RATE,
+    seed: int = 0,
+) -> tuple[np.ndarray, dict]:
+    """Speech, a pause, then kick-driven music at *bpm*.
+
+    Returns ``(samples, truth)`` where ``truth`` carries the ground truth the
+    tests assert against (music start/end, bpm).
+    """
+    rng = np.random.default_rng(seed)
+
+    t_speech = np.arange(int(speech_s * sample_rate)) / sample_rate
+    speech = (
+        rng.normal(0, 0.15, t_speech.size)
+        * (0.55 + 0.45 * np.sin(2 * np.pi * 3.8 * t_speech)) ** 2
+    )
+    speech *= np.sin(2 * np.pi * 0.4 * t_speech) > -0.6  # breathing pauses
+
+    silence = np.zeros(int(silence_s * sample_rate))
+
+    beat_period = 60 / bpm
+    t_music = np.arange(int(music_s * sample_rate)) / sample_rate
+    music = 0.05 * rng.normal(0, 1, t_music.size)  # hiss bed
+    music += 0.15 * np.sin(2 * np.pi * 110 * t_music)  # sustained tone
+    for k in range(int(music_s / beat_period)):
+        start = int(k * beat_period * sample_rate)
+        end = min(start + int(0.09 * sample_rate), t_music.size)
+        n = end - start
+        envelope = np.exp(-np.arange(n) / (0.02 * sample_rate))
+        music[start:end] += (
+            0.9 * np.sin(2 * np.pi * 55 * np.arange(n) / sample_rate) * envelope
+        )
+
+    samples = np.concatenate([speech, silence, music]).astype(np.float32)
+    truth = {
+        "bpm": bpm,
+        "music_start_s": speech_s + silence_s,
+        "music_end_s": speech_s + silence_s + music_s,
+        "sample_rate": sample_rate,
+    }
+    return samples, truth
+
+
+def speech_only_audio(
+    *, duration_s: float = 12.0, sample_rate: int = SAMPLE_RATE, seed: int = 1
+) -> np.ndarray:
+    """Talk with no music anywhere — the origin-unknown case."""
+    t = np.arange(int(duration_s * sample_rate)) / sample_rate
+    rng = np.random.default_rng(seed)
+    speech = (
+        rng.normal(0, 0.15, t.size) * (0.55 + 0.45 * np.sin(2 * np.pi * 4.1 * t)) ** 2
+    )
+    return (speech * (np.sin(2 * np.pi * 0.3 * t) > -0.7)).astype(np.float32)

paces-0.0.4/tests/test_measure.py

@@ -0,0 +1,259 @@
+"""Grid measurement (issue #2): tempo + macro-structure measured, origin
+estimated and flagged — on synthesized audio with known ground truth.
+
+These tests exercise the REAL mixing/librosa path (no mocks); the audio is
+deterministic, generated at test time, and never leaves tmp_path. They fail —
+not skip — when the [audio]/dev deps are missing: a silently skipped suite
+proves nothing.
+"""
+
+from __future__ import annotations
+
+import pytest
+import soundfile as sf
+
+from audio_synth import SAMPLE_RATE, practice_audio, speech_only_audio
+from paces.measure import measure_grid
+from paces.segmenters import segment
+
+BPM = 129.2
+MUSIC_START = 9.5  # 8 s speech + 1.5 s silence
+
+
+@pytest.fixture(scope="module")
+def practice_wav(tmp_path_factory) -> str:
+    samples, _ = practice_audio(bpm=BPM)
+    path = tmp_path_factory.mktemp("audio") / "practice.wav"
+    sf.write(str(path), samples, SAMPLE_RATE)
+    return str(path)
+
+
+@pytest.fixture(scope="module")
+def speech_wav(tmp_path_factory) -> str:
+    path = tmp_path_factory.mktemp("audio") / "speech.wav"
+    sf.write(str(path), speech_only_audio(), SAMPLE_RATE)
+    return str(path)
+
+
+def test_measure_finds_tempo_structure_and_estimated_origin(practice_wav):
+    measurement = measure_grid(practice_wav)
+    grid = measurement.grid
+    assert grid.unit == "eight" and grid.subdivisions == 8
+    assert float(grid.tempo_bpm) == pytest.approx(BPM, abs=0.5)
+    # origin: first beat of the music region — near, at or after music start
+    assert float(grid.origin) == pytest.approx(MUSIC_START, abs=1.0)
+    start, end = measurement.evidence["music_span"]
+    assert start == pytest.approx(MUSIC_START, abs=0.5)
+    assert any(flag.startswith("origin-estimated") for flag in measurement.flags)
+    assert 0 < measurement.confidence < 0.9  # an estimate, never certainty
+
+
+def test_fitting_routine_length_raises_confidence(practice_wav):
+    # 7 eights ≈ 26 s fits the ~30 s music region; 40 eights ≈ 148 s cannot
+    fits = measure_grid(practice_wav, total_units=7)
+    overruns = measure_grid(practice_wav, total_units=40)
+    assert fits.confidence > overruns.confidence
+    assert not any("duration-mismatch" in flag for flag in fits.flags)
+    assert any("duration-mismatch" in flag for flag in overruns.flags)
+
+
+def test_speech_only_media_is_honest_about_the_origin(speech_wav):
+    measurement = measure_grid(speech_wav)
+    assert measurement.grid.origin is None
+    assert "no-music-region" in measurement.flags
+    assert measurement.confidence <= 0.2
+
+
+def test_missing_file_names_the_fix():
+    with pytest.raises(FileNotFoundError, match="grid="):
+        measure_grid("nope-not-here.wav")
+
+
+# ── the grid-measured capability, end to end ────────────────────────────────
+
+
+def test_segment_measures_when_no_grid_is_given(practice_wav):
+    seg = segment(practice_wav, steps=[("intro", 2), ("chorus", 2), ("outro", 3)])
+    assert seg.method == "grid-measured"
+    assert seg.unit == "eight"
+    assert seg.grid is not None
+    assert float(seg.grid.tempo_bpm) == pytest.approx(BPM, abs=0.5)
+    # placement happened on the measured grid
+    assert len(seg.steps) == 3
+    assert seg.steps[0].spans[0][0] == pytest.approx(float(seg.grid.origin))
+    spu = 8 * 60 / float(seg.grid.tempo_bpm)
+    assert seg.steps[1].spans[0][0] == pytest.approx(
+        float(seg.grid.origin) + 2 * spu, abs=0.05
+    )
+    # honesty: the estimate and the assumed unit are both flagged
+    assert any(flag.startswith("origin-estimated") for flag in seg.flags)
+    assert any(flag.startswith("assumed-unit") for flag in seg.flags)
+    assert seg.confidence <= 0.7
+
+
+def test_partial_grid_supplies_the_unit_and_suppresses_the_assumption(practice_wav):
+    seg = segment(
+        practice_wav,
+        steps=[("a", 4), ("b", 4)],
+        grid={"unit": "bar", "subdivisions": 4},
+    )
+    assert seg.method == "grid-measured"
+    assert seg.unit == "bar" and seg.grid.subdivisions == 4
+    assert not any(flag.startswith("assumed-unit") for flag in seg.flags)
+
+
+def test_explicit_grid_still_outranks_measurement(practice_wav):
+    seg = segment(
+        practice_wav,
+        steps=[("a", 4), ("b", 4)],
+        grid={"unit": "eight", "subdivisions": 8, "tempoBpm": "120", "origin": "3"},
+    )
+    assert seg.method == "grid-placed"
+
+
+def test_remote_media_cannot_select_measurement():
+    seg = segment("https://example.com/video.mp4", steps=[("a", 2), ("b", 2)])
+    assert "no-signal" in seg.flags  # media.local is the gate
+
+
+def test_speech_only_segmentation_reports_what_it_still_needs(speech_wav):
+    seg = segment(speech_wav, steps=[("a", 2), ("b", 2)])
+    assert seg.method == "grid-measured"
+    assert seg.steps == ()  # no invented placement
+    assert seg.grid is not None and seg.grid.origin is None
+    assert "no-music-region" in seg.flags
+    assert any("origin-unknown" in flag for flag in seg.flags)
+
+
+def test_measure_grid_tool_is_json_ready(practice_wav):
+    import json
+
+    from paces.tools import measure_grid as measure_tool
+
+    payload = measure_tool(practice_wav, total_units=7)
+    json.dumps(payload)
+    assert payload["grid"]["tempoBpm"]
+    assert payload["evidence"]["music_span"]
+
+
+# ── adversarial-review regressions (PR #13) ────────────────────────────────
+
+
+@pytest.fixture(scope="module")
+def silence_wav(tmp_path_factory) -> str:
+    import numpy as np
+
+    path = tmp_path_factory.mktemp("audio") / "silence.wav"
+    sf.write(str(path), np.zeros(int(10 * SAMPLE_RATE), dtype="float32"), SAMPLE_RATE)
+    return str(path)
+
+
+def test_silence_never_crashes_and_never_claims_a_tempo(silence_wav):
+    """F1: beatless media used to reach ZeroDivisionError via tempo '0'."""
+    measurement = measure_grid(silence_wav)
+    assert measurement.grid.tempo_bpm is None  # never '0'
+    assert any("tempo-unmeasured" in flag for flag in measurement.flags)
+    seg = segment(silence_wav, steps=[("a", 2), ("b", 2)])  # the facade contract
+    assert seg.method == "grid-measured"
+    assert seg.steps == ()  # no invented placement
+    assert seg.confidence <= 0.2
+
+
+def test_tiny_and_empty_files_return_honest_results(tmp_path):
+    import numpy as np
+
+    tiny = tmp_path / "tiny.wav"
+    sf.write(str(tiny), np.zeros(int(0.05 * SAMPLE_RATE), dtype="float32"), SAMPLE_RATE)
+    seg = segment(str(tiny), steps=[("a", 2)])
+    assert seg.steps == () and seg.confidence <= 0.2
+
+    empty = tmp_path / "empty.wav"
+    sf.write(str(empty), np.zeros(0, dtype="float32"), SAMPLE_RATE)
+    seg = segment(str(empty), steps=[("a", 2)])  # must not raise
+    assert seg.steps == ()
+
+
+def test_metric_grid_refuses_zero_tempo_and_zero_subdivisions():
+    from paces.model import MetricGrid
+
+    with pytest.raises(Exception, match="positive"):
+        MetricGrid(unit="eight", tempo_bpm="0")
+    with pytest.raises(Exception, match="positive"):
+        MetricGrid(unit="eight", tempo_bpm="-5")
+    with pytest.raises(Exception):
+        MetricGrid(unit="eight", subdivisions=0)
+
+
+def test_partial_grid_tempo_wins_and_disagreement_is_flagged(practice_wav):
+    """F2: the caller's tempo is used, and the media's disagreement named."""
+    seg = segment(
+        practice_wav,
+        steps=[("a", 2), ("b", 2)],
+        grid={"unit": "eight", "subdivisions": 8, "tempoBpm": "200"},
+    )
+    assert seg.method == "grid-measured"
+    assert seg.grid.tempo_bpm == "200"
+    assert any(flag.startswith("tempo-disagreement") for flag in seg.flags)
+
+
+def test_partial_grid_origin_wins_and_is_not_estimated(practice_wav):
+    seg = segment(
+        practice_wav,
+        steps=[("a", 2), ("b", 2)],
+        grid={"unit": "eight", "subdivisions": 8, "origin": "12.5"},
+    )
+    assert seg.method == "grid-measured"
+    assert seg.grid.origin == "12.5"
+    assert not any(flag.startswith("origin-estimated") for flag in seg.flags)
+    assert seg.steps[0].spans[0][0] == pytest.approx(12.5)
+    assert seg.confidence >= 0.7  # the weak link was supplied, not guessed
+
+
+def test_directory_media_is_not_measurable(tmp_path):
+    """F3: a directory passes exists() but is not media."""
+    seg = segment(str(tmp_path), steps=[("a", 2), ("b", 2)])
+    assert "no-signal" in seg.flags
+    with pytest.raises(FileNotFoundError, match="not one"):
+        measure_grid(str(tmp_path))
+
+
+def test_non_audio_file_gets_an_informative_error(tmp_path):
+    from paces.measure import MediaDecodeError
+
+    junk = tmp_path / "not-audio.json"
+    junk.write_text('{"hello": "world"}', encoding="utf-8")
+    with pytest.raises(MediaDecodeError, match="as audio"):
+        measure_grid(str(junk))
+
+
+def test_zero_total_units_earns_no_fit_bonus(practice_wav):
+    from paces.measure import DFLT_MEASURED_CONFIDENCE
+
+    measurement = measure_grid(practice_wav, total_units=0)
+    assert measurement.confidence == DFLT_MEASURED_CONFIDENCE
+    assert "routine_s" not in measurement.evidence
+
+
+def test_known_values_round_trip_verbatim(practice_wav):
+    """Round 2 F1: an explicitly supplied string is never reformatted."""
+    measurement = measure_grid(practice_wav, tempo_bpm="129.25", origin="12.345")
+    assert measurement.grid.tempo_bpm == "129.25"
+    assert measurement.grid.origin == "12.345"
+
+
+def test_known_origin_on_no_music_media_stays_low_confidence(speech_wav):
+    """Round 2 F2: a speech-rhythm tempo must not earn origin-level trust."""
+    measurement = measure_grid(speech_wav, origin="3.0")
+    assert measurement.grid.origin == "3.0"
+    assert measurement.confidence <= 0.2
+    if measurement.grid.tempo_bpm is not None:
+        assert "no-music-region" in measurement.flags
+
+
+def test_tempo_unmeasured_wording_acknowledges_a_caller_tempo(silence_wav):
+    measurement = measure_grid(silence_wav, tempo_bpm="120")
+    assert measurement.grid.tempo_bpm == "120"
+    assert any(
+        "tempo-unmeasured" in flag and "using your tempoBpm" in flag
+        for flag in measurement.flags
+    )