Options
Every option the video editor accepts.
Every option of the video editor. With React, each option is a prop of VideoEditor. With the custom element or mountVideoEditor, each option is a key of props, and text options can also be attributes, such as license-key for licenseKey.
TypeScript names the type VideoEditorProps, and VideoEditorReactProps for the React component.
Address security
Use HTTPS for every server and remote media address you pass to the editor. The only HTTP exceptions are http://localhost, http://127.0.0.1 and http://[::1], for development on your own computer. Relative paths and storage keys must resolve to an HTTPS address outside local development.
Hosted requests that carry your license key, including hosted captions, are refused over HTTP to another computer. For other addresses, HTTPS is the integration rule; the SDK does not enforce it on every option.
This rule also applies to addresses in templates, stock results and callback requests. The former proxyUrl option follows the same rule; use endpointUrl in new integrations.
Custom actions
| Name | Type | Default | Description |
|---|---|---|---|
customActions | Read-only CustomAction[] | None | Adds host buttons to the selection controls and right-click menu. See Custom actions. |
onCustomAction | (event: CustomActionEvent) => void | None | Receives started and a final run status. |
Required
| Name | Type | Default | Description |
|---|---|---|---|
licenseKey | string | none | Your license key. See License keys. |
onClose | () => void | none | Called when the user closes the editor, and after Save & Exit. |
Export
| Name | Type | Default | Description |
|---|---|---|---|
onExport | (file: File, extras?) => void | none | Receives the exported MP4, WebM, or GIF file. Without it, there is no Save & Exit. See Export. |
onExportProgress | (event) => void | none | Progress of a Save & Exit export after the editor has closed, and the reason when an export is refused. |
onThumbnails | (delivery) => void | none | Receives a still picture and a short clip of each export. |
videoThumbnails | 'ask' | 'always' | 'never' | 'ask' | When thumbnails are made. Needs onThumbnails, except 'never'. |
export | { experimental: boolean } | none | Deprecated. Accepted, and changes nothing: every export uses the same engine. |
Saving and storage
| Name | Type | Default | Description |
|---|---|---|---|
onSaveTemplate | ({ template }) => Promise<void> | none | Stores a design or a draft. See Saving and loading. |
onGetTemplates | () => Promise<Template[]> | none | Returns the designs for the Templates panel. Use HTTPS for remote media addresses in returned templates. |
defaultTemplate | Template | none | The design the editor opens with. Use HTTPS for remote media addresses in the template. |
defaultVideo | File | none | A video file the editor opens with. |
templateCanvasPolicy | 'adopt' | 'fit' | 'place' | 'adopt' | What happens when a design comes from a canvas of another size. |
mediaAddPolicy | 'fit' | 'fill' | 'none' | 'fit' | Placement of new pictures and clips: fit inside, cover the canvas, or use native pixels centered. Explicit action sizes win. Any other value is treated as 'fit', with one console warning. |
templateMetadata | object | none | Your fields for saved designs (metadata), and your brand: brands and activeBrandId, or the one-brand colors, textStyles, and logoUrl. See Brand kits. Use HTTPS for remote brand logo addresses. |
onBrandChange | (brandId: string) => void | none | Called with the id of the active brand kit when the editor opens and on every switch. See Brand kits. |
onUploadAsset | (file, ctx) => Promise<{ url }> | none | Stores media files in your storage. See Asset storage. Return an HTTPS address, or a storage key that resolves to one. |
resolveAssetUrl | (storedUrl, ctx) => Promise<string> | none | Turns a stored reference into an address the browser can load. Resolve remote media to HTTPS. |
assetMetadata | Record<string, string> | none | Your own fields, added to the context of every upload. |
inlineTemplateMedia | boolean | false | Stores media inside the design record instead of uploading it. |
assetBaseUrl | string | none | The address that stored references without http are joined to. Use an HTTPS base address. |
uploadApiUrl | string | none | The server of the older upload path. Prefer onUploadAsset. Use HTTPS. |
workflows | array | none | Your workflows for the Templates panel. See Templates. |
For mediaAddImageFromUrl and mediaAddVideoFromUrl, executeAsync reads file dimensions before placing the item. That read has a 10-second limit. If it fails or reaches the limit, the item uses its previous default placement; an explicit box stays as requested. The synchronous execute does not read dimensions and ignores the file's shape. It places a picture in a fixed 300 × 300 box and a video in a fixed 400 × 300 box, both at x 100, y 100, unless you pass a box. Use executeAsync when you want the item fitted with mediaAddPolicy. This does not change an action's name or arguments.
Item locking
These options are part of item locking, which is new in
@layermetry/media-editor. Item locking needs version 1.0.0 or later; versions before 1.0.0 do not have these options.With the custom element, the attributes are editor-role, allow-unlock and default-locks. onUnlock is a function, so it can only be set in props. See Item locking in your framework guide.
| Name | Type | Default | Description |
|---|---|---|---|
role | 'creator' | 'adopter' | 'viewer' | 'adopter' | Who is editing. A creator ignores locks, an adopter obeys them, and a viewer changes nothing. |
allowUnlock | boolean | false | Lets an adopter ask to unlock items. A creator may always unlock. |
onUnlock | (event) => answer, or a Promise of an answer | none | Called before every unlock. Answer false, { allowed: false } or reject to refuse it. Answer { ref } to store your audit id in the unlock record. |
defaultLocks | object, for example { move: true } | the design's own | Replaces the design's own default locks for this session. A save never writes it. |
Servers and media
| Name | Type | Default | Description |
|---|---|---|---|
mediaApiUrl | string | none | Your media server: speech to text, background removal, stabilization, and the assistant chat. Use HTTPS. |
stockMediaApis | object | none | Pexels, Unsplash, and Freesound. See Stock media. Use HTTPS for provider endpoints and returned media addresses. |
showAttributionOverlay | boolean | false | The starting value of Show photo credits on the canvas in the Export panel. See Photo credits. |
includeAttributionInExport | boolean | false | The starting value of Include photo credits in the export. |
stickers | { sources: StickerSource[] } | the built-in set | The sticker sources. See Stickers and GIFs. Use HTTPS for remote source and sticker addresses. |
googleFonts | { hosted: true } | { endpointUrl } | { requestFn } | Built-in families | Where the font picker gets the whole Google Fonts catalog. See Fonts. Use HTTPS for a custom endpoint. |
googleFontsApiKey | string | none | Deprecated. Sends your Google key from the browser. Use googleFonts. |
AI
Configure generation through ai; expose developer tests separately with showAiPlayground.
| Name | Type | Default | Description |
|---|---|---|---|
ai | EditorAIConfig | None | Configures transport, operations and hooks. |
ai.endpointUrl | string | None | Sends requests to your server without the SDK license header. Use HTTPS. |
ai.requestFn | AIRequestFunction | None | Passes a request and AbortSignal to your callback. Use HTTPS for requests made by your callback. |
ai.hosted | true | None | Coming soon. Available only with an enterprise licence from Layermetry. Use your own endpointUrl or requestFn. |
ai.headers | AIHeaderValues or AIHeadersFunction | None | Supplies same-origin endpoint headers before each attempt. |
ai.credentials | omit, same-origin or include | same-origin | Sets endpoint request cookie behavior. |
ai.timeoutMs | number | None | Limits submission time with your endpoint or function. |
ai.maxRetries | number | 0 | Sets extra endpoint attempts with an idempotency header. |
ai.idempotencyKeyHeader | string | None | Names the server header used with positive maxRetries. |
ai.brand | false or { addToPrompt?, operations? } | Brand on | Controls the Use brand switch in the Generate boxes. false removes it. See Brand kits. |
ai.limits | { maxPerSession?: number } | Unlimited | Caps attempts across operations in a session. |
ai.text | Boolean or operation options | Enabled with usable AI | Configures text independently. |
ai.textRewrite | Boolean or operation options | Enabled with usable AI | Configures textRewrite independently. |
ai.image | Boolean or operation options | Enabled with usable AI | Configures image independently. |
ai.imageEdit | Boolean or operation options | Enabled with usable AI | Configures imageEdit independently. |
ai.sticker | Boolean or operation options | Enabled with usable AI | Configures sticker independently. |
ai.svgPath | Boolean or operation options | Enabled with usable AI | Configures svgPath independently. |
ai.video | Boolean or operation options | Enabled with usable AI | Configures video independently. |
ai.imageToVideo | Boolean or operation options | Enabled with usable AI | Configures imageToVideo independently. |
ai.captions | Boolean or operation options | Controls visible | Connect transcription with transport, or set mediaApiUrl. No audio is sent without a host destination. false hides the controls. Use HTTPS for the captions endpoint. |
ai.voice | Boolean or operation options | Enabled with usable AI | Configures voice independently. |
ai.music | Boolean or operation options | Enabled with usable AI | Configures music independently. |
ai.soundEffect | Boolean or operation options | Enabled with usable AI | Configures soundEffect independently. |
ai.onGenerationError | AIGenerationErrorObserver | None | Observes one failure per attempt. |
ai.onGenerationEvent | AIGenerationEventObserver | None | Observes generation lifecycle events. |
ai.errorMessages | AIErrorWordingByCategory | SDK wording | Replaces error wording by category. |
ai.supportUrl | HTTPS string | None | Adds Contact support on account and transport failures. Use HTTPS. |
showAiPlayground | boolean | false | Adds AI testing to the developer Studio. |
templateGeneration | TemplateGenerationConfig | None | Configures generation of complete templates through a separate callback. |
Choose exactly one transport. headers, credentials and retries require endpointUrl. With requestFn, only timeoutMs is accepted. The former proxyUrl name is not supported.
Operations share models, defaultModel, providers, transport and maxPerSession. Choose either models or providers. See AI providers for defaults, fields and restrictions.
Recording
| Name | Type | Default | Description |
|---|---|---|---|
recording | RecordingConfig | none | Defaults for the voiceover recorder. See Microphone recording. |
recording.countdownSeconds | 0 | 3 | 5 | 3 | The countdown before recording starts. 0 is no countdown. |
recording.cleanUpNoise | boolean | false | Ticks Clean up noise by default. |
recording.uploadAllTakes | boolean | false | Sends every take to onUploadAsset, each with ctx.take. |
recording.script | string | none | The words for the prompter, at most 20,000 characters. A new value replaces the current script. |
recording.preRollSeconds | number | 2 | How long the video plays before the range when the user re-records part of a clip. From 0 to 10. |
The user's own choices in the recorder win over these defaults, unless a ui.features switch hides the choice. A value that is not allowed is ignored, with one warning in the console.
Look and layout
| Name | Type | Default | Description |
|---|---|---|---|
theme | Partial<Record<SemanticRole, string>> | the Layermetry palette | Colors by role name. See Theming. |
darkMode | boolean | by container width | true for the dark theme, false for the light theme. |
enableThemeToggle | boolean | false | Adds a light and dark switch to the app bar. |
showThemeCreator | boolean | false | true shows the palette button that opens the Customization Studio. Any other value hides it. See Editor settings. |
typography | { heading, body, mono } | the built-in fonts | Fonts of the editor's panels and buttons. |
radii | { sm, md, lg, full } | the built-in rounding | Corner rounding of the editor's panels and buttons. |
logo | string | none | The address of a square logo for the app bar. Use HTTPS for the logo address. |
icons | Icon-name map | Built-in icons | Accepts IconData or React components; see Editor settings. |
ui | UiConfig | none | Hides, reorders, and renames tools, and places AI controls. See UI customization. |
ui.selection | ItemListConfig | The default lists | Hides, orders, labels and chooses display for the controls of the selected item. Applied after the default lists, on the desktop bar and on the phone. |
ui.toolbar | ItemListConfig | None | Older setting for toolbar groups. Its group ids are translated into control ids, with one console warning. Use ui.selection instead. |
ui.customActions.shown | CustomActionsUiConfig["shown"] | Surface counts | Sets custom-action overflow counts within their maximums. |
itemActions | object or false | the default actions | The menu of a selected item in the compact layout. |
width, height | number or string | 100% | With React: the size of the component's box. With the custom element: the size of the editor inside the element. |
Preferences
| Name | Type | Default | Description |
|---|---|---|---|
preferences | object | none | Starting values for the user's preferences. They win over values stored in the browser. |
onPreferenceChange | (key, value, all) => void | none | Called on every change of a preference. |
License
| Name | Type | Default | Description |
|---|---|---|---|
apiUrl | string | https://api.layermetry.com/social | The license server. Use HTTPS. |
statusUrl | string | none | Signed status files, read when the license server cannot be reached. Use HTTPS. |
onLicenseState | (report) => void | none | Each change of the license state. See License validation. |
renderLicenseBlocked | (state) => ReactNode | the default screen | Your own screen when the license is refused. |
Preview
| Name | Type | Default | Description |
|---|---|---|---|
player | { experimental: boolean } | the default preview | { experimental: true } turns on the newer preview engine. It is still in development. |