React 18

The React component VideoEditor renders the video editor inside your React 18 application. The code is the same as for React 19.

InstallationCopy Anchor Link

npm install @layermetry/media-editor

The package has no runtime dependencies. The editor carries its own copy of React, so it does not depend on the React version of your application.

RequirementsCopy Anchor Link

• React 18.2 or 18.3. See Supported React versions.
• A license key. See License keys.
• A page served over HTTPS, or from localhost. See Requirements.

UsageCopy Anchor Link

Import VideoEditor from @layermetry/media-editor/react. The editor fills the element that contains it, so give that element a size.

import { VideoEditor } from '@layermetry/media-editor/react';

export default function App() {
  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <VideoEditor
        licenseKey="YOUR_LICENSE_KEY"
        onExport={(file) => console.log(`Exported ${file.name}: ${file.size} bytes`)}
        onClose={() => console.log('The editor was closed')}
      />
    </div>
  );
}

For each complete App.tsx on this page, use a Vite React 18 TypeScript project. Install the package above, replace your main App.tsx with one complete example at a time, and replace YOUR_LICENSE_KEY with a key valid for your origin. Start the development server:

npm run dev

Open the address printed by Vite. The editor fills the browser window in the Usage example; its export and close callbacks log to the browser console. Later JSX excerpts show only the setting or callback being discussed; they are fragments, not standalone components. Keep the required props, imports, helpers, and surrounding UI from the complete file below each excerpt.

The examples that call your backend need the routes and response formats named beside their complete files. Relative routes need your application server or a Vite proxy; npm run dev does not create those routes. Addresses on example.com and provider-key placeholders must be replaced. For content and export examples, supply your own small playable clip, sound file, or picture as indicated. These files and servers are not bundled with this page.

licenseKey and onClose are required. The editor calls onClose when the user presses the close button. Save & Exit closes it when the first frame is written; the completed file reaches onExport later.

Every render passes the complete set of props to the editor. A prop you stop passing goes back to its default value.

Launch from a buttonCopy Anchor Link

Render the editor only while it is open, and close it in onClose:

import { useState } from 'react';
import { VideoEditor } from '@layermetry/media-editor/react';

export default function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <main>
      <button onClick={() => setIsOpen(true)}>Edit video</button>

      {isOpen && (
        <div style={{ position: 'fixed', inset: 0, zIndex: 1000 }}>
          <VideoEditor
            licenseKey="YOUR_LICENSE_KEY"
            onExport={(file) => console.log(`Exported ${file.name}`)}
            onClose={() => setIsOpen(false)}
          />
        </div>
      )}
    </main>
  );
}

When the component is removed, the editor stops and releases its resources.

ConfigurationCopy Anchor Link

Pass configuration options as props. Options lists every prop.

Layout and sizingCopy Anchor Link

width and height size the editor's container; omitted values fill its parent.

Use numeric values for pixels, such as width={390}, or CSS strings, such as height="80vh". The complete example below switches between narrow and wide containers and adds a fullscreen button.

Container sizingCopy Anchor Link

A numeric size is in pixels. A string accepts any CSS size, such as '80vh' or 'calc(100vh - 64px)'. Both props default to '100%'. Give the parent a height when you use these defaults. The editor measures its container continuously and adjusts when that container changes size.

Compact layoutCopy Anchor Link

The editor uses the compact layout below 768 pixels and the regular layout from 768 pixels. The container determines the layout, including in a narrow desktop side panel.

The tool rail becomes a bottom dock, and tools open as sheets. A selected item shows a small action menu configured by itemActions. Without darkMode, compact mode uses the dark theme. See Theming and UI customization.

Fullscreen modeCopy Anchor Link

The editor has no fullscreen button. Call requestFullscreen() on its container after a user click or key press. Exit fullscreen before removing that container. To fill the browser window without fullscreen, use position: fixed and inset: 0 on the parent.

Editing outside canvasCopy Anchor Link

Selected or dragged items remain visible in the gray area outside the canvas, with their outside parts dimmed. Resize and rotation handles remain usable. Deselecting an item clips it at the canvas edge. The export contains only the canvas.

Snapping aligns with the canvas, not with other items. Move into canvas is in the right-click menu, respects position locks and takes one undo step. Markers do not appear in exported files.

See Canvas editing for the recovery steps.

ThemingCopy Anchor Link

Theming changes the editor's colors, control fonts, corners, and logo. Canvas content keeps its own styling.

ColorsCopy Anchor Link

theme sets colors by role name. Each name you give replaces one color. Every name you leave out keeps its default.

<VideoEditor
  theme={{
    primary: '#7C3AED',
    accent: '#7C3AED',
    brand: '#7C3AED',
    selected: '#7C3AED',
    focus: '#7C3AED',
    link: '#7C3AED',
  }}
/>

View full size

A value is any CSS color, such as #7C3AED, or a color name from the editor's palette, such as gray.200.

There are 35 role names:

TypeScript lists the names as the type SemanticRole.

A few dark colors over the light palette give a mix: the names you did not set stay light. For a dark design, also pass darkMode={true}, so that the dark palette is the base. Or set all 35 names.

Customization StudioCopy Anchor Link

With showThemeCreator set to true, the palette button opens the Customization Studio. Choose colors, fonts, corners, icons and tool visibility there. Copy settings copies one JSON object. Download .json saves it as editor-settings.json.

The Settings tab starts from your supplied theme, logo, data icons and UI settings. It includes your edits. The file contains no license key or callbacks. React component icons are omitted because the file stores data only. Closing the Studio restores your supplied settings. Copy or download changes before closing it.

Logo edits appear immediately in the editor’s top bar while the Studio is open. Clearing the field removes the logo from the preview. Closing the Studio restores your supplied logo.

The Bar tab previews the real toolbar for each item type. Nothing selected previews the page bar. For a selected-item control, change its label, choose Default, Icon only, Words only or Both, move it up or down, or hide it. These settings are saved in ui.selection.

Tools marked (off by default) enter the rail order only when you enable them. Reordering the rail does not enable those tools. Reset restores the settings you supplied when the Studio opened.

Apply the settings fileCopy Anchor Link

Import the downloaded JSON and spread the whole settings object into the options from your existing host.

import settings from './editor-settings.json';

// Add this spread to the existing editor component.
<VideoEditor {...settings} licenseKey="YOUR_LICENSE_KEY"
  onClose={handleClose} />

The video settings file can also contain enableThemeToggle. A custom theme has no light/dark pair, so it hides the switch and overrides darkMode while active.

icons accepts IconData: { svg: '<svg …></svg>' } or { url: '/icons/plus.svg' }. SVG text is limited to 8,192 UTF-8 bytes and cannot contain a script tag, JavaScript URL or event-handler attribute. Icon addresses use HTTPS, image data URLs, relative paths or HTTP on localhost, 127.0.0.1 or [::1]. A refused standard icon keeps the built-in icon with one warning. Custom actions accept icon data only; the standard icon map also accepts React components.

The JSON file contains icon data. It contains no React components. Your page loads the font files named by typography. See Editor settings for complete files and the settings table.

The Studio is a development tool. Its button is hidden by default. Set showThemeCreator to true in your development build only.

The four status names, success, info, warning, and danger, are never worked out from your brand colors. Set them yourself if you want to change them.

Default: the Layermetry teal palette.

CornersCopy Anchor Link

radii sets the rounding of the editor's buttons, fields, and cards. Each value is a CSS length.

<VideoEditor
  radii={{ sm: '2px', md: '4px', lg: '8px', full: '9999px' }}
/>

sm is for small fields, such as the zoom percentage box and the width and height boxes in the Resize canvas panel. md is for buttons. lg is for cards inside a panel, such as the text card in the Text panel. full is for round buttons. The outer edge of the docked Export panel does not use lg. Default: the built-in rounding.

FontsCopy Anchor Link

typography sets the fonts of the editor's panels, menus, and buttons. It takes three CSS font-family values:

<VideoEditor
  typography={{ heading: 'Georgia, serif', body: 'Georgia, serif', mono: 'Menlo, monospace' }}
  radii={{ sm: '0', md: '0', lg: '0', full: '0' }}
/>

The editor writes the names into its styles. Your page must load the font files, for example with a <link> to Google Fonts. A font that the page did not load falls back to the browser's default font.

Text on the canvas keeps its own fonts. See Text.

Default: the built-in font stacks.

Light and dark modeCopy Anchor Link

darkMode={true} selects the dark theme, and darkMode={false} the light theme. enableThemeToggle={true} adds a button to the app bar, so the user can switch.

<VideoEditor
  darkMode={true}
  enableThemeToggle={true}
/>

The editor remembers the user's choice for the next time. When you pass darkMode, your value wins when the editor starts. A theme object hides the switch.

Default: without darkMode, the editor is light in the regular layout and dark in the compact layout. The switch is hidden.

LogoCopy Anchor Link

logo shows your logo at the left end of the app bar. It takes the address of a picture.

<VideoEditor
  logo="/logo.svg"
/>

The editor shows the logo at 32 by 32 pixels, or 24 by 24 pixels in the compact layout. Use a square picture.

Default: no logo.

UI customizationCopy Anchor Link

The ui prop hides, reorders, and renames parts of the editor. Every field is optional. Without ui, the editor shows everything in its default order.

PanelsCopy Anchor Link

ui.toolRail changes the tool rail on the left. order moves the tools you list to the top, hidden removes tools, and labels renames them:

<VideoEditor
  ui={{
    toolRail: {
      order: ['text', 'media'],
      hidden: ['stickers', 'templates'],
      labels: { subtitle: 'Subtitles' },
    },
  }}
/>

Tools you do not list in order keep their default order, after the ones you list. The ids of the tool rail are:

The AI Assistant button stays at the bottom of the rail. To remove it, see AI features.

With createAutomatedContent, the rail and the compact dock also have Generate, with the id automated. Hide it with ui.features.automatedContent: false.

ui.dock does the same for the dock of the compact layout. Its ids are media, text, elements, templates, captions, effects, background, aiChat, and resize.

An unknown id prints a warning in the console and is skipped. The editor keeps working.

To hide the timeline, for example in an editor that only fills in a template, set ui.chrome.timeline to false:

<VideoEditor
  ui={{ chrome: { timeline: false } }}
/>

Default: every tool in the order of the table, except the four that are off the rail. See Tools that are off the rail by default.

Toolbar buttonsCopy Anchor Link

The palette button. showThemeCreator={true} shows a button in the app bar that opens the Customization Studio, a tool for developers. Use it in your development build only. Default: hidden. Only the value true shows it.

The light and dark switch. enableThemeToggle={true} adds it to the app bar. Default: hidden. See Theming.

The right-click menu. ui.generative.contextMenu hides, reorders, or renames its entries by id. false gives the browser's own menu back.

<VideoEditor
  showThemeCreator={false}
  ui={{ generative: { contextMenu: { hidden: ['delete'] } } }}
/>

The item menu in the compact layout. A selected item shows a small menu of its most important actions. itemActions changes it for each kind of item: replace sets the whole list, add appends actions, and remove drops them. false removes the menu.

<VideoEditor
  itemActions={{ text: { replace: ['textColor', 'fontSize'] } }}
/>

The kinds of item are video, image, gif, sticker, text, shape, label, and subtitle. The menu always keeps the full set of actions in the bar at the bottom of the screen.

The menu shows four actions. More actions go behind a ⋯ button.

RecordingCopy Anchor Link

The voiceover recorder and the camera recorder are on by default. Each switch in ui.features removes one control:

<VideoEditor
  ui={{ features: { 'recording.camera': false, 'recording.takes': false } }}
/>

See Microphone recording for the recorder, and recording for its defaults.

The image editor accepts the same switches and ignores them.

Two switches change the box for AI music and sound effects:

The image editor accepts these two switches too, and ignores them. It has no music.

AI featuresCopy Anchor Link

Use HTTPS for endpointUrl. HTTP is allowed only on your own computer at the loopback addresses.

AI controls appear only when you pass ai. Inside ai, a capability set to false is hidden everywhere. ui then decides where the remaining controls appear:

<VideoEditor
  ai={{ endpointUrl: 'https://api.example.com/ai', video: false }}
  ui={{
    features: { 'ai.chat': false },
    generative: {
      actions: { image: { label: 'Create a picture', surfaces: ['panel'] } },
    },
  }}
/>

The capabilities are text, textRewrite, image, imageEdit, svgPath, video, imageToVideo, captions, voice, music, and soundEffect. music and soundEffect appear in the panel and shortcut places only. The places are:

ui can only take controls away. It never shows a control that your AI provider cannot serve.

Default: every AI control that your ai setting can serve, in its default places.

See AI providers for ai.

Built-in control listsCopy Anchor Link

On a desktop, one bar above the canvas shows the controls of the selected item, for every type of item and for several items together. The floating pill and the phone's selection bar use the same settings. A button shows its current value, for example opacity or font size. When the bar is too narrow, the controls at the end of the default list move into a More menu. Colour, volume, effects and the other value controls open in a panel on the left side. With nothing selected, the bar becomes a page bar with the canvas size, Background, the length of the video, the emoji button, the Save template button when the editor can save templates, and a More menu with the lines of the empty-canvas right-click menu.

ui.selection changes the controls of the selected item. The editor has a default list of controls for each type of item. That list is only the starting view. ui.selection is applied after it, so your choice wins. Merge this section into the existing host's ui option.

import type { UiConfig } from '@layermetry/media-editor';

const uiControls: UiConfig = {
  selection: {
    order: ['trim', 'mute'],           // these come first
    hidden: ['delete'],                // no Delete button
    labels: { replace: 'Swap file' },  // a new name
    display: { effects: 'icon' },      // a picture only
  },
};

Listed ids come first, in your order, even a control that would wait behind More. The other controls keep their default order. Hidden buttons leave shortcuts and editing actions available. labels renames a control, and the new name is also its tooltip and accessible name. display: 'icon' draws a picture only and keeps the label as the tooltip and accessible name. The desktop bar draws Bold, Italic, Underline, Bring forward, Send backward, Delete and Mute as a picture only by default. Set display to 'label' or 'both' to bring the words back. The right-click menu keeps words. Unknown ids are ignored with one warning.

The new ids are trim and mute (video and sound clips), replace, copyStyle and pasteStyle. group and ungroup also work for several selected items.

ui.toolbar is still accepted. The bar has no groups now, so the editor translates each group id into the controls that the group held. The group text held font, textAlign, rewriteWithAi and effects. A labels setting for a group has no heading to change, and the order, labels and display of actions (your own buttons) are not applied. The editor prints one console warning that starts with [MediaEditor] ui.toolbar:. Use ui.selection instead.

See Default lists for the real default list of every type of item, and Control ids for the typed id unions.

Tools that are off the rail by defaultCopy Anchor Link

Effects, Animations, Audio effects and Background are not on the left rail by default. Reach them from the bar above the canvas: Effects, Animations and Audio effects from the bar of the selected item, and Background from the page bar. To put a tool back on the rail, list its id in ui.toolRail.order. A host that already lists every tool sees no change. The phone's dock is not changed by this.

import type { UiConfig } from '@layermetry/media-editor';

const uiRail: UiConfig = {
  toolRail: { order: ['text', 'media', 'effects', 'background'] },
};

Color controlsCopy Anchor Link

Color controls show the current color, your brand colors and 16 default colors. Use the same control for text and label colors, shape fill and stroke, text outline and shadow, caption colors. Open Custom color for the color square, hue strip and HEX, R, G and B fields. The control stays inside the panel or phone sheet.

A steady 3 px line under a toolbar color icon shows its stored color. Mixed colors show a gray dashed line. Your icon, label and display settings still apply. Dragging an item color previews it live. Releasing it saves one change, so one Undo restores the previous color. Escape cancels an unfinished item preview. Selected words in an open text box receive colors through the text editor.

The video color controls save opaque hex colors.

Generate from the barCopy Anchor Link

With nothing selected, open More and choose Generate text… or Generate image here…. These open the Text panel or the Photo tab of Media, with its Generate form already open. With an item selected, Rewrite with AI, Edit with AI and Make video open the form in the left panel. For Rewrite with AI and Edit with AI, the selected suggestion previews on the existing item; closing the box keeps it. New-item operations add a separate item through their add action.

For an existing-item edit, closing with ✕ or Escape keeps the selected card. Selecting another item or opening another panel also ends the edit and keeps that choice as one Undo step. Choose Original first to keep the current item unchanged. A new result needs Add to canvas, Add to timeline or Set as background. Only one panel is open at a time.

When the required panel is unavailable or hidden by ui.panels, ui.toolRail or ui.dock, the form opens under the bar. Panel placement also respects ui.generative. The floating pill, Cmd+K and the panels’ own Generate buttons keep their existing behavior.

Copy style and paste styleCopy Anchor Link

Copy style takes the look of one item. Paste style gives that look to one or more other items. Both are in the More menu of the bar above the canvas, in the right-click menu, and on the keyboard: Cmd + Option + C and Cmd + Option + V on a Mac, Ctrl + Alt + C and Ctrl + Alt + V on Windows and Linux. The editor matches the physical key, AltGr on Windows still types its character, and holding the keys pastes once. The ids are copyStyle and pasteStyle, so ui.selection can hide, move or rename them.

Copy style needs exactly one selected item that has a style. Text copies its font, size, weight, italic, underline, color, alignment, letter spacing, line height, outline and shadow. A shape copies its fill, outline color and outline width. A picture, video clip, GIF or sticker copies the filters and adjustments of the Effects panel, and its mask. Every item that has transparency copies the transparency. Not copied yet: the colored plate behind a text and its color gradient, the corner rounding of a shape, and the outline of a picture. A plain source clears italic, underline, shadow, filters and the mask instead of keeping the target’s old style. A paste is one Undo step. A part of the style that does not fit an item is skipped, and locked items are skipped. The editor then shows one short message that says what was left out. If every selected item is locked, the message is "The selected items are locked." If cropping alone is locked, the message is "The mask was left as it was, because cropping is locked."

Custom actionsCopy Anchor Link

customActions adds your own buttons after the built-in controls. Define this complete configuration module, then import customActions and onCustomAction into the host from the UI customization example above.

import type { CustomAction, CustomActionEvent } from '@layermetry/media-editor';

export const customActions: CustomAction[] = [{
  id: 'inspect-selection',
  label: 'Inspect selection',
  placements: ['selection', 'contextMenu'],
  when: { selection: 'any' },
  run(ctx) {
    console.log('Selected items', ctx.items);
    ctx.notify(`${ctx.items.length} item(s) selected.`, 'info');
  },
}];

export function onCustomAction(event: CustomActionEvent) {
  console.log(event.actionId, event.status);
}

Options excerpt: keep the existing host's license key, required callbacks and lifecycle.

<VideoEditor customActions={customActions} onCustomAction={onCustomAction} />

Select at least one item to see Inspect selection. Video custom actions can edit through ctx.verbs. Pass explicit target ids and scopeReason: 'explicit'. Editor edits made by one action use one Undo step by default. The list accepts at most 24 actions. Only one custom action runs at a time. A viewer sees none. The customaction DOM event carries the same status payload as the callback. Pass the action list as a property, not an attribute. See Custom actions for the fields, overflow counts and cancellation rules.

Saving and loadingCopy Anchor Link

Your application stores designs as template records. Pass save and load callbacks to store a record and return it when the user opens a design.

Saving designsCopy Anchor Link

Pass onSaveTemplate. The editor calls it with the template record when the user saves, and waits for the Promise it returns:

<VideoEditor
  onSaveTemplate={saveTemplate}
  onGetTemplates={getTemplates}
/>

With onSaveTemplate, a save button appears in the toolbar above the canvas, and Save current design appears in the Templates panel. Without it, the editor shows no save button, and the console says which prop is missing.

How your Promise settles decides what the user sees:

The value that your Promise resolves with is ignored.

To attach your own fields to every save, pass templateMetadata. The editor adds the fields of templateMetadata.metadata next to template:

<VideoEditor
  templateMetadata={{ metadata: { workspaceId: 'ws-42', folder: 'spring-campaign' } }}
  onSaveTemplate={async ({ template, ...metadata }) => {
    const response = await fetch('/api/templates', {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ template, ...metadata }),
    });
    if (!response.ok) throw new Error(`Saving failed: ${response.status}`);
  }}
/>

The element also sends a DOM event named templatesave after each attempt, with detail: { template, saved }. Use it to observe saves. It cannot answer the editor.

Default: no onSaveTemplate, so the editor has no save button.

Loading designsCopy Anchor Link

To open a design, pass the record as defaultTemplate. Load the record before you render the editor:

<VideoEditor
  defaultTemplate={template}
/>

To let the user choose from your saved designs, pass onGetTemplates as in Saving designs. The Templates panel calls it and shows the records. A click on a design opens it.

The panel shows only records with sceneMode set to "video" and a schemaVersion that this version of the editor can read. You can keep video and image designs in one list.

A template can come from a canvas of a different size. templateCanvasPolicy decides what happens then:

Default: no defaultTemplate, so the editor opens with an empty canvas. templateCanvasPolicy is 'adopt'.

A design that carries voiceoverScript puts its script back in the voiceover recorder. A design without one leaves the current script as it is. See Script and prompter.

DraftsCopy Anchor Link

A draft is a design that the user has not finished. Save draft in the Export panel, or Cmd+S (Ctrl+S), sends it through the same onSaveTemplate, with draft: true on the record.

Saving a draft again updates the same record. The first draft save of a design makes a new template.id, and every later draft save of that design sends the same id, from the button, the keyboard, or automatic saving. Opening a draft from the Templates panel continues that draft under its own id. Opening another template, the defaultTemplate, or a new blank design starts a new record. A finished template save gets a new id every time. Store drafts by template.id, and replace a record that has the same id.

A draft record can carry two more fields:

• chatSessionId: the conversation with the AI assistant that belongs to the design.
• generated: what AI models made during the session, including the words the user typed. Remove this field before you share a draft with other people.

The Templates panel shows drafts under Drafts.

To save drafts while the user works, turn on autosave:

<VideoEditor
  ui={{ drafts: { autosave: true } }}
  onSaveTemplate={saveTemplate}
  onGetTemplates={getTemplates}
/>

Autosave starts only after the user has pressed Save draft once. After each change, it waits 30 seconds, and every further change restarts the wait.

Default: autosave is off. Every autosave is a request to your backend.

Server-side handlingCopy Anchor Link

Store each record exactly as you received it, and return it unchanged. The editor may add fields in later versions, and it reads them back.

This Node.js server stores each record as a file, and returns them all:

import { createServer } from 'node:http';
import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';

const FOLDER = './templates';
await mkdir(FOLDER, { recursive: true });

async function readBody(request) {
  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);
  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
}

createServer(async (request, response) => {
  if (request.url !== '/api/templates') {
    response.writeHead(404).end();
    return;
  }
  if (request.method === 'POST') {
    const payload = await readBody(request);
    const template = payload.template ? { ...payload, ...payload.template } : payload;
    if (payload.template) delete template.template;
    if (!/^[\w-]+$/.test(String(template.id))) {
      response.writeHead(400).end();
      return;
    }
    // Store the record exactly as the editor sent it, including fields you do not use.
    await writeFile(`${FOLDER}/${template.id}.json`, JSON.stringify(template));
    response.writeHead(201).end();
    return;
  }
  const files = await readdir(FOLDER);
  const templates = await Promise.all(
    files.map(async (file) => JSON.parse(await readFile(`${FOLDER}/${file}`, 'utf8'))),
  );
  response.writeHead(200, { 'Content-Type': 'application/json' });
  response.end(JSON.stringify(templates));
}).listen(3001);

Your page reaches it at /api/templates, for example through the proxy of your development server.

The record has these fields:

Pictures from the user's computer are stored inside scene as data, which makes records large. Videos and sound files from the user's computer need onUploadAsset, or the save fails. See Asset storage.

Item lockingCopy Anchor Link

A lock stops some kinds of change to one item. For example, a person can change the words of a headline but cannot move the logo. The person who made the design sets the locks. Your application tells the editor who is editing, and the editor obeys the locks for that person.

Lock rolesCopy Anchor Link

The role prop says who is editing. You choose it for each person. The editor never decides it.

When you pass no role, the role is 'adopter'. A value that is not one of the three names is also read as 'adopter'.

Lock propsCopy Anchor Link

Pass the four lock props to the editor. This example opens the editor for an adopter. It lets that person ask to unlock, records each unlock in your audit log, and locks the position of every item that has no lock of its own:

<VideoEditor
  role="adopter"
  allowUnlock
  onUnlock={handleUnlock}
  defaultLocks={{ move: true }}
/>

When a prop changes while the editor is open, the editor uses the new value at once.

TypeScript names the types EditorRole, LockScopes, UnlockHandler, UnlockEvent and UnlockAnswer. The package also exports LockScope, UnlockRecord and LockManifest. They come from @layermetry/media-editor, @layermetry/media-editor/embed and @layermetry/media-editor/react.

Lock scopesCopy Anchor Link

Each kind of change that a lock can stop has a name, called a scope. A lock is a list of scopes.

add is a lock on the whole design, not on one item. The editor reads it only from the design's default locks. The item lock panel does not show it. The Default locks… panel does.

Lock fieldsCopy Anchor Link

The locks are stored in the design, so every save carries them:

The editor decides the locked scopes of one item in this order:

1. When isLocked is true, every scope is locked.
2. Otherwise, when the item has a locks object, the scopes in it are locked. An empty object, {}, locks nothing, and the default locks do not apply to that item.
3. Otherwise, the design's default locks apply.

Only the lock menus and the lock actions change these fields. Any other change that writes locks, isLocked or unlocks is refused.

Unlocking itemsCopy Anchor Link

An unlock removes scopes from the lock of one or more items. A creator may always unlock. An adopter may unlock only when you pass allowUnlock. A viewer never may. Every unlock follows these steps:

1. The editor checks the role and allowUnlock. When they do not allow the unlock, it is refused, and your onUnlock is not called.
2. The editor calls your onUnlock and waits for its answer. It does this before every unlock, a creator's too.
3. When you allow the unlock, the editor removes the scopes. For an adopter, it also adds an unlock record to each item that lost a scope. An item that had none of the asked scopes locked stays as it is and gets no record. A creator's unlock adds no record, because a creator's change is the design itself.
4. Without onUnlock, the editor unlocks the items when step 1 allows it, and still adds the adopter's record.

Your onUnlock receives one event:

Your answer decides what happens:

Use ref for the id of the entry in your own audit log. The editor keeps a ref only when it is text that is not empty.

An unlock record looks like this:

{ "scopes": ["style"], "at": "2026-10-05T09:30:00.000Z", "role": "adopter", "ref": "audit-1" }

scopes lists the scopes that the unlock removed. at is the time, as a date and time text such as 2026-10-05T09:30:00.000Z. role is the role of the person. ref is present only when your onUnlock gave one.

Saving locksCopy Anchor Link

Each save gives onSaveTemplate two lock fields, next to scene:

A lockManifest looks like this:

{
  "version": 1,
  "defaultLocks": { "move": true },
  "items": {
    "logo-1": { "locks": ["move", "resize", "delete"] },
    "photo-1": { "locks": ["move"] },
    "headline-1": {
      "locks": [],
      "unlocks": [{ "scopes": ["style"], "at": "2026-10-05T09:30:00.000Z", "role": "adopter", "ref": "audit-1" }]
    }
  }
}

items lists only the items that have a locked scope or an unlock record. Each item's locks is the list of scopes that are locked for it, with the design's own default locks applied, never your defaultLocks prop. In this example, photo-1 has no lock of its own, so it shows the default lock move. headline-1 has no locked scope left, but it is listed because of its unlock record. add never appears in an item's list.

When the editor opens a design, it reads defaultLocks back from the record. It does not read lockManifest. The locks inside scene are the ones that count.

Checking locks on your serverCopy Anchor Link

The editor runs in the person's browser. A person who controls the browser can change a record before it reaches your server. The lock is protection against mistakes, not security.

Your server can still find a lock that was removed without permission. Keep the lockManifest of the template that a design came from. When an adopter saves the design, compare the two manifests. Accept a lock that disappeared only when the item carries an unlock record for that scope, and the record's ref is in your own audit log. A creator's save is a new version of the template, and a creator's unlock leaves no record, so do not run this check for a creator.

This Node.js route writes each unlock to an audit log, and returns the id that your onUnlock returns as ref:

import { createServer } from 'node:http';
import { appendFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

async function readBody(request) {
  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);
  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
}

createServer(async (request, response) => {
  if (request.method !== 'POST' || request.url !== '/api/unlocks') {
    response.writeHead(404).end();
    return;
  }
  const event = await readBody(request);
  const id = randomUUID();
  // One line per unlock: the id, the time, and the event from onUnlock.
  await appendFile('./unlock-audit.jsonl', JSON.stringify({ id, at: new Date().toISOString(), event }) + '\n');
  response.writeHead(201, { 'Content-Type': 'application/json' });
  response.end(JSON.stringify({ id }));
}).listen(3002);

Your page reaches it at /api/unlocks, for example through the proxy of your development server. Add your own sign-in check, so that only a person who may unlock gets an id.

This function compares the two manifests. It returns one line for each lock that disappeared without an approved unlock:

export function findUnapprovedUnlocks(sourceManifest, savedManifest, auditIds) {
  const problems = [];
  for (const [id, before] of Object.entries(sourceManifest.items)) {
    const after = savedManifest.items[id];
    if (!after) {
      // The item was deleted, or it lost every lock without an unlock record. See the note below.
      if (before.locks.length > 0) problems.push(`${id}: the item or its locks are gone`);
      continue;
    }
    for (const scope of before.locks) {
      if (after.locks.includes(scope)) continue;
      const approved = (after.unlocks ?? []).some(
        (record) => record.scopes.includes(scope) && auditIds.has(record.ref),
      );
      if (!approved) problems.push(`${id}: '${scope}' was unlocked without an approved ref`);
    }
  }
  return problems;
}

For example, the template's manifest has "headline-1": { "locks": ["style"] }. The saved design has the manifest shown in Saving locks, where headline-1 has "locks": [] and an unlock record with "ref": "audit-1". Your audit log holds audit-1, so findUnapprovedUnlocks(source, saved, new Set(['audit-1'])) returns [], and you accept the save. With an empty audit log, it returns ["headline-1: 'style' was unlocked without an approved ref"], and you refuse the save. auditIds.has(record.ref) is false for a record without ref, so such a record never approves an unlock.

An item that is missing from the saved manifest was deleted, or lost every lock without an unlock record. The manifest alone cannot tell these two apart, so the function reports both. When delete was not locked on that item, read scene to see whether the item is still there before you refuse the save.

Locks in the editor APICopy Anchor Link

Every action that runs through the Editor API obeys the locks. The actions of the AI assistant obey them too. A refused action changes nothing and adds no undo step. It returns ok: false, a fixed reason for your code, and an error sentence for a person:

When only some of the named items are locked, the action changes the others and returns ok: true. The locked items are listed in skipped, each with reason: 'locked'.

An action that makes one change across several items is kept whole or refused whole. This applies to cutting and joining clips, grouping, ungrouping, a layer move, a canvas resize, and replacing part of a sound clip.

Three actions change the locks:

Each lock action is one undo step. Like every action that changes the design, each one also needs scopeReason. The lock actions are for a person only. The assistant is not offered them, and it is refused when it calls one. Otherwise an assistant asked to move the logo could unlock it first.

itemUnlock waits for your onUnlock, so it cannot answer at once. Run it with executeAsync(name, args), which returns a Promise of the result:

const result = await api.executeAsync('itemUnlock', {
  ids: ['headline-1'],
  scopes: ['style'],
  scopeReason: 'explicit',
});
console.log(result.ok ? result.message : `${result.reason}: ${result.error}`);

api is the handle from the ready event; see Editor API. execute refuses itemUnlock with this sentence: itemUnlock takes time (it waits for work outside the editor), so it cannot answer at once. Run it through executeTool, the door the assistant uses, or executeAsync, the person's door, instead of execute.

scopes must be a list, even for one scope. scopes: 'all' is refused with the sentence "scopes must be a list, for example ["all"], even for one value. Got string."

The reading actions show the locks. readItems and readCanvasState give each locked item a locks list, such as ["move", "style"], with the default locks applied. readCanvasState also reports role, and defaultLocks as a list of the scopes that the default locks hold, add included. Each field is absent when it is empty.

Lock controlsCopy Anchor Link

A locked item shows a small lock badge at its top-right corner. The badge has the same size at every zoom, and every role sees it. It never appears in an exported file, a thumbnail or a template preview. An item whose select scope is locked cannot be selected by an adopter or a viewer.

A creator finds Lock… when items are selected, and Default locks… for the whole design. An adopter finds Unlock when you pass allowUnlock and a locked item is selected. These entries are in the right-click menu, in the ⋯ list of the selection toolbar, in the compact bar and in the desktop toolbar. Default locks… is also in the right-click menu of the empty canvas. A person who may not use an entry does not see it. The lock panel has one switch per scope, and the buttons Lock everything and Unlock everything. Lock everything leaves select unlocked, so that an adopter can still select the item and ask to unlock it. preset: 'all' in itemSetLocks locks select too.

When the editor refuses a change, it shows a short notice with the title "Locked":

Asset storageCopy Anchor Link

The editor never writes to cloud storage itself. When a design needs a file stored, the editor gives the file to your onUploadAsset function, and keeps the reference that your function returns.

UploadsCopy Anchor Link

A file that the user adds from the computer exists only in the browser. When the user saves the design, the editor passes each such file to onUploadAsset, and then the preview picture of the design:

<VideoEditor
  onSaveTemplate={saveTemplate}
  onUploadAsset={uploadAsset}
  resolveAssetUrl={resolveAssetUrl}
  assetMetadata={{ workspaceId: 'ws-42' }}
/>

Your function receives the File and a context object. It returns { url }. The editor stores url in the design exactly as you return it: a full address, a path, or a key of your own.

assetMetadata adds your own text fields to every context, for example a workspace or a customer id. They reach every upload: a template save, a generated file, a clip for a media server job, and a file that the AI assistant placed. A field name that the editor already uses keeps the editor's value.

If your function rejects, the whole save fails, and the user can try again. The editor never saves a design with missing media.

A file that already has an http or https address is stored by its address and not uploaded again. A stock photo that the user adds from Stock Images is different: the editor downloads it first, so it reaches onUploadAsset like a file from the computer, and the design keeps the key that your function returns.

When the design opens again, a reference that is a full http or https address loads as it is. Any other reference goes through resolveAssetUrl, which returns an address the browser can load, such as a signed URL. Without resolveAssetUrl, the editor adds the reference to assetBaseUrl.

Storage keysCopy Anchor Link

When onUploadAsset returns a storage key instead of a web address, the item keeps your key in the design. This is true for a picture, a clip, or a sound. A generated picture added to the canvas, by Edit with AI, or by the AI assistant holds the key at once, so a later save sends nothing to onUploadAsset again. A picture the user added from the computer is different: while the design stays open, each save sends it to onUploadAsset again, and it holds the key only after the design is opened again. When the design opens again, the editor loads the file from the key through resolveAssetUrl, or assetBaseUrl. Undo and redo load such a picture the same way.

The export also turns a background's key into an address itself, by the same rule: resolveAssetUrl first, then assetBaseUrl.

Signed addressesCopy Anchor Link

The editor loads the address that resolveAssetUrl returns exactly as it is. A signed S3 or CloudFront address is never changed, so its signature stays valid. The editor adds a t= parameter only to an S3 or CloudFront address that has no query at all, so that the browser asks for a fresh copy.

Every file that your storage returns must allow your page to read it, with the Access-Control-Allow-Origin header. The editor draws pictures on a canvas and reads sound and video for the export.

Default: no onUploadAsset. See Temporary assets for what happens then.

Generated mediaCopy Anchor Link

When the user keeps a picture, a clip, or a sound that an AI model made, the editor fetches it and passes it to onUploadAsset at once, before it appears on the canvas. The context has source: 'generated'. The design then keeps your reference, not the model's address.

Addresses from AI models are temporary. Some stop working after about an hour, so the editor stores the file as soon as the user keeps it.

capability says which AI feature made the file, for example image, imageToVideo, music, or soundEffect. Music and sound effects arrive with type: 'audio'. The words that the user typed are not in the context.

Default: without onUploadAsset, the design keeps the model's address, which can stop working.

Recorded voiceoversCopy Anchor Link

When the user presses Use this in the voiceover recorder, the editor passes the recording to onUploadAsset before it appears on the timeline. The design then keeps your reference. The context has these values:

By default, only the take that the user adds is sent. To receive every take, set recording.uploadAllTakes to true. The added take is sent first, with take.used: true. The other takes follow, with take.used: false. Takes that the user did not add are also sent when the recorder closes.

<VideoEditor
  recording={{ uploadAllTakes: true }}
  onUploadAsset={uploadAsset}
/>

When your function rejects the added take, the take is not lost. The editor adds it to the timeline from the browser, and writes one line to the console that starts with "[MediaEditor] onUploadAsset refused a recording". When your function rejects a take that was not added, the editor writes one line to the console and carries on. It never shows the user an error for it.

Default: without onUploadAsset, the take stays in the browser, like a sound file from the user's computer. See Temporary assets.

Staged clipsCopy Anchor Link

Stabilize and Remove background send a clip to your media server, and the server downloads it. A clip that is already at an http or https address is sent as it is. A clip that exists only in the browser, such as a file from the user's computer, is first passed to onUploadAsset:

Return an https address that your media server can reach, or a key that resolveAssetUrl turns into one. The editor sends that address to the server and does not keep it in the design.

Default: without onUploadAsset, the editor uploads the clip with its own uploader, which needs assetBaseUrl.

Temporary assetsCopy Anchor Link

Without onUploadAsset, files from the user's computer stay in the browser until the design is saved. Then:

• Pictures are stored inside the design record as data. The save works, but the record is large.
• A video or sound file stops the save. The user sees "This design contains video that this app can't store yet, so it wasn't saved." The console names onUploadAsset.

To store every file inside the record on purpose, set inlineTemplateMedia to true. Records can then be many megabytes.

A file the user has added but not saved exists only in that browser tab. Closing the tab loses it.

Default: inlineTemplateMedia is false.

Stock mediaCopy Anchor Link

Stock media lets users search photos, videos, music, and stickers from outside services inside the editor. You connect each service with your own account, in one of three ways:

Use exactly one of the three for each service. Use a proxy or a function in production.

A searchFn receives search parameters such as query, page, and perPage. Return { results, total, total_pages }, using the exported result types below:

Unmodified Pexels and Unsplash responses are also accepted. The editor validates each page of results: it skips an item missing id or url and logs the omission. A response without a result list appears as a service error.

A setting that names none, or more than one, of apiKey, endpointUrl, and searchFn turns off only that service. Its panel says, for example, "Unsplash photos are not available.", and the console says which setting is wrong.

PexelsCopy Anchor Link

Pexels gives the editor stock photos and stock videos:

<VideoEditor
  stockMediaApis={{ pexels: { apiKey: 'YOUR_PEXELS_KEY' } }}
/>

With endpointUrl, the editor sends POST requests to your address, with the paths of the Pexels API without /v1: /search and /curated for photos, /videos/search and /videos/popular for videos. The query string and a JSON body carry query, page, and perPage. Your server adds the key, calls Pexels, and returns the response from Pexels unchanged.

<VideoEditor
  stockMediaApis={{ pexels: { endpointUrl: 'https://api.example.com/stock/pexels' } }}
/>

Default: off.

UnsplashCopy Anchor Link

Unsplash gives the editor stock photos. Unsplash requires that the photographer's name is shown, so showAttribution must be true:

<VideoEditor
  stockMediaApis={{
    unsplash: { apiKey: 'YOUR_UNSPLASH_ACCESS_KEY', showAttribution: true },
  }}
/>

When the user adds an Unsplash photo, the editor reports the download to Unsplash, as the Unsplash rules require. trackDownloads: false turns this off.

With endpointUrl, the editor sends POST {endpointUrl}/search with the JSON body { query, page, perPage, orientation }. Return the response from the Unsplash search endpoint unchanged.

With endpointUrl, the editor reports a download through your server. It sends POST {endpointUrl}/download, with your headers and the JSON body { "downloadLocation": "<the photo's links.download_location>" }. Your server adds your access key and calls that address. Check that the address is on api.unsplash.com before you call it. No request in proxy mode carries your key. With searchFn, the editor has no route for the report, so it sends nothing and prints one console line.

Default: off.

FreesoundCopy Anchor Link

Freesound gives the editor music and sound under Creative Commons licenses. Pass it as music:

<VideoEditor
  stockMediaApis={{ music: { apiKey: 'YOUR_FREESOUND_KEY' } }}
/>

With endpointUrl, the editor sends POST {endpointUrl}/search with the JSON body { query, page, perPage, source, mediaType }, and downloads a track with GET {endpointUrl}/download/freesound/{id}. Your search response is { tracks, total, total_pages, page }:

{
  "tracks": [
    {
      "id": 701,
      "title": "Calm piano",
      "artist": "composer1",
      "duration": 42,
      "previewUrl": "https://cdn.example.com/previews/701.mp3",
      "downloadUrl": "https://cdn.example.com/sounds/701.mp3",
      "license": "CC0",
      "source": "freesound"
    }
  ],
  "total": 1,
  "total_pages": 1,
  "page": 1
}

license is CC0, CC-BY, or CC-BY-SA. A track that is not CC0 needs attribution, and the editor keeps the artist's name with the clip.

Default: off.

GIPHYCopy Anchor Link

GIPHY gives the editor stickers and animated stickers. It is a sticker source, so you pass it in stickers, with giphyStickers:

<VideoEditor
  stickers={{ sources: [giphyStickers({ apiKey: 'YOUR_GIPHY_KEY' })] }}
/>

The Stickers panel shows the words "Powered by GIPHY" while GIPHY stickers are browsed, as GIPHY's terms ask. The mark is in the panel only, never on the canvas or in an export.

With endpointUrl, the editor sends GET {endpointUrl}/search?q=… or GET {endpointUrl}/trending, with type=stickers, rating=pg, limit, and offset. Your server adds api_key, calls GIPHY, and returns the response from GIPHY unchanged. requestFn receives the same request as an object.

See Stickers and GIFs for built-in and custom sticker sets.

Default: off. Without stickers, the panel shows the built-in stickers.

Photo creditsCopy Anchor Link

A stock photo keeps its photographer's credit after the user places it. The placed item carries attribution, which is saved with templates and drafts. Stock video clips and music tracks keep their credit too.

When the design holds a stock photo with a credit, the Export panel shows two switches:

The user's choice is saved with the design, and it can be undone. showAttributionOverlay and includeAttributionInExport set the starting value of each switch. Both are false by default.

To show credits your own way, hide a switch. A hidden switch always follows your prop:

<VideoEditor
  ui={{ exportOptions: { hidden: ['photoCreditsOverlay', 'photoCreditsInExport'] } }}
/>

stockMediaApis.pexels.showAttribution: false hides the photographer's name on the Pexels photo tiles. Unsplash tiles always show the name, because Unsplash requires it.

Where providers appearCopy Anchor Link

Each service adds a Stock tab to the Media panel, or adds stickers to the Stickers panel:

View full size

A service without configuration has no tab.

AI providersCopy Anchor Link

The ai prop turns on the AI features of the editor and says where their requests go. Without ai, the editor shows no AI control and sends no AI request.

ai takes exactly one of three ways to send requests: endpointUrl, requestFn, or hosted. With none of them, or with two, the editor prints one error in the console and keeps AI off. Hosted AI is coming soon and available only with an enterprise licence from Layermetry.

The AI features, and the capability name of each:

The right-click menu of the canvas, and Cmd+K (Ctrl+K), also open these controls.

Hosted serviceCopy Anchor Link

Use your own endpointUrl or requestFn for generation. hosted: true sends AI requests to Layermetry. Hosted AI is coming soon. Available only with an enterprise licence from Layermetry. Enterprise setup:

<VideoEditor
  ai={{ hosted: true }}
/>

Hosted mode is coming soon and available only with an enterprise licence from Layermetry. It is the only AI transport that sends your license key, in the x-license-key header. Your own endpointUrl or requestFn does not receive it.

Use your own mediaApiUrl for transcription, background removal and stabilization. Hosted routing is coming soon and available only with an enterprise licence from Layermetry; when enabled, it uses Layermetry’s media service if no mediaApiUrl is set.

When the account that pays for AI has no credits left, a request is refused with ai-credits-exhausted. When the plan does not include a kind of AI work, it is refused with meter-off. Both can carry a top-up address for your own interface. See Top-up address.

For enterprise hosted integrations, the service address is exported as LAYERMETRY_MEDIA_API_URL for your content security policy. Hosted AI is coming soon and available only with an enterprise licence from Layermetry.

Default: off.

Proxy URLCopy Anchor Link

endpointUrl sends every AI request to your own server. Your server holds the provider keys and calls the providers:

<VideoEditor
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
/>

The editor sends POST with a JSON body, and never sends your license key. Custom AI endpoint describes every request and response, with a complete server.

Default: off.

Request functionCopy Anchor Link

requestFn hands each request to your own function. The editor then makes no AI request itself:

<VideoEditor
  ai={{ requestFn }}
/>

The function receives the same request object that a proxy receives, and an AbortSignal that fires when the user cancels. It returns the response, in the same format as a proxy response. A thrown error shows as a failed generation.

Pass functions directly as React props.

Default: off.

Session limitsCopy Anchor Link

maxPerSession stops a capability after a number of generations. limits.maxPerSession counts all capabilities together:

<VideoEditor
  ai={{
    endpointUrl: 'https://api.example.com/ai',
    text: { maxPerSession: 1 },
    limits: { maxPerSession: 20 },
  }}
/>

The editor counts in the browser, per editor, while the page is open. Anyone can change a number in their own browser, so this is a guard for honest use, not a security control. Enforce your real limits on your server.

In the voiceover recorder, Write with AI shows the requests left for text, and Generate captions shows the requests left for captions.

When your server refuses a request, it responds with an error code, and the editor shows a heading and a message for that code. See Error codes.

Default: no limit.

Per-feature optionsCopy Anchor Link

Each capability takes true, false, or an object with settings. A capability you do not name is on, if the transport can serve it:

<VideoEditor
  ai={{
    endpointUrl: 'https://api.example.com/ai',
    // No shape generation.
    svgPath: false,
    // Pictures go to a different server.
    image: { transport: { endpointUrl: 'https://images.example.com/generate' } },
    // Short vertical clips only.
    video: { maxDurationSeconds: 6, aspectRatios: ['9:16'] },
    // Two voices only, named as your server names them.
    voice: { voices: ['alloy', 'nova'] },
  }}
/>

There is no hosted service for music and sound effects. They work only through your own endpointUrl or requestFn. See Music and sound effects.

To hide a control in one place only, for example the right-click menu, use ui.generative. See UI customization.

Generating a clip with video or imageToVideo may take several minutes. The editor shows its progress in a notice, and the finished clip appears in Media > Generated. See Long-running jobs.

Default: every capability is on.

Saving generated resultsCopy Anchor Link

ai.generatedStore.onSave receives text results when they are generated. File results use saveFiles: 'all' by default; when you provide onUploadAsset, the file uploads before its record is pushed. Set saveFiles: 'used' to wait until a file is placed. The list matches records by userId and brandId; other scope fields are carried but not compared. See Save generated results for the details, flow diagram, defaults and host checklist.

Generation resultsCopy Anchor Link

The first returned suggestion is selected automatically. For Rewrite with AI and Edit with AI, it appears on the existing item. Click a different card to compare it. Leaving the box keeps the selected card as one editing action and one Undo step. This includes ✕, Escape, Enter from the results, changing selection or opening another panel. Choose Original before leaving to make no change. The timeline keeps the saved words until the box closes.

The text card says Original (your text now). A returned wording identical to it says Same as your text. Picture edits label the source Original. If the target was deleted, the editor says That item was deleted, so the change was not kept.

Generate more appends suggestions using the previous request. Try again replaces the current choices. The count excludes Original and states the number actually returned. The SDK sends the selected field values to your host through the configured schema, including any sendAs names. If your service returns fewer suggestions than requested, handling that count belongs to your service; the editor does not create extra answers.

For a new result shown in the box, the add action depends on its destination:

A long-running video result can finish under Generated in Media. Select its card there to add it. In the Text panel, Generated uses the same list as Elements. With no text selected, selecting a text result adds it. With editable text selected, choose Replace selected to keep its font family, font size and position, or Add as new. Replacement is one Undo step. Locked text has no Replace selected action.

The toolbar action Rewrite with AI opens the Text panel form in rewrite mode. With selected text, the form can change the words or put them in a template; + New starts a separate text item.

Custom AI endpointCopy Anchor Link

Use HTTPS for statusUrl and cancelUrl. HTTP is allowed only on your own computer at the loopback addresses.

With endpointUrl in ai, the editor sends each AI request to your server, and your server responds. The following contract describes the requests and responses, with a complete Node.js server.

The server below handles text, image, shape, voice, and video JSON requests. Captions use a multipart transcription endpoint; music and sound effects need the audio contract below. Its helper functions return fixed results. Replace them with calls to your AI service and provide reachable media files.

The local server uses loopback HTTP addresses for video job polling, which are allowed for development on your own computer. Use absolute HTTPS statusUrl and cancelUrl values outside local development, as described in Long-running jobs. Replace its placeholder picture, voice, and video addresses with reachable fixtures that allow your editor origin through CORS.

Start the server, and pass its address to the editor:

<VideoEditor
  ai={{ endpointUrl: 'http://localhost:8787/ai' }}
/>

Set ALLOWED_ORIGIN to the address of your page. The editor calls your server from the browser, so the server must allow that address with Access-Control-Allow-Origin.

Request formatCopy Anchor Link

The editor sends POST to endpointUrl, with Content-Type: application/json. It never sends your license key. The body has four fields:

For example, Generate sound effect, with the length on Auto and no model picked, sends:

{
  "type": "audio",
  "prompt": "a wooden door closing softly",
  "input": { "operation": "soundEffect", "prompt": "a wooden door closing softly", "loop": false },
  "options": { "action": "soundEffect" }
}

For text, pictures, shapes, voices, and clips, options also carries provider, the name of a vendor. The editor names that vendor for the reference backend, which reads it. Your server can ignore provider and choose its own vendor and model. Music and sound effects carry no provider.

Each capability puts these fields in input:

options.count is the number of results the editor asks for: 3 for text, and 1 for the others. options for video also carries aspectRatio (default 16:9), durationSeconds (default 8), resolution (720p), and generateAudio (true).

Captions are different. The editor sends the sound as a file upload, not as JSON. See Custom transcription.

Model listCopy Anchor Link

Before it shows a control, the editor asks which models your server offers: GET on the address next to endpointUrl, named models, with ?capability= and the type. For https://api.example.com/ai, that is https://api.example.com/models?capability=image. The response is:

{ "models": [{ "id": "fast", "label": "Fast" }, { "id": "best", "label": "Best quality" }], "default": "fast" }

This route is optional. Without it, the editor shows no model picker and lets your server choose. An empty models list hides the control of that capability.

Response formatCopy Anchor Link

Answer with HTTP 200 and { items: [...] }. Each entry depends on input.operation:

A shape outline is SVG path data, and it must start with M or m. The editor drops an outline that draws nothing.

The editor downloads each address in the response, so the files must allow cross-origin requests. Addresses from AI vendors are often temporary. Store the files, or pass onUploadAsset so that the editor stores them when the user keeps one. See Asset storage.

Returned clips appear under Generated in Media. Select a result to add it to the timeline. When a result is shown in the Generate box, its add action is Add to timeline.

Long-running jobsCopy Anchor Link

Video generation may take longer than your request timeout. Return HTTP 202 with a job handle so the editor can poll its status while processing continues:

{
  "ok": true,
  "job": {
    "id": "7f3c9a1e",
    "statusUrl": "https://api.example.com/ai/jobs/7f3c9a1e",
    "cancelUrl": "https://api.example.com/ai/jobs/7f3c9a1e/cancel",
    "pollMs": 2000
  }
}

Write statusUrl and cancelUrl as whole HTTPS addresses. For local development, HTTP is allowed only at the loopback addresses. The editor refuses a job whose addresses are paths, because it never guesses which server a path belongs to. cancelUrl is optional.

The editor then sends GET to statusUrl every pollMs milliseconds. pollMs is kept between 250 and 60,000, and is 1,500 when missing. Each response describes the job:

{ "ok": true, "job": { "jobId": "7f3c9a1e", "state": "running", "percent": 40, "stage": "rendering" } }

A finished job returns:

{
  "ok": true,
  "job": {
    "jobId": "7f3c9a1e",
    "state": "ok",
    "percent": 100,
    "stage": "done",
    "receipt": { "asset": { "url": "https://cdn.example.com/videos/7f3c9a1e.mp4" } }
  }
}

While the job runs, a notice shows its progress, with a Cancel button. When it finishes, the notice says "Your video is ready", and the clip is in Media > Generated. Nothing is added to the timeline until the user adds it.

Cancel sends POST to cancelUrl, and the notice says "Generation stopped". The editor also asks your server to stop when it gives up:

• after three failed status requests in a row;
• after 12 minutes.

A request function can respond with the same job. The editor then follows statusUrl and cancelUrl itself.

Music and sound effectsCopy Anchor Link

Your server makes music and sound effects for the editor. The editor names no vendor and no model: your server chooses them. There is no hosted service for them. They work only through your own endpointUrl or requestFn.

The request has type: "audio", and options.action is music or soundEffect. A voice request has no action. prompt is a description of the sound, not words to read out loud:

{
  "type": "audio",
  "prompt": "calm piano for a product story",
  "input": { "operation": "music", "prompt": "calm piano for a product story", "durationSeconds": 30, "instrumental": true },
  "options": { "action": "music" }
}

durationSeconds is missing when the user chose Auto: the model decides. loop is present for a sound effect. model is in input and options only when the user picked a model from your list.

Answer with HTTP 200:

{ "items": [{ "url": "https://files.example.com/generated/abc.mp3", "durationSeconds": 30.2 }] }

• items lists the files, with a url in each entry. Return one file for music. A sound effect can return up to four, and the user chooses one.
• Each item’s optional durationSeconds gives its length in seconds. Send a positive number when you know the duration. Without it, the editor reads the file to measure it.
• Serve MP3 (audio/mpeg) or WAV (audio/wav) files, with CORS headers that let the editor's page read them. The editor downloads each file to store it and to export it.

A slow server can respond with a job instead. See Long-running jobs. The file of a finished job is receipt.asset.url, and its length is receipt.asset.durationSeconds.

Model list for musicCopy Anchor Link

The editor shows Generate music only when your server names a music model. It asks GET on the models address with ?capability=music, and with ?capability=soundEffect for sound effects. These two ask by their own names, not by audio, because audio lists voices. For https://api.example.com/ai, the address is https://api.example.com/models?capability=music.

{
  "ok": true,
  "capability": "music",
  "default": "clip",
  "models": [
    { "id": "clip", "label": "Short clips", "limits": { "minSeconds": 3, "maxSeconds": 30 } },
    { "id": "full", "label": "Full tracks", "limits": { "minSeconds": 3, "maxSeconds": 180 } }
  ]
}

default must be one of the id values. limits is the length range of each model, in seconds. The editor offers lengths inside it, keeps Match the video inside it, and refuses a length outside it before anything is sent, with a sentence such as "This model makes music from 3 seconds to 30 seconds long." With two or more models, the box shows a picker. A range that is not valid is ignored, and the model is still offered.

A failed response, or an empty models list with "default": null, hides the button. A request made anyway is refused before it is sent, with not-configured. Its error.message is "This server offers no model for music, so nothing was sent." or "This server offers no model for sound effects, so nothing was sent."

With requestFn, there is no model list. The buttons are shown, and you state the range in the ai setting:

<VideoEditor
  ai={{
    requestFn: myAiFunction,
    music: { minDurationSeconds: 3, maxDurationSeconds: 300 },
    soundEffect: { maxDurationSeconds: 30 },
  }}
/>

Each value must be a number of seconds above zero, and minDurationSeconds must not be larger than maxDurationSeconds. A range you state replaces the range of the model list.

Refusals from your serverCopy Anchor Link

Use the codes in Error codes. Send invalid-input for a length outside the model's range, with the range in message. Send unsupported-model for a model you do not offer. Send ai-quota-exceeded or limit-reached for an allowance.

Check that your music vendor's terms allow commercial use by your own users. Some vendors exclude film, TV, radio, or games, or forbid reselling.

TypesCopy Anchor Link

These types describe the contract, and every entry exports them: AISoundAnswer, AIModelListAnswer, AIModelListEntry, and AISoundOptions. AIInput has the music and soundEffect operations, and each media entry in AIResponse.items can include durationSeconds.

Error codesCopy Anchor Link

To refuse a request, respond with an HTTP error status and this body:

{ "ok": false, "error": { "code": "limit-reached", "message": "You have made 20 videos today. Try again tomorrow." } }

The editor shows a heading for the code, and your message under it. It shows your message only when code is a code that the editor knows, such as the codes below. Any other response shows "AI request failed (HTTP 402).", with your status. For ai-quota-exceeded, ai-credits-exhausted, and meter-off, the editor shows fixed words instead of your message, and writes your message to the browser console. See AI errors.

With ai-credits-exhausted or meter-off, you can add topUpUrl to error: the https address where the account buys more credits. The editor passes it to your code as error.topUpUrl and shows no link itself. See Top-up address.

The editor also uses codes such as not-configured, transport-failed, and invalid-response. Error codes lists all of them.

To show the same words in your own controls, catch the error and pass it to describeAIError, which returns { title, description }.

EventsCopy Anchor Link

The editor tells your code what happens through callback props. The custom element also sends most of them as DOM events, so a page can listen with addEventListener.

A DOM event bubbles and crosses a shadow DOM boundary. A callback that must return a value, such as onSaveTemplate or onGetTemplates, can only be a prop, because an event listener cannot return a value to the editor.

SaveCopy Anchor Link

onSaveTemplate stores a design. The editor waits for the Promise it returns. After each attempt, the element sends templatesave with detail: { template, saved }.

See Saving and loading for the record and for failures.

Default: no onSaveTemplate, so the editor has no save button.

ExportCopy Anchor Link

onExport receives the finished MP4, WebM, or GIF file as a File, when the user presses Save & Exit, Export, or Share…. Its second argument, extras, is optional, and so is each of its fields. It carries email when the user shared the video by email from the Export panel, chat when the video came from a conversation with the AI assistant, and srt when the video has captions. Read each field with a check, such as extras?.email?.to.

Save & Exit closes the editor as soon as the first frame is written, usually in less than two seconds. The file is written in the background, and onExport receives it later. onExportProgress reports the progress:

<VideoEditor
  onExportProgress={handleProgress}
/>

Each progress event has these fields:

Show a placeholder in your page when the first event of a new jobId arrives, and replace it with the file from onExport when done arrives. See Export for thumbnails and file options.

When the browser refuses the export before it starts, no file is made and the editor stays open. onExportProgress then receives one event with done: true and a sentence in error that says why. See Export failures.

Default: no onExportProgress. Save & Exit still delivers the file through onExport.

CloseCopy Anchor Link

onClose is required. The editor calls it when the user presses the close button, and after Save & Exit. Remove or hide the editor when it runs:

<VideoEditor
  onClose={() => setIsOpen(false)}
/>

The custom element also sends close. After Save & Exit, onClose comes before onExport, while the file is still being written.

ErrorsCopy Anchor Link

The editor has no single error callback. Each kind of failure reaches you in its own way:

A wrong ai setting, for example, prints:

[MediaEditor] `ai` is not usable, so AI stays off: Provide exactly one of hosted, endpointUrl or requestFn.

Error codes lists every code and message.

Handling the exportCopy Anchor Link

onExport receives the selected MP4, WebM, or GIF file. Upload it with its original name and MIME type:

<VideoEditor
  onExport={handleExport}
/>

Save & Exit calls onClose when the first frame is written. The file finishes in the background, then reaches onExport. Keep the callback and upload in your application after you remove the editor.

For progress events and file options, see Export.

ContentCopy Anchor Link

TimelineCopy Anchor Link

The timeline displays one row for each clip, picture, text item, or sound. Render the editor to use its timeline controls:

Use the editor from Usage; these controls need no additional props.

View full size

The video is as long as its last item. With one 6-second clip, the time display shows 0:00.0 / 0:06.0.

PlacementCopy Anchor Link

Every item has a start time and an end time. The editor places a new item at the start of the video.

• Move. Drag an item left or right to change when it starts. Its length stays the same.
• Trim. Every item has a handle on its left edge and on its right edge. The right edge changes when the item ends. The left edge changes when the item starts, and its end stays where it is. On a video or sound clip, the left edge also cuts footage from the start of the clip. A clip cannot start before the first second of its file, and no item can be shorter than 0.1 seconds.
• Split. Select a clip, move the playhead, and press Split. The clip becomes two clips at the playhead. Join joins them again. Two pieces at different speeds cannot be joined.

A clip at a speed other than 1× shows its speed on its block, for example 2×. See Clip speed.

See Right-click menu.

LayersCopy Anchor Link

The order of the rows is the order of the layers. The item in the top row is drawn over everything else, and the item in the bottom row is furthest back.

To change the order, drag a row up or down, or use Bring forward, Send backward, Bring to front, and Send to back in the right-click menu. The background is always behind everything, and it has no row.

Show only clips at the playhead (the eye button) hides the rows of items that are not visible at the current time. If no item is visible there, the timeline shows all rows.

PlaybackCopy Anchor Link

Press Play, or the Space bar, to play the video from the playhead. The time display shows the position of the playhead and the length of the video.

Click the ruler above the rows to move the playhead. The zoom buttons make the timeline wider or narrower, and Zoom to fit shows the whole video. Minimize timeline makes the timeline small, to give the canvas more space.

These keys work while the editor has the focus:

Mute, the M key and the volume slider next to the play button change the sound of the preview only. They do not change the exported video. To change the sound of a clip, see Audio.

Right-click menuCopy Anchor Link

A right-click on a clip opens the same menu as a right-click on that item on the canvas. The lines, the actions, the locks and the roles are the same, and so are your settings in ui.generative.contextMenu. If the clip is not selected, the right-click selects it first. A right-click on empty space, on the ruler or on the playhead opens the browser's own menu, and so does a long press on a phone.

The menu has one extra line, Split at playhead. The editor offers it only when it would cut the clip you clicked: exactly one clip is selected, it is the clip you right-clicked, and the playhead is inside that clip. This is the same rule as the Split button. A press with the right mouse button does not start a drag or a trim. On a Mac, Ctrl + click is a right-click, so it does not start a drag either.

Clip colorsCopy Anchor Link

Each type of clip has its own color on the timeline: video, sound, picture, shape, title, caption and sticker. Your theme still decides. When you set the theme color video, audio, image, shape or text, the clips of that type use your color. Captions follow text, and stickers follow image. Without them, the timeline uses its own built-in colors, which do not change the Play button or the audio panel. See Theming.

Panels and menus cover the timeline playhead line. The line stays inside the timeline while you edit in a panel.

Full-screen playerCopy Anchor Link

The Full screen button is next to the time in the timeline, and the F key does the same. It shows only the picture, with a small player bar: play and pause, a position slider, the time, the volume and mute (the same volume as the timeline's), and Exit full screen. The toolbar and editing keyboard shortcuts are off while it is open. A reply already in progress from the AI assistant can still change the design. Leave full screen with Escape before using Undo. The bar above the canvas, the floating pill and the selection frame are hidden, Delete, Undo and the other editing keys do nothing, and a click on the picture plays or pauses. Space plays and pauses. F or Escape leaves, and holding F does not switch the player on and off again. The zoom is set to fit and is put back when you leave, and the selection is kept.

To hide the button and turn off the F key, set ui.features['player.fullscreen'] to false. The editor shows the button only when the browser allows full screen for the page. Safari on an iPhone cannot show one element on the whole screen, so the iPhone shows no button. Safari before version 16.4 works through its older function names. In an iframe, add allow="fullscreen". If the browser refuses, nothing changes, and the console shows one warning that starts with [PlayerFullscreen].

Timeline on a phoneCopy Anchor Link

On a phone, the play button and the time come first in the row of controls. The row stays on one line, and a swipe moves it sideways so that every control can be reached. The button that minimizes the timeline stays outside the moving part.

VideoCopy Anchor Link

Use HTTPS for mediaApiUrl. HTTP is allowed only on your own computer at the loopback addresses.

Video clips come from the user's computer, from the camera, from Pexels, or from an AI model. On the timeline, the user splits and trims them. On the canvas, the user crops them and adds filters.

Upload, camera recording, split, trim, speed, volume, and filters work with no setup. The other options need a key, a server, or an AI provider, which you pass as props:

<VideoEditor
  stockMediaApis={{ pexels: { apiKey: 'YOUR_PEXELS_KEY' } }}
  mediaApiUrl="https://media.example.com"
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
/>

UploadCopy Anchor Link

Open Media, choose Video, and press Upload Videos. The file appears under Local Upload. Press + on it to add it to the canvas and the timeline.

The panel lists MP4, MOV, WebM, and MKV. The browser must be able to decode the file. A file that it cannot decode is still listed after the upload. When the user presses +, the editor refuses it with a message such as "This video cannot be played here. old.avi is 2 seconds long, but your browser cannot decode this format. Please convert it to H.264 (MP4) and try again."

Export reads clips from MP4, MOV, WebM, and MKV files. See Source clips for the video and sound formats that export reads.

A new clip starts at the beginning of the video and sits in the top-left corner of the canvas. It keeps its own size, and a clip that is larger than the canvas is made smaller to fit. To scale a small clip to the canvas, choose Fit to canvas under ⋯.

View full size

When a clip is selected, a bar under it offers Crop, Mask, Effects, and Animate, and a ⋯ button for more actions. Crop shows part of the clip. Fit mode, under ⋯, decides how the clip fills the canvas. The tool rail also shows Audio Effects and Animations.

Camera recordingCopy Anchor Link

The user records a clip with the computer's camera, inside the editor. Open Media, choose Video, and press Record with camera. The browser asks for permission to use the camera first. A window then lists the connected cameras under Connected Devices, each as a Use button with the camera's name. Choose one, press Start Recording, and press Stop Recording when you are done. Press Save Asset to keep the clip, or Reset Asset to record again. Capture Image takes a picture instead. The recording goes into the uploads list, like a chosen file. Press + to put it on the timeline.

The camera needs a secure page: HTTPS, or localhost. On a page without camera access, the recorder says so. To remove Record with camera, set ui.features['recording.camera'] to false.

The editor records MP4 (H.264 video with AAC sound) when the browser can, and WebM otherwise.

Stock videoCopy Anchor Link

With stockMediaApis.pexels, the Video tab of Media shows Stock Videos. The user searches, and clicks a video to add it.

SplitCopy Anchor Link

Select a clip, move the playhead to where you want to cut, and press Split above the timeline. The clip becomes two clips. Split at playhead in the right-click menu does the same.

TrimCopy Anchor Link

Drag the left or right edge of a clip in the timeline. The left edge cuts footage from the start of the clip, and the clip's end stays where it is on the timeline. The right edge changes where the clip ends. A clip cannot start before the first second of its file, and cannot be longer than its file.

From your own code, the itemSetTimelinePlacement action trims the start with sourceStartSeconds: the second of its own file at which the clip begins. See Editor actions.

Volume and muteCopy Anchor Link

The speaker icon on a clip in the timeline mutes and unmutes that clip. To change its level, select the clip, open Audio Effects, and use Volume on the Advanced tab. See Audio.

The mute button and the slider above the timeline change the preview only, not the exported video.

StabilizationCopy Anchor Link

Stabilization removes camera shake from a clip. Select the clip, and choose Stabilize in the right-click menu. The editor replaces the clip with the steady version when the server has finished.

Your media server must be able to download the clip. A clip that is already at an http or https address is sent as it is. A clip that exists only in the browser is first stored through onUploadAsset, with source: 'staged', and the address you return is sent. The editor does not keep that address in the design. See Asset storage.

FiltersCopy Anchor Link

Select a clip and open Effects. Filters such as Grayscale and Sepia change the look of the clip, and adjustments such as brightness and contrast take a number. Filters appear in the exported video. See Effects and filters.

Text to videoCopy Anchor Link

Open Media, choose Video, and press Generate video. The user describes the clip and presses Generate. A notice shows progress while the video is generated. The finished clip appears under Generated, and the user adds it from there.

A clip is 8 seconds long and 16:9 by default. ai.video.maxDurationSeconds and ai.video.aspectRatios limit what users can ask for. See Long-running jobs for your server.

Image to videoCopy Anchor Link

Select a picture on the canvas and press Make video, or choose Make video… in its right-click menu. The AI model makes a new clip from the picture. The job runs like text to video.

The request has "operation": "imageToVideo" and carries the picture in input.source. The picture is sent as its web address when it has one. A picture uploaded from the computer, or a stock photo, is sent as the picture itself, in a data: URL, as input.source.dataUrl.

Clip speedCopy Anchor Link

Clip speed plays a video or sound clip faster or slower. Select the clip, open ⋯ in the bar under it, and choose Speed: 0.5×, 1×, 1.5×, or 2×. For a sound clip, the same choices are in the toolbar above the canvas.

The same footage keeps playing, so the length of the clip on the timeline changes. At 2×, the clip lasts half as long. The start of the clip stays where it is, and the clip after it does not move. The sound changes speed with the picture, so its pitch rises when the clip is faster and falls when it is slower, like a tape played faster or slower.

The preview and the exported video play the clip at the same speed. From your own code, the clipSetSpeed action accepts any speed from 0.25 to 4. The document stores it as playbackRate on the clip.

TransitionsCopy Anchor Link

Transitions will blend one clip into the next, for example with a crossfade.

ConfigurationCopy Anchor Link

EventsCopy Anchor Link

Video clips have no events of their own. They reach you inside the exported video through onExport, and through onUploadAsset when a design is saved. See Events.

TroubleshootingCopy Anchor Link

AudioCopy Anchor Link

Sound comes from video clips, from audio files, from Freesound, from an AI voice, from AI music and sound effects, or from the user's microphone. The editor improves it with presets, audio effects, and an equalizer.

Upload, microphone recording, presets, audio effects, the equalizer, and volume work with no setup. Stock music and text to speech need a key or an AI provider:

<VideoEditor
  stockMediaApis={{ music: { apiKey: 'YOUR_FREESOUND_KEY' } }}
  ai={{ endpointUrl: 'https://api.example.com/ai' }}
/>

UploadCopy Anchor Link

Open Media, choose Audio, and press Upload Audio. Press + on the file under Local Upload to add it to the timeline. The panel lists MP3, WAV, and M4A.

A sound file has no picture, so it appears only in the timeline.

Stock musicCopy Anchor Link

With stockMediaApis.music, the Audio tab of Media shows Stock Music. The user searches, listens to a preview, and adds a track.

Audio presetsCopy Anchor Link

A preset applies a ready-made set of audio effects in one click. Select a clip with sound, open Audio Effects in the tool rail, and choose a preset on the Presets tab. The same presets appear in a row under the canvas.

The editor listens to the clip and marks the presets that suit it with a star.

Presets and effects apply to the preview and to the exported video.

Audio processingCopy Anchor Link

The Advanced tab of Audio Effects has one switch for each effect:

EqualizerCopy Anchor Link

The Graphic EQ tab has ten bands, at 31, 62, 125, 250, and 500 Hz, and at 1, 2, 4, 8, and 16 kHz. Each band goes from −12 dB to +12 dB. The bands cannot be moved until the user turns on the switch next to 10-Band Graphic EQ. The tab says Flat while every band is 0 and none is muted, and Modified after a change. Reset sets all bands to 0.

Volume and muteCopy Anchor Link

To change the level of one clip, turn on Volume on the Advanced tab. To silence a video clip, press the speaker icon on the clip in the timeline. A sound clip has no speaker icon. To silence a sound clip, turn on Volume and set it to 0.

The mute button and the volume slider above the timeline, from 0 to 200%, change the preview only. The exported video keeps the levels of the clips.

Text to speechCopy Anchor Link

Open Media, choose Audio, and press Generate voiceover. The user types the words and presses Generate. Add to timeline adds the chosen recording to the timeline.

The request has "operation": "voice", and your server answers with { items: [{ url, durationSeconds }] }. The duration is optional. ai.voice.voices limits the voices users can choose. See Custom AI endpoint.

AI music generationCopy Anchor Link

The editor makes music and sound effects from a description. Open Media, choose Audio, and press Generate music or Generate sound effect. Both buttons are under Generate voiceover. Cmd+K on a Mac, or Ctrl+K, with nothing selected, lists both too. The user describes the sound, for example "calm piano for a product story" or "a wooden door closing softly", and presses Generate.

The two buttons appear only when your server's model list names a model for them. A server that makes no music shows neither button. See Model list for music.

LengthCopy Anchor Link

Match the video asks for the length of the timeline, to a tenth of a second. The length is kept inside the model's range. The range is shown under the row, for example "This model makes music from 3 seconds to 3 minutes long." A length outside the range is refused with the same sentence, and nothing is sent.

When the range comes from your ai setting and not from a model list, the sentence starts with "This editor" instead, for example "This editor makes music up to 5 minutes long."

Instrumental and Loops cleanlyCopy Anchor Link

Music has an Instrumental switch. It is on at first, so music under a voiceover has no singing. A sound effect has a Loops cleanly switch. It is off at first. Turn it on for a sound whose end joins its start, such as rain.

Placing the soundCopy Anchor Link

Each result plays in the box, with its length. Add to timeline adds the selected sound as a clip with its real length. Music made with Match the video starts at 0 seconds, so it covers the video. Every other sound starts at the playhead. Then the user moves, trims, and sets the volume of the sound like any sound clip.

The real length is the length your server states. When your server does not state it, the editor reads it from the file. A sound whose length cannot be read is not added, and the user sees "The length of this sound could not be read, so it was not placed."

Music gives one result, and Try again asks for another. A sound effect can give up to four results, and the user chooses one.

The box says Uses AI credits. When you set a limit with maxPerSession, it also says how many requests are left, for example Uses AI credits · 2 left. It shows no price.

Generated sound passes through onUploadAsset with source: 'generated'; the design keeps the reference your host returns. See Asset storage.

Microphone recordingCopy Anchor Link

The user records a voiceover with the microphone, inside the editor, while the video plays. Open Media, choose Audio, and press Record voiceover. On a desktop, the recorder takes the place of the Media panel. On a phone, it opens below the canvas.

The browser asks for permission to use the microphone. Recording needs a secure page: HTTPS, or localhost. The recorder never plays the microphone through the speakers.

The recorder has these settings. The browser remembers each choice.

A level meter shows the microphone's level before and during the recording. When the sound is close to the maximum, the top bars turn red, and the recorder shows Too loud.

Press Record, or Enter. After the countdown, the recorder records and shows the time. Press Stop, Enter, or the Space bar to stop. When the video played along, the playhead goes back to where the recording started. Escape cancels a countdown or a recording.

The recording, a take, appears in the recorder. The user plays it, then presses Use this to add it to the timeline, Record again to record another take, or the discard button to delete it. Use this adds the take at the moment on the timeline where its recording started, and selects it. One undo removes it.

A take shorter than half a second is not kept. The recorder then says: "The recording was too short to keep. Try again."

The file is WebM with Opus sound in Chrome, Edge, and Firefox, and MP4 (.m4a) in Safari. It is named voiceover-1, voiceover-2, and so on, with the extension of its format, for example voiceover-1.webm. The editor does not convert it.

With onUploadAsset, Use this first passes the file to your function with source: 'recorded', and the timeline keeps your reference. See Recorded voiceovers. Without it, the take stays in the browser, like a sound file from the user's computer. See Temporary assets.

When the recorder cannot start, it says why, and Record is turned off:

CountdownCopy Anchor Link

Before the recording starts, the recorder counts down. The user chooses the length under Countdown: Off, 3 s, or 5 s. The default is 3 seconds.

To set your own default, pass recording.countdownSeconds: 0, 3, or 5. The user's own choice in that browser still wins. To remove the choice, set ui.features['recording.countdownChoice'] to false. The recorder then always uses your default, or 3 seconds.

<VideoEditor
  recording={{ countdownSeconds: 5 }}
  ui={{ features: { 'recording.countdownChoice': false } }}
/>

Input levelCopy Anchor Link

By default, the browser keeps the user's voice at an even level. To set the level by hand, the user turns off Automatic level. A Level slider then appears under the level meter, from 10% to 200%. The meter shows the level after the slider, and the recording has the same level.

To remove both settings, set ui.features['recording.inputLevel'] to false. The browser's automatic level is then always used.

Clean up noiseCopy Anchor Link

Each take has a Clean up noise box. When it is ticked, Use this adds the take with the Clean Up Noise preset already on it. It is the same preset as in Audio presets, so the preview and the exported video both have it. It runs in the browser, and it uses no AI and no credits. One undo removes the take and the preset together.

To tick the box by default, pass recording.cleanUpNoise: true. The user's own choice in that browser still wins. To remove the box, set ui.features['recording.cleanUp'] to false. The take then gets the preset only when recording.cleanUpNoise is true.

Several takesCopy Anchor Link

Record again keeps the take and records another one. The newest take is shown at the top. The earlier takes are listed under Earlier takes, newest first, as Take 2, Take 1, and so on. Each has a play button, Use, and a delete button. Use adds that take at the moment on the timeline where its own recording started.

The takes exist only while the recorder is open. When the user closes the recorder with takes that were not used, the recorder asks first, for example: "Close the recorder? 2 recordings you have not used will be lost."

The recorder keeps at most 10 takes. At 10, Record again is turned off, and the recorder says: "You have kept 10 takes, the most the recorder holds. Delete one to record again."

To keep one take at a time, set ui.features['recording.takes'] to false. Record again then replaces the take. For a take longer than 30 seconds, the recorder first asks, for example: "Discard this 1:20 recording?"

To receive every take in your storage, not only the one the user adds, see Recorded voiceovers.

Script and prompterCopy Anchor Link

The recorder has a Script section for the words the user reads. While the user records, a prompter strip shows the words and moves on by itself.

The script comes from one of three places:

• Type or paste: the user types or pastes the words. The prompter moves at the Speed that the user sets, from 80 to 220 words a minute. The default is 140. The browser remembers the speed.
• From captions: the user picks a caption track of the design. The prompter follows the times of the captions at the playhead, so each line appears when the captions show it.
• Your code: pass the words as recording.script, or run the voiceoverSetScript action. The words appear in the Type or paste box, where the user can still change them.

<VideoEditor
  recording={{ script: 'Welcome to our spring sale. Everything is 20% off.' }}
/>

A new value of recording.script replaces the current script. Leaving the prop out changes nothing. A script has at most 20,000 characters. A longer value is ignored, with a warning in the console.

When the design is saved, the script is saved with it as voiceoverScript. See Saving and loading. To remove the Script section and the prompter, set ui.features['recording.script'] to false.

The Type or paste box has Write with AI. The user answers "What is the video about?", then presses the button. The words come back into the box, and the user can change them. Under the button, the recorder says Uses AI credits, and how many requests are left when you set a limit. Nothing is sent until the user presses the button.

The request is the same text request as the Text panel's: { "operation": "text", "prompt": "…" }. Your server answers with text. See Custom AI endpoint.

Captions from a recordingCopy Anchor Link

Each take has Generate captions. It writes down what was said, then adds the take and a caption track under it, timed to the voice. The caption track starts where the take starts. Under the button, the recorder says "Adds this take with a caption track of its words. Uses AI credits.", with the requests left when you set a limit. Nothing is sent until the user presses the button.

When the transcription fails, the take is not added, and the recorder says: "The captions could not be written:", then the reason, then "The take was not added; try again, or press Use this." When no speech is heard, the recorder says: "No speech was heard in this take, so there are no captions to add."

The recorder sends the first language of ai.captions.languages. Without a list, it sends no language, and the transcription service detects it. To remove the button, set ui.features['recording.captions'] to false. ui.generative hides it wherever it hides captions.

Re-record part of a clipCopy Anchor Link

To fix a part of a voiceover without recording all of it again, select the sound clip on the timeline and open the recorder. Turn on Replace part of the selected clip, then set From and To. Type a time to a tenth of a second, or press Playhead to use the position of the playhead.

Press Record. There is no countdown. The video plays for 2 seconds before From, so the user hears what comes before. It never starts before 0:00. The recording starts at From and stops by itself at To. The take shows the range, for example "Replaces 0:05.0 to 0:07.5 of the clip".

Use this cuts the clip at From and at To, removes the part between them, and places the new take there. The new take fills the range exactly, with no gap and no overlap. One undo brings back the whole clip.

A range must be inside the selected clip and at least half a second long. Otherwise the recorder says why, for example "The range must be inside the selected clip, from 0:02.0 to 0:12.0." or "The range must be at least half a second long.", and Record is turned off.

On a phone, a selected clip replaces the bottom bar with its own buttons. There, select the sound clip and press Re-record part. The recorder opens with Replace part of the selected clip already on.

To change the time that plays before the range, pass recording.preRollSeconds, from 0 to 10. To remove the option, set ui.features['recording.punchIn'] to false.

Audio fadesCopy Anchor Link

Audio fades raise the sound of a clip from silence at its start, and lower it to silence at its end, in straight lines. They work on sound clips and on video clips with sound. The picture is not faded.

Select the clip and open ⋯ in the bar under it, then choose Fades. For a sound clip, the Fades (s) group is in the toolbar above the canvas. Each has two fields in seconds: In for the fade-in and Out for the fade-out. A value is kept between 0 and the length of the clip, and never more than 60 seconds. 0 removes the fade. Each change is one step to undo.

The preview and the exported video fade the sound at the same moments. When a clip is split, the fade-in stays with the first piece and the fade-out with the second. From your own code, use the audioSetFades action with fadeInSeconds and fadeOutSeconds. The document stores them as fadeIn and fadeOut on the clip.

Sound effects libraryCopy Anchor Link

The sound effects library will offer short sounds, such as clicks and whooshes, to add to the timeline.

ConfigurationCopy Anchor Link