2026-11-20 · 6 min read

How to Add Captions to Videos in Remotion

A film strip of programmatic video scenes, the middle frame showing the captioned word REMOTION
This image was generated with AI.

Remotion makes video a React render, so captions look easy: map a transcript to timed Text components and they are part of the output. That works well when you already have exact word timings. When you only have narration audio, the timing problem is the whole job, and an API that transcribes, times, and styles captions is the shorter path.

Option 1: captions inside the Remotion render

If you have a timed transcript, drive text with useCurrentFrame and interpolate. You control every pixel and the captions render with the video in one pass. The catch: you need word or line timings from somewhere, you own wrapping and safe-zone logic, and restyling means re-rendering. For voiceover-first content, the timings are the expensive part.

Option 2: caption the rendered MP4 with an API

The other path keeps Remotion doing what it is good at (the visuals) and treats captioning as a post step on the finished file. Render the MP4, hand it to caption.sh, get a captioned file back. One POST starts the job:

const res = await fetch("https://api.caption.sh/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAPTION_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source_url: renderedVideoUrl,
    options: { position: "bottom", max_words: 4 },
  }),
});
const { job_id } = await res.json();

Poll until the job finishes. Statuses are queued, awaiting_upload, running, done, error; add a timeout alongside the two terminal states.

const deadline = Date.now() + 10 * 60 * 1000;
let status = "queued";
while (status !== "done") {
  if (Date.now() > deadline) throw new Error("timed out");
  await new Promise((r) => setTimeout(r, 5000));
  const r = await fetch(`https://api.caption.sh/v1/jobs/${job_id}`, {
    headers: { Authorization: `Bearer ${process.env.CAPTION_API_KEY}` },
  });
  status = (await r.json()).status;
  if (status === "error") throw new Error("captioning failed");
}

The result endpoint redirects to the finished file, so read the Location header instead of following redirects. Results are stored for 24 hours, then deleted.

const result = await fetch(
  `https://api.caption.sh/v1/jobs/${job_id}/result`,
  {
    headers: { Authorization: `Bearer ${process.env.CAPTION_API_KEY}` },
    redirect: "manual",
  }
);
const fileUrl = result.headers.get("Location");

Which path when

  • Programmatic videos with known script timings (data-driven clips, templated ads): in-render captions are precise and free.
  • Voiceover or recorded audio where timings are unknown: the API path saves you building transcription and timing.
  • Cost: $0.10 per minute of video, prepaid; up to 10 minutes per job, so split long renders into segments.
  • A 429 means the transcription throughput ceiling: wait and retry.
  • Burned-in captions cannot be toggled or resized. If the destination player supports caption tracks, keep those enabled too.

Back to all articles