caption-utils

1import {
2  createTikTokStyleCaptions,
3  type Caption,
4  type TikTokPage,
5} from "@remotion/captions";
6import { interpolate } from "remotion";
7import { EASING } from "./motion-tokens";
8 
9export const DEFAULT_CAPTION_PAGE_MS = 1200;
10 
11export function groupCaptionsIntoPages(
12  captions: Caption[],
13  combineTokensWithinMilliseconds = DEFAULT_CAPTION_PAGE_MS,
14): TikTokPage[] {
15  const { pages } = createTikTokStyleCaptions({
16    captions,
17    combineTokensWithinMilliseconds,
18  });
19  return pages;
20}
21 
22/** Absolute composition time for the current sequence frame. */
23export function getAbsoluteTimeMs(page: TikTokPage, frame: number, fps: number) {
24  const relativeMs = (frame / fps) * 1000;
25  return page.startMs + relativeMs;
26}
27 
28export function isTokenActive(
29  token: { fromMs: number; toMs: number },
30  absoluteTimeMs: number,
31) {
32  return token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs;
33}
34 
35/** Token timing relative to the page sequence start (required inside `<Sequence from={...}>`). */
36export function getTokenRelativeFrames(
37  token: { fromMs: number; toMs: number },
38  page: TikTokPage,
39  fps: number,
40) {
41  const startFrame = Math.round(((token.fromMs - page.startMs) / 1000) * fps);
42  const endFrame = Math.round(((token.toMs - page.startMs) / 1000) * fps);
43  return { startFrame, endFrame };
44}
45 
46export function getTokenEmphasis(
47  frame: number,
48  token: { fromMs: number; toMs: number },
49  page: TikTokPage,
50  fps: number,
51  options?: { enterFrames?: number; exitFrames?: number },
52) {
53  // A word holds for 200-800ms, so emphasis has to arrive fast and release
54  // slower — a symmetric ramp reads as a flicker on short tokens.
55  const enterFrames = options?.enterFrames ?? 4;
56  const exitFrames = options?.exitFrames ?? 9;
57  const { startFrame, endFrame } = getTokenRelativeFrames(token, page, fps);
58  const absoluteTimeMs = getAbsoluteTimeMs(page, frame, fps);
59  const active = isTokenActive(token, absoluteTimeMs);
60 
61  const enter = interpolate(
62    frame,
63    [startFrame, startFrame + enterFrames],
64    [0, 1],
65    {
66      extrapolateLeft: "clamp",
67      extrapolateRight: "clamp",
68      easing: EASING.enter,
69    },
70  );
71 
72  // Releasing emphasis is a settle, not an exit — accelerating away would snap
73  // the word back to its resting size.
74  const exit = interpolate(
75    frame,
76    [endFrame, endFrame + exitFrames],
77    [1, 0],
78    {
79      extrapolateLeft: "clamp",
80      extrapolateRight: "clamp",
81      easing: EASING.editorial,
82    },
83  );
84 
85  if (active) {
86// … truncated