Video Source

Extracts frames from a video file with controls for time mapping, speed, reverse, and looping.

Category: Source Menu path: Source > VideoSource

Ports

Port	Type	Direction	Description
out	imageRgba16f	output	The decoded video frame for the current time

Parameters

Param	Type	Default	Description
path	string	""	Absolute path to the video file. Supports formats that ffmpeg can decode (MP4, MOV, ProRes, etc.).
timeMode	enum	Layer	Composition: video time follows the composition playhead. Layer: video time is relative to the layer's start on the timeline (default).
speed	scalar	1.0	Playback speed multiplier. 2.0 = double speed, 0.5 = half speed. Clamped to >= 0.
reverse	boolean	false	Play the video backwards. Applied after looping, so a looped reversed clip loops in reverse.
startOffset	scalar	0	Skip ahead into the video by this many comp-frames. Interpreted at the comp's frame rate (e.g. 90 at 30fps = skip 3 seconds), which matches how AudioSource.startOffset works — wire the same scalar into both startOffset_in ports to keep video + audio in sync.
loopMode	enum	None	None: video holds on its last frame after it ends. Loop: wraps back to the beginning when it reaches the end. PingPong: plays forward then backward, repeating.

Expose Channels

When enabled (E button on node header), adds input ports that override params via edge connections:

Port	Type	Overrides
speed_in	scalar	speed
startOffset_in	scalar	startOffset

How It Works

VideoSource uses ffmpeg (bundled with the editor) to decode video frames on demand. When the composition playhead changes, the node computes which video frame to show based on the time mode, speed, offset, loop mode, and reverse settings.

Time mapping: In Layer mode (the default), frame 0 of the video aligns with the layer's start on the timeline, so moving the layer clip slides the video in time. In Composition mode, the video always maps to the composition playhead directly, regardless of layer position.

The formula is: video_time = (comp_or_layer_time * speed) + (startOffset / source_fps). The resulting time is then mapped to a frame number, with looping and reverse applied.

Decoded frames are cached in a 512MB LRU cache shared across quality levels. The decoder runs in three modes internally (sequential, reverse-buffered, random access) to optimize for different playback patterns, but this is transparent to the user.

Usage Examples

Basic: Add video footage

1. Drag a video file from the Assets panel onto the timeline to create a new layer with VideoSource -> Transform2D -> Output already wired
2. Scrub the playhead to see different frames
3. Trim the layer clip to the desired range

Slow motion

Set speed to 0.5 for half-speed playback. Set loopMode to Loop if the slowed footage is shorter than the layer clip.

Reversed loop

Enable reverse and set loopMode to PingPong for a boomerang-style effect that plays backward then forward continuously.

Offset start point

Set startOffset to skip an intro or start from a specific moment in the source video. For example, startOffset of 90 at 30fps skips the first 3 seconds.

Tips

• VideoSource defaults to Layer time mode, so the video plays from its beginning when the layer starts, regardless of where it sits on the timeline. Switch to Composition if you need the video locked to the comp playhead.
• Use the probeVideo command (automatic when importing) to detect frame count and frame rate from the source file
• Dragging a video from the Assets panel auto-creates the layer with correct clip duration matching the video length
• Speed is clamped to zero (no negative speed). Use the reverse toggle instead of negative speed values.
• Loop and PingPong prevent the video from freezing on its last frame when the layer extends beyond the source duration

Related Nodes

• ImageSource -- loads still images (no time mapping)
• Transform2D -- positions the video frame in the composition
• Time -- outputs frame/seconds/normalized values for driving other time-based effects