Clip types

Placeholder clips

A Placeholder clip occupies a slot on the timeline while its media is still loading. When the media becomes ready, the placeholder is replaced by the real clip in place.

Useful when:

Media is uploaded asynchronously and the UI needs to render a “filler” tile immediately.
A batch import processes large files one by one and you want the timeline to reflect intermediate state.
A project is deserialized with media that still needs to be hashed or transcoded.

Register a placeholder

const mediaData = Engine.getInstance().getLibrary().getMediaById(mediaId);

await mediaData.addPlaceholderClip(placeholderClipId);

The Library holds the list of placeholder clip ids per media entry. Once the media finishes loading (library:media:ready), the Engine replaces each placeholder with a clip of the correct type (ImageClip, VideoClip, and so on) using the media’s metadata.

Listening for replacement

When a placeholder is replaced by the real clip, the engine fires a clip:replaced event. Use this to update your UI:

Engine.getInstance().on("clip:replaced", ({ oldClipId, newClip }) => {
  console.log(`Placeholder ${oldClipId} replaced with ${newClip.constructor.name}`);
  // Update your UI state, re-bind event listeners, etc.
});

Common patterns

Drag-and-Drop upload

When a user drops a file onto the timeline, immediately create a placeholder so the slot appears before the upload finishes:

// 1. Reserve a slot on the timeline
const placeholderId = crypto.randomUUID();
const mediaData = Engine.getInstance().getLibrary().getMediaById(pendingMediaId);
await mediaData.addPlaceholderClip(placeholderId);

// 2. Upload the file in the background
const mediaId = await Engine.getInstance().getLibrary().addMedia(file);
// The placeholder is replaced automatically once the media is ready.

Batch import

When importing a project with dozens of assets, placeholders keep the timeline interactive while media loads one by one. Each asset resolves independently, so the user sees clips appear progressively rather than waiting for everything to finish.