Cinematic 3D Video with TypeScript: A Guide to Perspective and Rotation

Flat, 2D motion graphics often lack the "punch" required for high-end product demos or cinematic intros. While many programmatic video tools restrict you to the X and Y axes, adding a third dimension transforms a simple layout into a dynamic, immersive scene.

Building 3D video with code usually involves complex WebGL boilerplate or heavy math libraries. In this guide, we'll explore how to use the VideoFlow core API to create cinematic 3D effects using familiar TypeScript patterns.

The Three-Dimensional Coordinate System

In VideoFlow, every layer exists in a 3D-aware coordinate system. While we author most positions in normalized 0..1 units for the X and Y axes, we can also manipulate the Z-axis to create depth.

To enable 3D depth, we use the perspective property. This property defines how "far" the viewer is from the Z=0 plane. A smaller perspective value creates a more dramatic, wide-angle distortion, while a larger value feels flatter and more telephoto. The default is 100em (where 1em is 1% of the project width).

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

const card = $.addShape(
  {
    width: 40, height: 25,
    fill: '#FF5A1F',
    perspective: 80, // Enable 3D depth
    rotation: [0, 45, 0], // Rotate 45 degrees on the Y axis
  },
  { shapeType: 'rectangle' }
);

Rotating on Three Axes

Unlike traditional CSS where you might chain rotateX and rotateY, VideoFlow uses a single rotation property that accepts an array: [rx, ry, rz]. This makes it trivial to animate complex, multi-axis tumbles with a single animation call.

When you rotate a layer, it pivots around its anchor. By default, the anchor is [0.5, 0.5], the center of the layer. If you want a door-swing effect, you can move the anchor to the edge: anchor: [0, 0.5].

Creating a 3D Flip Card

const card = $.addShape(
  {
    width: 30, height: 40,
    fill: '#1c2233',
    cornerRadius: 2,
    rotation: [0, 0, 0],
  },
  { shapeType: 'rectangle' }
);

// Animate a cinematic tumble over 2 seconds
card.animate(
  { rotation: [0, 0, 0], scale: 1 },
  { rotation: [10, 180, -5], scale: 1.2 },
  { duration: '2s', easing: 'easeInOut' }
);

The "Virtual Camera" with Layer Groups

One of the most powerful patterns in VideoFlow is using $.group() as a virtual camera. Because a group composites its children onto a private surface, you can apply 3D transforms to the group itself to move the entire scene as one.

This is perfect for creating "floating UI" shots or parallax backgrounds where multiple elements need to maintain their relative positions while the "camera" pans around them. Combined with VideoFlow's easing functions, you can achieve incredibly smooth, professional motion.

$.group(
  { perspective: 120, rotation: [15, -10, 0] },
  { transitionIn: { transition: 'tilt3d', duration: '1s' } },
  () => {
    // All layers added here will inherit the group's 3D tilt
    $.addImage({ fit: 'cover', opacity: 0.8 }, { source: '/bg.jpg' });
    $.addText({ text: '3D SCENE', fontSize: 8, color: '#fff' });
    $.wait('3s');
  }
);

How VideoFlow Handles 3D

VideoFlow's 3D engine is designed for portability. When you build a scene using @videoflow/core, your 3D transforms are compiled into a portable VideoJSON document. This document renders identically across all three official renderers:

1. Browser Renderer: Uses CSS 3D transforms for hardware-accelerated export in the tab.
2. Server Renderer: Uses headless Chromium to render the same GPU-accelerated frames in Node.js.
3. DOM Renderer: Provides a frame-accurate, 60fps live preview in the Playground or your own React app.

This means you can design a complex 3D animation once and deploy it anywhere—from a real-time preview in an editor to a high-concurrency server-side render pipeline.

Get Started with 3D Video

Ready to add depth to your video pipelines? You can start experimenting with 3D properties right now in the VideoFlow Playground. For a full list of animatable properties and 3D transition presets like rotate3dY and tilt3d, check out the official documentation.

VideoFlow is open-source (Apache-2.0). You can find the source code, report issues, or contribute to the core engine on GitHub.