# Hypervideo

> Generate and play transparent videos, everywhere.

## What is Stacked Alpha Video?

Most platforms lack native transparent video support. Safari/iOS don't support WebM with alpha, ProRes is too large for web, and HEVC with alpha only works on Apple devices and can only be encoded on macOS hardware — not on cloud servers.

Stacked alpha encodes color and transparency in a single H.264 video: top half = RGB color, bottom half = grayscale alpha mask. A GPU shader (WebGL or Metal) composites both halves in real-time for transparent playback.

Because it's standard H.264, it works on every platform. Hypervideo provides open-source player SDKs for React, Expo, and Swift that handle the compositing.

Hypervideo also supports other transparent formats: WebP (smallest files, all browsers), APNG (works in <img> tags on iOS), WebM (Chrome/Firefox, fast processing), and MOV/ProRes (professional editing).

## API

Base URL: https://api.hypervideo.dev
Authentication: Bearer token (Authorization: Bearer hc_...)

### POST /api/v1/video/remove-background
Remove background from video (sync). Returns base64 output.
- file: Video file (multipart) OR url: Video URL
- format: webm | webp | apng | stacked-alpha | mov
- formats: JSON array for multiple outputs (default: ["webm", "stacked-alpha"])
- tolerance: 0-100 (default 30)
- fps: 1-60 (default 24)
- quality: 0-100 for webp/apng (default 60)
- chromaKey: {"r":0,"g":255,"b":0} for manual color

### POST /api/v1/jobs/video/remove-background
Async version. Returns 202 with { jobId, status: "queued" }.

### GET /api/v1/jobs/{jobId}
Poll job status. Statuses: queued → submitted → processing → completed | failed.
Result includes signed download URLs for outputs.

### POST /api/v1/image/remove-background
Remove background from image. Returns PNG with transparency.

### POST /api/v1/image/detect-background-color
Returns dominant edge color as { r, g, b, hex }.

## Output Formats

| Format | Method | Size | Browser Support | Use Case |
|--------|--------|------|-----------------|----------|
| webp | AI | Small (~1.5MB/6s) | All browsers | Smallest files |
| apng | AI | Medium (~3-5MB/6s) | All (iOS 8+) | iOS Safari, <img> tag |
| stacked-alpha | AI | Medium (~5-10MB/6s) | All via WebGL | Cross-platform with player SDK |
| webm | Chromakey | Small (~1.5MB/6s) | Chrome, Firefox, Edge | Fast processing |
| mov | Chromakey | Large (~60MB/6s) | Safari, editors | Professional editing |

## SDK

```
npm install @hypervideo-dev/sdk
```

```typescript
import { Hypervideo } from '@hypervideo-dev/sdk';
const client = new Hypervideo({ apiKey: 'hc_...' });

// Sync
const result = await client.video.removeBackground({ file, format: 'webp' });

// Async
const { jobId } = await client.jobs.submit({ file, formats: ['webm', 'stacked-alpha'] });
const job = await client.jobs.poll(jobId, { onProgress: (j) => console.log(j.progress) });
```

## CLI

```
npm install -g @hypervideo-dev/cli
hypervideo login
hypervideo video remove-bg input.mp4 -f webp -o output.webp
```

## Players

### React/Next.js
```
npm install @hypervideo-dev/react
```
```tsx
import { StackedAlphaVideo } from '@hypervideo-dev/react';
<StackedAlphaVideo src="/video-stacked.mp4" width={384} height={384} autoPlay loop muted />
```

### Expo/React Native (iOS)
```
npm install @hypervideo-dev/expo
```
Requires development build (not Expo Go). iOS only.

### Swift
Add via Xcode SPM: https://github.com/hypersocialinc/hypervideo.git

## Smart Processing

- WebP/APNG → Always AI (BiRefNet frame-by-frame, ~60s for 6s video)
- Stacked-Alpha → Always AI (FAL Bria single-call, ~15s for 6s video)
- WebM/MOV → Always Chromakey (FFmpeg, ~10s for 6s video)
- Manual chromaKey parameter forces chromakey for WebM/MOV but doesn't override AI formats

## API Authentication

All endpoints require Bearer token authentication: `Authorization: Bearer hc_xxx`

Get an API key:
1. Sign in at https://hypervideo.dev/playground
2. Click user menu → "API Keys"
3. Or use the CLI: `hypervideo login`

## Hypervideo Skill (for AI assistants)

```
npx skills add hypervideo
```

Provides auto-context for transparent video, stacked alpha, and background removal workflows. Includes /setup, /add-player, and /remove-bg commands.

## Creator

Built by Hypersocial (https://hypersocial.com).

## Pages

- https://hypervideo.dev — Landing page and product overview
- https://hypervideo.dev/playground — Interactive playground for testing background removal
- https://hypervideo.dev/docs — Documentation overview
- https://hypervideo.dev/docs/api — API reference with all endpoints
- https://hypervideo.dev/docs/formats — Output format comparison and recommendations
- https://hypervideo.dev/docs/players — Cross-platform player setup (React, Expo, Swift)
- https://hypervideo.dev/docs/sdk — TypeScript SDK guide
- https://hypervideo.dev/docs/cli — CLI tool usage
- https://hypervideo.dev/docs/async-jobs — Async job queue documentation
- https://hypervideo.dev/docs/plugin — Claude Code plugin/skill for AI assistants

## Links

- Playground: https://hypervideo.dev/playground
- API Docs: https://hypervideo.dev/docs
- OpenAPI Spec: https://api.hypervideo.dev/docs.json
- GitHub: https://github.com/hypersocialinc/hypervideo
- npm SDK: https://www.npmjs.com/package/@hypervideo-dev/sdk
- npm CLI: https://www.npmjs.com/package/@hypervideo-dev/cli
- npm React: https://www.npmjs.com/package/@hypervideo-dev/react
- npm Expo: https://www.npmjs.com/package/@hypervideo-dev/expo