Video Node

Video nodes are static media nodes for uploaded files and video outputs that already exist on the canvas. They keep the playable source, sync-backed media reference, file metadata, and video-specific playback state with the node so downstream steps can reuse the same asset.

What it stores

• The local preview fields, including src and blobKey, while the browser can still display the staged upload.
• The durable R2-backed mediaRef after media sync finishes.
• File metadata such as fileName, mimeType, duration, naturalWidth, naturalHeight, and aspectRatio.
• Optional presentation metadata for poster-first editorial video surfaces.

Add or replace a video

1. 1

   Choose the Video node

   Add a Video node from the canvas toolbar, or drag compatible video files into the canvas. Drag-and-drop creates Video nodes with the standard video node dimensions before metadata is loaded.

2. 2

   Drop or select a file

   The file picker is limited to supported video MIME types. The same validator also rejects empty, unsupported, or oversized files when the file is dropped or pasted into the canvas.

3. 3

   Let metadata load

   Builder Studio stages a local preview first, then reads video metadata from the active source. The loaded duration, natural dimensions, and aspect ratio are written back to the node.

4. 4

   Use the synced asset

   After media sync completes, the node prefers the R2 display URL. Downstream nodes receive the same video through the video-out port.

Supported files

Playback controls

A loaded Video node renders an inline video element with metadata preloading and custom controls. The controls appear while the node is selected, while the progress scrubber is active, or while a seek is syncing.

• Play and pause use node-safe event handling so clicking controls does not drag or pan the canvas.
• The progress control is a keyboard-accessible slider labeled Video progress.
• The time display uses tenths for clips under 10 seconds and standard time formatting for longer clips.
• Mute and volume controls share the global video volume state, so a volume change applies consistently across Video nodes.
• If the media element fails to load, the node shows Retry. Editable sessions also show Replace video.

Metadata and sizing

Loaded metadata is only accepted from the active playback source. That protects the node from stale browser events when a local preview is replaced by a synced URL or another file.

• The node updates aspectRatio when the loaded video ratio differs by more than 0.001.
• The node stores naturalWidth and naturalHeight from videoWidth and videoHeight.
• Local uploads auto-fit the node to the natural video dimensions when the aspect ratio changes. Synced remote media references do not resize an existing node from a later metadata event.
• The node updates duration when the loaded duration is finite, positive, and meaningfully different from the stored value.

1{2  "type": "video",3  "data": {4    "mediaRef": "r2://media/workspace/demo-video",5    "mimeType": "video/mp4",6    "fileName": "demo-video.mp4",7    "duration": 12.4,8    "naturalWidth": 1920,9    "naturalHeight": 1080,10    "aspectRatio": 1.777777777811  }12}

Sync and retry behavior

Before a source is available, pending media renders the shared media loading state. During sync, the node frame can show the current media state, a sync message, and a retry action when the upload pipeline can be retried.

• The display source prefers the R2 display URL, then the stored media URL, then the local preview source.
• Replacing a video clears the previous media fields before writing the next local preview and metadata.
• The playback source key includes the local blob key, remote URL, fallback source, and media creation timestamp so load events can be matched to the current source.

Agent and API notes

Agents should treat Video nodes as media references, not generation requests. The passthrough executor emits the stored video URL on video-out with the stored MIME type when available. Keep mediaRef, src, and video metadata together when replacing the underlying asset so downstream reference-to-video workflows receive the expected media.