Developer docs

Embed vdoflow tools in your own site

Use iframe embeds for tutorials, support content, landing pages, or product docs, then control the tool through a small postMessage API.

The embed keeps a tiny vdoflow shell, built-in library access, local processing, and export flow inside the iframe. For broad iframe compatibility, embed routes run the single-thread FFmpeg runtime, so heavy jobs may be slower than the main site.

Preview and copy an embed

Choose a vdoflow tool, set any supported URL parameters, and copy the exact iframe snippet for that configuration.

Select a tool

Supported URL parameters

Start time (seconds)End time (seconds)

Embed URL: /embed/trim-video

Source page: /trim-video

Embed Trim Video

Copy the exact iframe snippet for the tool and parameter combination you selected, including the tiny shell and library access.

<iframe
  title="vdoflow embedded video tool"
  src="https://vdoflow.com/embed/trim-video"
  width="100%"
  height="760"
  style="border:0;"
  loading="lazy"
  allow="clipboard-write"
></iframe>

Preview embed

Supported tools and parameters

Embeds are supported only for the core vdoflow tools. URL parameters map directly to existing tool presets, and embed routes always use the single-thread FFmpeg runtime for compatibility.

Core tools only

Trim, crop, resize, rotate, remove audio, convert, and extract frame are the supported embed targets.

Preset query parameters

Only parameters already recognized by the tool are included in the generator, so the embed URL stays valid.

Tiny built-in shell

Each embed includes compact vdoflow branding plus direct library access without loading a file automatically.

Embed compatibility note: the main vdoflow site can use the multithreaded FFmpeg core, but `/embed/*` routes intentionally load the single-thread core so third-party iframes do not depend on cross-origin isolation.

Messaging contract

All messages use the same envelope: `{ source, version, type, toolId, requestId, payload }`.

Commands sent to the iframe

`vdoflow:connect` initializes the parent-child session.
`vdoflow:load-files` injects one or more `File` objects.
`vdoflow:clear-files` resets the loaded source set.
`vdoflow:start-export` triggers the current export flow.
`vdoflow:get-state` returns the current editor state snapshot.

Events sent back to the host

`vdoflow:ready` confirms the embed is live.
`vdoflow:file-loaded` confirms files were accepted.
`vdoflow:export-started` fires when processing begins.
`vdoflow:export-failed` reports validation or runtime failures.
`vdoflow:export-complete` returns output metadata and blob-backed files.

Implementation examples

Use these snippets as the baseline integration.

Connect to the embed

iframe.contentWindow.postMessage({
  source: "vdoflow-embed",
  version: 1,
  type: "vdoflow:connect",
  toolId: "trim",
  requestId: "connect-1",
  payload: {}
}, "*");

Load local files from the host page

iframe.contentWindow.postMessage({
  source: "vdoflow-embed",
  version: 1,
  type: "vdoflow:load-files",
  toolId: "trim",
  requestId: "load-1",
  payload: {
    files: [file],
    mode: "replace"
  }
}, "*");

Listen for lifecycle and result events

window.addEventListener("message", (event) => {
  if (event.data?.source !== "vdoflow-embed") return;

  switch (event.data.type) {
    case "vdoflow:ready":
    case "vdoflow:file-loaded":
    case "vdoflow:export-started":
    case "vdoflow:export-failed":
    case "vdoflow:export-complete":
      console.log(event.data);
      break;
  }
});