1---
2name: display-captions
3description: Displaying captions in Remotion with TikTok-style pages and word highlighting
4metadata:
5  tags: captions, subtitles, display, tiktok, highlight
6---
7 
8# Displaying captions in Remotion
9 
10This guide explains how to display captions in Remotion, assuming you already have captions in the [`Caption`](https://www.remotion.dev/docs/captions/caption) format.
11 
12## Prerequisites
13 
14Read [Transcribing audio](transcribe-captions.md) for how to generate captions.
15 
16First, the [`@remotion/captions`](https://www.remotion.dev/docs/captions) package needs to be installed.
17If it is not installed, use the following command:
18 
19```bash
20npx remotion add @remotion/captions
21```
22 
23## Fetching captions
24 
25First, fetch your captions JSON file. Use [`useDelayRender()`](https://www.remotion.dev/docs/use-delay-render) to hold the render until the captions are loaded:
26 
27```tsx
28import { useState, useEffect, useCallback } from "react";
29import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
30import type { Caption } from "@remotion/captions";
31 
32export const MyComponent: React.FC = () => {
33  const [captions, setCaptions] = useState<Caption[] | null>(null);
34  const { delayRender, continueRender, cancelRender } = useDelayRender();
35  const [handle] = useState(() => delayRender());
36 
37  const fetchCaptions = useCallback(async () => {
38    try {
39      // Assuming captions.json is in the public/ folder.
40      const response = await fetch(staticFile("captions123.json"));
41      const data = await response.json();
42      setCaptions(data);
43      continueRender(handle);
44    } catch (e) {
45      cancelRender(e);
46    }
47  }, [continueRender, cancelRender, handle]);
48 
49  useEffect(() => {
50    fetchCaptions();
51  }, [fetchCaptions]);
52 
53  if (!captions) {
54    return null;
55  }
56 
57  return <AbsoluteFill>{/* Render captions here */}</AbsoluteFill>;
58};
59```
60 
61## Creating pages
62 
63Use `createTikTokStyleCaptions()` to group captions into pages. The `combineTokensWithinMilliseconds` option controls how many words appear at once:
64 
65```tsx
66import { useMemo } from "react";
67import { createTikTokStyleCaptions } from "@remotion/captions";
68import type { Caption } from "@remotion/captions";
69 
70// How often captions should switch (in milliseconds)
71// Higher values = more words per page
72// Lower values = fewer words (more word-by-word)
73const SWITCH_CAPTIONS_EVERY_MS = 1200;
74 
75const { pages } = useMemo(() => {
76  return createTikTokStyleCaptions({
77    captions,
78    combineTokensWithinMilliseconds: SWITCH_CAPTIONS_EVERY_MS,
79  });
80}, [captions]);
81```
82 
83## Rendering with Sequences
84 
85Map over the pages and render each one in a `<Sequence>`. Calculate the start frame and duration from the page timing:
86 
87```tsx
88import { Sequence, useVideoConfig, AbsoluteFill } from "remotion";
89import type { TikTokPage } from "@remotion/captions";
90 
91const CaptionedContent: React.FC = () => {
92  const { fps } = useVideoConfig();
93 
94  return (
95    <AbsoluteFill>
96      {pages.map((page, index) => {
97        const nextPage = pages[index + 1] ?? null;
98        const startFrame = (page.startMs / 1000) * fps;
99        const endFrame = Math.min(
100          nextPage ? (nextPage.startMs / 1000) * fps : Infinity,
101          startFrame + (SWITCH_CAPTIONS_EVERY_MS / 1000) * fps,
102        );
103        const durationInFrames = endFrame - startFrame;
104 
105        if (durationInFrames <= 0) {
106          return null;
107        }
108 
109        return (
110          <Sequence
111            key={index}
112            from={startFrame}
113            durationInFrames={durationInFrames}
114          >
115            <CaptionPage page={page} />
116          </Sequence>
117        );
118      })}
119    </AbsoluteFill>
120  );
121};
122```
123 
124## White-space preservation
125 
126The captions are whitespace sensitive. You should include spaces in the `text` field before each word. Use `whiteSpace: "pre"` to preserve the whitespace in the captions.
127 
128## Separate component for captions
129 
130Put captioning logic in a separate component.  
131Make a new file for it.
132 
133## Word highlighting
134 
135A caption page contains `tokens` which you can use to highlight the currently spoken word:
136 
137```tsx
138import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
139import type { TikTokPage } from "@remotion/captions";
140 
141const HIGHLIGHT_COLOR = "#39E508";
142 
143const CaptionPage: React.FC<{ page: TikTokPage }> = ({ page }) => {
144  const frame = useCurrentFrame();
145  const { fps } = useVideoConfig();
146 
147  // Current time relative to the start of the sequence
148  const currentTimeMs = (frame / fps) * 1000;
149  // Convert to absolute time by adding the page start
150  const absoluteTimeMs = page.startMs + currentTimeMs;
151 
152  return (
153    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
154      <div style={{ fontSize: 80, fontWeight: "bold", whiteSpace: "pre" }}>
155        {page.tokens.map((token) => {
156          const isActive =
157            token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs;
158 
159          return (
160            <span
161              key={token.fromMs}
162              style={{ color: isActive ? HIGHLIGHT_COLOR : "white" }}
163            >
164              {token.text}
165            </span>
166          );
167        })}
168      </div>
169    </AbsoluteFill>
170  );
171};
172```
173 
174## Display captions alongside video content
175 
176By default, put the captions alongside the video content, so the captions are in sync.  
177For each video, make a new captions JSON file.
178 
179```tsx
180<AbsoluteFill>
181  <Video src={staticFile("video.mp4")} />
182  <CaptionPage page={page} />
183</AbsoluteFill>
184```
185