Skip to main content

createTikTokStyleCaptions()v4.0.216

Using this function, you can segment tokens to create "pages" of captions, as commonly seen on TikTok videos.

You may specify how often pages switch. A high value for combineTokensWithinMilliseconds will fit many words on 1 page, while a low value will lead to word-by-word animation.

This function is safe to use in the browser, Node.js and Bun.

note

This API expects the whitespace to be included in the text field before each word. Spaces are used as delimiters, and omitting them will cause the entire text to merge into a single line or page, resulting in poorly formatted captions..

Create pages from captions
import {createTikTokStyleCaptions, Caption} from '@remotion/captions';

const captions: Caption[] = [
  {
    text: 'Using',
    startMs: 40,
    endMs: 300,
    timestampMs: 200,
    confidence: null,
  },
  {
    text: " Remotion's",
    startMs: 300,
    endMs: 900,
    timestampMs: 440,
    confidence: null,
  },
  {
    text: ' TikTok',
    startMs: 900,
    endMs: 1260,
    timestampMs: 1080,
    confidence: null,
  },
  {
    text: ' template,',
    startMs: 1260,
    endMs: 1950,
    timestampMs: 1600,
    confidence: null,
  },
];

const {pages} = createTikTokStyleCaptions({
  captions,
  combineTokensWithinMilliseconds: 1200,
});

/* pages: [
  {
    text: "Using Remotion's",
    startMs: 40,
    durationMs: 860,
    tokens: [
      {
        text: 'Using',
        fromMs: 40,
        toMs: 300,
      },
      {
        text: " Remotion's",
        fromMs: 300,
        toMs: 900,
      },
    ],
  },
  {
    text: 'TikTok template,',
    startMs: 900,
    durationMs: 1050,
    tokens: [
      {
        text: 'TikTok',
        fromMs: 900,
        toMs: 1260,
      },
      {
        text: ' template,',
        fromMs: 1260,
        toMs: 1950,
      },
    ],
  }
] */

API​

captions​

An array of Caption objects.

combineTokensWithinMilliseconds​

Controls how long captions are combined into a page. Once the current page's duration exceeds this value, the next caption that starts with a space begins a new page.

breakOnSilenceAfterMilliseconds?v4.0.514​

number

If set, a gap of at least this many milliseconds between the end of one caption and the start of the next begins a new page, even if combineTokensWithinMilliseconds has not been exceeded yet. By default, gaps do not cause an early page break.

This compares caption timestamps and does not analyze the audio track.

As with all page breaks, the previous page's durationMs extends until the next page starts, so the caption stays on screen through the pause.

A value of 0 starts a new page at every word boundary, resulting in word-by-word pages.

This option only adds earlier page breaks: combineTokensWithinMilliseconds remains the upper bound, and pages can only get shorter, never longer.

Return value​

An object with the following properties:

pages​

An array of TikTokPage objects.

A page consists of:

  • text: The text of the page.
  • startMs: The start time of the page in milliseconds.
  • durationMs: The duration of the page in milliseconds (from v4.0.261).
  • tokens: An array of objects, if you want to animate word-per-word:
    • text: The text of the token.
    • fromMs: The absolute start time of the token in milliseconds.
    • toMs: The absolute end time of the token in milliseconds.

Whitespace sensitivity​

The text field is whitespace sensitive. You should include spaces in it, ideally before each word.

While rendering, apply the white-space: pre CSS property to the container of the caption to ensure that the spaces are preserved.

See also​