framerudiments 0.1.4__tar.gz → 0.3.0__tar.gz

{framerudiments-0.1.4 → framerudiments-0.3.0}/MANIFEST.in

@@ -5,3 +5,5 @@ recursive-include tests *.py
 recursive-include integration *.py
 
 prune models
+
+recursive-include scripts *.py

{framerudiments-0.1.4/src/framerudiments.egg-info → framerudiments-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.1.4
+Version: 0.3.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,
@@ -229,3 +242,25 @@ Playback is user-controlled; no automatic media playback is required.
 
 Generated vector illustration of the processing order. The comparison above
 and linked video are captured renderer output; the diagram is explanatory.
+
+## Explore and profile the preset library
+
+Version 0.3.0 adds a separately installed, checksum-pinned library of **14,680
+distinct upstream presets** (1,738 Butterchurn and 12,942 projectM), with source
+notices, duplicate aliases and 67 shared textures. Real-engine acceptance is
+recorded per preset; available catalogue entries are not claimed as tested.
+
+Use `framerudiments presets-install`, then `framerudiments presets-profile` or
+`scripts/profile_visualisers.py` to feed ordinary cover/lyric/audio projects and
+three static calibration cards through each engine, replay every feedback frame,
+capture chosen intervals and invoke released PrismMoves/PixelCue. Reports keep
+input/output, temporal, tune/silence and same-card/different-tune comparisons
+separate, with measured response ranges and explicit unknowns.
+
+![Generated static input cards for controlled preset experiments](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.3.0/docs/media/preset-test-cards.png)
+
+Generated calibration illustrations; not preset-output evidence. The maintained
+My Songs suite uses Arcadians and The Truth is a Virus with their canonical
+masters, covers and timed lyrics; those private assets are not bundled.
+See [the complete capture, analysis and synthesis workflow](https://github.com/kieransimkin/FrameRudiments/blob/v0.3.0/docs/preset-profiling.md)
+for pinned packs, licences, runtime setup, resume and interpretation limits.

{framerudiments-0.1.4 → framerudiments-0.3.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,
@@ -204,3 +217,25 @@ Playback is user-controlled; no automatic media playback is required.
 
 Generated vector illustration of the processing order. The comparison above
 and linked video are captured renderer output; the diagram is explanatory.
+
+## Explore and profile the preset library
+
+Version 0.3.0 adds a separately installed, checksum-pinned library of **14,680
+distinct upstream presets** (1,738 Butterchurn and 12,942 projectM), with source
+notices, duplicate aliases and 67 shared textures. Real-engine acceptance is
+recorded per preset; available catalogue entries are not claimed as tested.
+
+Use `framerudiments presets-install`, then `framerudiments presets-profile` or
+`scripts/profile_visualisers.py` to feed ordinary cover/lyric/audio projects and
+three static calibration cards through each engine, replay every feedback frame,
+capture chosen intervals and invoke released PrismMoves/PixelCue. Reports keep
+input/output, temporal, tune/silence and same-card/different-tune comparisons
+separate, with measured response ranges and explicit unknowns.
+
+![Generated static input cards for controlled preset experiments](https://raw.githubusercontent.com/kieransimkin/FrameRudiments/v0.3.0/docs/media/preset-test-cards.png)
+
+Generated calibration illustrations; not preset-output evidence. The maintained
+My Songs suite uses Arcadians and The Truth is a Virus with their canonical
+masters, covers and timed lyrics; those private assets are not bundled.
+See [the complete capture, analysis and synthesis workflow](https://github.com/kieransimkin/FrameRudiments/blob/v0.3.0/docs/preset-profiling.md)
+for pinned packs, licences, runtime setup, resume and interpretation limits.

framerudiments-0.3.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.3.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.3.0/docs/preset-profiling.md

@@ -0,0 +1,200 @@
+# Preset libraries and input-response profiles
+
+FrameRudiments installs **14,680 distinct upstream presets** separately from the
+Python package: **1,738 Butterchurn** and **12,942 projectM** entries. Original
+names remain searchable aliases after exact-byte deduplication. The five preset
+packs contain 16,334 files before deduplication; 67 shared textures accompany them.
+The six existing built-in presets (three per engine) remain available through
+the ordinary project format.
+
+![Generated calibration cards used as static inputs](media/preset-test-cards.png)
+
+Generated calibration illustrations: colour bars with grayscale ramp,
+asymmetric grid/rings, and light/dark text. These are input cards, not evidence
+of a preset's appearance. Their PNG hashes are recorded with each experiment.
+
+The [actual four-second full-frame demonstration](https://kieransimkin.github.io/DanceFlow/framerudiments.html)
+shows the composition/effect pipeline, with user-controlled video playback and
+an accompanying transcript. It uses the earlier synthetic software demo;
+profiling inputs are supplied separately and are never silently substituted.
+
+## Install the complete pinned library
+
+```powershell
+framerudiments presets-install local/preset-library
+```
+
+Installation explicitly downloads upstream executable equations/shaders. No
+download happens during ordinary rendering. Every archive is SHA-256 pinned;
+the catalogue retains source commits, notices, aliases, preset hashes and texture
+hashes. Packages and caches remain outside the wheel/sdist. The installer reads
+bounded ordinary archive members and writes content-addressed preset filenames,
+avoiding original-path traversal and Windows filename/length problems.
+
+| Pack | Source pin | Files before deduplication |
+|---|---|---:|
+| Butterchurn presets, all six stable bundles | npm 2.4.7 | 1,754 |
+| Cream of the Crop | 0180df21f5e0bd39b9060cc5de420ed2f1f9e509 | 9,795 |
+| Classic projectM | 14a6244a7d32eb7e114e1a92d1cb93358cdcc54a | 4,193 |
+| Original MilkDrop | e03b83e3338d8f1ed6cbcf908c719f249ef24288 | 552 |
+| En D | fff71ea81223109f3558351667eef851f2781c96 | 40 |
+| Shared textures | 6368812f27bc747b517218fbf89d21d59afce4d9 | 67 images |
+
+Butterchurn 2.6.7 accepts the stable pack's JavaScript-equation format. The
+upstream 3.0 beta pack uses EEL fields and is not represented as compatible with
+this engine. projectM remains pinned to unmodified development commit
+`349b7cc2db312d47cef6be24c6856ced6643a385` (4.2.0-dev).
+
+Butterchurn's pack supplies an MIT notice. Some projectM packs supply no explicit
+licence grant; Cream/En D describe a historical public-domain assumption, which
+does not establish author permission. Keep their exact notices and provenance.
+FrameRudiments does not relicense or redistribute these packs as its own MIT
+assets. Source availability, shader compatibility and public-use eligibility are
+different states. Additional community packs require their own provenance and
+format review; raw pack size alone does not establish useful coverage.
+
+## Supply the two tunes, covers and lyrics
+
+Create an ordinary untreated FrameRudiments project for each sample, with pinned
+audio, cover background, font and timed LRC. Select explicit source sample bounds
+covering the desired excerpt. Use saved StemLab evidence when choosing musical
+sections or motion; the profiling runner does not estimate tempo or retime lyrics.
+Native DanceRudiments sprite/atlas layers can remain in these projects and enter
+the same full-frame processing path. The static-card conditions remove authored
+layers and lyrics to isolate the calibration imagery.
+
+```json
+{
+  "schema": "framerudiments.preset-suite.v1",
+  "projects": [
+    {"path": "arcadians-project.json", "sha256": "EXACT_PROJECT_SHA256"},
+    {"path": "truth-project.json", "sha256": "EXACT_PROJECT_SHA256"}
+  ],
+  "input_mix": 0.35,
+  "seed": 123
+}
+```
+
+For the maintained My Songs experiment the selected tunes are **Arcadians** and
+**The Truth is a Virus**, with their canonical masters, covers and manually timed
+lyrics. Their private suite and evidence stay outside the public repository.
+An optional `assets` list pins additional canonical/provenance files. Preserve
+the original LRC if an export needs a documented parser-input adapter; never
+silently alter its words or timings. An estimated clock used by a static test
+does not become an approved musical grid.
+
+## Capture, analyse and resume
+
+Set up the two optional engines as described in [visualisers.md](visualisers.md).
+Use a separate Python 3.13 interpreter with released **PrismMoves 0.1.0** and
+**PixelCue 0.9.0**, plus NumPy/Pillow, for analysis. This keeps heavy optional
+analysis dependencies out of the renderer's base installation. Existing local
+model-free APIs are sufficient; no model download is needed.
+
+```powershell
+framerudiments presets-profile local/suite.json local/preset-library/catalogue.json `
+  --output local/response-run --intervals 0 1 2 4 `
+  --prism-python path/to/prism-python
+
+# Equivalent script entrypoint in the source distribution:
+python scripts/profile_visualisers.py local/suite.json local/preset-library/catalogue.json `
+  --output local/response-run --intervals 0 1 2 4 --prism-python path/to/prism-python
+```
+
+Intervals are output seconds, rounded up to the next available frame and rejected
+outside the programme. Every preceding frame is replayed sequentially. Sparse
+captures skip unnecessary GPU readback; they do not skip feedback simulation.
+Each preset/condition starts a clean engine with the same mix, frame cadence,
+resolution and authored seed. projectM has no public seed API, so its random
+state remains an explicit confound. GPU/driver output is not cross-platform
+bit-identical.
+
+Default conditions cross each sample with cover/timed-lyrics, colour bars,
+grid/rings and text card, then programme audio and all-zero PCM controls: **16
+conditions for two samples**. Programme PCM uses the encoder's exact native-rate
+trim/repeat/fade filters and causal windows. Album imagery and captions undergo
+the same effects as the rest of the composition. Static cards do not inherit
+album colours or captions. The catalogue's verified textures are attached to the
+actual engine APIs, with runtime receipts.
+
+Use `--id EXACT_CATALOGUE_ID` repeatedly for a selected batch, or `--limit N`
+for a pilot; omitted limits select the full catalogue. `--image cover-lyrics`
+and `--audio-mode programme` narrow a declared experiment. Changing conditions
+requires a new output directory. A full sweep of thousands of presets is an
+explicit substantial workload: benchmark a representative batch first, retain
+elapsed time and storage evidence, then use the chosen settings consistently.
+Lowering frame rate changes feedback behaviour and must remain a labelled
+preview, with `fps_reason`, rather than a production-appearance claim.
+
+Re-run the identical command with `--resume` to reuse verified captures. Add
+`--retry-failed` for fresh attempts while retaining failures and older profiles.
+Changed inputs, runtime binaries, host bridges, textures, settings or capture
+bytes prevent stale reuse. Failed shaders are retained explicitly; native shader
+fallback errors are not accepted as a successful preset render.
+
+## Assemble one coherent response profile
+
+1. Read `experiment.json` and `index.json` for exact scope and coverage. Available
+   catalogue entries are not completed profiles. Every preset has `captures.json`
+   with per-condition times, hashes, PCM and engine/cleanup receipts.
+2. Open `identity/report.html` to inspect matching input/output frames and the
+   original condition families. `identity/prism-*/` contains the actual PrismMoves
+   reports, measured palette graphics, PixelCue evidence and checksums. Statistics
+   remain observations; optional `--model clip`, `dinov2`, `blip` or `ocr` outputs
+   remain interpretations, with unavailable receipts. Models load local weights
+   only under the experiment's `models/`; this runner never enables downloads.
+3. Use `identity/response.json` for source-to-output, successive-capture,
+   programme-versus-silence and same-card/different-tune comparisons. PixelCue's
+   `compare_profiles` supplies separate hue, texture and saturation distances and
+   supported embedding similarities. Named PixelCue luminance, edge/mirror,
+   texture/co-occurrence and spatial-frequency values also retain signed
+   input/output changes and observed ranges. No private analysis engine or invented
+   overall identity score is introduced.
+4. Review palette, geometry, texture, text treatment and temporal behaviour for
+   each family before synthesising. Describe a visual thesis supported by named
+   conditions; retain controlled variation and outliers. Frame grabs from one
+   run share a lineage and are not independent artistic authorities. Keep a
+   response range when tunes or cards differ rather than averaging incompatible
+   looks into one claimed invariant.
+5. Record remaining unknowns and production review: glyph legibility, safe zones,
+   sustained motion, flash safety, exact final frame rate, audio listening,
+   resource warnings and public-use rights. Measurements cannot establish these.
+   A failed preset receives a failure/unknown record, not an invented identity.
+
+## Potential problems
+
+- Thousands of available entries have not all been GPU accepted. Inspect each
+  capture state and runtime warnings; missing custom textures and old shader
+  dialects can produce failures or an altered appearance.
+- Native GPU/driver stalls may still require operator recovery; a completed
+  Python report is not evidence that an interrupted job cleaned up. The normal
+  Butterchurn route closes its owned headless browser and removes only its
+  freshly allocated profile; projectM destroys its native instance/window.
+- A report with unavailable neural/OCR models still has useful statistics.
+  Keep it partial; installing random/untrained checkpoints would not establish
+  visual understanding. No paid inference or automatic model sweep is implied.
+- Comparison settings (matte, ICC handling, analysis edge, frame rate, source
+  offset, input mix) influence results. Preserve them across a comparison batch.
+- Source PNGs and processed PNGs are renderer evidence, not decoded-video QA.
+  Encode and inspect the selected production preset using the normal render
+  pipeline before publishing a campaign video.
+
+Evidence JSON writes use same-directory temporary files and atomic replacement,
+so a failed update preserves the previous valid receipt. Disk exhaustion can
+still leave incomplete PNGs or reports: retain the interrupted attempt and
+resume only after hash validation, or start a fresh output directory.
+
+On Windows, Chromium's internal cache filenames can exceed its path limit even
+when Python can write the evidence folder. Profiling creates fresh profiles in
+the short experiment-level `.browser/` directory, with normal verified cleanup.
+For a deeply nested output root set `FRAMERUDIMENTS_BROWSER_PROFILE_ROOT` to a
+short writable project-local folder. Existing user browser profiles are never
+opened, read or reused.
+
+To use a catalogue entry in an ordinary render, copy its verified `preset`
+`{path, sha256}` reference into an effect stage with `engine` and
+`trusted_preset: true` after the explicit library review. Set
+`FRAMERUDIMENTS_TEXTURES_DIR` to the installed library's `textures/` directory
+when the preset needs it; the runtime records image hashes and native warnings.
+The profiler does this texture attachment automatically from the verified
+catalogue. Keep public-use eligibility separate from rendering acceptance.

{framerudiments-0.1.4 → framerudiments-0.3.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

{framerudiments-0.1.4 → framerudiments-0.3.0}/docs/visualisers.md

@@ -175,3 +175,15 @@ Playback is user-controlled; no automatic media playback is required.
 
 Generated vector illustration of the processing order. The comparison above
 and linked video are captured renderer output; the diagram is explanatory.
+
+## Expanded libraries and response experiments
+
+The [preset profiling workflow](preset-profiling.md) installs the complete pinned
+upstream catalogue and uses matching-time captures, three static test cards,
+programme/silence controls and released PrismMoves/PixelCue comparisons.
+
+![Generated calibration input cards](media/preset-test-cards.png)
+
+Generated input illustrations. Per-preset rendered captures and statistical
+reports are retained separately by each experiment; catalogue presence does
+not establish GPU compatibility or public-use rights.

framerudiments-0.3.0/integration/test_preset_analysis.py

@@ -0,0 +1,42 @@
+"""Actual PrismMoves/PixelCue measurements on sequential native-engine captures."""
+import json
+import os
+from pathlib import Path
+
+from PIL import Image
+
+from framerudiments.demo import create_demo
+from framerudiments.io import read_json, write_json, sha256
+from framerudiments.visualisers import ASSETS
+from framerudiments.preset_profiling import profile_presets
+from framerudiments.profile_analysis import summarise
+
+
+def test_real_prism_pixelcue_response_synthesis_and_controls(tmp_path):
+    project = create_demo(tmp_path/'sample', os.environ['FRAMERUDIMENTS_TEST_FONT'], width=128, height=128)
+    cover = project.parent/'cover.png'
+    Image.new('RGB', (128,128), 'navy').save(cover)
+    data = read_json(project)
+    data['background'] = dict(image=dict(path=str(cover),sha256=sha256(cover)))
+    data['layers'], data['identity'] = [], []
+    data['audio'].update(end_sample=48000,fade_seconds=0)
+    write_json(project,data)
+    suite = tmp_path/'suite.json'
+    write_json(suite,dict(schema='framerudiments.preset-suite.v1',projects=[dict(path=str(project),sha256=sha256(project))]))
+    preset=ASSETS/'feedback.milk'
+    catalogue=tmp_path/'catalogue.json'
+    write_json(catalogue,dict(schema='framerudiments.preset-library.v1',presets=[dict(id='native',name='Native fixture',engine='projectm',preset=dict(path=str(preset),sha256=sha256(preset)))]))
+    result=profile_presets(suite,catalogue,tmp_path/'run',intervals=[0,.1],images=['cover-lyrics','grid-rings'])
+    response=summarise(result[0]['manifest'],max_edge=64,models_dir=tmp_path/'models')
+    assert response['state']=='completed'
+    assert len(response['conditions'])==4
+    assert len(response['controlled_comparisons'])==2
+    assert all(len(x['source_to_output'])==2 for x in response['conditions'])
+    assert all(len(x['temporal'])==1 for x in response['conditions'])
+    assert response['settings']['versions']['prismmoves']=='0.1.0'
+    assert response['settings']['versions']['pixelcue']=='0.9.0'
+    assert all('median' in x for x in response['measured_response_ranges'].values())
+    assert summarise(result[0]['manifest'],max_edge=64,models_dir=tmp_path/'models')==response
+    report=Path(result[0]['manifest']).parent/'identity/report.html'
+    assert report.is_file() and 'matching-time capture' in report.read_text(encoding='utf-8')
+    assert json.loads((report.parent/'response.json').read_text())['settings']==response['settings']

{framerudiments-0.1.4 → framerudiments-0.3.0}/integration/test_visualisers_gpu.py

@@ -133,3 +133,19 @@ def test_projectm_shader_error_cannot_silently_fall_back(tmp_path, kind):
     path.write_text(preset, encoding="utf-8")
     with pytest.raises(RuntimeError, match="projectM preset failed"):
         ProjectMBackend((160, 240), 60, path, .8, 0, tmp_path)
+
+
+@pytest.mark.parametrize("factory,extension", [(ProjectMBackend,"milk"),(ButterchurnBackend,"json")])
+def test_sparse_capture_advances_real_feedback_and_retains_frame_clock(tmp_path,factory,extension):
+    image=glyph_frame()
+    backend=factory(image.size,60,ASSETS/f"feedback.{extension}",.75,12,tmp_path)
+    pcm=array("f",[0]*2048)
+    try:
+        for n in range(7):
+            assert backend.advance(image,SimpleNamespace(frame=n,output_seconds=n/60),pcm,capture=False) is None
+        final=backend.advance(image,SimpleNamespace(frame=7,output_seconds=7/60),pcm,capture=True)
+        assert final.mode=="RGBA" and final.size==image.size
+        assert final.getpixel((35,30))[0]>final.getpixel((35,30))[2]+80
+    finally:
+        backend.close()
+    assert all(backend.evidence["cleanup"].values())