framerudiments 0.3.0__tar.gz → 0.4.0__tar.gz

framerudiments-0.4.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md LICENSE AGENTS.md RELEASE_NOTES.md analysis-releases.json
+recursive-include docs *.md *.png *.svg *.json *.mp4
+recursive-include tests *.py
+
+recursive-include integration *.py
+
+prune models
+prune visualiser-analysis
+
+recursive-include scripts *.py *.ps1
+recursive-include src/framerudiments/sprite_assets *.png *.json

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.3.0
+Version: 0.4.0
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -16,6 +16,9 @@ Requires-Dist: dancerudiments<0.4,>=0.3.0
 Provides-Extra: projectm
 Requires-Dist: glfw==2.10.2; extra == "projectm"
 Requires-Dist: PyOpenGL==3.1.10; extra == "projectm"
+Provides-Extra: gpu
+Requires-Dist: moderngl<6,>=5.11; extra == "gpu"
+Requires-Dist: numpy>=1.26; extra == "gpu"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
@@ -25,10 +28,76 @@ Dynamic: license-file
 
 # FrameRudiments
 
+## Pinned visual-analysis releases
+
+PixelCue **0.9.1** and PrismMoves **0.2.0** are pinned by final release URL,
+source commit and wheel SHA-256 in `analysis-releases.json`. Both analysis
+launchers install these coordinated wheels into the project-local analysis
+environment; neither can silently restore the old development/API pair.
+Run `scripts/install_analysis_releases.py --python PATH_TO_ANALYSIS_PYTHON
+--with-sequence` to reinstall the pinned pair without downloading model weights.
+The native CI job tests the actual released sequence/description APIs with
+synthetic frames and no neural inference. OpenCV and other runtime dependencies
+remain separately constrained; this is not a whole-environment lock.
+
+## Efficient preset descriptions (new recommended analysis entry point)
+
+Run `./scripts/Run-PresetBehaviourAnalysis.ps1 -Limit 2` after installing the
+coordinated PixelCue/PrismMoves update. It captures 15 fps over 3 seconds (46
+frames per condition; 368 for the default four inputs and two audio controls),
+measures motion **before** semantic inference, and selects at most 24 unique
+non-blank images for CLIP and BLIP. Generated fixtures render at 384 x 384
+instead of the legacy 160-pixel pilot. The native render/audio clock is unchanged.
+
+One paragraph per preset describes supported movement, appearance and artefacts.
+The searchable gallery rebuilds from completed per-preset records at each job,
+not from an occasionally checkpointed index. Raw dense frames and attempts stay
+in ignored `_work/`; the compact reports and compressed evidence are under
+`visualiser-analysis/behaviour-catalogue/`. The old full-catalogue is preserved.
+
+`./scripts/Run-PresetBehaviourAnalysis.ps1 -DescribeExisting` produces a separate
+atlas from the saved analysis receipts without rerunning models. Sparse legacy
+stills never acquire invented temporal measurements. An authored `-Suite` or an
+explicit `-ArtworkDirectory` supplies real material; defaults use synthetic audio.
+See [the efficient workflow and its limitations](docs/preset-behaviour.md).
+
+Windows setup also gains checked project-local MinGW runtime bundling. Missing
+compiler DLLs come from the recorded, matching compiler installation and are
+verified in a fresh process; arbitrary DLL downloads and global PATH changes
+are not used. See [projectM local runtime bundle](docs/projectm-local-runtime.md).
+
 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/).
 
+## Full visualiser preset analysis — PrismMoves and PixelCue
+
+Run `./scripts/Run-FullPresetAnalysis.ps1` in Windows PowerShell for a **single
+resumable entry point** that installs the optional visual-analysis dependencies,
+captures every available Butterchurn/projectM preset, and produces searchable
+per-preset metrics, caption and tag hypotheses, summaries and previews.
+A quick pilot is `./scripts/Run-FullPresetAnalysis.ps1 -Limit 5`; rerun without
+`-Limit` to continue all remaining presets. The complete catalogue includes
+explicit partial/failure receipts for presets that cannot render.
+
+The full analysis evaluates all four image families (album/lyric input, colour
+bars, grid/rings and text card), music and silence, and frames at 0, 0.5, 1.5
+and 3 seconds. PixelCue and PrismMoves examine every captured output by
+default, and each preset gets labelled contact sheets plus an evidence-linked
+summary across the input conditions and time points. The processing queue
+alternates randomly selected projectM and Butterchurn presets, using a fresh
+shuffle of unprocessed entries each invocation. `-OrderSeed 20261018` optionally
+reproduces the order; receipts are saved under ignored `_work/schedules/`.
+Existing five-preset pilots using the older, narrower protocol need an explicit
+`-UpgradeCoverage` to archive earlier results before rerunning the fuller test.
+
+All model weights, runtimes and caches live in **project-local `models/`**
+(Git ignored). All generated results live under
+**`visualiser-analysis/full-catalogue/`** (commit the curated reports when ready;
+raw intermediate images in `_work/` stay local and ignored). No private music
+is required: a synthetic, checksum-pinned fixture is generated by default.
+See the [complete setup, resume, model, verification and Git guide](docs/full-preset-analysis.md).
+
 **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
@@ -48,6 +117,86 @@ Silly Sausage Britain and Moderate or Good renderers. Release-specific artwork,
 scene layouts and creative decisions belong in project files or Python scene
 hooks. Historical render scripts and approved outputs remain preserved.
 
+## Particle and smoke emitters
+
+A new deterministic `type: "emitter"` layer provides continuous smoke,
+sparks, embers, snow, rain, confetti and cue-triggered bursts, driven by
+independent DanceRudiments. Pinned DanceMoves/StemLab `.lrc`, `.cue`, or
+versioned `.json` timing files can trigger one-shot explosions; `hybrid`
+mode combines these with constant emission. Every parameter in the engine's
+numeric style table supports native `style.*` modulation. Pinned transparent
+PNG particles are optional, and the existing element- and frame-level post
+passes remain available. See [particle and smoke reference](docs/particle-smoke.md)
+and the [CI-generated synthetic gallery](https://kieransimkin.github.io/FrameRudiments/particles/).
+
+## Variable-tempo synchronisation and word subtitles
+
+FrameRudiments accepts a checksum-pinned `stemlab.beat-timeline.v1` in
+`clock.beat_timeline` for true piecewise BPM/beat phase at sample-frame anchors,
+matching StemLab and the opt-in DanceMoves variable-tempo API. Nominal/fixed
+BPM, beat grids, and fixed-tempo `beat_alignment` remain supported independently.
+Lyrics, cue timing and recorded Rudiments retain their source audio clock.
+A separate pinned `word_lyrics` LRC supports enhanced timestamps, per-word
+karaoke highlighting, progressive word colour and a distinct `word_captions`
+lane; line captions remain available through `lyrics`. Both per-line and
+per-word subtitle exports are generated with the same encoded frame ledger.
+See [variable-tempo and word LRC guide](docs/variable-bpm-word-subtitles.md)
+and the [synthetic public demo](https://kieransimkin.github.io/FrameRudiments/timing/).
+
+## Rich lyric typography and word-following particle sprites
+
+Caption blocks and identity titles optionally accept checksum-pinned `font` overrides and
+`effects` for stroked, bevelled, embossed, multi-stop gradient, inner/outer glow, and shadowed
+text. Existing plain text remains untouched unless configured. Set `word_indicator` for a
+native 1-dimensional DanceRudiment-driven bouncing sprite that tracks the active word of
+the full line. Its particle field can be continuous, word/cue-triggered, or hybrid;
+trigger windows independently change colour, density, size, glow and burst count.
+See [rich lyric reference](docs/rich-lyric-effects.md) and the
+[CI-generated demo](https://kieransimkin.github.io/FrameRudiments/rich-lyrics/).
+
+## Maximum-quality rendering enabled by default
+
+FrameRudiments now redraws pinned text outlines and procedural vector Rudiment
+views at **4× linear pixel resolution** before Lanczos reduction. It also
+renders **eight different source-clock subframes per output frame**,
+averaging them in linear light for true temporal supersampling. A final
+three-pass edge-aware AA filter runs after the optional GPU effect chain.
+These are the maximum supported preset settings and require no project changes.
+Explicitly lower them with `render_quality.spatial_scale` (1–4),
+`render_quality.temporal_samples` (1–8), or
+`render_quality.enabled: false` for deliberate pixel art or legacy output.
+Full-quality rendering can be much slower; read the
+[spatiotemporal sampling guide](docs/spatiotemporal-supersampling.md).
+
+## Layer-selective Butterchurn/projectM feedback
+
+Each composited element can feed the GPU visualisers continuously, only
+during a bounded window measured in **64-pip source-clock beats**, or not at
+all. Independently, an element can render cleanly over the last stage.
+Word captions, lyric sprites, particle emitters, backgrounds and normal
+Rudiment layers use the same routing policy. Existing projects remain
+unchanged. [Configuration and examples](docs/visualiser-routing.md) ·
+[CI comparisons](https://kieransimkin.github.io/FrameRudiments/routing/).
+
+## Solid 3D meshes and atmospheric rendering
+
+Three additional `spatial-solid-*` viewport modes (torus, sphere and terrain)
+provide per-pixel Z-buffered geometry, roughness/metallic direct lighting and
+depth-terminated procedural fog. They use the normal StemLab/DanceRudiments
+motion paths and can feed existing Butterchurn/projectM compositing chains.
+They are CPU rasterisers, not GPU mesh engines.
+See the [3D rendering guide](docs/solid-spatial-renderers.md).
+
+Three opt-in `spatial-music-*` modes add music-reactive mesh deformation,
+procedural rock/ice materials, erosion, normal/bump effects, and an optional
+ModernGL offscreen rasteriser with depth-tested shadows and single-scattering
+volumetric lighting. `spatial-music-terrain` can generate new rows from a
+checksum-pinned calibrated StemLab Fourier recording's history with
+`style.terrain_source: "fft"`. Existing DanceRudiments drivers can modulate
+mesh, camera, material, lighting and atmospheric properties. The CPU path
+remains deterministic and works without GPU dependencies.
+See [music-reactive 3D](docs/music-reactive-3d.md) for integration and limits.
+
 ## Install and run
 
 Python 3.11+ and FFmpeg with libx264/AAC are required. Install the package into
@@ -264,3 +413,75 @@ 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.
+
+## Visualisation Atlas and public gallery
+
+FrameRudiments now exposes **161 deterministic built-in Rudiment renderers**,
+including spectral waterfall, spectrogram heatmap (linear/log/mel/Bark/ERB
+**axis remappings**, not newly computed filterbanks), radial FFT-band views,
+and oscilloscope-inspired motion traces. All spectrum renderers require pinned,
+calibrated StemLab Fourier evidence; motion traces are not raw PCM audio.
+
+[Browse the CI-generated public visualisation gallery](https://kieransimkin.github.io/FrameRudiments/)
+(available after the Pages workflow is enabled and deployed), and read the
+[comprehensive method catalogue](docs/visualisation-atlas.md). Each PR checks
+and generates every mode; main deploys an interactive searchable gallery with
+four reproducible **synthetic** frames per mode. It now also publishes
+**20 annotated native DanceRudiment colour/geometry modulation scenes**.
+
+New options include continuous/inward/bipolar/segmented circular spectrum bars,
+polar time-frequency heatmaps, annular and spiral waveform plots, custom gradient
+stops, 16 built-in colour palettes, glow/hue/rotation/scale effects and up to
+32 independent source-clocked Rudiment modulators targeting colour *or* any
+validated numeric renderer style parameter. All modulation evidence keeps its
+pinned/native input identity. See [all 60 new modes, gradient controls and
+modulation examples](docs/annular-modulation.md).
+
+The next generation adds **60 additional display families**: spectrum LED matrices,
+cityscapes, ridgetrails and half-circle analysers; time-frequency voxel terrain,
+hexagonal mosaics and slit scans; and native-value CRT, triggered, braided and
+polar oscilloscope modes. Opt-in deterministic image treatments include scanlines,
+pixelation, grain, vignette, edge highlights, halftone, chromatic separation,
+solarisation and glitches. All these visual controls can be driven by
+source-clocked DanceRudiments. See [expanded effects reference](docs/expanded-effects.md).
+
+## Image-backed Rudiment renderers: 52 additional options
+
+FrameRudiments now offers **213 built-in Rudiment renderers**: the existing 161 vector
+options remain registered and unchanged, and 52 sprite-rendered spectrum,
+spectrogram, waveform and movement alternatives can be selected independently.
+The package bundles **17 PNG sprite atlas themes** (1,088 tiles), including 64
+transparent image-generated neon motifs and 1,024 procedurally generated LCD,
+LED, VFD, crystal, glass, retro-pixel, flame and other tiles. Pinned custom
+PNG atlases, animated cell selection and the existing DanceRudiment geometry/
+colour modulation and per-element/full-frame post effects are supported.
+
+[Explore vector and sprite comparisons](https://kieransimkin.github.io/FrameRudiments/sprites/)
+and see the [full sprite renderer reference](docs/sprite-visualisations.md).
+There are also 40 new per-sprite numeric controls (including size, rotation,
+colour channels, jitter, glow and animation speed) and validated native-driven
+categorical theme, shape and palette choices. The 16 new modulation lab
+scenes show these controls at four encoded-frame moments.
+
+The demo images are synthetic, not measured audio.
+
+Enable Settings → Pages → GitHub Actions as the repository publication source.
+
+## Per-element and full-frame post-render effects
+
+The new `post_effects` project field supports isolated effects for **each**
+background, scene, sprite, legacy bars, Rudiment layer, identity caption or
+lyric-art element, and separate passes over the **finished frame**. All 161
+renderers and the shared gradients/CRT/colour post effects are supported. Numeric
+parameters use native DanceRudiment modulation; palettes, colour-stop sets and
+gradient modes can switch between validated alternatives. Independent layer
+passes cannot recolour already composited neighbours, while a frame pass can
+act on everything. These stages run before the existing optional
+Butterchurn/projectM feedback chain. See the [compositor effects reference](docs/scoped-post-effects.md)
+and the [public scopes gallery](https://kieransimkin.github.io/FrameRudiments/scopes/).
+
+## High-quality antialiasing and motion blur
+
+Opt-in edge-aware antialiasing and premultiplied-alpha directional blur now work in Rudiment `visual` settings and independent per-element or whole-frame `post_effects` stages. Both accept native DanceRudiment modulation of all numeric settings, including direction, shutter distance, samples, strength, thresholds, radius and falloff. A separate `post_effects.temporal` shutter recomposes actual observed encoded frames in linear-light RGB, bounded to the current source repeat. It does not invent subframes or optical flow.
+
+The [CI-generated AA and motion-blur comparison gallery](https://kieransimkin.github.io/FrameRudiments/quality/) combines four existing visualiser modes with nine quality-effect configurations, four observed moments each, and machine-readable parameters. See [the quality-effects guide](docs/quality-effects.md).