Timeline actions

Timeline processors use action dictionaries to request editor-owned changes to tracks, clips and automation. Yrendr validates these actions and applies them on the main thread as part of the processor result.

Note: References such as ref, track_ref and clip_ref are local to one processor result and let later actions target objects created earlier in that same result.

create_track

{
    "action": "create_track",
    "name": "Generated",
    "color": [80, 140, 255],
    "ref": "generated_track",
}

ref is optional and exists only for the current processor result. Later actions can target the created track through track_ref.

Note: Yrendr applies supported actions on the main thread as editor-owned mutations. Unsupported actions raise an error and prevent partial application.

update_track

{
    "action": "update_track",
    "track": 1,
    "name": "Dialogue",
    "muted": False,
    "color": [120, 180, 255],
}

Or target a processor-created track:

{
    "action": "update_track",
    "track_ref": "generated_track",
    "name": "Captions",
}

create_clip

{
    "action": "create_clip",
    "ref": "generated_caption",
    "clip_type": "subtitle",
    "track_ref": "generated_track",
    "start": 4.2,
    "duration": 2.1,
    "properties": {
        "text": "Hello world",
        "font_size": 56,
    },
}

end may be used instead of duration. If both are omitted, the host uses a one-second duration. ref is optional and creates a processor-local clip reference. Later actions can target that newly created clip with clip_ref.

Supported clip types are:

video, image, text, audio, subtitle, shape, generator

Properties are filtered through the host's editable TimelineClip fields. Immutable identity/type fields and raw automation storage cannot be overwritten through properties.

update_clip

{
    "action": "update_clip",
    "clip_id": "existing-id",
    "properties": {
        "opacity": 180,
        "rotation": 8.0,
    },
}

move_clip

{
    "action": "move_clip",
    "clip_id": "existing-id",
    "start": 12.0,
    "track": 2,
}

track_ref is accepted instead of track.

trim_clip

{
    "action": "trim_clip",
    "clip_id": "existing-id",
    "start": 8.0,
    "duration": 4.0,
    "source_offset": 2.5,
}

Only fields supplied by the action are changed.

split_clip

{
    "action": "split_clip",
    "clip_id": "existing-id",
    "time": 14.25,
}

time is an absolute timeline time. Yrendr ignores a split at/too near a clip boundary. Source offsets and automation are separated by the host when a valid split occurs.

delete_clip

{
    "action": "delete_clip",
    "clip_id": "existing-id",
}

set_keyframes

{
    "action": "set_keyframes",
    "clip_ref": "generated_caption",
    "property": "scale_x",
    "keyframes": [
        {"time": 0.0, "value": 1.0, "easing": "linear"},
        {"time": 1.0, "value": 1.15, "easing": "ease_out"},
    ],
}

Keyframe time is clip-relative, not absolute timeline time. Yrendr converts it to the clip's internal automation representation.

Supported automation properties are currently:

volume, opacity, position_x, position_y, scale_x, scale_y, rotation,
effect_blur, effect_brightness, effect_contrast, effect_saturation,
effect_grayscale, effect_vignette, effect_sharpen

Supported easing names are linear (or any unrecognized/default value), ease_in, ease_out and ease_in_out.

The action replaces existing automation for the named property. Actions that operate on a clip accept either a persisted clip_id or a processor-local clip_ref created by a previous create_clip action.