### Clone and Install React Video Editor Project

Source: https://github.com/designcombo/react-video-editor/blob/main/README.md

Follow these commands to clone the repository, navigate into the project directory, install dependencies using pnpm, and start the development server.

```bash
git clone git@github.com:designcombo/react-video-editor.git
cd react-video-editor
pnpm install
pnpm dev
```

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

### Initiate Video Render (POST /api/render)

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Use this endpoint to create a project and start an export job. Requires `COMBO_SK` environment variable. The response includes a `render.id` for status polling.

```bash
curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "design": {
      "id": "proj_abc123",
      "fps": 30,
      "size": { "width": 1080, "height": 1920 },
      "tracks": [...],
      "trackItemsMap": {...},
      "transitionsMap": {}
    },
    "options": {
      "fps": 30,
      "size": { "width": 1080, "height": 1920 },
      "format": "mp4"
    }
  }'

# Response:
# {
#   "render": { "id": "render_xyz789", "status": "PENDING" }
# }
```

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

### GET /api/pexels-videos – Stock Video Search

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Proxies the Pexels Videos API to search for stock videos. It returns popular videos if no query is provided, or search results based on the `query` parameter. It selects the best available HD/SD file.

```APIDOC
## GET /api/pexels-videos – Stock Video Search

### Description
Proxies the Pexels Videos API, selecting the best available HD/SD file. Without `query` it returns popular videos.

### Method
GET

### Endpoint
/api/pexels-videos

### Parameters
#### Query Parameters
- **query** (string) - Optional - The search term for videos.
- **page** (integer) - Optional - The page number for results.
- **per_page** (integer) - Optional - The number of results per page.

### Request Example
```bash
curl "http://localhost:3000/api/pexels-videos?query=ocean&page=1&per_page=15"
```

### Response
#### Success Response (200)
- **videos** (array) - An array of video objects.
  - **id** (string) - The unique identifier for the video.
  - **details** (object) - Contains detailed information about the video source.
    - **src** (string) - The URL of the video file.
    - **width** (integer) - The width of the video.
    - **height** (integer) - The height of the video.
    - **duration** (integer) - The duration of the video in seconds.
    - **fps** (integer) - The frames per second of the video.
  - **preview** (string) - A URL for a preview of the video.
  - **type** (string) - The type of media, always 'video'.
  - **metadata** (object) - Additional metadata about the video.
    - **pexels_id** (integer) - The Pexels API ID.
    - **user** (object) - Information about the video uploader.
      - **name** (string) - The name of the user.
- **total_results** (integer) - The total number of results found.
- **page** (integer) - The current page number.
- **per_page** (integer) - The number of results per page.

### Response Example
```json
{
  "videos": [
    {
      "id": "pexels_video_67890",
      "details": { "src": "https://player.vimeo.com/.../hd.mp4", "width": 1920, "height": 1080, "duration": 30, "fps": 30 },
      "preview": "https://images.pexels.com/.../preview.jpg",
      "type": "video",
      "metadata": { "pexels_id": 67890, "user": { "name": "Jane Doe" } }
    }
  ],
  "total_results": 500, "page": 1, "per_page": 15
}
```
```

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

### GET /api/pexels – Stock Image Search

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Proxies the Pexels Photos API to search for stock images. It can return curated images if no query is provided, or search results based on the `query` parameter. Requires `PEXELS_API_KEY` environment variable.

```APIDOC
## GET /api/pexels – Stock Image Search

### Description
Proxies the Pexels Photos API. Without a `query` parameter it returns curated images; with `query` it searches. Requires `PEXELS_API_KEY` environment variable.

### Method
GET

### Endpoint
/api/pexels

### Parameters
#### Query Parameters
- **query** (string) - Optional - The search term for images.
- **page** (integer) - Optional - The page number for results.
- **per_page** (integer) - Optional - The number of results per page.

### Request Example
```bash
# Search for images
curl "http://localhost:3000/api/pexels?query=mountains&page=1&per_page=20"

# Curated images (no query)
curl "http://localhost:3000/api/pexels?page=1&per_page=20"
```

### Response
#### Success Response (200)
- **photos** (array) - An array of image objects.
  - **id** (string) - The unique identifier for the photo.
  - **details** (object) - Contains detailed information about the image source.
    - **src** (string) - The URL of the image.
    - **width** (integer) - The width of the image.
    - **height** (integer) - The height of the image.
  - **preview** (string) - A URL for a preview of the image.
  - **type** (string) - The type of media, always 'image'.
  - **metadata** (object) - Additional metadata about the image.
    - **pexels_id** (integer) - The Pexels API ID.
    - **avg_color** (string) - The average color of the image.
- **total_results** (integer) - The total number of results found.
- **page** (integer) - The current page number.
- **per_page** (integer) - The number of results per page.

### Response Example
```json
{
  "photos": [
    {
      "id": "pexels_12345",
      "details": { "src": "https://images.pexels.com/.../large2x.jpg", "width": 3000, "height": 2000 },
      "preview": "https://images.pexels.com/.../medium.jpg",
      "type": "image",
      "metadata": { "pexels_id": 12345, "avg_color": "#4a6b8c" }
    }
  ],
  "total_results": 8000, "page": 1, "per_page": 20
}
```
```

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

### Load Fonts and Get Compact Font Data

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Use `loadFonts` to register custom fonts with the browser's font registry. `getCompactFontData` organizes a flat font list into a structure suitable for font pickers.

```typescript
import { loadFonts, getCompactFontData } from "@/features/editor/utils/fonts";
import { FONTS } from "@/features/editor/data/fonts";

// Load a single custom font for rendering
await loadFonts([
  { name: "geist-regular", url: "https://cdn.designcombo.dev/fonts/Geist-SemiBold.ttf" },
  { name: "theboldfont",   url: "https://cdn.designcombo.dev/fonts/the-bold-font.ttf" },
]);

// Build compact font list for a font-picker dropdown
const compactFonts = getCompactFontData(FONTS);
// compactFonts[0] → { family: "Roboto", styles: [...], default: { fullName: "Roboto Regular", ... } }
```

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

### Poll Render Status (GET /api/render/:id)

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Poll this endpoint to check the status of a render job using its `render.id`. The response includes `status`, `progress`, and `presigned_url` upon completion.

```bash
curl http://localhost:3000/api/render/render_xyz789

# Response while processing:
# { "render": { "id": "render_xyz789", "status": "PROCESSING", "progress": 45 } }

# Response when complete:
# {
#   "render": {
#     "id": "render_xyz789",
#     "status": "COMPLETED",
#     "progress": 100,
#     "presigned_url": "https://storage.googleapis.com/..."
#   }
# }
```

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

### GET /api/render/:id – Poll Render Status

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Polls the DesignCombo API for the status of a render job using its ID. Returns the render status, progress, and a presigned URL upon completion.

```APIDOC
## GET /api/render/:id – Poll Render Status

Polls the DesignCombo API for the status of a render job. Returns `status` (`PENDING` | `PROCESSING` | `COMPLETED`), `progress` (0–100), and `presigned_url` when complete.

```bash
curl http://localhost:3000/api/render/render_xyz789

# Response while processing:
# { "render": { "id": "render_xyz789", "status": "PROCESSING", "progress": 45 } }

# Response when complete:
# {
#   "render": {
#     "id": "render_xyz789",
#     "status": "COMPLETED",
#     "progress": 100,
#     "presigned_url": "https://storage.googleapis.com/..."
#   }
# }
```
```

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

### Set Up Environment Variables for React Video Editor

Source: https://github.com/designcombo/react-video-editor/blob/main/README.md

Create a .env file in the project root to store environment-specific variables. The PEXELS_API_KEY is required for certain functionalities.

```env
PEXELS_API_KEY=""
```

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

### POST /api/render – Initiate Video Render

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Initiates a video render job by creating a project in the DesignCombo API. Requires COMBO_SK environment variable. Returns an export object with a render ID for status polling.

```APIDOC
## POST /api/render – Initiate Video Render

Creates a project in the DesignCombo API and starts an export job. Requires `COMBO_SK` environment variable. Returns the export object including a `render.id` for status polling.

```bash
curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "design": {
      "id": "proj_abc123",
      "fps": 30,
      "size": { "width": 1080, "height": 1920 },
      "tracks": [...],
      "trackItemsMap": {...},
      "transitionsMap": {}
    },
    "options": {
      "fps": 30,
      "size": { "width": 1080, "height": 1920 },
      "format": "mp4"
    }
  }'

# Response:
# {
#   "render": { "id": "render_xyz789", "status": "PENDING" }
# }
```
```

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

### Upload Media by URL

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Copies externally-hosted media, such as Pexels CDN URLs, into the project's cloud storage bucket. Provide `userId` and an array of `urls` to copy.

```bash
curl -X POST http://localhost:3000/api/uploads/url \
  -H "Content-Type: application/json" \
  -d '{ \
    "userId": "user_abc", \
    "urls": [ \
      "https://images.pexels.com/photos/12345/large2x.jpg", \
      "https://player.vimeo.com/67890/hd.mp4" \
    ] \
  }'
```

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

### Initialize StateManager and Render Editor

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Bootsraps the StateManager with canvas size and renders the main Editor component. Used at the /edit route.

```tsx
// src/features/editor/editor.tsx
import StateManager, { DESIGN_LOAD } from "@designcombo/state";
import { dispatch } from "@designcombo/events";
import { design } from "./mock"; // pre-built IDesign JSON

// Instantiate state manager at 1080×1920 (vertical/Shorts canvas)
const stateManager = new StateManager({
  size: { width: 1080, height: 1920 },
});

// Optionally load a pre-existing design into the editor on mount:
// dispatch(DESIGN_LOAD, { payload: design });

// The Editor component is rendered at the /edit route:
// src/app/edit/page.tsx  →  <Editor />
// src/app/edit/[...id]/page.tsx  →  <Editor id={params.id} />
export default function App() {
  return <Editor />;
}
```

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

### useDownloadState for Export Pipeline

Source: https://context7.com/designcombo/react-video-editor/llms.txt

This Zustand store orchestrates the cloud render pipeline. Use `startExport()` to initiate the process after setting the design state and export type. The `output` property will contain the download URL upon completion.

```typescript
import { useDownloadState } from "@/features/editor/store/use-download-state";
import { generateId } from "@designcombo/timeline";

function ExportButton({ stateManager }) {
  const { actions, progress, exporting, output } = useDownloadState();

  const handleExport = () => {
    const design: IDesign = { id: generateId(), ...stateManager.toJSON() };
    actions.setState({ payload: design });
    actions.setExportType("mp4"); // or "json"
    actions.startExport();        // kicks off POST /api/render + polling
  };

  return (
    <div>
      <button onClick={handleExport} disabled={exporting}>
        {exporting ? `Exporting… ${progress}%` : "Export MP4"}
      </button>
      {output && <a href={output.url}>Download</a>}
    </div>
  );
}
```

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

### Search Stock Videos with Pexels API

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Proxies the Pexels Videos API, returning the best available HD/SD file. Without a `query` parameter, it returns popular videos.

```bash
curl "http://localhost:3000/api/pexels-videos?query=ocean&page=1&per_page=15"
```

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

### Speech-to-Text Caption Generation (POST /api/transcribe)

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Submit a media URL to generate speech-to-text captions. Requires `COMBO_SK`. The response provides a job ID and a URL to the transcription results.

```bash
curl -X POST http://localhost:3000/api/transcribe \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://storage.googleapis.com/bucket/video.mp4",
    "targetLanguage": "ES"
  }'

# Response:
# {
#   "transcribe": {
#     "id": "t_abc123",
#     "url": "https://storage.googleapis.com/transcripts/t_abc123.json"
#   }
# }
```

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

### Search Stock Images with Pexels API

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Proxies the Pexels Photos API. Use the `query` parameter to search for specific images, or omit it for curated images. Requires `PEXELS_API_KEY` environment variable.

```bash
curl "http://localhost:3000/api/pexels?query=mountains&page=1&per_page=20"
```

```bash
curl "http://localhost:3000/api/pexels?page=1&per_page=20"
```

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

### POST /api/transcribe – Speech-to-Text Caption Generation

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Submits a media URL to the DesignCombo speech-to-text service for caption generation. Requires COMBO_SK environment variable. Returns a job with a URL to the transcription results.

```APIDOC
## POST /api/transcribe – Speech-to-Text Caption Generation

Submits a media URL to the DesignCombo speech-to-text service. Requires `COMBO_SK` environment variable. Returns a job with a `transcribe.url` pointing to the transcription JSON results.

```bash
curl -X POST http://localhost:3000/api/transcribe \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://storage.googleapis.com/bucket/video.mp4",
    "targetLanguage": "ES"
  }'

# Response:
# {
#   "transcribe": {
#     "id": "t_abc123",
#     "url": "https://storage.googleapis.com/transcripts/t_abc123.json"
#   }
# }
```
```

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

### POST /api/uploads/url – Upload Media by URL

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Copies externally-hosted media, such as Pexels CDN URLs, into the project's cloud storage bucket.

```APIDOC
## POST /api/uploads/url – Upload Media by URL

### Description
Copies externally-hosted media (e.g., Pexels CDN URLs) into the project's cloud storage bucket.

### Method
POST

### Endpoint
/api/uploads/url

### Parameters
#### Request Body
- **userId** (string) - Required - The ID of the user for whom the media is being uploaded.
- **urls** (array of strings) - Required - An array of URLs pointing to the media to be copied.

### Request Example
```bash
curl -X POST http://localhost:3000/api/uploads/url \
  -H "Content-Type: application/json" \
  -d '{ 
    "userId": "user_abc",
    "urls": [
      "https://images.pexels.com/photos/12345/large2x.jpg",
      "https://player.vimeo.com/67890/hd.mp4"
    ]
  }'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **uploads** (array) - An array of upload objects detailing the copied media.
  - **fileName** (string) - The name of the uploaded file.
  - **originalUrl** (string) - The original URL of the media.
  - **url** (string) - The final URL of the media in the project's storage.

### Response Example
```json
{
  "success": true,
  "uploads": [
    {
      "fileName": "large2x.jpg",
      "originalUrl": "https://images.pexels.com/photos/12345/large2x.jpg",
      "url": "https://storage.googleapis.com/bucket/users/user_abc/large2x.jpg"
    }
  ]
}
```
```

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

### Dispatching Add-Item Events for Media

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Use these events to add video, image, or text media items to the timeline. Ensure the correct event type and payload structure are used.

```typescript
import { ADD_VIDEO, ADD_IMAGE, ADD_AUDIO, ADD_TEXT } from "@designcombo/state";
import { dispatch } from "@designcombo/events";
import { generateId } from "@designcombo/timeline";

// Add a video clip to the main track
dispatch(ADD_VIDEO, {
  payload: {
    id: generateId(),
    details: { src: "https://example.com/clip.mp4" },
    metadata: { previewUrl: "https://example.com/thumb.jpg" },
  },
  options: { resourceId: "main", scaleMode: "fit" },
});

// Add a 5-second image overlay
dispatch(ADD_IMAGE, {
  payload: {
    id: generateId(),
    type: "image",
    display: { from: 0, to: 5000 },
    details: { src: "https://example.com/photo.jpg" },
    metadata: {},
  },
  options: {},
});

// Add a text track item
dispatch(ADD_ITEMS, {
  payload: {
    trackItems: [{
      id: generateId(),
      type: "text",
      display: { from: 0, to: 5000 },
      details: {
        text: "Hello World",
        fontSize: 120,
        width: 600,
        fontFamily: "Roboto",
        color: "#ffffff",
        textAlign: "center",
      },
    }],
  },
});
```

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

### POST /api/uploads/presign – Presigned Upload URLs

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Generates S3-compatible presigned upload URLs for one or more files. This allows for direct browser-to-storage uploads.

```APIDOC
## POST /api/uploads/presign – Presigned Upload URLs

### Description
Generates S3-compatible presigned upload URLs for one or more files, enabling direct browser-to-storage uploads.

### Method
POST

### Endpoint
/api/uploads/presign

### Parameters
#### Request Body
- **userId** (string) - Required - The ID of the user initiating the upload.
- **fileNames** (array of strings) - Required - An array of file names to generate presigned URLs for.

### Request Example
```bash
curl -X POST http://localhost:3000/api/uploads/presign \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_abc", "fileNames": ["clip.mp4", "photo.jpg"] }'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **uploads** (array) - An array of upload objects, one for each requested file.
  - **fileName** (string) - The name of the file.
  - **filePath** (string) - The intended path for the file in storage.
  - **contentType** (string) - The MIME type of the file.
  - **presignedUrl** (string) - The presigned URL for uploading the file.
  - **url** (string) - The final URL of the file after upload.

### Response Example
```json
{
  "success": true,
  "uploads": [
    {
      "fileName": "clip.mp4",
      "filePath": "users/user_abc/clip.mp4",
      "contentType": "video/mp4",
      "presignedUrl": "https://storage.googleapis.com/...?X-Goog-Signature=...",
      "url": "https://storage.googleapis.com/bucket/users/user_abc/clip.mp4"
    }
  ]
}
```
```

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

### Generate Presigned Upload URLs

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Generates S3-compatible presigned upload URLs for direct browser-to-storage uploads. Specify `userId` and an array of `fileNames` in the request body.

```bash
curl -X POST http://localhost:3000/api/uploads/presign \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_abc", "fileNames": ["clip.mp4", "photo.jpg"] }'
```

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

### Dispatching Add-Item Events

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Add media items (video, audio, image, text) to the timeline by dispatching specific events with an ITrackItem payload.

```APIDOC
## Dispatching Add-Item Events

Media items (video, audio, image, text) are added to the timeline by dispatching `@designcombo/state` events with an `ITrackItem`-shaped payload.

```ts
import { ADD_VIDEO, ADD_IMAGE, ADD_AUDIO, ADD_TEXT } from "@designcombo/state";
import { dispatch } from "@designcombo/events";
import { generateId } from "@designcombo/timeline";

// Add a video clip to the main track
dispatch(ADD_VIDEO, {
  payload: {
    id: generateId(),
    details: { src: "https://example.com/clip.mp4" },
    metadata: { previewUrl: "https://example.com/thumb.jpg" },
  },
  options: { resourceId: "main", scaleMode: "fit" },
});

// Add a 5-second image overlay
dispatch(ADD_IMAGE, {
  payload: {
    id: generateId(),
    type: "image",
    display: { from: 0, to: 5000 },
    details: { src: "https://example.com/photo.jpg" },
    metadata: {},
  },
  options: {},
});

// Add a text track item
dispatch(ADD_ITEMS, {
  payload: {
    trackItems: [{
      id: generateId(),
      type: "text",
      display: { from: 0, to: 5000 },
      details: {
        text: "Hello World",
        fontSize: 120,
        width: 600,
        fontFamily: "Roboto",
        color: "#ffffff",
        textAlign: "center",
      },
    }],
  },
});
```
```

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

### Query AI Voices

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Queries the dubbing/voice service for available text-to-speech voices. Filter results by `languages` and `genders` using the `query` object.

```bash
curl -X POST http://localhost:3000/api/voices \
  -H "Content-Type: application/json" \
  -d '{ \
    "limit": 10, \
    "page": 1, \
    "query": { \
      "languages": ["en-US", "es-ES"], \
      "genders": ["female"] \
    } \
  }'
```

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

### Player Event Bus

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Control player playback by dispatching named events that are consumed by hooks to translate them into player actions.

```APIDOC
## Player Event Bus

Player playback is controlled by dispatching named events consumed by the `useTimelineEvents` and `usePlayerEvents` hooks, which translate them into Remotion `PlayerRef` calls.

```ts
import { dispatch } from "@designcombo/events";
import {
  PLAYER_PLAY,
  PLAYER_PAUSE,
  PLAYER_SEEK,
  PLAYER_SEEK_BY,
  PLAYER_TOGGLE_PLAY,
} from "@/features/editor/constants/events";

// Play
dispatch(PLAYER_PLAY);

// Pause
dispatch(PLAYER_PAUSE);

// Toggle
dispatch(PLAYER_TOGGLE_PLAY);

// Seek to an absolute time (in milliseconds)
dispatch(PLAYER_SEEK, { payload: { time: 3500 } }); // jump to 3.5s

// Seek by N frames relative to current position
dispatch(PLAYER_SEEK_BY, { payload: { frames: 30 } }); // forward 1 second at 30fps
```
```

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

### Load Design Payload

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Dispatch the `DESIGN_LOAD` event with a complete `IDesign` object to load a pre-built project into the editor. The `design` object contains all necessary editor state.

```typescript
import { design } from "@/features/editor/mock";
import { DESIGN_LOAD } from "@designcombo/state";
import { dispatch } from "@designcombo/events";

// Load a pre-built design into the editor (e.g., from a saved project)
dispatch(DESIGN_LOAD, { payload: design });

// design shape:
// {
//   id: "Wgp84CB2FzHWoaDL",
//   fps: 30,
//   size: { width: 1080, height: 1920 },
//   tracks: [{ id, type: "caption"|"video", items: string[], accepts: string[] }],
//   trackItemIds: string[],
//   trackItemsMap: {
//     "<id>": {
//       id, type: "video"|"caption"|"text"|"audio"|"image",
//       display: { from: number, to: number },  // ms
//       details: { src, width, height, opacity, ... },
//       metadata: { previewUrl, parentId? },
//       trim?: { from, to },
//       playbackRate?: number
//     }
//   },
//   transitionsMap: {},
//   transitionIds: []
// }
```

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

### Generate Captions from Transcription

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Use `generateCaptions` to convert speech-to-text results into `ICaption` track items. Ensure fonts are loaded beforehand using `loadFonts`.

```typescript
import { generateCaptions } from "@/features/editor/utils/captions";
import { loadFonts } from "@/features/editor/utils/fonts";
import { ADD_ITEMS } from "@designcombo/state";
import { dispatch } from "@designcombo/events";
import { generateId } from "@designcombo/timeline";

// transcriptionJson shape from /api/transcribe result URL
const transcriptionJson = {
  sourceUrl: "https://storage.googleapis.com/bucket/video.mp4",
  results: {
    main: {
      words: [
        { word: "Hello", start: 0.0,  end: 0.48, confidence: 0.98 },
        { word: "world", start: 0.52, end: 1.1,  confidence: 0.95 },
      ],
    },
  },
};

const fontInfo = {
  fontFamily: "theboldfont",
  fontUrl: "https://cdn.designcombo.dev/fonts/the-bold-font.ttf",
  fontSize: 64,
};

const options = {
  containerWidth: 800,     // max line width in pixels
  linesPerCaption: 1,      // words per caption block
  parentId: "video-track-item-id",
  displayFrom: 0,          // offset in ms if video doesn't start at 0
};

await loadFonts([{ name: fontInfo.fontFamily, url: fontInfo.fontUrl }]);

const captions = generateCaptions(transcriptionJson, fontInfo, options);
// captions: ICaption[] with display.from/to, words[], fontFamily, color, etc.

dispatch(ADD_ITEMS, {
  payload: {
    trackItems: captions,
    tracks: [{
      id: generateId(),
      items: captions.map((c) => c.id),
      type: "caption",
      name: "Captions",
    }],
  },
});
```

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

### Player Event Bus for Playback Control

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Dispatch these events to control player playback. They are consumed by hooks to translate into Remotion PlayerRef calls. Ensure the correct event constants are imported.

```typescript
import { dispatch } from "@designcombo/events";
import {
  PLAYER_PLAY,
  PLAYER_PAUSE,
  PLAYER_SEEK,
  PLAYER_SEEK_BY,
  PLAYER_TOGGLE_PLAY,
} from "@/features/editor/constants/events";

// Play
dispatch(PLAYER_PLAY);

// Pause
dispatch(PLAYER_PAUSE);

// Toggle
dispatch(PLAYER_TOGGLE_PLAY);

// Seek to an absolute time (in milliseconds)
dispatch(PLAYER_SEEK, { payload: { time: 3500 } }); // jump to 3.5s

// Seek by N frames relative to current position
dispatch(PLAYER_SEEK_BY, { payload: { frames: 30 } }); // forward 1 second at 30fps
```

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

### useStore Timeline State Access

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Accesses the live timeline state from the Zustand store, including tracks, items, player/timeline refs, and state manipulation functions. Used for seeking the player and resizing the timeline.

```ts
import useStore from "@/features/editor/store/use-store";

function MyComponent() {
  const {
    tracks,
    trackItemsMap,
    transitionsMap,
    activeIds,
    fps,
    duration,
    playerRef,
    timeline,
    setState,
  } = useStore();

  // Seek the player to 2 seconds
  playerRef?.current?.seekTo((2000 / 1000) * fps);

  // Resize the timeline canvas after layout change
  timeline?.resize({ height: 210, width: 1200 }, { force: true });
}
```

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

### StateManager Design State Management

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Manages the authoritative design state including tracks, items, and canvas size. Supports serialization and state mutations via events. Includes undo/redo functionality.

```ts
import StateManager, { DESIGN_RESIZE, HISTORY_UNDO, HISTORY_REDO } from "@designcombo/state";
import { dispatch } from "@designcombo/events";

const stateManager = new StateManager({ size: { width: 1920, height: 1080 } });

// Serialize the current design to JSON (used before export)
const design: IDesign = { id: generateId(), ...stateManager.toJSON() };
// design.tracks, design.trackItemsMap, design.transitionsMap, design.size, design.fps

// Resize the canvas
dispatch(DESIGN_RESIZE, {
  payload: { width: 1080, height: 1920, name: "9:16" }
});

// Undo / Redo
dispatch(HISTORY_UNDO);
dispatch(HISTORY_REDO);
```

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

### POST /api/voices – AI Voice Search

Source: https://context7.com/designcombo/react-video-editor/llms.txt

Queries the dubbing/voice service to find available text-to-speech voices. Voices can be filtered by language and gender.

```APIDOC
## POST /api/voices – AI Voice Search

### Description
Queries the dubbing/voice service for available text-to-speech voices, filterable by language and gender.

### Method
POST

### Endpoint
/api/voices

### Parameters
#### Request Body
- **limit** (integer) - Optional - The maximum number of voices to return.
- **page** (integer) - Optional - The page number for paginating results.
- **query** (object) - Optional - An object containing filters for the voice search.
  - **languages** (array of strings) - Optional - An array of language codes to filter by (e.g., "en-US").
  - **genders** (array of strings) - Optional - An array of genders to filter by (e.g., "female", "male").

### Request Example
```bash
curl -X POST http://localhost:3000/api/voices \
  -H "Content-Type: application/json" \
  -d '{ 
    "limit": 10,
    "page": 1,
    "query": {
      "languages": ["en-US", "es-ES"],
      "genders": ["female"]
    }
  }'
```

### Response
#### Success Response (200)
- **voices** (array) - An array of voice objects matching the query.
  - **id** (string) - The unique identifier for the voice.
  - **name** (string) - The name of the voice.
  - **language** (string) - The language code of the voice.
  - **gender** (string) - The gender of the voice.
  - **preview_url** (string) - A URL to a preview of the voice.
- **total** (integer) - The total number of voices available matching the criteria.

### Response Example
```json
{
  "voices": [
    { "id": "v_123", "name": "Aria", "language": "en-US", "gender": "female", "preview_url": "..." }
  ],
  "total": 42
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.