Rails

ERB renders the editor's host element. A Stimulus controller mounts the editor in the browser and releases it when Turbo removes the view. The permanent custom-element alternative is described under Turbo navigation.

InstallationCopy Anchor Link

Install the package and serve its distribution files from public/sdk/:

npm install @layermetry/media-editor
mkdir -p public/sdk
cp -R node_modules/@layermetry/media-editor/dist/. public/sdk/

Copy the distribution again after each package update. Keep the browser assets beside the bundle at the same relative paths. No React installation or JavaScript bundler is required for this importmap setup.

RequirementsCopy Anchor Link

• Rails with Turbo. The example application uses Rails 8.1.3 with turbo-rails and importmap-rails 2.2.3.
• A license key. See License keys.
• A page served over HTTPS, or from localhost. See Requirements.

UsageCopy Anchor Link

Use the following files in an existing Rails application with Turbo and importmap-rails. The controller registration is explicit; replace the application entry shown here, or add the same registration to your existing Stimulus application once.

Rails.application.config.media_editor = {
  license_key: ENV.fetch("LAYERMETRY_LICENSE_KEY", "YOUR_LICENSE_KEY")
}

Set LAYERMETRY_LICENSE_KEY to a key valid for your origin. This license key reaches the browser. Keep provider secrets on the Rails server.

Rails.application.routes.draw do
  get "editor", to: "editors#show"
end

class EditorsController < ApplicationController
  def show
  end
end

pin "application"
pin "@hotwired/turbo-rails", to: "turbo.min.js"
pin "@hotwired/stimulus", to: "stimulus.min.js"
pin_all_from "app/javascript/controllers", under: "controllers"

import "@hotwired/turbo-rails";
import { Application } from "@hotwired/stimulus";
import MediaEditorController from "controllers/media_editor_controller";

const application = Application.start();
application.register("media-editor", MediaEditorController);

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Media editor</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>
    <meta name="turbo-cache-control" content="no-preview">
    <%= javascript_importmap_tags %>
  </head>
  <body><%= yield %></body>
</html>

The shared browser helper adds the current CSRF token to your application's non-GET requests. It leaves cross-origin requests unchanged. railsAI sends captions as multipart and other AI requests as JSON, so a Rails endpoint can keep forgery protection enabled.

export async function csrfFetch(input, init = {}) {
  const url = new URL(input instanceof Request ? input.url : String(input), window.location.href);
  const method = (init.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
  const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
  if (url.origin === window.location.origin && !['GET', 'HEAD', 'OPTIONS'].includes(method)) {
    const token = document.querySelector('meta[name="csrf-token"]')?.content;
    if (!token) throw new Error('Missing Rails CSRF token');
    headers.set('X-CSRF-Token', token);
  }
  return window.fetch(input, { ...init, headers });
}

export async function railsAI(url, request, signal, extraHeaders = {}) {
  let body;
  const headers = { ...extraHeaders };
  if (request.input.operation === 'captions') {
    const input = request.input;
    body = new FormData();
    body.append('audio', input.audio, input.audio.name ?? 'audio.wav');
    body.append('kind', 'captions');
    body.append('type', request.type);
    if (input.language !== undefined) body.append('language', input.language);
    if (input.format !== undefined) body.append('format', input.format);
    if (request.options !== undefined) body.append('options', JSON.stringify(request.options));
  } else {
    headers['Content-Type'] = 'application/json';
    body = JSON.stringify(request);
  }
  const response = await csrfFetch(url, { method: 'POST', headers, body, signal });
  if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
  return response.json();
}

<section data-controller="media-editor"
  data-media-editor-license-key-value="<%= Rails.application.config.media_editor.fetch(:license_key) %>">
  <div data-editor-host style="position: fixed; inset: 0"></div>
</section>

import { Controller } from "@hotwired/stimulus";
import { mountVideoEditor } from "/sdk/embed.modern.js";

export default class extends Controller {
  static values = { licenseKey: String };

  connect() {
    if (this.editor) return;
    this.events = new AbortController();
    const box = this.element.querySelector('[data-editor-host]');
    box.hidden = false;
    this.editor = mountVideoEditor(box, {
      licenseKey: this.licenseKeyValue,
      onExport: (file) => console.log(`Exported ${file.name}: ${file.size} bytes, ${file.type}`),
      onClose: () => { console.log('The editor was closed'); this.stop(); },
    });
    document.addEventListener('turbo:before-cache', () => this.stop(), { signal: this.events.signal });
  }

  stop() {
    this.editor?.unmount();
    this.editor = null;
    this.element.querySelector('[data-editor-host]').hidden = true;
  }

  disconnect() {
    this.events?.abort();
    this.stop();
  }
}

For each complete example below, replace the view and media_editor_controller.js together. Keep the shared helper, layout, routes, importmap and application registration above. Restart Rails after changing initializer configuration. Start the server:

bin/rails server -p 3000

Open http://localhost:3000/editor. Usage mounts an editor that fills the viewport; its export and close callbacks log in the browser console. Later Options excerpt blocks show only the settings being explained. Imports, callback helpers and lifecycle belong to their complete files.

The topic examples unmount before Turbo caches the page and when Stimulus disconnects the view. Their request and UI cleanup also runs at that point. Navigating away therefore discards unsaved editor state; use Saving and loading to persist it. These view-scoped mount examples are distinct from the layout-wide permanent custom-element alternative below.

Relative /api/... requests require matching Rails routes/actions or another reachable backend. Rails server startup does not create those endpoints. The complete files name HTTP methods, multipart fields, JSON wrappers and response shapes. Replace provider credentials and example.com URLs; supply the media and sticker fixtures named beside each file. JSON-backed actions must return JSON, not a Turbo Stream or redirect. Keep your existing authentication and authorization on stored assets and designs.

For a same-origin Rails AI route, use requestFn with railsAI so requests carry CSRF. A bare endpointUrl does not add the Rails token. Long-running job handles returned through requestFn need whole status/cancel addresses: HTTPS, or loopback HTTP for development on your own computer. The SDK polls and cancels those jobs directly; its cancellation POST does not call csrfFetch. Supply signed or otherwise authenticated job-service URLs rather than a session-protected Rails cancellation action that requires the page token. Cross-origin services and the assistant media API need their own documented authentication/CORS setup; the local CSRF helper does not authenticate them.

Launch from a buttonCopy Anchor Link

Mount the editor after the user presses the button. onClose unmounts it; Stimulus disconnect and Turbo caching use the same cleanup.

<section data-controller="media-editor"
  data-media-editor-license-key-value="<%= Rails.application.config.media_editor.fetch(:license_key) %>">
  <button type="button" data-action="media-editor#open">Edit video</button>
  <div data-editor-host hidden style="position: fixed; inset: 0; z-index: 1000"></div>
</section>

import { Controller } from "@hotwired/stimulus";
import { mountVideoEditor } from "/sdk/embed.modern.js";

export default class extends Controller {
  static values = { licenseKey: String };

  connect() {
    this.events = new AbortController();
    document.addEventListener('turbo:before-cache', () => this.close(), { signal: this.events.signal });
  }

  open() {
    if (this.editor) return;
    const box = this.element.querySelector('[data-editor-host]');
    box.hidden = false;
    this.editor = mountVideoEditor(box, {
      licenseKey: this.licenseKeyValue,
      onExport: (file) => console.log(`Exported ${file.name} (${file.type})`),
      onClose: () => this.close(),
    });
  }

  close() {
    this.editor?.unmount();
    this.editor = null;
    this.element.querySelector('[data-editor-host]').hidden = true;
  }

  disconnect() {
    this.events?.abort();
    this.close();
  }
}

Expected result: Edit video opens the editor; Close removes it and the button opens it again. Use the shared setup and server command in Usage.

ConfigurationCopy Anchor Link

Pass objects, functions, and files through the custom element's props property or the second argument of mountVideoEditor. The complete topic files below use the mount function inside a Stimulus controller.

update(patch) shallow-merges options. replace(options) replaces the mount handle's complete options; assigning element.props replaces the element's own options too. Options omitted from replacement return to their defaults, except attributes on a custom element remain its base configuration. element.update(patch) merges into its own options.

Attributes hold strings, numbers, booleans, or JSON values. Use lowercase hyphenated names such as license-key and dark-mode. Functions must be properties. The license key stays text; other values are parsed as JSON when possible. Explicit properties override attributes.

Layout and sizingCopy Anchor Link

Set the host element's CSS width and height to size the editor. The editor fills that host.

Use CSS sizes such as width: 390px or height: 80vh. The complete example below switches between narrow and wide containers and adds a fullscreen button.

#editor { width: 390px; height: 80vh; max-width: 100%; }

Container sizingCopy Anchor Link

Give the host an explicit CSS height, such as height: 80vh or height: calc(100vh - 64px). 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.

const options = {
    "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:

The role names above are accepted as keys of the theme object.

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';

// In the Stimulus controller, update the existing mount handle.
this.editor.update(settings);

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, panels, and badges. Each value is a CSS length.

const options = {
    "radii": { sm: '2px', md: '4px', lg: '8px', full: '9999px' }
};

sm is for badges, md for buttons and fields, lg for panels, and full for round buttons. 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:

const options = {
    "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.

const options = {
    "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.

const options = {
    "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:

const options = {
    "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:

const options = {
    "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.

const options = {
    "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.

const options = {
    "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:

const options = {
    "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:

const options = {
    "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.

/** @type {import('@layermetry/media-editor').UiConfig} */
const uiControls = {
  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.

/** @type {import('@layermetry/media-editor').UiConfig} */
const uiRail = {
  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.

/** @type {import('@layermetry/media-editor').CustomAction[]} */
export const customActions = [{
  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');
  },
}];

/** @param {import('@layermetry/media-editor').CustomActionEvent} event */
export function onCustomAction(event) {
  console.log(event.actionId, event.status);
}

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

this.editor.update({ customActions, 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:

const options = {
    "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:

const options = {
    "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:

const options = {
    "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:

const options = {
    "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:

mountVideoEditor(box, {
  role: 'adopter',
  allowUnlock: true,
  onUnlock: handleUnlock,
  defaultLocks: { move: true },
});

In markup, the role attribute is editor-role, not role. On every HTML element, role describes the element to screen readers, so the editor leaves role to the browser and never reads it. allow-unlock with no value means true. default-locks takes JSON text. onUnlock is a function, so it goes in props, like onSaveTemplate.

The element reads its attributes when it starts, and again each time you set props. When props and an attribute set the same prop, props wins. In props, the role is named role. To change the role while the editor is open, call update on the element, for example editor.update({ role: 'viewer' }). Changing an attribute alone does not reach an editor that is already open. The editor uses a new value of props 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:

const options = {
    "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, such as a stock photo, is stored by its address and not uploaded again.

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. A later save keeps the key and sends nothing to onUploadAsset again. This is true for a picture, a clip, or a sound, including one added from the generated results, by Edit with AI, or by the AI assistant. 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.

const options = {
    "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:

const options = {
    "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.

const options = {
    "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:

const options = {
    "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:

const options = {
    "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:

const options = {
    "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:

const options = {
    "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:

const options = {
    "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:

const options = {
    "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:

const options = {
    "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 in the options object you give to the mount function.

Default: off.

Session limitsCopy Anchor Link

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

const options = {
    "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:

const options = {
    "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:

const options = {
    "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.

For generated voice, your server can return { items: [{ url, durationSeconds }] }, with a positive length in seconds for each file. When no usable length is supplied, the editor reads the sound file before adding it. Serve the file with CORS headers that allow the editor page to read it. If the length cannot be read, the editor shows “The length of this sound could not be read, so it was not placed.” and adds no clip.

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:

const options = {
    "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 options. 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:

const options = {
    "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:

const options = {
    "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.

DOM events on the custom elementCopy Anchor Link

The custom element emits notifications as DOM events. Callbacks that return a value, such as onGetTemplates, must remain properties; a listener cannot return that value to the editor.

Handling the exportCopy Anchor Link

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

const options = {
    "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.

Use this Rails action for POST /api/videos. It receives the multipart video field used by the complete file above and returns JSON with HTTP 201. It accepts all selected export formats shown here and writes a temporary file; configure persistent storage before using this in your product.

Rails.application.routes.draw do
  get "editor", to: "editors#show"
  namespace :api do
    post "videos", to: "videos#create"
  end
end

class Api::VideosController < ApplicationController
  def create
    file = params.require(:video)
    unless file.respond_to?(:read) && file.respond_to?(:content_type)
      return render json: { error: "Missing video file" }, status: :bad_request
    end
    allowed_types = %w[video/mp4 video/webm image/gif]
    unless allowed_types.include?(file.content_type)
      return render json: { error: "Unsupported output format" }, status: :unsupported_media_type
    end
    # Replace temporary storage with your own persistent storage service.
    directory = Rails.root.join("tmp", "editor-exports")
    FileUtils.mkdir_p(directory)
    path = directory.join(SecureRandom.uuid)
    File.binwrite(path, file.read)
    render json: { name: file.original_filename, type: file.content_type }, status: :created
  end
end

Do not disable forgery protection for this session-backed action. The host helper sends the current X-CSRF-Token from csrf_meta_tags. Content-Type for multipart is supplied by the browser. For large files, use your storage service's direct-upload flow if your Rails host has a request-size limit.

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 options.

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 options:

const options = {
    "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.