framerudiments 0.4.6__tar.gz → 0.4.7__tar.gz

{framerudiments-0.4.6/src/framerudiments.egg-info → framerudiments-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.4.6
+Version: 0.4.7
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -121,6 +121,7 @@ framerudiments --version
 framerudiments demo demo --font /path/to/a/font.ttf
 framerudiments plan demo/project.json --output demo-plan.json
 framerudiments preflight demo/project.json --output preflight --ffmpeg /path/to/ffmpeg
+framerudiments preflight demo/project.json --output bounded-preflight --max-frames 3 --ffmpeg /path/to/ffmpeg
 framerudiments render demo/project.json --output render --ffmpeg /path/to/ffmpeg
 ```
 
@@ -130,6 +131,12 @@ ffprobe. Environment alternatives are `FRAMERUDIMENTS_FFMPEG` and
 font or FFmpeg location is hardcoded into the engine. The synthetic demo creates
 its own tone, sprite, LRC, CUE and four-dimensional recording.
 
+For expensive long projects, `preflight --max-frames N` validates a bounded
+sequential prefix and records the exact incomplete scope in `manifest.json`.
+This preserves stateful particles and feedback inside the prefix without paying
+for a complete unencoded pass before the complete encoded render. It never
+claims later frames were checked. See [bounded preflight](docs/bounded-preflight.md).
+
 ## Capabilities
 
 * Portrait, landscape and square frame-addressed Pillow composition, at native

{framerudiments-0.4.6 → framerudiments-0.4.7}/README.md

@@ -90,6 +90,7 @@ framerudiments --version
 framerudiments demo demo --font /path/to/a/font.ttf
 framerudiments plan demo/project.json --output demo-plan.json
 framerudiments preflight demo/project.json --output preflight --ffmpeg /path/to/ffmpeg
+framerudiments preflight demo/project.json --output bounded-preflight --max-frames 3 --ffmpeg /path/to/ffmpeg
 framerudiments render demo/project.json --output render --ffmpeg /path/to/ffmpeg
 ```
 
@@ -99,6 +100,12 @@ ffprobe. Environment alternatives are `FRAMERUDIMENTS_FFMPEG` and
 font or FFmpeg location is hardcoded into the engine. The synthetic demo creates
 its own tone, sprite, LRC, CUE and four-dimensional recording.
 
+For expensive long projects, `preflight --max-frames N` validates a bounded
+sequential prefix and records the exact incomplete scope in `manifest.json`.
+This preserves stateful particles and feedback inside the prefix without paying
+for a complete unencoded pass before the complete encoded render. It never
+claims later frames were checked. See [bounded preflight](docs/bounded-preflight.md).
+
 ## Capabilities
 
 * Portrait, landscape and square frame-addressed Pillow composition, at native

{framerudiments-0.4.6 → framerudiments-0.4.7}/RELEASE_NOTES.md

@@ -1,3 +1,21 @@
+# FrameRudiments 0.4.7
+
+- `preflight --max-frames N` composes a declared sequential prefix for expensive
+  long projects instead of forcing a complete unencoded pass before rendering.
+- The manifest records full versus bounded scope, frames rendered, total frames,
+  sequential-state behaviour and the explicit later-frame validation limit.
+- The final rendered file still receives complete decode, CFR, frame-count,
+  audio and encoded-checkpoint verification; bounded preflight does not weaken
+  or relabel final technical QA.
+- Focused regression coverage preserves default full-preflight behaviour, exact
+  prefix boundaries, final-prefix QA capture and fail-closed limits.
+- Wrapped-word layout coverage now follows visual reading order across current
+  Pillow text metrics instead of assuming every word remains on one row.
+
+![Generated workload illustration for bounded preflight](docs/media/bounded-preflight.svg)
+
+Generated explanatory diagram; not a benchmark or rendered campaign frame.
+
 # FrameRudiments 0.4.6
 
 - Encoding now accepts the complete named libx264 preset range: `ultrafast`,

framerudiments-0.4.7/docs/bounded-preflight.md

@@ -0,0 +1,45 @@
+# Bounded sequential preflight
+
+`framerudiments preflight` remains a full, unencoded composition pass by
+default. For a long or unusually expensive project, `--max-frames N` composes
+only the first `N` frames in order:
+
+```sh
+framerudiments preflight project.json --output preflight-prefix --max-frames 3
+```
+
+The mode is a cost and failure-surface check. It verifies pinned inputs,
+audio identity, project construction, sequential state creation, the declared
+prefix and cleanup. It saves frame zero, ordinary checkpoints encountered in
+the prefix and the last rendered prefix frame. `manifest.json` records:
+
+```json
+{
+  "preflight_scope": {
+    "mode": "bounded-prefix",
+    "frames_rendered": 3,
+    "total_frames": 15850,
+    "complete": false,
+    "sequential": true,
+    "note": "Only the declared sequential prefix was composed; later frames remain unvalidated."
+  }
+}
+```
+
+## Why the prefix is sequential
+
+Feedback visualisers, emitters and historical effects can depend on every
+preceding frame. Randomly drawing distant checkpoints would reset or omit that
+history and could create misleading evidence. The bounded mode therefore starts
+at frame zero and advances normally. It does not describe later checkpoints,
+the ending, full cleanup behaviour or the encoded result.
+
+Run the complete `render` afterward. The renderer still composes every frame,
+encodes the soundtrack, extracts all encoded QA checkpoints and verifies full
+decode, constant frame rate, exact frame count, timestamps, dimensions, audio
+shape and duration. Creative review and attended listening remain separate.
+
+![Generated comparison of full and bounded preflight workloads](media/bounded-preflight.svg)
+
+Generated explanatory diagram. The short amber prefix represents frames that
+were actually composed; the outlined remainder is explicitly unvalidated.

framerudiments-0.4.7/docs/media/bounded-preflight.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="360" viewBox="0 0 960 360" role="img" aria-labelledby="title desc">
+  <title id="title">Full preflight compared with bounded sequential preflight</title>
+  <desc id="desc">A full preflight composes every frame before rendering. A bounded preflight composes a short sequential prefix and labels the remainder unvalidated.</desc>
+  <rect width="960" height="360" fill="#16051f"/>
+  <text x="48" y="55" fill="#fff2cf" font-family="sans-serif" font-size="28" font-weight="700">Generated workflow illustration</text>
+  <text x="48" y="105" fill="#fff2cf" font-family="sans-serif" font-size="22">Full preflight</text>
+  <rect x="250" y="78" width="650" height="38" rx="19" fill="#ffb52e"/>
+  <text x="575" y="104" fill="#351300" text-anchor="middle" font-family="sans-serif" font-size="17" font-weight="700">every frame composed without encoding</text>
+  <path d="M575 126v45" stroke="#ffcf62" stroke-width="4" marker-end="url(#arrow)"/>
+  <text x="48" y="201" fill="#fff2cf" font-family="sans-serif" font-size="22">Complete render</text>
+  <rect x="250" y="174" width="650" height="38" rx="19" fill="#ff7a28"/>
+  <text x="575" y="200" fill="#351300" text-anchor="middle" font-family="sans-serif" font-size="17" font-weight="700">every frame composed again and encoded</text>
+  <text x="48" y="279" fill="#fff2cf" font-family="sans-serif" font-size="22">Bounded preflight</text>
+  <rect x="250" y="252" width="92" height="38" rx="19" fill="#ffb52e"/>
+  <rect x="342" y="252" width="558" height="38" rx="19" fill="none" stroke="#9c759f" stroke-width="3" stroke-dasharray="10 10"/>
+  <text x="296" y="278" fill="#351300" text-anchor="middle" font-family="sans-serif" font-size="16" font-weight="700">prefix</text>
+  <text x="621" y="278" fill="#d8b9dc" text-anchor="middle" font-family="sans-serif" font-size="17">later frames explicitly unvalidated</text>
+  <defs><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#ffcf62"/></marker></defs>
+</svg>

{framerudiments-0.4.6 → framerudiments-0.4.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "framerudiments"
-version = "0.4.6"
+version = "0.4.7"
 description = "Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence."
 requires-python = ">=3.11"
 readme = "README.md"

{framerudiments-0.4.6 → framerudiments-0.4.7}/src/framerudiments/__init__.py

@@ -1,6 +1,6 @@
 """Offline frame composition on a traceable musical clock."""
 
-__version__ = "0.4.6"
+__version__ = "0.4.7"
 
 from .project import Project
 from .render import render, preflight

{framerudiments-0.4.6 → framerudiments-0.4.7}/src/framerudiments/cli.py

@@ -76,7 +76,13 @@ def main(argv=None):
         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":
+        if name == "preflight":
+            item.add_argument(
+                "--max-frames",
+                type=int,
+                help="Compose only this many initial sequential frames; later frames remain unvalidated",
+            )
+        else:
             item.add_argument("--preset", default="fast")
             item.add_argument("--crf", type=int, default=20)
     args = parser.parse_args(argv)
@@ -161,7 +167,11 @@ def main(argv=None):
             print(output)
         else:
             runner = preflight if args.command == "preflight" else render
-            extra = {"preset": args.preset, "crf": args.crf} if args.command == "render" else {}
+            extra = (
+                {"preset": args.preset, "crf": args.crf}
+                if args.command == "render"
+                else {"max_frames": args.max_frames}
+            )
             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

{framerudiments-0.4.6 → framerudiments-0.4.7}/src/framerudiments/render.py

@@ -107,9 +107,38 @@ def _prepare(project, output, ffmpeg, ffprobe, scene, renderers):
     return project, output, ffmpeg, ffprobe, compositor
 
 
-def preflight(project, output, *, ffmpeg=None, ffprobe=None, scene=None, renderers=None):
-    p, out, ffmpeg, ffprobe, compositor = _prepare(project, output, ffmpeg, ffprobe, scene, renderers)
-    selected = set(checkpoints(p))
+def preflight(
+    project,
+    output,
+    *,
+    ffmpeg=None,
+    ffprobe=None,
+    scene=None,
+    renderers=None,
+    max_frames=None,
+):
+    p = Project.load(project) if not isinstance(project, Project) else project
+    if max_frames is None:
+        frame_count = p.frame_count
+    elif type(max_frames) is not int or not 1 <= max_frames <= p.frame_count:
+        raise ValueError(f"Preflight max_frames must be an integer in [1,{p.frame_count}]")
+    else:
+        frame_count = max_frames
+    p, out, ffmpeg, ffprobe, compositor = _prepare(p, output, ffmpeg, ffprobe, scene, renderers)
+    selected = {frame for frame in checkpoints(p) if frame < frame_count}
+    selected.add(frame_count - 1)
+    scope = dict(
+        mode="full" if frame_count == p.frame_count else "bounded-prefix",
+        frames_rendered=frame_count,
+        total_frames=p.frame_count,
+        complete=frame_count == p.frame_count,
+        sequential=True,
+        note=(
+            "All project frames were composed."
+            if frame_count == p.frame_count
+            else "Only the declared sequential prefix was composed; later frames remain unvalidated."
+        ),
+    )
     effects = None
     try:
         effects = (
@@ -118,7 +147,7 @@ def preflight(project, output, *, ffmpeg=None, ffprobe=None, scene=None, rendere
             else None
         )
         with (out / "rudiment-analysis.jsonl").open("w", encoding="utf-8") as analysis:
-            for n in range(p.frame_count):
+            for n in range(frame_count):
                 image, context = compositor.frame(n, apply_quality=False)
                 if effects:
                     if n in selected:
@@ -141,10 +170,15 @@ def preflight(project, output, *, ffmpeg=None, ffprobe=None, scene=None, rendere
         p.verify_inputs()
         result = dict(
             p.summary(),
+            preflight_scope=scope,
             composition=compositor.evidence(),
             full_frame_effects=effects.evidence() if effects else None,
             analysis_sidecar=_sidecar(out),
-            state="preflight passed; no encoded video",
+            state=(
+                "full preflight passed; no encoded video"
+                if scope["complete"]
+                else "bounded-prefix preflight passed; later frames unvalidated; no encoded video"
+            ),
         )
         write_json(out / "manifest.json", result)
         return result

{framerudiments-0.4.6 → framerudiments-0.4.7/src/framerudiments.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.4.6
+Version: 0.4.7
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -121,6 +121,7 @@ framerudiments --version
 framerudiments demo demo --font /path/to/a/font.ttf
 framerudiments plan demo/project.json --output demo-plan.json
 framerudiments preflight demo/project.json --output preflight --ffmpeg /path/to/ffmpeg
+framerudiments preflight demo/project.json --output bounded-preflight --max-frames 3 --ffmpeg /path/to/ffmpeg
 framerudiments render demo/project.json --output render --ffmpeg /path/to/ffmpeg
 ```
 
@@ -130,6 +131,12 @@ ffprobe. Environment alternatives are `FRAMERUDIMENTS_FFMPEG` and
 font or FFmpeg location is hardcoded into the engine. The synthetic demo creates
 its own tone, sprite, LRC, CUE and four-dimensional recording.
 
+For expensive long projects, `preflight --max-frames N` validates a bounded
+sequential prefix and records the exact incomplete scope in `manifest.json`.
+This preserves stateful particles and feedback inside the prefix without paying
+for a complete unencoded pass before the complete encoded render. It never
+claims later frames were checked. See [bounded preflight](docs/bounded-preflight.md).
+
 ## Capabilities
 
 * Portrait, landscape and square frame-addressed Pillow composition, at native

{framerudiments-0.4.6 → framerudiments-0.4.7}/src/framerudiments.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ docs/FrameRudiments-PATCH_WORKFLOW.md
 docs/annular-modulation.md
 docs/authoring-workspace.md
 docs/beat-alignment.md
+docs/bounded-preflight.md
 docs/controlled-audio-response.md
 docs/expanded-effects.md
 docs/extraction.md
@@ -45,6 +46,7 @@ docs/workflow-media.md
 docs/media/beat-alignment-evidence.json
 docs/media/beat-alignment.mp4
 docs/media/beat-alignment.png
+docs/media/bounded-preflight.svg
 docs/media/demo-transcript.md
 docs/media/effects-pipeline.svg
 docs/media/full-frame-comparison.png

{framerudiments-0.4.6 → framerudiments-0.4.7}/tests/test_pipeline.py

@@ -135,3 +135,52 @@ def test_custom_scene_hook_and_preflight(demo, tmp_path):
     assert calls == list(range(240))
     assert result["composition"]["custom_scene"]
     assert "no encoded" in result["state"]
+    assert result["preflight_scope"] == {
+        "mode": "full",
+        "frames_rendered": 240,
+        "total_frames": 240,
+        "complete": True,
+        "sequential": True,
+        "note": "All project frames were composed.",
+    }
+
+    calls.clear()
+    bounded = preflight(demo, tmp_path / "bounded-preflight", scene=scene, max_frames=3)
+    assert calls == [0, 1, 2]
+    assert bounded["preflight_scope"] == {
+        "mode": "bounded-prefix",
+        "frames_rendered": 3,
+        "total_frames": 240,
+        "complete": False,
+        "sequential": True,
+        "note": "Only the declared sequential prefix was composed; later frames remain unvalidated.",
+    }
+    assert "later frames unvalidated" in bounded["state"]
+    assert (tmp_path / "bounded-preflight" / "qa" / "source-00000002.png").exists()
+
+
+@pytest.mark.parametrize("limit", [0, -1, 241, 1.5, True])
+def test_bounded_preflight_rejects_invalid_frame_limit(demo, tmp_path, limit):
+    with pytest.raises(ValueError, match="Preflight max_frames"):
+        preflight(demo, tmp_path / f"bad-preflight-{limit}", max_frames=limit)
+
+
+def test_cli_forwards_bounded_preflight_limit(monkeypatch, capsys):
+    from framerudiments import cli
+
+    received = {}
+
+    def fake_preflight(project, output, **kwargs):
+        received.update(project=project, output=output, **kwargs)
+        return {"state": "bounded-prefix preflight passed", "frames": 240}
+
+    monkeypatch.setattr(cli, "preflight", fake_preflight)
+    assert cli.main(["preflight", "project.json", "--output", "out", "--max-frames", "3"]) == 0
+    assert received == {
+        "project": "project.json",
+        "output": "out",
+        "ffmpeg": None,
+        "ffprobe": None,
+        "max_frames": 3,
+    }
+    assert '"state": "bounded-prefix preflight passed"' in capsys.readouterr().out

{framerudiments-0.4.6 → framerudiments-0.4.7}/tests/test_rich_subtitles.py

@@ -199,7 +199,8 @@ def test_word_centres_follow_wrapped_text_layout_and_stay_in_box(project):
     centres = word_centres(text, "Lights follow every word")
     assert len(centres) == 4
     assert all(text.box[0] <= x <= text.box[2] for x, _ in centres)
-    assert all(a[0] < b[0] for a, b in zip(centres, centres[1:]))
+    assert all(a[1] <= b[1] for a, b in zip(centres, centres[1:]))
+    assert all(a[0] < b[0] for a, b in zip(centres, centres[1:]) if a[1] == b[1])
 
 
 def test_rich_highlight_can_tint_single_word_without_destroying_gradients(project):