One JSON, Three Aspect Ratios: Building Resolution-Agnostic Video Pipelines

Building a video pipeline that works across TikTok (9:16), Instagram (1:1), and YouTube (16:9) usually means managing three different sets of layout logic. If you've ever tried to automate this with traditional tools, you've likely wrestled with hardcoded pixel values, fragile coordinate systems, and font sizes that look great in 1080p but disappear in 4K.

In the world of programmatic video, treating a canvas like a fixed-pixel grid is a legacy constraint. To build truly scalable automation, your video definitions should be resolution-agnostic.

At VideoFlow, we solved this by moving away from absolute units. By using normalized coordinates and width-relative sizing, the same VideoJSON document can render a vertical short and a cinematic trailer with zero logic changes.

The Problem with Absolute Pixels

Traditional video editing software—and many programmatic libraries—anchor everything to a fixed pixel grid. If you place a title at x: 960, y: 540 for a 1920x1080 project, it's centered. But if you switch that project to 1080x1920 (vertical), that same title is now off-canvas.

Scaling is even harder. A 48px font looks massive on a 720p screen but tiny on a 4K display. To fix this, developers often write complex "scaler" functions that multiply every coordinate and size by a ratio. This is brittle, hard to debug, and makes your JSON impossible to read.

Mental Model: The Normalized Canvas

VideoFlow uses a normalized coordinate system for positioning. Instead of pixels, every position is a value between 0.0 and 1.0 relative to the canvas dimensions. This ensures that your elements stay in the same relative place regardless of the final resolution.

• [0.5, 0.5] is always the center.
• [0.0, 0.0] is always the top-left.
• [1.0, 1.0] is always the bottom-right.

When you define a layer's position as [0.5, 0.2], it stays at the horizontal center and 20% from the top, regardless of whether the video is 500px or 5000px wide. This is a fundamental concept in our core concepts guide.

Sizing with em Units

For sizing text and shapes, we borrowed a concept from CSS: the em unit. In VideoFlow, 1em is defined as 1% of the project width.

This is the secret sauce for resolution-agnostic design. If you set a fontSize to 5, it will always occupy 5% of the video's width. Whether you render at 720p or 4K, the visual hierarchy remains identical. This also applies to shape widths, heights, and even effect parameters like blur radii.

Code Example: A Responsive Title Card

Here is how you build a title card that looks perfect on any screen size using the @videoflow/core builder API:

import VideoFlow from '@videoflow/core';

// This same logic works for { width: 1080, height: 1920 } too!
const $ = new VideoFlow({ width: 1920, height: 1080, fps: 30 });

// Positioned at 50% width, 40% height
const title = $.addText({
  text: 'RESPONSIVE VIDEO',
  fontSize: 8,           // 8% of project width
  color: '#FF5A1F',
  position: [0.5, 0.4],
  fontWeight: 800,
});

// A background shape that scales with the text
const bar = $.addShape(
  {
    width: 40, height: 1, // 40% width, 1% width tall
    fill: '#FF5A1F',
    position: [0.5, 0.5],
  },
  { shapeType: 'rectangle' }
);

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

How VideoFlow Handles Rendering

Because the layout logic is baked into the VideoJSON schema as relative values, our three official renderers can handle the heavy lifting.

1. Live Preview: The @videoflow/renderer-dom renders your video to a 60fps preview in your browser. You can resize the preview container, and the video scales instantly.
2. Browser Export: The @videoflow/renderer-browser uses WebCodecs to export an MP4 directly in the user's tab.
3. Server Automation: The @videoflow/renderer-server runs in Node.js to handle batch jobs.

This architecture is what enables the VideoFlow Playground to feel so fast. When you change the project resolution in the sidebar, the renderer doesn't have to re-calculate your layout—it just re-interprets the same relative values against a new pixel grid.

Beyond Layout: The Three-Renderer Rule

This resolution-agnostic approach is a core part of what we call the Three-Renderer Rule. By decoupling the description of the video (JSON) from the execution of the render (the pixel grid), you gain massive flexibility. You can preview a low-res version on a mobile dashboard, then trigger a 4K high-bitrate render on a server using the exact same source of truth.

If you're currently building video automation by concatenating FFmpeg strings or managing multiple React component trees for different aspect ratios, it's time to treat your video like data. This is a topic we explored deeply in our guide on The Three-Renderer Rule: Preview, Export, and Automate with VideoFlow.

Conclusion

Resolution-agnostic video pipelines are not just about convenience; they are about future-proofing your content engine. Whether you are building a SaaS recap feature or an automated social media factory, adopting normalized coordinates and relative sizing will save you hundreds of hours of manual layout adjustment.

Ready to try it out? Head over to the GitHub repo to grab the core package, or jump straight into the documentation to start building your first responsive video.