Video as JSON: Building Diffable, Version-Controlled Video Assets

For decades, video has been a "black box" in the developer's toolkit. Whether it's a multi-gigabyte .mp4 sitting in an S3 bucket or a complex After Effects project file, video assets are notoriously difficult to track, diff, and version-control. When a marketing lead asks to change a hex code in a lower-third, you aren't just changing a line of code; you're re-rendering, re-uploading, and losing all visibility into what actually changed in the source.

At VideoFlow, we believe video should be treated like any other piece of modern software infrastructure. That means moving away from binary blobs and toward Video as JSON—a portable, human-readable, and highly diffable format that brings video production into the Git era.

Why Your Video Pipeline Needs a Schema

Traditional video pipelines rely on "baked" assets. If you need 1,000 personalized videos for an onboarding flow, you're either running a massive FFmpeg cluster or paying for a proprietary SaaS API. In both cases, the source of truth is often a fragile string of shell commands or a template locked in a vendor's database.

By representing video as a structured JSON document, you gain three immediate advantages:

1. Git-Friendly Versioning: You can see exactly which property changed in a pull request. Did the fontSize change from 6 to 7? Was a new gaussianBlur effect added to the background? Your Git history becomes your production log.
2. Platform Independence: The same JSON that powers a live preview in your React app can be sent to a Node.js worker for high-volume rendering.
3. LLM Compatibility: Large Language Models are excellent at emitting structured data. Giving an AI agent the ability to produce VideoJSON is far more reliable than asking it to generate binary files or complex shell scripts.

The Anatomy of a VideoJSON Document

In VideoFlow, you don't write JSON by hand. You use our fluent builder API to compose scenes. This API acts as a compiler, turning high-level commands like $.addText and .fadeIn() into a strict VideoJSON schema.

import VideoFlow from '@videoflow/core';

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

// Add a background image with a subtle blur effect
const bg = $.addImage(
  { fit: 'cover', opacity: 0.8 },
  { source: 'https://assets.videoflow.dev/office-bg.jpg' }
);

bg.animate(
  { filterBlur: 0 },
  { filterBlur: 5 },
  { duration: '4s', wait: false }
);

// Add a title with a built-in transition
$.addText(
  { text: 'Video as Code', fontSize: 8, color: '#FF5A1F' },
  { transitionIn: { transition: 'blurResolve', duration: '800ms' } }
);

$.wait('3s');

// Compile to portable JSON
const videoData = await $.compile();
console.log(JSON.stringify(videoData, null, 2));

This videoData object is now your source of truth. It contains every layer, keyframe, and effect parameter required to reproduce the video byte-for-byte on any machine.

The Three-Renderer Rule

One of the most powerful aspects of the VideoFlow architecture is that the JSON is renderer-agnostic. We provide three official renderers that consume the exact same schema:

• @videoflow/renderer-dom: For frame-accurate, 60fps live previews in the browser. Perfect for building internal tools or interactive editors.
• @videoflow/renderer-browser: For client-side MP4 export using WebCodecs. This allows your users to render videos in their own browser tab with zero server costs.
• @videoflow/renderer-server: For headless video rendering in Node.js. This is the workhorse for automated content factories and bulk personalization.

Building a Diffable Pipeline

When your videos are JSON, your CI/CD pipeline can treat them like code. You can run automated tests to ensure that a change in a shared branding configuration doesn't break the layout of your automated product updates. You can even use JSON-patching to create thousands of variants of a master video without ever touching the original source code.

This shift from "video as a file" to "video as data" is what enables true scale. Whether you're building a YouTube Shorts factory or a personalized SaaS recap system, the foundation is a portable, versioned schema.

Ready to see what your videos look like as code? Head over to the VideoFlow Playground to start building, or check out the source on GitHub to see how we're building the future of programmatic video.