splitsmith 0.2.0__py3-none-any.whl

splitsmith/compare/filler.py

@@ -0,0 +1,98 @@
+"""Black filler video for empty grid tiles in compare exports."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+Runner = Callable[..., subprocess.CompletedProcess]
+
+
+class FillerRenderError(RuntimeError):
+    """ffmpeg refused to render the black filler clip."""
+
+
+def filler_filename(
+    *, width: int, height: int, frame_rate_num: int, frame_rate_den: int, duration_seconds: float
+) -> str:
+    """Deterministic filename so two stages with matching geometry reuse the same file.
+
+    Encodes ``(W, H, fps_num, fps_den, duration_ms)``; duration is rounded
+    to milliseconds because the same compound clip should resolve to the
+    same filler file across runs even when the source duration differs by
+    sub-millisecond rounding.
+    """
+    duration_ms = int(round(duration_seconds * 1000))
+    return f"_compare_filler_{width}x{height}_{frame_rate_num}-{frame_rate_den}" f"_{duration_ms}ms.mp4"
+
+
+def ensure_filler(
+    *,
+    width: int,
+    height: int,
+    frame_rate_num: int,
+    frame_rate_den: int,
+    duration_seconds: float,
+    output_dir: Path,
+    ffmpeg_binary: str = "ffmpeg",
+    runner: Runner = subprocess.run,
+) -> Path:
+    """Render (or reuse) a silent black filler video.
+
+    Idempotent: the filename encodes geometry + duration, so a second call
+    with matching arguments returns the existing file without re-running
+    ffmpeg. ``output_dir`` is created if needed.
+
+    The clip has no audio (``-an``) so the emitter doesn't need to mute it
+    explicitly. ``libx264 -pix_fmt yuv420p`` is used for cross-platform
+    reproducibility -- this stays predictable in CI / Linux even though
+    the rest of the pipeline can use VideoToolbox locally.
+    """
+    if width <= 0 or height <= 0:
+        raise ValueError(f"width/height must be positive, got {width}x{height}")
+    if frame_rate_num <= 0 or frame_rate_den <= 0:
+        raise ValueError(f"frame rate must be positive, got {frame_rate_num}/{frame_rate_den}")
+    if duration_seconds <= 0.0:
+        raise ValueError(f"duration_seconds must be positive, got {duration_seconds}")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    target = output_dir / filler_filename(
+        width=width,
+        height=height,
+        frame_rate_num=frame_rate_num,
+        frame_rate_den=frame_rate_den,
+        duration_seconds=duration_seconds,
+    )
+    if target.exists():
+        return target
+
+    fps = frame_rate_num / frame_rate_den
+    cmd = [
+        ffmpeg_binary,
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-y",
+        "-f",
+        "lavfi",
+        "-i",
+        f"color=c=black:s={width}x{height}:r={fps:.6f}",
+        "-t",
+        f"{duration_seconds:.3f}",
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-an",
+        str(target),
+    ]
+    try:
+        runner(cmd, check=True, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise FillerRenderError(f"ffmpeg binary not found: {ffmpeg_binary}") from exc
+    except subprocess.CalledProcessError as exc:
+        raise FillerRenderError(
+            f"ffmpeg failed rendering filler ({exc.returncode}): " f"{exc.stderr or exc.stdout!r}"
+        ) from exc
+    return target

splitsmith/compare/layout.py

@@ -0,0 +1,164 @@
+"""Grid-tile placement math for compare exports.
+
+Pure functions: no I/O, no FCPXML. Slot positions are returned in
+sequence-frame pixels (centre-of-tile, sequence-centre origin, +Y up);
+the FCPXML emitter converts them to FCP's normalised units using the
+same ``unit_per_px = 100.0 / sequence_height`` rule
+:func:`splitsmith.fcpxml_gen._pip_transform_attrs` uses.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+GridKind = Literal["1up", "2up-h", "2up-v", "2x2", "3x3", "4x4"]
+Layout2Up = Literal["horizontal", "vertical"]
+
+# (rows, cols) per grid kind. ``2up-h`` is one row of two; ``2up-v`` is
+# two stacked rows. Bigger grids are square.
+_GRID_SHAPE: dict[GridKind, tuple[int, int]] = {
+    "1up": (1, 1),
+    "2up-h": (1, 2),
+    "2up-v": (2, 1),
+    "2x2": (2, 2),
+    "3x3": (3, 3),
+    "4x4": (4, 4),
+}
+
+
+@dataclass(frozen=True)
+class GridSlot:
+    """One tile's transform inside the sequence frame."""
+
+    scale: float
+    """Uniform letterbox factor vs. native cam size (``1.0`` == native)."""
+
+    position_px: tuple[float, float]
+    """Centre-of-tile pixel offset from the sequence centre, +Y up."""
+
+
+@dataclass(frozen=True)
+class GridLayout:
+    """A resolved grid for one stage of one compare export."""
+
+    kind: GridKind
+    slots_per_label: dict[str, GridSlot]
+    """Slot keyed by label, in alphabetical order. Only labels actually
+    present in this stage appear; missing-tile labels are absent."""
+
+    empty_slots: list[GridSlot]
+    """Filler-tile slots for cells the chosen grid leaves empty."""
+
+
+def choose_grid(roster_count: int, *, layout_2up: Layout2Up = "horizontal") -> GridKind:
+    """Smallest grid whose capacity is ``>= roster_count``.
+
+    Sized for the *full* manifest roster, not the per-stage present
+    subset, so slot indices stay stable across stages of one export
+    (a label always lands in the same tile; missing tiles become
+    filler). 1 -> ``1up``; 2 -> ``2up-h`` or ``2up-v`` per
+    ``layout_2up``; 3..4 -> ``2x2``; 5..9 -> ``3x3``; 10..16 ->
+    ``4x4``. Counts of 0 or above 16 raise :class:`ValueError`.
+    """
+    if roster_count <= 0:
+        raise ValueError(f"roster_count must be >= 1, got {roster_count}")
+    if roster_count == 1:
+        return "1up"
+    if roster_count == 2:
+        return "2up-h" if layout_2up == "horizontal" else "2up-v"
+    if roster_count <= 4:
+        return "2x2"
+    if roster_count <= 9:
+        return "3x3"
+    if roster_count <= 16:
+        return "4x4"
+    raise ValueError(f"roster_count={roster_count} exceeds the largest supported grid (16)")
+
+
+def _slot_for_index(
+    *,
+    index: int,
+    rows: int,
+    cols: int,
+    sequence_width: int,
+    sequence_height: int,
+    cam_width: int,
+    cam_height: int,
+) -> GridSlot:
+    """Compute the transform for tile ``index`` (0-based, row-major)."""
+    row = index // cols
+    col = index % cols
+    cell_w = sequence_width / cols
+    cell_h = sequence_height / rows
+    scale = min(cell_w / cam_width, cell_h / cam_height)
+    # Centre of cell (col, row) in the same +Y-up convention the emitter
+    # uses (row 0 sits at the top of the frame, so y is positive).
+    centre_x = (col + 0.5) * cell_w - sequence_width / 2.0
+    centre_y = sequence_height / 2.0 - (row + 0.5) * cell_h
+    return GridSlot(scale=scale, position_px=(centre_x, centre_y))
+
+
+def compute_layout(
+    *,
+    sorted_labels: list[str],
+    present_labels: set[str],
+    sequence_width: int,
+    sequence_height: int,
+    cam_width: int,
+    cam_height: int,
+    layout_2up: Layout2Up = "horizontal",
+) -> GridLayout:
+    """Resolve per-tile transforms for one stage.
+
+    ``sorted_labels`` is the alphabetically-sorted list of every label
+    in the manifest (the full roster -- ``len(sorted_labels)`` drives
+    the chosen grid kind). Slot indices follow that order so a label
+    always lands in the same tile across every stage of the export,
+    regardless of who's missing. Missing labels leave their cell empty
+    for the filler; remaining unused cells in the chosen grid (when
+    the roster doesn't fill it perfectly) also go into ``empty_slots``.
+    """
+    if not sorted_labels:
+        raise ValueError("sorted_labels must not be empty")
+    if not present_labels:
+        raise ValueError("present_labels must not be empty")
+    unknown = present_labels - set(sorted_labels)
+    if unknown:
+        raise ValueError(f"present_labels has unknown labels: {sorted(unknown)}")
+
+    kind = choose_grid(len(sorted_labels), layout_2up=layout_2up)
+    rows, cols = _GRID_SHAPE[kind]
+    capacity = rows * cols
+
+    # Slot index = position in sorted_labels. Stable across stages even
+    # when a different shooter is missing each stage.
+    slots_per_label: dict[str, GridSlot] = {}
+    used_indices: set[int] = set()
+    for index, label in enumerate(sorted_labels):
+        if label in present_labels:
+            slots_per_label[label] = _slot_for_index(
+                index=index,
+                rows=rows,
+                cols=cols,
+                sequence_width=sequence_width,
+                sequence_height=sequence_height,
+                cam_width=cam_width,
+                cam_height=cam_height,
+            )
+            used_indices.add(index)
+
+    empty_slots = [
+        _slot_for_index(
+            index=i,
+            rows=rows,
+            cols=cols,
+            sequence_width=sequence_width,
+            sequence_height=sequence_height,
+            cam_width=cam_width,
+            cam_height=cam_height,
+        )
+        for i in range(capacity)
+        if i not in used_indices
+    ]
+    return GridLayout(kind=kind, slots_per_label=slots_per_label, empty_slots=empty_slots)

splitsmith/compare/manifest.py

@@ -0,0 +1,91 @@
+"""Pydantic schema + YAML loader for compare-export manifests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class CompareShooter(BaseModel):
+    """One shooter contributing tiles to the comparison."""
+
+    project: Path
+    label: str = Field(min_length=1)
+
+    @field_validator("project", mode="before")
+    @classmethod
+    def _expand(cls, value: object) -> object:
+        if isinstance(value, str):
+            return Path(value).expanduser()
+        if isinstance(value, Path):
+            return value.expanduser()
+        return value
+
+
+class CompareManifest(BaseModel):
+    """A compare-export manifest loaded from YAML.
+
+    Path resolution: ``output`` and shooter ``project`` paths in the
+    YAML are taken verbatim. ``~`` is expanded; relative paths are NOT
+    rewritten here -- :func:`load_manifest` does the manifest-dir
+    resolution because it's the only caller that knows where the
+    manifest lives on disk.
+    """
+
+    output: Path
+    audio_from: str = Field(min_length=1)
+    layout_2up: Literal["horizontal", "vertical"] = "horizontal"
+    shooters: list[CompareShooter] = Field(min_length=1)
+
+    @field_validator("output", mode="before")
+    @classmethod
+    def _expand_output(cls, value: object) -> object:
+        if isinstance(value, str):
+            return Path(value).expanduser()
+        if isinstance(value, Path):
+            return value.expanduser()
+        return value
+
+    @model_validator(mode="after")
+    def _labels_unique(self) -> CompareManifest:
+        labels = [s.label for s in self.shooters]
+        if len(set(labels)) != len(labels):
+            dupes = sorted({lab for lab in labels if labels.count(lab) > 1})
+            raise ValueError(f"duplicate shooter labels: {dupes}")
+        return self
+
+    @model_validator(mode="after")
+    def _audio_from_matches(self) -> CompareManifest:
+        labels = {s.label for s in self.shooters}
+        if self.audio_from not in labels:
+            raise ValueError(
+                f"audio_from={self.audio_from!r} does not match any shooter label " f"({sorted(labels)})"
+            )
+        return self
+
+
+def load_manifest(path: Path) -> CompareManifest:
+    """Read ``path`` and return a validated :class:`CompareManifest`.
+
+    Resolves the manifest's ``output`` path against the manifest's
+    parent directory when it's relative, and rewrites each shooter's
+    ``project`` path against the same base when relative -- so a
+    manifest is portable as long as the YAML and the project roots
+    move together.
+    """
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"manifest {path} must be a YAML mapping at the top level")
+    manifest = CompareManifest.model_validate(raw)
+    base = path.parent
+    if not manifest.output.is_absolute():
+        manifest = manifest.model_copy(update={"output": (base / manifest.output).resolve()})
+
+    def _resolve(p: Path) -> Path:
+        return p if p.is_absolute() else (base / p).resolve()
+
+    resolved_shooters = [s.model_copy(update={"project": _resolve(s.project)}) for s in manifest.shooters]
+    return manifest.model_copy(update={"shooters": resolved_shooters})

splitsmith/compare/project_loader.py

@@ -0,0 +1,195 @@
+"""Load per-stage trim metadata from a shooter -- legacy project or merged Match."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .. import fcpxml_gen
+from ..fcpxml_gen import VideoMetadata
+from ..match_model import Match, Shooter
+from ..ui.match_exports import _slugify
+from ..ui.project import MatchProject
+
+ProbeFn = Callable[[Path], VideoMetadata]
+
+
+@dataclass(frozen=True)
+class CompareStageBundle:
+    """All the per-stage facts the emitter needs from one shooter."""
+
+    stage_number: int
+    stage_name: str
+    trim_path: Path
+    audit_path: Path
+    beep_offset_in_clip: float
+    duration_seconds: float
+    width: int
+    height: int
+    frame_rate_num: int
+    frame_rate_den: int
+
+    @property
+    def metadata(self) -> VideoMetadata:
+        return VideoMetadata(
+            width=self.width,
+            height=self.height,
+            duration_seconds=self.duration_seconds,
+            frame_rate_num=self.frame_rate_num,
+            frame_rate_den=self.frame_rate_den,
+        )
+
+
+@dataclass(frozen=True)
+class CompareShooterBundle:
+    """A shooter's project + the per-stage bundles ready for export.
+
+    ``project`` is the legacy :class:`MatchProject` when this bundle came
+    from a single-shooter project; ``None`` when it came from a shooter
+    inside a merged :class:`splitsmith.match_model.Match`. The emitter
+    only reads ``label`` and ``stages_by_number``, so the optional field
+    is informational for callers that want to inspect it.
+    """
+
+    label: str
+    project_root: Path
+    project: MatchProject | None = None
+    stages_by_number: dict[int, CompareStageBundle] = field(default_factory=dict)
+
+
+def trim_path_for_stage(
+    project: MatchProject, project_root: Path, stage_number: int, stage_name: str
+) -> Path:
+    """Return the lossless-trim path the per-stage exporter would write.
+
+    Mirrors :func:`splitsmith.ui.exports.export_audit_clip`'s naming:
+    ``<exports>/stage<N>_<slug>_trimmed.mp4``.
+    """
+    base = f"stage{stage_number}_{_slugify(stage_name)}"
+    return project.exports_path(project_root) / f"{base}_trimmed.mp4"
+
+
+def audit_path_for_stage(project: MatchProject, project_root: Path, stage_number: int) -> Path:
+    return project.audit_path(project_root) / f"stage{stage_number}.json"
+
+
+def load_shooter(
+    project_root: Path,
+    label: str,
+    *,
+    probe: ProbeFn | None = None,
+) -> CompareShooterBundle:
+    """Open ``project_root`` and build per-stage bundles for ``label``.
+
+    Stages are skipped (omitted from ``stages_by_number``) when:
+      - the stage is marked ``skipped``;
+      - there is no primary video, or the primary has no ``beep_time``;
+      - the lossless trim is not on disk.
+
+    ``probe`` defaults to :func:`splitsmith.fcpxml_gen.probe_video`;
+    pass a stub in tests to avoid shelling out to ffprobe.
+    """
+    if probe is None:
+        probe = fcpxml_gen.probe_video
+    project = MatchProject.load(project_root)
+    pre_buffer = project.trim_pre_buffer_seconds
+    bundles: dict[int, CompareStageBundle] = {}
+    for stage in project.stages:
+        if stage.skipped:
+            continue
+        primary = stage.primary()
+        if primary is None or primary.beep_time is None:
+            continue
+        trim = trim_path_for_stage(project, project_root, stage.stage_number, stage.stage_name)
+        if not trim.exists():
+            continue
+        meta = probe(trim)
+        bundles[stage.stage_number] = CompareStageBundle(
+            stage_number=stage.stage_number,
+            stage_name=stage.stage_name,
+            trim_path=trim,
+            audit_path=audit_path_for_stage(project, project_root, stage.stage_number),
+            beep_offset_in_clip=min(pre_buffer, primary.beep_time),
+            duration_seconds=meta.duration_seconds,
+            width=meta.width,
+            height=meta.height,
+            frame_rate_num=meta.frame_rate_num,
+            frame_rate_den=meta.frame_rate_den,
+        )
+    return CompareShooterBundle(
+        label=label,
+        project_root=project_root,
+        project=project,
+        stages_by_number=bundles,
+    )
+
+
+def _trim_path_for_shooter_stage(
+    shooter: Shooter,
+    shooter_root: Path,
+    stage_number: int,
+    stage_name: str,
+) -> Path:
+    """Same naming as :func:`trim_path_for_stage` but rooted at a shooter dir."""
+    base = f"stage{stage_number}_{_slugify(stage_name)}"
+    exports = Path(shooter.exports_dir).expanduser() if shooter.exports_dir else shooter_root / "exports"
+    if not exports.is_absolute():
+        exports = shooter_root / exports
+    return exports / f"{base}_trimmed.mp4"
+
+
+def load_shooter_from_match(
+    match_root: Path,
+    slug: str,
+    label: str,
+    *,
+    probe: ProbeFn | None = None,
+) -> CompareShooterBundle:
+    """Build a :class:`CompareShooterBundle` from one shooter inside a merged Match.
+
+    Stage definitions come from the match (shared across shooters); per-
+    stage data (time + videos) comes from the shooter. Same skip rules
+    as :func:`load_shooter`: a stage is omitted when it's marked skipped,
+    has no primary video with a beep time, or its lossless trim is
+    missing from the shooter's exports dir.
+    """
+    if probe is None:
+        probe = fcpxml_gen.probe_video
+    match = Match.load(match_root)
+    shooter = match.load_shooter(match_root, slug)
+    shooter_root = Match.shooter_root(match_root, slug)
+    # Stage name lookup from the match-level definitions.
+    stage_names: dict[int, str] = {s.stage_number: s.stage_name for s in match.stages}
+
+    bundles: dict[int, CompareStageBundle] = {}
+    for stage in shooter.stages:
+        if stage.skipped:
+            continue
+        primary = next((v for v in stage.videos if v.role == "primary"), None)
+        if primary is None or primary.beep_time is None:
+            continue
+        stage_name = stage_names.get(stage.stage_number, f"stage{stage.stage_number}")
+        trim = _trim_path_for_shooter_stage(shooter, shooter_root, stage.stage_number, stage_name)
+        if not trim.exists():
+            continue
+        meta = probe(trim)
+        bundles[stage.stage_number] = CompareStageBundle(
+            stage_number=stage.stage_number,
+            stage_name=stage_name,
+            trim_path=trim,
+            audit_path=shooter_root / "audit" / f"stage{stage.stage_number}.json",
+            beep_offset_in_clip=min(shooter.trim_pre_buffer_seconds, primary.beep_time),
+            duration_seconds=meta.duration_seconds,
+            width=meta.width,
+            height=meta.height,
+            frame_rate_num=meta.frame_rate_num,
+            frame_rate_den=meta.frame_rate_den,
+        )
+
+    return CompareShooterBundle(
+        label=label,
+        project_root=shooter_root,
+        project=None,
+        stages_by_number=bundles,
+    )