framerudiments 0.4.7__tar.gz → 0.4.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.4.7
+Version: 0.4.8
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -358,6 +358,22 @@ 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.
 
+Each visualiser stage can also be chroma-keyed, constrained by a named animated
+alpha/luminance track matte, faded, or use all three operations together. The
+processed stage is composited over its own input before the next engine, so
+projectM and Butterchurn can occupy different regions while retaining their
+continuous source-time feedback. See [stage-level keying and matting](docs/visualisers.md#stage-level-chroma-key-and-track-mattes).
+
+The same stage can apply the complete FrameRudiments visual-effect pipeline at
+its source input, directly to the retained Butterchurn/projectM feedback state,
+or to display output. These hooks are separate and evidence-recorded; a
+feedback hook is written back for consumption by the next frame.
+
+The [real-engine feedback smoke evidence](docs/media/visualiser-feedback-writeback.png)
+shows the control frame, injected retained state and measured pixel difference
+for both pinned engines. It uses synthetic imagery and is evidence of the hook,
+not a claim about a campaign render.
+
 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)

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

@@ -327,6 +327,22 @@ 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.
 
+Each visualiser stage can also be chroma-keyed, constrained by a named animated
+alpha/luminance track matte, faded, or use all three operations together. The
+processed stage is composited over its own input before the next engine, so
+projectM and Butterchurn can occupy different regions while retaining their
+continuous source-time feedback. See [stage-level keying and matting](docs/visualisers.md#stage-level-chroma-key-and-track-mattes).
+
+The same stage can apply the complete FrameRudiments visual-effect pipeline at
+its source input, directly to the retained Butterchurn/projectM feedback state,
+or to display output. These hooks are separate and evidence-recorded; a
+feedback hook is written back for consumption by the next frame.
+
+The [real-engine feedback smoke evidence](docs/media/visualiser-feedback-writeback.png)
+shows the control frame, injected retained state and measured pixel difference
+for both pinned engines. It uses synthetic imagery and is evidence of the hook,
+not a claim about a campaign render.
+
 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)

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

@@ -1,3 +1,22 @@
+# FrameRudiments 0.4.8
+
+- Butterchurn and projectM stages now support deterministic post-stage chroma
+  keying, edge smoothing and bounded despill.
+- The complete VisualStyle effect set can run on a stage's source input,
+  retained feedback state, or display output. Retained-feedback treatments are
+  written back through Butterchurn's pinned target framebuffer and projectM's
+  pinned 4.2 texture-burn API before the next frame.
+- A stage can use any named isolated compositor element as an alpha or
+  luminance track matte, with inversion and independent matte/stage opacity.
+- Keying and matting compose in a documented order over the image that entered
+  each stage; later engines receive the already contained result while clean
+  routed text remains above the final chain.
+- Focused pixel tests cover hard/soft keys, combined key-plus-matte output,
+  luminance/alpha multiplication and two-engine stage order.
+- Pinned real-engine smoke evidence is included at
+  `docs/media/visualiser-feedback-writeback.png`, with source hashes in the
+  adjacent JSON receipt.
+
 # FrameRudiments 0.4.7
 
 - `preflight --max-frames N` composes a declared sequential prefix for expensive

framerudiments-0.4.8/docs/media/visualiser-feedback-writeback.json

@@ -0,0 +1,45 @@
+{
+  "schema": "framerudiments.feedback-contact-sheet.v1",
+  "synthetic_input": true,
+  "purpose": "Visual evidence of retained-feedback writeback in pinned real engines.",
+  "output": "docs\\media\\visualiser-feedback-writeback.png",
+  "output_sha256": "5d35e7555196c539bf669616405f759754472661c7838e2cfe92d74c74b323d5",
+  "sources": [
+    {
+      "engine": "Butterchurn",
+      "state": "control",
+      "file": "butterchurn-control.png",
+      "sha256": "c0210c81e18d3626fddcbae69151c11246879123fef5c27a7b8647c82ffb3225"
+    },
+    {
+      "engine": "Butterchurn",
+      "state": "feedback writeback",
+      "file": "butterchurn-feedback-hook.png",
+      "sha256": "406a7a828b49775a506507b59097588e0bc05d2f63ca28de571df211732f8a2f"
+    },
+    {
+      "engine": "Butterchurn",
+      "state": "pixel difference",
+      "file": "butterchurn-difference.png",
+      "sha256": "9ac9efc47ca3eb0dff21af46aaa5e8f7f7879bb4c5f004c64ca1fe2111a6d08d"
+    },
+    {
+      "engine": "projectM",
+      "state": "control",
+      "file": "projectm-control.png",
+      "sha256": "8ff0c598bde30f1c53f7037a46142c47e9e87a7d68cc66e87871d973d19cd74f"
+    },
+    {
+      "engine": "projectM",
+      "state": "feedback writeback",
+      "file": "projectm-feedback-hook.png",
+      "sha256": "3f8c01f0e568dfe61e691ebddd7a9c714bfc515d59613a6f14bae126950c4b08"
+    },
+    {
+      "engine": "projectM",
+      "state": "pixel difference",
+      "file": "projectm-difference.png",
+      "sha256": "2eac385f46c092d80e71224567f012b108505cc79c92c5a436a033af7e0dd9fc"
+    }
+  ]
+}

{framerudiments-0.4.7 → framerudiments-0.4.8}/docs/project-format.md

@@ -23,7 +23,7 @@ the inputs are checked again before and after a render.
 | `layers` | Ordered sprite, legacy bar and modular rudiment layers described below. |
 | Native radial petals | Use `type: "rudiment", renderer: "rangoli"` with independent scale/spin/lift axes; see [rangoli configuration and actual demo](rangoli.md). |
 | `visualiser_routing` | Optional per-element GPU input/overlay policies. Feed continuously, only for first N native pips after visibility onset, or never; see [routing](visualiser-routing.md). |
-| `effects` | Ordered Butterchurn/projectM stages. Butterchurn may set a denser `mesh_width`/`mesh_height`; any stage may set a multi-stop `output_palette_grade` applied before the next stage or clean routing overlay. projectM stages may use `preset_timeline` for ordered changes at canonical source seconds through the native soft transition on one retained feedback instance. See [visualisers](visualisers.md). |
+| `effects` | Ordered Butterchurn/projectM stages. Butterchurn may set a denser `mesh_width`/`mesh_height`; any stage may set `input_effects`, retained-loop `feedback_effects`, `output_effects`, a multi-stop `output_palette_grade`, and a stage-level `composite` containing chroma key, named alpha/luminance matte and opacity controls. projectM stages may use `preset_timeline` for ordered changes at canonical source seconds through the native soft transition on one retained feedback instance. See [visualisers](visualisers.md). |
 | `lyric_art` | `{items: [{text, asset}], placement: <sprite fields>, fallback: "text" or "error"}`. Exact text lookup preserves canonical lyric association. `error` requires every visible lyric to have an asset. |
 | `stemlab_loop` | `{file: <pinned loops report>, id: <accepted loop id>}`; imports native bounds/rate, verifies source SHA, rejects conflicting explicit audio values. Does not approve a seam. |
 
@@ -156,7 +156,8 @@ see [full schema and examples](rich-lyric-effects.md).
 ## Optional full-frame effects
 
 The top-level `effects` list is additive to v1. See [visualisers.md](visualisers.md)
-for the `id`, `engine`, `preset`, `input_mix`, `seed` and `trusted_preset` fields,
+for the `id`, `engine`, `preset`, `input_mix`, `seed`, `trusted_preset` and
+stage-level `composite` fields,
 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.

{framerudiments-0.4.7 → framerudiments-0.4.8}/docs/visualisers.md

@@ -57,6 +57,111 @@ Generated test illustration; it demonstrates the colour transform rather than
 evidence from a private campaign. A video is omitted because the grade is a
 stateless per-frame colour operation with no temporal behaviour.
 
+## Stage-level chroma key and track mattes
+
+### Input, retained-feedback and output effect hooks
+
+Every stage accepts three ordered arrays using the same `EffectStage` schema as
+`post_effects.frame`: `input_effects`, `feedback_effects` and
+`output_effects`. They support the complete validated `VisualStyle` set and
+native DanceRudiment modulations.
+
+```json
+{
+  "id": "cloud-feedback",
+  "engine": "butterchurn",
+  "preset": "feedback",
+  "input_effects": [
+    {"id": "source-grade", "visual": {"saturation": 0.7, "contrast": 1.1}}
+  ],
+  "feedback_effects": [
+    {"id": "memory-drift", "visual": {"hue_shift": 4, "blur": 0.6}}
+  ],
+  "output_effects": [
+    {"id": "display-finish", "visual": {"grain": 0.03, "vignette": 0.2}}
+  ]
+}
+```
+
+- `input_effects` changes the source texture before it is injected into that
+  engine's warp/composite pass. It therefore participates in feedback.
+- `feedback_effects` processes the engine frame and writes those pixels back
+  into the engine's retained feedback target before the next frame consumes
+  it. Butterchurn writes to its pinned `targetFrameBuffer`; projectM uses the
+  pinned 4.2 `projectm_opengl_burn_texture` API. This is an actual loop-state
+  mutation and requires one GPU readback/upload per affected stage and frame.
+- `output_effects` changes only the displayed stage result. It does not alter
+  retained feedback unless the same treatment is also declared under
+  `feedback_effects`.
+
+The exact order is stage input injection → `input_effects` → engine render →
+`feedback_effects` branch/writeback → legacy `output_palette_grade` →
+`output_effects` → chroma key → track matte → stage opacity/alpha-over. The
+next engine receives that composited display result. Clean routing overlays
+remain after the final engine.
+
+![Synthetic control frames beside real Butterchurn and projectM retained-feedback writeback results](media/visualiser-feedback-writeback.png)
+
+*Real-engine GPU smoke evidence from the pinned Butterchurn and projectM
+runtimes. The magenta card is deliberately written into each engine's retained
+feedback target; the following frame changes before ordinary output processing.
+Inputs are synthetic and the enlarged nearest-neighbour pixels make the
+difference inspectable. Source hashes are retained in the adjacent
+`visualiser-feedback-writeback.json` receipt.*
+
+Each Butterchurn or projectM stage may declare `composite`. FrameRudiments
+renders the visualiser normally, optionally removes a keyed colour, multiplies
+the remaining alpha by a named isolated compositor layer, then composites that
+result over the image that entered the stage. Both operations can be combined:
+
+```json
+{
+  "id": "coastal-light",
+  "engine": "projectm",
+  "preset": "julia",
+  "composite": {
+    "opacity": 0.82,
+    "chroma_key": {
+      "colour": "#00ff00",
+      "similarity": 0.10,
+      "smoothness": 0.08,
+      "despill": 0.35
+    },
+    "matte": {
+      "source": "layer:moving-clouds",
+      "mode": "luminance",
+      "invert": false,
+      "opacity": 0.9
+    }
+  }
+}
+```
+
+`similarity` is the fully removed maximum per-channel RGB distance from the
+key colour, normalised to 0..1. `smoothness` is the following soft transition
+to fully opaque pixels. A zero smoothness gives a hard key. `despill` blends
+near-key edge pixels toward their luminance without altering distant colours.
+
+The matte `source` names an actual isolated compositor element such as
+`layer:moving-clouds`, `background`, `scene`, `caption` or `lyric-art:0`.
+Unknown names fail during composition setup. `alpha` uses its rendered alpha;
+`luminance` multiplies that alpha by greyscale RGB. `invert`, matte `opacity`
+and stage `opacity` are applied after keying. An invisible or gated matte
+source produces an empty contribution for that frame.
+
+Compositing happens independently after every configured stage. The next
+visualiser receives the already keyed/matted result, so two engines can occupy
+different spatial regions without a release-owned frame loop. The visualiser
+still advances across the full sequential programme even when its visible
+matte is empty; its feedback state and PCM clock therefore remain continuous.
+Clean `visualiser_routing` overlays are drawn after the last stage as before.
+
+Keying is colour removal, not evidence that a preset was authored for a green
+screen. Choose a key colour demonstrated to be isolated in inspected output,
+and inspect edge transparency at delivery size. Track mattes preserve the
+provider's rendered motion and post effects; they do not infer a mask from a
+filename or visual role.
+
 ## Per-element feed and clean overlay routing
 
 FrameRudiments supports an optional project-level `visualiser_routing` object.

framerudiments-0.4.8/integration/build_feedback_contact_sheet.py

@@ -0,0 +1,83 @@
+"""Build a labelled documentation image from real-engine feedback smoke outputs."""
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+
+def file_hash(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--butterchurn-dir", type=Path, required=True)
+    parser.add_argument("--projectm-dir", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+
+    entries = []
+    for engine, folder in (
+        ("Butterchurn", args.butterchurn_dir),
+        ("projectM", args.projectm_dir),
+    ):
+        for state, filename in (
+            ("control", f"{engine.lower()}-control.png"),
+            ("feedback writeback", f"{engine.lower()}-feedback-hook.png"),
+            ("pixel difference", f"{engine.lower()}-difference.png"),
+        ):
+            path = folder / filename
+            entries.append((engine, state, path, Image.open(path).convert("RGB")))
+
+    scale = 3
+    tile = (96 * scale, 64 * scale)
+    margin, label_height, footer_height = 20, 42, 22
+    sheet = Image.new(
+        "RGB",
+        (
+            margin * 4 + tile[0] * 3,
+            margin * 3 + (label_height + tile[1] + footer_height) * 2,
+        ),
+        "#0b1020",
+    )
+    draw = ImageDraw.Draw(sheet)
+    font = ImageFont.load_default(size=16)
+    small = ImageFont.load_default(size=13)
+    for index, (engine, state, path, image) in enumerate(entries):
+        row, column = divmod(index, 3)
+        x = margin + column * (tile[0] + margin)
+        y = margin + row * (tile[1] + label_height + footer_height + margin)
+        draw.text((x, y), f"{engine} - {state}", font=font, fill="#f4f0e8")
+        resized = image.resize(tile, Image.Resampling.NEAREST)
+        sheet.paste(resized, (x, y + label_height))
+        draw.rectangle((x, y + label_height, x + tile[0] - 1, y + label_height + tile[1] - 1), outline="#5ce1e6", width=2)
+        draw.text((x, y + label_height + tile[1] + 3), path.name, font=small, fill="#9aa8c7")
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(args.output, optimize=True)
+    receipt = {
+        "schema": "framerudiments.feedback-contact-sheet.v1",
+        "synthetic_input": True,
+        "purpose": "Visual evidence of retained-feedback writeback in pinned real engines.",
+        "output": str(args.output),
+        "output_sha256": file_hash(args.output),
+        "sources": [
+            {
+                "engine": engine,
+                "state": state,
+                "file": path.name,
+                "sha256": file_hash(path),
+            }
+            for engine, state, path, _ in entries
+        ],
+    }
+    args.output.with_suffix(".json").write_text(
+        json.dumps(receipt, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+if __name__ == "__main__":
+    main()

framerudiments-0.4.8/integration/verify_feedback_writeback.py

@@ -0,0 +1,117 @@
+"""Run opt-in real-engine feedback-writeback smoke checks.
+
+This script needs the documented Butterchurn and projectM environment variables.
+It writes tiny synthetic PNG evidence and a JSON receipt; no campaign media is used.
+"""
+
+import argparse
+import hashlib
+import json
+from array import array
+from pathlib import Path
+from types import SimpleNamespace
+
+from PIL import Image, ImageChops, ImageDraw
+
+from framerudiments.projectm_backend import ProjectMBackend
+from framerudiments.visualisers import ASSETS, ButterchurnBackend
+
+
+def digest(image):
+    return hashlib.sha256(image.tobytes()).hexdigest()
+
+
+def input_card(size):
+    image = Image.new("RGBA", size, "#10182f")
+    draw = ImageDraw.Draw(image)
+    draw.ellipse((8, 8, size[0] - 8, size[1] - 8), fill="#ff5b87")
+    draw.line((0, size[1] - 1, size[0] - 1, 0), fill="#4ee9ff", width=5)
+    return image
+
+
+def run_engine(name, factory, preset, output):
+    size = (96, 64)
+    pcm = array("f", [0.0] * 2048)
+    card = input_card(size)
+    transparent = Image.new("RGBA", size)
+    override = Image.new("RGBA", size, "#ff00ff")
+
+    def trial(writeback):
+        engine = factory(size, 60, preset, 0.72, 41, output)
+        try:
+            first = engine.process(card, SimpleNamespace(frame=0, output_seconds=0), pcm)
+            if writeback:
+                engine.set_feedback(override)
+            second = engine.process(
+                transparent, SimpleNamespace(frame=1, output_seconds=1 / 60), pcm
+            )
+            return first, second
+        finally:
+            engine.close()
+
+    first_control, control = trial(False)
+    first_treated, treated = trial(True)
+    try:
+        difference = ImageChops.difference(control.convert("RGB"), treated.convert("RGB"))
+        bbox = difference.getbbox()
+        if bbox is None:
+            raise AssertionError(f"{name} feedback writeback produced no next-frame pixel change")
+        control.save(output / f"{name}-control.png")
+        treated.save(output / f"{name}-feedback-hook.png")
+        difference.save(output / f"{name}-difference.png")
+        return {
+            "engine": name,
+            "frame0_hashes": [digest(first_control), digest(first_treated)],
+            "control_hash": digest(control),
+            "feedback_hook_hash": digest(treated),
+            "difference_bbox": list(bbox),
+            "difference_extrema": [list(value) for value in difference.getextrema()],
+        }
+    finally:
+        del first_control, first_treated, control, treated
+
+
+def write_receipt(path, receipt):
+    path.write_text(json.dumps(receipt, indent=2) + "\n", encoding="utf-8")
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument(
+        "--engine",
+        choices=("all", "butterchurn", "projectm"),
+        default="all",
+        help="Run both engines or a single bounded recovery trial.",
+    )
+    args = parser.parse_args()
+    args.output.mkdir(parents=True, exist_ok=False)
+    receipt = {
+        "schema": "framerudiments.feedback-writeback-smoke.v1",
+        "synthetic": True,
+        "engines": [],
+    }
+    if args.engine in {"all", "butterchurn"}:
+        receipt["engines"].append(
+            run_engine(
+                "butterchurn",
+                ButterchurnBackend,
+                ASSETS / "feedback.json",
+                args.output,
+            )
+        )
+        write_receipt(args.output / "receipt.json", receipt)
+    if args.engine in {"all", "projectm"}:
+        receipt["engines"].append(
+            run_engine(
+                "projectm",
+                ProjectMBackend,
+                ASSETS / "feedback.milk",
+                args.output,
+            )
+        )
+        write_receipt(args.output / "receipt.json", receipt)
+
+
+if __name__ == "__main__":
+    main()

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

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

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

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

{framerudiments-0.4.7 → framerudiments-0.4.8}/src/framerudiments/compositor.py

@@ -16,7 +16,7 @@ from .timeline import EventTrack
 from .word_timing import WordTrack
 from .rich_subtitles import RichTextAppearance
 from .lyric_indicator import WordIndicator
-from .visualisers import effect_specs
+from .visualisers import effect_specs, VisualiserEffectHooks
 from .scoped_effects import CompositingEffects
 from .visualiser_routing import VisualiserLayerRouting
 from .layer_masks import LayerMasks
@@ -378,6 +378,15 @@ class Compositor:
             targets.add("word-caption")
         if self.word_indicator:
             targets.add("word-indicator")
+        matte_sources = {
+            spec["composite"]["matte"]["source"]
+            for spec in self.effect_specs
+            if spec.get("composite") and spec["composite"].get("matte")
+        }
+        unknown_mattes = matte_sources - targets
+        if unknown_mattes:
+            raise ValueError(f"Unknown visualiser matte sources: {sorted(unknown_mattes)}")
+        self.visualiser_hooks = VisualiserEffectHooks(project, self.effect_specs, self.context)
         self.post_pipeline = CompositingEffects(
             project, project.data.get("post_effects", {}), self.context, valid_elements=targets
         )
@@ -386,7 +395,9 @@ class Compositor:
         self.layer_masks = LayerMasks(project.data.get("layer_masks", {}), mask_order)
         self.layer_animations = LayerAnimations(project.data.get("layer_animations", {}), mask_order)
         self.layer_displacement = LayerDisplacement(project.data.get("layer_displacement", {}), mask_order)
-        self._isolate_stage_injections = bool(project.data.get("visualiser_stage_injections"))
+        self._isolate_stage_injections = bool(
+            project.data.get("visualiser_stage_injections") or matte_sources
+        )
         self.visualiser_routing = None
         if "visualiser_routing" in project.data:
             if not self.effect_specs:

{framerudiments-0.4.7 → framerudiments-0.4.8}/src/framerudiments/projectm_backend.py

@@ -27,6 +27,7 @@ class ProjectMBackend:
         self.glfw, self.gl = glfw, GL
         self.window = self.handle = None
         self.texture = self.fbo = self.output_texture = None
+        self.feedback_override = None
         self.dll_dirs = []
         self.registered = False
         path = Path(os.environ.get("FRAMERUDIMENTS_PROJECTM_LIBRARY", ""))
@@ -225,7 +226,33 @@ class ProjectMBackend:
         gl = self.gl
         self.glfw.make_context_current(self.window)
         self.lib.projectm_set_log_callback(self.log_callback, True, None)
+        if self.feedback_override is not None:
+            self._burn(self.feedback_override, 1.0)
+            self.feedback_override = None
         frame = image.convert("RGBA")
+        self._burn(frame, self.mix)
+        self.lib.projectm_set_frame_time(self.handle, context.output_seconds)
+        audio = (C.c_float * len(pcm)).from_buffer_copy(pcm)
+        self.lib.projectm_pcm_add_float(self.handle, audio, len(pcm) // 2, 2)
+        self.lib.projectm_opengl_render_frame_fbo(self.handle, int(self.fbo))
+        self._check()
+        actual = self.lib.projectm_get_last_frame_time(self.handle)
+        if abs(actual - context.output_seconds) > 1e-9:
+            raise RuntimeError("projectM did not honour the offline frame clock")
+        if not capture:
+            return None
+        gl.glBindFramebuffer(gl.GL_FRAMEBUFFER, self.fbo)
+        gl.glPixelStorei(gl.GL_PACK_ALIGNMENT, 1)
+        raw = gl.glReadPixels(0, 0, *self.size, gl.GL_RGBA, gl.GL_UNSIGNED_BYTE)
+        frame = Image.frombytes("RGBA", self.size, raw).transpose(Image.Transpose.FLIP_TOP_BOTTOM)
+        return frame.crop((self.crop_left, 0, self.crop_left + self.frame_size[0], self.frame_size[1]))
+
+    def _burn(self, image, opacity):
+        """Burn an RGBA source into projectM's retained target through its public 4.2 API."""
+        gl = self.gl
+        frame = image.convert("RGBA")
+        if frame.size != self.frame_size:
+            raise ValueError("projectM feedback hook needs frame-sized RGBA")
         if self.size != self.frame_size:
             blank = (0, 0, 0, 0) if frame.getchannel("A").getextrema()[0] < 255 else "black"
             canvas = Image.new("RGBA", self.size, blank)
@@ -233,7 +260,7 @@ class ProjectMBackend:
             frame = canvas
         # Preserve source alpha so an unfed layer cannot paint black into feedback.
         # Fully opaque legacy inputs remain numerically unchanged.
-        frame.putalpha(frame.getchannel("A").point(lambda a: round(a * self.mix)))
+        frame.putalpha(frame.getchannel("A").point(lambda a: round(a * opacity)))
         pixels = frame.transpose(Image.Transpose.FLIP_TOP_BOTTOM).tobytes()
         gl.glActiveTexture(gl.GL_TEXTURE0)
         gl.glBindTexture(gl.GL_TEXTURE_2D, self.texture)
@@ -243,22 +270,12 @@ class ProjectMBackend:
         gl.glEnable(gl.GL_BLEND)
         gl.glBlendEquation(gl.GL_FUNC_ADD)
         gl.glBlendFunc(gl.GL_SRC_ALPHA, gl.GL_ONE_MINUS_SRC_ALPHA)
-        self.lib.projectm_set_frame_time(self.handle, context.output_seconds)
         self.lib.projectm_opengl_burn_texture(self.handle, int(self.texture), 0, 0, *self.size)
-        audio = (C.c_float * len(pcm)).from_buffer_copy(pcm)
-        self.lib.projectm_pcm_add_float(self.handle, audio, len(pcm) // 2, 2)
-        self.lib.projectm_opengl_render_frame_fbo(self.handle, int(self.fbo))
-        self._check()
-        actual = self.lib.projectm_get_last_frame_time(self.handle)
-        if abs(actual - context.output_seconds) > 1e-9:
-            raise RuntimeError("projectM did not honour the offline frame clock")
-        if not capture:
-            return None
-        gl.glBindFramebuffer(gl.GL_FRAMEBUFFER, self.fbo)
-        gl.glPixelStorei(gl.GL_PACK_ALIGNMENT, 1)
-        raw = gl.glReadPixels(0, 0, *self.size, gl.GL_RGBA, gl.GL_UNSIGNED_BYTE)
-        frame = Image.frombytes("RGBA", self.size, raw).transpose(Image.Transpose.FLIP_TOP_BOTTOM)
-        return frame.crop((self.crop_left, 0, self.crop_left + self.frame_size[0], self.frame_size[1]))
+
+    def set_feedback(self, image):
+        if image.mode != "RGBA" or image.size != self.frame_size:
+            raise ValueError("projectM feedback hook needs frame-sized RGBA")
+        self.feedback_override = image.copy()
 
     def close(self):
         global _users

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

@@ -142,7 +142,14 @@ def preflight(
     effects = None
     try:
         effects = (
-            EffectChain(p, compositor.effect_specs, ffmpeg, out, routing=compositor.visualiser_routing)
+            EffectChain(
+                p,
+                compositor.effect_specs,
+                ffmpeg,
+                out,
+                routing=compositor.visualiser_routing,
+                hooks=compositor.visualiser_hooks,
+            )
             if compositor.effect_specs
             else None
         )
@@ -201,7 +208,14 @@ def render(project, output, *, ffmpeg=None, ffprobe=None, scene=None, renderers=
     effects = None
     try:
         effects = (
-            EffectChain(p, compositor.effect_specs, ffmpeg, out, routing=compositor.visualiser_routing)
+            EffectChain(
+                p,
+                compositor.effect_specs,
+                ffmpeg,
+                out,
+                routing=compositor.visualiser_routing,
+                hooks=compositor.visualiser_hooks,
+            )
             if compositor.effect_specs
             else None
         )

{framerudiments-0.4.7 → framerudiments-0.4.8}/src/framerudiments/visualiser_assets/butterchurn-page.js

@@ -84,13 +84,19 @@ async function initialise(config) {
     gl.activeTexture(gl.TEXTURE0);
     const oldTexture = gl.getParameter(gl.TEXTURE_BINDING_2D), oldSampler = gl.getParameter(gl.SAMPLER_BINDING);
     gl.bindSampler(0, null); gl.bindTexture(gl.TEXTURE_2D, texture);
-    if (message.rgba) gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, config.width, config.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, decode(message.rgba));
-    // target becomes prev on render(): source pixels enter the real warp pass.
-    gl.bindFramebuffer(gl.FRAMEBUFFER, r.targetFrameBuffer);
-    gl.viewport(0, 0, r.texsizeX, r.texsizeY);
-    gl.useProgram(program); gl.bindVertexArray(vao); gl.uniform1i(source, 0); gl.uniform1f(amount, config.mix);
-    gl.enable(gl.BLEND); gl.blendEquation(gl.FUNC_ADD); gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
-    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    const inject = (rgba, opacity) => {
+      if (rgba) gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, config.width, config.height, 0,
+        gl.RGBA, gl.UNSIGNED_BYTE, decode(rgba));
+      gl.bindFramebuffer(gl.FRAMEBUFFER, r.targetFrameBuffer);
+      gl.viewport(0, 0, r.texsizeX, r.texsizeY);
+      gl.useProgram(program); gl.bindVertexArray(vao); gl.uniform1i(source, 0); gl.uniform1f(amount, opacity);
+      gl.enable(gl.BLEND); gl.blendEquation(gl.FUNC_ADD); gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+      gl.drawArrays(gl.TRIANGLES, 0, 3);
+    };
+    // A feedback hook replaces the retained target before this frame consumes
+    // it. The ordinary source is then injected with its independent input mix.
+    if (message.feedback_rgba) inject(message.feedback_rgba, 1);
+    inject(message.rgba, config.mix);
     gl.bindVertexArray(state.vao); gl.useProgram(state.program);
     gl.bindTexture(gl.TEXTURE_2D, oldTexture); gl.bindSampler(0, oldSampler); gl.activeTexture(state.active);
     gl.bindFramebuffer(gl.FRAMEBUFFER, state.fbo); gl.viewport(...state.viewport);