Timeline Processors Version 1.1Updated 26 Sep 2026

Timeline processor API

Timeline processors are analysis/editing tools rather than per-frame effects. They run on a detached project snapshot and return data that Yrendr validates and applies.

Python

from editor.plugin_api import PluginParameterDefinition


def process_timeline(context, parameters):
    track_index = context["selection"]["track_index"]
    if track_index is None:
        return {"message": "Select a track first."}

    return {
        "message": "Created one title.",
        "actions": [
            {
                "action": "create_clip",
                "clip_type": "text",
                "track": track_index,
                "start": context["playhead"],
                "duration": 2.0,
                "properties": {
                    "text": "Generated by a timeline processor",
                },
            }
        ],
    }


def register(api):
    api.register_timeline_processor(
        processor_id="example",
        name="Example Processor",
        processor=process_timeline,
        description="Creates one text clip at the playhead.",
        capabilities=("create_clips",),
        randomizer=lambda current: {**current, "duration": 1.0},
        parameters=(
            PluginParameterDefinition(
                key="duration",
                label="Duration",
                control="slider",
                default=2.0,
                minimum=0.25,
                maximum=10.0,
                step=0.25,
                unit="s",
            ),
        ),
    )

Caution: Treat the supplied project snapshot as read-only. Return actions and outputs; never mutate the live editor project from the worker thread.

Threading model

Timeline processor functions run on a worker thread. They must not call Pygame UI functions or mutate the live project.

After the worker returns, Yrendr validates processor outputs/actions and applies them on the main thread as one history transaction. If application fails, Yrendr restores the pre-run project snapshot and removes editor-owned output files that were created as part of the failed operation.

Processor context

The processor receives a detached dictionary with this high-level shape:

Python

{
    "api_version": 1,
    "project": {
        "name": "Project",
        "width": 1920,
        "height": 1080,
        "fps": 30,
        "duration": 42.5,
    },
    "tracks": [
        {
            "index": 0,
            "name": "Track 1",
            "muted": False,
        }
    ],
    "clips": [...],
    "media": [...],
    "selection": {
        "clip_ids": [...],
        "track_index": 0,
    },
    "playhead": 10.0,
    "runtime": {
        "report_progress": callable,
        "render_media": callable,
    },
}

Treat the snapshot as read-only even though normal Python dictionaries/lists are used. Return actions instead of mutating the snapshot in place.