Player and interactive mode

setMode, setZoom, setTool, setActiveElements, setActiveComposition, undo, redo, clearHistory

The preview has two modes. In player mode it shows the video like a video player, and your app changes the video through its methods. That is the mode the previous pages assume, and the right choice when the user supplies content and the design stays as you made it; when in doubt, choose player. In interactive mode the preview becomes a canvas on which the user selects, drags, resizes, and rotates elements, much like in Creatomate's template editor. Choose it when the user should change the video itself, and switch between the modes at any time with setMode. The rest of this page is about interactive mode and what it adds: zoom, selection, drawing tools, undo, and saving the result.

Interactive mode

1const preview = new Preview(document.getElementById('canvas'), 'interactive', 'YOUR_PUBLIC_TOKEN');
2
3preview.onReady = async () => {
4  await preview.loadTemplate('YOUR_TEMPLATE_ID');
5  await preview.setZoom('centered');
6};

Zoom

setZoom(mode, scale?)

By default the user can pan and zoom the canvas, like in the template editor; that is 'free'. It suits a layout with room around the video. For a fixed layout, 'centered' keeps the video fitted and centered, 'auto' fits it to the viewport, and 'fixed' holds the scale you pass (1 is 100%). onScaleChange reports the scale.

Selection

setActiveElements(elementIds), setActiveComposition(elementId)

To show or edit what the user selected, your app needs to know which elements those are. onActiveElementsChange gives you their IDs, and the state has their names and properties:

1preview.onActiveElementsChange = (elementIds) => {
2  const names = elementIds.map((id) => preview.findElement((element) => element.source.id === id)?.source.name);
3  // Show the selection in your UI
4};

The other direction exists too: setActiveElements selects elements from code, for example when the user picks one from a list in your app. A composition is a scene with its own elements. setActiveComposition opens one for editing and null returns to the main composition; onActiveCompositionChange reports the switch.

Drawing tools

setTool(tool)

To let users add to the video rather than only move what is there, change the mouse tool: 'pen', 'text', 'ellipse', and 'rectangle' draw a new element, and 'default' selects. onToolChange reports the tool.

Undo and redo

undo(), redo(), clearHistory(stack?)

When the user edits the video, they expect undo, and the SDK keeps the history for you. Every change the user makes on the canvas is an undo step. So is a change from code with applyModifications, the method that changes the video itself. setModifications creates no undo step, by design: it's an overlay on the video, not an edit to the document. undo() and redo() step through the history; the state tells you whether there is anything to step to:

1preview.onStateChange = (state) => {
2  undoButton.disabled = !state.undo;
3  redoButton.disabled = !state.redo;
4};
5
6undoButton.onclick = () => preview.undo();
7redoButton.onclick = () => preview.redo();

clearHistory() forgets the history, or one side of it with 'undo' or 'redo'.

Save and restore

When the user changes the video itself, the video's JSON is what your app saves. getSource() returns the whole video as RenderScript, with every change the user made; store that wherever your app keeps its data. To bring it back, load it with setSource:

1const saved = preview.getSource();      // save this with the user's project
2
3await preview.setSource(saved, true);   // later: bring it back, as an undo step

Loading is not an undo step unless you ask for one with the second argument, as you would for a restore the user may regret. After a save, clearHistory() makes the saved state the new starting point. The same JSON renders the final video, as the source of a render.

Next step

Everything the preview reports to your app, and why it's events rather than return values: Events.