transition-editing

name: transition-editing description: Learn how to add and modify transition clips to bridge two adjacent clips seamlessly. Includes the full catalog of available transitions with descriptions.

transition-editing

Overview

This skill documents how to apply and customize transitions between adjacent clips on the timeline. A transition connects a source clip (fromClipId) and a destination clip (toClipId).

The transition catalog is maintained in @openvideo/core — use the keys listed in Section 4 when setting transitionKey.

Instructions

When the user asks to add or edit transitions (e.g. crossfades, slides, wipes, custom glsl transitions), you should output batch commands in your plan to:

1. Add the transition clip.
2. Link the adjacent clips.

⚠️ Supported Clip Types

Transitions only work between Video and Image clips. The rendering engine (engine-pixi) will not blend any other clip types.

Never add a Transition clip between two Text, Caption, or Audio clips. Even though the command will succeed at the data layer, the engine will silently ignore the blend and the clips will render normally without any transition.

What to do instead for Text / Caption clips

If the user asks for a fade or smooth entry/exit on a Text or Caption clip, use effect-editing instead:

• Use a fadeIn effect clip on the text track to fade in at the start.
• Use a fadeOut effect clip on the text track to fade out at the end.
• See the effect-editing skill for full details and examples.

1. Adding a Transition

A transition clip is placed at the overlapping intersection of two adjacent Video or Image clips.

• type: Must be "Transition"
• transitionKey: The transition effect key from the catalog (Section 4) — e.g. "fade", "GlitchMemories", "cube"
• fromClipId: The ID of the preceding clip
• toClipId: The ID of the succeeding clip
• timing: Nested timing block specifying duration and position.
  • duration: The transition duration in microseconds (e.g., 1000000 for 1 second)
  • display: The time range { "from": start, "to": end } where the transition occurs (centered on the transition boundary)

Example: Adding a fade transition

{
  "type": "command",
  "description": "Adding a fade transition",
  "command": {
    "type": "clip.add",
    "payload": {
      "clip": {
        "type": "Transition",
        "name": "fade",
        "transitionKey": "fade",
        "fromClipId": "clip_123",
        "toClipId": "clip_456",
        "timing": {
          "duration": 1000000,
          "display": {
            "from": 4500000,
            "to": 5500000
          }
        }
      }
    }
  }
}

2. Linking Adjacent Clips

To ensure the rendering engine properly blends the two clips during transition, you must link the adjacent clips by updating their transition metadata property.

Example: Updating fromClip and toClip metadata

[
  {
    "type": "command",
    "description": "Linking source clip to transition",
    "command": {
      "type": "clip.update",
      "payload": {
        "id": "clip_123",
        "updates": {
          "transition": {
            "key": "fade",
            "name": "fade",
            "fromClipId": "clip_123",
            "toClipId": "clip_456",
            "timing": {
              "duration": 1000000,
              "display": {
                "from": 4500000,
                "to": 5500000
              }
            }
          }
        }
      }
    }
  },
  {
    "type": "command",
    "description": "Linking destination clip to transition",
    "command": {
      "type": "clip.update",
      "payload": {
        "id": "clip_456",
        "updates": {
          "transition": {
            "key": "fade",
            "name": "fade",
            "fromClipId": "clip_123",
            "toClipId": "clip_456",
            "timing": {
              "duration": 1000000,
              "display": {
                "from": 4500000,
                "to": 5500000
              }
            }
          }
        }
      }
    }
  }
]

3. Customizing or Updating a Transition

To modify an existing transition (e.g. changing its key or duration), use clip.update.

Example: Changing transition to slide and duration to 1.5 seconds

{
  "type": "command",
  "description": "Updating transition key and duration",
  "command": {
    "type": "clip.update",
    "payload": {
      "id": "clip_transition_789",
      "updates": {
        "transitionKey": "Directional",
        "timing": {
          "duration": 1500000
        }
      }
    }
  }
}

4. Transition Catalog

All supported transitions are listed below, grouped by visual category. Use the key value as the transitionKey in commands.

Provider: All transitions below are supported by engine-pixi. Additional providers (e.g. react-skia) may support a subset.

Fade

Wipe

Slide

Zoom

Geometric

Blur

Distort

Stylized

Glitch

5. Adding New Transitions

To add a new transition manually:

1. Add an ITransitionDefinition entry to packages/core/src/transitions/catalog.ts
2. Set supportedProviders to the appropriate renderer(s)
3. Register the actual shader/implementation in the provider package (e.g. call registerCustomTransition() in engine-pixi)

To support a new rendering provider (e.g. react-skia), add your provider key to supportedProviders in each relevant catalog entry and implement the transition handler in your provider package.