Caption Files

Upload and manage subtitle files in WebVTT or SRT format.

Captions use the unified files API with type: "caption". They are ready immediately after upload (no processing step).

Upload Captions

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

const captionStats = await stat("subtitles.vtt");

const captionFile = await createFile(client, {
  filename: "subtitles.vtt",
  type: "caption",
  byte_size: captionStats.size,
});

const captionStream = createReadStream("subtitles.vtt");

for await (const event of uploadFile(
  client,
  { id: captionFile.id, byte_size: captionStats.size, type: "caption" },
  captionStream
)) {
  if (event.type === "progress") {
    console.log(`Upload: ${event.progress.toFixed(1)}%`);
  }
}

Supported formats: WebVTT (.vtt), SRT (.srt). Maximum size: 2MB.

Deduplication

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

const existing = await lookupFileByMd5(client, "caption-md5-hash");

if (existing && existing.status === "ready") {
  console.log("Captions already uploaded");
} else {
  // Upload new captions
}

Using in Compositions

Use <ef-captions> with target to display captions from a video's transcription, or provide a standalone caption file:

<ef-configuration api-host="https://editframe.com">
  <ef-timegroup mode="contain" class="w-[1920px] h-[1080px]">
    <ef-video file-id="${videoFile.id}"></ef-video>
    <ef-captions
      target="ef-video"
      class="absolute bottom-10 left-10 right-10 text-white text-4xl text-center">
    </ef-captions>
  </ef-timegroup>
</ef-configuration>

See files.md for the complete files API reference.