<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/iuploop/uploop-vided/main/docs/uploop-vided-dark.svg">
    <img alt="Uploop Vided" src="https://raw.githubusercontent.com/iuploop/uploop-vided/main/docs/uploop-vided-light.svg" width="480">
  </picture>
</p>

<p align="center">
  <strong>Generative AI-driven composition &amp; VFX engine — the AI is the director.</strong>
</p>

<p align="center">
  <a href="https://github.com/iuploop/uploop-vided/actions/workflows/ci.yml"><img src="https://github.com/iuploop/uploop-vided/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="#"><img src="https://img.shields.io/badge/tests-152%20passed-brightgreen" alt="Tests"></a>
  <a href="#"><img src="https://img.shields.io/badge/examples-63%20interactive-blue" alt="Examples"></a>
  <a href="#"><img src="https://img.shields.io/badge/packages-12%20total-orange" alt="Packages"></a>
  <a href="#"><img src="https://img.shields.io/badge/version-v0.3.0-blueviolet" alt="Version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-purple" alt="License"></a>
</p>

<p align="center">
  <a href="https://github.com/iuploop/uploopjs"><img src="https://img.shields.io/badge/powered_by-uploopjs-818cf8" alt="Powered by uploopjs"></a>
  <a href="https://github.com/iuploop/uploop-ge"><img src="https://img.shields.io/badge/GPU-uploop--ge-4ade80" alt="GPU: uploop-ge"></a>
</p>

---

**Uploop Vided** is an AI-native video composition and VFX engine. Built on
[`uploop-ge`](https://github.com/iuploop/uploop-ge) for GPU rendering and
[`uploopjs`](https://github.com/iuploop/uploopjs) for HyperGraph
orchestration. Exposes its engine as AI-callable tools (MCP) — the AI acts as
the director, uploop-vided is the VFX engine.

## Quick Start

```bash
git clone https://github.com/iuploop/uploop-vided.git
cd uploop-vided
pnpm install
pnpm dev
```

Open `http://localhost:3002` — you'll see the examples gallery.

🌐 **Live demo:** [iuploop.github.io/uploop-vided](https://iuploop.github.io/uploop-vided/)

## Vided DSL — Component Tag Syntax

Uploop Vided uses an **HTML-like tag syntax** for video composition. Compose
timelines, tracks, clips, 3D scenes, and effects using familiar declarative
tags — no imperative API required.

### Video Composition

```js
import { vided } from '@uploop/vided'

const { timeline, composition } = vided`
  <Timeline name="My Video" width=${1920} height=${1080} fps=${30}>
    <Track type="video">
      <Clip source="intro.mp4" inPoint=${0} outPoint=${5} />
      <Clip source="content.mp4" inPoint=${5} outPoint=${12} opacity=${1} />
    </Track>
    <Track type="audio" muted=${false}>
      <Clip source="music.mp3" inPoint=${0} outPoint=${12} volume=${0.8} />
    </Track>
    <Track type="text">
      <Clip source="My Title" inPoint=${0} outPoint=${12} y=${80} opacity=${1} />
    </Track>
  </Timeline>
`

// Render with html-video:
import { renderVideo } from '@uploop/html-video'
await renderVideo({ composition, output: 'output.mp4' })
```

### 3D Scene Composition (uploop-ge)

```js
import { vided } from '@uploop/vided'

const { scene, renderer } = vided`
  <Scene width=${1920} height=${1080} background="gradient">
    <Camera type="orbit" distance=${5} angle=${-0.4} pitch=${0.35} />
    <AmbientLight color="#334" intensity=${0.5} />
    <DirectionalLight direction=${[0.5, 0.4, 0.7]} color="#fff" intensity=${1.2} />
    <Model src="brain.glb" position=${[0, 0, 0]} scale=${1} />
    <Shape type="sphere" radius=${1} position=${[0, 1, 0]} color="#f44" />
    <Skybox top="#4a8fcf" mid="#c8dcf0" bottom="#1a3050" />
    <PostFX bloom=${true} tonemap=${true} />
  </Scene>
`
```

### Hybrid: Video + 3D

```js
import { vided } from '@uploop/vided'

const { timeline, composition } = vided`
  <Timeline name="3D Product Ad" width=${1920} height=${1080} fps=${30}>
    <Track type="video">
      <Clip source="background.mp4" inPoint=${0} outPoint=${30} />
    </Track>
    <Track type="3d">
      <Scene>
        <Camera type="orbit" distance=${4} angle=${-0.4} />
        <Model src="product.glb" />
        <DirectionalLight direction=${[0.5, 0.6, 0.4]} intensity=${1.5} />
      </Scene>
    </Track>
    <Track type="text">
      <Clip source="New Arrival" inPoint=${5} outPoint=${15} y=${80} />
    </Track>
    <Track type="audio">
      <Clip source="soundtrack.mp3" inPoint=${0} outPoint=${30} />
    </Track>
  </Timeline>
`
```

### Tag Reference

| Tag | Description | Key Props |
|-----|-------------|-----------|
| `<Timeline>` | Multi-track timeline container | `name`, `width`, `height`, `fps` |
| `<Track>` | Single track (video/audio/text/3d) | `type`, `muted`, `volume` |
| `<Clip>` | Media clip with time range | `source`, `inPoint`, `outPoint`, `opacity`, `scale`, `x`, `y`, `rotation` |
| `<Sequence>` | Sequential timeline player | `timelines`, `json` |
| `<Scene>` | 3D scene (uploop-ge) | `width`, `height`, `background` |
| `<Camera>` | Viewpoint camera | `type` (`orbit`/`perspective`), `distance`, `angle`, `pitch`, `fov` |
| `<Model>` | glTF 3D model | `src`, `position`, `rotation`, `scale` |
| `<Shape>` | Primitive geometry | `type` (`sphere`/`cube`/`plane`), `radius`/`size`, `color` |
| `<DirectionalLight>` | Parallel light source | `direction`, `color`, `intensity` |
| `<AmbientLight>` | Uniform fill light | `color`, `intensity` |
| `<PointLight>` | Omni-directional light | `position`, `color`, `intensity`, `range` |
| `<Skybox>` | Background environment | `top`, `mid`, `bottom` colors or 6-face cube URLs |
| `<PostFX>` | Post-processing pipeline | `bloom`, `tonemap`, `vignette`, `ssao` |
| `<Particles>` | Particle system | `count`, `size`, `color`, `lifetime` |

### Imperative API (no tags)

```js
import { Timeline, Track, Clip } from '@uploop/timeline'
import { Compositor, Layer, createTransition } from '@uploop/compositor'
import { renderVideo } from '@uploop/html-video'

const timeline = new Timeline({ fps: 30, width: 1920, height: 1080 })
timeline.addTrack(new Track({ id: 'main', type: 'video', clips: [
  new Clip({ id: 'intro', source: 'intro.mp4', inPoint: 0, outPoint: 5 }),
  new Clip({ id: 'body',  source: 'body.mp4',  inPoint: 3, outPoint: 10 }),
]}))

const fade = createTransition('fade', { duration: 1 })
await renderVideo({ composition: createTimelineComposition({ timeline }), output: 'output.mp4' })
```

> 📖 Full DSL reference: [`docs/VIDED-DSL.md`](docs/VIDED-DSL.md)

## Why Uploop Vided?

| | Remotion | Motion Canvas | Uploop Vided |
|---|---|---|---|
| **Framework** | React | Generator functions | **Component Tags** (HTML-like) |
| **License** | Source-available, paid ≥5 devs | MIT | **MIT — always free** |
| **GPU** | Via Three.js (external) | Canvas2D only | **Native WebGL2 + WebGPU** (uploop-ge) |
| **AI-native** | Manual API calls | ❌ | **MCP server + tool registry + advisor** |
| **3D Scenes** | External React-Three-Fiber | ❌ | **Built-in `<Scene>`, `<Model>`, `<Skybox>`** |
| **Timeline** | `<Sequence>` | `Thread.main()` | **Multi-track `<Timeline>` + `<Track>` + `<Clip>`** |
| **Transitions** | CSS/JS | Tween functions | **36 GPU-ready transition types** |
| **Compositor** | React component stacking | Layout nodes | **Layers with blend modes, masks, effects** |
| **Output** | ffmpeg (Chromium) | ffmpeg (Chromium) | **WebCodecs + ffmpeg + streaming (WebRTC/RTMP)** |
| **Editor UI** | Remotion Studio (React) | Editor (Electron) | **5 Custom Elements (player, timeline, inspector, etc.)** |
| **CLI** | `npx remotion` | `npm start` | **`uploop-video init/dev/render/serve`** |
| **HyperGraph** | ❌ | ❌ | **Typed graph of nodes — inspectable by AI** |

## Packages

| Package | Description | Status |
|---------|-------------|--------|
| `@uploop/media` | Image/video/audio decode, frame extraction, codec registry | ✅ |
| `@uploop/timeline` | Multi-track timeline, clips, keyframes, easing, sequence | ✅ |
| `@uploop/compositor` | GPU-accelerated layer compositing, 36 transitions, 8 blend modes | ✅ |
| `@uploop/vided` | **Component tag DSL** — HTML-like composition for video + 3D | ✅ |
| `@uploop/common-elements` | 72 reusable UI components, hooks, and graphics primitives | ✅ |
| `@uploop/toolset` | AI-callable tool registry + OpenAI-compatible advisor + MCP server | 🟡 |
| `@uploop/output` | WebCodecs encoder, stream output, export presets | 🟡 |
| `@uploop/vided-ui` | 5 Web Components: player, timeline editor, preview, inspector, library | ✅ |
| `@uploop/html-video` | Remotion-style HTML → MP4 via Puppeteer + ffmpeg | ✅ |
| `@uploop/cli` | CLI: `uploop-video init/dev/render/serve/info/list` | ✅ |
| `@uploop/project` | Project management: folders, config, assets, renders | ✅ |
| `@uploop/editor` | Standalone editor workspace (launch via CLI) | ✅ |

**12 packages** — all MIT licensed, pure ESM.

## AI-Native: The AI is the Director

```bash
pnpm uploop-video serve --port 3004
```

```json
// POST /mcp → { "method": "tools/list" }
[
  { "name": "timeline.addTrack", "parameters": { "type": { "enum": ["video","audio","image","text","3d"] } } },
  { "name": "timeline.addClip",  "parameters": { /* inPoint, outPoint, source, props */ } },
  { "name": "scene.create",      "parameters": { /* width, height, background */ } },
  { "name": "scene.addModel",    "parameters": { /* src, position, rotation, scale */ } },
  { "name": "compositor.renderFrame", "parameters": { /* time, width, height */ } },
  { "name": "output.encode",     "parameters": { /* format, codec, bitrate */ } },
]
```

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    uploopjs (UI Layer)                    │
│  @uploop/html — declarative component model             │
├─────────────────────────────────────────────────────────┤
│                  uploop-vided (VFX Layer)                 │
│  vided DSL → timeline → compositor → output → html-video │
│  common-elements → scene → camera → model → postfx       │
│  project → cli → editor → toolset → vided-ui             │
├─────────────────────────────────────────────────────────┤
│                   uploop-ge (GPU Layer)                   │
│  math → geometry → shader → renderer → scene → physics   │
│  WebGL 2.0 + WebGPU engine from scratch                  │
└─────────────────────────────────────────────────────────┘
```

## Docs

| Document | Description |
|---|---|
| [VIDED-DSL.md](./docs/VIDED-DSL.md) | **Full component tag reference** — all tags, props, patterns |
| [PLANNING.md](./docs/PLANNING.md) | Package map, dependency graph, AI toolset design |
| [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Composition pipeline, protocols |
| [TODO.md](./docs/TODO.md) | Living task list — phases, status |

## Examples

**63 interactive examples** organized by category:

| Category | Count | Description |
|----------|-------|-------------|
| `examples/basic/` | 20 | Core timeline, compositor, transitions, effects |
| `examples/advanced/` | 10 | Calculus, geometry, physics, chemistry |
| `examples/multimedia/` | 20 | Music, video effects, glitch, text animation |
| `render-examples/` | 11 | Render-ready compositions with common-elements (WebGL 3D) |
| `examples/editor/` | 1 | Full editor workspace |
| `examples/render-demo/` | 1 | Solar system educational video |

## License

MIT