framerudiments 0.1.0__py3-none-any.whl

framerudiments/__init__.py

@@ -0,0 +1,7 @@
+"""Offline frame composition on a traceable musical clock."""
+__version__ = "0.1.0"
+
+from .project import Project
+from .render import render, preflight
+
+__all__ = ["Project", "render", "preflight", "__version__"]

framerudiments/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

framerudiments/atlas.py

@@ -0,0 +1,44 @@
+"""Connected alpha-component cleaning extracted from the sprite preparation tools."""
+from collections import deque
+from PIL import Image
+
+def components(alpha: Image.Image, threshold: int = 18) -> list[list[tuple[int, int]]]:
+    width, height = alpha.size
+    pixels = alpha.load()
+    seen: set[tuple[int, int]] = set()
+    result: list[list[tuple[int, int]]] = []
+    for y in range(height):
+        for x in range(width):
+            if (x, y) in seen or pixels[x, y] < threshold:
+                continue
+            queue = deque([(x, y)])
+            seen.add((x, y))
+            group: list[tuple[int, int]] = []
+            while queue:
+                px, py = queue.popleft()
+                group.append((px, py))
+                for ny in range(max(0, py - 1), min(height, py + 2)):
+                    for nx in range(max(0, px - 1), min(width, px + 2)):
+                        if (nx, ny) not in seen and pixels[nx, ny] >= threshold:
+                            seen.add((nx, ny))
+                            queue.append((nx, ny))
+            result.append(group)
+    return sorted(result, key=len, reverse=True)
+
+def isolate_one_object(cell: Image.Image) -> tuple[Image.Image, int, int]:
+    rgba = cell.convert("RGBA")
+    groups = components(rgba.getchannel("A"))
+    if not groups:
+        raise ValueError("atlas cell contains no opaque object")
+    keep = set(groups[0])
+    removed = sum(len(group) for group in groups[1:])
+    src = rgba.load()
+    for y in range(rgba.height):
+        for x in range(rgba.width):
+            if (x, y) not in keep:
+                r, g, b, _ = src[x, y]
+                src[x, y] = (r, g, b, 0)
+    post = [group for group in components(rgba.getchannel("A")) if len(group) >= 8]
+    if len(post) != 1:
+        raise ValueError(f"cleaned cell has {len(post)} meaningful objects")
+    return rgba, len(groups), removed

framerudiments/choreography.py

@@ -0,0 +1,30 @@
+"""Frame-addressed entrance/hold/exit mechanics extracted from lyric-plane rendering."""
+from .timeline import half_up
+from .io import number, integer
+
+
+def lyric_placements(events, frame, *, fps, bpm, transition_ticks=8, width=1920, centre=960,
+                     margin=650, programme_frames):
+    """Enter by onset, hold to explicit end_frame, then leave; no copied song BPM."""
+    fps = integer(fps, "fps", minimum=1)
+    bpm = number(bpm, "bpm", minimum=.00001)
+    transition = max(1, half_up(number(transition_ticks, "transition ticks", minimum=0) * 3.75 / bpm * fps))
+    for index, event in enumerate(events):
+        onset = event["frame"]
+        if "end_frame" not in event:
+            raise ValueError("Lyric-art choreography requires explicit end_frame")
+        following = event["end_frame"]
+        if following < onset:
+            raise ValueError("Lyric-art end precedes onset")
+        enter, end = max(0, onset - transition), min(programme_frames, following + transition)
+        if not enter <= frame < end:
+            continue
+        if frame < onset:
+            u = 1 - (1 - (frame - enter) / max(1, onset - enter)) ** 3
+            x, phase = -margin + (centre + margin) * u, "enter"
+        elif frame < following:
+            x, phase = centre, "hold"
+        else:
+            u = 1 - (1 - min(1, (frame - following) / transition)) ** 3
+            x, phase = centre + (width + margin - centre) * u, "exit"
+        yield index, round(x), phase

framerudiments/cli.py

@@ -0,0 +1,54 @@
+import argparse
+import json
+import sys
+
+from . import __version__
+from .demo import create_demo
+from .io import write_json
+from .project import Project
+from .render import preflight, render
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="FrameRudiments: traceable Shorts and lyric visualisers")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    demo = commands.add_parser("demo", help="Create a synthetic audio/image/recording project")
+    demo.add_argument("directory")
+    demo.add_argument("--font", required=True)
+    demo.add_argument("--width", type=int, default=360)
+    demo.add_argument("--height", type=int, default=640)
+    plan = commands.add_parser("plan", help="Validate pinned inputs and export the frame ledger")
+    plan.add_argument("project")
+    plan.add_argument("--output", required=True)
+    for name in ("preflight", "render"):
+        item = commands.add_parser(name)
+        item.add_argument("project")
+        item.add_argument("--output", required=True, help="A new evidence/output directory; never overwrites")
+        item.add_argument("--ffmpeg")
+        item.add_argument("--ffprobe")
+        if name == "render":
+            item.add_argument("--preset", default="fast")
+            item.add_argument("--crf", type=int, default=20)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "demo":
+            print(create_demo(args.directory, args.font, width=args.width, height=args.height))
+        elif args.command == "plan":
+            output = __import__("pathlib").Path(args.output)
+            if output.exists():
+                raise ValueError("Plan output already exists")
+            project = Project.load(args.project)
+            from .compositor import Compositor
+            Compositor(project)
+            write_json(output, project.summary())
+            print(output)
+        else:
+            runner = preflight if args.command == "preflight" else render
+            extra = {"preset": args.preset, "crf": args.crf} if args.command == "render" else {}
+            result = runner(args.project, args.output, ffmpeg=args.ffmpeg, ffprobe=args.ffprobe, **extra)
+            print(json.dumps({"state": result["state"], "frames": result["frames"], "output": args.output}))
+        return 0
+    except (ValueError, OSError, RuntimeError, KeyError, IndexError) as exc:
+        print(f"FrameRudiments: {exc}", file=sys.stderr)
+        return 2

framerudiments/compositor.py

@@ -0,0 +1,278 @@
+"""Pillow scene composition; per-release artwork and appearance stay declarative."""
+from dataclasses import dataclass
+from functools import lru_cache
+import math
+
+from PIL import Image, ImageDraw, ImageFont, ImageOps
+
+from .effects import alpha_scaled, transformed_bounds, within, directional_trail, atlas_cell
+from .io import fields, number, integer
+from .motion import Motion
+from .timeline import EventTrack
+
+
+@dataclass(frozen=True)
+class FrameContext:
+    frame: int
+    output_seconds: float
+    source_seconds: float
+    beat: float
+    lyric: dict | None
+    cue: dict | None
+
+
+def rectangle(value, name, width, height):
+    if not isinstance(value, (list, tuple)) or len(value) != 4:
+        raise ValueError(f"{name} needs [left, top, right, bottom]")
+    value = tuple(number(x, name) for x in value)
+    if not (0 <= value[0] < value[2] <= width and 0 <= value[1] < value[3] <= height):
+        raise ValueError(f"{name} must be an ordered rectangle inside the frame")
+    return value
+
+
+class TextBlock:
+    def __init__(self, project, config, *, label):
+        fields(config, {"box", "font_size", "min_font_size", "colour", "panel", "stroke", "mode",
+                        "line_spacing", "neighbour_colour"}, label)
+        self.project, self.config, self.label = project, config, label
+        self.box = rectangle(config["box"], label, project.width, project.height)
+        self.maximum = integer(config.get("font_size", 60), "font size", minimum=1, maximum=512)
+        self.minimum = integer(config.get("min_font_size", self.maximum), "min font size", minimum=1,
+                               maximum=self.maximum)
+        self.spacing = integer(config.get("line_spacing", 8), "line spacing", maximum=512)
+        self.stroke = integer(config.get("stroke", 1), "text stroke", maximum=20)
+        if not project.font_ref:
+            raise ValueError("Text needs an explicit font")
+        self.colour = config.get("colour", "#f5eddf")
+        self.mode = config.get("mode", "current")
+        if self.mode not in {"current", "neighbours"}:
+            raise ValueError("Caption mode must be current or neighbours")
+
+    @lru_cache(maxsize=256)
+    def layout(self, text):
+        draw = ImageDraw.Draw(Image.new("RGBA", (1, 1)))
+        left, top, right, bottom = self.box
+        for size in range(self.maximum, self.minimum - 1, -1):
+            font = ImageFont.truetype(self.project.font_ref["path"], size)
+            rows = []
+            for paragraph in text.split("\n"):
+                line = ""
+                for word in paragraph.split():
+                    trial = (line + " " + word).strip()
+                    bb = draw.textbbox((0, 0), trial, font=font, stroke_width=self.stroke)
+                    if bb[2] - bb[0] > right - left and line:
+                        rows.append(line)
+                        line = word
+                    else:
+                        line = trial
+                rows.append(line)
+            boxes = [draw.textbbox((0, 0), row, font=font, stroke_width=self.stroke) for row in rows]
+            height = sum(bb[3] - bb[1] for bb in boxes) + self.spacing * (len(rows) - 1)
+            if height <= bottom - top and all(bb[2] - bb[0] <= right - left for bb in boxes):
+                return font, tuple(rows), tuple(boxes), height
+        raise ValueError(f"{self.label} cannot fit without clipping: {text!r}")
+
+    def draw(self, image, text, *, colour=None):
+        if not text:
+            return []
+        font, rows, boxes, height = self.layout(text)
+        left, top, right, bottom = self.box
+        draw = ImageDraw.Draw(image)
+        if panel := self.config.get("panel"):
+            draw.rounded_rectangle(self.box, radius=12, fill=panel)
+        y = top + (bottom - top - height) / 2
+        bounds = []
+        for row, bb in zip(rows, boxes):
+            x = left + (right - left - (bb[2] - bb[0])) / 2 - bb[0]
+            actual = (x + bb[0], y, x + bb[2], y + bb[3] - bb[1])
+            if not within(actual, self.box):
+                raise ValueError(f"Text outside {self.label} box")
+            draw.text((x, y - bb[1]), row, font=font, fill=colour or self.colour,
+                      stroke_width=self.stroke, stroke_fill="#12111c")
+            bounds.append([round(v, 3) for v in actual])
+            y += bb[3] - bb[1] + self.spacing
+        return bounds
+
+
+class Sprite:
+    def __init__(self, project, cfg):
+        fields(cfg, {"id", "type", "asset", "center", "width", "bounds", "crop_alpha", "motion", "mapping",
+                     "atlas", "opacity", "trail", "start_seconds", "end_seconds", "cue_labels"}, "layer")
+        self.project, self.cfg = project, cfg
+        self.id = cfg["id"]
+        self.kind = cfg.get("type", "sprite")
+        if self.kind not in {"sprite", "bars"}:
+            raise ValueError("Supported declarative layers: sprite and bars; use scene hook for custom drawing")
+        self.bounds = rectangle(cfg.get("bounds", [0, 0, project.width, project.height]),
+                                "layer bounds", project.width, project.height)
+        self.opacity = number(cfg.get("opacity", 1), "opacity", minimum=0, maximum=1)
+        self.motion = Motion(cfg["motion"], project.base, project.clock) if "motion" in cfg else None
+        if self.motion:
+            project.inputs.extend(self.motion.files)
+        mapping = cfg.get("mapping", {})
+        fields(mapping, {"dx", "dy", "rotation", "scale", "x_axis", "y_axis", "rotation_axis", "scale_axis"}, "appearance mapping")
+        self.mapping = {k: number(mapping.get(k, 0), k) for k in ("dx", "dy", "rotation", "scale")}
+        self.axes = {key: integer(mapping.get(key, default), key, maximum=2)
+                     for key, default in (("x_axis", 0), ("y_axis", 1), ("rotation_axis", 2), ("scale_axis", 2))}
+        if abs(self.mapping["scale"]) >= 1:
+            raise ValueError("Scale amplitude must keep the sprite's size positive")
+        if self.kind == "bars":
+            if not self.motion or not self.motion.recording:
+                raise ValueError("Bars require a native N-dimensional recording")
+            self.image = None
+            return
+        self.asset = project.ref(cfg["asset"])
+        with Image.open(self.asset["path"]) as image:
+            self.image = image.convert("RGBA")
+        if cfg.get("crop_alpha", False):
+            box = self.image.getchannel("A").getbbox()
+            if box is None:
+                raise ValueError("Empty sprite")
+            self.image = self.image.crop(box)
+        self.width = integer(cfg["width"], "sprite width", minimum=1, maximum=16384)
+        self.center = tuple(number(x, "sprite center") for x in cfg["center"])
+        if len(self.center) != 2:
+            raise ValueError("Sprite center needs two coordinates")
+        self.atlas = cfg.get("atlas")
+        if self.atlas:
+            fields(self.atlas, {"columns", "rows", "count", "cycle_ticks", "phase_beats"}, "atlas")
+            cols = integer(self.atlas["columns"], "atlas columns", minimum=1)
+            rows = integer(self.atlas["rows"], "atlas rows", minimum=1)
+            integer(self.atlas["count"], "atlas count", minimum=1, maximum=cols * rows)
+            number(self.atlas["cycle_ticks"], "atlas cycle ticks", minimum=.0001)
+            number(self.atlas.get("phase_beats", 0), "atlas phase")
+            atlas_cell(self.image, columns=cols, rows=rows, index=0)
+
+    @lru_cache(maxsize=16)
+    def transformed(self, index, width, rotation):
+        im = self.image
+        if self.atlas:
+            im = atlas_cell(im, columns=self.atlas["columns"], rows=self.atlas["rows"], index=index)
+        im = im.resize((width, max(1, round(im.height * width / im.width))), Image.Resampling.LANCZOS)
+        im = im.rotate(rotation, Image.Resampling.BICUBIC, expand=True)
+        if trail := self.cfg.get("trail"):
+            fields(trail, {"offset", "opacity", "radius"}, "trail")
+            im = directional_trail(im, **trail)
+        return alpha_scaled(im, self.opacity)
+
+    def draw(self, image, ctx):
+        if not self.cfg.get("start_seconds", 0) <= ctx.source_seconds < self.cfg.get("end_seconds", math.inf):
+            return None
+        if "cue_labels" in self.cfg and (not ctx.cue or ctx.cue["text"] not in self.cfg["cue_labels"]):
+            return None
+        if self.kind == "bars":
+            values = self.motion.recording_values(ctx.source_seconds)
+            left, top, right, bottom = self.bounds
+            draw = ImageDraw.Draw(image)
+            mid = (top + bottom) / 2
+            draw.line((left, mid, right, mid), fill="#9ca4bc", width=1)
+            width = (right - left) / len(values)
+            if width < 2:
+                raise ValueError("Too many recording dimensions for the selected bar width")
+            for j, value in enumerate(values):
+                end = mid - value * (bottom - top) / 2
+                draw.rectangle((left + j * width, min(mid, end), left + (j + 1) * width - 1,
+                                max(mid, end)), fill="#76d4cf" if value >= 0 else "#edb56d")
+            return self.bounds
+        v = self.motion.sample(ctx.source_seconds, continuous_beat=ctx.beat) if self.motion else (0, 0, 0)
+        index = 0
+        if self.atlas:
+            phase = (ctx.beat + self.atlas.get("phase_beats", 0)) * 16 / self.atlas["cycle_ticks"]
+            index = math.floor((phase % 1) * self.atlas["count"])
+        width = max(1, round(self.width * (1 + v[self.axes["scale_axis"]] * self.mapping["scale"])))
+        im = self.transformed(index, width, round(v[self.axes["rotation_axis"]] * self.mapping["rotation"], 3))
+        x = round(self.center[0] + v[self.axes["x_axis"]] * self.mapping["dx"] - im.width / 2)
+        y = round(self.center[1] + v[self.axes["y_axis"]] * self.mapping["dy"] - im.height / 2)
+        bounds = transformed_bounds(im, x, y)
+        if not within(bounds, self.bounds):
+            raise ValueError(f"Frame {ctx.frame}: {self.id} transformed alpha {bounds} exceeds {self.bounds}")
+        image.alpha_composite(im, (x, y))
+        return bounds
+
+
+class Compositor:
+    def __init__(self, project, *, scene=None):
+        self.project, self.scene = project, scene
+        bg = project.data.get("background", {})
+        fields(bg, {"colour", "image", "fit"}, "background")
+        self.background = Image.new("RGBA", (project.width, project.height), bg.get("colour", "#101b2e"))
+        if "image" in bg:
+            ref = project.ref(bg["image"])
+            with Image.open(ref["path"]) as source:
+                source = source.convert("RGBA")
+            fit = bg.get("fit", "cover")
+            if fit == "cover":
+                source = ImageOps.fit(source, self.background.size, method=Image.Resampling.LANCZOS)
+            elif fit == "contain":
+                source = ImageOps.contain(source, self.background.size, method=Image.Resampling.LANCZOS)
+            else:
+                raise ValueError("Background fit must be cover or contain")
+            self.background.alpha_composite(source, ((project.width - source.width) // 2,
+                                                       (project.height - source.height) // 2))
+        self.lyrics, self.cues = EventTrack(project.lyrics), EventTrack(project.cues)
+        self.layers = [Sprite(project, cfg) for cfg in project.data.get("layers", [])]
+        ids = [x.id for x in self.layers]
+        if len(set(ids)) != len(ids):
+            raise ValueError("Layer ids must be unique")
+        self.caption = TextBlock(project, project.data["captions"], label="captions") if "lyrics" in project.data else None
+        self.lyric_art = {}
+        self.lyric_art_fallback = "text"
+        if art := project.data.get("lyric_art"):
+            fields(art, {"items", "placement", "fallback"}, "lyric art")
+            self.lyric_art_fallback = art.get("fallback", "error")
+            if self.lyric_art_fallback not in {"text", "error"}:
+                raise ValueError("Lyric art fallback must be text or error")
+            for i, item in enumerate(art["items"]):
+                fields(item, {"text", "asset"}, "lyric art item")
+                if item["text"] in self.lyric_art:
+                    raise ValueError("Duplicate lyric art text mapping")
+                self.lyric_art[item["text"]] = Sprite(project, dict(art["placement"],
+                                                                  id=f"lyric-art-{i}", asset=item["asset"]))
+            if self.lyric_art_fallback == "error":
+                missing = {e["text"] for e in project.lyrics if e["text"]} - set(self.lyric_art)
+                if missing:
+                    raise ValueError(f"Missing lyric artwork: {sorted(missing)}")
+        self.identity = []
+        for item in project.data.get("identity", []):
+            fields(item, {"text", "style"}, "identity")
+            self.identity.append((item["text"], TextBlock(project, item["style"], label="identity")))
+        self.extents, self.text_states = {}, {}
+
+    def frame(self, frame):
+        p = self.project
+        ctx = FrameContext(frame, frame / p.fps, p.source_time(frame), p.continuous_beat(frame),
+                           self.lyrics.at(frame), self.cues.at(frame))
+        image = self.background.copy()
+        if self.scene:
+            image = self.scene(image, ctx)
+            if image.size != self.background.size or image.mode != "RGBA":
+                raise ValueError("Custom scene hook must return frame-sized RGBA")
+        for layer in self.layers:
+            bounds = layer.draw(image, ctx)
+            if bounds:
+                previous = self.extents.get(layer.id, bounds)
+                self.extents[layer.id] = [min(bounds[0], previous[0]), min(bounds[1], previous[1]),
+                                         max(bounds[2], previous[2]), max(bounds[3], previous[3])]
+        text_bounds = []
+        for text, style in self.identity:
+            text_bounds.extend(style.draw(image, text))
+        if self.caption:
+            text = ctx.lyric["text"] if ctx.lyric else ""
+            art_layer = self.lyric_art.get(text)
+            if art_layer:
+                bounds = art_layer.draw(image, ctx)
+                if bounds:
+                    text_bounds.append(bounds)
+            elif self.caption.mode == "neighbours":
+                before, current, after = self.lyrics.neighbours(frame)
+                text = "\n".join((before["text"] if before else "", current["text"] if current else "",
+                                  after["text"] if after else ""))
+            if not art_layer:
+                text_bounds.extend(self.caption.draw(image, text))
+            self.text_states.setdefault(text, dict(first_frame=frame, bounds=text_bounds))
+        return image.convert("RGB"), ctx
+
+    def evidence(self):
+        return dict(transformed_alpha_extents=self.extents, text_states=self.text_states,
+                    motions={x.id: x.motion.evidence for x in [*self.layers, *self.lyric_art.values()] if x.motion},
+                    custom_scene=bool(self.scene))

framerudiments/demo.py

@@ -0,0 +1,68 @@
+"""Self-contained synthetic demonstration: no private songs or third-party artwork."""
+import math
+from pathlib import Path
+import struct
+import wave
+
+from PIL import Image, ImageDraw
+from dancerudiments_authoring.recording import Recording, RecordingClock, write_recording
+
+from .io import sha256, write_json
+
+
+def create_demo(directory, font, *, width=360, height=640):
+    directory = Path(directory).resolve()
+    directory.mkdir(parents=True, exist_ok=False)
+    font = Path(font).resolve()
+    if not font.is_file():
+        raise ValueError("Pass an installed font with --font")
+    rate = 48000
+    with wave.open(str(directory / "tone.wav"), "wb") as handle:
+        handle.setparams((2, 2, rate, 0, "NONE", "not compressed"))
+        data = bytearray()
+        for i in range(rate * 4):
+            t = i / rate
+            envelope = min(1, t / .02, (4 - t) / .02)
+            value = round(9000 * envelope * math.sin(2 * math.pi * 220 * t))
+            data.extend(struct.pack("<hh", value, value))
+        handle.writeframes(data)
+    sprite = Image.new("RGBA", (160, 160))
+    draw = ImageDraw.Draw(sprite)
+    draw.ellipse((20, 20, 140, 140), fill="#76d4cf", outline="#f9edca", width=5)
+    draw.line((50, 80, 70, 105, 115, 55), fill="#101b2e", width=12)
+    sprite.save(directory / "sprite.png")
+    (directory / "lyrics.lrc").write_text("[00:00.00]Signals into motion\n[00:01.25]Words into light\n"
+                                         "[00:02.50]Keep the clock in sight\n[00:03.75]\n", encoding="utf-8")
+    (directory / "sections.cue").write_text('FILE "tone.wav" WAVE\nTRACK 01 AUDIO\nTITLE "opening"\n'
+                                           'INDEX 01 00:00:00\nTRACK 02 AUDIO\nTITLE "closing"\nINDEX 01 00:02:00\n',
+                                           encoding="utf-8")
+    clock = RecordingClock(120, "synthetic demo oscillator", "confirmed", 0, "supplied", 0)
+    recording = Recording("demo_bands", ("low", "mid", "high", "air"),
+                          tuple(tuple(math.sin(i / 24 + j) for j in range(4)) for i in range(512)), clock)
+    write_recording(directory / "recording.json", recording)
+    def ref(name):
+        path = directory / name
+        return dict(path=name, sha256=sha256(path))
+    def box(a, b, c, d):
+        return [round(a * width), round(b * height), round(c * width), round(d * height)]
+    text_size = max(8, round(min(width * .078, height * .045)))
+    data = dict(schema="framerudiments.project.v1", title="FrameRudiments", artist="Synthetic demonstration",
+                purpose="short", width=width, height=height, fps=60,
+                audio=dict(source=ref("tone.wav"), sample_rate=rate, start_sample=0, end_sample=rate * 4,
+                           fade_seconds=.12),
+                clock=dict(bpm=120, authority="synthetic oscillator", status="synthetic", phase_status="supplied"),
+                font=dict(path=str(font), sha256=sha256(font)), lyrics=ref("lyrics.lrc"), cues=ref("sections.cue"),
+                background=dict(colour="#101b2e"),
+                identity=[dict(text="FrameRudiments", style=dict(box=box(.1, .13, .9, .23), font_size=text_size,
+                                                   min_font_size=max(6, text_size // 2), stroke=0, line_spacing=2))],
+                captions=dict(box=box(.12, .28, .88, .48), font_size=text_size,
+                              min_font_size=max(6, text_size // 2), stroke=0, line_spacing=2),
+                layers=[dict(id="native", asset=ref("sprite.png"), center=[width * .5, height * .65],
+                             width=round(min(width * .33, height * .22)), bounds=box(.1, .5, .9, .82),
+                             motion=dict(kind="named", pattern="bounce"),
+                             mapping=dict(dy=height * .035, y_axis=0)),
+                        dict(id="bands", type="bars", bounds=box(.15, .84, .85, .94),
+                             motion=dict(kind="recording", file=ref("recording.json")))],
+                notes="Synthetic audio and motion; no actual sung lyric or creative approval implied.")
+    write_json(directory / "project.json", data)
+    return directory / "project.json"

framerudiments/effects.py

@@ -0,0 +1,51 @@
+"""Reusable bounded raster operations extracted from the release compositors."""
+from PIL import Image, ImageChops, ImageFilter
+
+
+def alpha_scaled(image, opacity):
+    opacity = max(0.0, min(1.0, opacity))
+    result = image.copy()
+    result.putalpha(result.getchannel("A").point(lambda v: round(v * opacity)))
+    return result
+
+
+def transformed_bounds(image, x, y):
+    bounds = image.getchannel("A").getbbox()
+    return None if bounds is None else (x + bounds[0], y + bounds[1], x + bounds[2], y + bounds[3])
+
+
+def within(bounds, allowed):
+    return bounds is None or (bounds[0] >= allowed[0] and bounds[1] >= allowed[1]
+                              and bounds[2] <= allowed[2] and bounds[3] <= allowed[3])
+
+
+def directional_trail(image, *, offset=(0, 0), opacity=.2, radius=2):
+    """Same-pose trail avoids detached anatomy from a previous sprite pose."""
+    dx, dy = map(int, offset)
+    margin = int(radius * 3 + 2)
+    result = Image.new("RGBA", (image.width + abs(dx) + margin * 2,
+                                image.height + abs(dy) + margin * 2))
+    origin = (margin + max(0, -dx), margin + max(0, -dy))
+    trail = Image.new("RGBA", result.size)
+    trail.alpha_composite(alpha_scaled(image, opacity), (origin[0] + dx, origin[1] + dy))
+    result.alpha_composite(trail.filter(ImageFilter.GaussianBlur(radius)))
+    result.alpha_composite(image, origin)
+    return result
+
+
+def masked_overlay(image, mask, opacity=1.0):
+    result = alpha_scaled(image, opacity)
+    if mask.size != result.size:
+        raise ValueError("Overlay and mask dimensions must match")
+    result.putalpha(ImageChops.multiply(result.getchannel("A"), mask.convert("L")))
+    return result
+
+
+def atlas_cell(image, *, columns, rows, index):
+    if image.width % columns or image.height % rows:
+        raise ValueError("Atlas cells must divide the exact sheet dimensions")
+    if not 0 <= index < columns * rows:
+        raise ValueError("Atlas index outside sheet")
+    width, height = image.width // columns, image.height // rows
+    x, y = index % columns * width, index // columns * height
+    return image.crop((x, y, x + width, y + height))

framerudiments/encoding.py

@@ -0,0 +1,111 @@
+"""One FFmpeg boundary for exact audio slices, repeats, H.264/AAC and decoded QA."""
+from fractions import Fraction
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+
+def binaries(ffmpeg=None, ffprobe=None):
+    ffmpeg = ffmpeg or os.environ.get("FRAMERUDIMENTS_FFMPEG") or shutil.which("ffmpeg")
+    if not ffmpeg:
+        raise ValueError("Set FRAMERUDIMENTS_FFMPEG or pass --ffmpeg")
+    ffmpeg = str(Path(ffmpeg).resolve())
+    ffprobe = ffprobe or os.environ.get("FRAMERUDIMENTS_FFPROBE")
+    if not ffprobe:
+        sibling = Path(ffmpeg).with_name("ffprobe.exe" if os.name == "nt" else "ffprobe")
+        ffprobe = str(sibling) if sibling.is_file() else shutil.which("ffprobe")
+    if not ffprobe or not Path(ffprobe).is_file() or not Path(ffmpeg).is_file():
+        raise ValueError("Both FFmpeg and ffprobe must be available")
+    return ffmpeg, str(Path(ffprobe).resolve())
+
+
+def probe(path, ffprobe, *, count=False):
+    args = [ffprobe, "-v", "error", "-show_streams", "-show_format", "-of", "json"]
+    if count:
+        args += ["-count_frames"]
+    return json.loads(subprocess.check_output([*args, str(path)], encoding="utf-8"))
+
+
+def validate_audio(project, ffprobe):
+    info = probe(project.audio_ref["path"], ffprobe)
+    audio = next(s for s in info["streams"] if s["codec_type"] == "audio")
+    if int(audio["sample_rate"]) != project.sample_rate:
+        raise ValueError("Configured sample rate differs from source audio")
+    duration = Fraction(str(audio.get("duration", info["format"]["duration"])))
+    if "duration_ts" in audio:
+        duration = int(audio["duration_ts"]) * Fraction(audio["time_base"])
+    if project.end_sample > duration * project.sample_rate:
+        raise ValueError("Excerpt exceeds source audio extent")
+    return info
+
+
+def command(project, output, ffmpeg, *, preset="fast", crf=20):
+    if preset not in {"ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow"}:
+        raise ValueError("Unsupported encoder preset")
+    if not isinstance(crf, int) or not 0 <= crf <= 51:
+        raise ValueError("CRF must be an integer in [0,51]")
+    p = project
+    filters = [f"atrim=start_sample={p.start_sample}:end_sample={p.end_sample}", "asetpts=PTS-STARTPTS"]
+    if p.repeats > 1:
+        filters += [f"aloop=loop={p.repeats - 1}:size={p.end_sample - p.start_sample}"]
+    if p.fade:
+        filters += [f"afade=t=in:st=0:d={p.fade:.12f}:curve=qsin",
+                    f"afade=t=out:st={float(p.duration) - p.fade:.12f}:d={p.fade:.12f}:curve=qsin"]
+    return [ffmpeg, "-n", "-hide_banner", "-loglevel", "warning", "-f", "rawvideo",
+            "-pixel_format", "rgb24", "-video_size", f"{p.width}x{p.height}",
+            "-framerate", str(p.fps), "-i", "pipe:0", "-i", p.audio_ref["path"],
+            "-map", "0:v:0", "-map", "1:a:0", "-af", ",".join(filters),
+            "-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-threads", "4",
+            "-pix_fmt", "yuv420p", "-fps_mode", "cfr", "-color_primaries", "bt709",
+            "-color_trc", "bt709", "-colorspace", "bt709", "-c:a", "aac", "-b:a", "256k",
+            "-ar", str(p.sample_rate), "-movflags", "+faststart", str(output)]
+
+
+def verify(path, project, ffmpeg, ffprobe):
+    info = probe(path, ffprobe, count=True)
+    video = next(s for s in info["streams"] if s["codec_type"] == "video")
+    audio = next(s for s in info["streams"] if s["codec_type"] == "audio")
+    if (int(video["nb_read_frames"]) != project.frame_count or
+        Fraction(video["avg_frame_rate"]) != project.fps or
+        Fraction(video["r_frame_rate"]) != project.fps or video["codec_name"] != "h264" or
+        video["pix_fmt"] != "yuv420p" or [video["width"], video["height"]] != [project.width, project.height]):
+        raise ValueError("Encoded video does not match the prepared frame contract")
+    if audio["codec_name"] != "aac" or int(audio["sample_rate"]) != project.sample_rate:
+        raise ValueError("Encoded audio contract differs")
+    duration_error = float(audio["duration"]) - float(project.duration)
+    if abs(duration_error) > max(2 / project.sample_rate, .002):
+        raise ValueError(f"Encoded audio programme length differs by {duration_error:.6f}s")
+    # Inspect decoded timestamps, not only nominal container rate labels.
+    timestamp_command = [ffprobe, "-v", "error", "-select_streams", "v:0", "-show_entries",
+                         "frame=best_effort_timestamp_time", "-of", "csv=p=0", str(path)]
+    completed = subprocess.run(timestamp_command, capture_output=True, text=True, check=True)
+    timestamps = [float(line.split(",")[0]) for line in completed.stdout.splitlines() if line.split(",")[0].strip()]
+    if len(timestamps) != project.frame_count or any(abs(t - i / project.fps) > .000002
+                                                    for i, t in enumerate(timestamps)):
+        raise ValueError("Decoded frame timestamps are not constant-rate from zero")
+    subprocess.run([ffmpeg, "-v", "error", "-xerror", "-i", str(path), "-f", "null", "-"],
+                   check=True, capture_output=True)
+    # Verify actual MP4 atom order for fast start.
+    atoms = []
+    with Path(path).open("rb") as handle:
+        while header := handle.read(8):
+            if len(header) != 8:
+                raise ValueError("Truncated MP4 atom")
+            size, kind = int.from_bytes(header[:4], "big"), header[4:].decode("ascii")
+            consumed = 8
+            if size == 1:
+                size = int.from_bytes(handle.read(8), "big")
+                consumed = 16
+            atoms.append(kind)
+            if size == 0:
+                break
+            if size < consumed:
+                raise ValueError("Invalid MP4 atom size")
+            handle.seek(size - consumed, 1)
+    if "moov" not in atoms or "mdat" not in atoms or atoms.index("moov") > atoms.index("mdat"):
+        raise ValueError("MP4 is missing fast-start atom order")
+    return dict(probe=info, full_decode="passed", decoded_timestamps="CFR from zero; all frames checked",
+                audio_duration_error_seconds=duration_error, mp4_atoms=atoms,
+                listening_approved=False, platform_safe_zone_verified=False)