@remotion/sdkv4.0.527

Build a composition preview and layer list for a Remotion authoring interface. The package combines <Player> playback with registered sequence data, selection, and synchronized hover.

warning

Experimental API: This package is not stable. Its public API may change without a major version bump.

Installation

Remotion CLI
npm
bun
pnpm
yarn

npx remotion add @remotion/sdk

npm i --save-exact @remotion/[email protected]

This assumes you are currently using v4.0.532 of Remotion.
Also update remotion and all `@remotion/*` packages to the same version.
Remove all ^ character in front of the version numbers of it as it can lead to a version conflict.

pnpm i @remotion/[email protected]

bun i @remotion/[email protected]

yarn --exact add @remotion/[email protected]

Install @remotion/player as well. Keep the Remotion packages on the same version.

Basic example

Pass the same controller to <Canvas> and your layer list. showOutlines enables hover and selection on the composition.

Editor.tsx
import {
  Canvas,
  getCanvasSelectionItemKey,
  getCanvasSequenceNodePathInfo,
  useCanvasController,
  useCanvasSelection,
  useCanvasSequenceHover,
  type CanvasSelectionItem,
  type TimelineTrackData,
} from '@remotion/sdk';
import {useSyncExternalStore} from 'react';
import {Video} from './Video';

const Layer = ({
  track,
  controller,
  items,
  selectedKeys,
}: {
  track: TimelineTrackData;
  controller: ReturnType<typeof useCanvasController>;
  items: CanvasSelectionItem[];
  selectedKeys: Set<string>;
}) => {
  const nodePathInfo = getCanvasSequenceNodePathInfo(track);
  const item: CanvasSelectionItem = {type: 'sequence', nodePathInfo};
  const key = getCanvasSelectionItemKey(item);
  const {hovered, onPointerEnter, onPointerLeave} = useCanvasSequenceHover(
    controller.hover,
    nodePathInfo,
    'timeline',
  );

  return (
    <button
      aria-pressed={selectedKeys.has(key)}
      onPointerEnter={onPointerEnter}
      onPointerLeave={onPointerLeave}
      onClick={(event) => controller.selection.select(
        item,
        {shiftKey: event.shiftKey, toggleKey: event.metaKey || event.ctrlKey},
        items,
      )}
    >
      {hovered ? '● ' : ''}{track.sequence.displayName ?? track.sequence.type}
    </button>
  );
};

export const Editor = () => {
  const controller = useCanvasController();
  const tracks = useSyncExternalStore(
    controller.timeline.subscribe,
    controller.timeline.getSnapshot,
    controller.timeline.getSnapshot,
  );
  const selection = useCanvasSelection(controller.selection);
  const items: CanvasSelectionItem[] = tracks.map((track) => ({
    type: 'sequence',
    nodePathInfo: getCanvasSequenceNodePathInfo(track),
  }));
  const selectedKeys = new Set(selection.selectedItems.map(getCanvasSelectionItemKey));

  return (
    <>
      <Canvas
        controller={controller}
        showOutlines
        component={Video}
        compositionWidth={1920}
        compositionHeight={1080}
        durationInFrames={150}
        fps={30}
      />
      <div>
        {tracks.map((track) => (
          <Layer
            key={track.sequence.id}
            track={track}
            controller={controller}
            items={items}
            selectedKeys={selectedKeys}
          />
        ))}
      </div>
    </>
  );
};

The timeline contains registered <Sequence> and other sequence tracks from the mounted composition. The Canvas does not edit source files or provide timeline controls; your interface owns those actions.

Selection identity

The built-in getCanvasSequenceNodePathInfo() uses a source identity when available. Otherwise it falls back to a mounted sequence ID, which can change after a remount.

If your editor has the source code, register the source node of each sequence with setSequenceNodePaths(). For projects compiled with @remotion/browser-bundler, getCanvasSequenceSourceLocation() returns the file and position of each sequence's JSX element, which getNodes() maps to a node path. Alternatively, pass a custom resolveSequenceNodePathInfo to <Canvas> and use the same resolver for layer items. Return null for tracks that should not be selectable.

An outline requires a registered DOM element. A <Sequence layout="none"> has no outline of its own.

Editing

The Canvas exposes the controls of each mounted element: its interactivity schema and current prop values. Use them to build an inspector, and write changes to the source with @remotion/codemods.

While a value is being dragged, controller.overrides previews it on the canvas immediately. Persist the final value when the gesture ends, then clear the override.

Pass onSequencePropsChange to <Canvas> to let users move elements by dragging their outlines or pressing the arrow keys. The Canvas previews the movement itself and reports the final style.translate values to the callback. With getSequencePropStatuses, it respects how the source is written: computed values cannot be moved and keyframed values receive a keyframe.

Keyframesv4.0.530

Props animated with interpolate() are reported as keyframed by getNodeProps(). The package converts between the frame clock of the interpolation and the composition timeline, so a timeline can show and edit those keyframes like the Remotion Studio does.

getCanvasKeyframes() places the keyframes of a prop on the timeline. getCanvasKeyframeToggle() describes a keyframe button at the playhead and returns the change that adds or removes a keyframe there, while getCanvasPropValueAtFrame() reads the animated value for an inspector. startCanvasKeyframeDrag() moves keyframes with the pointer, previewing the result through controller.overrides. Every edit is a CanvasKeyframeChange whose operation you pass to updateNodeKeyframes().

Between two keyframes, getCanvasKeyframeEasingSegments() describes the segments a timeline can draw and select, and getCanvasKeyframeEasingChange() sets the easing of one, with canvasKeyframeEasingPresets for a picker. getCanvasKeyframeSettings() and getCanvasKeyframeSettingsChange() read and write the extrapolation, output mode and posterize of the interpolation. getCanvasKeyframeChangeOverride() turns any change into an override, so the canvas shows it before the source is updated.