Installation

The Preview SDK lets you embed a video preview in your own web app. This is useful when you want to give your users a live preview, so they can customize the video before you render the final one through the API.

How it fits together

The SDK is a JavaScript library that runs in the browser and draws the video with the same engine the API renders with. That is the reason to use it rather than a video file or a mock-up: what the user sees in the preview is what the API will produce. It plays a template from your project or any video described in RenderScript and applies changes the moment your app makes them.

The final file is rendered by the API, on your server's request, from the same template and the same changes. Rendering an MP4 in the browser is too unreliable across devices, as explained under Rendering the final video. That split also decides where the keys live. The SDK signs in with your project's public token. The token can show videos but not render them and is therefore safe to publish. Your API key stays on the server.

Requirements

The preview renders video in real time on the user's device, which takes more performance than most phones and tablets have. It therefore runs in desktop browsers only: best on Chrome, Edge, and Opera, while Safari and Firefox are supported too, though playback may be less smooth. To also support phones and tablets, show them a video rendered through the API instead of the live preview. Rendered at a low resolution with the render_scale parameter, that video is quick and cheap to make. Check the device before you load the SDK:

1const isMobile = navigator.userAgentData?.mobile ?? /Mobi|Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
2
3if (isMobile) {
4  // Show a video rendered through the API
5} else {
6  const { Preview } = await import('@creatomate/preview');
7  // Start the live preview
8}

Install the SDK

The SDK is a package on NPM that works with any framework and in plain JavaScript.

You can also import it from a CDN, without installing anything:

1import { Preview } from 'https://cdn.jsdelivr.net/npm/@creatomate/[email protected]/+esm';

Get your public token

You find the public token in the dashboard under Project Settings. It can only load the templates of that project; rendering is done through the API with your API key, from your server.

Your first preview

The preview needs an empty element to live in and fills whatever size you give that element.

1<div id="player" style="width: 480px; aspect-ratio: 9 / 16"></div>

Then create a preview, wait for it to be ready, and load a template from your project:

1import { Preview } from '@creatomate/preview';
2
3const preview = new Preview(document.getElementById('player'), 'player', 'YOUR_PUBLIC_TOKEN');
4
5preview.onReady = async () => {
6  await preview.loadTemplate('YOUR_TEMPLATE_ID');
7  await preview.play();
8};

Because the SDK loads its engine in the background, the preview isn't usable the moment you create it. Wait for onReady before you call anything else; a call before that throws an error. The second argument is the mode. Player shows the video like a video player and suits an app where the user supplies content and the design stays fixed. Interactive turns the preview into a canvas on which the user moves elements. Both are explained under Player and interactive mode.

Next step

Where the video comes from and how your app changes it: Loading and changing content.