Video Files

Upload video files with automatic processing to streamable ISOBMFF format.

Video files use the unified files API with type: "video". After upload, they are automatically processed to ISOBMFF format.

Upload and Process

import { createFile, uploadFile, getFileProcessingProgress } from "@editframe/api";
import { createReadStream } from "node:fs";
import { stat } from "node:fs/promises";

const fileStats = await stat("video.mp4");

// 1. Create file record
const file = await createFile(client, {
  filename: "video.mp4",
  type: "video",
  byte_size: fileStats.size,
  md5: "optional-md5-hash",
});

// 2. Upload content
const fileStream = createReadStream("video.mp4");

for await (const event of uploadFile(
  client,
  { id: file.id, byte_size: fileStats.size, type: "video" },
  fileStream
)) {
  if (event.type === "progress") {
    console.log(`Upload: ${event.progress.toFixed(1)}%`);
  }
}

// 3. Wait for processing (automatic after upload)
for await (const event of await getFileProcessingProgress(client, file.id)) {
  if (event.type === "progress") {
    console.log(`Processing: ${event.progress.toFixed(1)}%`);
  } else if (event.type === "complete") {
    console.log("Ready");
    break;
  }
}

Processing converts the raw file to ISOBMFF format, enabling:

• Frame-accurate seeking
• Adaptive bitrate streaming
• Efficient composition rendering

Maximum file size: 1GB.

Get Video Details

After processing, retrieve track information:

import { getFileDetail } from "@editframe/api";

const detail = await getFileDetail(client, file.id);

console.log(detail.status);  // "ready"
console.log(detail.width);   // 1920
console.log(detail.height);  // 1080

if (detail.tracks) {
  for (const track of detail.tracks) {
    console.log(`Track ${track.track_id}: ${track.type} ${track.codec_name} (${track.duration_ms}ms)`);
  }
}

Using in Compositions

Reference videos by their file-id:

<ef-configuration api-host="https://editframe.com">
  <ef-timegroup mode="contain" class="w-[1920px] h-[1080px]">
    <ef-video
      file-id="${file.id}"
      class="size-full object-contain">
    </ef-video>
  </ef-timegroup>
</ef-configuration>

The file-id is a stable UUID that remains the same from creation through processing and playback.

See files.md for the complete files API reference and media-pipeline.md for the end-to-end workflow.