Installation

What you are installing

@layermetry/media-editor is one npm package that puts a working image editor or video editor inside your own page. It is not an iframe and it is not a hosted service you redirect people to. The editor becomes part of your page, so it inherits your fonts and your layout and you can style it. The current version is 2.0.0.

npm install @layermetry/media-editor

That is one package, about 45 MB on disk. Version 1 pulled in 162 packages; this one pulls in none. The part that ships to the browser is a single self-contained bundle of about 1.1 MB after compression.

If you are moving from version 1, the package name has changed. Anything that still reads @layermetry/media-editor is out of date — the package is now @layermetry/media-editor.

What it needs to run


Node.js	18 or newer, to install and build. The editor itself runs in the browser.
A browser	Any current Chrome, Edge, Firefox or Safari. The editor uses the browser’s own video hardware for exporting, so an out-of-date browser will not export.
A licence key	Generate one in your layermetry account, under SDK licences. It is checked in the browser at run time.

React 18 and React 19 both work

Version 2 works in React 18 and React 19. It also works with no React at all. This is a change worth spelling out, because the old documentation said the opposite. Version 1 was built on React 18.2.0 and told you to pin react@18.2.0 and react-dom@18.2.0. Version 2 does not. The editor no longer brings its own copy of React into your application: it ships as a custom element, which is a tag the browser itself knows how to render, the same way it knows <video>. Your framework only has to put the tag on the page. That is why the same bundle runs in React, in Vue with no React installed at all, in Angular, in Svelte, in Next.js and in a plain HTML file.

Delete any react@18.2.0 or react-dom@18.2.0 pin you added for version 1. It is no longer needed, and holding React back may now be blocking other upgrades in your project for no reason.

Put an editor on the page

There are two ways in, and they do the same thing.

mount(element, props) — a function. You give it a DOM element and the settings, it puts the editor inside. This works everywhere, in any framework and in none.
The React components — ImageEditor and VideoEditor, from @layermetry/media-editor/react. This is a thin wrapper around the same thing, so React people can pass props and not think about DOM elements.

Pick the tab for what you are using.

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

export default function Editor() {
  return (
    <ImageEditor
      licenseKey={process.env.REACT_APP_LAYERMETRY_KEY}
      style={{ height: '100vh' }}
    />
  );
}

Works on React 18 and React 19. No version pin is needed.

The editor runs in the browser and touches browser-only things, so it must not be rendered on the server. next/dynamic with ssr: false is how you say that.

'use client';

import dynamic from 'next/dynamic';

const VideoEditor = dynamic(
  () => import('@layermetry/media-editor/react').then((m) => m.VideoEditor),
  { ssr: false }
);

export default function Editor() {
  return (
    <VideoEditor
      licenseKey={process.env.NEXT_PUBLIC_LAYERMETRY_KEY}
      style={{ height: '100vh' }}
    />
  );
}

If you are using the video editor, you also need two response headers. See Video editing needs two headers below.

Vue needs no React installed. The editor is a custom element, and Vue renders it like any other tag.

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import { mount } from '@layermetry/media-editor';

const host = ref(null);
let editor;

onMounted(() => {
  editor = mount(host.value, {
    licenseKey: import.meta.env.VITE_LAYERMETRY_KEY,
  });
});

// Tear the editor down when the component goes away, so its
// memory and its event listeners go with it.
onBeforeUnmount(() => editor?.destroy());
</script>

<template>
  <div ref="host" style="height: 100vh"></div>
</template>

Angular will warn about a tag it does not recognise unless you tell it that some tags come from the browser rather than from Angular. That is what CUSTOM_ELEMENTS_SCHEMA does.

import {
  Component,
  ElementRef,
  ViewChild,
  AfterViewInit,
  OnDestroy,
  CUSTOM_ELEMENTS_SCHEMA,
} from '@angular/core';
import { mount } from '@layermetry/media-editor';

@Component({
  selector: 'app-editor',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<div #host style="height: 100vh"></div>`,
})
export class EditorComponent implements AfterViewInit, OnDestroy {
  @ViewChild('host') host!: ElementRef<HTMLDivElement>;
  private editor?: { destroy(): void };

  ngAfterViewInit() {
    this.editor = mount(this.host.nativeElement, {
      licenseKey: environment.layermetryKey,
    });
  }

  ngOnDestroy() {
    this.editor?.destroy();
  }
}

<script>
  import { onMount, onDestroy } from 'svelte';
  import { mount } from '@layermetry/media-editor';

  let host;
  let editor;

  onMount(() => {
    editor = mount(host, { licenseKey: import.meta.env.VITE_LAYERMETRY_KEY });
  });

  onDestroy(() => editor?.destroy());
</script>

<div bind:this={host} style="height: 100vh"></div>

No build step and no framework. Importing the package registers the custom elements with the browser; after that the tag works like any other tag.

<!doctype html>
<html>
  <body>
    <media-editor-video id="editor" style="height: 100vh"></media-editor-video>

    <script type="module">
      // Importing the package teaches the browser what
      // <media-editor-video> means.
      import '@layermetry/media-editor';

      document.getElementById('editor').licenseKey = 'YOUR_KEY';
    </script>
  </body>
</html>

You can also skip the tag and call mount yourself:

<div id="host" style="height: 100vh"></div>

<script type="module">
  import { mount } from '@layermetry/media-editor';
  mount(document.getElementById('host'), { licenseKey: 'YOUR_KEY' });
</script>

The licence key

The editor checks a licence key in the browser when it starts.

<ImageEditor licenseKey={process.env.NEXT_PUBLIC_LAYERMETRY_KEY} />

Three things about it that are worth knowing before you plan around it. The check happens without a network call. The key carries a signature, and the editor checks the signature using a public key it already has. It does not phone home to ask whether your key is real. It fails open. If layermetry’s servers are unreachable, the editor keeps working. Your users do not lose their work because of an outage at our end. It is safe in the browser. The key names which website may run the editor, and it is checked against the address the page is actually served from. It is not a password, so putting it in a NEXT_PUBLIC_ or VITE_ variable is fine.

Exporting is faster if you ask for it

Exporting — turning what is on the timeline into a finished file — runs entirely in the reader’s own browser tab, using the video hardware in their machine. No file is uploaded, and there is no ffmpeg involved. In version 1, ffmpeg arrived as 31 MB of WebAssembly that every visitor downloaded; in version 2 that is 0 MB. There is a newer export path that is measured at 4.4 times faster than the previous exporter. It is not on by default yet, so you have to ask for it:

<VideoEditor
  licenseKey={key}
  export={{ experimental: true }}
/>

The same setting through mount:

mount(host, { licenseKey: key, export: { experimental: true } });

It is called experimental because it is newer and has had less time in front of real files, not because it produces a different result. 4K export works today.

Video editing needs two headers

This one costs people an afternoon if they meet it by surprise, so it is worth setting up before you write any code. The video editor decodes and encodes video using several threads at once, and those threads share one block of memory. Browsers only allow that sharing on a page that has been put in its own isolated process, away from any other site. You ask for that isolation by sending two extra lines with the page — two HTTP response headers:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Without them the video editor will load and then fail when it tries to export, usually with a browser error mentioning SharedArrayBuffer. The image editor does not need them. The second header has a consequence that catches people out. require-corp means the browser will refuse to load anything from another site onto that page unless that other site explicitly allows it. So images, fonts and scripts you pull from a content delivery network will start failing on that page. Either serve them from your own domain, or make sure they send Cross-Origin-Resource-Policy: cross-origin back.

Next.js
Vite
Nginx

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        // Only the route that holds the video editor, so the rest
        // of the site keeps loading third-party assets normally.
        source: '/editor/:path*',
        headers: [
          { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
          { key: 'Cross-Origin-Embedder-Policy', value: 'require-corp' },
        ],
      },
    ];
  },
};

// vite.config.js
export default {
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
};

This covers the development server only. Your production host has to send the same two headers.

location /editor/ {
  add_header Cross-Origin-Opener-Policy   same-origin   always;
  add_header Cross-Origin-Embedder-Policy require-corp  always;
}

To check whether it worked, open the page and run this in the browser console:

console.log(window.crossOriginIsolated); // must print true

If it prints false, one of the two headers is missing or is being overwritten further along — a proxy or a content delivery network in front of your server is the usual culprit.

Using your own AI models

Any AI feature in the editor can go to your own endpoint instead of ours. You give it a list of providers and the address of your own proxy, and inference requests go from the reader’s browser to your endpoint. In that arrangement the media never reaches layermetry at all.

<ImageEditor
  licenseKey={key}
  aiProviders={['openai', 'anthropic']}
  aiProxyUrl="https://your-app.example.com/api/ai"
/>

Anything that speaks the OpenAI request format works, including models you run yourself on your own hardware. The providers wired up today are OpenAI, Anthropic and Fal. If you leave both settings out, the editor uses layermetry-provided models.

Install for agents

The same SDK, set up so a coding agent can drive it: verbs, previewing a plan before it runs, and a record of what ran.

API reference

Every prop and every method on both editors.

Get Started

React.js Integration

Next.js Integration

Troubleshooting

What you are installing

What it needs to run

React 18 and React 19 both work

Put an editor on the page

The licence key

Exporting is faster if you ask for it

Video editing needs two headers

Using your own AI models

Next

Install for agents

API reference

​What you are installing

​What it needs to run

​React 18 and React 19 both work

​Put an editor on the page

​The licence key

​Exporting is faster if you ask for it

​Video editing needs two headers

​Using your own AI models

​Next

Install for agents

API reference

What you are installing

What it needs to run

React 18 and React 19 both work

Put an editor on the page

The licence key

Exporting is faster if you ask for it

Video editing needs two headers

Using your own AI models

Next