# captions.js

> captions.js is an open-source (MIT) JavaScript library that renders word-level animated captions (subtitles) on canvas. The same renderFrame function draws the captions live over a <video> element in the browser and frame by frame into an MP4 through FFmpeg in Node.js, so the preview and the exported video are pixel-identical, with no headless browser.

Key facts:

- Install: `npm install captions.js` (browser overlay). Server-side burn-in: `npm install @captionsjs/server` (needs ffmpeg), or with nothing installed: `npx captions.js burn video.mp4 words.json --preset Karaoke`.
- Input: word timings from Whisper (verbose_json), Deepgram, or a plain array of { word, startTime, endTime }. `toCaptions()` detects the format.
- Output: a live canvas overlay in the browser; an H.264 MP4 from Node or the Docker image `maskin25/captions.js-render` (CLI and HTTP API on port 4000).
- 26 style presets (Karaoke, Focus Box, Banger, Neon Pulse, Cinema, Old Money and more), 10 word animations (bounce, pop, scale, box, box-word, underline, slide-left, slide-up, slide-down, none), Google Fonts loaded on demand.
- Compared with alternatives: @remotion/captions only converts transcript formats and renders nothing; full Remotion rendering needs headless Chrome in production; ASS/libass and FFmpeg drawtext cannot do per-word animated kinetic typography.
- Source: https://github.com/maskin25/captions.js · npm: https://www.npmjs.com/package/captions.js · Site: https://captionsjs.dev

## Docs

- [Introduction](https://captionsjs.dev/docs.md): 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.
- [Docker Render Service](https://captionsjs.dev/docs/server.md)

## Guides

- [captions.js vs Remotion, ASS/libass and FFmpeg drawtext](https://captionsjs.dev/docs/guides/captions-js-vs-remotion-ass-drawtext.md): How the common ways to render animated captions compare: live preview, server-side burn-in, headless browser, word-level animation.
- [Animated captions from Deepgram transcripts](https://captionsjs.dev/docs/guides/deepgram-animated-captions.md): Feed a Deepgram pre-recorded response straight into captions.js: word timings, sentences and paragraphs, rendered as animated captions.
- [Animated captions with FFmpeg in Node.js](https://captionsjs.dev/docs/guides/ffmpeg-animated-captions-nodejs.md): 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.
- [Word-by-word captions in React and Next.js](https://captionsjs.dev/docs/guides/react-word-by-word-captions.md): 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.
- [Animated captions from Whisper word timestamps](https://captionsjs.dev/docs/guides/whisper-animated-captions.md): Turn OpenAI Whisper, faster-whisper or the Whisper API output into word-by-word animated captions, in the browser and burned into an MP4.

## Caption styles

- [Karaoke caption style](https://captionsjs.dev/styles/karaoke.md): Karaoke caption preset: Rubik black, uppercase, "bounce" word animation, bottom of the frame.
- [Focus Box caption style](https://captionsjs.dev/styles/focus-box.md): Focus Box caption preset: Montserrat black, uppercase, "box-word" word animation, bottom of the frame.
- [Banger caption style](https://captionsjs.dev/styles/banger.md): Banger caption preset: Oswald bold, uppercase, "pop" word animation, bottom of the frame.
- [Acid caption style](https://captionsjs.dev/styles/acid.md): Acid caption preset: PT Sans black, "none" word animation, bottom of the frame.
- [Lovly caption style](https://captionsjs.dev/styles/lovly.md): Lovly caption preset: Pacifico medium, "scale" word animation, bottom of the frame.
- [Marvel caption style](https://captionsjs.dev/styles/marvel.md): Marvel caption preset: Oswald medium, "scale" word animation, bottom of the frame.
- [Marker caption style](https://captionsjs.dev/styles/marker.md): Marker caption preset: Raleway black, "underline" word animation, bottom of the frame.
- [Neon Pulse caption style](https://captionsjs.dev/styles/neon-pulse.md): Neon Pulse caption preset: Amatic SC black, "slide-up" word animation, bottom of the frame.
- [Beasty caption style](https://captionsjs.dev/styles/beasty.md): Beasty caption preset: Permanent Marker black, uppercase, "pop" word animation, bottom of the frame.
- [Crazy caption style](https://captionsjs.dev/styles/crazy.md): Crazy caption preset: Montserrat black, uppercase, "none" word animation, bottom of the frame.
- [Safari caption style](https://captionsjs.dev/styles/safari.md): Safari caption preset: Poppins bold, "box" word animation, bottom of the frame.
- [Popline caption style](https://captionsjs.dev/styles/popline.md): Popline caption preset: Raleway bold, "none" word animation, bottom of the frame.
- [Desert caption style](https://captionsjs.dev/styles/desert.md): Desert caption preset: Montserrat black, uppercase, "bounce" word animation, bottom of the frame.
- [Hook caption style](https://captionsjs.dev/styles/hook.md): Hook caption preset: Lato black, uppercase, "underline" word animation, bottom of the frame.
- [Sky caption style](https://captionsjs.dev/styles/sky.md): Sky caption preset: Montserrat black, uppercase, "slide-left" word animation, bottom of the frame.
- [Flamingo caption style](https://captionsjs.dev/styles/flamingo.md): Flamingo caption preset: Montserrat black, uppercase, "scale" word animation, bottom of the frame.
- [Deep Diver B&W caption style](https://captionsjs.dev/styles/deep-diver-bw.md): Deep Diver B&W caption preset: Raleway bold, "box" word animation, bottom of the frame.
- [New caption style](https://captionsjs.dev/styles/new.md): New caption preset: Montserrat bold, uppercase, "pop" word animation, middle of the frame.
- [Catchy caption style](https://captionsjs.dev/styles/catchy.md): Catchy caption preset: Montserrat black, uppercase, "bounce" word animation, bottom of the frame.
- [From caption style](https://captionsjs.dev/styles/from.md): From caption preset: Kanit black, uppercase, "pop" word animation, bottom of the frame.
- [Classic caption style](https://captionsjs.dev/styles/classic.md): Classic caption preset: Roboto bold, "none" word animation, bottom of the frame.
- [Classic Big caption style](https://captionsjs.dev/styles/classic-big.md): Classic Big caption preset: Roboto medium, "none" word animation, bottom of the frame.
- [Old Money caption style](https://captionsjs.dev/styles/old-money.md): Old Money caption preset: Playfair Display regular, "slide-up" word animation, bottom of the frame.
- [Cinema caption style](https://captionsjs.dev/styles/cinema.md): Cinema caption preset: Lato bold, "none" word animation, bottom of the frame.
- [Midnight Serif caption style](https://captionsjs.dev/styles/midnight-serif.md): Midnight Serif caption preset: Playfair Display bold, "box" word animation, bottom of the frame.
- [Aurora Ink caption style](https://captionsjs.dev/styles/aurora-ink.md): Aurora Ink caption preset: Oswald bold, uppercase, "underline" word animation, bottom of the frame.

## API Reference

- [API Reference](https://captionsjs.dev/docs/api.md): Every export of the captions.js package.
- [Captions](https://captionsjs.dev/docs/api/classes/Captions.md): Imperative controller that owns the Konva stage lifecycle for a single video element.
- [captionsjs()](https://captionsjs.dev/docs/api/functions/captionsjs.md): Factory mirroring the legacy default export for ergonomic imports.
- [getHighlightColor()](https://captionsjs.dev/docs/api/functions/getHighlightColor.md): Active-word color of a settings object, honouring the deprecated aplifiedWordColor name for settings saved before 1.10.
- [getParagraphs()](https://captionsjs.dev/docs/api/functions/getParagraphs.md)
- [getPreset()](https://captionsjs.dev/docs/api/functions/getPreset.md): Predefined caption appearance presets and their strong typings.
- [renderString()](https://captionsjs.dev/docs/api/functions/renderString.md): Server/worker-friendly helper that paints a text string onto a provided canvas.
- [renderStylePreset()](https://captionsjs.dev/docs/api/functions/renderStylePreset.md)
- [toCaptions()](https://captionsjs.dev/docs/api/functions/toCaptions.md)
- [Caption](https://captionsjs.dev/docs/api/interfaces/Caption.md): Single timed word/segment that will be highlighted as audio plays.
- [CaptionsSettings](https://captionsjs.dev/docs/api/interfaces/CaptionsSettings.md): Full styling + animation configuration for a single captions track.
- [StylePreset](https://captionsjs.dev/docs/api/interfaces/StylePreset.md): Shared schema describing how a preset styles captions plus rough layout hints.
- [CaptionsInput](https://captionsjs.dev/docs/api/type-aliases/CaptionsInput.md)
- [CaptionsInstance](https://captionsjs.dev/docs/api/type-aliases/CaptionsInstance.md): Convenience alias for the concrete controller class.
- [CaptionsOptions](https://captionsjs.dev/docs/api/type-aliases/CaptionsOptions.md): Configuration passed to the captions runtime when binding to a video element.
- [LoadGoogleFontOptions](https://captionsjs.dev/docs/api/type-aliases/LoadGoogleFontOptions.md)
- [StylePresetName](https://captionsjs.dev/docs/api/type-aliases/StylePresetName.md): Names of all available style presets.
- [googleFontsList](https://captionsjs.dev/docs/api/variables/googleFontsList.md): Whitelisted Google Fonts that the renderer knows how to lazy-load.
- [preloadGoogleFont](https://captionsjs.dev/docs/api/variables/preloadGoogleFont.md): Bullet-proof browser preload for Google Fonts: 1) Fetches Google CSS 2) Parses every returned
- [presetNames](https://captionsjs.dev/docs/api/variables/presetNames.md): Names of all built-in presets, in display order.
- [renderFrame](https://captionsjs.dev/docs/api/variables/renderFrame.md)
- [stylePresets](https://captionsjs.dev/docs/api/variables/stylePresets.md): Curated set of presets that ship with captions.js out of the box.

## Blog

- [captions.js has a new home: captionsjs.dev](https://captionsjs.dev/blog/new-home.md): Docs, changelog and this blog now live on one site. Old GitHub Pages links redirect here.

## Optional

- [Changelog](https://captionsjs.dev/changelog.md): every release, newest first
- [All docs in one file](https://captionsjs.dev/llms-full.txt)
- [Caption style previews](https://captionsjs.dev/presets/manifest.json): machine-readable list of presets with preview videos