npm package: @hyperplex/hyperflix
Description: A library and CLI for generating and stitching together AI videos
Author: Hyperplex Research Centre
Latest version: 0.6.0

<p align="center">
  <img src="public/hyperflix.png" alt="HyperFlix" width="250"/>
</p>

<h1 align="center">HyperFlix</h1>
<p align="center">Generate and stitch together AI videos with ease</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@hyperplex/hyperflix">
    <img src="https://img.shields.io/npm/v/@hyperplex/hyperflix.svg" alt="NPM Version" />
  </a>
  <a href="https://github.com/hyper-plex/hyperflix/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License" />
  </a>
</p>

## 📋 Overview

HyperFlix is a powerful library and CLI for generating and stitching together AI videos using [LumaAI](https://lumalabs.ai/). 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}`);
```

### Generate from multiple images

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

### Create Options

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

### Vercel Blob Storage (Default)

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

### S3-Compatible Storage

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

### Cloudflare R2 Storage

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

### Mock Storage (For Testing)

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

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

### Using the Factory Function

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