Video as Markdown: Why your Video Pipeline should be Diffable and Version-Controlled

For decades, video editing has been a "black box" operation. Whether you're using After Effects, Premiere, or Final Cut, your project lives inside a proprietary binary file. If you want to see what changed between two versions, you can't just run a git diff. You have to open the app, scrub the timeline, and hope you spot the difference.

But in the world of modern software engineering, we treat everything as code. We have Infrastructure as Code (Terraform), Documentation as Code (Markdown), and even UI as Code (React). It's time we treated video as markdown—a portable, human-readable, and version-controlled asset.

The Problem with Binary Blobs

When your video project is a binary blob, you lose the most powerful tools in the developer's arsenal:

1. Version Control: You can't see who changed what. A "Merge Conflict" in a project file is a death sentence for the project.
2. Portability: You need a specific, heavy application to even view the project structure.
3. Automation: You can't easily search and replace a hex code across 100 videos or programmatically swap a background image without a complex SDK or manual labor.

By moving to a programmatic approach where the source of truth is code that compiles to JSON, we unlock a completely different workflow.

VideoJSON: The Portable Document Format for Motion

At the heart of VideoFlow is a simple but powerful idea: a video is just a sequence of data over time. When you use the VideoFlow Core builder API, you aren't just "editing"; you are authoring a document.

When you call $.compile(), VideoFlow produces a VideoJSON document. This is the "Markdown" of video. It’s a plain text representation of every layer, every keyframe, and every GLSL effect in your project.

import VideoFlow from '@videoflow/core';

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

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

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

// This produces the "Markdown" of your video
const videoJson = await $.compile();

Because this output is pure JSON, it is diffable. If a designer changes the fontSize from 6 to 7, your Git history will show exactly that change. No more "Final_v2_REVISED_actual_final.mp4". Just a clean commit history.

Git-Friendly Video Pipelines

Treating video as markdown allows you to integrate video production directly into your CI/CD pipelines. Imagine a world where:

• A pull request to your branding repository automatically triggers a re-render of all your social media templates to ensure the colors match.
• A change in a JSON translation file automatically updates the captions layer in your explainer videos.
• You can use standard Unix tools like grep or sed to audit your entire video library for a specific font or asset URL.

This is the power of a diffable video pipeline. It brings the rigor of software engineering to the creative process.

How VideoFlow Handles This

VideoFlow was built from the ground up to support this "Code-to-JSON-to-Video" philosophy. We follow what we call the Three-Renderer Rule.

Because the source of truth is a portable VideoJSON document, it can be rendered identically across three official environments:

1. The Browser: Using @videoflow/renderer-browser, you can export MP4s directly in the user's tab via WebCodecs.
2. The Server: Using the server-side renderer, you can run batch jobs in Node.js without needing to manage complex FFmpeg dependencies.
3. The DOM: Using @videoflow/renderer-dom, you get a 60fps frame-accurate live preview for scrubbing and debugging.

This decoupling of authoring (the builder API) from rendering (the three renderers) is what makes VideoFlow a true alternative to proprietary systems. Whether you are building automated SaaS user recap videos or a custom internal tool, the JSON remains the constant.

Why Your Pipeline Should be Diffable

The transition from binary projects to version-controlled JSON isn't just about technical elegance—it's about scalability. When your video projects are text, they become searchable, scriptable, and shareable.

If you're tired of "black box" video files and want to start treating your video assets with the same respect as your codebase, it's time to try VideoFlow.

Next Steps

• Try it out: Head over to the VideoFlow Playground to see the builder in action.
• Read the Docs: Check out our Getting Started guide to set up your first project.
• Star on GitHub: Support the project and track our progress at github.com/ybouane/VideoFlow.