Skip to content

Video preview

Play the app compositor while editing, and inspect exact frames before exporting. None of it uses your export allowance.

Embed the app player#

The /embed/player page mounts the same preview canvas as the web editor and the phone app. It plays video, audio, titles, effects and keyframes without exporting. The editor starter includes a working React integration.

Fetch the document with GET /v1/projects/{id}?view=document on your server, keep the key there, and send only the document to the player, with absolute, browser-accessible media URLs.

player.js
const origin = 'https://www.vidmoat.com';
iframe.src = origin + '/embed/player?parentOrigin=' +
  encodeURIComponent(location.origin);
iframe.allow = 'autoplay; fullscreen';
const channel = 'vidmoat.player.v1';
const send = data => iframe.contentWindow.postMessage({ channel, ...data }, origin);
window.addEventListener('message', event => {
  if (event.source !== iframe.contentWindow || event.origin !== origin ||
      event.data?.channel !== channel) return;
  if (event.data.type === 'ready') {
    send({ type: 'document', document: project.document, revision: 1, time: 0 });
  }
  // 'loaded' acknowledges the document revision.
  // 'state' reports time, playing and audioTime; 'error' includes a message.
  // 'audio' reports sound: state is 'suspended' or 'running'.
});
// After 'loaded', from your playback controls:
send({ type: 'play' });
send({ type: 'pause' });
send({ type: 'seek', time: 2.5 }); // keeps playing or paused as it was
// After an edit, send 'document' again with a new revision.
// An interactive project, played as a viewer will see it:
send({ type: 'viewer', on: true }); // 'viewer' { on } answers; 'interactive' { event } reports what they do

Play an interactive project as a viewer#

When the document carries interactive parts (see Interactive video), send { type: 'viewer', on: true } after loaded. The player then runs the document the way a viewer of the published video will see it: it starts at the first scene, draws the choices over the picture, holds or plays on as each choice says, and jumps on a pick. It is the same runtime and overlay as the Vidmoat watch page.

MessageDirectionMeaning
{ type: 'viewer', on: true }to the playerStart watching as a viewer, from the start.
{ type: 'viewer', on: false }to the playerStop, and go back to an ordinary preview.
{ type: 'viewer', on, error? }from the playerWhether viewer mode is on now. error says why it could not start (for example, nothing interactive in the document).
{ type: 'interactive', event }from the playerWhat the viewer did: event.kind is start, scene, choice, answer, vote, hotspot, chapter, angle or complete, with scene, t (seconds into the video) and, where they apply, itemId, optionId, correct and ending.

Sending document again with a change ends the session and the player says { type: 'viewer', on: false }: what was being watched is no longer the video. state keeps reporting the same clock throughout, so a pick shows up as a jump in time. Nothing is published or saved from the player, and talking to a character is only on the watch page.

Sound on iPhone#

The player posts { channel: 'vidmoat.player.v1', type: 'audio', state }, where state is 'suspended' or 'running'. After play, 'suspended' means the picture is playing and sound has not been allowed to start yet. 'running' follows as soon as it starts. Every other message is unchanged, and a host that ignores audio keeps working.

Keeping sound and picture together#

The narration is the player's clock: when an audio clip is under the playhead, the picture follows it, so sound never waits for video. Small drift is corrected by running a video slightly faster or slower; only a gap of more than 0.4 seconds is corrected with a jump.

Each state message carries audioTime: where the narration actually is, in timeline seconds, or null when no audio clip is under the playhead. Compare it with time to see drift. A seek keeps the player playing or paused as it was; send pause first if you want it to stop.

A document shorter than 60 seconds is loaded whole before loaded arrives, so later clips do not stall the picture when the playhead reaches them.

When 'loaded' arrives#

The player posts loaded once the media at the current time can be drawn. On a desktop browser that means every visible video has a decoded frame, and it posts error if that takes more than 15 seconds. On a touch device (phones and tablets) it waits up to 30 seconds, and after 8 seconds it posts loaded as soon as every visible video has its metadata, so the first frame can appear a moment later. A file that fails to load posts error straight away on every device. The player stays paused until you send play.

Fetch a single frame#

The preview endpoint draws one timeline timestamp through the same pipeline that renders the export: clips, keyframes, effects, captions, colour grade. What you see is what the file will contain at that moment.

Shell
curl "https://api.vidmoat.com/v1/projects/$ID/preview?format=image&at=2.5" \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -o frame.jpg

It needs render.read, not render.write: a preview uses no export allowance, so a read-only key can check a composition it is not allowed to render. Frames are limited to 10 a minute per key.

QueryMeaning
formatjson (default): metadata, lint and suggestedPreviewTimes, and a frame as a data URI when at is set. image: the JPEG bytes. html: the composition below.
atTimeline time in seconds. Defaults to 0 for image.
resolutionfull or half, for html only. Frames are captured at half the project resolution, which is enough to check layout.

Lightweight HTML composition (approximate)#

format=html returns an approximate HTML version of the timeline: clips, text, captions, effects and keyframes, driven by a single GSAP timeline. No file is produced. Serve it in an iframe and you have a scrubbable preview.

It arrives paused at 0. Clip visibility is driven by the timeline, so until you tell the document what time it is, nothing is on screen. That is what makes deterministic seeking possible, but an un-driven composition looks like a black rectangle.

Live: this is format=html, not a video. Built from the commands below and served with no key; open the raw document to read exactly what you get back.

The commands that produced it. Note where fontSize and y live: passing them at the top level is ignored, and every element lands centred on top of everything else.

JSON
{
  "commands": [
    {
      "op": "addClip",
      "type": "video",
      "src": "/fixtures/v1/video.mp4",
      "start": 0,
      "duration": 6,
      "trackIndex": 0
    },
    {
      "op": "addTextClip",
      "text": "Shipped from the API",
      "start": 0.4,
      "duration": 3,
      "trackIndex": 1,
      "style": {
        "fontSize": 72
      },
      "patch": {
        "y": -220
      }
    },
    {
      "op": "addTextClip",
      "text": "No editor. No timeline. One POST.",
      "start": 1.2,
      "duration": 4.2,
      "trackIndex": 1,
      "style": {
        "fontSize": 34
      },
      "patch": {
        "y": -110
      }
    },
    {
      "op": "addCaptions",
      "words": [
        {
          "text": "Every",
          "start": 3.4,
          "end": 3.7
        },
        {
          "text": "frame",
          "start": 3.7,
          "end": 4
        },
        {
          "text": "you",
          "start": 4,
          "end": 4.2
        },
        {
          "text": "see",
          "start": 4.2,
          "end": 4.45
        },
        {
          "text": "here",
          "start": 4.45,
          "end": 4.75
        },
        {
          "text": "is",
          "start": 4.75,
          "end": 4.9
        },
        {
          "text": "real",
          "start": 4.9,
          "end": 5.4
        }
      ],
      "trackIndex": 2
    }
  ]
}

Drive it from the parent frame. Both handles are on the composition's own window:

JavaScript
const win = document.querySelector('iframe').contentWindow;

win.setCompositionTime(2.5);  // seek, and pin every video to its own in-clip time
win.playComposition();        // or let it run
win.pauseComposition();       // pause picture and sound together

Use setCompositionTime rather than seeking the GSAP timeline directly. tl.seek() suppresses events by default, so the callback that decides which clips are on screen never fires, and GSAP does not know a <video> has a playhead of its own.

What the frames look like#

The same composition at four timestamps. They are the frames worth sampling in any project: where something appears, where two elements share the screen, where one track hands over to another, and the last frame before a clip ends.

The demo composition at 0.8 seconds
at=0.8 Title only. Check it clears the top safe area.
The demo composition at 2 seconds
at=2 Title and subtitle together: the overlap moment.
The demo composition at 4.3 seconds
at=4.3 Captions running, titles gone.
The demo composition at 5.8 seconds
at=5.8 Last frame before the clip ends.

Preview inline with the edit (MCP)#

If an agent drives Vidmoat over MCP, do not preview as a separate step. Pass previewAt on the edit itself and the frames come back as images in the same response:

JSON
{
  "name": "edit_project",
  "arguments": {
    "projectId": "…",
    "commands": [{ "op": "addTextClip", "text": "Hello", "start": 0, "duration": 3 }],
    "previewAt": [0.5, 1.5, 2.5]
  }
}

Up to three timestamps. The standalone preview_frame tool takes projectId and time, for looking without editing.

Which one to use#

You areUse
A server-side pipeline checking its own outputGET /v1/projects/{id}/preview
Building a signed-in web UI on top of VidmoatThe app player at /embed/player
An agent making edits and needing to see themMCP previewAt on the edit call
Shipping a finished video to a userA real render. Previews are not deliverables.