Video as Markdown: Why Your Video Pipeline Should Be Diffable

For decades, video editing has been a "black box" for software engineers. If you wanted to change a single lower-third or swap a background color in a professional motion graphics project, you had to open a proprietary GUI, navigate a complex timeline, and export a binary project file that Git couldn't possibly understand.

This workflow is the antithesis of modern DevOps. In a world where we treat infrastructure as code and documentation as markdown, it’s time we started treating video as data.

The Problem with Binary Timelines

Traditional video project files (like those from After Effects or Premiere) are opaque. When you check them into a repository, your version control system sees a blob of bytes. You can't see what changed between v1 and v2. You can't run a git diff to see why the render failed. You can't have two developers work on the same scene without a high risk of merge conflicts that are impossible to resolve.

This lack of transparency makes programmatic video automation—generating thousands of personalized videos for a SaaS dashboard or an ad campaign—fragile and expensive.

Enter VideoJSON: The Markdown of Motion

VideoFlow solves this by introducing a portable, schema-validated intermediate format: VideoJSON.

Think of VideoJSON as the "Markdown of video." Just as Markdown allows you to write plain text that renders into beautiful HTML, VideoFlow's @videoflow/core allows you to write a fluent TypeScript builder that compiles into a portable JSON document. This document contains every layer, every keyframe, every GLSL effect, and every transition in a human-readable format.

Here is what a simple scene looks like in the builder API:

import VideoFlow from '@videoflow/core';

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

const title = $.addText({
  text: 'Video as Code',
  fontSize: 8,
  color: '#FF5A1F',
  position: [0.5, 0.4],
});

title.fadeIn('600ms');
$.wait('3s');
title.fadeOut('400ms');

const json = await $.compile();

When you call $.compile(), you get a JSON object. If you change the color from #FF5A1F to #FFFFFF, your Git diff will show exactly that one-line change. Your video pipeline is now as predictable and reviewable as your frontend code.

Why a Diffable Pipeline Wins

Treating video as a diffable pipeline unlocks three massive advantages for engineering teams:

1. Code Reviews for Content: Designers and developers can collaborate in the same repo. A senior engineer can review a PR and see exactly how a transition was timed or how a GLSL effect was configured without ever leaving GitHub.
2. Automated Testing: You can write unit tests for your videos. Does the title layer always exist? Is the brand color correct? You can assert against the VideoJSON before you ever spend a single cent on rendering.
3. LLM-Friendly Authoring: Language models are excellent at emitting structured JSON. Because VideoFlow uses a portable JSON schema, it is trivial to build an LLM-powered video generation pipeline where an agent composes the timeline and your server renders the result.

How VideoFlow Handles the Render

Once you have your "Video Markdown" (the VideoJSON), VideoFlow provides three official, Apache-2.0 licensed renderers to turn that data into pixels:

• @videoflow/renderer-browser: Exports high-quality MP4s directly in the user's browser using WebCodecs. Perfect for client-side tools where you want to avoid server costs.
• @videoflow/renderer-server: A Node.js renderer that uses headless Chromium. It’s built for scale and doesn't require FFmpeg to be installed by default.
• @videoflow/renderer-dom: Provides a frame-accurate, 60fps live preview. This is what powers our Playground.

Because all three renderers consume the same JSON, you can build your video in the browser, preview it instantly, and then send the exact same data to a server for batch processing. No translation layers, no "it works on my machine" bugs.

Start Building Your Video Pipeline

Video shouldn't be a black box. It should be a first-class citizen of your codebase. By moving away from binary project files and embracing a diffable, JSON-based architecture, you can build video automation that scales with your product.

Ready to see your code in motion? Head over to the VideoFlow Documentation to get started, or experiment with the API directly in our interactive Playground. If you're building a custom editor for your users, check out the React Video Editor for a drop-in multi-track timeline component.

Join the community and contribute to the future of programmatic video on GitHub.