framerudiments 0.2.0__tar.gz → 0.3.0__tar.gz

{framerudiments-0.2.0 → 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.2.0/src/framerudiments.egg-info → framerudiments-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.2.0
+Version: 0.3.0
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -242,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.2.0 → framerudiments-0.3.0}/README.md

@@ -217,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/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.2.0 → 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.2.0 → 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())

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

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

framerudiments-0.3.0/scripts/profile_visualisers.py

@@ -0,0 +1,10 @@
+"""Feed projects/audio to presets, capture intervals and invoke PrismMoves.
+
+Usage: python scripts/profile_visualisers.py SUITE CATALOGUE --output NEW_DIRECTORY
+All remaining options are the maintained `framerudiments presets-profile` options.
+"""
+import sys
+from framerudiments.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main(["presets-profile", *sys.argv[1:]]))

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

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

{framerudiments-0.2.0 → framerudiments-0.3.0}/src/framerudiments/cli.py

@@ -21,6 +21,24 @@ def main(argv=None):
     setup.add_argument("directory")
     setup.add_argument("--cmake-arg", action="append", default=[])
     setup.add_argument("--parallel", type=int, default=4)
+    libraries = commands.add_parser("presets-install", help="Install separately pinned upstream executable preset libraries")
+    libraries.add_argument("directory")
+    libraries.add_argument("--pack", action="append", default=[])
+    libraries.add_argument("--cache", help="Optional folder of exact checksum-pinned archives")
+    profiling = commands.add_parser("presets-profile", help="Replay sample covers/lyrics, static cards and audio; capture and profile preset response")
+    profiling.add_argument("suite")
+    profiling.add_argument("catalogue")
+    profiling.add_argument("--output", required=True)
+    profiling.add_argument("--intervals", nargs="+", type=float, default=[0, 1, 2, 4])
+    profiling.add_argument("--image", action="append", default=[])
+    profiling.add_argument("--audio-mode", action="append", choices=("programme", "silence"), default=[])
+    profiling.add_argument("--id", action="append", default=[])
+    profiling.add_argument("--limit", type=int)
+    profiling.add_argument("--resume", action="store_true")
+    profiling.add_argument("--retry-failed", action="store_true")
+    profiling.add_argument("--prism-python", help="Python with released PrismMoves and PixelCue installed; no model downloads")
+    profiling.add_argument("--model", action="append", choices=("clip", "dinov2", "blip", "ocr"), default=[])
+    profiling.add_argument("--max-edge", type=int, default=256)
     commands.add_parser("renderers", help="List available built-in rudiment renderers")
     demo = commands.add_parser("demo", help="Create a synthetic audio/image/recording project")
     demo.add_argument("directory")
@@ -63,6 +81,19 @@ def main(argv=None):
             result = (setup_butterchurn(args.directory) if args.engine == "butterchurn" else
                       setup_projectm(args.directory, cmake_args=args.cmake_arg, parallel=args.parallel))
             print(format_result(result))
+        elif args.command == "presets-install":
+            from .preset_library import PACKS, install_library
+            result = install_library(args.directory, packs=args.pack or tuple(PACKS), cache=args.cache)
+            print(json.dumps(dict(presets=len(result["presets"]), textures=len(result["textures"]))))
+        elif args.command == "presets-profile":
+            from .preset_profiling import CARDS, profile_presets
+            result = profile_presets(args.suite, args.catalogue, args.output, intervals=args.intervals,
+                images=args.image or ("cover-lyrics", *CARDS), audio_modes=args.audio_mode or ("programme", "silence"),
+                ids=args.id, limit=args.limit, resume=args.resume, retry_failed=args.retry_failed,
+                prism_python=args.prism_python, models=args.model, max_edge=args.max_edge)
+            print(json.dumps(dict(presets=len(result), captures=sum(x["state"] == "captured" for x in result))))
+            if any(x["state"] != "captured" or args.prism_python and x["analysis_state"] != "completed" for x in result):
+                return 2
         elif args.command == "renderers":
             print(json.dumps(default_renderers().names))
         elif args.command == "plan":

{framerudiments-0.2.0 → framerudiments-0.3.0}/src/framerudiments/io.py

@@ -2,6 +2,8 @@
 import hashlib
 import json
 import math
+import os
+import tempfile
 from pathlib import Path
 
 
@@ -28,8 +30,15 @@ def read_json(path):
 
 
 def write_json(path, value):
-    Path(path).write_text(json.dumps(value, ensure_ascii=False, allow_nan=False, indent=2) + "\n",
-                          encoding="utf-8")
+    path = Path(path)
+    text = json.dumps(value, ensure_ascii=False, allow_nan=False, indent=2) + "\n"
+    fd, temporary = tempfile.mkstemp(prefix="." + path.name + ".", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            stream.write(text)
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
 
 
 def number(value, name, *, minimum=None, maximum=None):

framerudiments-0.3.0/src/framerudiments/preset_library.py

@@ -0,0 +1,132 @@
+"""Pinned, separately installed upstream preset libraries; never bundled as MIT assets."""
+import hashlib
+import io
+import json
+from pathlib import Path, PurePosixPath
+import tarfile
+import urllib.request
+import zipfile
+
+from .io import sha256, write_json
+
+PACKS = {
+    "butterchurn": dict(engine="butterchurn", version="2.4.7", licence="MIT",
+        url="https://registry.npmjs.org/butterchurn-presets/-/butterchurn-presets-2.4.7.tgz",
+        sha256="d9c067b354e4ed87b3a1dace1dc59c9d64e6a99300a82d5fa086f696e35204a7"),
+    "cream": dict(engine="projectm", repository="projectM-visualizer/presets-cream-of-the-crop",
+        commit="0180df21f5e0bd39b9060cc5de420ed2f1f9e509",
+        sha256="5600f974497d8f73295393fbdf866895ceb89efe82892f5e2d019358b2659202"),
+    "classic": dict(engine="projectm", repository="projectM-visualizer/presets-projectm-classic",
+        commit="14a6244a7d32eb7e114e1a92d1cb93358cdcc54a",
+        sha256="328a41acf9216057fce0d873b244ca06e1aee5b466f7560df4903fdf28832ad0"),
+    "original": dict(engine="projectm", repository="projectM-visualizer/presets-milkdrop-original",
+        commit="e03b83e3338d8f1ed6cbcf908c719f249ef24288",
+        sha256="4479bbd10e4f4a005d636f7b0ed26004042541a62a925ca97e12ff13765b688d"),
+    "en-d": dict(engine="projectm", repository="projectM-visualizer/presets-en-d",
+        commit="fff71ea81223109f3558351667eef851f2781c96",
+        sha256="6badaf79e1ff095a5b56d38a380dd9b9ac8c2b5c6f6770879cbc0f65d549b5e1"),
+    "textures": dict(engine="textures", repository="projectM-visualizer/presets-milkdrop-texture-pack",
+        commit="6368812f27bc747b517218fbf89d21d59afce4d9",
+        sha256="38e93612f79a313830480d7458d8eb065d2b67992211a5dd0c92ef87b8607f6a"),
+}
+for _pin in PACKS.values():
+    if "url" not in _pin:
+        _pin["url"] = f"https://codeload.github.com/{_pin['repository']}/zip/{_pin['commit']}"
+        _pin["licence"] = "No explicit preset/texture grant established; retain upstream notices; not redistributed in FrameRudiments"
+
+
+def archive_members(data, *, tar=False):
+    """Read bounded ordinary files only; never extract paths, links or devices."""
+    if tar:
+        archive = tarfile.open(fileobj=io.BytesIO(data))
+        entries = ((x.name, x.size, lambda x=x: archive.extractfile(x).read())
+                   for x in archive.getmembers() if x.isfile())
+    else:
+        archive = zipfile.ZipFile(io.BytesIO(data))
+        entries = ((x.filename, x.file_size, lambda x=x: archive.read(x))
+                   for x in archive.infolist() if not x.is_dir())
+    total = 0
+    with archive:
+        for name, size, read in entries:
+            path = PurePosixPath(name)
+            if path.is_absolute() or ".." in path.parts or "\\" in name or ":" in name:
+                raise ValueError(f"Unsafe archive member: {name}")
+            total += size
+            if size > 32 * 1024**2 or total > 512 * 1024**2:
+                raise ValueError("Preset archive exceeds bounded extraction size")
+            yield str(PurePosixPath(*path.parts[1:])), read()
+
+
+def install_library(directory, *, packs=tuple(PACKS), cache=None):
+    """Explicit download/installation. Calling this acknowledges upstream executable presets."""
+    out = Path(directory).resolve()
+    if out.exists():
+        raise ValueError("Choose a new preset-library directory")
+    if not packs or set(packs) - PACKS.keys():
+        raise ValueError("Unknown or empty preset-pack selection")
+    out.mkdir(parents=True)
+    rows, receipts, textures = [], [], []
+    seen = {}
+    for name in packs:
+        pin = PACKS[name]
+        filename = "butterchurn-presets-2.4.7.tgz" if name == "butterchurn" else name + ".zip"
+        cached = Path(cache) / filename if cache else None
+        if cached and cached.is_file():
+            data = cached.read_bytes()
+        else:
+            with urllib.request.urlopen(pin["url"], timeout=180) as response:
+                data = response.read(64 * 1024**2 + 1)
+        if hashlib.sha256(data).hexdigest() != pin["sha256"]:
+            raise ValueError(f"Pinned preset archive checksum differs: {name}")
+        pack = out / name
+        pack.mkdir()
+        notices, count = [], 0
+        for original, content in archive_members(data, tar=name == "butterchurn"):
+            path = PurePosixPath(original)
+            if path.name.lower().startswith(("license", "copying", "readme")):
+                target = pack / path.name
+                target.write_bytes(content)
+                notices.append(dict(path=str(target), sha256=sha256(target)))
+            suffix = path.suffix.lower()
+            is_preset = (name == "butterchurn" and original.startswith("presets/converted/") and suffix == ".json"
+                         or pin["engine"] == "projectm" and suffix in {".milk", ".prjm"})
+            is_texture = name == "textures" and suffix in {".png", ".jpg", ".jpeg", ".bmp", ".dds", ".tga"}
+            if not is_preset and not is_texture:
+                continue
+            digest = hashlib.sha256(content).hexdigest()
+            if is_texture:
+                target = pack / path.name
+                if target.exists() and target.read_bytes() != content:
+                    raise ValueError(f"Texture basename collision: {original}")
+                target.write_bytes(content)
+                textures.append(dict(path=str(target), sha256=digest, original=original))
+                continue
+            count += 1
+            key = (pin["engine"], digest)
+            alias = dict(pack=name, original=original, name=path.stem)
+            if key in seen:
+                seen[key]["aliases"].append(alias)
+                continue
+            target = pack / (digest + suffix)
+            target.write_bytes(content)
+            row = dict(id=pin["engine"] + ":" + digest, engine=pin["engine"], name=path.stem,
+                       preset=dict(path=str(target), sha256=digest), aliases=[alias],
+                       source_pack=name, licence=pin["licence"], compatibility="unverified until actual rendering")
+            rows.append(row)
+            seen[key] = row
+        receipts.append(dict(id=name, **pin, preset_files=count, notices=notices))
+    result = dict(schema="framerudiments.preset-library.v1", packs=receipts, presets=rows,
+                  textures=textures, limits="Source membership and syntax are not shader/GPU acceptance or rights clearance.")
+    write_json(out / "catalogue.json", result)
+    return result
+
+
+def load_library(path):
+    path = Path(path).resolve()
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if data.get("schema") != "framerudiments.preset-library.v1":
+        raise ValueError("Expected framerudiments.preset-library.v1")
+    ids = [x["id"] for x in data["presets"]]
+    if len(ids) != len(set(ids)):
+        raise ValueError("Duplicate preset identities")
+    return data