OpenVideo

https://docs.openvideo.dev/
Admin
OpenVideo is a framework-agnostic video editor SDK built on WebCodecs API that enables programmatic...
Tokens:65,902
Snippets:755
Trust Score:4.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install OpenVideo Core

Source: https://docs.openvideo.dev/core/00-getting-started/quickstart

Install the required package via npm.

```bash
npm install @openvideo/core
```

--------------------------------

### Install Node.js Polyfills

Source: https://docs.openvideo.dev/core/04-advanced/headless-node

Install necessary polyfills for browser APIs required by OpenVideo Core in a Node.js environment.

```bash
npm install ws @peculiar/webcrypto
```

--------------------------------

### Undo/Redo Command Example

Source: https://docs.openvideo.dev/core/02-guides/undo-redo

Illustrates how commands generate patches and inverse patches for undo/redo operations. This is a conceptual example showing the flow.

```text
Execute: Add Clip
├─ Patches: [{ op: "add", path: "/clips", value: {...} }]
└─ Inverse: [{ op: "remove", path: "/clips/clip_123" }]

History Stack: [Add Clip]

Undo: Apply inverse patches (clip removed)
Redo: Re-apply original patches (clip restored)
```

--------------------------------

### Full AI Agent Example

Source: https://docs.openvideo.dev/core/02-guides/ai-integration

An example of a Video Editing Agent class that processes user requests using AI. It includes steps for getting context, planning, converting plans to commands, validation, user confirmation, execution, and logging.

```typescript
class VideoEditingAgent {
  private core: Core;

  constructor(core: Core) {
    this.core = core;
  }

  async processRequest(prompt: string): Promise<void> {
    // 1. Get current state context
    const context = this.getContext();

    // 2. Ask LLM for plan
    const plan = await this.llm.plan(prompt, context);

    // 3. Convert plan to commands
    const commands = this.planToCommands(plan);

    // 4. Validate
    const valid = this.validate(commands);
    if (!valid.valid) {
      throw new Error(`Invalid plan: ${valid.reason}`);
    }

    // 5. Confirm with user (optional)
    const confirmed = await this.confirm(commands);
    if (!confirmed) return;

    // 6. Execute
    this.core.batch(commands);

    // 7. Log
    this.log(commands);
  }

  private getContext() {
    const state = this.core.store.getState();
    return {
      duration: state.settings.duration,
      tracks: state.tracks.map((t) => ({
        id: t.id,
        name: t.name,
        clipCount: t.clips.length,
      })),
      selected: state.selectedIds,
    };
  }
}
```

--------------------------------

### Example Command JSON

Source: https://docs.openvideo.dev/core/02-guides/ai-integration

This is an example of a plain JSON command object representing a clip addition intent. Commands are serializable, validatable, reversible, and inspectable.

```json
{
  "id": "cmd_abc123",
  "type": "clip.add",
  "payload": {
    "trackId": "main",
    "clip": {
      "type": "Video",
      "src": "./intro.mp4",
      "timing": { "display": { "from": 0, "to": 5000000 } },
    },
  },
}
```

--------------------------------

### Command Registry Example

Source: https://docs.openvideo.dev/core/04-advanced/custom-commands

Illustrates a basic entry in the command registry, mapping a command type to a handler function that calculates state patches.

```javascript
// Registry entry
"clip.rotate": (state, command) => {
  // Calculate patches
  return [{ op: "update", path: "/clips/123/transform/angle", value: 45 }];
}
```

--------------------------------

### Initialize OpenVideo Core with Project Settings and Tracks

Source: https://docs.openvideo.dev/core/02-guides/create-project

This snippet shows the basic setup for initializing the OpenVideo Core instance. It defines essential project settings like dimensions, frame rate, and duration, and configures initial audio and video tracks.

```javascript
import { Core } from "@openvideo/core";

const core = new Core({
  settings: {
    width: 1920,
    height: 1080,
    fps: 30,
    duration: 60_000_000, // 60 seconds in microseconds
  },
  tracks: [
    { id: "video-1", name: "Video", clips: [] },
    { id: "audio-1", name: "Audio", clips: [] },
  ],
});
```

--------------------------------

### Example Command Object

Source: https://docs.openvideo.dev/core/01-concepts

Commands represent user or AI intent to modify the project state. They are deterministic, serializable, and AI-friendly.

```javascript
{
  id: "cmd_abc123",
  type: "clip.add",
  payload: { trackId: "main", clip: videoClip }
}
```

--------------------------------

### Example Patch Flow: Moving a Clip

Source: https://docs.openvideo.dev/core/04-advanced/patches

Illustrates a typical patch flow, showing the initial state, the generated patch for moving a clip, the resulting state after applying the patch, and the inverse patch for undoing the action.

```javascript
// Initial state
{ clips: { clip_123: { transform: { x: 0 } } } }

// User moves clip to x: 100
// → Generated patch:
{
  op: "update",
  path: "/clips/clip_123/transform/x",
  value: 100,
  oldValue: 0
}

// Applied to state:
{ clips: { clip_123: { transform: { x: 100 } } } }

// Undo: Apply inverse (oldValue → value)
{
  op: "update",
  path: "/clips/clip_123/transform/x",
  value: 0,  // oldValue becomes new value
  oldValue: 100
}
```

--------------------------------

### Example Patch Objects

Source: https://docs.openvideo.dev/core/01-concepts

Patches describe atomic changes to the project state, enabling undo/redo functionality and real-time synchronization.

```javascript
{ op: "add", path: "/tracks/0/clips", value: { id: "clip_1", ... } }
```

```javascript
{ op: "update", path: "/duration", value: 15000000 }
```

--------------------------------

### Update Project Settings

Source: https://docs.openvideo.dev/core/02-guides/create-project

Modify existing project settings after initialization. This example demonstrates how to update the canvas dimensions.

```javascript
core.store.getState().updateSettings({
  width: 1280,
  height: 720,
});
```

--------------------------------

### Export Project as MP4 Video

Source: https://docs.openvideo.dev/core/02-guides/create-project

Renders the current project state into a video file. This example exports the project as an MP4 using specified FPS. It requires importing the `render` function.

```javascript
import { render } from "@openvideo/core/rendering";

const blob = await render(core.store.getState().getSnapshot(), {
  format: "mp4",
  fps: 30,
});
```

--------------------------------

### Navigate to timeline boundaries

Source: https://docs.openvideo.dev/core/02-guides/timeline-editing

Move the playhead to the start of the timeline or the end of the project duration.

```javascript
// Start of timeline
core.execute({
  id: nanoid(),
  type: "playback.seek",
  payload: 0,
});

// End of project duration
const duration = core.store.getState().settings.duration;
core.execute({
  id: nanoid(),
  type: "playback.seek",
  payload: duration,
});
```

--------------------------------

### Microsecond Precision Example

Source: https://docs.openvideo.dev/core/01-concepts

OpenVideo uses microsecond precision for frame-accurate synchronization of video, audio, and animations.

```javascript
// 5 seconds = 5,000,000 microseconds
const time = 5000000;
```

--------------------------------

### Dockerfile for Headless Node.js

Source: https://docs.openvideo.dev/core/04-advanced/headless-node

This Dockerfile sets up a Node.js environment with Chrome installed for headless video processing using WebCodecs and Puppeteer.

```docker
FROM node:18-slim

# Install Chrome for headless WebCodecs
RUN apt-get update && apt-get install -y \
    chromium \
    && rm -rf /var/lib/apt/lists/*

ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

WORKDIR /app
COPY package*.json ./
RUN npm install

COPY . .
EXPOSE 3000

CMD ["node", "server.js"]
```

--------------------------------

### Execute Command in OpenVideo Core

Source: https://docs.openvideo.dev/core/00-getting-started

Use the `core.execute` method to dispatch commands for atomic state changes in the OpenVideo Core engine. This example demonstrates a programmatic seek operation.

```typescript
import { core, nanoid } from "@openvideo/core";

// Programmatic seek using the Command API
core.execute({
  id: nanoid(),
  type: "playback.seek",
  payload: { time: 5000000 },
});
```

--------------------------------

### Playback Control Methods

Source: https://docs.openvideo.dev/core/05-reference

Provides examples for controlling media playback using core.playback methods. These include playing, pausing, toggling, and seeking to a specific time.

```typescript
core.playback.play();
core.playback.pause();
core.playback.toggle();
core.playback.seek(time);
```

--------------------------------

### Store Access

Source: https://docs.openvideo.dev/core/05-reference

Provides methods to get the current state, subscribe to state changes, and listen to patches from the store.

```APIDOC
## Store Access

### `core.store.getState()`

**Description**: Get the current state of the store.

**Method**: Not applicable (SDK method)

**Parameters**: None

**Response Example**: 
```javascript
const state = core.store.getState();
// state contains the current project data and settings
```

### `core.store.subscribe(callback)`

**Description**: Subscribe to changes in the store state.

**Method**: Not applicable (SDK method)

**Parameters**: 
- **callback** (function) - Required - A function that will be called with the new state and previous state whenever the state changes.

**Response Example**: 
```javascript
const unsubscribe = core.store.subscribe((state, prevState) => {
  console.log("State changed");
});
// Call unsubscribe() to stop listening
```

### `state.onChange(callback)`

**Description**: Listen to specific patches (changes) applied to the state. This is typically called on the state object obtained from `getState()`.

**Method**: Not applicable (SDK method)

**Parameters**: 
- **callback** (function) - Required - A function that will be called with an array of patches whenever changes occur.

**Response Example**: 
```javascript
const state = core.store.getState();
const off = state.onChange((patches) => {
  console.log("Patches:", patches);
});
// Call off() to stop listening
```
```

--------------------------------

### Accessing and Subscribing to Store State

Source: https://docs.openvideo.dev/core/05-reference

Demonstrates how to get the current state from the store, subscribe to state changes, and listen for specific data patches. Useful for reacting to updates in the application's state.

```typescript
const state = core.store.getState();

const unsubscribe = core.store.subscribe((state, prev) => {
  console.log("State changed");
});

const off = state.onChange((patches) => {
  console.log("Patches:", patches);
});
```

--------------------------------

### Initialize and Play Studio with Pixi Renderer

Source: https://docs.openvideo.dev/core/00-getting-started

Instantiate the `Studio` class from `openvideo` to create a visual editing environment. Ensure the studio is ready before playing.

```typescript
import { Studio } from "openvideo";

const studio = new Studio({
  width: 1920,
  height: 1080,
  canvas: document.getElementById("canvas"),
});

await studio.ready;
studio.play();
```

--------------------------------

### Create Project with Initial Tracks

Source: https://docs.openvideo.dev/core/02-guides/create-project

Initialize a new Core instance with a predefined set of tracks. This is a best practice to create tracks upfront for better organization.

```javascript
const core = new Core({
  tracks: [
    { id: "background", name: "Background", clips: [] },
    { id: "video-main", name: "Main Video", clips: [] },
    { id: "video-pip", name: "Picture-in-Picture", clips: [] },
    { id: "overlays", name: "Overlays", clips: [] },
    { id: "audio-music", name: "Music", clips: [] },
    { id: "audio-voice", name: "Voice", clips: [] },
  ],
});
```

--------------------------------

### Initialize Core Instance

Source: https://docs.openvideo.dev/core/00-getting-started/quickstart

Create a new Core instance with specified video settings and an empty track list.

```typescript
import { Core } from "@openvideo/core";

const core = new Core({
  settings: {
    width: 1920,
    height: 1080,
    fps: 30,
    duration: 30_000_000, // 30 seconds in microseconds
  },
  tracks: [],
});
```

--------------------------------

### Initialize OpenVideo Core Project

Source: https://docs.openvideo.dev/core/04-advanced/headless-node

Create a new OpenVideo Core project instance with specified settings and tracks in a headless environment.

```typescript
import { Core } from "@openvideo/core";
import "./polyfills";

const core = new Core({
  settings: {
    width: 1920,
    height: 1080,
    fps: 30,
    duration: 60_000_000,
  },
  tracks: [
    { id: "video", name: "Video", clips: [] },
    { id: "audio", name: "Audio", clips: [] },
  ],
});

```

--------------------------------

### Initialize OpenVideo Core with Minimal Settings

Source: https://docs.openvideo.dev/core/02-guides/create-project

A minimal initialization of the OpenVideo Core instance, setting only the required dimensions and frame rate, with an empty array for tracks. Includes awaiting `core.ready` for asynchronous initialization.

```javascript
const core = new Core({
  settings: { width: 1920, height: 1080, fps: 30, duration: 30_000_000 },
  tracks: [],
});

// Wait for any async initialization
await core.ready;
```

--------------------------------

### Initialize OpenVideo Core

Source: https://docs.openvideo.dev/core/00-getting-started/basic-usage

Configure the engine settings including dimensions, frame rate, and total duration.

```javascript
import { Core } from "@openvideo/core";

const core = new Core({
  settings: {
    width: 1920,
    height: 1080,
    fps: 30,
    duration: 30_000_000,
  },
});
```

--------------------------------

### Get Selected Clips

Source: https://docs.openvideo.dev/core/02-guides/timeline-editing

Retrieves the list of currently selected clip IDs and their corresponding clip objects.

```javascript
const selectedIds = core.store.getState().selectedIds;
const selectedClips = selectedIds.map((id) => state.clips[id]);
```

--------------------------------

### Prepare a Static Image

Source: https://docs.openvideo.dev/core/02-guides/add-media

Initializes a static image clip with specified display timing.

```javascript
const image = await core.clip.prepare({
  type: "Image",
  src: "./photo.jpg",
  timing: {
    display: { from: 0, to: 5_000_000 }, // Display for 5 seconds
  },
});
```

--------------------------------

### Initialize OpenVideo Core Engine

Source: https://docs.openvideo.dev/core/05-reference/api-reference

Instantiate the Core engine with essential project settings like dimensions, frame rate, and duration. Ensure settings are provided during initialization.

```typescript
import { Core } from "@openvideo/core";

const core = new Core({
  settings: {
    width: 1920,
    height: 1080,
    fps: 30,
    duration: 30000000,
  },
});
```

--------------------------------

### Clear All History

Source: https://docs.openvideo.dev/core/02-guides/undo-redo

Reset both the undo and redo stacks to empty. This is typically done after saving the project or when starting a new session.

```typescript
// Clear all history (e.g., after save)
core.store.setState((state) => ({
  ...state,
  history: [],
  future: [],
}));
```

--------------------------------

### Load media with clip.prepare()

Source: https://docs.openvideo.dev/core/02-guides/add-media

The convenience method for loading media, extracting metadata, and creating a normalized clip object.

```javascript
const clip = await core.clip.prepare(payload, options);
```

--------------------------------

### Calculate Transition Overlap

Source: https://docs.openvideo.dev/core/03-creative/transitions

A utility function to determine the start and end points of a transition based on clip timing and a specified duration.

```typescript
function calculateOverlap(fromClip: AnyClip, toClip: AnyClip, duration: number) {
  const fromEnd = fromClip.timing?.display?.to || 0;
  const toStart = toClip.timing?.display?.from || 0;
  const junction = (fromEnd + toStart) / 2;

  return {
    from: junction - duration / 2,
    to: junction + duration / 2,
  };
}
```

--------------------------------

### Core Engine Constructor

Source: https://docs.openvideo.dev/core/05-reference/api-reference

Initializes the Core engine with project settings.

```APIDOC
## Core Engine Constructor

### Description
Initializes the Core engine with project settings.

### Usage
```typescript
import { Core } from "@openvideo/core";

const core = new Core({
  settings: {
    width: 1920,
    height: 1080,
    fps: 30,
    duration: 30_000_000,
  },
});
```
```

--------------------------------

### Listen to timeupdate Event

Source: https://docs.openvideo.dev/core/01-concepts/events

Subscribe to the 'timeupdate' event to get the current playback time in microseconds. This event is emitted during playback or seeking.

```javascript
import { core } from "@openvideo/core";

core.on("timeupdate", (time) => {
  console.log("Current time (μs):", time);
});
```

--------------------------------

### Prepare Basic Text

Source: https://docs.openvideo.dev/core/02-guides/add-media

Initializes a text clip with positioning and timing parameters.

```javascript
const title = await core.clip.prepare({
  type: "Text",
  text: "Hello World",
  timing: { display: { from: 0, to: 3_000_000 } },
  transform: {
    x: 960, // Center X
    y: 540, // Center Y
    width: 400,
    height: 100,
    angle: 0,
    zIndex: 10,
    opacity: 1,
  },
});
```

--------------------------------

### Organize Captions on Dedicated Track

Source: https://docs.openvideo.dev/core/03-creative/captions

Example of defining tracks, including a dedicated track for captions. Keeping captions on their own track simplifies management and organization.

```typescript
const tracks = [
  { id: "video-main", name: "Video" },
  { id: "captions", name: "Captions" }, // Dedicated track
  { id: "overlays", name: "Other Overlays" },
];
```

--------------------------------

### Initialize Compositor with Video Settings

Source: https://docs.openvideo.dev/core/04-advanced/rendering

Configure basic video output parameters like resolution, frame rate, and bitrate when creating a new Compositor instance.

```typescript
const compositor = new Compositor({
  width: 1920, // Output width
  height: 1080, // Output height
  fps: 30, // Frame rate
  bitrate: 8000000, // Video bitrate (bps)
});
```

--------------------------------

### Listen to Playback State Events

Source: https://docs.openvideo.dev/core/01-concepts/events

Use the 'play' and 'pause' events to track changes in the playback state. These events are emitted when playback starts or is paused.

```javascript
core.on("play", () => {
  console.log("Playback started");
});

core.on("pause", () => {
  console.log("Playback paused");
});
```

--------------------------------

### project.select

Source: https://docs.openvideo.dev/core/05-reference/command-catalog

Sets or adds clips to the current selection.

```APIDOC
## project.select

### Description
Set or add clips to the current selection array.

### Payload
- **ids** (string[]) - Required - Array of clip IDs to select.
- **multi** (boolean) - Optional - If true, appends to the selection rather than overriding it.

### Example
```javascript
core.execute({
  id: nanoid(),
  type: "project.select",
  payload: {
    ids: ["clip_123"],
    multi: true,
  },
});
```
```

--------------------------------

### Cleanup OpenVideo Resources

Source: https://docs.openvideo.dev/core/02-guides/create-project

Demonstrates how to clean up resources by removing event listeners. The Core instance itself can be garbage collected when no longer referenced.

```javascript
// Remove event listeners
core.off("timeupdate", handler);

// The Core instance can be garbage collected when no longer referenced
```

--------------------------------

### Control Video Playback

Source: https://docs.openvideo.dev/core/04-advanced/rendering

Use core functions to start, pause, seek, and monitor playback. Listen for playback events like play, pause, and timeupdate.

```javascript
import { core } from "@openvideo/core";

// Start playback
core.play();

// Pause playback
core.pause();

// Seek to a specific time (microseconds)
core.seek(1_500_000); // 1.5 seconds

// Get current playback state
const state = core.store.getState();
console.log("Playing:", state.isPlaying);
console.log("Current time:", state.currentTime);
console.log("Duration:", state.settings.duration);

// Listen for playback events
core.on("play", () => console.log("Started playing"));
core.on("pause", () => console.log("Paused"));
core.on("timeupdate", (time) => console.log("Time:", time));
```

--------------------------------

### Node.js Server-Side Video Export

Source: https://docs.openvideo.dev/core/04-advanced/rendering

Export a composition to an MP4 video file on a server using Node.js. This example converts a Web Stream to a Node.js stream for file writing.

```javascript
import { Compositor } from "@openvideo/core";
import { writeFile } from "fs/promises";
import { Readable } from "stream";

// Create compositor
const compositor = new Compositor({
  width: 1920,
  height: 1080,
  fps: 30,
});

// Load project
compositor.import(projectData);
await compositor.ready;

// Export
const stream = await compositor.output();

// Convert Web Stream to Node Stream and save
const nodeStream = Readable.fromWeb(stream as any);
const chunks: Buffer[] = [];

for await (const chunk of nodeStream) {
  chunks.push(Buffer.from(chunk));
}

await writeFile("output.mp4", Buffer.concat(chunks));
```

--------------------------------

### Extract Frames for AI Processing

Source: https://docs.openvideo.dev/core/04-advanced/rendering

Capture specific frames from a composition at defined timestamps for use in AI analysis pipelines. This example uses `Promise.all` to concurrently render multiple frames.

```typescript
// Extract frames at specific timestamps for analysis
const analysisFrames = await Promise.all([
  compositor.renderFrame(0), // Start
  compositor.renderFrame(5000), // 5 seconds
  compositor.renderFrame(10000), // 10 seconds
  compositor.renderFrame(15000), // 15 seconds
]);

// Send to AI service
const results = await aiService.analyzeFrames(analysisFrames);
```

--------------------------------

### Batch Loading Media Clips

Source: https://docs.openvideo.dev/core/02-guides/add-media

Use Promise.all to prepare multiple media files and add them to a track in a single batch operation.

```javascript
const files = [
  { type: "Video", src: "./intro.mp4" },
  { type: "Image", src: "./slide1.jpg" },
  { type: "Image", src: "./slide2.jpg" },
  { type: "Video", src: "./outro.mp4" },
];

const clips = await Promise.all(
  files.map((f, i) =>
    core.clip.prepare({
      ...f,
      timing: {
        display: {
          from: i * 10_000_000,
          to: (i + 1) * 10_000_000,
        },
      },
    }),
  ),
);

// Add all clips in a batch
import { nanoid } from "@openvideo/core";

core.batch(
  clips.map((clip) => ({
    id: nanoid(),
    type: "clip.add",
    payload: { trackId: "video-main", clip },
  })),
);
```

--------------------------------

### Define Available AI Actions

Source: https://docs.openvideo.dev/core/02-guides/ai-integration

Define a list of available actions for AI agents, including their names, descriptions, and required parameters. This structure guides the AI in understanding what operations it can perform.

```typescript
const AI_ACTIONS = [
  {
    name: "add_video",
    description: "Add a video clip to the timeline",
    parameters: {
      src: { type: "string", required: true },
      position: { type: "number", description: "Start time in seconds" },
      duration: { type: "number" },
    },
  },
  {
    name: "add_text",
    description: "Add a text overlay",
    parameters: {
      text: { type: "string", required: true },
      position: { type: "number" },
      style: { type: "object" },
    },
  },
  {
    name: "add_transition",
    description: "Add a transition between two clips",
    parameters: {
      type: { enum: ["fade", "slide", "wipe"] },
      duration: { type: "number" },
    },
  },
];
```

--------------------------------

### Define Common Project Presets

Source: https://docs.openvideo.dev/core/02-guides/create-project

Predefined configurations for common video resolutions and frame rates, such as HD, 4K, vertical, and square formats. Use these to quickly set up projects with standard dimensions.

```javascript
// 1080p @ 30fps (default)
const HD30 = { width: 1920, height: 1080, fps: 30 };

// 4K @ 60fps
const UHD60 = { width: 3840, height: 2160, fps: 60 };

// Vertical video (TikTok/Reels)
const VERTICAL = { width: 1080, height: 1920, fps: 30 };

// Square format
const SQUARE = { width: 1080, height: 1080, fps: 30 };
```

--------------------------------

### Initialize Compositor for Headless Rendering

Source: https://docs.openvideo.dev/core/05-reference/api-reference

Set up the Compositor for high-performance, headless video rendering. Specify output dimensions and frame rate. The compositor can output a ReadableStream or render individual frames.

```typescript
import { Compositor } from "@openvideo/core";

const compositor = new Compositor({
  width: 1920,
  height: 1080,
  fps: 30,
});
```

--------------------------------

### Patch Operation: Update Clip Position

Source: https://docs.openvideo.dev/core/04-advanced/patches

Provides an example of the 'update' operation to modify an existing property, like the 'x' coordinate of a clip's transform. The 'oldValue' is crucial for enabling undo functionality.

```json
{
  op: "update",
  path: "/clips/clip_123/transform/x",
  value: 100,
  oldValue: 0  // Required for undo
}
```

--------------------------------

### Compositor Constructor

Source: https://docs.openvideo.dev/core/05-reference/api-reference

Initializes the Compositor for high-performance headless video rendering.

```APIDOC
## Compositor Constructor

### Description
Initializes the Compositor for high-performance headless video rendering.

### Usage
```typescript
import { Compositor } from "@openvideo/core";

const compositor = new Compositor({
  width: 1920,
  height: 1080,
  fps: 30,
});
```
```

--------------------------------

### Apply Entry Animation Presets

Source: https://docs.openvideo.dev/core/03-creative/animations

Demonstrates how to apply fade-in, slide-in, and zoom-in animations to a clip using the core.clip.update method.

```typescript
import { core } from "@openvideo/core";

// Fade in
core.clip.update(clipId, {
  animations: [
    {
      id: "fade-in",
      type: "fadeIn",
      duration: 1_000_000,
      easing: "easeOutQuad",
    },
  ],
});

// Slide in from left
core.clip.update(clipId, {
  animations: [
    {
      id: "slide-in",
      type: "slideIn",
      duration: 800_000,
      easing: "easeOutBack",
      params: {
        direction: "left", // "left" | "right" | "top" | "bottom"
        distance: 500,
      },
    },
  ],
});

// Zoom in
core.clip.update(clipId, {
  animations: [
    {
      id: "zoom-in",
      type: "zoomIn",
      duration: 600_000,
      easing: "easeOutCubic",
    },
  ],
});
```

--------------------------------

### Batch-Friendly Command: Set Clip Position (Single Patch)

Source: https://docs.openvideo.dev/core/04-advanced/custom-commands

Optimize commands for batch operations by generating a single, more comprehensive patch for related state changes. This example updates the entire transform object for a clip.

```typescript
// BETTER: Single patch for related changes
const setClipPosition2: CommandHandler<{ clipId: string; x: number; y: number }> = (
  state,
  command,
) => {
  const { clipId, x, y } = command.payload;
  const clip = state.clips[clipId];

  return [
    {
      op: "update",
      path: `/clips/${clipId}/transform`,
      value: { ...clip.transform, x, y },
    },
  ];
};
```

--------------------------------

### Initialize Compositor with Audio Settings

Source: https://docs.openvideo.dev/core/04-advanced/rendering

Set audio-specific parameters such as bitrate, sample rate, and channel count during Compositor initialization.

```typescript
const compositor = new Compositor({
  // Video settings...
  audioBitrate: 128000, // Audio bitrate (bps)
  sampleRate: 48000, // Audio sample rate
  channels: 2, // Stereo (1 for mono)
});
```

--------------------------------

### Graceful Error Handling in Command Handlers

Source: https://docs.openvideo.dev/core/04-advanced/custom-commands

Provides an example of how to implement error handling within a command handler using a try-catch block. This prevents command execution failures from crashing the application and ensures a predictable state.

```typescript
const safeHandler: CommandHandler = (state, command) => {
  try {
    return calculatePatches(state, command);
  } catch (error) {
    // Log but don't crash
    console.error(`Command ${command.type} failed:`, error);
    return []; // Empty patches = no change
  }
};
```

--------------------------------

### Prepare an Animated GIF

Source: https://docs.openvideo.dev/core/02-guides/add-media

Initializes an animated GIF by using the Video type.

```javascript
const gif = await core.clip.prepare({
  type: "Video", // GIFs use Video type
  src: "./animation.gif",
});
```

--------------------------------

### Batch-Friendly Command: Set Clip Position (Multiple Patches)

Source: https://docs.openvideo.dev/core/04-advanced/custom-commands

Define a command handler that generates multiple patches for related state updates, suitable for batch processing. This example shows setting X and Y coordinates individually.

```typescript
// GOOD: Works in batch, single patch per command
const setClipPosition: CommandHandler<{ clipId: string; x: number; y: number }> = (
  state,
  command,
) => {
  const { clipId, x, y } = command.payload;

  return [
    { op: "update", path: `/clips/${clipId}/transform/x`, value: x },
    { op: "update", path: `/clips/${clipId}/transform/y`, value: y },
  ];
};
```

--------------------------------

### Server-Side Rendering with Compositor

Source: https://docs.openvideo.dev/core/04-advanced/serialization

Demonstrates how to use exported project state with the Compositor for server-side rendering. The Compositor can import the project data directly.

```javascript
import { Compositor } from "@openvideo/core";

// On the server:
const projectData = getProjectFromDB(projectId);
const compositor = new Compositor(projectData.settings);

// Import the state directly
compositor.import(projectData);

const stream = await compositor.output();
```

--------------------------------

### core.execute

Source: https://docs.openvideo.dev/core/05-reference/command-catalog

Executes a single command with optional metadata for attribution and tracking.

```APIDOC
## core.execute(command)

### Description
Executes a command. All commands support optional metadata objects to attribute edits.

### Parameters
- **command** (Object) - Required - The command object containing:
  - **id** (String) - Required - Unique identifier for the command.
  - **type** (String) - Required - The type of command (e.g., "clip.update").
  - **payload** (Object) - Required - The data required for the command.
  - **meta** (Object) - Optional - Metadata for attribution, including source, timestamp, and userId.
```

--------------------------------

### Configure Playback Settings

Source: https://docs.openvideo.dev/core/04-advanced/rendering

Adjust playback speed, mute/unmute audio, and set the volume level for the video composition.

```javascript
// Set playback speed (0.5x, 1x, 2x, etc.)
const state = core.store.getState();
state.setSpeed(1.5);

// Mute/unmute
state.setMuted(true);

// Set volume (0.0 to 1.0)
state.setVolume(0.8);
```

--------------------------------

### Configuring Custom Metadata Provider

Source: https://docs.openvideo.dev/core/02-guides/add-media

Implement a custom metadata provider to override default media resolution logic.

```typescript
import { CoreConfig } from "@openvideo/core";

CoreConfig.setMetadataProvider({
  async getMetadata(src: string) {
    // Your custom logic
    return {
      width: 1920,
      height: 1080,
      duration: 10_000_000,
      fps: 30,
    };
  },
});
```

--------------------------------

### Basic Effect Application

Source: https://docs.openvideo.dev/core/03-creative/effects

Demonstrates applying a sepia effect using both the DX Layer helper and the Direct Command API.

```typescript
import { core, nanoid } from "@openvideo/core";

// Using the DX Layer helper:
core.clip.update(clipId, {
  effects: [
    {
      id: nanoid(),
      key: "sepia",
      startTime: 0,
      duration: 5_000_000, // 5 seconds
    },
  ],
});

// Or using the Direct Command API:
core.execute({
  id: nanoid(),
  type: "clip.update",
  payload: {
    id: clipId,
    updates: {
      effects: [
        {
          id: nanoid(),
          key: "sepia",
          startTime: 0,
          duration: 5_000_000,
        },
      ],
    },
  },
});
```

--------------------------------

### Handling Failed Media Loads

Source: https://docs.openvideo.dev/core/02-guides/add-media

Wrap clip preparation in a try-catch block to handle individual loading failures.

```javascript
try {
  const video = await core.clip.prepare({
    type: "Video",
    src: "./missing.mp4",
  });
} catch (error) {
  console.error("Failed to load video:", error);
  // Show user-friendly error
}
```

--------------------------------

### Use DX Convenience Methods

Source: https://docs.openvideo.dev/core/01-concepts/commands

High-level methods provided by the Core class that wrap common command execution patterns.

```typescript
// These are equivalent:
core.clip.add({ type: 'Video', src: '...' });

// Manual equivalent:
core.execute({
  id: nanoid(),
  type: 'clip.add',
  payload: { clip: await core.clip.prepare({ type: 'Video', ... }) }
});
```

--------------------------------

### Importing Core Classes and Types

Source: https://docs.openvideo.dev/core/05-reference

Shows how to import essential classes, functions, and types from the OpenVideo Core library. This is necessary for using the library's features in your project.

```typescript
// Core classes and functions
import { Core, nanoid, createProjectStore } from "@openvideo/core";

// Types
import type {
  IProject,
  IProjectSettings,
  ITrack,
  AnyClip,
  IBaseClip,
  IVideoClip,
  IAudioClip,
  IImageClip,
  ITextClip,
  ICaptionClip,
  IClipTiming,
  IClipTransform,
  Command,
  Patch,
  ProjectStore,
} from "@openvideo/core";

// Commands
import { commandRegistry } from "@openvideo/core/commands/registry";
import type { CommandHandler, CommandMeta } from "@openvideo/core/commands/types";

// Utils
import { applyPatches, invertPatches } from "@openvideo/core/utils/patch";
```

--------------------------------

### Core Methods

Source: https://docs.openvideo.dev/core/05-reference

Provides methods for executing commands, managing undo/redo history, and loading projects.

```APIDOC
## Core Methods

### `core.execute(cmd)`

**Description**: Execute a single command.

**Method**: Not applicable (SDK method)

**Parameters**: None

**Request Example**: 
```javascript
core.execute({
  id: "some-id",
  type: "clip.add",
  payload: { /* ... */ }
});
```

### `core.batch(cmds)`

**Description**: Execute multiple commands in a batch.

**Method**: Not applicable (SDK method)

**Parameters**: None

**Request Example**: 
```javascript
core.batch([
  { id: "id1", type: "clip.add", payload: { /* ... */ } },
  { id: "id2", type: "clip.remove", payload: { clipId: "some-clip-id" } }
]);
```

### `core.undo()`

**Description**: Undo the last action performed.

**Method**: Not applicable (SDK method)

**Parameters**: None

**Request Example**: 
```javascript
core.undo();
```

### `core.redo()`

**Description**: Redo the last undone action.

**Method**: Not applicable (SDK method)

**Parameters**: None

**Request Example**: 
```javascript
core.redo();
```

### `core.reset(project)`

**Description**: Load a new project, resetting the current state.

**Method**: Not applicable (SDK method)

**Parameters**: 
- **project** (object) - Required - The project data to load.

**Request Example**: 
```javascript
const newProject = { /* project data */ };
core.reset(newProject);
```
```

--------------------------------

### Add a basic transition

Source: https://docs.openvideo.dev/core/03-creative/transitions

Demonstrates adding a 1-second fade transition between two existing clips using the Command API.

```typescript
import { core, nanoid } from "@openvideo/core";

// Add a 1-second fade transition between two clips
core.execute({
  id: nanoid(),
  type: "clip.add",
  payload: {
    clip: {
      id: nanoid(),
      type: "Transition",
      name: "Fade Transition",
      transitionKey: "fade",
      display: {
        from: 4_500_000, // Starts 0.5s before the junction
        to: 5_500_000, // Ends 0.5s after the junction
      },
      fromClipId: "video_1",
      toClipId: "video_2",
    },
  },
});
```

--------------------------------

### Configure video timing options

Source: https://docs.openvideo.dev/core/02-guides/add-media

Define display duration, source trimming, and playback speed for a video clip.

```javascript
const video = await core.clip.prepare({
  type: "Video",
  src: "./interview.mp4",
  timing: {
    // When on timeline
    display: { from: 0, to: 30_000_000 },
    // Which part of source to use
    trim: { from: 5_000_000, to: 35_000_000 },
    // Playback speed
    playbackRate: 1.0,
  },
});
```

--------------------------------

### Load Media in Headless Mode

Source: https://docs.openvideo.dev/core/04-advanced/headless-node

Prepare media clips in headless Node.js mode using HTTP URLs, local file paths, or Base64 data URIs.

```typescript
// In headless mode, src can be:
// - HTTP URL (publicly accessible)
// - File path (local filesystem)
// - Base64 data URI

const video = await core.clip.prepare({
  type: "Video",
  src: "https://example.com/video.mp4",
  // or
  // src: "file:///path/to/local/video.mp4",
});

core.execute({
  id: nanoid(),
  type: "clip.add",
  payload: { trackId: "video", clip: video },
});

```

--------------------------------

### Execute Creative Operations

Source: https://docs.openvideo.dev/core/03-creative

Demonstrates how to apply keyframe-based animations and transitions between clips using the core execution engine.

```javascript
// Animate position
core.execute({
  id: nanoid(),
  type: "clip.addKeyframes",
  payload: {
    clipId: "clip_1",
    property: "transform.x",
    keyframes: [
      { time: 0, value: 0, easing: "easeOut" },
      { time: 1_000_000, value: 100, easing: "linear" },
    ],
  },
});

// Add transition
core.execute({
  id: nanoid(),
  type: "transition.add",
  payload: {
    trackId: "main",
    between: ["clip_1", "clip_2"],
    type: "fade",
    duration: 500_000,
  },
});
```

--------------------------------

### Add video from file input

Source: https://docs.openvideo.dev/core/02-guides/add-media

Handle local file uploads by creating an object URL and preparing the video clip for the timeline.

```javascript
const input = document.querySelector('input[type="file"]');
input.addEventListener("change", async (e) => {
  const file = e.target.files[0];
  const url = URL.createObjectURL(file);

  const video = await core.clip.prepare({
    type: "Video",
    src: url,
    name: file.name,
  });

  core.execute({
    id: nanoid(),
    type: "clip.add",
    payload: { trackId: "video-main", clip: video },
  });
});
```

--------------------------------

### Apply Exit Animation Presets

Source: https://docs.openvideo.dev/core/03-creative/animations

Demonstrates how to apply fade-out and slide-out animations, including the use of delay parameters.

```typescript
// Fade out (start 4 seconds into clip)
core.clip.update(clipId, {
  animations: [
    {
      id: "fade-out",
      type: "fadeOut",
      duration: 800_000,
      easing: "easeInQuad",
      delay: 4_000_000,
    },
  ],
});

// Slide out to right
core.clip.update(clipId, {
  animations: [
    {
      id: "slide-out",
      type: "slideOut",
      duration: 600_000,
      easing: "easeInBack",
      params: { direction: "right", distance: 300 },
    },
  ],
});
```

--------------------------------

### Import Project State from JSON

Source: https://docs.openvideo.dev/core/04-advanced/serialization

Restores a project's state by parsing a JSON string and loading it into the core engine. Ensure the data exists before attempting to import.

```javascript
// Retrieve the data
const savedData = JSON.parse(localStorage.getItem("my-video-project"));

if (savedData) {
  // Load into the core engine
  core.project.import(savedData);
  console.log("Project state restored!");
}
```

--------------------------------

### Export Project to MP4

Source: https://docs.openvideo.dev/core/00-getting-started/quickstart

Render the current project state to a blob and trigger a browser download.

```typescript
import { render } from "@openvideo/core/rendering";

const blob = await render(core.store.getState().getSnapshot(), {
  format: "mp4",
  quality: "high",
});

// Download the result
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "my-video.mp4";
a.click();
```

--------------------------------

### Configure Node.js Polyfills

Source: https://docs.openvideo.dev/core/04-advanced/headless-node

Set up global polyfills for Crypto and WebSocket in your Node.js application.

```typescript
// polyfills.ts
import { Crypto } from "@peculiar/webcrypto";
import { WebSocket } from "ws";

// WebCrypto
global.crypto = new Crypto();

// WebSocket (for real-time features)
global.WebSocket = WebSocket as any;

// Other globals if needed
global.fetch = fetch; // Node 18+ has native fetch

```

--------------------------------

### Configure volume

Source: https://docs.openvideo.dev/core/02-guides/timeline-editing

Set the audio volume level or toggle the mute state.

```javascript
// Set volume (0-1)
core.store.getState().setVolume(0.8);

// Mute/unmute
core.store.getState().setMuted(true);
```

--------------------------------

### Project API

Source: https://docs.openvideo.dev/core/05-reference/api-reference

Methods for managing the overall project state, including creation and persistence.

```APIDOC
## Project API

### Description
Methods for managing the overall project state.

### Methods
* `core.project.new()`: Resets to a blank project.
* `core.project.export()`: Returns a JSON snapshot of the project.
* `core.project.import(json)`: Loads a project from a JSON snapshot.
```

--------------------------------

### Sync UI to Core State in Video Editor

Source: https://docs.openvideo.dev/core/04-advanced

Use `useSyncExternalStore` to synchronize your UI components with the OpenVideo Core state. User interactions can then dispatch commands to modify the state.

```typescript
const { currentTime, isPlaying } = useSyncExternalStore(core.store.subscribe, () =>
  core.store.getState(),
);

// User interactions dispatch commands
const onSeek = (time: number) => {
  core.execute({ id: nanoid(), type: "playback.seek", payload: { time } });
};
```

--------------------------------

### Navigate Timeline and Listen for Updates

Source: https://docs.openvideo.dev/core/00-getting-started/quickstart

Use playback commands to seek through the timeline and subscribe to timeupdate events.

```typescript
// Seek to 5 seconds
core.execute({
  id: nanoid(),
  type: "playback.seek",
  payload: { time: 5_000_000 },
});

// Listen for time updates
core.on("timeupdate", (time) => {
  console.log("Current time:", time / 1_000_000, "seconds");
});
```

--------------------------------

### Add multiple transitions

Source: https://docs.openvideo.dev/core/03-creative/transitions

Generate and execute a batch of add commands to place transitions between consecutive clips.

```javascript
// Add transitions between consecutive clips in a sequence
const clipIds = ["clip-1", "clip-2", "clip-3", "clip-4"];
const commands = [];

for (let i = 0; i < clipIds.length - 1; i++) {
  const fromId = clipIds[i];
  const toId = clipIds[i + 1];
  const junctionTime = 5_000_000 * (i + 1); // 5 seconds apart

  commands.push({
    id: nanoid(),
    type: "clip.add",
    payload: {
      clip: {
        id: nanoid(),
        type: "Transition",
        transitionKey: i % 2 === 0 ? "fade" : "cube",
        display: {
          from: junctionTime - 500_000,
          to: junctionTime + 500_000,
        },
        fromClipId: fromId,
        toClipId: toId,
      },
    },
  });
}

core.batch(commands);
```

--------------------------------

### core.execute(command)

Source: https://docs.openvideo.dev/core/01-concepts/commands

Executes a single command to update the project state.

```APIDOC
## core.execute(command)

### Description
Runs a single command and updates the state. Commands are plain objects containing an id, type, and payload.

### Parameters
- **command** (Object) - Required - The command object containing `id`, `type`, and `payload`.

### Example
```javascript
core.execute({
  id: nanoid(),
  type: "playback.seek",
  payload: 5_000_000
});
```
```

--------------------------------

### Add video from URL

Source: https://docs.openvideo.dev/core/02-guides/add-media

Load a video from a remote URL and add it to a specific track on the timeline.

```javascript
import { nanoid } from "@openvideo/core";

const video = await core.clip.prepare({
  type: "Video",
  src: "https://example.com/video.mp4",
  timing: {
    display: { from: 0, to: 10_000_000 }, // 10 seconds
    trim: { from: 0, to: 10_000_000 }, // Use first 10s of source
  },
});

core.execute({
  id: nanoid(),
  type: "clip.add",
  payload: { trackId: "video-main", clip: video },
});
```

--------------------------------

### core.execute

Source: https://docs.openvideo.dev/core/03-creative/animations

Executes a direct command to update a clip's animations.

```APIDOC
## core.execute(command)

### Description
Executes a command to update a clip's properties, including its animations.

### Parameters
- **command** (object) - Required - The command object containing `id`, `type` (set to "clip.update"), and `payload`.

### Request Example
```javascript
core.execute({
  id: nanoid(),
  type: "clip.update",
  payload: {
    id: clipId,
    updates: {
      animations: [
        {
          id: "fade-in",
          type: "fadeIn",
          duration: 1_000_000,
        },
      ],
    },
  },
});
```
```

--------------------------------

### Add Background Music

Source: https://docs.openvideo.dev/core/02-guides/add-media

Prepares an audio clip and adds it to a specific track using the clip.add command.

```javascript
const music = await core.clip.prepare({
  type: "Audio",
  src: "./music.mp3",
  timing: {
    display: { from: 0, to: 60_000_000 },
    trim: { from: 0, to: 60_000_000 },
  },
});

core.execute({
  id: nanoid(),
  type: "clip.add",
  payload: { trackId: "audio-music", clip: music },
});
```

--------------------------------

### Reset project

Source: https://docs.openvideo.dev/core/05-reference/command-catalog

Resets the workspace state to a new project configuration.

```javascript
core.execute({
  id: nanoid(),
  type: "project.reset",
  payload: {
    settings: { width: 1920, height: 1080, fps: 30, duration: 30_000_000 },
    tracks: [],
    clips: {},
  },
});
```
Tokens:
Raw