framerudiments 0.1.0__py3-none-any.whl

framerudiments/flight.py

@@ -0,0 +1,157 @@
+"""Seeded paper-glider animation extracted from the original Shorts renderer.
+
+This is an animation model, not CFD. Its state machine makes the energy
+exchange visible: a fast glide rises, speed bleeds away, the aircraft mushes,
+lift breaks, the nose drops, the dive rebuilds speed, and the plane pulls out
+into another long swoop. A separate falling-leaf mode adds the alternating
+slip/roll seen in a fully stalled paper glider.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import math
+import random
+
+
+@dataclass
+class FlightState:
+    x: float
+    y: float
+    vx: float
+    vy: float
+    pitch: float
+    pitch_rate: float = 0.0
+    roll: float = 0.0
+    yaw_scale: float = 1.0
+    state: str = "glide"
+    state_time: float = 0.0
+    age: float = 0.0
+    stall_count: int = 0
+    history: list[tuple[float, float]] = field(default_factory=list)
+
+
+class PaperPlaneFlight:
+    """Deterministic portrait-space motion with visually explicit stall phases."""
+
+    def __init__(self, seed: int, x: float, y: float, speed: float,
+                 sprite_index: int, stall_after: float | None = None,
+                 behaviour: str = "cycle"):
+        self.rng = random.Random(seed)
+        self.sprite_index = sprite_index
+        self.stall_after = stall_after
+        self.behaviour = behaviour
+        self.phase = self.rng.random() * math.tau
+        self.base_scale = self.rng.uniform(0.78, 1.08)
+        self.depth = self.rng.uniform(0.72, 1.0)
+        self.cruise_speed = speed
+        self.next_cycle = stall_after if stall_after is not None else self.rng.uniform(2.0, 3.1)
+        self.s = FlightState(x=x, y=y, vx=speed, vy=-0.025, pitch=math.radians(-7))
+
+    @property
+    def flight_angle(self) -> float:
+        return math.atan2(self.s.vy, max(1e-6, self.s.vx))
+
+    @property
+    def airspeed(self) -> float:
+        return math.hypot(self.s.vx, self.s.vy)
+
+    @property
+    def angle_of_attack(self) -> float:
+        return self.flight_angle - self.s.pitch
+
+    def _enter(self, state: str) -> None:
+        self.s.state = state
+        self.s.state_time = 0.0
+        if state == "stall":
+            self.s.stall_count += 1
+
+    def _transition(self) -> None:
+        s = self.s
+        if s.state == "glide" and s.age >= self.next_cycle and self.behaviour != "stable":
+            self._enter("climb")
+        elif s.state == "climb" and s.state_time >= 1.02:
+            self._enter("mush")
+        elif s.state == "mush" and s.state_time >= 0.32:
+            self._enter("stall")
+        elif s.state == "stall" and s.state_time >= 0.22:
+            self._enter("drop")
+        elif s.state == "drop" and s.state_time >= (1.10 if self.behaviour == "leaf" else 0.78):
+            self._enter("recovery")
+        elif s.state == "recovery" and s.state_time >= 0.68:
+            self._enter("swoop")
+        elif s.state == "swoop" and s.state_time >= 0.92:
+            self._enter("glide")
+            self.next_cycle = s.age + self.rng.uniform(1.05, 1.65)
+
+    def step(self, dt: float, global_time: float) -> FlightState:
+        s = self.s
+        s.age += dt
+        s.state_time += dt
+        self._transition()
+
+        targets = {
+            "glide":    (self.cruise_speed, -0.018, -6.0),
+            "climb":    (self.cruise_speed * 0.68, -0.105, -25.0),
+            "mush":     (self.cruise_speed * 0.38, -0.012, -20.0),
+            "stall":    (self.cruise_speed * 0.25,  0.055, -14.0),
+            "drop":     (self.cruise_speed * 0.76,  0.205,  36.0),
+            "recovery": (self.cruise_speed * 1.18,  0.095,  17.0),
+            "swoop":    (self.cruise_speed * 1.02, -0.090, -18.0),
+        }
+        target_vx, target_vy, target_pitch_deg = targets[s.state]
+        velocity_scale = self.cruise_speed / 0.22
+        target_vy *= velocity_scale
+
+        if self.behaviour == "stable":
+            target_vy = (-0.010 + 0.018 * math.sin(global_time * 0.72 + self.phase)) * velocity_scale
+            target_pitch_deg = math.degrees(math.atan2(target_vy, target_vx)) - 2.5
+
+        leaf_weight = 0.0
+        if self.behaviour == "leaf" and s.state in {"stall", "drop"}:
+            leaf_weight = min(1.0, s.state_time / 0.32)
+            target_vx *= 0.58
+            target_vy = 0.155 * velocity_scale
+            s.x += math.sin(global_time * 5.0 + self.phase) * 0.0018 * leaf_weight
+
+        response = 1.9 if s.state in {"climb", "swoop"} else 3.2
+        if s.state == "stall":
+            response = 5.0
+        s.vx += (target_vx - s.vx) * min(1.0, dt * response)
+        s.vy += (target_vy - s.vy) * min(1.0, dt * response)
+
+        target_pitch = math.radians(target_pitch_deg)
+        pitch_response = 2.2 if s.state in {"mush", "stall"} else 4.0
+        s.pitch_rate += ((target_pitch - s.pitch) * pitch_response - s.pitch_rate * 3.0) * dt
+        s.pitch += s.pitch_rate * dt
+
+        # Bank belongs to the manoeuvre, not a permanent oscillation. Stable
+        # flight stays almost level; climbs and pull-outs use one smooth lean.
+        bank_by_state = {
+            "glide": 0.0, "climb": -7.0, "mush": -3.0,
+            "stall": 2.0, "drop": 8.0, "recovery": 5.0, "swoop": -8.0,
+        }
+        bank = bank_by_state[s.state]
+        if leaf_weight:
+            bank = 31.0 * math.sin(global_time * 5.0 + self.phase) * leaf_weight
+        s.roll += (bank - s.roll) * min(1.0, dt * 5.2)
+        s.yaw_scale = 1.0 - 0.38 * leaf_weight * abs(math.sin(global_time * 5.0 + self.phase))
+
+        s.x += s.vx * dt
+        s.y += s.vy * dt
+        if not s.history or math.hypot(s.x - s.history[-1][0], s.y - s.history[-1][1]) > 0.003:
+            s.history.append((s.x, s.y))
+            del s.history[:-70]
+        return s
+
+
+def simulate_stall(seed: int = 7, seconds: float = 10.0,
+                   dt: float = 1 / 120) -> list[tuple[float, str, float, float, float]]:
+    plane = PaperPlaneFlight(seed, 0.05, 0.42, 0.15, 0, stall_after=0.5)
+    samples = []
+    t = 0.0
+    while t < seconds:
+        plane.step(dt, t)
+        samples.append((t, plane.s.state, plane.airspeed, plane.s.y, plane.s.pitch))
+        t += dt
+    return samples

framerudiments/io.py

@@ -0,0 +1,66 @@
+"""Strict documents and content identities."""
+import hashlib
+import json
+import math
+from pathlib import Path
+
+
+def sha256(path):
+    h = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def read_json(path):
+    def bad(value):
+        raise ValueError(f"Non-finite JSON number: {value}")
+    def unique(pairs):
+        out = {}
+        for key, value in pairs:
+            if key in out:
+                raise ValueError(f"Duplicate JSON key: {key}")
+            out[key] = value
+        return out
+    return json.loads(Path(path).read_text(encoding="utf-8-sig"),
+                      parse_constant=bad, object_pairs_hook=unique)
+
+
+def write_json(path, value):
+    Path(path).write_text(json.dumps(value, ensure_ascii=False, allow_nan=False, indent=2) + "\n",
+                          encoding="utf-8")
+
+
+def number(value, name, *, minimum=None, maximum=None):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        raise ValueError(f"{name} must be finite")
+    if (minimum is not None and value < minimum) or (maximum is not None and value > maximum):
+        raise ValueError(f"{name} outside [{minimum}, {maximum}]")
+    return float(value)
+
+
+def integer(value, name, *, minimum=0, maximum=2**31 - 1):
+    if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
+        raise ValueError(f"{name} must be an integer in [{minimum}, {maximum}]")
+    return value
+
+
+def fields(data, allowed, label):
+    if not isinstance(data, dict):
+        raise ValueError(f"{label} must be an object")
+    extra = set(data) - set(allowed)
+    if extra:
+        raise ValueError(f"Unknown {label} fields: {sorted(extra)}")
+
+
+def file_ref(data, base):
+    fields(data, {"path", "sha256"}, "file reference")
+    path = (Path(base) / data["path"]).resolve()
+    expected = data["sha256"]
+    if not isinstance(expected, str) or len(expected) != 64 or any(c not in "0123456789abcdefABCDEF" for c in expected):
+        raise ValueError(f"A SHA-256 is required for {path}")
+    actual = sha256(path)
+    if actual != expected.lower():
+        raise ValueError(f"Input hash mismatch: {path}")
+    return {"path": str(path), "sha256": actual, "bytes": path.stat().st_size}

framerudiments/motion.py

@@ -0,0 +1,137 @@
+"""Native integer-pip motion. Never substitute a Python movement engine."""
+import math
+from importlib.metadata import version
+from functools import lru_cache
+
+from .io import file_ref, read_json, fields, number, integer, sha256
+from .stemlab import selected_match
+
+
+@lru_cache(maxsize=1)
+def native_identity():
+    import dancerudiments as dr
+    return dict(distribution="dancerudiments", version=version("dancerudiments"),
+                path=dr.__file__, sha256=sha256(dr.__file__), pips_per_beat=dr.PIPS_PER_BEAT)
+
+
+class Motion:
+    def __init__(self, config, base, clock):
+        import dancerudiments as dr
+        self.dr, self.clock = dr, clock
+        fields(config, {"kind", "pattern", "rate", "phase_beats", "origin_beat", "file",
+                        "source_index", "match_index", "source_offset_seconds", "axes", "outside",
+                        "allow_outside_match", "interpolate", "repeat_clock", "channels"}, "motion")
+        if dr.PIPS_PER_BEAT != 64:
+            raise ValueError("Native DanceRudiments must use 64 pips per beat")
+        self.config = config
+        self.kind = config.get("kind", "named")
+        self.rate = number(config.get("rate", 1), "motion rate", minimum=0.00001)
+        self.phase = number(config.get("phase_beats", 0), "phase")
+        self.origin = number(config.get("origin_beat", 0), "motion origin")
+        self.file = file_ref(config["file"], base) if "file" in config else None
+        self.evidence = {"native": native_identity(), "config": config, "file": self.file}
+        self.files = [self.file] if self.file else []
+        self.pattern = config.get("pattern")
+        self.recording = None
+        if config.get("repeat_clock", "continuous") not in {"source", "continuous"}:
+            raise ValueError("repeat_clock must be source or continuous")
+        if self.kind == "composite":
+            if not 1 <= len(config["channels"]) <= 3:
+                raise ValueError("Composite motion needs one to three independent output channels")
+            self.channels = []
+            for channel in config["channels"]:
+                fields(channel, {"motion", "axis"}, "composite channel")
+                child = Motion(channel["motion"], base, clock)
+                self.channels.append((child, integer(channel.get("axis", 0), "channel axis", maximum=2)))
+                self.files.extend(child.files)
+            self.evidence["channels"] = [child.evidence for child, axis in self.channels]
+            return
+        if self.kind == "match":
+            if self.file is None:
+                raise ValueError("Match needs a pinned StemLab report")
+            evidence = selected_match(self.file["path"], config["source_index"], config["match_index"])
+            match = evidence["selection"]
+            self.evidence["match"] = evidence
+            self.pattern = match["pattern"]
+            self.phase = match["phase_beats"]
+            offset = number(config.get("source_offset_seconds", 0), "match source offset")
+            self.origin = clock.beat_at(match["start_seconds"] + offset)
+            self.window = (match["start_seconds"] + offset, match["end_seconds"] + offset)
+        if self.kind in {"named", "match"}:
+            if self.pattern not in {x["name"] for x in dr.catalogue()}:
+                raise ValueError(f"Unknown native movement: {self.pattern}")
+        elif self.kind == "recording":
+            from dancerudiments_authoring.recording import load_recording
+            if self.rate != 1 or self.phase != 0 or self.origin != 0 or config.get("interpolate", False):
+                raise ValueError("Recordings use their own source clock; no rate, phase or interpolation override")
+            recording = load_recording(self.file["path"])
+            self.recording = recording.to_native()
+            self.dimensions = list(recording.dimensions)
+            self.axes = config.get("axes", self.dimensions[:3])
+            if not 1 <= len(self.axes) <= 3 or any(x not in self.dimensions for x in self.axes):
+                raise ValueError("Choose one to three existing recording axes")
+            if config.get("outside", "error") not in {"error", "neutral"}:
+                raise ValueError("Recording outside policy must be error or neutral")
+            self.evidence["clock"] = recording.to_dict()["clock"]
+            self.evidence["dimensions"] = self.dimensions
+            self.evidence["provenance"] = recording.provenance
+        elif self.kind == "table":
+            table = read_json(self.file["path"])
+            if table.get("pipsPerBeat", table.get("pips_per_beat")) != 64:
+                raise ValueError("Native export needs 64-pip identity")
+            if not table.get("version") or not (table.get("wasmSha256") or table.get("extension_sha256")):
+                raise ValueError("Native export needs version and binary hash provenance")
+            self.row = table["movements"][self.pattern]
+            self.samples = self.row["samples"]
+            period = self.row.get("periodPips", self.row.get("period_pips"))
+            if integer(period, "table period", minimum=1) != len(self.samples):
+                raise ValueError("Native table period does not match its samples")
+            for row in self.samples:
+                if not 1 <= len(row) <= 3:
+                    raise ValueError("Native tables have one to three axes")
+                for v in row:
+                    number(v, "native table sample", minimum=-1, maximum=1)
+        else:
+            raise ValueError(f"Unknown motion kind: {self.kind}")
+
+    @lru_cache(maxsize=4096)
+    def _named(self, pip):
+        result = self.dr.sample(self.pattern, pip)
+        return (result.x, result.y, result.z)
+
+    def recording_values(self, source_seconds):
+        r = self.recording
+        pip = math.floor((source_seconds - r.beat_zero_seconds) * r.bpm / 60 * 64)
+        if not r.start_pip <= pip < r.start_pip + r.sample_count:
+            if self.config.get("outside", "error") == "neutral":
+                return [0.0] * len(self.dimensions)
+            raise ValueError(f"Source time {source_seconds} is outside non-looping recording")
+        return r.sample(pip)
+
+    def sample(self, source_seconds, *, continuous_beat=None):
+        if self.kind == "composite":
+            values = tuple(child.sample(source_seconds, continuous_beat=continuous_beat)[axis]
+                           for child, axis in self.channels)
+            return (values + (0.0, 0.0))[:3]
+        if self.recording:
+            values = self.recording_values(source_seconds)
+            projected = tuple(values[self.dimensions.index(axis)] for axis in self.axes)
+            return (projected + (0.0, 0.0))[:3]
+        if self.kind == "match" and not self.config.get("allow_outside_match", False):
+            if not self.window[0] <= source_seconds < self.window[1]:
+                raise ValueError("Motion exceeds matched window; choose another fit or explicitly permit extrapolation")
+        beat = self.clock.beat_at(source_seconds)
+        if self.kind in {"named", "table"} and self.config.get("repeat_clock", "continuous") == "continuous":
+            beat = beat if continuous_beat is None else continuous_beat
+        position = ((beat - self.origin) * self.rate + self.phase) * 64
+        pip = math.floor(position)
+        def sample_at(p):
+            values = tuple(self.samples[p % len(self.samples)]) if self.kind == "table" else self._named(p)
+            return (values + (0.0, 0.0))[:3]
+        a = sample_at(pip)
+        if not self.config.get("interpolate", False):
+            return a
+        # Explicit legacy compositor mode, still only adjacent native integer samples.
+        b = sample_at(pip + 1)
+        fraction = position - pip
+        return tuple(x + (y - x) * fraction for x, y in zip(a, b))

framerudiments/project.py

@@ -0,0 +1,124 @@
+"""Validated portable render projects; private media remains outside the package."""
+from fractions import Fraction
+import math
+from pathlib import Path
+
+from .io import read_json, file_ref, fields, integer, number, sha256
+from .timeline import BeatClock, parse_lrc, parse_cue, frame_ledger
+from .stemlab import beat_grid, selected_loop
+
+
+class Project:
+    @classmethod
+    def load(cls, path):
+        path = Path(path).resolve()
+        return cls(read_json(path), path.parent, project_path=path)
+
+    def __init__(self, data, base, *, project_path=None):
+        self.base, self.path, self.data = Path(base), project_path, data
+        fields(data, {"schema", "title", "artist", "purpose", "width", "height", "fps", "fps_reason",
+                      "audio", "clock", "font", "lyrics", "cues", "background", "layers", "captions",
+                      "identity", "stemlab_loop", "notes", "lyric_art", "canonical_lyrics"}, "project")
+        if data.get("schema") != "framerudiments.project.v1":
+            raise ValueError("Expected framerudiments.project.v1")
+        self.width = integer(data.get("width", 1080), "width", minimum=16, maximum=7680)
+        self.height = integer(data.get("height", 1920), "height", minimum=16, maximum=7680)
+        if self.width % 2 or self.height % 2:
+            raise ValueError("H.264 yuv420p needs even dimensions")
+        self.fps = integer(data.get("fps", 60), "fps", minimum=1, maximum=120)
+        if self.fps != 60 and not data.get("fps_reason"):
+            raise ValueError("Non-60-fps output needs a documented reason")
+        self.purpose = data.get("purpose", "short")
+        if self.purpose not in {"short", "visualiser", "canvas"}:
+            raise ValueError("purpose must be short, visualiser or canvas")
+        self.inputs = []
+        self.audio = dict(data["audio"])
+        fields(self.audio, {"source", "sample_rate", "start_sample", "end_sample", "repeats", "fade_seconds"}, "audio")
+        self.audio_ref = self.ref(self.audio["source"])
+        self.sample_rate = integer(self.audio["sample_rate"], "sample rate", minimum=1, maximum=768000)
+        self.loop = None
+        if "stemlab_loop" in data:
+            cfg = data["stemlab_loop"]
+            fields(cfg, {"file", "id"}, "StemLab loop")
+            ref = self.ref(cfg["file"])
+            self.loop = selected_loop(ref["path"], cfg["id"], self.audio_ref["sha256"])
+            for key in ("start_sample", "end_sample", "sample_rate"):
+                if key in self.audio and self.audio[key] != self.loop[key]:
+                    raise ValueError(f"Explicit {key} conflicts with selected StemLab loop")
+                self.audio[key] = self.loop[key]
+        self.start_sample = integer(self.audio.get("start_sample", 0), "start sample")
+        self.end_sample = integer(self.audio["end_sample"], "end sample", minimum=self.start_sample + 1)
+        self.sample_rate = self.audio["sample_rate"]
+        self.repeats = integer(self.audio.get("repeats", 1), "repeats", minimum=1, maximum=1000)
+        self.slice_duration = Fraction(self.end_sample - self.start_sample, self.sample_rate)
+        self.duration = self.slice_duration * self.repeats
+        self.frame_count = math.ceil(self.duration * self.fps)
+        if self.frame_count > 10_000_000:
+            raise ValueError("Render exceeds ten million frames")
+        self.fade = number(self.audio.get("fade_seconds", .12 if self.purpose == "short" else 0),
+                           "fade seconds", minimum=0, maximum=float(self.duration) / 2)
+        cfg = data["clock"]
+        fields(cfg, {"bpm", "origin", "authority", "status", "phase_status", "beat_grid"}, "clock")
+        if not cfg.get("authority") or cfg.get("status") not in {"confirmed", "estimated", "synthetic"}:
+            raise ValueError("Clock needs authority and confirmed/estimated/synthetic status")
+        grid = beat_grid(self.ref(cfg["beat_grid"])["path"]) if "beat_grid" in cfg else None
+        self.clock = BeatClock(bpm=cfg.get("bpm"), origin=cfg.get("origin", 0), beats=grid)
+        self.font_ref = self.ref(data["font"]) if "font" in data else None
+        if (data.get("lyrics") or data.get("identity")) and not self.font_ref:
+            raise ValueError("Pin an explicit font for all authored text")
+        self.lyric_ref = self.ref(data["lyrics"]) if "lyrics" in data else None
+        self.lyrics = self.ledger(parse_lrc(self.lyric_ref["path"])) if self.lyric_ref else []
+        if "canonical_lyrics" in data:
+            ref = self.ref(data["canonical_lyrics"])
+            canonical = [line.strip() for line in Path(ref["path"]).read_text(encoding="utf-8-sig").splitlines()
+                         if line.strip() and not line.strip().startswith("[")]
+            if not self.lyric_ref:
+                raise ValueError("canonical_lyrics requires a timed lyrics file")
+            timed = [e.text for e in parse_lrc(self.lyric_ref["path"]) if e.text]
+            if timed != canonical:
+                raise ValueError("Timed lyrics do not match the pinned canonical text, including punctuation")
+        self.cues = []
+        if "cues" in data:
+            ref = self.ref(data["cues"])
+            parser = parse_cue if Path(ref["path"]).suffix.lower() == ".cue" else parse_lrc
+            events = parser(ref["path"]) if parser is parse_cue else parser(ref["path"], lyrics=False)
+            self.cues = self.ledger(events)
+
+    def ref(self, data):
+        result = file_ref(data, self.base)
+        self.inputs.append(result)
+        return result
+
+    def ledger(self, events):
+        return frame_ledger(events, start_sample=self.start_sample, end_sample=self.end_sample,
+                            sample_rate=self.sample_rate, fps=self.fps, repeats=self.repeats)
+
+    def source_time(self, frame):
+        output = Fraction(frame, self.fps)
+        # Only the fractional last video frame can exceed exact audio; clamp into last source sample.
+        output = min(output, self.duration - Fraction(1, self.sample_rate))
+        return float(Fraction(self.start_sample, self.sample_rate) + output % self.slice_duration)
+
+    def continuous_beat(self, frame):
+        output = min(Fraction(frame, self.fps), self.duration - Fraction(1, self.sample_rate))
+        cycle = int(output // self.slice_duration)
+        start = float(Fraction(self.start_sample, self.sample_rate))
+        end = float(Fraction(self.end_sample, self.sample_rate))
+        return self.clock.beat_at(self.source_time(frame)) + cycle * (
+            self.clock.beat_at(end) - self.clock.beat_at(start))
+
+    def verify_inputs(self):
+        for ref in self.inputs:
+            if sha256(ref["path"]) != ref["sha256"]:
+                raise ValueError(f"Input changed since preparation: {ref['path']}")
+
+    def summary(self):
+        return dict(schema="framerudiments.plan.v1", dimensions=[self.width, self.height], fps=self.fps,
+                    frames=self.frame_count, source_start_sample=self.start_sample,
+                    source_end_sample_exclusive=self.end_sample, sample_rate=self.sample_rate,
+                    repeats=self.repeats, duration_seconds=float(self.duration),
+                    video_duration_seconds=self.frame_count / self.fps,
+                    frame_rounding="nearest, ties toward positive infinity; stable source ordering",
+                    clock=self.data["clock"], endpoint_fade_seconds=self.fade, endpoint_fade_curve="qsin",
+                    lyrics=self.lyrics, cues=self.cues, stemlab_loop=self.loop, inputs=self.inputs,
+                    state="prepared; perceptual review pending")

framerudiments/render.py

@@ -0,0 +1,111 @@
+"""Shared render runner, cleanup, evidence and representative encoded stills."""
+from pathlib import Path
+import subprocess
+from importlib.metadata import version
+
+from PIL import Image
+
+from . import encoding
+from .compositor import Compositor
+from .io import sha256, write_json
+from .project import Project
+from .subtitles import export_subtitles
+
+
+def checkpoints(project):
+    count = project.frame_count
+    return sorted({0, count - 1, count // 4, count // 2, 3 * count // 4,
+                   *(max(0, min(count - 1, event["frame"] + delta))
+                     for event in project.lyrics + project.cues for delta in (-1, 0, 1))})
+
+
+def _prepare(project, output, ffmpeg, ffprobe, scene):
+    project = Project.load(project) if not isinstance(project, Project) else project
+    ffmpeg, ffprobe = encoding.binaries(ffmpeg, ffprobe)
+    source_probe = encoding.validate_audio(project, ffprobe)
+    # Load every dependency before making the evidence snapshot.
+    compositor = Compositor(project, scene=scene)
+    project.verify_inputs()
+    output = Path(output).resolve()
+    output.mkdir(parents=True, exist_ok=False)
+    (output / "qa").mkdir()
+    write_json(output / "plan.json", project.summary())
+    write_json(output / "source-probe.json", source_probe)
+    export_subtitles(project.lyrics, project.fps, project.frame_count, output, project.width, project.height)
+    return project, output, ffmpeg, ffprobe, compositor
+
+
+def preflight(project, output, *, ffmpeg=None, ffprobe=None, scene=None):
+    p, out, ffmpeg, ffprobe, compositor = _prepare(project, output, ffmpeg, ffprobe, scene)
+    selected = set(checkpoints(p))
+    try:
+        for n in range(p.frame_count):
+            image, _ = compositor.frame(n)
+            if n in selected:
+                image.save(out / "qa" / f"source-{n:08}.png")
+        p.verify_inputs()
+        result = dict(p.summary(), composition=compositor.evidence(), state="preflight passed; no encoded video")
+        write_json(out / "manifest.json", result)
+        return result
+    except BaseException as exc:
+        write_json(out / "failure.json", dict(state="preflight failed", error=str(exc)))
+        raise
+
+
+def render(project, output, *, ffmpeg=None, ffprobe=None, scene=None, preset="fast", crf=20):
+    p, out, ffmpeg, ffprobe, compositor = _prepare(project, output, ffmpeg, ffprobe, scene)
+    candidate, final = out / "candidate.mp4", out / "video.mp4"
+    cmd = encoding.command(p, candidate, ffmpeg, preset=preset, crf=crf)
+    write_json(out / "encode-command.json", cmd)
+    selected = set(checkpoints(p))
+    process = None
+    try:
+        with (out / "encode.log").open("wb") as log:
+            process = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=log)
+            for n in range(p.frame_count):
+                image, _ = compositor.frame(n)
+                if n in selected:
+                    image.save(out / "qa" / f"source-{n:08}.png")
+                process.stdin.write(image.tobytes())
+            process.stdin.close()
+            if process.wait() != 0:
+                raise RuntimeError(f"FFmpeg failed; see {out / 'encode.log'}")
+        p.verify_inputs()
+        verified = encoding.verify(candidate, p, ffmpeg, ffprobe)
+        source_audio = encoding.probe(p.audio_ref["path"], ffprobe)
+        source_channels = next(s["channels"] for s in source_audio["streams"] if s["codec_type"] == "audio")
+        output_channels = next(s["channels"] for s in verified["probe"]["streams"] if s["codec_type"] == "audio")
+        if source_channels != output_channels:
+            raise ValueError("Encoder changed channel count")
+        candidate.rename(final)
+        # Extract from the actual encoded file, independently of the source Pillow frames.
+        selection = "+".join(f"eq(n\\,{n})" for n in sorted(selected))
+        subprocess.run([ffmpeg, "-n", "-v", "error", "-i", str(final), "-vf", f"select={selection}",
+                        "-fps_mode", "passthrough", "-start_number", "0", "-frames:v", str(len(selected)),
+                        str(out / "qa" / "checkpoint-%08d.png")], check=True, capture_output=True)
+        for i, n in enumerate(sorted(selected)):
+            (out / "qa" / f"checkpoint-{i:08}.png").rename(out / "qa" / f"encoded-{n:08}.png")
+        with Image.open(out / "qa" / "encoded-00000000.png") as first:
+            first.save(out / "poster.png")
+            thumbnail = first.copy()
+            thumbnail.thumbnail((360, 640))
+            thumbnail.save(out / "phone-preview.png")
+        result = dict(p.summary(), composition=compositor.evidence(), verification=verified,
+                      software={"framerudiments": "0.1.0", "Pillow": version("Pillow"),
+                                "dancerudiments": version("dancerudiments"),
+                                "ffmpeg": subprocess.check_output([ffmpeg, "-version"], text=True).splitlines()[0]},
+                      output={"path": str(final), "sha256": sha256(final), "bytes": final.stat().st_size},
+                      state="technical-QA passed; creative and attended listening review pending")
+        write_json(out / "manifest.json", result)
+        return result
+    except BaseException as exc:
+        if process and process.poll() is None:
+            if process.stdin and not process.stdin.closed:
+                process.stdin.close()
+            try:
+                process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                process.kill()  # only the encoder child owned by this render
+                process.wait()
+        write_json(out / "failure.json", dict(state="failed; any encoded file remains unapproved", error=str(exc)))
+        raise

framerudiments/stemlab.py

@@ -0,0 +1,36 @@
+"""Read saved StemLab evidence without re-running analysis or copying DSP."""
+from .io import read_json, integer
+
+
+def selected_loop(path, loop_id, source_sha256):
+    report = read_json(path)
+    if report.get("schema") != "stemlab.loops.v1":
+        raise ValueError("Expected stemlab.loops.v1")
+    if report.get("source_sha256") != source_sha256:
+        raise ValueError("StemLab loop belongs to a different audio source")
+    pool = [x for x in report["loops"] if x["id"] == loop_id]
+    if len(pool) != 1:
+        raise ValueError("Select one accepted loop id; exploratory candidates are not accepted loops")
+    item = pool[0]
+    start = integer(item["start_sample"], "loop start")
+    end = integer(item["end_sample"], "loop end", minimum=start + 1)
+    return dict(start_sample=start, end_sample=end, sample_rate=report["sample_rate"],
+                evidence=item, listening_approved=False)
+
+
+def selected_match(path, source_index, match_index):
+    report = read_json(path)
+    if report.get("schema") != "stemlab.dancerudiments.candidates.v1":
+        raise ValueError("Expected stemlab.dancerudiments.candidates.v1")
+    source = report["sources"][integer(source_index, "source index")]
+    match = source["matches"][integer(match_index, "match index")]
+    return {"selection": match, "source": {k: v for k, v in source.items() if k != "matches"},
+            "note": "Ranked fit in this source window; no creative or whole-song approval implied."}
+
+
+def beat_grid(path):
+    data = read_json(path)
+    beats = data.get("beats")
+    if not isinstance(beats, list):
+        raise ValueError("Expected a saved beat report with beats[]")
+    return beats