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

``bash


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

`typescript
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});
`

$3

`typescript
// 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:

`bash


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
`

$3

`bash
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:

$3

`typescript
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();
`

$3

`typescript
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
});
`

$3

`typescript
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
});
`

$3

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

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

$3

`typescript
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:

`bash
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