Parameters and native controls

Effects and timeline processors use PluginParameterDefinition for native editor controls:

PluginParameterDefinition(
    key="strength",
    label="Strength",
    control="slider",
    default=1.0,
    minimum=0.0,
    maximum=2.0,
    step=0.05,
    unit="x",
    help_text="Overall processing amount.",
)

Use stable key values. Parameter dictionaries are persisted in projects and are passed back to the processor exactly by key.

Note: Parameter keys and stored values are persisted in projects. Treat key names and value shapes as compatibility-sensitive API.

Supported controls

help_text is rendered as secondary explanatory text below the control where space permits.

Curve control

Use curve for an editable normalized graph with free X/Y point placement:

PluginParameterDefinition(
    key="mapping",
    label="Mapping",
    control="curve",
    default=[[0.0, 0.0], [0.5, 0.65], [1.0, 1.0]],
    curve_snap=0.05,
    curve_interpolation="smooth",
)

Users can drag points in both axes, left-click empty graph space to add a point, and right-click an internal point to remove it. The first and last points keep their X positions pinned to 0 and 1; their Y values remain editable.

curve_snap applies grid snapping on both axes. Holding Shift temporarily bypasses snapping. Use None or 0 for free movement. curve_interpolation accepts "linear" or "smooth".

curve5 remains available when a plugin specifically wants five fixed X positions. New plugins that need a general curve editor should normally use curve.

Choice example

PluginParameterDefinition(
    key="mode",
    label="Mode",
    control="choice",
    default="Soft",
    choices=("Soft", "Medium", "Hard"),
)

Folder example

PluginParameterDefinition(
    key="output_dir",
    label="Export folder",
    control="folder",
    default="",
    help_text="Leave empty to use Yrendr's generated-output directory.",
)

File example

PluginParameterDefinition(
    key="archive",
    label="Input archive",
    control="file",
    default="",
)

The generic file control opens the native OS file chooser. Plugins should validate the selected extension/content themselves.

Control interaction

Yrendr owns the control behavior. Heavy slider, curve and EQ changes are committed on mouse release rather than continuously while dragging. This prevents an expensive DSP or VFX processor from blocking the editor for every pointer event.

Ctrl+click resets the targeted parameter. For fixed-node controls such as curve5 and EQ, an individual node can also be reset independently.

knob is a compact rotary presentation for numeric values. Drag upward to increase and downward to decrease; hold Shift while dragging for fine adjustment. It is automatically packed into rows in the native plugin modal.

segmented is intended for a small set of mutually exclusive choices, while choice remains preferable for long choice lists. xy_pad stores two numeric values and is useful for positions, vectors and effect centers. toggle is the switch-style presentation of a boolean value; checkbox remains supported.

Native controls or a custom editor?

Prefer native controls for normal parameter forms. They inherit Yrendr interaction behavior, persistence, reset handling and styling automatically.

Video effects, audio effects and generators can register a custom_editor when the interface needs a full image/canvas, bespoke gestures, meters or another layout that does not map cleanly to native controls. The effect should still declare its persistent values with PluginParameterDefinition; the custom editor replaces only how those values are edited.

Custom editors can use PluginWindowOptions for host-owned sizing, resizing, dragging, minimize/maximize controls and optional custom title-bar rendering. See Custom editors and plugin windows for the complete callback and window contract.