### Create and Setup Editframe Project (Bash)

Source: https://editframe.com/skills/editframe-create/getting-started

This snippet demonstrates how to create a new Editframe project using npm and navigate into the project directory. It's the first step in getting started with Editframe.

```bash
npm create @editframe -- html -d my-video
cd my-video
```

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

### Install Project Dependencies (Bash)

Source: https://editframe.com/skills/editframe-create/getting-started

Installs the necessary dependencies for your Editframe project. This command should be run after creating the project and navigating into its directory.

```bash
npm install
```

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

### Start Editframe Development Server (Bash)

Source: https://editframe.com/skills/editframe-create/getting-started

Launches a live preview server for your Editframe project. Changes made to the composition will be reflected instantly in the browser at http://localhost:4321.

```bash
npm start
```

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

### Installation

Source: https://editframe.com/skills/editframe-api/getting-started

Install the Editframe API package using npm.

```APIDOC
## Install the Package

```bash
npm install @editframe/api
```
```

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

### Create Your First Render

Source: https://editframe.com/skills/editframe-api/getting-started

Example of creating a video render from an HTML composition, monitoring its progress, and downloading the result.

```APIDOC
## Create Your First Render

### Description
This example demonstrates how to create a video render using an HTML composition, track its progress, and download the final video file.

### Method
POST (implicitly via `createRender` function)

### Endpoint
`/renders` (implicitly via `createRender` function)

### Parameters
#### Request Body (for `createRender`)
- **html** (string) - Required - The HTML composition to render.
- **width** (number) - Required - The width of the output video.
- **height** (number) - Required - The height of the output video.
- **fps** (number) - Required - The frames per second for the output video.
- **output** (object) - Optional - Configuration for output format (e.g., `container`, `quality`).

### Request Example
```typescript
import { Client, createRender } from "@editframe/api";

const client = new Client(process.env.EDITFRAME_API_KEY);

const render = await createRender(client, {
  html: `
    <ef-timegroup mode="contain" class="w-[1920px] h-[1080px] bg-black">
      <ef-video 
        src="https://assets.editframe.com/bars-n-tone.mp4"
        class="size-full object-contain">
      </ef-video>
      <ef-text 
        class="absolute bottom-10 left-10 text-white text-6xl font-bold">
        Hello, Editframe!
      </ef-text>
    </ef-timegroup>
  `,
  width: 1920,
  height: 1080,
  fps: 30,
});

console.log(`Render created: ${render.id}`);
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created render job.

#### Response Example
```json
{
  "id": "render_abc123xyz"
}
```

### Progress Monitoring

#### Description
Poll for the progress of a render job using its ID.

#### Method
GET (implicitly via `getRenderProgress` function)

#### Endpoint
`/renders/{render_id}/progress` (implicitly via `getRenderProgress` function)

### Download Render

#### Description
Download the completed render file.

#### Method
GET (implicitly via `downloadRender` function)

#### Endpoint
`/renders/{render_id}/download` (implicitly via `downloadRender` function)
```

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

### Install Editframe API Package

Source: https://editframe.com/skills/editframe-api/getting-started

Install the Editframe API client package using npm. This is the first step to integrating Editframe's rendering capabilities into your project.

```bash
npm install @editframe/api
```

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

### Local Webhook Testing with ngrok (Bash)

Source: https://editframe.com/skills/webhooks/getting-started

Sets up local development for testing Editframe webhooks. It involves starting a local development server (e.g., using 'npm run dev') and then using ngrok to expose the local server to the internet. The ngrok URL is then used as the webhook URL in the Editframe dashboard.

```bash
# Start your local server
npm run dev

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook URL
# Example: https://abc123.ngrok.io/webhooks/editframe
```

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

### TimelineRoot Setup with Configuration in React

Source: https://editframe.com/skills/composition/timeline-root

This example shows how to configure the TimelineRoot component with specific API host and media engine settings. It involves importing the Configuration component and wrapping TimelineRoot with it.

```tsx
// main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { Configuration, TimelineRoot } from "@editframe/react";
import { Video } from "./Video";
import "@editframe/elements/styles.css";

const root = document.getElementById("root");
if (!root) throw new Error("Root element not found");

ReactDOM.createRoot(root).render(
  <Configuration apiHost="https://api.example.com" mediaEngine="local">
    <TimelineRoot id="root" component={Video} />
  </Configuration>
);
```

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

### ef-focus-overlay Context Requirement Example

Source: https://editframe.com/skills/editor-gui/focus-overlay

Illustrates the context requirement for the ef-focus-overlay. The first example shows correct usage within an `ef-preview` which provides the necessary context. The second example demonstrates incorrect usage without a context provider, where the overlay will not function.

```html
<!-- Works - preview provides context -->
<ef-preview target="composition">
  <ef-focus-overlay></ef-focus-overlay>
</ef-preview>

<!-- Doesn't work - no context provider -->
<ef-focus-overlay></ef-focus-overlay>
```

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

### Basic HTML Video Composition Example

Source: https://editframe.com/skills/composition

A foundational example demonstrating a video composition using Editframe's HTML web components. It includes nested timegroups for sequencing and fixed modes, video and text elements, and basic styling with CSS animations. This serves as a starting point for creating visual narratives.

```html
<ef-configuration api-host="..." media-engine="local">
  <ef-timegroup mode="sequence" overlap="1s">
    <ef-timegroup mode="fixed" duration="5s" class="absolute w-full h-full">
      <ef-video src="intro.mp4" class="size-full object-cover"></ef-video>
      <ef-text
        split="word"
        class="absolute top-8 left-8 text-white text-4xl font-bold"
        style="animation: 0.6s slide-up both; animation-delay: calc(var(--ef-word-index) * 80ms)"
      >Opening Title</ef-text>
    </ef-timegroup>
    <ef-timegroup mode="fixed" duration="5s" class="absolute w-full h-full">
      <ef-video src="main.mp4" sourcein="10s" sourceout="15s" class="size-full"></ef-video>
      <ef-audio src="music.mp3" volume="0.3"></ef-audio>
    </ef-timegroup>
  </ef-timegroup>
</ef-configuration>
<style>
  @keyframes slide-up {
    from { transform: translateY(24px); opacity: 0; }
    to   { transform: translateY(0);    opacity: 1; }
  }
</style>
```

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

### Minimal Editor Setup (HTML)

Source: https://editframe.com/skills/editor-gui

This snippet demonstrates the most basic setup for a video editor, including a preview component and playback controls. It initializes an `ef-timegroup` as the composition and connects controls to it using the `target` attribute.

```html
<ef-preview>
  <ef-timegroup id="comp" mode="sequence" class="w-[1920px] h-[1080px]">
    <!-- your composition -->
  </ef-timegroup>
</ef-preview>

<ef-controls target="comp" class="flex items-center gap-4">
  <ef-toggle-play></ef-toggle-play>
  <ef-time-display></ef-time-display>
  <ef-scrubber class="flex-1"></ef-scrubber>
  <ef-toggle-loop></ef-toggle-loop>
</ef-controls>
```

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

### Full Scene ef-waveform Example

Source: https://editframe.com/skills/composition/waveform

A comprehensive example showcasing the ef-waveform within a full scene context, including an ef-timegroup, ef-audio, and ef-text. This illustrates how to integrate waveform visualization into a larger scene composition.

```html
<ef-timegroup mode="contain" workbench class="w-[720px] h-[400px] bg-slate-900 flex flex-col items-center justify-center">
  <ef-audio id="wf-demo" fft-size="256" src="https://assets.editframe.com/bars-n-tone.mp4" volume="0.6"></ef-audio>
  <ef-waveform mode="bars" target="wf-demo" class="text-green-400 w-3/4 h-32"></ef-waveform>
  <ef-text duration="10s" class="text-white text-lg mt-4">Audio Waveform</ef-text>
</ef-timegroup>
```

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

### Output Formats

Source: https://editframe.com/skills/editframe-api/getting-started

Configure the output format for renders, including image formats like JPEG and PNG.

```APIDOC
## Output Formats

### Description
By default, renders output MP4 with H.264 video and AAC audio. You can also configure renders to output still images.

### Parameters
#### Request Body (for `createRender` - `output` field)
- **container** (string) - Required - The desired output format (e.g., `mp4`, `jpeg`, `png`, `webp`).
- **quality** (number) - Optional - The quality setting for image formats (e.g., 90 for JPEG).

### Request Example
```typescript
const render = await createRender(client, {
  html: compositionHtml,
  width: 1920,
  height: 1080,
  output: {
    container: "jpeg",
    quality: 90,
  },
});
```

### Supported Formats
- `mp4`
- `jpeg`
- `png`
- `webp`

See [references/renders.md](references/renders.md) for complete output configuration options.
```

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

### Referencing Media Assets

Source: https://editframe.com/skills/composition/getting-started

Explains how to include media files like videos, audio, and images in your composition. Assets should be placed in the `src/assets/` directory and referenced using the `/assets/` path.

```html
<ef-video src="/assets/video.mp4"></ef-video>
<ef-audio src="/assets/music.mp3"></ef-audio>
<ef-image src="/assets/logo.png"></ef-image>
```

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

### Rendering Video with Editframe CLI

Source: https://editframe.com/skills/composition/getting-started

Provides the command-line instruction to render the video composition into a file. The `-o` flag specifies the output filename. For more options, refer to the `editframe-cli` skill.

```bash
npx editframe render -o output.mp4
```

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

### Webhook Handling Example

Source: https://editframe.com/skills/webhooks

Example of how to handle incoming webhook requests, including signature verification and asynchronous processing.

```APIDOC
## POST /webhooks/editframe

### Description
Handles incoming webhook notifications from Editframe. This endpoint should verify the signature of incoming requests and respond quickly to acknowledge receipt, processing the event data asynchronously.

### Method
POST

### Endpoint
`/webhooks/editframe`

### Parameters
#### Headers
- **X-Webhook-Signature** (string) - Required - The HMAC-SHA256 signature of the raw request body.

#### Request Body
- **topic** (string) - The event topic (e.g., `render.completed`).
- **data** (object) - The payload containing event-specific data.

### Request Example
```json
{
  "topic": "render.completed",
  "data": {
    "id": "rnd_abc123",
    "download_url": "https://example.com/render.mp4"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates successful receipt of the webhook.

#### Response Example
```
OK
```

### Security
All webhook requests include an `X-Webhook-Signature` header. It is critical to verify this signature using the `EDITFRAME_WEBHOOK_SECRET` before processing the payload to ensure the request originated from Editframe and has not been tampered with. Use `crypto.timingSafeEqual` for secure comparison.
```

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

### Installing Editframe CLI Globally

Source: https://editframe.com/skills/editframe-cli

Instructions for installing the Editframe CLI globally on your system using npm, allowing access to its commands from any directory.

```bash
npm install -g @editframe/cli
```

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

### Skip Agent Skills Installation During Project Creation (Bash)

Source: https://editframe.com/skills/editframe-create/agent-skills

These commands allow skipping the agent skills installation prompt when creating a new project with `npm create @editframe`. The first command skips all prompts, while the second specifically skips only the skills prompt, allowing other prompts to remain.

```bash
npm create @editframe -- html --skip-skills -y

```

```bash
npm create @editframe -- --skip-skills

```

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

### Example: Export with Custom Settings

Source: https://editframe.com/skills/composition/render-api

Provides a code example for rendering a video with specific custom settings like FPS, codec, bitrate, and scaling.

```APIDOC
## Example: Export with Custom Settings

### Description
Illustrates how to export a video using `renderToVideo` with a variety of custom parameters for quality and compatibility.

### Method
JavaScript

### Endpoint
N/A

### Parameters
N/A

### Request Example
```typescript
await timegroup.renderToVideo({
  fps: 60,                       // Smooth 60fps
  codec: 'avc',                  // H.264 for compatibility
  bitrate: 8_000_000,            // 8 Mbps
  scale: 1.5,                    // 1.5x resolution
  includeAudio: true,
  audioBitrate: 256_000,         // High quality audio
  filename: 'high-quality.mp4'
});
```

### Response
#### Success Response (200)
Video file rendered with specified custom settings.

#### Response Example
N/A
```

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

### Local Development Setup with ef-configuration

Source: https://editframe.com/skills/composition/configuration

Illustrates a typical local development setup using 'local' media engine and a custom signing URL path, often used in conjunction with the Editframe Vite plugin for fast iteration.

```html
<ef-configuration media-engine="local" signing-url="/@ef-sign-url">
  <ef-timegroup mode="contain" class="w-[720px] h-[480px]">
    <ef-video src="./assets/video.mp4" class="size-full"></ef-video>
  </ef-timegroup>
</ef-configuration>
```

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

### Webhook Endpoint Setup

Source: https://editframe.com/skills/webhooks/getting-started

This section details how to set up a webhook endpoint in your application to receive POST requests from Editframe. It includes prerequisites and a basic Express.js example.

```APIDOC
## POST /webhooks/editframe

### Description
This endpoint receives real-time notifications from Editframe for various events.

### Method
POST

### Endpoint
`/webhooks/editframe`

### Parameters
#### Query Parameters
None

#### Request Body
- **topic** (string) - The type of event that occurred (e.g., `render.completed`, `file.ready`).
- **data** (object) - Payload containing details about the event.

### Request Example
```json
{
  "topic": "render.completed",
  "data": {
    "render_id": "rnd_abc123",
    "file_id": "fil_xyz789"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message, e.g., "OK".

#### Response Example
```json
{
  "message": "OK"
}
```

### Requirements
- Accept POST requests with a JSON body.
- Respond with `200 OK` within 30 seconds.
- Verify the `X-Webhook-Signature` header.
- Handle events idempotently.
```

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

### Verifying Webhook Signatures

Source: https://editframe.com/skills/webhooks/getting-started

This section provides the necessary logic and code examples to verify the HMAC-SHA256 signature of incoming webhook requests, ensuring their authenticity.

```APIDOC
## Verify Webhook Signature

### Description
Verifies the authenticity of an incoming webhook request by comparing its `X-Webhook-Signature` header against a computed signature using the provided webhook secret.

### Method
POST (within the webhook handler)

### Endpoint
`/webhooks/editframe`

### Parameters
#### Headers
- **X-Webhook-Signature** (string) - Required - The HMAC-SHA256 signature provided by Editframe.

#### Request Body
- **Raw Request Body** (string) - The raw, unparsed JSON string of the webhook payload.

### Verification Logic
1. Retrieve the raw request body.
2. Retrieve the `X-Webhook-Signature` header value.
3. Retrieve your stored `webhookSecret`.
4. Compute the HMAC-SHA256 hash of the raw request body using the `webhookSecret`.
5. Compare the computed signature with the signature from the header using a timing-safe comparison method.

### Code Example (Node.js)
```javascript
import crypto from 'node:crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
}

// Inside your webhook handler:
app.post('/webhooks/editframe', async (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const payload = JSON.stringify(req.body); // IMPORTANT: Use the parsed body to get the original structure for stringification
  const secret = process.env.EDITFRAME_WEBHOOK_SECRET!;

  if (!verifyWebhookSignature(payload, signature, secret)) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Invalid signature');
  }

  // Signature is valid - process event
  const { topic, data } = req.body;
  console.log(`Verified webhook: ${topic}`);

  res.status(200).send('OK');
});
```

### Critical Note
Ensure you hash the **raw request body** as received, not a re-serialized version of a parsed JSON object, as differences in serialization can lead to signature mismatches.
```

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

### Basic ef-preview Usage (HTML)

Source: https://editframe.com/skills/editor-gui/preview

Demonstrates the fundamental usage of the ef-preview component by wrapping a composition to enable preview mode. It sets up a basic viewing area for media content.

```html
<ef-preview class="w-[720px] h-[480px] bg-gray-100 border border-gray-300 rounded">
  <ef-timegroup mode="contain" class="size-full bg-black">
    <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
  </ef-timegroup>
</ef-preview>
```

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

### Render Editframe Composition to MP4 (Bash)

Source: https://editframe.com/skills/editframe-create/getting-started

This command uses the Editframe CLI to render the project's composition into an MP4 video file. It processes the composition frame-by-frame.

```bash
npx editframe render -o my-video.mp4
```

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

### Multiple Canvases Setup (HTML)

Source: https://editframe.com/skills/editor-gui/active-root-temporal

Demonstrates setting up multiple independent ef-canvas instances, each with its own ef-active-root-temporal component.

```html
<ef-active-root-temporal canvas="canvas-1">None</ef-active-root-temporal>
<ef-canvas id="canvas-1"></ef-canvas>

<ef-active-root-temporal canvas="canvas-2">None</ef-active-root-temporal>
<ef-canvas id="canvas-2"></ef-canvas>
```

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

### Define Editframe Composition (HTML)

Source: https://editframe.com/skills/editframe-create/getting-started

This HTML snippet shows how to define a video composition using Editframe elements. It includes nested `ef-timegroup` elements to structure the sequence and apply styles.

```html
<ef-timegroup mode="sequence" class="w-[1920px] h-[1080px] bg-black">
  <ef-timegroup mode="fixed" duration="5s" class="absolute w-full h-full">
    <ef-text class="text-white text-4xl">Hello, Editframe!</ef-text>
  </ef-timegroup>
</ef-timegroup>
```

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

### Basic Composition Structure with ef-timegroup

Source: https://editframe.com/skills/composition/getting-started

Defines the root element for a video composition. The `mode` attribute controls how child elements are timed (e.g., 'sequence' for sequential playback). The example sets dimensions and background color.

```html
<ef-timegroup mode="sequence" class="w-[1920px] h-[1080px] bg-black">
  <!-- scenes go here -->
</ef-timegroup>
```

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

### Programmatic Access (Return Buffer)

Source: https://editframe.com/skills/composition/render-to-video

Retrieves the rendered video as a binary buffer instead of directly downloading it, enabling further programmatic manipulation like uploading to a server.

```APIDOC
## POST /api/render/video

### Description
Renders a video composition and returns the output as a binary buffer instead of a downloadable file. This is useful for server-side processing or direct uploads.

### Method
POST

### Endpoint
/api/render/video

### Parameters
#### Query Parameters
- **returnBuffer** (boolean) - Required - If set to `true`, the response will be a binary buffer of the video data.

### Request Body
(Assumed to contain composition details and other render options)

### Request Example
```javascript
const videoBuffer = await timegroup.renderToVideo({
  returnBuffer: true,
  filename: 'video.mp4' // Filename might still be relevant for internal processing
});

// Example: Uploading the buffer to a server
const formData = new FormData();
formData.append('video', new Blob([videoBuffer], { type: 'video/mp4' }));

await fetch('/api/upload', {
  method: 'POST',
  body: formData
});
```

### Response
#### Success Response (200)
- **(Binary Data)** - The raw binary data of the rendered video file if `returnBuffer` is true.
```

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

### Basic ef-workbench Usage with Composition

Source: https://editframe.com/skills/editor-gui/workbench

Demonstrates the basic integration of ef-workbench by wrapping a composition. It includes a canvas with pan/zoom, a hierarchy panel, and a timeline with playback controls and a filmstrip. This setup provides a functional video editing environment.

```html
<ef-workbench class="w-full h-screen">
  <ef-pan-zoom slot="canvas">
    <ef-fit-scale>
      <ef-timegroup mode="sequence" class="w-[720px] h-[480px] bg-black">
        <ef-timegroup mode="fixed" duration="3s" class="flex items-center justify-center">
          <ef-text duration="3s" class="text-white text-4xl">First Scene</ef-text>
        </ef-timegroup>
        <ef-timegroup mode="fixed" duration="3s" class="flex items-center justify-center">
          <ef-text duration="3s" class="text-white text-4xl">Second Scene</ef-text>
        </ef-timegroup>
      </ef-timegroup>
    </ef-fit-scale>
  </ef-pan-zoom>

  <ef-hierarchy slot="hierarchy"></ef-hierarchy>

  <div slot="timeline" class="h-full flex flex-col">
    <ef-controls class="flex items-center gap-2 p-2 border-b border-gray-700">
      <ef-toggle-play>
        <button slot="play" class="px-3 py-1 bg-blue-600 text-white rounded">Play</button>
        <button slot="pause" class="px-3 py-1 bg-gray-600 text-white rounded">Pause</button>
      </ef-toggle-play>
      <ef-time-display class="text-sm text-gray-300"></ef-time-display>
    </ef-controls>
    <ef-filmstrip class="flex-1"></ef-filmstrip>
  </div>
</ef-workbench>
```

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

### Registering a Webhook

Source: https://editframe.com/skills/webhooks/getting-started

Instructions on how to register your webhook URL and select events, both through the Editframe dashboard and programmatically via the API.

```APIDOC
## Create API Key with Webhook Configuration

### Description
This API allows you to programmatically create an API key and configure webhook settings, including the URL and the events to subscribe to.

### Method
POST

### Endpoint
`/api/v1/api_keys` (Hypothetical endpoint for programmatic creation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - A name for the API key (e.g., "My Application").
- **webhookUrl** (string) - Required - The HTTPS URL of your application's webhook endpoint.
- **webhookEvents** (array of strings) - Required - A list of event types to receive notifications for (e.g., `["render.completed", "render.failed", "file.ready"]`).
- **webhookSecret** (string) - Optional - A secret key used for signing webhook events. If not provided, one will be generated.
- **token** (string) - Optional - A specific API token to use. If not provided, one will be generated.
- **orgId** (string) - Required - The ID of the organization.
- **userId** (string) - Required - The ID of the user.
- **expired_at** (string or null) - Optional - The expiration date of the API key in ISO 8601 format, or null for no expiration.

### Request Example
```json
{
  "name": "My Application",
  "webhookUrl": "https://your-app.com/webhooks/editframe",
  "webhookEvents": [
    "render.completed",
    "render.failed",
    "file.ready"
  ],
  "orgId": "your-org-id",
  "userId": "your-user-id",
  "expired_at": null
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created API key.
- **token** (string) - The generated API token (should be stored securely).
- **webhookSecret** (string) - The generated webhook secret (should be stored securely).

#### Response Example
```json
{
  "id": "key_abc123",
  "token": "generated_api_token_here",
  "webhookSecret": "generated_webhook_secret_here"
}
```
```

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

### Build Composition Editor with ef-preview (HTML)

Source: https://editframe.com/skills/editor-gui/preview

Demonstrates the foundational structure of a composition editor using ef-preview. It includes a preview area for the composition and a properties panel. This setup is essential for visualizing and interacting with temporal elements.

```html
<div class="bg-gray-900 p-4 rounded-lg">
  <div class="flex gap-4">
    <!-- Preview area -->
    <ef-preview class="flex-1 bg-gray-800 border border-gray-700 rounded">
      <ef-timegroup mode="sequence" class="w-[720px] h-[480px] bg-black">
        <ef-timegroup mode="fixed" duration="3s" class="absolute size-full flex items-center justify-center">
          <div class="text-white text-4xl font-bold">Scene 1</div>
        </ef-timegroup>
        <ef-timegroup mode="fixed" duration="3s" class="absolute size-full flex items-center justify-center">
          <div class="text-white text-4xl font-bold">Scene 2</div>
        </ef-timegroup>
      </ef-timegroup>
    </ef-preview>

    <!-- Properties panel -->
    <div class="w-64 bg-gray-800 border border-gray-700 rounded p-4">
      <h3 class="text-white font-semibold mb-2">Properties</h3>
      <p class="text-gray-400 text-sm">Hover elements to inspect</p>
    </div>
  </div>
</div>
```

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

### Caption JSON Output Format (JSON)

Source: https://editframe.com/skills/editframe-cli/transcribe

Example of the JSON structure generated by the Editframe Transcribe skill. It includes segments and word-level segments with start and end times in milliseconds, and the transcribed text.

```json
{
  "segments": [
    { "start": 0, "end": 2500, "text": "Hello world" }
  ],
  "word_segments": [
    { "text": "Hello", "start": 0, "end": 800 },
    { "text": "world", "start": 900, "end": 2500 }
  ]
}
```

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

### Basic Usage of ef-trim-handles with Video

Source: https://editframe.com/skills/editor-gui/trim-handles

Demonstrates the basic integration of ef-trim-handles with an ef-video element. It shows how to set up the trim handles, link them to a video element and a timegroup, and listen for 'trim-change' events to update the video's trim attributes. Dependencies include ef-timegroup, ef-video, and ef-trim-handles.

```html
<div class="space-y-4">
  <ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="trim-demo">
    <ef-video
      src="https://assets.editframe.com/bars-n-tone.mp4"
      class="size-full object-contain"
      id="trim-video"
    ></ef-video>
  </ef-timegroup>

  <div class="p-4 bg-gray-900 rounded-lg">
    <div class="text-white text-sm mb-2">Drag handles to trim video:</div>
    <div class="h-[60px] relative bg-gray-800 rounded-lg">
      <ef-trim-handles
        element-id="trim-video"
        intrinsic-duration-ms="10000"
        seek-target="trim-demo"
      ></ef-trim-handles>
    </div>
    <ef-controls target="trim-demo" class="flex gap-2 mt-3">
      <ef-toggle-play class="px-3 py-1 bg-blue-600 text-white rounded"></ef-toggle-play>
      <ef-time-display class="text-white font-mono"></ef-time-display>
    </ef-controls>
  </div>
</div>

<script>
  const handles = document.querySelector('ef-trim-handles');
  const video = document.getElementById('trim-video');

  handles.addEventListener('trim-change', (e) => {
    const { value } = e.detail;
    video.setAttribute('trimstart', `${value.startMs}ms`);
    video.setAttribute('trimend', `${value.endMs}ms`);
  });
</script>
```

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

### Basic Timeline Editor Usage (HTML)

Source: https://editframe.com/skills/editor-gui/timeline

Demonstrates the basic setup of the ef-timeline component, integrating it with an ef-timegroup to display video and text elements. This serves as a foundational example for timeline integration.

```html
<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="timeline-demo">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
  <ef-text class="absolute top-4 left-4 text-white text-3xl font-bold">Timeline Demo</ef-text>
  <ef-text class="absolute bottom-4 left-4 text-white text-lg">Subtitle text</ef-text>
</ef-timegroup>
<div class="mt-4 h-[400px] bg-gray-900 rounded-lg overflow-hidden">
  <ef-timeline target="timeline-demo"></ef-timeline>
</div>
```

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

### Basic Usage of ef-controls with HTML

Source: https://editframe.com/skills/editor-gui/controls

Demonstrates how to use ef-controls to manage a media composition from outside its DOM tree. It shows the setup for an ef-timegroup and its associated controls, including play/pause buttons and a time display.

```html
<ef-timegroup id="my-composition" mode="sequence" class="w-[720px] h-[480px] bg-black">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>

<ef-controls target="my-composition" class="flex gap-2 mt-4">
  <ef-toggle-play>
    <button slot="play" class="px-4 py-2 bg-blue-600 text-white rounded">Play</button>
    <button slot="pause" class="px-4 py-2 bg-gray-600 text-white rounded">Pause</button>
  </ef-toggle-play>
  <ef-time-display class="text-gray-300"></ef-time-display>
</ef-controls>
```

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

### Render Still Image with TypeScript

Source: https://editframe.com/skills/editframe-api/getting-started

This TypeScript snippet shows how to configure Editframe to render a still image (JPEG) instead of a video. It specifies the output container as 'jpeg' and sets the quality level.

```typescript
const render = await createRender(client, {
  html: compositionHtml,
  width: 1920,
  height: 1080,
  output: {
    container: "jpeg",
    quality: 90,
  },
});
```

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

### ef-preview with Focus Overlay Placeholder (HTML)

Source: https://editframe.com/skills/editor-gui/preview

Provides a basic structure for using ef-preview in conjunction with a focus overlay. It sets up the preview container and includes a placeholder comment for where the focus overlay would typically be integrated.

```html
<ef-preview class="w-[720px] h-[480px] bg-gray-100 border border-gray-300 rounded relative">
  <ef-timegroup mode="contain" class="size-full bg-black">
    <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
    <div class="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white/10 backdrop-blur border-2 border-white/50 px-6 py-4 rounded-lg">
      <p class="text-white text-lg font-semibold">Hover to focus</p>
    </div>
  </ef-timegroup>
  <!-- Focus overlay would go here in a real editor -->
</ef-preview>
```

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

### Responsive Layouts with CSS Grid and Flexbox for Editframe

Source: https://editframe.com/skills/editor-gui/editor-toolkit

Provides an example of using CSS Grid and Flexbox to create responsive layouts for the Editframe editor interface. This snippet demonstrates how to structure the main layout areas (preview, controls, timeline) to adapt to different screen sizes and user needs.

```html
<div class="h-screen grid grid-rows-[1fr_auto_200px]">
  <ef-preview><!-- preview --></ef-preview>
  <ef-controls><!-- controls --></ef-controls>
  <ef-filmstrip><!-- timeline --></ef-filmstrip>
</div>
```

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

### Use ef-preview in Selection System Use Case (HTML)

Source: https://editframe.com/skills/editor-gui/preview

Presents a use case for ef-preview within a selection system. This example shows how to structure ef-preview with ef-timegroup to contain multiple elements like video clips and text, enabling selection and editing functionalities.

```html
<ef-preview>
  <ef-timegroup>
    <ef-video id="clip1"></ef-video>
    <ef-text id="title"></ef-text>
  </ef-timegroup>
</ef-preview>
```

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

### Launch Live Preview with editframe CLI

Source: https://editframe.com/skills/editframe-cli/preview

Launches a live development preview of your composition using the Editframe CLI. This command starts a Vite dev server, which enables instant updates through hot module replacement as you make changes. The default project directory is the current directory, but a specific directory can be provided.

```bash
npx editframe preview [directory]
```

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

### Layering Video Background with ef-contain

Source: https://editframe.com/skills/composition/getting-started

Shows how to layer elements within a composition. An animated title is placed inside a `contain` timegroup, which holds both the title and a video background simultaneously.

```html
<ef-timegroup mode="sequence" class="w-[1920px] h-[1080px] bg-black">
  <ef-contain>
    <ef-video src="/assets/background.mp4"></ef-video>
    <ef-text split="word" style="animation: slideUp 1s ease-out forwards;">
      Hello Editframe
    </ef-text>
  </ef-contain>
</ef-timegroup>
```

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

### Partial Video Export

Source: https://editframe.com/skills/composition/render-to-video

This code example demonstrates how to export only a specific segment of a video composition. By using the `fromMs` and `toMs` parameters, you can define the start and end times (in milliseconds) for the desired clip.

```javascript
await timegroup.renderToVideo({
  fromMs: 2000,    // Start at 2 seconds
  toMs: 8000,      // End at 8 seconds
  filename: 'clip.mp4'
});
```

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

### Include Audio in Video Render

Source: https://editframe.com/skills/composition/render-to-video

Demonstrates how to include audio from ef-video and ef-audio elements in the final video render. Audio is automatically mixed when present.

```APIDOC
## POST /api/render/video

### Description
Renders a video composition, automatically mixing in audio from specified elements. Supports various audio-related options for quality and codec preference.

### Method
POST

### Endpoint
/api/render/video

### Parameters
#### Query Parameters
- **includeAudio** (boolean) - Optional - Whether to include audio in the render. Defaults to true.
- **audioBitrate** (integer) - Optional - The desired bitrate for the audio in bits per second (e.g., 192000 for 192 kbps).
- **preferredAudioCodecs** (array of strings) - Optional - An ordered list of preferred audio codecs (e.g., ['opus', 'aac']).

### Request Body
(Assumed to contain composition details and other render options)

### Request Example
```javascript
await timegroup.renderToVideo({
  fps: 30,
  codec: 'avc',
  includeAudio: true,
  audioBitrate: 192000,
  preferredAudioCodecs: ['opus', 'aac'],
  filename: 'video-with-audio.mp4'
});
```

### Response
#### Success Response (200)
- **videoUrl** (string) - URL to the rendered video file.

#### Response Example
```json
{
  "videoUrl": "/path/to/rendered/video-with-audio.mp4"
}
```
```

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

### Creating a New Editframe Project

Source: https://editframe.com/skills/composition/getting-started

Shows the command to create a new Editframe project using the `editframe-create` tool. The `-d` flag specifies the directory name for the project, and `-y` accepts defaults.

```bash
npm create @editframe -- html -d my-project -y
```

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

### Example: Progress Bar with Time Estimates

Source: https://editframe.com/skills/composition/render-api

Shows how to implement a progress bar during video rendering, displaying completion percentage, elapsed time, and estimated remaining time.

```APIDOC
## Example: Progress Bar with Time Estimates

### Description
Demonstrates how to utilize the `onProgress` callback in `renderToVideo` to display real-time rendering progress, including time estimates and speed.

### Method
JavaScript

### Endpoint
N/A

### Parameters
N/A

### Request Example
```typescript
await timegroup.renderToVideo({
  onProgress: ({ progress, elapsedMs, estimatedRemainingMs, speedMultiplier }) => {
    const percent = Math.round(progress * 100);
    const elapsed = Math.round(elapsedMs / 1000);
    const remaining = Math.round(estimatedRemainingMs / 1000);

    console.log(
      `${percent}% complete | ` +
      `Elapsed: ${elapsed}s | ` +
      `Remaining: ${remaining}s | ` +
      `Speed: ${speedMultiplier.toFixed(1)}x`
    );
  }
});
```

### Response
#### Success Response (200)
Rendering progress updates are logged to the console.

#### Response Example
N/A
```

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

### Create a Webhook Endpoint (TypeScript)

Source: https://editframe.com/skills/webhooks/getting-started

Sets up an Express.js endpoint to receive POST requests from Editframe webhooks. It includes basic logging and a placeholder for signature verification. The endpoint must respond quickly and handle events idempotently.

```typescript
import express from "express";
import crypto from "node:crypto";

const app = express();
app.use(express.json());

app.post("/webhooks/editframe", async (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const payload = req.body;

  // TODO: Verify signature (see Step 3)

  console.log("Webhook received:", payload.topic);

  // Respond quickly - process events asynchronously
  res.status(200).send("OK");

  // Process event in background
  processWebhookEvent(payload).catch(console.error);
});

app.listen(3000);
```

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

### ef-canvas with Multiple Selectable Items

Source: https://editframe.com/skills/editor-gui/canvas

An example demonstrating an ef-canvas setup with multiple child elements designed for box selection. This HTML structure provides the visual elements that can be selected using the box selection feature.

```html
<div class="relative w-full h-[400px] border border-gray-300 rounded overflow-hidden">
  <ef-pan-zoom class="w-full h-full">
    <ef-canvas class="w-[1200px] h-[800px] bg-gray-100">
      <div id="item-1" class="absolute top-12 left-12 w-24 h-24 bg-blue-500 rounded"></div>
      <div id="item-2" class="absolute top-12 left-48 w-24 h-24 bg-green-500 rounded"></div>
      <div id="item-3" class="absolute top-12 left-84 w-24 h-24 bg-red-500 rounded"></div>
      <div id="item-4" class="absolute top-48 left-12 w-24 h-24 bg-purple-500 rounded"></div>
      <div id="item-5" class="absolute top-48 left-48 w-24 h-24 bg-yellow-500 rounded"></div>
      <div id="item-6" class="absolute top-48 left-84 w-24 h-24 bg-pink-500 rounded"></div>
    </ef-canvas>
  </ef-pan-zoom>
</div>
```

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

### Full Editor Workbench Setup (HTML)

Source: https://editframe.com/skills/editor-gui

This snippet configures a complete video editor using the `ef-workbench` component. It utilizes named slots to arrange various editing panels like canvas, hierarchy, and timeline, simplifying layout management.

```html
<ef-workbench class="w-full h-screen">
  <ef-pan-zoom slot="canvas">
    <ef-fit-scale>
      <ef-timegroup mode="sequence" class="w-[1920px] h-[1080px]">
        <!-- composition -->
      </ef-timegroup>
    </ef-fit-scale>
  </ef-pan-zoom>

  <ef-hierarchy slot="hierarchy"></ef-hierarchy>

  <div slot="timeline" class="h-full flex flex-col">
    <ef-controls class="flex items-center gap-2 p-2">
      <ef-toggle-play></ef-toggle-play>
      <ef-time-display></ef-time-display>
      <ef-scrubber class="flex-1"></ef-scrubber>
    </ef-controls>
    <ef-filmstrip class="flex-1"></ef-filmstrip>
  </div>
</ef-workbench>
```

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

### Process Editframe Webhook Events (TypeScript)

Source: https://editframe.com/skills/webhooks/getting-started

Handles incoming webhook events from Editframe based on their topic. It logs details for 'render.completed', 'render.failed', and 'file.ready' events, and includes logic to download completed renders. This function expects a WebhookEvent object as input.

```typescript
async function processWebhookEvent(event: WebhookEvent) {
  const { topic, data } = event;

  switch (topic) {
    case "render.completed":
      console.log(`Render ${data.id} completed`);
      console.log(`Download URL: ${data.download_url}`);
      console.log(`Duration: ${data.duration_ms}ms`);
      console.log(`Size: ${data.byte_size} bytes`);

      // Download the render
      const response = await fetch(data.download_url);
      const videoBuffer = await response.arrayBuffer();
      // ... save or process video
      break;

    case "render.failed":
      console.error(`Render ${data.id} failed`);
      // ... notify user or retry
      break;

    case "file.ready":
      console.log(`File ${data.id} is ready`);
      // ... use file in composition
      break;

    default:
      console.log(`Unhandled webhook topic: ${topic}`);
  }
}
```

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

### Basic Usage: Track Element with Overlay (HTML)

Source: https://editframe.com/skills/editor-gui/overlay-item

Demonstrates how to use ef-overlay-item to track a target element and display an overlay with custom content. It requires an ef-overlay-layer to manage the overlays.

```html
<div class="relative w-[600px] h-[400px] border border-gray-300 rounded overflow-hidden">
  <ef-overlay-layer class="absolute inset-0 pointer-events-none">
    <ef-overlay-item target="#box-1" class="border-2 border-blue-500 pointer-events-auto">
      <div class="absolute -top-6 left-0 bg-blue-500 text-white text-xs px-2 py-1 rounded whitespace-nowrap">
        Selected Box
      </div>
    </ef-overlay-item>
  </ef-overlay-layer>

  <div id="box-1" class="absolute top-12 left-12 w-40 h-32 bg-blue-100 border-2 border-blue-300 rounded"></div>
  <div id="box-2" class="absolute top-48 left-48 w-40 h-32 bg-green-100 border-2 border-green-300 rounded"></div>
</div>
```

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

### Verify Webhook Signature (TypeScript)

Source: https://editframe.com/skills/webhooks/getting-started

Provides a utility function `verifyWebhookSignature` that uses Node.js's `crypto` module to validate the HMAC-SHA256 signature of incoming webhooks. It compares the computed signature with the one provided in the `X-Webhook-Signature` header using a timing-safe comparison.

```typescript
import crypto from "node:crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post("/webhooks/editframe", async (req, res) => {
  const signature = req.headers["x-webhook-signature"] as string;
  const payload = JSON.stringify(req.body);
  const secret = process.env.EDITFRAME_WEBHOOK_SECRET!;

  if (!verifyWebhookSignature(payload, signature, secret)) {
    console.error("Invalid webhook signature");
    return res.status(401).send("Invalid signature");
  }

  // Signature is valid - process event
  const { topic, data } = req.body;
  console.log(`Verified webhook: ${topic}`);

  res.status(200).send("OK");
});
```

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

### Basic ef-waveform Usage

Source: https://editframe.com/skills/composition/waveform

Demonstrates the fundamental setup for an ef-waveform component, linking it to an ef-audio source. It requires an ef-audio element with a specified 'src' and 'fft-size', and an ef-waveform element targeting the audio element.

```html
<ef-audio id="audio" fft-size="256" src="music.mp3"></ef-audio>
<ef-waveform target="audio" mode="bars" class="text-green-400 w-3/4 h-32"></ef-waveform>
```