@hyperplex/hyperflix

HyperFlix

Generate and stitch together AI videos with ease

📋 Overview

HyperFlix is a powerful library and CLI for generating and stitching together AI videos using LumaAI. It provides:

• Chainable API for elegant workflows
• CLI commands for project management
• Type-safe with TypeScript
• Flexible storage with support for Vercel Blob, AWS S3, and Cloudflare R2

🚀 Installation

# Install as a package
npm install @hyperplex/hyperflix

# Install globally for CLI use
npm install -g @hyperplex/hyperflix

# Using yarn
yarn add @hyperplex/hyperflix

🧩 Library Usage

import { VideoStitcher } from '@hyperplex/hyperflix';

// Create a video stitcher
const stitcher = new VideoStitcher({
  title: 'my-awesome-video',
  model: 'luma:ray-2',     // LumaAI model
  aspectRatio: '16:9',     // Aspect ratio
  videoLength: '5s',       // Video duration
  defaultPrompt: 'Beautiful landscape'  // Default prompt
});

// Initialize with first image (Buffer or URL)
await stitcher.initialize(imageUrlOrBuffer);

// Add keyframes with camera motions (chainable API)
const result = await stitcher.addKeyframe(
  secondImageUrlOrBuffer, 
  'mountain vista',  // Prompt
  'zoom-in'          // Camera motion
);

// Continue adding keyframes
const finalResult = await result.stitcher.addKeyframe(
  thirdImageUrlOrBuffer, 
  'flowing river', 
  'pan-right'
);

console.log(`Video metadata: ${finalResult.videoUrl}`);

Generate from multiple images

// Batch generate a video from multiple images
const images = [image1, image2, image3];
const prompts = ['forest', 'mountain', 'river'];
const cameras = ['tilt-up', 'pan-right', 'zoom-out'];

const result = await stitcher.generateFrom(images, prompts, cameras);
console.log(`Video URL: ${result.videoUrl}`);

💻 CLI Usage

HyperFlix includes a robust command-line interface:

# List all projects
hyperflix list

# Create a new project interactively
hyperflix create my-video-project

# View project details
hyperflix project details my-video-project

# Resume editing a project
hyperflix project resume my-video-project

Create Options

hyperflix create my-video-project \
  --prompt "A beautiful landscape" \
  --model luma:ray-2 \
  --aspect 16:9 \
  --duration 5s

🔧 Configuration

Create a .env file in your project directory:

# Required for API access
LUMAAI_API_KEY=your_lumaai_api_key_here

# Storage options (choose one based on your CDN)
VERCEL_BLOB_READ_WRITE_TOKEN=your_vercel_blob_token_here

# For S3 storage:
# S3_ACCESS_KEY=your_s3_access_key
# S3_SECRET_KEY=your_s3_secret_key
# S3_BUCKET=your_s3_bucket
# S3_REGION=us-east-1
# S3_ENDPOINT=https://s3.amazonaws.com (optional, for custom endpoints)

# For Cloudflare R2 storage:
# R2_ACCOUNT_ID=your_cloudflare_account_id
# R2_ACCESS_KEY_ID=your_r2_access_key
# R2_SECRET_ACCESS_KEY=your_r2_secret_key
# R2_BUCKET=your_r2_bucket
# R2_PUBLIC_URL=https://your-custom-domain.com (optional, for public URLs)

💾 Storage Providers

HyperFlix supports multiple storage providers for storing your project data:

Vercel Blob Storage (Default)

import { VercelBlobCDN } from '@hyperplex/hyperflix';

// Create storage service with Vercel Blob
const storage = new VercelBlobCDN('your_token');
// Or use environment variable: VERCEL_BLOB_READ_WRITE_TOKEN
const storage = new VercelBlobCDN();

S3-Compatible Storage

import { S3CDN } from '@hyperplex/hyperflix';

// Create storage service with S3
const storage = new S3CDN({
  accessKey: 'your_access_key',
  secretKey: 'your_secret_key',
  bucket: 'your_bucket',
  region: 'us-east-1',
  endpoint: 'https://nyc3.digitaloceanspaces.com' // Optional, for custom endpoints
});

Cloudflare R2 Storage

import { CloudflareR2CDN } from '@hyperplex/hyperflix';

// Create storage service with Cloudflare R2
const storage = new CloudflareR2CDN({
  accountId: 'your_cloudflare_account_id',
  accessKeyId: 'your_r2_access_key',
  secretAccessKey: 'your_r2_secret_key',
  bucket: 'your_r2_bucket',
  publicUrl: 'https://your-custom-domain.com' // Optional, for public URLs
});

Mock Storage (For Testing)

import { MockStorageService } from '@hyperplex/hyperflix';

// Create a mock storage service for testing
const storage = new MockStorageService();

Using the Factory Function

import { createCDNService } from '@hyperplex/hyperflix';

// Create a Vercel storage service
const vercelStorage = createCDNService('vercel', { token: 'your_token' });

// Create an S3 storage service
const s3Storage = createCDNService('s3', {
  accessKey: 'your_access_key',
  secretKey: 'your_secret_key',
  bucket: 'your_bucket'
});

// Create a Cloudflare R2 storage service
const r2Storage = createCDNService('r2', {
  accountId: 'your_cloudflare_account_id',
  accessKeyId: 'your_r2_access_key',
  secretAccessKey: 'your_r2_secret_key',
  bucket: 'your_r2_bucket'
});

🎥 Camera Motions

HyperFlix supports all LumaAI camera motions:

Motion	Description
zoom-in / zoom-out	Zoom camera in or out
pan-left / pan-right	Pan camera horizontally
tilt-up / tilt-down	Tilt camera vertically
crane-up / crane-down	Move camera up or down
rotate-left / rotate-right	Rotate camera
dolly-in / dolly-out	Move camera towards/away from subject

🌐 Demo

View the demo by running:

npm run dev
# or
yarn dev

This will start a local web server and open the demo page in your browser.

📝 License

MIT © Hyperplex Research Centre