framerudiments 0.4.4__tar.gz → 0.4.5__tar.gz

{framerudiments-0.4.4/src/framerudiments.egg-info → framerudiments-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.4.4
+Version: 0.4.5
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -204,6 +204,8 @@ text. Existing plain text remains untouched unless configured. Set `word_indicat
 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.
+An optional between-word travel arc rises before the next timestamp and lands
+exactly on its encoded word frame.
 See [rich lyric reference](docs/rich-lyric-effects.md) and the
 [CI-generated demo](https://kieransimkin.github.io/FrameRudiments/rich-lyrics/).
 

{framerudiments-0.4.4 → framerudiments-0.4.5}/README.md

@@ -173,6 +173,8 @@ text. Existing plain text remains untouched unless configured. Set `word_indicat
 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.
+An optional between-word travel arc rises before the next timestamp and lands
+exactly on its encoded word frame.
 See [rich lyric reference](docs/rich-lyric-effects.md) and the
 [CI-generated demo](https://kieransimkin.github.io/FrameRudiments/rich-lyrics/).
 

{framerudiments-0.4.4 → framerudiments-0.4.5}/RELEASE_NOTES.md

@@ -1,3 +1,19 @@
+# FrameRudiments 0.4.5
+
+- Word indicators can now travel between encoded word hits with a configurable
+  arc and land on the next word's authoritative frame, while retaining the
+  existing after-hit mode.
+- projectM stages accept source-time preset timelines and perform bounded soft
+  transitions on the existing feedback instance, with every switch recorded in
+  render evidence.
+- Lyric layers can feed the visualiser only during their final bounded pips when
+  a real blank gap follows, allowing the departing line to dissolve into the
+  background without contaminating immediate line-to-line changes.
+- Project-format and visualiser documentation describe the new contracts;
+  focused regression coverage preserves clock, preset trust, routing and
+  evidence behaviour. Private campaign artwork and audio remain outside the
+  distribution.
+
 # FrameRudiments 0.4.4
 
 - Spectrum views accept a validated `style.grid` boolean. Set it to `false` to remove the three fixed dB guide lines while retaining calibrated bars and moving peak holds; label visibility remains independent.

{framerudiments-0.4.4 → framerudiments-0.4.5}/docs/project-format.md

@@ -23,6 +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[].preset_timeline` | Optional ordered projectM preset changes at canonical source seconds, using the native soft transition and retaining one feedback instance. |
 | `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. |
 
@@ -148,7 +149,9 @@ Set `effects` and optional checksum-pinned `font` on any `captions`, `word_capti
 emboss, inner/outer glow and drop shadow. `word_indicator` needs both line and word LRC,
 a full-line captions block and a selected native one-axis Rudiment bounce driver. Its
 particle options support constant emission, timed word/cue bursts and trigger-driven
-appearance changes; see [full schema and examples](rich-lyric-effects.md).
+appearance changes. `travel_mode: "between_words"` can use the pinned next-word
+timestamp to follow a smooth pre-hit arc and land exactly on the word frame;
+see [full schema and examples](rich-lyric-effects.md).
 
 ## Optional full-frame effects
 

{framerudiments-0.4.4 → framerudiments-0.4.5}/docs/rich-lyric-effects.md

@@ -92,6 +92,8 @@ DanceRudiment axis to the y-coordinate. The cursor may use a `spark`, `orb`,
     "glow": 5,
     "opacity": 1,
     "travel_frames": 10,
+    "travel_mode": "between_words",
+    "travel_arc": 24,
     "offset_x": 0,
     "offset_y": 14,
     "bounce": {
@@ -123,7 +125,13 @@ The `sprite` field is optional. For custom files, the supplied SHA-256 is
 mandatory; changing images requires changing the project reference. The same
 built-in transparent glyphs work without external assets. `position` accepts
 `above`, `below` or `on`. `travel_frames` (0–120) determines the smoothstep
-movement to the next word. Selecting `bounce.axis` projects one native
+movement window. The default `travel_mode: "after_hit"` preserves the original
+behaviour, moving from the preceding word after the new timestamp. Use
+`travel_mode: "between_words"` to move during the final `travel_frames` before
+the next encoded word timestamp; `travel_arc` (0–250 pixels) adds a sine-shaped
+lift that is zero at both ends, so the sprite lands exactly on the next word
+frame. This uses only the pinned word ledger and does not infer timing from the
+audio. Selecting `bounce.axis` projects one native
 DanceRudiment dimension only; captured recordings retain their own source
 clock, and rhythmic named/table motions use the corrected BPM map if enabled.
 

{framerudiments-0.4.4 → framerudiments-0.4.5}/docs/visualiser-routing.md

@@ -55,6 +55,7 @@ misspellings are errors rather than silent omissions.
 | --- | --- |
 | `continuous` | Inject this element on every output frame where it has visible alpha pixels |
 | `first_pips` | Inject from the first visible frame until `duration_pips` source-clock pips have elapsed, using the half-open interval `[appearance_pip, appearance_pip + duration_pips)` |
+| `last_pips` | With `retrigger: lyric`, inject the visible lyric element for the final `duration_pips` before the next effective lyric state becomes blank. A same-frame clear followed by a new nonblank line is an immediate handoff and does not trigger this window. |
 | `never` | No pixels from this element enter the first GPU stage; it can still be overlaid |
 
 `duration_pips` must be a finite number between 0 and 65,536. One beat is
@@ -64,6 +65,13 @@ beat count over repeated audio excerpts. Therefore a 64-pip window may be
 shorter or longer than half a second as the music accelerates or slows.
 A zero-pip window never injects the element.
 
+`last_pips` is designed for lyric tails that should enter feedback only before
+a genuine silent display gap. It requires `retrigger: lyric`, an active nonblank
+lyric, and a known next effective lyric event. The route report records
+`remaining_pips` and `lyric_gap_exit` so the decision is auditable. With
+`overlay: true`, the readable original remains visible while its copy enters the
+feedback pipeline; at the blank event both disappear from the clean layer.
+
 `retrigger` controls how the window starts:
 
 - `reappearance` (default): reset the window when an element becomes visible

{framerudiments-0.4.4 → framerudiments-0.4.5}/docs/visualisers.md

@@ -25,6 +25,33 @@ that two independent MilkDrop implementations produce identical pixels.
 ## Per-element feed and clean overlay routing
 
 FrameRudiments supports an optional project-level `visualiser_routing` object.
+
+## Source-timed projectM preset changes
+
+A projectM stage may retain one feedback instance while changing presets at
+canonical source-audio times. The native projectM soft transition blends the
+old and new preset; no frame is skipped and the existing PCM/output clock stays
+authoritative.
+
+```json
+{
+  "id": "section-visualiser",
+  "engine": "projectm",
+  "preset": "feedback",
+  "preset_timeline": [
+    {"at_source_seconds": 62.46, "preset": "kaleidoscope", "transition_seconds": 0.42},
+    {"at_source_seconds": 128.60, "preset": "julia", "transition_seconds": 0.42}
+  ]
+}
+```
+
+Times are measured in the unchanged source recording. Entries must be strictly
+increasing. Built-in names retain their package hashes; external `.milk` files
+still require `trusted_preset: true` on the individual timeline entry. Timeline
+switches currently use projectM because its pinned native API provides an
+auditable soft-cut transition on the same renderer instance. The manifest
+records the scheduled boundary, actual frame/source time, preset hash and blend
+duration.
 It controls the **input RGBA texture** entering the first Butterchurn or
 projectM stage and independently decides which original layers are composited
 cleanly above the **last** visualiser result. The subsequent stages remain

{framerudiments-0.4.4 → framerudiments-0.4.5}/pyproject.toml

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

{framerudiments-0.4.4 → framerudiments-0.4.5}/src/framerudiments/__init__.py

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

{framerudiments-0.4.4 → framerudiments-0.4.5}/src/framerudiments/compositor.py

@@ -33,6 +33,8 @@ class FrameContext:
     lyric: dict | None
     cue: dict | None
     word: dict | None = None
+    lyric_next: dict | None = None
+    lyric_next_beat: float | None = None
 
 
 class TextBlock:
@@ -413,6 +415,7 @@ class Compositor:
     def context(self, frame):
         p = self.project
         lyric = self.lyrics.at(frame)
+        lyric_next = self.lyrics.next_effective(frame)
         word = self.words.at(frame, lyric if p.lyrics else None) if self.words else None
         return FrameContext(
             frame,
@@ -422,6 +425,8 @@ class Compositor:
             lyric,
             self.cues.at(frame),
             word,
+            lyric_next,
+            p.continuous_beat(lyric_next["frame"]) if lyric_next is not None else None,
         )
 
     def _caption_draw(self, image, text, ctx):

{framerudiments-0.4.4 → framerudiments-0.4.5}/src/framerudiments/lyric_indicator.py

@@ -107,6 +107,8 @@ class WordIndicator:
                 "offset_x",
                 "offset_y",
                 "travel_frames",
+                "travel_mode",
+                "travel_arc",
                 "bounce",
                 "rotation",
                 "particles",
@@ -142,6 +144,25 @@ class WordIndicator:
         self.travel = integer(
             config.get("travel_frames", 8), "indicator transition frames", maximum=120 * time_factor
         )
+        self.travel_mode = config.get("travel_mode", "after_hit")
+        if self.travel_mode not in {"after_hit", "between_words"}:
+            raise ValueError("Indicator travel_mode must be after_hit or between_words")
+        self.travel_arc = number(
+            config.get("travel_arc", 0), "indicator travel arc", minimum=0, maximum=250
+        )
+        self._next_words = {}
+        timed_words = [
+            row for row in project.words if row.get("text") and row.get("word_index") is not None
+        ]
+        for current, following in zip(timed_words, timed_words[1:]):
+            if (
+                current.get("cycle") == following.get("cycle")
+                and current.get("line_frame") == following.get("line_frame")
+                and current.get("line_order") == following.get("line_order")
+                and following["frame"] > current["frame"]
+            ):
+                key = (current["frame"], current.get("source_order"), current.get("cycle"))
+                self._next_words[key] = following
         self.style = dict(
             indicator_size=number(config.get("size", 18), "indicator size", minimum=2, maximum=128),
             indicator_glow=number(config.get("glow", 4), "indicator glow", minimum=0, maximum=24),
@@ -282,7 +303,13 @@ class WordIndicator:
             font=self.font_ref,
             glyph=self.glyph,
             mode=self.particle_mode,
-            source_clock="encoded words/cues + native bounce axis",
+            source_clock="encoded words/cues + optional native bounce axis",
+            travel={
+                "mode": self.travel_mode,
+                "frames": self.travel,
+                "arc_pixels": self.travel_arc,
+                "landing_authority": "next encoded word frame" if self.travel_mode == "between_words" else None,
+            },
             bounce=self.bounce.evidence if self.bounce else None,
             modulations=self.modulations.evidence,
             cue_file=self.cue_ref,
@@ -323,7 +350,21 @@ class WordIndicator:
         if not 0 <= i < len(positions):
             return None
         x, y = positions[i]
-        if self.travel and i:
+        arc = 0.0
+        if self.travel_mode == "between_words" and self.travel:
+            key = (word["frame"], word.get("source_order"), word.get("cycle"))
+            following = self._next_words.get(key)
+            if following is not None:
+                target_index = following["word_index"]
+                start = max(word["frame"], following["frame"] - self.travel)
+                if frame >= start and 0 <= target_index < len(positions):
+                    u = _unit((frame - start) / max(1, following["frame"] - start))
+                    smooth = u * u * (3 - 2 * u)
+                    target = positions[target_index]
+                    x = x + (target[0] - x) * smooth
+                    y = y + (target[1] - y) * smooth
+                    arc = math.sin(math.pi * u) * self.travel_arc
+        elif self.travel and i:
             u = _unit((frame - word["frame"]) / self.travel)
             smooth = u * u * (3 - 2 * u)
             before = positions[i - 1]
@@ -337,6 +378,7 @@ class WordIndicator:
             y -= h / 2 + style["offset_y"]
         else:
             y += self.block.maximum * 0.5
+        y -= arc
         if self.bounce:
             values = self.bounce.sample(ctx.source_seconds, continuous_beat=ctx.beat)
             y -= values[self.bounce_axis] * style["bounce_amplitude"]
@@ -543,5 +585,7 @@ class WordIndicator:
             particles_active=active,
             cue_trigger=ctx.frame in self._events["cue"],
             word_trigger=ctx.frame in self._events["word"],
+            travel_mode=self.travel_mode,
+            landed=ctx.frame == ctx.word["frame"],
         )
         return layer.getchannel("A").getbbox()

{framerudiments-0.4.4 → framerudiments-0.4.5}/src/framerudiments/projectm_backend.py

@@ -169,6 +169,7 @@ class ProjectMBackend:
             "set_preset_locked": (None, [h, C.c_bool]),
             "set_hard_cut_enabled": (None, [h, C.c_bool]),
             "set_preset_start_clean": (None, [h, C.c_bool]),
+            "set_soft_cut_duration": (None, [h, C.c_double]),
             "load_preset_file": (None, [h, C.c_char_p, C.c_bool]),
             "set_preset_switch_failed_event_callback": (None, [h, C.c_void_p, h]),
             "pcm_add_float": (None, [h, C.POINTER(C.c_float), C.c_uint, C.c_int]),
@@ -202,6 +203,24 @@ class ProjectMBackend:
     def advance(self, image, context, pcm, *, capture=False):
         return self.process(image, context, pcm, capture=capture)
 
+    def switch_preset(self, preset, transition_seconds):
+        """Change preset on the existing feedback instance with projectM's soft transition."""
+        self.glfw.make_context_current(self.window)
+        self.lib.projectm_set_soft_cut_duration(self.handle, float(transition_seconds))
+        self.lib.projectm_load_preset_file(
+            self.handle,
+            os.fsencode(preset),
+            bool(transition_seconds),
+        )
+        self._check()
+        self.evidence.setdefault("preset_switches", []).append(
+            dict(
+                preset_path=str(Path(preset).resolve()),
+                preset_sha256=sha256(preset),
+                transition_seconds=float(transition_seconds),
+            )
+        )
+
     def process(self, image, context, pcm, *, capture=True):
         gl = self.gl
         self.glfw.make_context_current(self.window)

{framerudiments-0.4.4 → framerudiments-0.4.5}/src/framerudiments/timeline.py

@@ -111,6 +111,21 @@ class EventTrack:
         index = bisect_right(self.frames, frame) - 1
         return self.events[index] if index >= 0 else None
 
+    def next_effective(self, frame):
+        """Return the rendered state at the next distinct event frame.
+
+        Several lyric ledgers deliberately write a blank clear followed by the
+        next line at the same frame.  The last event at that frame is the state
+        a viewer actually sees, so a same-frame clear must not be mistaken for
+        a real lyric gap.
+        """
+        index = bisect_right(self.frames, frame)
+        if index >= len(self.events):
+            return None
+        next_frame = self.events[index]["frame"]
+        end = bisect_right(self.frames, next_frame)
+        return self.events[end - 1]
+
     def neighbours(self, frame):
         index = bisect_right(self.frames, frame) - 1
         current = self.events[index] if index >= 0 else None

{framerudiments-0.4.4 → framerudiments-0.4.5}/src/framerudiments/visualiser_routing.py

@@ -13,7 +13,7 @@ from PIL import Image
 from .io import fields, number
 
 MAX_TARGETS = 256
-MODES = frozenset({"continuous", "first_pips", "never"})
+MODES = frozenset({"continuous", "first_pips", "last_pips", "never"})
 RETRIGGERS = frozenset({"reappearance", "once", "lyric", "cue"})
 
 
@@ -27,12 +27,12 @@ def _policy(config, label, inherited=None):
     fields(feed, {"mode", "duration_pips"}, label + ".feed")
     mode = feed.get("mode")
     if mode not in MODES:
-        raise ValueError(f"{label}.feed.mode must be continuous, first_pips or never")
-    if mode == "first_pips":
+        raise ValueError(f"{label}.feed.mode must be continuous, first_pips, last_pips or never")
+    if mode in {"first_pips", "last_pips"}:
         duration = number(feed.get("duration_pips"), label + ".feed.duration_pips", minimum=0, maximum=65536)
         feed = dict(mode=mode, duration_pips=duration)
     elif "duration_pips" in feed:
-        raise ValueError(f"{label}.feed.duration_pips requires first_pips")
+        raise ValueError(f"{label}.feed.duration_pips requires first_pips or last_pips")
     else:
         feed = dict(mode=mode)
     overlay = config.get("overlay", parent["overlay"])
@@ -41,6 +41,8 @@ def _policy(config, label, inherited=None):
     retrigger = config.get("retrigger", parent["retrigger"])
     if retrigger not in RETRIGGERS:
         raise ValueError(f"{label}.retrigger must be reappearance, once, lyric or cue")
+    if feed["mode"] == "last_pips" and retrigger != "lyric":
+        raise ValueError(f"{label}.feed.mode last_pips requires retrigger=lyric")
     return dict(feed=feed, overlay=overlay, retrigger=retrigger)
 
 
@@ -128,6 +130,20 @@ class VisualiserLayerRouting:
             state["lyric"], state["cue"] = lyric, cue
             mode = policy["feed"]["mode"]
             elapsed = max(0.0, pip - state["onset"]) if state["onset"] is not None else None
+            lyric_next = getattr(context, "lyric_next", None)
+            lyric_next_beat = getattr(context, "lyric_next_beat", None)
+            remaining = (
+                max(0.0, float(lyric_next_beat) * 64.0 - pip)
+                if lyric_next_beat is not None and math.isfinite(float(lyric_next_beat))
+                else None
+            )
+            lyric_gap_exit = bool(
+                trigger == "lyric"
+                and getattr(context, "lyric", None)
+                and getattr(context, "lyric", {}).get("text")
+                and lyric_next is not None
+                and not lyric_next.get("text")
+            )
             feeding = bool(
                 visible
                 and (
@@ -135,6 +151,10 @@ class VisualiserLayerRouting:
                     or mode == "first_pips"
                     and elapsed is not None
                     and elapsed < policy["feed"]["duration_pips"]
+                    or mode == "last_pips"
+                    and lyric_gap_exit
+                    and remaining is not None
+                    and 0.0 < remaining <= policy["feed"]["duration_pips"]
                 )
             )
             on_top = bool(visible and policy["overlay"])
@@ -149,6 +169,8 @@ class VisualiserLayerRouting:
                     overlay=on_top,
                     first_pip=state["onset"],
                     elapsed_pips=elapsed,
+                    remaining_pips=remaining,
+                    lyric_gap_exit=lyric_gap_exit,
                     policy=policy["feed"]["mode"],
                 )
         self.next_frame += 1

{framerudiments-0.4.4 → framerudiments-0.4.5}/src/framerudiments/visualisers.py

@@ -18,31 +18,88 @@ ASSETS = Path(__file__).with_name("visualiser_assets")
 PRESETS = ("feedback", "kaleidoscope", "julia")
 
 
+def _preset_ref(project, engine, preset, *, trusted=False):
+    if isinstance(preset, str):
+        if preset not in PRESETS:
+            raise ValueError(f"Unknown built-in visualiser preset: {preset}")
+        path = ASSETS / f"{preset}.{'json' if engine == 'butterchurn' else 'milk'}"
+        return project.ref(dict(path=str(path), sha256=sha256(path)))
+    if trusted is not True:
+        raise ValueError(
+            "External presets contain executable equations/shaders: set trusted_preset true after review"
+        )
+    return project.ref(preset)
+
+
 def effect_specs(project):
     configs = project.data.get("effects", [])
     if not isinstance(configs, list) or len(configs) > 8:
         raise ValueError("effects must be an ordered list with at most eight stages")
     specs = []
     for cfg in configs:
-        fields(cfg, {"id", "engine", "preset", "input_mix", "seed", "trusted_preset"}, "full-frame effect")
+        fields(
+            cfg,
+            {
+                "id",
+                "engine",
+                "preset",
+                "input_mix",
+                "seed",
+                "trusted_preset",
+                "preset_timeline",
+            },
+            "full-frame effect",
+        )
         name = cfg.get("id")
         if not isinstance(name, str) or not name or name in [item["id"] for item in specs]:
             raise ValueError("Full-frame effect ids must be nonempty and unique")
         engine = cfg.get("engine")
         if engine not in {"butterchurn", "projectm"}:
             raise ValueError("Full-frame engine must be butterchurn or projectm")
-        preset = cfg.get("preset", "feedback")
-        if isinstance(preset, str):
-            if preset not in PRESETS:
-                raise ValueError(f"Unknown built-in visualiser preset: {preset}")
-            path = ASSETS / f"{preset}.{'json' if engine == 'butterchurn' else 'milk'}"
-            ref = project.ref(dict(path=str(path), sha256=sha256(path)))
-        else:
-            if cfg.get("trusted_preset") is not True:
-                raise ValueError(
-                    "External presets contain executable equations/shaders: set trusted_preset true after review"
+        ref = _preset_ref(
+            project,
+            engine,
+            cfg.get("preset", "feedback"),
+            trusted=cfg.get("trusted_preset", False),
+        )
+        timeline = cfg.get("preset_timeline", [])
+        if timeline and engine != "projectm":
+            raise ValueError("preset_timeline currently requires projectM")
+        if not isinstance(timeline, list) or len(timeline) > 64:
+            raise ValueError("preset_timeline must be a list with at most 64 entries")
+        resolved_timeline = []
+        previous = -1.0
+        for index, entry in enumerate(timeline):
+            fields(
+                entry,
+                {"at_source_seconds", "preset", "transition_seconds", "trusted_preset"},
+                f"preset_timeline[{index}]",
+            )
+            at = number(
+                entry.get("at_source_seconds"),
+                f"preset_timeline[{index}].at_source_seconds",
+                minimum=0,
+            )
+            if at <= previous:
+                raise ValueError("preset_timeline source times must be strictly increasing")
+            previous = at
+            resolved_timeline.append(
+                dict(
+                    at_source_seconds=at,
+                    preset=_preset_ref(
+                        project,
+                        engine,
+                        entry.get("preset"),
+                        trusted=entry.get("trusted_preset", False),
+                    ),
+                    transition_seconds=number(
+                        entry.get("transition_seconds", 0.5),
+                        f"preset_timeline[{index}].transition_seconds",
+                        minimum=0,
+                        maximum=30,
+                    ),
                 )
-            ref = project.ref(preset)
+            )
         specs.append(
             dict(
                 id=name,
@@ -50,6 +107,7 @@ def effect_specs(project):
                 preset=ref,
                 input_mix=number(cfg.get("input_mix", 0.65), "input mix", minimum=0.001, maximum=1),
                 seed=integer(cfg.get("seed", 0), "visualiser seed", maximum=2**32 - 1),
+                preset_timeline=resolved_timeline,
             )
         )
     return specs
@@ -243,6 +301,8 @@ class EffectChain:
         self.closed = False
         self.specs = specs
         self.routing = routing
+        self.preset_timeline_positions = [0 for _ in specs]
+        self.preset_switches = []
         self.stage_injections = {}
         requested = getattr(project, "data", {}).get("visualiser_stage_injections", [])
         if not isinstance(requested, list) or len(requested) > 32 or (requested and not specs):
@@ -298,6 +358,25 @@ class EffectChain:
         if self.stage_injections and isolated_layers is None:
             raise ValueError("Intermediate stage injection needs isolated layer surfaces")
         for index, backend in enumerate(self.backends):
+            timeline = self.specs[index].get("preset_timeline", [])
+            position = self.preset_timeline_positions[index]
+            while position < len(timeline) and context.source_seconds >= timeline[position]["at_source_seconds"]:
+                event = timeline[position]
+                if not hasattr(backend, "switch_preset"):
+                    raise ValueError("Scheduled preset changes require a backend with switch_preset support")
+                backend.switch_preset(event["preset"]["path"], event["transition_seconds"])
+                self.preset_switches.append(
+                    dict(
+                        frame=context.frame,
+                        source_seconds=context.source_seconds,
+                        stage=index,
+                        scheduled_at_source_seconds=event["at_source_seconds"],
+                        transition_seconds=event["transition_seconds"],
+                        preset=event["preset"],
+                    )
+                )
+                position += 1
+            self.preset_timeline_positions[index] = position
             if index in self.stage_injections:
                 image = image.convert("RGBA")
                 for names, opacity in self.stage_injections[index]:
@@ -330,6 +409,7 @@ class EffectChain:
             pcm=self.audio.evidence,
             routing=self.routing.evidence if self.routing is not None else None,
             stage_injections={index: entries for index, entries in self.stage_injections.items()},
+            preset_switches=self.preset_switches,
             stages=[dict(spec, runtime=backend.evidence) for spec, backend in zip(self.specs, self.backends)],
             limits="GPU/driver and engine noise can vary; not a cross-platform bit-exact contract. Text bounds refer to pre-effect composition.",
         )

{framerudiments-0.4.4 → framerudiments-0.4.5/src/framerudiments.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.4.4
+Version: 0.4.5
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -204,6 +204,8 @@ text. Existing plain text remains untouched unless configured. Set `word_indicat
 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.
+An optional between-word travel arc rises before the next timestamp and lands
+exactly on its encoded word frame.
 See [rich lyric reference](docs/rich-lyric-effects.md) and the
 [CI-generated demo](https://kieransimkin.github.io/FrameRudiments/rich-lyrics/).
 

{framerudiments-0.4.4 → framerudiments-0.4.5}/tests/test_rich_subtitles.py

@@ -226,6 +226,30 @@ def test_bounce_uses_single_selected_native_rudiment_axis_and_replays(project):
     assert obj.bounce_axis == 0
 
 
+def test_between_word_arc_lands_on_the_next_word_frame(project):
+    settings = {
+        "glyph": "star",
+        "size": 17,
+        "travel_frames": 20,
+        "travel_mode": "between_words",
+        "travel_arc": 24,
+    }
+    obj = WordIndicator(project, settings, project.context, block(project, {}))
+    first = obj._centre(5)
+    midpoint = obj._centre(25)
+    before_landing = obj._centre(34)
+    landed = obj._centre(35)
+    assert first and midpoint and before_landing and landed
+    assert first[0] < midpoint[0] < landed[0]
+    assert midpoint[1] < first[1] and midpoint[1] < landed[1]
+    assert before_landing[0] < landed[0]
+    assert landed[1] == pytest.approx(first[1])
+    frame = image()
+    obj.draw(frame, project.context(35))
+    assert obj.frame_report["landed"] is True
+    assert obj.frame_report["travel_mode"] == "between_words"
+
+
 def test_constant_particles_stay_on_and_word_events_trigger_bursts(project):
     obj = indicator(
         project,