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.
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.
| Message | Direction | Meaning |
|---|---|---|
{ type: 'viewer', on: true } | to the player | Start watching as a viewer, from the start. |
{ type: 'viewer', on: false } | to the player | Stop, and go back to an ordinary preview. |
{ type: 'viewer', on, error? } | from the player | Whether viewer mode is on now. error says why it could not start (for example, nothing interactive in the document). |
{ type: 'interactive', event } | from the player | What 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.
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.
| Query | Meaning |
|---|---|
format | json (default): metadata, lint and suggestedPreviewTimes, and a frame as a data URI when at is set. image: the JPEG bytes. html: the composition below. |
at | Timeline time in seconds. Defaults to 0 for image. |
resolution | full 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.
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.
Drive it from the parent frame. Both handles are on the composition's own window:
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.

at=0.8 Title only. Check it clears the top safe area.
at=2 Title and subtitle together: the overlap moment.
at=4.3 Captions running, titles gone.
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:
Up to three timestamps. The standalone preview_frame tool takes projectId and time, for looking without editing.
Which one to use#
| You are | Use |
|---|---|
| A server-side pipeline checking its own output | GET /v1/projects/{id}/preview |
| Building a signed-in web UI on top of Vidmoat | The app player at /embed/player |
| An agent making edits and needing to see them | MCP previewAt on the edit call |
| Shipping a finished video to a user | A real render. Previews are not deliverables. |