Procedural generators

Generators create visual content rather than modifying an existing frame. Register one with register_generator():

import numpy as np

from editor.plugin_api import PluginParameterDefinition


def render(size, parameters, context):
    width, height = size
    return np.zeros((height, width, 4), dtype=np.uint8)


def register(api):
    api.register_generator(
        effect_id="blank",
        name="Blank Generator",
        processor=render,
        parameters=(
            PluginParameterDefinition(
                key="mode",
                label="Mode",
                control="choice",
                default="Static",
                choices=("Static", "Animated"),
            ),
        ),
    )

The generator processor is called as:

def render(size, parameters, context):
    ...

size is (width, height). The processor may return:

• a pygame.Surface;
• an HxWx3 RGB NumPy array;
• an HxWx4 RGBA NumPy array.

NumPy output is clipped to uint8 when necessary. Output with an unexpected size/channel count is ignored.

Generator clips remain normal timeline clips after the source image is created. Yrendr still applies clip transforms, track FX, compositing and Master FX.

Note: A generator creates source pixels; it does not mutate an existing frame. The resulting generator clip still passes through normal transforms and FX routing.

Generator context

The generator context includes:

{
    "playhead": ...,
    "local_time": ...,
    "clip_duration": ...,
    "project_duration": ...,
    "render_scale": ...,
    "project": project,
    "clip": clip,
    "track": ...,
    "scope": "generator",
    "audio_spectrum": (...),
    "audio_waveform": (...),
    "audio_level": ...,
    "audio_peak": ...,
    "audio_bass": ...,
    "audio_mid": ...,
    "audio_treble": ...,
}

audio_spectrum currently contains 64 analysis bands for the audible timeline mix. The remaining audio values are convenience summaries derived from the same analysis path.

Custom editor support

register_generator() accepts custom_editor= and window_options=. This is intended for generator-specific canvases, visual composition controls and other layouts that are awkward to express as a standard parameter form. The generator still declares stable parameters and receives those same values in render(size, parameters, context).

See Custom editors and plugin windows for responsive content_renderer usage, window sizing, custom title bars and singleton editor behavior.