framerudiments 0.1.3__tar.gz → 0.2.0__tar.gz

{framerudiments-0.1.3 → framerudiments-0.2.0}/MANIFEST.in

@@ -1,5 +1,7 @@
 include README.md LICENSE AGENTS.md
-recursive-include docs *.md
+recursive-include docs *.md *.png *.svg *.json *.mp4
 recursive-include tests *.py
 
 recursive-include integration *.py
+
+prune models

{framerudiments-0.1.3/src/framerudiments.egg-info → framerudiments-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.1.3
+Version: 0.2.0
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -29,6 +29,19 @@ FrameRudiments renders Shorts, Canvas-style clips and full lyric visualisers
 from one traceable timeline. It is the offline Python renderer in the
 [DanceFlow ecosystem](https://kieransimkin.co.uk/danceflow/).
 
+**0.2.0** accepts source-bound StemLab BPM/first-beat readings through
+`clock.beat_alignment`. Procedural motion follows the fractional beat phase
+after excerpt/repeat mapping. Audio, lyric/cue timestamps and captured
+recordings retain their original source clock. See [beat alignment](docs/beat-alignment.md).
+
+![Actual encoded FrameRudiments 0.2.0 synthetic example with original and aligned movement side by side, source-timed captions and recorded bands](docs/media/beat-alignment.png)
+
+[Play the four-second demonstration](docs/media/beat-alignment.mp4): original
+120 BPM clicks start at 0.125 seconds; the right movement uses the -16 pip
+reading. Text and recorded bands keep source time. This synthetic example
+demonstrates clock composition; it does not establish song-analysis accuracy.
+[Encoded-frame verification and hashes](docs/media/beat-alignment-evidence.json).
+
 It consolidates the shared Python/Pillow/FFmpeg mechanisms developed across
 the existing Gilt Trip, Blame Putin, Clay, Paper Dreams, Free Danny Tommo,
 Silly Sausage Britain and Moderate or Good renderers. Release-specific artwork,
@@ -172,8 +185,8 @@ analysis outputs into the source distribution.
 
 ## Source, contribution and releases
 
-[Canonical repository](https://github.com/kieransimkin/FrameRudiments) ·
-[Python package](https://pypi.org/project/framerudiments/) ·
+[Canonical repository](https://github.com/kieransimkin/FrameRudiments) ·
+[Python package](https://pypi.org/project/framerudiments/) ·
 [Issues and improvements](https://github.com/kieransimkin/FrameRudiments/issues)
 
 Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing the engine. Improvements
@@ -213,3 +226,19 @@ Optional runtime setup is explicit; the base renderer still works without Node,
 a browser or projectM. Feedback is sequential, and GPU output can vary by driver.
 Inspect processed/encoded glyphs and safe zones; pre-effect text bounds cannot
 prove final legibility.
+
+Version 0.1.4 preserves portrait geometry in pinned projectM legacy presets through a recorded square overscan/crop mapping; the upstream engine remains unmodified. Neutral portrait/landscape/square mapping is tested for both backends.
+
+![Actual synthetic frame before and after both visualisers](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-comparison.png)
+
+Actual FrameRudiments 0.1.4 candidate output: timed captions and native moving
+sprites/atlas before composition effects (left) and after both real engines
+(right). Synthetic oscillator audio and example words; this is a software demo.
+[Play the four-second demonstration](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-demo.mp4)
+and [read its transcript](https://github.com/kieransimkin/FrameRudiments/blob/v0.1.4/docs/media/demo-transcript.md).
+Playback is user-controlled; no automatic media playback is required.
+
+![Generated processing-order illustration; not a screenshot](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/effects-pipeline.svg)
+
+Generated vector illustration of the processing order. The comparison above
+and linked video are captured renderer output; the diagram is explanatory.

{framerudiments-0.1.3 → framerudiments-0.2.0}/README.md

@@ -4,6 +4,19 @@ FrameRudiments renders Shorts, Canvas-style clips and full lyric visualisers
 from one traceable timeline. It is the offline Python renderer in the
 [DanceFlow ecosystem](https://kieransimkin.co.uk/danceflow/).
 
+**0.2.0** accepts source-bound StemLab BPM/first-beat readings through
+`clock.beat_alignment`. Procedural motion follows the fractional beat phase
+after excerpt/repeat mapping. Audio, lyric/cue timestamps and captured
+recordings retain their original source clock. See [beat alignment](docs/beat-alignment.md).
+
+![Actual encoded FrameRudiments 0.2.0 synthetic example with original and aligned movement side by side, source-timed captions and recorded bands](docs/media/beat-alignment.png)
+
+[Play the four-second demonstration](docs/media/beat-alignment.mp4): original
+120 BPM clicks start at 0.125 seconds; the right movement uses the -16 pip
+reading. Text and recorded bands keep source time. This synthetic example
+demonstrates clock composition; it does not establish song-analysis accuracy.
+[Encoded-frame verification and hashes](docs/media/beat-alignment-evidence.json).
+
 It consolidates the shared Python/Pillow/FFmpeg mechanisms developed across
 the existing Gilt Trip, Blame Putin, Clay, Paper Dreams, Free Danny Tommo,
 Silly Sausage Britain and Moderate or Good renderers. Release-specific artwork,
@@ -147,8 +160,8 @@ analysis outputs into the source distribution.
 
 ## Source, contribution and releases
 
-[Canonical repository](https://github.com/kieransimkin/FrameRudiments) ·
-[Python package](https://pypi.org/project/framerudiments/) ·
+[Canonical repository](https://github.com/kieransimkin/FrameRudiments) ·
+[Python package](https://pypi.org/project/framerudiments/) ·
 [Issues and improvements](https://github.com/kieransimkin/FrameRudiments/issues)
 
 Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing the engine. Improvements
@@ -188,3 +201,19 @@ Optional runtime setup is explicit; the base renderer still works without Node,
 a browser or projectM. Feedback is sequential, and GPU output can vary by driver.
 Inspect processed/encoded glyphs and safe zones; pre-effect text bounds cannot
 prove final legibility.
+
+Version 0.1.4 preserves portrait geometry in pinned projectM legacy presets through a recorded square overscan/crop mapping; the upstream engine remains unmodified. Neutral portrait/landscape/square mapping is tested for both backends.
+
+![Actual synthetic frame before and after both visualisers](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-comparison.png)
+
+Actual FrameRudiments 0.1.4 candidate output: timed captions and native moving
+sprites/atlas before composition effects (left) and after both real engines
+(right). Synthetic oscillator audio and example words; this is a software demo.
+[Play the four-second demonstration](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-demo.mp4)
+and [read its transcript](https://github.com/kieransimkin/FrameRudiments/blob/v0.1.4/docs/media/demo-transcript.md).
+Playback is user-controlled; no automatic media playback is required.
+
+![Generated processing-order illustration; not a screenshot](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/effects-pipeline.svg)
+
+Generated vector illustration of the processing order. The comparison above
+and linked video are captured renderer output; the diagram is explanatory.

framerudiments-0.2.0/docs/beat-alignment.md

@@ -0,0 +1,56 @@
+# Beat alignment from saved StemLab evidence
+
+![Actual FrameRudiments 0.2.0 encoded example: original and aligned native movement with source-time captions and recorded bands](media/beat-alignment.png)
+
+[Play the four-second example](media/beat-alignment.mp4). Original synthetic
+120 BPM clicks begin at 0.125 seconds. The left native bounce shows the original
+grid; the right follows the -16 pip reading. The bands retain their recording
+clock. Text changes at the original LRC times: “Signals into motion” at 0,
+“Words into light” at 1.25, “Keep the clock in sight” at 2.50, then clears at
+3.75 seconds. The synthetic text is a caption fixture, not sung lyrics.
+[Encoded verification, source identity and hashes](media/beat-alignment-evidence.json).
+
+Generate a source-bound reading from saved StemLab evidence, reviewing canonical,
+combined, fitted and half/double-time interpretations and individual detectors:
+
+```sh
+stemlab beat-offset RESULTS --output NEW --audio EXACT-MASTER.wav \
+  --alignment-analysis consensus --alignment-bpm-basis combined_fit
+```
+
+Use `canonical` only when canonical BPM has an established authority. Retain the
+full comparison report; a good beat-grid fit is not a listening or downbeat
+confirmation. A normal half-time reading does not mean a detector failed.
+
+Pin the resulting file exactly as every other project input:
+
+```json
+"clock": {
+  "authority": "Reviewed StemLab consensus constant-grid fit",
+  "status": "estimated",
+  "phase_status": "estimated",
+  "beat_alignment": {"path": "beat-alignment.json", "sha256": "EXACT_FILE_SHA256"}
+}
+```
+
+The adapter validates the master SHA-256, source sample rate/frame bounds,
+64-pip units, detector/report identities and exact rational clock equation.
+An explicit BPM must agree. Do not also supply `origin` or `beat_grid`; the
+reading owns this clock. An estimated BPM cannot become `confirmed` through
+project metadata, and phase authority stays separate.
+
+The existing BeatClock uses the first source beat as its origin. At that instant
+the procedural clock is pip zero; before it, pips can be negative. Excerpts and
+repeats map source time first and apply phase once. Keep the original master,
+LRC, CUE and captured recording clocks unchanged. A recording's captured beat
+zero and integer samples remain authoritative, including Fourier dimensions.
+
+Missing, mismatched or poor evidence remains a review hold. A constant-grid
+reading is not proof that a variable-tempo song fits one BPM. Existing projects
+without a reading retain their explicit clock and report unverified phase when
+no phase status was supplied.
+
+Reproduce the actual fixture with `python examples/beat-alignment/generate.py
+NEW-DIRECTORY --font /path/to/font.ttf`, then use normal `plan`, `preflight` and
+`render` commands. Keep technical encoded QA separate from attended listening,
+creative approval and any platform publication.

framerudiments-0.2.0/docs/media/beat-alignment-evidence.json

@@ -0,0 +1,173 @@
+{
+  "context": "Actual FrameRudiments 0.2.0 encoded synthetic clock-composition example",
+  "frames": 240,
+  "fps": 60,
+  "dimensions": [
+    360,
+    640
+  ],
+  "duration_seconds": 4,
+  "source_audio_sha256": "83e47effac0c8cf6c6c8c70f3babec9b55f61fcea0ba1a97822528e85b8ffe8c",
+  "first_beat_seconds": 0.125,
+  "offset_pips": -16,
+  "pips_per_beat": 64,
+  "screenshot_frame": 75,
+  "screenshot_source_seconds": 1.25,
+  "verification": {
+    "probe": {
+      "streams": [
+        {
+          "index": 0,
+          "codec_name": "h264",
+          "codec_long_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
+          "profile": "High",
+          "codec_type": "video",
+          "codec_tag_string": "avc1",
+          "codec_tag": "0x31637661",
+          "mime_codec_string": "avc1.64001f",
+          "width": 360,
+          "height": 640,
+          "coded_width": 368,
+          "coded_height": 640,
+          "has_b_frames": 2,
+          "pix_fmt": "yuv420p",
+          "level": 31,
+          "color_range": "tv",
+          "color_space": "bt709",
+          "chroma_location": "left",
+          "field_order": "progressive",
+          "refs": 4,
+          "is_avc": "true",
+          "nal_length_size": "4",
+          "id": "0x1",
+          "r_frame_rate": "60/1",
+          "avg_frame_rate": "60/1",
+          "time_base": "1/15360",
+          "start_pts": 0,
+          "start_time": "0.000000",
+          "duration_ts": 61440,
+          "duration": "4.000000",
+          "bit_rate": "108766",
+          "bits_per_raw_sample": "8",
+          "nb_frames": "240",
+          "nb_read_frames": "240",
+          "extradata_size": 49,
+          "disposition": {
+            "default": 1,
+            "dub": 0,
+            "original": 0,
+            "comment": 0,
+            "lyrics": 0,
+            "karaoke": 0,
+            "forced": 0,
+            "hearing_impaired": 0,
+            "visual_impaired": 0,
+            "clean_effects": 0,
+            "attached_pic": 0,
+            "timed_thumbnails": 0,
+            "non_diegetic": 0,
+            "captions": 0,
+            "descriptions": 0,
+            "metadata": 0,
+            "dependent": 0,
+            "still_image": 0,
+            "multilayer": 0
+          },
+          "tags": {
+            "language": "und",
+            "handler_name": "VideoHandler",
+            "encoder": "Lavc63.1.101 libx264"
+          }
+        },
+        {
+          "index": 1,
+          "codec_name": "aac",
+          "codec_long_name": "AAC (Advanced Audio Coding)",
+          "profile": "LC",
+          "codec_type": "audio",
+          "codec_tag_string": "mp4a",
+          "codec_tag": "0x6134706d",
+          "mime_codec_string": "mp4a.40.2",
+          "sample_fmt": "fltp",
+          "sample_rate": "48000",
+          "channels": 2,
+          "channel_layout": "stereo",
+          "bits_per_sample": 0,
+          "initial_padding": 1024,
+          "id": "0x2",
+          "r_frame_rate": "0/0",
+          "avg_frame_rate": "0/0",
+          "time_base": "1/48000",
+          "start_pts": 0,
+          "start_time": "0.000000",
+          "duration_ts": 192000,
+          "duration": "4.000000",
+          "bit_rate": "35574",
+          "nb_frames": "189",
+          "nb_read_frames": "188",
+          "extradata_size": 5,
+          "disposition": {
+            "default": 1,
+            "dub": 0,
+            "original": 0,
+            "comment": 0,
+            "lyrics": 0,
+            "karaoke": 0,
+            "forced": 0,
+            "hearing_impaired": 0,
+            "visual_impaired": 0,
+            "clean_effects": 0,
+            "attached_pic": 0,
+            "timed_thumbnails": 0,
+            "non_diegetic": 0,
+            "captions": 0,
+            "descriptions": 0,
+            "metadata": 0,
+            "dependent": 0,
+            "still_image": 0,
+            "multilayer": 0
+          },
+          "tags": {
+            "language": "und",
+            "handler_name": "SoundHandler"
+          }
+        }
+      ],
+      "format": {
+        "nb_streams": 2,
+        "nb_programs": 0,
+        "nb_stream_groups": 0,
+        "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
+        "format_long_name": "QuickTime / MOV",
+        "start_time": "0.000000",
+        "duration": "4.000000",
+        "size": "79895",
+        "bit_rate": "159790",
+        "probe_score": 100,
+        "tags": {
+          "major_brand": "isom",
+          "minor_version": "512",
+          "compatible_brands": "isomiso2avc1mp41",
+          "encoder": "Lavf63.1.101"
+        }
+      }
+    },
+    "full_decode": "passed",
+    "decoded_timestamps": "CFR from zero; all frames checked",
+    "audio_duration_error_seconds": 0.0,
+    "mp4_atoms": [
+      "ftyp",
+      "moov",
+      "free",
+      "mdat"
+    ],
+    "listening_approved": false,
+    "platform_safe_zone_verified": false
+  },
+  "description": "Left: original pip-zero movement. Right: source-bound aligned movement. Bottom: captured recording keeps source clock. Text changes at original LRC timestamps. Soundtrack: original synthetic clicks.",
+  "limits": "Synthetic score, not detector accuracy, canonical-song authority or attended listening approval. Generated illustration omitted because actual rendered output demonstrates the composition.",
+  "files": {
+    "beat-alignment.mp4": "7e8a62a67fcc2967540121bd848263d2eff2bea02ca77e0b01f3be2966d45ccb",
+    "beat-alignment.png": "1755f09c51382cf04adbe0b18ce702036807e8b595633cc10cd116bfb9c5f88a"
+  }
+}

framerudiments-0.2.0/docs/media/demo-transcript.md

@@ -0,0 +1,15 @@
+# Synthetic visualiser demonstration transcript
+
+Four seconds at 60 fps, 360 by 640 pixels. This is synthetic oscillator audio,
+not a performed song. FrameRudiments identity text stays in the upper section.
+A DanceRudiments bounce moves the round check-mark sprite; a circular native
+motion moves a four-cell, beat-animated triangle atlas. Four native recording
+bars appear below. Both engines apply feedback to the complete image.
+
+- 0.00-1.25 seconds: Signals into motion.
+- 1.25-2.50 seconds: Words into light.
+- 2.50-3.75 seconds: Keep the clock in sight.
+- 3.75-4.00 seconds: caption cleared; shapes and feedback remain.
+
+The still compares the original composed frame with the encoded processed
+frame at output time 2.00 seconds. See media-evidence.json for exact hashes.

framerudiments-0.2.0/docs/media/effects-pipeline.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="280" viewBox="0 0 1000 280" role="img" aria-labelledby="title desc">
+  <title id="title">Illustration of FrameRudiments full-frame effects</title>
+  <desc id="desc">Artwork, native sprites, rudiment views and lyrics are composed before optional Butterchurn and projectM stages, followed by encoding. Both effects receive PCM from the same soundtrack edits.</desc>
+  <defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto"><path d="M0 0L8 4L0 8Z" fill="#76d4cf"/></marker></defs>
+  <rect width="1000" height="280" rx="18" fill="#101b2e"/>
+  <g font-family="sans-serif" fill="#f5eddf" text-anchor="middle">
+    <text x="500" y="32" font-size="18">Processing-order illustration — not a screenshot</text>
+    <g stroke="#76d4cf" stroke-width="2" fill="#192a40">
+      <rect x="20" y="65" width="250" height="110" rx="12"/>
+      <rect x="320" y="65" width="210" height="110" rx="12"/>
+      <rect x="580" y="65" width="210" height="110" rx="12"/>
+      <rect x="840" y="65" width="140" height="110" rx="12"/>
+    </g>
+    <text x="145" y="93" font-size="20">Compose full frame</text>
+    <text x="145" y="120" font-size="15">Artwork · native sprites/atlases</text>
+    <text x="145" y="145" font-size="15">Rudiment views · lyrics</text>
+    <text x="425" y="100" font-size="22">Butterchurn</text>
+    <text x="425" y="130" font-size="16">Optional warp + feedback</text>
+    <text x="425" y="153" font-size="14">Includes text and sprites</text>
+    <text x="685" y="100" font-size="22">projectM</text>
+    <text x="685" y="130" font-size="16">Optional warp + feedback</text>
+    <text x="685" y="153" font-size="14">Includes text and sprites</text>
+    <text x="910" y="105" font-size="22">Encode</text>
+    <text x="910" y="137" font-size="16">Verified MP4</text>
+    <text x="500" y="225" font-size="17">Exact output-frame clock + causal PCM from the same trim/repeat/fade chain</text>
+    <text x="500" y="255" font-size="14">Choose either engine or change stage order. No clean lyric/sprite overlay is added after effects.</text>
+  </g>
+  <g stroke="#76d4cf" stroke-width="3" marker-end="url(#arrow)"><path d="M278 120H308"/><path d="M538 120H568"/><path d="M798 120H828"/></g>
+</svg>

framerudiments-0.2.0/docs/media/media-evidence.json

@@ -0,0 +1,50 @@
+{
+  "context": "Actual FrameRudiments0.1.4 candidate render; source91e69c1; synthetic words/tone/art only",
+  "frames": 240,
+  "fps": 60,
+  "dimensions": [
+    360,
+    640
+  ],
+  "full_decode": "passed",
+  "source_time_seconds": 2,
+  "engines": [
+    {
+      "engine": "butterchurn",
+      "preset": "9dc533150c3807697041399961802a7c6056a8de01922bcf07440dabea33385f",
+      "runtime_version": "2.6.7"
+    },
+    {
+      "engine": "projectm",
+      "preset": "815d9c4e1574908b67aff3c7d735dc2e24b01ac1f03ceb582f268965a91d5785",
+      "runtime_version": "4.2.0-dev"
+    }
+  ],
+  "portrait_canvas": [
+    640,
+    640
+  ],
+  "frame_size": [
+    360,
+    640
+  ],
+  "illustration": "effects-pipeline.svg is a generated explanatory diagram, not screenshot evidence",
+  "files": {
+    "demo-transcript.md": {
+      "sha256": "e331c33d2940290845484d0d17674461168f0ba4ebc8d156be02521754e97bab",
+      "bytes": 778
+    },
+    "effects-pipeline.svg": {
+      "sha256": "73671c92921a02d0017e2d7bb33bff4527311cd60672483b6c469ba7fc52c19c",
+      "bytes": 2283
+    },
+    "full-frame-comparison.png": {
+      "sha256": "fe53c0e80dfdbb52b48ae55b8bf0330793b24c76b6644d0cdad444e91f6e05ee",
+      "bytes": 88048
+    },
+    "full-frame-demo.mp4": {
+      "sha256": "5014dd1e467a73be1f17b18c03e55872c739178fdab5cdb4ad62e629019909e1",
+      "bytes": 285522
+    }
+  }
+}

{framerudiments-0.1.3 → framerudiments-0.2.0}/docs/project-format.md

@@ -11,7 +11,7 @@ the inputs are checked again before and after a render.
 | `purpose` | `short` (120 ms endpoint fades by default), `visualiser`, or `canvas` (no fades by default). |
 | `width`, `height`, `fps`, `fps_reason` | Even dimensions, fps defaults to 60; other rates need a reason. No platform compliance is inferred. |
 | `audio` | `source` file reference, verified `sample_rate`, start-inclusive `start_sample`, end-exclusive `end_sample`, optional positive integer `repeats` and `fade_seconds`. |
-| `clock` | `bpm` or `beat_grid` file reference; `authority`, `status` (`confirmed`, `estimated`, `synthetic`), optional `origin` in source seconds and `phase_status`. |
+| `clock` | `bpm`, `beat_grid` or source-bound `beat_alignment` file reference; `authority`, `status` (`confirmed`, `estimated`, `synthetic`), optional `origin` in source seconds and `phase_status`. A reading owns its BPM/origin and cannot be combined with `beat_grid` or `origin`. |
 | `font` | Pinned TTF/OTF file for authored text. |
 | `lyrics`, `cues` | Separate LRC references; `.cue` files are also supported for structural cues. |
 | `canonical_lyrics` | Optional pinned plain text whose performed nonempty lines must exactly match the LRC. Bracketed structural lines in this comparison file are excluded. |
@@ -30,6 +30,13 @@ control their appearance. `mapping` amplitudes are `dx`, `dy`, `rotation`
 and `scale_axis` select index 0,1,2 of the motion projection. Defaults are
 0,1,2,2 respectively. Set `y_axis: 0` to map a one-dimensional bounce vertically.
 
+![Actual encoded original/aligned clock example: captions and recorded bands retain source time](media/beat-alignment.png)
+
+[Watch the synthetic clock example](media/beat-alignment.mp4) and follow the
+[source-bound alignment setup](beat-alignment.md). Its first click at 0.125
+seconds maps to pip zero; the screenshot is encoded frame 75 at source 1.25
+seconds. [Verification and media hashes](media/beat-alignment-evidence.json).
+
 Atlas configuration is `{columns, rows, count, cycle_ticks, phase_beats?}`.
 The atlas must divide into exact cells. One beat is 16 ticks; cycle ticks are
 explicitly authored rather than silently quantised. Cycles use a continuous
@@ -87,3 +94,17 @@ for the `id`, `engine`, `preset`, `input_mix`, `seed` and `trusted_preset` field
 runtime setup and sequential feedback contract. Both engines process all existing
 layers, including native moving sprites/atlases, captions and lyric art, before
 encoding. Existing projects without `effects` keep the original composition path.
+
+![Actual synthetic frame before and after both visualisers](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-comparison.png)
+
+Actual FrameRudiments 0.1.4 candidate output: timed captions and native moving
+sprites/atlas before composition effects (left) and after both real engines
+(right). Synthetic oscillator audio and example words; this is a software demo.
+[Play the four-second demonstration](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-demo.mp4)
+and [read its transcript](https://github.com/kieransimkin/FrameRudiments/blob/v0.1.4/docs/media/demo-transcript.md).
+Playback is user-controlled; no automatic media playback is required.
+
+![Generated processing-order illustration; not a screenshot](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/effects-pipeline.svg)
+
+Generated vector illustration of the processing order. The comparison above
+and linked video are captured renderer output; the diagram is explanatory.

{framerudiments-0.1.3 → framerudiments-0.2.0}/docs/visualisers.md

@@ -94,7 +94,8 @@ the next warp input. This touches pinned internal properties, so changing the
 Butterchurn version requires adapter review and real-engine acceptance tests.
 projectM uses the public 4.2 burn-in/FBO/time APIs and one zero-time allocation
 warmup. Preset selection is locked; failures abort instead of retaining an idle
-or previous preset unnoticed.
+or previous preset unnoticed. Native error/fallback log messages are captured
+through the pinned 4.2 API; malformed warp/composite shaders abort too.
 
 `effects-audio.f32` is stereo native-rate PCM decoded with the **same shared
 FFmpeg trim, repeat and qsin fade filters** as the encoded soundtrack. Each
@@ -120,9 +121,21 @@ cross-platform bit-exact contract.
 
 The headless helper creates its own temporary profile, blocks external requests,
 and closes its page/browser through Puppeteer on success and failure before
-removing only that owned profile. It does not attach to a signed-in browser.
+removing only that owned profile. Bounded retries handle transient Windows file
+locks after browser closure; an unresolved cleanup failure aborts the render. It does not attach to a signed-in browser.
 projectM destroys its instance, textures, framebuffer and hidden GLFW window.
 
+## Portrait mapping
+
+In 0.1.4+, the pinned projectM legacy VideoEcho path's portrait stretch is
+avoided with a square overscan canvas: the whole input frame is placed at its
+original pixel size in the centre, processed by the unmodified engine, and
+cropped back to the requested dimensions. The manifest records frame/canvas
+sizes and mapping. Landscape/square projectM and Butterchurn use native viewports.
+Presets use the engine canvas coordinates, so material can move through the
+overscan margin. No post-effect lyric or sprite overlay is drawn. Neutral mapping
+is tested in portrait, landscape and square formats for both engines.
+
 ## External presets and potential problems
 
 A preset may instead be a pinned `{ "path": "...", "sha256": "..." }` file
@@ -148,3 +161,17 @@ wheel does not bundle the native library, browser or npm modules. When
 redistributing those runtimes, retain their own licences and corresponding
 source/relinking obligations. See the upstream [Butterchurn repository](https://github.com/jberg/butterchurn)
 and [pinned projectM source](https://github.com/projectM-visualizer/projectm/tree/349b7cc2db312d47cef6be24c6856ced6643a385).
+
+![Actual synthetic frame before and after both visualisers](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-comparison.png)
+
+Actual FrameRudiments 0.1.4 candidate output: timed captions and native moving
+sprites/atlas before composition effects (left) and after both real engines
+(right). Synthetic oscillator audio and example words; this is a software demo.
+[Play the four-second demonstration](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-demo.mp4)
+and [read its transcript](https://github.com/kieransimkin/FrameRudiments/blob/v0.1.4/docs/media/demo-transcript.md).
+Playback is user-controlled; no automatic media playback is required.
+
+![Generated processing-order illustration; not a screenshot](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/effects-pipeline.svg)
+
+Generated vector illustration of the processing order. The comparison above
+and linked video are captured renderer output; the diagram is explanatory.

framerudiments-0.2.0/docs/workflow-media.md

@@ -0,0 +1,15 @@
+## FrameRudiments visual examples
+
+![Actual before/after lyric and native sprite frames](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-comparison.png)
+
+Actual synthetic FrameRudiments 0.1.4 candidate output: lyrics, native moving
+sprites and a beat-animated atlas all pass through both real visualisers.
+[Play the four-second demo](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/full-frame-demo.mp4)
+with [transcript](https://github.com/kieransimkin/FrameRudiments/blob/v0.1.4/docs/media/demo-transcript.md).
+
+![Generated effects-pipeline illustration, not screenshot evidence](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.1.4/docs/media/effects-pipeline.svg)
+
+The diagram illustrates composition order; the still and video are captured
+renderer output. Use the exact runtime pins and project format in the
+[visualiser guide](https://github.com/kieransimkin/FrameRudiments/blob/v0.1.4/docs/visualisers.md).
+Inspect encoded glyphs/safe zones; pre-effect bounds do not prove final fit.

{framerudiments-0.1.3 → framerudiments-0.2.0}/integration/test_visualisers_gpu.py

@@ -91,3 +91,45 @@ def test_butterchurn_shader_failure_closes_browser(tmp_path):
 def test_projectm_missing_preset_fails_instead_of_idle_fallback(tmp_path):
     with pytest.raises(RuntimeError, match="preset failed"):
         ProjectMBackend((160, 240), 60, tmp_path / "does-not-exist.milk", .8, 0, tmp_path)
+
+
+@pytest.mark.parametrize("size", [(180, 320), (320, 180), (240, 240)])
+@pytest.mark.parametrize("engine,factory,ext", [("projectm", ProjectMBackend, "milk"), ("butterchurn", ButterchurnBackend, "json")])
+def test_neutral_mapping_preserves_source_pixel_geometry(tmp_path, size, engine, factory, ext):
+    # Disable all artistic transforms to separate host geometry from preset choices.
+    milk = ('[preset00]\nfDecay=1\nfGammaAdj=1\nfWaveAlpha=0\nfShader=0\nmv_a=0\n'
+            'ob_size=0\nib_size=0\nwarp=0\nzoom=1\nfZoomExponent=1\nrot=0\nsx=1\nsy=1\n'
+            'dx=0\ndy=0\nfVideoEchoAlpha=0\n')
+    preset = dict(baseVals=dict(decay=1, gammaadj=1, wave_a=0, shader=0, mv_a=0,
+        ob_size=0, ib_size=0, warp=0, zoom=1, zoomexp=1, rot=0, sx=1, sy=1, dx=0, dy=0, echo_alpha=0),
+        shapes=[], waves=[], init_eqs_str='', frame_eqs_str='', pixel_eqs_str='', warp='', comp='')
+    target = tmp_path / f'neutral.{ext}'
+    target.write_text(milk if engine == 'projectm' else json.dumps(preset), encoding='utf-8')
+    image = Image.new('RGBA', size, 'black')
+    width, height = size
+    expected = (width//2-20, height//2-20, width//2+21, height//2+21)
+    draw = ImageDraw.Draw(image)
+    draw.rectangle((expected[0], expected[1], expected[2]-1, expected[3]-1), fill='white')
+    draw.rectangle((8, 8, 24, 24), fill='red')
+    backend = factory(size, 60, target, 1, 0, tmp_path)
+    try:
+        output = backend.process(image, SimpleNamespace(frame=0, output_seconds=0), array('f', [0]*2048))
+        red, green, blue = output.convert('RGB').split()
+        white = ImageChops.darker(ImageChops.darker(red, green), blue).point(lambda value: 255 if value > 80 else 0)
+        assert all(abs(a-b) <= 2 for a, b in zip(white.getbbox(), expected))
+        assert output.getpixel((16, 16))[0] > 100 and output.getpixel((16, 16))[2] < 10
+        assert output.size == size
+    finally:
+        backend.close()
+    assert all(backend.evidence['cleanup'].values())
+
+
+@pytest.mark.parametrize("kind", ["WARP", "COMP"])
+def test_projectm_shader_error_cannot_silently_fall_back(tmp_path, kind):
+    preset = (ASSETS / "feedback.milk").read_text()
+    preset = (f"MILKDROP_PRESET_VERSION=201\nPSVERSION_{kind}=2\n" + preset +
+              f"{kind.lower()}_1=shader_body {{ ret = THIS_IS_NOT_VALID; }}\n")
+    path = tmp_path / "broken.milk"
+    path.write_text(preset, encoding="utf-8")
+    with pytest.raises(RuntimeError, match="projectM preset failed"):
+        ProjectMBackend((160, 240), 60, path, .8, 0, tmp_path)

{framerudiments-0.1.3 → framerudiments-0.2.0}/pyproject.toml

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

{framerudiments-0.1.3 → framerudiments-0.2.0}/src/framerudiments/__init__.py

@@ -1,5 +1,5 @@
 """Offline frame composition on a traceable musical clock."""
-__version__ = "0.1.3"
+__version__ = "0.2.0"
 
 from .project import Project
 from .render import render, preflight