# captions.js documentation (full)

> All captions.js guide and API reference pages in one file. Index: https://captionsjs.dev/llms.txt

## Introduction

> Welcome to the captions.js developer documentation. Use the sidebar to explore the full API reference and learn how to embed animated captions into your video workflow.

```ts
import captionsjs, { stylePresets } from "captions.js";

const instance = captionsjs({
  video: document.querySelector("video")!,
  preset: stylePresets[0],
  captions: [
    { word: "Hello", startTime: 0, endTime: 0.4 },
    { word: "world", startTime: 0.4, endTime: 0.9 },
  ],
});

instance.enable();
```

Source: https://captionsjs.dev/docs

---

## Docker Render Service

`maskin25/captions.js-render` is a ready-to-run container that burns captions onto a video using the **captions.js** renderer plus ffmpeg. This page shows how to pull the image, feed it your assets, and customize the render through CLI flags.

## 1. Pull the image

```bash
docker pull maskin25/captions.js-render:latest
```

Tags follow the npm package version (`0.1.0`, `0.2.0`, …). Use a fixed tag in production.

## 2. Provide inputs

The container expects:

| Flag                              | Description                                                                                                          | Example                           |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `--preset <name>`                 | Name of the captions style preset (e.g. `Lovly`, `From`). See the [stylePresets](/docs/api/type-aliases/StylePresetName). | `--preset Lovly`                  |
| `--video <path or URL>`           | Source video file. Supports `@/path` for mounted files or full HTTP(S) URLs.                                         | `--video @/data/margo.mp4`        |
| `--captions <path, JSON, or URL>` | Captions payload. Accepts JSON string, mounted file, or remote URL.                                                  | `--captions @/data/margo-dg.json` |
| `--output <path>`                 | Where to save the rendered video inside the container. Defaults to `/app/output.mp4`.                                | `--output @/data/output.mp4`      |
| `--rootDir <path>`                | Convenience flag: if set, any argument starting with `@/` will be resolved relative to this directory.               | `--rootDir /data`                 |

All paths that start with `@/` are interpreted relative to the bind mount supplied via `-v`. This lets you keep videos/captions on the host.

## 3. Typical local run

```bash
docker run --rm \
  -v /absolute/path/to/assets:/data \
  maskin25/captions.js-render:latest \
  burnCaptions \
    --preset Lovly \
    --rootDir /data \
    --video @/video.mp4 \
    --captions @/captions.json \
    --output @/output.mp4
```

- `/absolute/path/to/assets` must contain both `video.mp4` and `captions.json`.
- The resulting `output.mp4` is written back into the same host folder.

## 4. Remote assets

The CLI can download files directly:

```bash
docker run --rm maskin25/captions.js-render \
  burnCaptions \
    --preset From \
    --rootDir /data \
    --video https://<path-to-video> \
    --captions https://<path-to-captions> \
    --output /app/output.mp4
```

After the run, copy the result out with `docker cp <container>:/app/output.mp4 ./output.mp4` or mount a host directory via `-v` so the file lands on disk automatically.

Source: https://captionsjs.dev/docs/server

---

## captions.js vs Remotion, ASS/libass and FFmpeg drawtext

> How the common ways to render animated captions compare: live preview, server-side burn-in, headless browser, word-level animation.

Most caption tools make you choose between a good **live preview** and a reliable
**server-side export**. This page compares the usual options on the points that decide
which one fits.

| | captions.js | `@remotion/captions` | Remotion (full render) | ASS / libass | FFmpeg `drawtext` |
| --- | --- | --- | --- | --- | --- |
| Live preview over `<video>` | yes | no renderer | yes, React player | depends on the player | no |
| Server-side burn-in | yes, Node + FFmpeg | no | yes | yes | yes |
| Headless Chrome in production | not needed | n/a | required | not needed | not needed |
| Word-level highlighting | yes | timing data only | build it yourself | karaoke tags only | no |
| Kinetic word animations (bounce, pop, box…) | yes, 10 built in | no | build it yourself | no | no |
| Preview and export share one code path | yes | n/a | yes, through Chrome | n/a | n/a |
| Ready-made styles | 26 presets | none | templates | write them by hand | none |
| License | MIT | Remotion license | Remotion license | open source | LGPL/GPL (FFmpeg) |

## When to use which

- **captions.js**: you show captions to users in a browser editor or player **and** export
  MP4s on a server, and the two must look identical. The same `renderFrame` draws on a canvas
  in both places, with skia-canvas + FFmpeg on the server and no browser.
- **Remotion**: your whole video is a React composition (titles, scenes, transitions),
  and you are fine running headless Chrome to render it. `@remotion/captions` parses and
  groups transcripts; it does not draw anything, so you still build the caption visuals.
- **ASS / libass**: classic subtitles, broad player support and fast burn-in, as long as you
  only need static lines or simple karaoke color changes.
- **FFmpeg `drawtext`**: a single static line or a watermark. Word-by-word animation means
  generating and escaping a filter per word, which gets unmanageable fast.

## Licensing note

Remotion uses its own license: free for individuals and small teams, paid for companies
above a size threshold. Check their current terms. captions.js is MIT and stays MIT, free
for commercial use.

## Try it

```bash
npx captions.js burn talk.mp4 words.json --preset Karaoke
```

Then see [Animated captions with FFmpeg in Node.js](/docs/guides/ffmpeg-animated-captions-nodejs)
and the [styles gallery](/styles).

Source: https://captionsjs.dev/docs/guides/captions-js-vs-remotion-ass-drawtext

---

## Animated captions from Deepgram transcripts

> Feed a Deepgram pre-recorded response straight into captions.js: word timings, sentences and paragraphs, rendered as animated captions.

captions.js reads a Deepgram pre-recorded transcription response as is. `toCaptions()`
detects it and returns timed words; `getParagraphs()` returns the paragraph structure when
Deepgram provides it.

## 1. Transcribe with Deepgram

Ask for word timings with punctuation and paragraphs:

```bash
curl -X POST "https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true&paragraphs=true" \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H "Content-Type: video/mp4" \
  --data-binary @talk.mp4 \
  -o deepgram.json
```

Keep the API key on your server; never ship it to the browser.

## 2. Render in the browser

```ts
import captionsjs, { getPreset, toCaptions } from "captions.js";

const response = await fetch("/deepgram.json").then((r) => r.json());

captionsjs({
  video: document.querySelector("video")!,
  preset: getPreset("Focus Box"),
  captions: toCaptions(response), // Deepgram response → [{ word, startTime, endTime, … }]
});
```

## 3. Or burn it into an MP4

```bash
npx captions.js burn talk.mp4 deepgram.json --preset "Focus Box"
```

The server package accepts the same Deepgram file. Options and Docker usage:
[Animated captions with FFmpeg in Node.js](/docs/guides/ffmpeg-animated-captions-nodejs).

## Notes

- `smart_format=true` gives you punctuated words, which read better on screen.
- Other providers (AssemblyAI, ElevenLabs, Gladia…) work too: map their words to
  `{ word, startTime, endTime }` in seconds, the same way as in the
  [Whisper guide](/docs/guides/whisper-animated-captions).

Source: https://captionsjs.dev/docs/guides/deepgram-animated-captions

---

## Animated captions with FFmpeg in Node.js

> Burn word-by-word animated captions into an MP4 from Node.js: no headless browser, no ASS files, the same renderer as the browser preview.

`@captionsjs/server` draws captions.js frames with skia-canvas and pipes them straight
into FFmpeg. You get the kinetic, word-level captions people know from TikTok and Reels,
rendered on your server, with output that matches the browser preview frame for frame.

## Why not drawtext or ASS?

| | captions.js | FFmpeg `drawtext` | ASS / libass |
| --- | --- | --- | --- |
| Word-by-word highlight | yes | build it from many filters | karaoke tags only |
| Per-word scale, bounce, box animations | yes | no | no |
| Same look as a live browser preview | yes, same `renderFrame` | no | depends on the player |
| Headless Chrome needed | no | no | no |

## Install

```bash
npm install @captionsjs/server
```

You need `ffmpeg` and `ffprobe` on `PATH` (or point `FFMPEG_PATH` / `FFPROBE_PATH` at them).
On macOS: `brew install ffmpeg`. On Debian/Ubuntu: `apt-get install ffmpeg`.

## Burn captions

```ts
import { burnCaptions } from "@captionsjs/server";

const result = await burnCaptions({
  video: "talk.mp4",            // path or http(s) URL
  captions: "words.json",       // path, URL, JSON string or parsed array
  preset: "Focus Box",          // any preset name, case-insensitive
  output: "talk.captions.mp4",  // default: <input>.captions.mp4
  onProgress: ({ frame, totalFrames }) =>
    process.stdout.write(`\r${Math.round((frame / totalFrames) * 100)}%`),
});

console.log(result); // { output, frames, width, height, fps, durationSec }
```

`captions` accepts plain `[{ word, start, end }]` (or `startTime` / `endTime`), OpenAI
Whisper `verbose_json` and Deepgram responses. See
[Animated captions from Whisper](/docs/guides/whisper-animated-captions) for getting word timings.

## Options

| Option | Default | What it does |
| --- | --- | --- |
| `preset` | `"Karaoke"` | Preset name or a full preset object (clone one with `getPreset()` and edit it) |
| `fps` | source fps | Frame rate of the caption overlay |
| `crf` | `20` | x264 quality, lower is better and bigger |
| `x264Preset` | `"veryfast"` | x264 speed/size trade-off |
| `scale` | `height / 480` | Font-size multiplier; the browser overlay uses the same rule |
| `fonts.fontsDir` | none | Folder with TTFs in Google Fonts layout, searched first |
| `fonts.download` | `true` | Set `false` to fail instead of downloading missing fonts |

Preset fonts are downloaded from Google Fonts on first use and cached in
`~/.cache/captionsjs/fonts` (set `CAPTIONSJS_CACHE_DIR` to move it).

## Custom styles

A preset is a plain object, so brand it in code and pass it in:

```ts
import { getPreset } from "captions.js";
import { burnCaptions } from "@captionsjs/server";

const base = getPreset("Karaoke");
const branded = {
  ...base,
  captionsSettings: {
    ...base.captionsSettings,
    style: { ...base.captionsSettings.style, highlightColor: "#ff2e88" },
  },
};

await burnCaptions({ video: "talk.mp4", captions: "words.json", preset: branded });
```

## Without writing code

```bash
npx captions.js burn talk.mp4 words.json --preset Karaoke -o out.mp4
npx captions.js presets   # list every preset name
```

Or run the Docker image, which has FFmpeg and every preset font baked in and works offline:

```bash
docker run --rm -v "$PWD:/data" maskin25/captions.js-render \
  burn /data/talk.mp4 /data/words.json --preset Karaoke -o /data/out.mp4
```

More on the image in [Docker Render Service](/docs/server).

## Rather not run it yourself?

[captions.js Cloud](/cloud) is the same renderer as a hosted API: send a video URL, get the
captioned MP4 back by webhook. It's in early access; founding members get free render minutes.

Source: https://captionsjs.dev/docs/guides/ffmpeg-animated-captions-nodejs

---

## Word-by-word captions in React and Next.js

> Add TikTok-style animated captions over a video in a React or Next.js app: a small component around captions.js, with live preset switching.

captions.js draws captions on a canvas layered over your `<video>`. In React that is one
effect: create the overlay when the video mounts, update it when props change, destroy it
on unmount.

## Install

```bash
npm install captions.js
```

## A `<CaptionedVideo>` component

```tsx
"use client"; // Next.js App Router: the overlay needs the DOM

import { useEffect, useRef } from "react";
import type { Caption, CaptionsInstance, StylePresetName } from "captions.js";

type Props = {
  src: string;
  captions: Caption[];
  preset?: StylePresetName;
};

export function CaptionedVideo({ src, captions, preset = "Karaoke" }: Props) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const instanceRef = useRef<CaptionsInstance | null>(null);

  // Create once. The import runs in the browser only, so SSR never loads canvas code.
  useEffect(() => {
    let cancelled = false;
    import("captions.js").then(({ default: captionsjs, getPreset }) => {
      if (cancelled || !videoRef.current) return;
      instanceRef.current = captionsjs({
        video: videoRef.current,
        preset: getPreset(preset),
        captions,
      });
    });
    return () => {
      cancelled = true;
      instanceRef.current?.destroy();
      instanceRef.current = null;
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  // Live updates, no remount.
  useEffect(() => {
    import("captions.js").then(({ getPreset }) => instanceRef.current?.preset(getPreset(preset)));
  }, [preset]);

  useEffect(() => {
    instanceRef.current?.captions(captions);
  }, [captions]);

  return (
    <div style={{ position: "relative" }}>
      <video ref={videoRef} src={src} controls playsInline style={{ width: "100%" }} />
    </div>
  );
}
```

Use it with word timings from any speech-to-text service:

```tsx
<CaptionedVideo src="/talk.mp4" captions={words} preset="Focus Box" />
```

`words` is an array of `{ word, startTime, endTime }` in seconds. For a Deepgram response
call `toCaptions(response)`; for Whisper see
[Animated captions from Whisper](/docs/guides/whisper-animated-captions).

## Notes

- **Positioning:** the overlay sits on top of the video and resizes with it. Keep the
  `<video>` inside a positioned wrapper as above.
- **Style picker:** `presetNames` lists every preset, handy for a `<select>`. Each name
  has a preview in the [styles gallery](/styles).
- **Same look on export:** the server package renders with the same `renderFrame`, so what
  users pick in your UI is exactly what `burnCaptions()` writes to the MP4. See
  [Animated captions with FFmpeg in Node.js](/docs/guides/ffmpeg-animated-captions-nodejs).

Source: https://captionsjs.dev/docs/guides/react-word-by-word-captions

---

## Animated captions from Whisper word timestamps

> Turn OpenAI Whisper, faster-whisper or the Whisper API output into word-by-word animated captions, in the browser and burned into an MP4.

Whisper gives you **when each word was spoken**. captions.js turns those timings into
animated, word-by-word captions: live over a `<video>` in the browser, or burned into
an MP4 with FFmpeg. Both paths use the same renderer, so the preview and the export match.

## 1. Get word-level timestamps

Captions need a start and end time **per word**, not per segment. Turn word timestamps on:

**OpenAI API** (`whisper-1`): ask for `verbose_json` with word granularity. The words
come back in a top-level `words` array.

```ts
import OpenAI from "openai";
import fs from "node:fs";

const openai = new OpenAI();
const transcript = await openai.audio.transcriptions.create({
  file: fs.createReadStream("talk.mp4"),
  model: "whisper-1",
  response_format: "verbose_json",
  timestamp_granularities: ["word"],
});

fs.writeFileSync("words.json", JSON.stringify(transcript));
// transcript.words → [{ word: "Hello", start: 0.12, end: 0.48 }, …]
```

**openai-whisper** (Python): pass `word_timestamps=True`. The words sit inside
`segments[].words`.

```python
import json, whisper

model = whisper.load_model("small")
result = model.transcribe("talk.mp4", word_timestamps=True)
json.dump(result, open("words.json", "w"))
```

**faster-whisper**: also `word_timestamps=True`; collect the words yourself:

```python
from faster_whisper import WhisperModel
import json

segments, _ = WhisperModel("small").transcribe("talk.mp4", word_timestamps=True)
words = [{"word": w.word.strip(), "start": w.start, "end": w.end}
         for s in segments for w in s.words]
json.dump(words, open("words.json", "w"))
```

## 2. Burn the captions into the video

The server package reads all three shapes above as they are: a top-level `words`
array, `segments[].words`, or a plain `[{ word, start, end }]` list.

```bash
npx captions.js burn talk.mp4 words.json --preset Karaoke
# → talk.captions.mp4
```

Or from Node:

```ts
import { burnCaptions } from "@captionsjs/server";

await burnCaptions({
  video: "talk.mp4",
  captions: "words.json",
  preset: "Karaoke",
  output: "talk.captions.mp4",
});
```

Needs `ffmpeg` and `ffprobe` on `PATH`. See [Animated captions with FFmpeg in Node.js](/docs/guides/ffmpeg-animated-captions-nodejs) for every option.

## 3. Show them live in the browser

In the browser, `toCaptions()` reads a Deepgram response or an array of
`{ word, startTime, endTime }`. Map the Whisper words first:

```ts
import captionsjs, { getPreset } from "captions.js";

type WhisperWord = { word: string; start: number; end: number };

// OpenAI API: transcript.words; openai-whisper: segments.flatMap(s => s.words)
function fromWhisper(words: WhisperWord[]) {
  return words.map((w) => ({ word: w.word.trim(), startTime: w.start, endTime: w.end }));
}

const instance = captionsjs({
  video: document.querySelector("video")!,
  preset: getPreset("Karaoke"),
  captions: fromWhisper(transcript.words),
});
```

The overlay follows `video.currentTime`, so seeking, pausing and playback speed just work.
Switch the look without remounting: `instance.preset(getPreset("Focus Box"))`.

## Tips

- **Pick a style** from the [caption styles gallery](/styles): every preset name works in
  `getPreset()`, `--preset` and `burnCaptions({ preset })`.
- **Clean words first.** Whisper sometimes returns leading spaces or punctuation-only
  tokens; trim them and drop empty words before rendering.
- **Long videos:** transcribe once, save `words.json`, and reuse it for every preview and export.

Source: https://captionsjs.dev/docs/guides/whisper-animated-captions

---

## API Reference

> Every export of the captions.js package.

## Classes

- [Captions](/docs/api/classes/Captions)

## Interfaces

- [Caption](/docs/api/interfaces/Caption)
- [CaptionsSettings](/docs/api/interfaces/CaptionsSettings)
- [StylePreset](/docs/api/interfaces/StylePreset)

## Type Aliases

- [CaptionsInput](/docs/api/type-aliases/CaptionsInput)
- [CaptionsInstance](/docs/api/type-aliases/CaptionsInstance)
- [CaptionsOptions](/docs/api/type-aliases/CaptionsOptions)
- [LoadGoogleFontOptions](/docs/api/type-aliases/LoadGoogleFontOptions)
- [StylePresetName](/docs/api/type-aliases/StylePresetName)

## Variables

- [googleFontsList](/docs/api/variables/googleFontsList)
- [preloadGoogleFont](/docs/api/variables/preloadGoogleFont)
- [presetNames](/docs/api/variables/presetNames)
- [renderFrame](/docs/api/variables/renderFrame)
- [stylePresets](/docs/api/variables/stylePresets)

## Functions

- [captionsjs](/docs/api/functions/captionsjs)
- [getHighlightColor](/docs/api/functions/getHighlightColor)
- [getParagraphs](/docs/api/functions/getParagraphs)
- [getPreset](/docs/api/functions/getPreset)
- [renderString](/docs/api/functions/renderString)
- [renderStylePreset](/docs/api/functions/renderStylePreset)
- [toCaptions](/docs/api/functions/toCaptions)

## References

### default

Renames and re-exports [captionsjs](/docs/api/functions/captionsjs)

Source: https://captionsjs.dev/docs/api

---

## Captions

> Imperative controller that owns the Konva stage lifecycle for a single video element.

Imperative controller that owns the Konva stage lifecycle for a single video element.

## Constructors

### Constructor

```ts
new Captions(options): Captions;
```

Create a controller bound to the provided video element and preset.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`CaptionsOptions`](/docs/api/type-aliases/CaptionsOptions) | Complete configuration for the controller. |

#### Returns

`Captions`

## Methods

### captions()

```ts
captions(nextCaptions): void;
```

Replace the current caption track and repaint without reloading fonts.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `nextCaptions` | [`Caption`](/docs/api/interfaces/Caption)[] \| `null` | Timed words that should drive the overlay. |

#### Returns

`void`

***

### destroy()

```ts
destroy(): void;
```

Alias for [disable()](#disable) to match typical imperative controller APIs.

#### Returns

`void`

***

### disable()

```ts
disable(): void;
```

Tear down overlays, observers and animation loops to free resources.

#### Returns

`void`

***

### enable()

```ts
enable(): void;
```

Mount caption overlays onto the configured video if they are not active yet.

#### Returns

`void`

***

### getRenderCount()

```ts
getRenderCount(): number;
```

Number of times the scene has been rebuilt. Useful for diagnostics and
tests — it stays flat while the video is paused.

#### Returns

`number`

***

### isEnabled()

```ts
isEnabled(): boolean;
```

Whether the Konva overlay is currently attached to the video element.

#### Returns

`boolean`

`true` when the overlay is mounted on top of the video.

***

### preset()

```ts
preset(nextPreset): void;
```

Swap the active preset and re-render with updated typography/colors.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `nextPreset` | [`StylePreset`](/docs/api/interfaces/StylePreset) | Preset that becomes the new render baseline. |

#### Returns

`void`

Source: https://captionsjs.dev/docs/api/classes/Captions

---

## captionsjs()

> Factory mirroring the legacy default export for ergonomic imports.

```ts
function captionsjs(options): Captions;
```

Factory mirroring the legacy default export for ergonomic imports.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`CaptionsOptions`](/docs/api/type-aliases/CaptionsOptions) | Same options accepted by the [Captions](/docs/api/classes/Captions) constructor. |

## Returns

[`Captions`](/docs/api/classes/Captions)

New controller instance.

Source: https://captionsjs.dev/docs/api/functions/captionsjs

---

## getHighlightColor()

> Active-word color of a settings object, honouring the deprecated aplifiedWordColor name for settings saved before 1.10.

```ts
function getHighlightColor(captionsSettings): string;
```

Active-word color of a settings object, honouring the deprecated
`aplifiedWordColor` name for settings saved before 1.10.

## Parameters

| Parameter | Type |
| ------ | ------ |
| `captionsSettings` | [`CaptionsSettings`](/docs/api/interfaces/CaptionsSettings) |

## Returns

`string`

Source: https://captionsjs.dev/docs/api/functions/getHighlightColor

---

## getParagraphs()

```ts
function getParagraphs(input): DeepgramParagraph[] | null;
```

## Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | `unknown` |

## Returns

`DeepgramParagraph`[] \| `null`

Source: https://captionsjs.dev/docs/api/functions/getParagraphs

---

## getPreset()

> Predefined caption appearance presets and their strong typings.

Predefined caption appearance presets and their strong typings.

## Call Signature

```ts
function getPreset(name): StylePreset;
```

Looks up a built-in preset by name.

### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | [`StylePresetName`](/docs/api/type-aliases/StylePresetName) |

### Returns

[`StylePreset`](/docs/api/interfaces/StylePreset)

### Remarks

Matching is case-insensitive and treats spaces, `-` and `_` the same, so
`"focus-box"` resolves to `"Focus Box"` (handy for CLI flags).

### Example

```ts
const preset = getPreset("Karaoke");
```

### Throws

Error listing the available names when nothing matches.

## Call Signature

```ts
function getPreset(name): StylePreset;
```

Looks up a built-in preset by name.

### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

### Returns

[`StylePreset`](/docs/api/interfaces/StylePreset)

### Remarks

Matching is case-insensitive and treats spaces, `-` and `_` the same, so
`"focus-box"` resolves to `"Focus Box"` (handy for CLI flags).

### Example

```ts
const preset = getPreset("Karaoke");
```

### Throws

Error listing the available names when nothing matches.

Source: https://captionsjs.dev/docs/api/functions/getPreset

---

## renderString()

> Server/worker-friendly helper that paints a text string onto a provided canvas.

```ts
function renderString(
   canvas, 
   text, 
   options
): Promise<boolean>;
```

Server/worker-friendly helper that paints a text string onto a provided canvas.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `canvas` | `HTMLCanvasElement` | Destination canvas that should receive the rendered text. |
| `text` | `string` | Arbitrary content that needs to be painted. |
| `options` | \{ `preset`: [`StylePreset`](/docs/api/interfaces/StylePreset); \} | Rendering options that include the style preset. |
| `options.preset` | [`StylePreset`](/docs/api/interfaces/StylePreset) | - |

## Returns

`Promise`\<`boolean`\>

Resolves once the frame has been painted (always resolves to `true`).

## Remarks

Uses the same Konva pipeline as the video overlay renderer so the results
match what users see in the browser.

Source: https://captionsjs.dev/docs/api/functions/renderString

---

## renderStylePreset()

```ts
function renderStylePreset(
   stylePreset, 
   size, 
   frames, 
   text?
): Promise<string[]>;
```

## Parameters

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `stylePreset` | [`StylePreset`](/docs/api/interfaces/StylePreset) | `undefined` |
| `size` | \[`number`, `number`\] | `undefined` |
| `frames` | `number`[] | `undefined` |
| `text` | `string` | `"Hello World"` |

## Returns

`Promise`\<`string`[]\>

Source: https://captionsjs.dev/docs/api/functions/renderStylePreset

---

## toCaptions()

```ts
function toCaptions(input): Caption[];
```

## Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | `unknown` |

## Returns

[`Caption`](/docs/api/interfaces/Caption)[]

Source: https://captionsjs.dev/docs/api/functions/toCaptions

---

## Caption

> Single timed word/segment that will be highlighted as audio plays.

Single timed word/segment that will be highlighted as audio plays.

## Properties

| Property | Type |
| ------ | ------ |
| <a id="property-endtime"></a> `endTime` | `number` |
| <a id="property-highlightcolor"></a> `highlightColor?` | `string` |
| <a id="property-paragraphendtime"></a> `paragraphEndTime?` | `number` |
| <a id="property-paragraphstarttime"></a> `paragraphStartTime?` | `number` |
| <a id="property-sentenceendtime"></a> `sentenceEndTime?` | `number` |
| <a id="property-sentencestarttime"></a> `sentenceStartTime?` | `number` |
| <a id="property-speaker"></a> `speaker?` | `number` |
| <a id="property-starttime"></a> `startTime` | `number` |
| <a id="property-word"></a> `word` | `string` |

Source: https://captionsjs.dev/docs/api/interfaces/Caption

---

## CaptionsSettings

> Full styling + animation configuration for a single captions track.

Full styling + animation configuration for a single captions track.

## Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-animation"></a> `animation` | \| `"scale"` \| `"none"` \| `"bounce"` \| `"underline"` \| `"box"` \| `"pop"` \| `"slide-left"` \| `"slide-up"` \| `"slide-down"` \| `"box-word"` | - |
| <a id="property-linespacing"></a> `lineSpacing?` | `number` \| `null` | - |
| <a id="property-linesperpage"></a> `linesPerPage` | `number` | - |
| <a id="property-position"></a> `position` | `"auto"` \| `"top"` \| `"middle"` \| `"bottom"` | - |
| <a id="property-positiontopoffset"></a> `positionTopOffset?` | `number` | - |
| <a id="property-style"></a> `style` | `object` | - |
| `style.aplifiedWordColor?` | `string` | **Deprecated** Misspelled original name of CaptionsSettings.style.highlightColor. Still read when `highlightColor` is not set; will be removed in 2.0. |
| `style.backgroundColor` | `string` | - |
| `style.font` | `object` | - |
| `style.font.fontCapitalize` | `boolean` | - |
| `style.font.fontColor` | `string` | - |
| `style.font.fontFamily` | `string` | - |
| `style.font.fontSize` | `number` | - |
| `style.font.fontStrokeColor` | `string` | - |
| `style.font.fontStrokeWidth` | `number` | - |
| `style.font.fontWeight` | `"thin"` \| `"light"` \| `"regular"` \| `"medium"` \| `"bold"` \| `"black"` | - |
| `style.font.italic` | `boolean` | - |
| `style.font.shadow?` | `object` | - |
| `style.font.shadow.fontShadowBlur` | `number` | - |
| `style.font.shadow.fontShadowColor` | `string` | - |
| `style.font.shadow.fontShadowOffsetX` | `number` | - |
| `style.font.shadow.fontShadowOffsetY` | `number` | - |
| `style.font.underline` | `boolean` | - |
| `style.highlightColor?` | `string` | Color of the active (spoken) word. A per-word `Caption.highlightColor` overrides it. |
| `style.name` | `string` | - |
| `style.verticalCoverImg?` | `string` | - |

Source: https://captionsjs.dev/docs/api/interfaces/CaptionsSettings

---

## StylePreset

> Shared schema describing how a preset styles captions plus rough layout hints.

Shared schema describing how a preset styles captions plus rough layout hints.

## Properties

| Property | Type |
| ------ | ------ |
| <a id="property-captionssettings"></a> `captionsSettings` | [`CaptionsSettings`](/docs/api/interfaces/CaptionsSettings) |
| <a id="property-id"></a> `id` | `number` |
| <a id="property-layoutsettings"></a> `layoutSettings` | `object` |
| `layoutSettings.aIAutoLayout` | `string`[] |
| `layoutSettings.aspectRatio` | `string` |
| `layoutSettings.fitLayoutAspectRatio` | `string` |

Source: https://captionsjs.dev/docs/api/interfaces/StylePreset

---

## CaptionsInput

```ts
type CaptionsInput = DeepgramResponse | PlainCaptions;
```

Source: https://captionsjs.dev/docs/api/type-aliases/CaptionsInput

---

## CaptionsInstance

> Convenience alias for the concrete controller class.

```ts
type CaptionsInstance = Captions;
```

Convenience alias for the concrete controller class.

Source: https://captionsjs.dev/docs/api/type-aliases/CaptionsInstance

---

## CaptionsOptions

> Configuration passed to the captions runtime when binding to a video element.

```ts
type CaptionsOptions = object;
```

Configuration passed to the captions runtime when binding to a video element.

## Properties

### autoEnable?

```ts
optional autoEnable?: boolean;
```

When false, caller must invoke [Captions.enable](/docs/api/classes/Captions#enable) manually.

***

### captions?

```ts
optional captions?: Caption[] | null;
```

Initial caption track.

***

### container?

```ts
optional container?: HTMLDivElement;
```

Optional custom container to host the Konva stage.

***

### debug?

```ts
optional debug?: boolean;
```

Show debug bounding boxes around lines/blocks.

***

### preset

```ts
preset: StylePreset;
```

Initial preset controlling font, colors, animations.

***

### video

```ts
video: HTMLVideoElement;
```

Video element that should receive overlays.

Source: https://captionsjs.dev/docs/api/type-aliases/CaptionsOptions

---

## LoadGoogleFontOptions

```ts
type LoadGoogleFontOptions = object;
```

## Properties

### preloadAllSubsets?

```ts
optional preloadAllSubsets?: boolean;
```

***

### text?

```ts
optional text?: string;
```

***

### weights?

```ts
optional weights?: string[];
```

Source: https://captionsjs.dev/docs/api/type-aliases/LoadGoogleFontOptions

---

## StylePresetName

> Names of all available style presets.

```ts
type StylePresetName = 
  | "Karaoke"
  | "Focus Box"
  | "Banger"
  | "Acid"
  | "Lovly"
  | "Marvel"
  | "Marker"
  | "Neon Pulse"
  | "Beasty"
  | "Crazy"
  | "Safari"
  | "Popline"
  | "Desert"
  | "Hook"
  | "Sky"
  | "Flamingo"
  | "Deep Diver B&W"
  | "New"
  | "Catchy"
  | "From"
  | "Classic"
  | "Classic Big"
  | "Old Money"
  | "Cinema"
  | "Midnight Serif"
  | "Aurora Ink";
```

Names of all available style presets.

Source: https://captionsjs.dev/docs/api/type-aliases/StylePresetName

---

## googleFontsList

> Whitelisted Google Fonts that the renderer knows how to lazy-load.

```ts
const googleFontsList: readonly ["Roboto", "Open Sans", "Lato", "Montserrat", "Nunito", "Poppins", "Ubuntu", "PT Sans", "Merriweather Sans", "Lobster", "Amatic SC", "Pacifico", "Raleway", "Cinzel", "Quicksand", "Zilla Slab", "Caveat", "Crimson Pro", "Bebas Neue", "Comfortaa", "Satisfy", "Permanent Marker", "Oswald", "Onest", "Bangers", "Kanit", "Work Sans", "Fira Sans", "Anton", "Playfair Display", "Rubik", "Alumni Sans", "Righteous", "Kalam", "Arsenal", "Balsamiq Sans", "Bona Nova SC"];
```

Whitelisted Google Fonts that the renderer knows how to lazy-load.

## Remarks

Restricting the list keeps bundle size predictable across consumers.

Source: https://captionsjs.dev/docs/api/variables/googleFontsList

---

## preloadGoogleFont

> Bullet-proof browser preload for Google Fonts: 1) Fetches Google CSS 2) Parses every returned

```ts
const preloadGoogleFont: (fontFamily, options) => Promise<void> = loadGoogleFont2;
```

Bullet-proof browser preload for Google Fonts:
1) Fetches Google CSS
2) Parses every returned

## Parameters

| Parameter | Type |
| ------ | ------ |
| `fontFamily` | `string` |
| `options` | [`LoadGoogleFontOptions`](/docs/api/type-aliases/LoadGoogleFontOptions) |

## Returns

`Promise`\<`void`\>

## Font-face

3) Loads each selected .woff2 via FontFace.load()
4) Registers in document.fonts

If the exact requested weights are not available for the family (Google
Fonts CSS2 API responds with 400 in that case, e.g. "PT Sans" + 900 or
"Pacifico" + 500), falls back to loading 400/700 so the family is still
registered and the canvas can resolve the closest available weight.

Source: https://captionsjs.dev/docs/api/variables/preloadGoogleFont

---

## presetNames

> Names of all built-in presets, in display order.

```ts
const presetNames: StylePresetName[];
```

Names of all built-in presets, in display order.

Source: https://captionsjs.dev/docs/api/variables/presetNames

---

## renderFrame

```ts
const renderFrame: RenderFrameFn;
```

Source: https://captionsjs.dev/docs/api/variables/renderFrame

---

## stylePresets

> Curated set of presets that ship with captions.js out of the box.

```ts
const stylePresets: StylePreset[];
```

Curated set of presets that ship with captions.js out of the box.

## Remarks

Downstream apps can reference them directly or clone/extend as needed.

Source: https://captionsjs.dev/docs/api/variables/stylePresets