Scene-based editing

Scenes provide a powerful way to organize complex video projects. Each scene has its own timeline with independent tracks and elements, plus bookmarks for marking important moments.

What is a scene?

A scene is a self-contained timeline within your project. Think of scenes as chapters in your video or different takes you can switch between.

apps/web/src/types/timeline.ts

export interface TScene {
  id: string;
  name: string;
  isMain: boolean;        // One scene must be marked as main
  tracks: TimelineTrack[];
  bookmarks: Bookmark[];
  createdAt: Date;
  updatedAt: Date;
}

Scene structure

Each scene maintains its own timeline state independently. Changes in one scene don’t affect others.

ScenesManager API

Creating and managing scenes

// Create a new scene
const sceneId = await editor.scenes.createScene({
  name: 'Take 2',
  isMain: false
});

// Switch to a scene
await editor.scenes.switchToScene({ sceneId });

// Rename a scene
await editor.scenes.renameScene({
  sceneId,
  name: 'Final Take'
});

// Delete a scene (cannot delete the main scene)
await editor.scenes.deleteScene({ sceneId });

// Get active scene
const activeScene = editor.scenes.getActiveScene();

// Get all scenes
const allScenes = editor.scenes.getScenes();

You cannot delete the main scene. At least one scene with isMain: true must always exist in the project.

Scene switching implementation

Here’s how scene switching is implemented:

apps/web/src/core/managers/scenes-manager.ts

async switchToScene({ sceneId }: { sceneId: string }): Promise<void> {
  const targetScene = this.list.find((s) => s.id === sceneId);

  if (!targetScene) {
    throw new Error("Scene not found");
  }

  const activeProject = this.editor.project.getActive();

  if (activeProject) {
    const updatedProject = {
      ...activeProject,
      currentSceneId: sceneId,
      metadata: {
        ...activeProject.metadata,
        updatedAt: new Date(),
      },
    };

    this.editor.project.setActiveProject({ project: updatedProject });
  }

  this.active = targetScene;
  this.notify();
}

Bookmarks

Bookmarks let you mark important moments on the timeline with optional notes and colors.

apps/web/src/types/timeline.ts

export interface Bookmark {
  time: number;       // Timeline position in seconds
  note?: string;      // Optional description
  color?: string;     // Optional color for visual identification
  duration?: number;  // Optional duration for ranged bookmarks
}

Working with bookmarks

// Toggle bookmark at current time
await editor.scenes.toggleBookmark({ time: 5.5 });

// Check if time is bookmarked
const isBookmarked = editor.scenes.isBookmarked({ time: 5.5 });

// Get bookmark at time
const bookmark = editor.scenes.getBookmarkAtTime({ time: 5.5 });

// Update bookmark properties
await editor.scenes.updateBookmark({
  time: 5.5,
  updates: {
    note: 'Important scene transition',
    color: '#ff6b6b',
    duration: 2  // Make it a ranged bookmark
  }
});

// Move bookmark to different time
await editor.scenes.moveBookmark({
  fromTime: 5.5,
  toTime: 7.0
});

// Remove bookmark
await editor.scenes.removeBookmark({ time: 5.5 });

Bookmarks are frame-accurate. The system automatically snaps bookmark times to the nearest frame based on your project’s FPS.

Scene lifecycle

Understanding how scenes are initialized and managed:

apps/web/src/core/managers/scenes-manager.ts

initializeScenes({
  scenes,
  currentSceneId,
}: {
  scenes: TScene[];
  currentSceneId?: string;
}): void {
  // Ensure at least one main scene exists
  const ensuredScenes = ensureMainScene({ scenes });
  
  // Ensure each scene has a main track
  const { scenes: scenesWithMainTracks, hasAddedMainTrack } =
    this.ensureScenesHaveMainTrack({ scenes: ensuredScenes });
  
  // Set active scene
  const currentScene = currentSceneId
    ? scenesWithMainTracks.find((s) => s.id === currentSceneId)
    : null;

  const fallbackScene = getMainScene({ scenes: scenesWithMainTracks });

  this.list = scenesWithMainTracks;
  this.active = currentScene || fallbackScene;
  this.notify();
}

Scene commands

All scene operations are implemented using the command pattern for undo/redo support:

CreateSceneCommand

Creates a new scene and adds it to the project.

DeleteSceneCommand

Removes a scene (with validation to prevent deleting main scene).

RenameSceneCommand

Changes the name of an existing scene.

ToggleBookmarkCommand

Adds or removes a bookmark at a specific time.

UpdateBookmarkCommand

Modifies bookmark properties like note, color, or duration.

MoveBookmarkCommand

Moves a bookmark from one time to another.

RemoveBookmarkCommand

Deletes a bookmark at a specific time.

Timeline integration

The TimelineManager retrieves its track data from the active scene:

apps/web/src/core/managers/timeline-manager.ts

getTracks(): TimelineTrack[] {
  return this.editor.scenes.getActiveScene()?.tracks ?? [];
}

updateTracks(newTracks: TimelineTrack[]): void {
  this.editor.scenes.updateSceneTracks({ tracks: newTracks });
  this.notify();
}

This tight integration means:

Timeline operations automatically update the active scene
Switching scenes instantly changes the visible timeline
Each scene’s timeline state is preserved independently

Use cases for scenes

Multiple takes

Create a scene for each take of the same content. Switch between them to compare and choose the best version.

Project chapters

Organize long videos into logical chapters. Each scene represents a major section of your video.

A/B variations

Create alternative versions of the same content with different edits, effects, or timing.

Template variations

Build multiple variations of a video template with different content but similar structure.

Best practices

Name scenes clearly

Use descriptive names like “Intro”, “Take 3”, or “Short Version” instead of generic names.

Use bookmarks liberally

Mark important moments, transitions, or areas that need review with bookmarks.

Keep one main scene

Designate your primary edit as the main scene for easy identification.

Clean up unused scenes

Delete scenes you’re no longer using to keep your project organized.

EditorCore - Understanding the singleton architecture
Timeline - Working with tracks and elements within scenes
Commands - Scene operations use commands for undo/redo
Actions - User-triggered scene operations

⌘I

Get Started

Core Concepts

Features

Development

Scene-based editing

What is a scene?

Scene structure

ScenesManager API

Creating and managing scenes

Scene switching implementation

Bookmarks

Working with bookmarks

Scene lifecycle

Scene commands

CreateSceneCommand

DeleteSceneCommand

RenameSceneCommand

ToggleBookmarkCommand

UpdateBookmarkCommand

MoveBookmarkCommand

RemoveBookmarkCommand

Timeline integration

Use cases for scenes

Best practices

Name scenes clearly

Use bookmarks liberally

Keep one main scene

Clean up unused scenes

​What is a scene?

​Scene structure

​ScenesManager API

​Creating and managing scenes

​Scene switching implementation

​Bookmarks

​Working with bookmarks

​Scene lifecycle

​Scene commands

CreateSceneCommand

DeleteSceneCommand

RenameSceneCommand

ToggleBookmarkCommand

UpdateBookmarkCommand

MoveBookmarkCommand

RemoveBookmarkCommand

​Timeline integration

​Use cases for scenes

​Best practices

Name scenes clearly

Use bookmarks liberally

Keep one main scene

Clean up unused scenes

​Related concepts

What is a scene?

Scene structure

ScenesManager API

Creating and managing scenes

Scene switching implementation

Bookmarks

Working with bookmarks

Scene lifecycle

Scene commands

Timeline integration

Use cases for scenes

Best practices

Related concepts