Skip to content

🎥 Make videos programmatically with React

@remotion/canvas: Add heterogeneous selection state

JonnyBurger4bc01755989a
diff --git a/packages/canvas/README.md b/packages/canvas/README.md
index 5b42d519d8..78e215b23e 100644
--- a/packages/canvas/README.md
+++ b/packages/canvas/README.md
@@ -14,6 +14,19 @@ controller.timeline.subscribe(() => {
console.log(controller.timeline.getSnapshot());
});
+controller.selection.subscribe(() => {
+ console.log(controller.selection.getSnapshot());
+});
+
+controller.selection.select(
+ {
+ type: 'property',
+ entity: {type: 'sequence', id: 'title'},
+ propertyPath: ['style', 'opacity'],
+ },
+ 'add',
+);
+
<Canvas
controller={controller}
component={MyComposition}
diff --git a/packages/canvas/src/canvas-controller.ts b/packages/canvas/src/canvas-controller.ts
index daba37e089..961b651006 100644
--- a/packages/canvas/src/canvas-controller.ts
+++ b/packages/canvas/src/canvas-controller.ts
@@ -1,13 +1,29 @@
-import {useState} from 'react';
+import {useState, useSyncExternalStore} from 'react';
import type {TSequence} from 'remotion';
import {calculateTimeline} from './calculate-timeline';
import type {TimelineTrackData} from './get-timeline-sequence-sort-key';
+import {
+ getCanvasSelectionItemKey,
+ type CanvasSelectionItem,
+ type CanvasSelectionMode,
+ type CanvasSelectionSnapshot,
+} from './selection';
export type CanvasController = {
readonly timeline: {
readonly getSnapshot: () => readonly TimelineTrackData[];
readonly subscribe: (listener: () => void) => () => void;
};
+ readonly selection: {
+ readonly getSnapshot: () => CanvasSelectionSnapshot;
+ readonly subscribe: (listener: () => void) => () => void;
+ readonly select: (
+ item: CanvasSelectionItem,
+ mode: CanvasSelectionMode,
+ ) => void;
+ readonly setSelectedItems: (items: readonly CanvasSelectionItem[]) => void;
+ readonly clear: () => void;
+ };
};
type CanvasControllerInternals = {
@@ -21,36 +37,112 @@ const controllerInternals = new WeakMap<
>();
export const createCanvasController = (): CanvasController => {
- let snapshot: readonly TimelineTrackData[] = [];
- const listeners = new Set<() => void>();
+ let timelineSnapshot: readonly TimelineTrackData[] = [];
+ let selectionSnapshot: CanvasSelectionSnapshot = {
+ selectedItems: [],
+ anchor: null,
+ };
+ const timelineListeners = new Set<() => void>();
+ const selectionListeners = new Set<() => void>();
- const updateSnapshot = (nextSnapshot: readonly TimelineTrackData[]) => {
- snapshot = nextSnapshot;
- for (const listener of listeners) {
+ const updateTimelineSnapshot = (
+ nextSnapshot: readonly TimelineTrackData[],
+ ) => {
+ timelineSnapshot = nextSnapshot;
+ for (const listener of timelineListeners) {
+ listener();
+ }
+ };
+
+ const updateSelectionSnapshot = (
+ selectedItems: readonly CanvasSelectionItem[],
+ anchor: CanvasSelectionItem | null,
+ ) => {
+ selectionSnapshot = {selectedItems, anchor};
+ for (const listener of selectionListeners) {
listener();
}
};
const controller: CanvasController = {
timeline: {
- getSnapshot: () => snapshot,
+ getSnapshot: () => timelineSnapshot,
subscribe: (listener) => {
- listeners.add(listener);
- return () => listeners.delete(listener);
+ timelineListeners.add(listener);
+ return () => timelineListeners.delete(listener);
},
},
+ selection: {
+ getSnapshot: () => selectionSnapshot,
+ subscribe: (listener) => {
+ selectionListeners.add(listener);
+ return () => selectionListeners.delete(listener);
+ },
+ select: (item, mode) => {
+ const itemKey = getCanvasSelectionItemKey(item);
+ const selectedItemIndex = selectionSnapshot.selectedItems.findIndex(
+ (selectedItem) => getCanvasSelectionItemKey(selectedItem) === itemKey,
+ );
+
+ if (mode === 'replace') {
+ updateSelectionSnapshot([item], item);
+ return;
+ }
+
+ if (mode === 'add') {
+ if (selectedItemIndex === -1) {
+ updateSelectionSnapshot(
+ [...selectionSnapshot.selectedItems, item],
+ item,
+ );
+ }
+
+ return;
+ }
+
+ if (selectedItemIndex === -1) {
+ updateSelectionSnapshot(
+ [...selectionSnapshot.selectedItems, item],
+ item,
+ );
+ return;
+ }
+
+ const nextSelectedItems = selectionSnapshot.selectedItems.filter(
+ (_selectedItem, index) => index !== selectedItemIndex,
+ );
+ updateSelectionSnapshot(
+ nextSelectedItems,
+ nextSelectedItems.at(-1) ?? null,
+ );
+ },
+ setSelectedItems: (items) => {
+ const keys = new Set<string>();
+ const selectedItems = items.filter((item) => {
+ const key = getCanvasSelectionItemKey(item);
+ if (keys.has(key)) {
+ return false;
+ }
+
+ keys.add(key);
+ return true;
+ });
+ updateSelectionSnapshot(selectedItems, selectedItems.at(-1) ?? null);
+ },
+ clear: () => updateSelectionSnapshot([], null),
+ },
};
controllerInternals.set(controller, {
setSequences: (sequences) => {
- updateSnapshot(
+ updateTimelineSnapshot(
calculateTimeline({
sequences,
overrideIdsToNodePaths: {},
}),
);
},
- clear: () => updateSnapshot([]),
+ clear: () => updateTimelineSnapshot([]),
});
return controller;
@@ -61,6 +153,16 @@ export const useCanvasController = (): CanvasController => {
return controller;
};
+export const useCanvasSelection = (
+ controller: CanvasController,
+): CanvasSelectionSnapshot => {
+ return useSyncExternalStore(
+ controller.selection.subscribe,
+ controller.selection.getSnapshot,
+ controller.selection.getSnapshot,
+ );
+};
+
export const getCanvasControllerInternals = (
controller: CanvasController,
): CanvasControllerInternals => {
diff --git a/packages/canvas/src/index.ts b/packages/canvas/src/index.ts
index 1c4ba36102..b7134a2661 100644
--- a/packages/canvas/src/index.ts
+++ b/packages/canvas/src/index.ts
@@ -1,13 +1,12 @@
+export {calculateTimeline} from './calculate-timeline';
export {Canvas} from './canvas';
export type {CanvasProps} from './canvas';
-export {createCanvasController, useCanvasController} from './canvas-controller';
+export {
+ createCanvasController,
+ useCanvasController,
+ useCanvasSelection,
+} from './canvas-controller';
export type {CanvasController} from './canvas-controller';
-export {calculateTimeline} from './calculate-timeline';
-export type {
- SequenceNodePathInfo,
- TimelineTrackData,
- TimelineTrackWithOriginalTimings,
-} from './get-timeline-sequence-sort-key';
export {getConnectedCompositions} from './get-connected-compositions';
export {
getCascadedStart,
@@ -17,6 +16,19 @@ export {
} from './get-sequence-visible-range';
export {getTimelineNestedLevel} from './get-timeline-nestedness';
export {getTimelineSequenceSortKey} from './get-timeline-sequence-sort-key';
+export type {
+ SequenceNodePathInfo,
+ TimelineTrackData,
+ TimelineTrackWithOriginalTimings,
+} from './get-timeline-sequence-sort-key';
+export {getCanvasSelectionItemKey} from './selection';
+export type {
+ CanvasEntityReference,
+ CanvasPropertyPath,
+ CanvasSelectionItem,
+ CanvasSelectionMode,
+ CanvasSelectionSnapshot,
+} from './selection';
export {
compareNonceHistories,
sortItemsByNonceHistory,
diff --git a/packages/canvas/src/selection.ts b/packages/canvas/src/selection.ts
new file mode 100644
index 0000000000..6f9f2b8a40
--- /dev/null
+++ b/packages/canvas/src/selection.ts
@@ -0,0 +1,77 @@
+export type CanvasEntityReference =
+ | {
+ readonly type: 'sequence';
+ readonly id: string;
+ }
+ | {
+ readonly type: 'effect';
+ readonly id: string;
+ readonly sequenceId: string;
+ }
+ | {
+ readonly type: 'guide';
+ readonly id: string;
+ };
+
+export type CanvasPropertyPath = readonly (string | number)[];
+
+export type CanvasSelectionItem =
+ | {
+ readonly type: 'entity';
+ readonly entity: CanvasEntityReference;
+ }
+ | {
+ readonly type: 'property';
+ readonly entity: CanvasEntityReference;
+ readonly propertyPath: CanvasPropertyPath;
+ }
+ | {
+ readonly type: 'keyframe';
+ readonly entity: CanvasEntityReference;
+ readonly propertyPath: CanvasPropertyPath;
+ readonly frame: number;
+ }
+ | {
+ readonly type: 'easing';
+ readonly entity: CanvasEntityReference;
+ readonly propertyPath: CanvasPropertyPath;
+ readonly fromFrame: number;
+ readonly toFrame: number;
+ readonly segmentIndex: number;
+ };
+
+export type CanvasSelectionSnapshot = {
+ readonly selectedItems: readonly CanvasSelectionItem[];
+ readonly anchor: CanvasSelectionItem | null;
+};
+
+export type CanvasSelectionMode = 'replace' | 'add' | 'toggle';
+
+export const getCanvasSelectionItemKey = (
+ item: CanvasSelectionItem,
+): string => {
+ const entity =
+ item.entity.type === 'effect'
+ ? [item.entity.type, item.entity.sequenceId, item.entity.id]
+ : [item.entity.type, item.entity.id];
+
+ switch (item.type) {
+ case 'entity':
+ return JSON.stringify([item.type, entity]);
+ case 'property':
+ return JSON.stringify([item.type, entity, item.propertyPath]);
+ case 'keyframe':
+ return JSON.stringify([item.type, entity, item.propertyPath, item.frame]);
+ case 'easing':
+ return JSON.stringify([
+ item.type,
+ entity,
+ item.propertyPath,
+ item.fromFrame,
+ item.toFrame,
+ item.segmentIndex,
+ ]);
+ default:
+ throw new Error('Unknown Canvas selection item');
+ }
+};
diff --git a/packages/canvas/src/test/selection.test.ts b/packages/canvas/src/test/selection.test.ts
new file mode 100644
index 0000000000..0febc855fd
--- /dev/null
+++ b/packages/canvas/src/test/selection.test.ts
@@ -0,0 +1,56 @@
+import {expect, test} from 'bun:test';
+import {createCanvasController, type CanvasSelectionItem} from '../index';
+
+test('stores a heterogeneous multi-selection through the public controller', () => {
+ const controller = createCanvasController();
+ let updates = 0;
+ const unsubscribe = controller.selection.subscribe(() => {
+ updates++;
+ });
+ const sequence: CanvasSelectionItem = {
+ type: 'entity',
+ entity: {type: 'sequence', id: 'intro'},
+ };
+ const effectProperty: CanvasSelectionItem = {
+ type: 'property',
+ entity: {type: 'effect', id: 'blur', sequenceId: 'intro'},
+ propertyPath: ['radius'],
+ };
+ const easing: CanvasSelectionItem = {
+ type: 'easing',
+ entity: {type: 'sequence', id: 'intro'},
+ propertyPath: ['style', 'opacity'],
+ fromFrame: 0,
+ toFrame: 30,
+ segmentIndex: 0,
+ };
+
+ controller.selection.select(sequence, 'replace');
+ controller.selection.select(effectProperty, 'add');
+ controller.selection.select(easing, 'add');
+
+ expect(controller.selection.getSnapshot()).toEqual({
+ selectedItems: [sequence, effectProperty, easing],
+ anchor: easing,
+ });
+
+ controller.selection.select(effectProperty, 'toggle');
+ expect(controller.selection.getSnapshot()).toEqual({
+ selectedItems: [sequence, easing],
+ anchor: easing,
+ });
+
+ controller.selection.setSelectedItems([sequence, sequence, effectProperty]);
+ expect(controller.selection.getSnapshot()).toEqual({
+ selectedItems: [sequence, effectProperty],
+ anchor: effectProperty,
+ });
+
+ controller.selection.clear();
+ expect(controller.selection.getSnapshot()).toEqual({
+ selectedItems: [],
+ anchor: null,
+ });
+ expect(updates).toBe(6);
+ unsubscribe();
+});
diff --git a/packages/player-example/pages/canvas.tsx b/packages/player-example/pages/canvas.tsx
index e3bc16e921..e015125cfe 100644
--- a/packages/player-example/pages/canvas.tsx
+++ b/packages/player-example/pages/canvas.tsx
@@ -1,4 +1,11 @@
-import {Canvas, useCanvasController} from '@remotion/canvas';
+import {
+ Canvas,
+ getCanvasSelectionItemKey,
+ useCanvasController,
+ useCanvasSelection,
+ type CanvasSelectionItem,
+ type CanvasSelectionMode,
+} from '@remotion/canvas';
import React, {useSyncExternalStore} from 'react';
import {AbsoluteFill, Sequence, useCurrentFrame} from 'remotion';
@@ -44,6 +51,10 @@ const CanvasPage: React.FC = () => {
controller.timeline.getSnapshot,
controller.timeline.getSnapshot,
);
+ const selection = useCanvasSelection(controller);
+ const selectedKeys = new Set(
+ selection.selectedItems.map(getCanvasSelectionItemKey),
+ );
return (
<main
@@ -78,35 +89,155 @@ const CanvasPage: React.FC = () => {
acknowledgeRemotionLicense
style={{width: '100%'}}
/>
- <section
- style={{
- border: '1px solid #d1d5db',
- borderRadius: 8,
- padding: 20,
- }}
- >
- <h2 style={{marginTop: 0}}>Mounted layers ({layers.length})</h2>
- {layers.length === 0 ? (
- <p>No layers mounted.</p>
- ) : (
- <ol style={{paddingLeft: 24}}>
- {layers.map((layer) => (
- <li
- key={layer.sequence.id}
- style={{marginBottom: 12, paddingLeft: layer.depth * 16}}
- >
- <strong>
- {layer.sequence.displayName ?? layer.sequence.type}
- </strong>
- <div style={{color: '#555', fontSize: 14}}>
- {layer.sequence.type} · frame {layer.sequence.from} ·{' '}
- {layer.sequence.duration} frames
- </div>
- </li>
- ))}
- </ol>
- )}
- </section>
+ <div>
+ <section
+ style={{
+ border: '1px solid #d1d5db',
+ borderRadius: 8,
+ padding: 20,
+ }}
+ >
+ <h2 style={{marginTop: 0}}>Mounted layers ({layers.length})</h2>
+ {layers.length === 0 ? (
+ <p>No layers mounted.</p>
+ ) : (
+ <ol style={{paddingLeft: 24}}>
+ {layers.map((layer) => {
+ const entity = {
+ type: 'sequence' as const,
+ id: layer.sequence.id,
+ };
+ const layerSelection: CanvasSelectionItem = {
+ type: 'entity',
+ entity,
+ };
+ const opacitySelection: CanvasSelectionItem = {
+ type: 'property',
+ entity,
+ propertyPath: ['style', 'opacity'],
+ };
+ const easingSelection: CanvasSelectionItem = {
+ type: 'easing',
+ entity,
+ propertyPath: ['style', 'opacity'],
+ fromFrame: layer.sequence.from,
+ toFrame: Math.min(
+ layer.sequence.from + 30,
+ layer.sequence.from + layer.sequence.duration,
+ ),
+ segmentIndex: 0,
+ };
+ const layerSelected = selectedKeys.has(
+ getCanvasSelectionItemKey(layerSelection),
+ );
+ const opacitySelected = selectedKeys.has(
+ getCanvasSelectionItemKey(opacitySelection),
+ );
+ const easingSelected = selectedKeys.has(
+ getCanvasSelectionItemKey(easingSelection),
+ );
+
+ return (
+ <li
+ key={layer.sequence.id}
+ style={{
+ marginBottom: 16,
+ paddingLeft: layer.depth * 16,
+ }}
+ >
+ <button
+ type="button"
+ aria-pressed={layerSelected}
+ onClick={(event) => {
+ const mode: CanvasSelectionMode =
+ event.metaKey || event.ctrlKey
+ ? 'toggle'
+ : event.shiftKey
+ ? 'add'
+ : 'replace';
+ controller.selection.select(layerSelection, mode);
+ }}
+ style={{
+ backgroundColor: layerSelected ? '#ddd6fe' : 'white',
+ border: '1px solid #d1d5db',
+ borderRadius: 4,
+ padding: '6px 8px',
+ textAlign: 'left',
+ width: '100%',
+ }}
+ >
+ <strong>
+ {layer.sequence.displayName ?? layer.sequence.type}
+ </strong>
+ <div style={{color: '#555', fontSize: 14}}>
+ {layer.sequence.type} · frame {layer.sequence.from} ·{' '}
+ {layer.sequence.duration} frames
+ </div>
+ </button>
+ <div style={{display: 'flex', gap: 6, marginTop: 6}}>
+ <button
+ type="button"
+ aria-pressed={opacitySelected}
+ onClick={() =>
+ controller.selection.select(
+ opacitySelection,
+ 'toggle',
+ )
+ }
+ >
+ style.opacity
+ </button>
+ <button
+ type="button"
+ aria-pressed={easingSelected}
+ onClick={() =>
+ controller.selection.select(
+ easingSelection,
+ 'toggle',
+ )
+ }
+ >
+ Opacity easing
+ </button>
+ </div>
+ </li>
+ );
+ })}
+ </ol>
+ )}
+ </section>
+ <section
+ style={{
+ border: '1px solid #d1d5db',
+ borderRadius: 8,
+ marginTop: 16,
+ padding: 20,
+ }}
+ >
+ <h2 style={{marginTop: 0}}>
+ Selection ({selection.selectedItems.length})
+ </h2>
+ <p style={{fontSize: 14}}>
+ Click a layer to replace the selection. Shift-click adds a layer;
+ Command/Ctrl-click toggles it. Property and easing buttons toggle
+ heterogeneous items.
+ </p>
+ <button type="button" onClick={controller.selection.clear}>
+ Clear selection
+ </button>
+ <pre
+ style={{
+ backgroundColor: '#f3f4f6',
+ fontSize: 12,
+ overflowX: 'auto',
+ padding: 12,
+ whiteSpace: 'pre-wrap',
+ }}
+ >
+ {JSON.stringify(selection, null, 2)}
+ </pre>
+ </section>
+ </div>
</div>
</main>
);