@deepreels/remotion-preview

A comprehensive React SDK for previewing and converting Creatomate JSON templates with Remotion. This package provides a complete video preview system with bidirectional conversion, professional animations, and TypeScript support.

Features

• 🎬 Real-time Video Preview - Full Remotion Player integration with controls
• 🔄 Bidirectional Conversion - Convert Creatomate JSON ↔ Overlays with 95%+ accuracy
• 🎨 20+ Animations - 13 basic + 7 advanced animations with cubic-bezier easing
• 📝 Typography System - Gradients, shadows, strokes, and responsive text sizing
• 🎭 Professional Masking - Shape-based masking with blend modes
• ⚡ TypeScript First - Complete type definitions and IntelliSense support
• 🎯 Next.js Ready - Optimized for modern React applications

Installation

npm install @deepreels/remotion-preview

Peer Dependencies

npm install react react-dom @remotion/bundler @remotion/player @remotion/cli @remotion/animation-utils remotion

Quick Start

React Component

import React from 'react';
import { RemotionPreview } from '@deepreels/remotion-preview';
import type { CreatomateTemplate } from '@deepreels/remotion-preview';

const template: CreatomateTemplate = {
  width: 720,
  height: 1280,
  duration: 5,
  frame_rate: 25,
  elements: [
    {
      id: 'text-1',
      type: 'text',
      text: 'Hello World!',
      time: 0,
      track: 1,
      duration: 5,
      font_family: 'Inter',
      font_size: '48px',
      fill_color: '#ffffff',
      x: '50%',
      y: '50%',
    }
  ]
};

export default function MyComponent() {
  return (
    <RemotionPreview
      template={template}
      width={360}
      height={640}
      controls={true}
      autoPlay={false}
      loop={true}
      onReady={(player) => console.log('Player ready:', player)}
    />
  );
}

React Hooks

import { useCreateCreatomateConverter } from '@deepreels/remotion-preview';

function MyComponent() {
  const converter = useCreateCreatomateConverter();

  const handleConvert = async () => {
    // Convert Creatomate template to overlays
    const result = converter.convertTemplate(template);
    console.log('Converted overlays:', result.overlays);

    // Convert overlays back to Creatomate JSON
    const reverse = converter.convertToTemplate(result.overlays);
    console.log('Reverse converted:', reverse.template);
  };

  return <button onClick={handleConvert}>Convert Template</button>;
}

Standalone Usage

import { createCreatomateConverter, validateCreatomateTemplate } from '@deepreels/remotion-preview';

// Validate template structure
const isValid = validateCreatomateTemplate(template);

// Create converter instance
const converter = createCreatomateConverter();

// Convert template
const result = converter.convertTemplate(template, {
  fps: 25,
  preserveAnimations: true,
});

// Convert back to Creatomate JSON
const reversed = converter.convertToTemplate(result.overlays);

API Reference

Components

RemotionPreview

Main React component for video preview.

interface RemotionPreviewProps {
  template: CreatomateTemplate;
  width?: number;          // Default: 720
  height?: number;         // Default: 1280
  fps?: number;           // Default: 25
  autoPlay?: boolean;     // Default: false
  controls?: boolean;     // Default: true
  loop?: boolean;         // Default: false
  className?: string;
  style?: React.CSSProperties;
  onReady?: (player: any) => void;
  onTimeUpdate?: (time: number) => void;
  onDurationChange?: (duration: number) => void;
}

Hooks

useCreateCreatomateConverter()

Returns a complete converter instance with bidirectional conversion.

const converter = useCreateCreatomateConverter();
// Methods: convertTemplate, convertToTemplate, validateTemplate

useCreatomateConverter()

Returns a forward converter only (Creatomate → Overlays).

useReverseConverter()

Returns a reverse converter only (Overlays → Creatomate).

Factory Functions

createCreatomateConverter()

Creates a complete converter instance for non-React usage.

validateCreatomateTemplate(template)

Validates Creatomate template structure.

previewTemplateConversion(template)

Get conversion preview without actually converting.

Core Classes

CreatomateConverter

Main converter class for Creatomate → Overlays conversion.

const converter = new CreatomateConverter();
const result = converter.convertTemplate(template, options);

OverlayToCreatomateConverter

Reverse converter class for Overlays → Creatomate conversion.

const reverseConverter = new OverlayToCreatomateConverter();
const result = reverseConverter.convertOverlaysToTemplate(overlays, options);

RoundTripTester

Test conversion accuracy and data preservation.

const tester = new RoundTripTester();
const testResult = await tester.testRoundTrip(template);
console.log('Accuracy:', testResult.accuracy); // 0.0 - 1.0

Animation System

Basic Animations (13 types)

• fade - Simple opacity transition
• slideRight, slideUp - Directional slide movements
• scale - Scale transformations from center
• bounce - Elastic bounce entrance
• flipX - 3D flip around X-axis
• zoomBlur - Zoom with blur effect
• snapRotate - Quick rotate with snap
• glitch - Digital glitch effect
• swipeReveal - Content reveal with swipe
• floatIn - Smooth floating entrance
• wipe - Directional wipe reveal
• pan - Ken Burns camera effect

Advanced Animations (7 types)

• slide - Directional movement with custom distance and easing
• wipe - ClipPath-based directional reveals
• pan - Camera-like movement with scale (Ken Burns effect)
• text-slide - Text-optimized slide with subtle movement
• scale - Size transformation with precise control
• text-appear - Character-by-character text reveal
• fade - Advanced opacity transition with cubic-bezier easing

Easing Functions

Professional easing with Newton-Raphson cubic-bezier implementation:

import { getEasingFunction, EASING_PRESETS } from '@deepreels/remotion-preview';

// Get easing function
const easing = getEasingFunction('cubic-bezier', [0.25, 0.1, 0.25, 1.0]);

// Use presets
const preset = EASING_PRESETS.easeOutBack;

Supported Elements

Text Elements

• Typography controls (font family, size, weight, style)
• Gradient fills (linear, radial, conic)
• Text shadows and stroke effects
• Background colors with border radius
• Text alignment and transforms

Video Elements

• Volume control and playback speed
• Start time positioning
• Chroma key properties (green screen)
• Filter effects and blend modes

Image Elements

• Object fit modes (cover, contain, fill)
• Filter chains (brightness, contrast, saturation, etc.)
• Rotation and scaling transformations
• Border effects and shadows

Shape Elements

• SVG path data support
• Gradient fills (linear, radial, conic)
• Stroke properties (width, color, dash patterns)
• Shadow effects and color overlays

Audio Elements

• Volume conversion and fade properties
• Loop configuration
• Start/end time control

Caption Elements

• Word-level timing precision
• Style inheritance from text elements
• Transcript source integration

TypeScript Support

The package includes complete TypeScript definitions:

import type {
  CreatomateTemplate,
  CreatomateElementUnion,
  ConversionResult,
  RemotionPreviewProps,
  AdvancedAnimation,
  EasingType,
} from '@deepreels/remotion-preview';

Examples

See the /examples directory for complete Next.js integration examples.

Contributing

We welcome contributions! Please see our contributing guidelines for details.

License

MIT License - see LICENSE file for details.

Support

For support and questions:

• GitHub Issues: Report bugs and feature requests
• Documentation: Full API documentation
• Community: Join our Discord