Beyond Frame Math: Mastering Timing and Flow with VideoFlow’s Primitives

Managing timestamps manually is the "off-by-one" error of the video world. If you've ever tried to chain FFmpeg commands or manually calculate startTime and duration for twenty different layers, you know the pain: one small change at the start of the timeline ripples through every subsequent layer, forcing a complete recalculation of the entire sequence.

In VideoFlow, we’ve replaced manual frame math with a set of video timing primitives that treat your timeline like a logical flow of events rather than a static array of timestamps. By using $.wait, $.parallel, and $.group, you can build complex, cinematic sequences that are resilient to change and easy to reason about.

The Sequential Default: Thinking in "Next"

Most programmatic video tools require you to specify an absolute startTime for every layer. In VideoFlow, the builder maintains an internal "playhead." When you add a layer or call an animation method, it defaults to starting wherever the previous action finished.

import VideoFlow from '@videoflow/core';

const $ = new VideoFlow();

// This text starts at 0s
const title = $.addText({ text: 'The Future of Video', fontSize: 6 });
title.fadeIn('500ms');

// The flow pointer is now at 500ms. 
// We wait for 2 seconds before the next action.
$.wait('2s');

// This starts at 2.5s automatically
title.fadeOut('500ms');

This "fluent" approach means you can insert a new scene at the beginning of your script without touching a single line of code in the middle. The system handles the ripple effect for you.

Parallel Execution: Breaking the Linear Chain

Sometimes you don't want the playhead to move. If you want to trigger a background music track or a screen-overlay effect that runs while your main content continues to evolve, you use the $.parallel primitive.

The $.parallel method accepts a function. Everything inside that function runs starting from the current flow position, but when the function returns, the outer flow pointer remains exactly where it was before the call.

// Start background music without advancing the main timeline
$.parallel(() => {
  $.addAudio({ volume: 0.4 }, { source: '/music/ambient.mp3' });
});

// This text still starts at the current "main" playhead
$.addText({ text: 'Main Content' }).fadeIn();

This is essential for building automated video pipelines where different tracks (audio, overlays, captions) need to be managed independently of the primary visual sequence.

Composable Scenes with Nested Groups

The most powerful primitive in the toolkit is $.group. A group allows you to bundle multiple layers into a single container. Crucially, the timing inside a group is relative to the group's own start time.

Groups let you build "components" for your video. You can define a complex lower-third animation or a credit roll once, and then place it anywhere on your timeline as a single unit.

$.group({ opacity: 0.8 }, {}, ($g) => {
  $g.addShape({ shapeType: 'rectangle', fill: '#FF5A1F', width: 40, height: 10 });
  $g.addText({ text: 'Breaking News', fontSize: 3, position: [0.5, 0.5] });
});

Because groups are layers themselves, you can apply transitions and effects to the entire group at once. Want to blur an entire scene? Just add the gaussianBlur effect to the group properties.

How VideoFlow Handles the Math

Under the hood, the @videoflow/core builder compiles these high-level instructions into a portable VideoJSON document. This document contains the resolved absolute timestamps that renderers need, but you never have to see or edit them.

This abstraction is what makes VideoFlow so powerful for developers. Whether you are rendering an MP4 on the server using @videoflow/renderer-server or providing a live, frame-accurate preview in a React app with @videoflow/renderer-dom, the timing logic remains identical.

Build Your First Flow

Stop wrestling with frame counters and start thinking in flows. The ability to treat video like a composable, logical program opens up entirely new possibilities for personalized content and AI-driven automation.

• Explore the VideoFlow Playground to see these primitives in action.
• Read the Parallel and Wait Guide for a deep dive into timing logic.
• Star the project on GitHub and join the community of developers building the future of programmatic video.