VideoFlow

Programmatic video for the web. Define videos with a fluent TypeScript API, compile them to a portable JSON format, and render to MP4 — in the browser, on the server, or play them back live with full scrubbing controls.

Try it live: videoflow.dev/playground · Docs: videoflow.dev

---

Why VideoFlow?

• Code your video like a script. A flow-style API where wait, parallel, and per-layer animate advance a timeline you can read top-to-bottom.
• One JSON, three renderers. Compile once, render anywhere — server-side MP4, browser-side MP4, or live DOM playback for editors.
• Built-in transitions and shader effects. 25+ enter/exit presets (slideUp, blurResolve, glitchResolve, typewriter, numberCountUp, …) and a WebGL effect pipeline (bloom, chromaticAberration, colorCorrection, …) — animate any param.
• Resolution-independent units. Sizes default to em where 1em = 1% of the project width, so a layout written for 1920×1080 renders identically at 720p or 4K.
• Editor-ready. The same JSON model powers a drop-in React video editor — your code-built videos and your editor scenes share the same format.

---

Packages

This monorepo publishes four npm packages — install only what you need.

Package	What it does	Docs
@videoflow/core	Define and compose videos with the fluent API · compile to portable JSON	Core docs
@videoflow/renderer-dom	Live preview / scrubbable playback in the browser	Renderers docs
@videoflow/renderer-browser	Render to MP4 entirely client-side (WebCodecs + MediaBunny)	Renderers docs
@videoflow/renderer-server	Render to MP4 on Node.js via headless Chromium	Renderers docs

There's also a separate React component for building visual editors on top of this format → VideoFlow React Video Editor.

---

Installation

# Core (always required)
npm install @videoflow/core

# Pick a renderer for your environment:
npm install @videoflow/renderer-server          # Node.js → MP4
npx playwright install chromium                 #   one-time browser download

# or
npm install @videoflow/renderer-browser         # Browser → MP4
npm install @videoflow/renderer-dom             # Browser → live preview

renderVideo() auto-detects the environment and dynamically imports the matching renderer, so you usually only need to install one alongside @videoflow/core.

---

Quick Start

import VideoFlow from '@videoflow/core';

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

const title = $.addText({
  text: 'Hello, VideoFlow!',
  fontSize: 7,
  fontWeight: 800,
  color: '#ffffff',
});

title.animate(
  { opacity: 0, scale: 0.8 },
  { opacity: 1, scale: 1 },
  { duration: '0.8s' },
);
$.wait('1.5s');
title.animate(
  { opacity: 1, scale: 1 },
  { opacity: 0, scale: 1.2 },
  { duration: '0.8s' },
);

// Auto-detects environment and renders to MP4
await $.renderVideo({
  outputType: 'file',
  output: './hello.mp4',
  verbose: true,
});

Run it with:

npx tsx hello.ts

Compile once, render later

$.compile() produces a fully self-describing VideoJSON you can store, send over the wire, or hand to any VideoFlow renderer:

const json = await $.compile();
// → { width, height, fps, duration, layers, ... }

Pick a specific renderer

// Server (Node.js)
import VideoRenderer from '@videoflow/renderer-server';
await VideoRenderer.render(json, { outputType: 'file', output: './out.mp4' });

// Browser (MP4 export)
import VideoRenderer from '@videoflow/renderer-browser';
const blob = await VideoRenderer.render(json);

// Browser (live preview)
import DomRenderer from '@videoflow/renderer-dom';
const player = new DomRenderer(document.getElementById('player'));
await player.loadVideo(json);
await player.play();

---

A taste of the API

const $ = new VideoFlow({ width: 1920, height: 1080, fps: 30, backgroundColor: '#0a0d18' });

// Background image with a colour-correction sweep
$.addImage(
  {
    fit: 'cover',
    effects: [{ effect: 'colorCorrection', params: { saturation: 1.2, contrast: 1.1 } }],
  },
  { source: './hero.jpg' },
);

// Two text lines that slide in in parallel, hold, then fade out together
const heading = $.addText(
  { text: 'Built with VideoFlow', fontSize: 6, fontWeight: 800 },
  { transitionIn: { transition: 'slideUp', duration: '500ms' } },
);
const sub = $.addText(
  { text: 'Code → JSON → MP4', fontSize: 3, position: [0.5, 0.6], color: '#94a3b8' },
  { transitionIn: { transition: 'slideUp', duration: '500ms' }, startTime: '0.15s' },
);

$.wait('3s');
$.parallel([
  () => heading.fadeOut('500ms'),
  () => sub.fadeOut('500ms'),
]);

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

Group layers

Composite a sub-tree as a single unit. Transitions, animations, and effects on the group apply to the whole composite — child timings are relative to the group's start.

$.group(
  { position: [0.5, 0.5], scale: 1 },
  { transitionIn: { transition: 'zoom', duration: '600ms' } },
  () => {
    $.addShape({ width: 30, height: 18, fill: '#0e1524', cornerRadius: 2 }, { shapeType: 'rectangle' });
    $.addText({ text: 'CARD', fontSize: 4, fontWeight: 800 });
  },
);

Visual properties at a glance

All visual layers (text, image, video, captions, shape, group) share the same transform / styling vocabulary:

Property	Type	Default	Notes
position	[x, y] or [x, y, z]	[0.5, 0.5]	Normalised 0–1 of the canvas; z adds depth in em
scale	number or [x, y]	1	Uniform or per-axis multiplier
rotation	number or [x, y, z]	0	Degrees, clockwise. [x, y, z] for 3D
anchor	[x, y]	[0.5, 0.5]	Normalised pivot inside the element
opacity	0–1	1	Animatable
blendMode	CSS mix-blend-mode	'normal'	'multiply', 'screen', 'difference', …
perspective	number (em)	100	3D viewing distance
effects	EffectSpec[]	[]	WebGL pipeline; each param animatable via dot-paths

See @videoflow/core for the complete property list (filters, borders, shadows, text styling, audio …) plus the full transition + effect catalogue.

Time formats

Anywhere a duration or time appears (startTime, duration, wait, sourceDuration, …) you can pass a number (seconds) or one of:

Form	Example	Meaning
Seconds	'5s'	5 seconds
Milliseconds	'500ms'	500 ms
Minutes / hours	'2m', '1h'	2 minutes / 1 hour
Frames	'120f'	120 frames at the project's fps
Timecode	'01:30', '01:02:30', '01:02:30:15'	mm:ss / hh:mm:ss / hh:mm:ss:ff

---

Examples

The examples/ folder contains 11 runnable scripts that double as a feature tour. Each compiles a project and renders an MP4.

Example	What it shows
01-basic-text.ts	addText with a fade + scale animation
02-image-background.ts	Image background with an animated blur
03-video-with-audio.ts	Video layer + parallel music track
04-captions.ts	Time-coded addCaptions overlay
05-parallel-animations.ts	$.parallel with staggered children
06-render-frame-and-audio.ts	Render a single frame or just the audio
07-abort-controller.ts	Cancel a render mid-flight via AbortController
08-transitions.ts	Built-in transition presets showcase
09-effects.ts	WebGL effects (bloom, glitch, frosted glass)
10-groups.ts	Composing sub-trees with shared transitions
11-keyframe-animations.ts	Keyframe-driven scale / position / rotation / blur

npx tsx examples/01-basic-text.ts

---

Building from source

git clone https://github.com/ybouane/VideoFlow.git
cd VideoFlow
npm install
npm run build

Resources

• Website: videoflow.dev
• Live playground: videoflow.dev/playground
• Core library docs: videoflow.dev/core
• Renderers docs: videoflow.dev/renderers
• React Video Editor: videoflow.dev/react-video-editor

License

Apache-2.0