One JSON, Three Renderers: Mastering the VideoFlow Lifecycle

In the world of programmatic video, the biggest bottleneck isn't usually the rendering speed—it's the architecture. Most "video-as-code" tools force a hard choice: do you want a React-based preview, or a server-side FFmpeg pipeline? Once you commit to one, moving to the other often requires a total rewrite of your scene logic.

VideoFlow was built to break this cycle. By decoupling the composition (how the video is defined) from the rendering (how the pixels are drawn), VideoFlow introduces a truly portable lifecycle. You write your logic once in TypeScript, compile it to a standard VideoJSON document, and then pipe that same JSON into any of our three official renderers.

Whether you are building a SaaS dashboard with personalized video or a headless video rendering API, understanding this "One JSON, Three Renderers" rule is the key to mastering the toolkit.

The Source of Truth: VideoJSON

At the heart of every VideoFlow project is @videoflow/core. This package provides the fluent builder API you use to add layers, timing, and cinematic effects. But here is the critical part: the builder doesn't actually render anything. Its only job is to produce a VideoJSON document.

import VideoFlow from '@videoflow/core';

const $ = new VideoFlow({ width: 1920, height: 1080, fps: 30 });

// Add a background and a title
const bg = $.addImage({ fit: 'cover' }, { source: 'https://assets.flow.dev/bg.jpg' });
const title = $.addText({ text: 'Hello World', fontSize: 8, color: '#FF5A1F' });

title.fadeIn('500ms');
$.wait('3s');

// The output is a portable JSON object
const videoJson = await $.compile();

Because this JSON is resolution-agnostic (using em units where 1em = 1% of project width), it is perfectly portable. As we discussed in our guide on The Git-Flow for Video, this JSON can be stored in a database, version-controlled in Git, and sent across the wire to different rendering environments.

1. The Browser Renderer: Zero-Server Export

The first stop in the lifecycle is often the user's browser. @videoflow/renderer-browser is designed for high-performance MP4 export directly in the client tab.

By leveraging the WebCodecs API, this renderer bypasses the need for a heavy server-side GPU or expensive cloud rendering instances. When a user hits "Export" in your app, the browser renderer consumes the VideoJSON and produces an MP4 file locally. This is the ultimate way to scale video generation without scaling your infrastructure costs.

2. The Server Renderer: Headless Automation

When you need to generate videos in the background—think automated social media posts or weekly email recaps—you move the lifecycle to the server.

@videoflow/renderer-server runs in a Node.js environment and uses headless Chromium (via Playwright) to execute the render. Unlike traditional FFmpeg-based tools, it doesn't require FFmpeg to be installed on the host system by default. It uses a high-efficiency pipeline to capture frames and encode them into an MP4.

The beauty of the VideoFlow architecture is that the code you wrote for the browser export is exactly the same code that runs on your server. You simply swap the renderer package:

import '@videoflow/renderer-server'; // Registers the server renderer

// ... same builder logic as above ...

await $.renderVideo({
  outputType: 'file',
  output: './automated-output.mp4'
});

3. The DOM Renderer: Frame-Accurate Live Preview

The final piece of the puzzle is the developer and user experience. You can't build a great video product if you have to wait for an MP4 export every time you change a hex code.

@videoflow/renderer-dom provides a frame-accurate, 60fps live preview of your VideoJSON. It renders directly to a DOM target, allowing for instant scrubbing and playback. This is the engine that powers the VideoFlow Playground and the React Video Editor.

By integrating the DOM renderer into your React or Vue application, you give your users a "What You See Is What You Get" experience. When they are happy with the preview, you send that same VideoJSON to the browser or server renderer to finalize the MP4.

Why the Three-Renderer Rule Wins

This architecture solves the three biggest problems in video automation:

1. Consistency: Because all three renderers use the same underlying logic, the preview in your browser will look byte-for-byte identical to the MP4 generated on your server.
2. Flexibility: You can start with a simple client-side tool and later add a server-side batching pipeline without changing a single line of your composition code.
3. Speed: The DOM renderer allows for rapid iteration, while WebCodecs in the browser and server renderers ensure that the final export is as fast as the hardware allows.

Get Started with the Lifecycle

Ready to see the renderers in action? The best way to start is by exploring the official documentation or jumping straight into the Playground to see how code turns into a live, scrubbable preview.

If you're building a commercial video product, you can also check out the React Video Editor—a drop-in component that brings the entire VideoFlow lifecycle into your UI with a multi-track timeline and inspector.

For the full source code and to join our community, head over to the VideoFlow GitHub repository. We can't wait to see what you build.