Captionseasy

captionseasy

Bring your words, get styled captions. CaptionsEasy is a caption style layer for developers and AI editing agents: 99 designed, animated caption looks, a validator that turns timed words + a look into ready-to-render caption props, the React/Remotion components that draw them, a CLI and an MCP server.

• Tiny and dependency-free. npm i captionseasy adds one package, about 1.6 MB, with zero runtime dependencies.
• Designed looks, not settings soup. Every look has a permanent number (#12 Jumping Box, #105 Classic Subtitle). Each look lists the few controls it really responds to. Anything else is rejected with a clear error instead of silently doing nothing.
• Agent-ready. Every CLI command has --json. The MCP tools take JSON and return JSON.
• Runs 100% locally, free. No servers and no API keys. Rendering and speech-to-text are optional add-ons that also run on your machine.

30-second quickstart

You already have word timings, for example from your editor, your ASR or your agent:

[{ "text": "Stop", "startMs": 380, "endMs": 840 }, { "text": "scrolling", "startMs": 840, "endMs": 1080 }]

npx captionseasy looks bold                     # pick a look (search: neon, karaoke, subtitle, "one word" ...)

npx captionseasy look 12 # what can I change on look #12? npx captionseasy build --words words.json --look 12 --set active.boxColor=#FF3366 --out props.json

props.json holds { doc, style, settings }, validated and complete. Render it with the CaptionsEasy composition in your own Remotion timeline (see Use the props in Remotion). If you would rather get a finished video file, add rendering.

Library

import { listLooks, describeLook, buildCaptions } from "captionseasy";

listLooks({ query: "bold" }); // [{ number, id, name, section, tags, description, layout, wordsPerCard }] describeLook(12); // { ...summary, defaults, controls: [{ key, type, min, max, options, default, dependsOn }], settings: [...] }

const props = buildCaptions({ words, // [{ text, startMs, endMs }] look: 12, // number or id ("hormozi_box") overrides: { "active.boxColor": "#FF3366", "position.y": 0.6 }, settings: { maxWordsPerCard: 2 }, // pacing }); // { doc, style, settings, look: { number, id, name }, warnings }

Errors are CaptionsEasyError objects with a stable code: UNKNOWN_LOOK, BAD_OVERRIDE, BAD_SETTINGS, BAD_WORDS, BAD_ARGS, FILE_NOT_FOUND, ADDON_MISSING, NO_AUDIO, NO_VIDEO, TRANSCRIBE_FAILED or RENDER_FAILED. The details field carries machine-readable context, such as the valid keys, the allowed range or the install command.

Overrides can be flat dot paths ({"active.color": "#FF3366"}) or nested objects. Colours can be written as #RGB, #RRGGBB, #RRGGBBAA, rgb()/rgba()/hsl(), or a basic name.

A control with dependsOn only works once another key is set:

• Harmless switches (outline, shadow, glow, background, gradient) are turned on for you, with a warning.
• Switches that change the motion are never turned on for you; you get an error saying what to set.

Use the props in Remotion

captionseasy/remotion exports the same composition the CaptionsEasy studio uses. Its peer dependencies are react and remotion (^4.0.484).

import { Composition } from "remotion";

import { CaptionedVideo, CaptionsOverlay, calculateMetadata } from "captionseasy/remotion";

// captions only, transparent: put it on a track above your video

// or captions burned over a video

CaptionsEasyCompositions registers both compositions (CaptionedVideo, CaptionsOverlay). Fonts load from Google Fonts while rendering (free, no key).

CLI

captionseasy looks [query] [--tag <tag>] [--section <id>]   list the looks

captionseasy look one look: defaults + the controls it honours captionseasy build --words --look [--set key=value ...] [--out props.json] captionseasy mcp MCP server on stdio captionseasy --look [--words w.json] ... render a video (add-on captionseasy-render) captionseasy transcribe [--out words.json] speech to timed words (add-on captionseasy-transcribe)

MCP server

The tools are `list_looks`, `describe_look`, `build_captions`, `caption_video` and `transcribe`. All take JSON and use local file paths.

• build_captions works with the core package alone.
• caption_video and transcribe need their add-on. Without it they return ADDON_MISSING with the exact install command.

To add it to Claude Code:

claude mcp add captionseasy -- npx -y captionseasy mcp

with video rendering:

claude mcp add captionseasy -- npx -y -p captionseasy -p captionseasy-render captionseasy mcp

For Cursor (~/.cursor/mcp.json), Claude Desktop, or any client that takes the usual shape:

{ "mcpServers": { "captionseasy": { "command": "npx", "args": ["-y", "captionseasy", "mcp"] } } }

On Windows, if your client cannot start npx directly, use "command": "cmd", "args": ["/c", "npx", "-y", "captionseasy", "mcp"].

Optional: rendering (captionseasy-render)

npm i captionseasy captionseasy-render        # ~75 MB; a headless Chrome (~100 MB) downloads on first render

npx captionseasy talk.mp4 --look 12 --words talk.words.json # -> talk.captioned.mp4 npx captionseasy talk.mp4 --look 12 --words talk.words.json --overlay # -> talk.captions.mov (alpha)

without a local install:

npx -p captionseasy -p captionseasy-render captionseasy talk.mp4 --look 12 --words talk.words.json

import { render } from "captionseasy";   // loads captionseasy-render on demand

await render({ video: "talk.mp4", words, look: 12, mode: "overlay", overlayFormat: "webm", out: "captions.webm" }); // { out, mode, durationMs, width, height, fps, look, words, renderMs, warnings }

• Burn mode writes an H.264 MP4 with the original audio.
• Overlay mode writes ProRes 4444 .mov or VP9 .webm, both with an alpha channel, at the video's size and length.
• The add-on ships the composition pre-bundled, so no webpack runs on your machine. It uses the ffmpeg that comes with Remotion.

Optional: transcription (captionseasy-transcribe)

No word timings yet? This add-on runs Whisper locally, using whisper-base with word timestamps through transformers.js on onnxruntime-node.

• onnxruntime-node ships prebuilt binaries, so nothing is compiled.
• The add-on is about 540 MB installed, plus a speech model downloaded once into your user cache (about 200 MB for English, about 77 MB for Hinglish).

npm i captionseasy captionseasy-transcribe

npx captionseasy transcribe talk.mp4 --out talk.words.json # [{ text, startMs, endMs }]

With both add-ons installed, captionseasy talk.mp4 --look 12 transcribes and renders in one step.

JSON shapes

// describe_look / captionseasy look 12 --json (trimmed)

{ "number": 12, "id": "hormozi_box", "name": "Jumping Box", "section": "popular", "layout": "sentence", "wordsPerCard": 3, "defaults": { "fontSize": 58, "active.boxColor": "#22C55E", "position.y": 0.72 }, "controls": [ { "key": "fontSize", "label": "Size", "type": "number", "min": 24, "max": 140, "step": 1, "default": 58 }, { "key": "active.effect", "label": "Spoken-word effect", "type": "enum", "options": ["none", "color", "box"], "default": "box" }, { "key": "stroke.width", "label": "Outline width", "type": "number", "min": 1, "max": 16, "default": 3, "dependsOn": "stroke.enabled=true" } ], "settings": [{ "key": "maxWordsPerCard", "type": "number", "min": 1, "max": 12, "default": 3 }] }

// build_captions / buildCaptions { "doc": { "version": 2, "language": "en", "words": [{ "id": "a1b2c3d4e5f6", "text": "Stop", "startMs": 380, "endMs": 840 }] }, "style": { "templateId": "boxed_word", "fontId": "Montserrat", "...": "every field filled in" }, "settings": { "maxWordsPerCard": 3, "pauseMs": 400, "...": "..." }, "look": { "number": 12, "id": "hormozi_box", "name": "Jumping Box" }, "warnings": [] }

// any error { "error": { "code": "BAD_OVERRIDE", "message": "Unknown style key \"wobble\". Jumping Box (#12) accepts: fontId, fontSize, ...", "details": { "validKeys": ["fontId", "..."] } } }

Licences

• captionseasy: MIT (see LICENSE).
• Rendering uses Remotion. Remotion is free for individuals and for companies of up to 3 people; larger companies need a Remotion company licence. This applies whether you render with captionseasy-render or render the components in your own Remotion project.
• Speech models (transcribe add-on): OpenAI Whisper (MIT), via onnx-community/whisper-base_timestamped. The Hinglish model is ishaan-g/whisper-hinglish-swift_timestamped.
• Fonts: Google Fonts (open licences).