captionseasy

captionseasy

带上你的文字，获得精美字幕。 CaptionsEasy 是面向开发者和 AI 编辑 Agent 的字幕样式层：包含 99 种精心设计的动态字幕样式、一个可将带时间戳的词语和样式转换为可直接渲染的字幕属性的验证器、用于绘制字幕的 React/Remotion 组件，以及命令行工具和 MCP 服务。

• 轻巧且无依赖。 npm i captionseasy 只需安装一个软件包，大小约为 1.6 MB，运行时零依赖。
• 精心设计的样式，而非繁杂的设置。 每种样式都有固定编号（#12 Jumping Box、#105 Classic Subtitle）。每种样式只列出实际支持的少数控件。其他设置都会被明确报错，而不会被悄悄忽略。
• 为 Agent 做好准备。 每个命令行工具命令都支持 --json。MCP 工具接收 JSON 并返回 JSON。
• 100% 本地运行，免费使用。 无需服务器和 API 密钥。渲染和语音转文字是可选附加功能，也可在你的设备上运行。

30 秒快速入门

你已经有词语时间戳，例如来自编辑器、ASR 或 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 包含经过验证且完整的 { doc, style, settings }。在你自己的 Remotion 时间线上，使用 CaptionsEasy 合成进行渲染（参见在 Remotion 中使用属性）。如果你想直接获得最终视频文件，可以添加渲染功能。

库

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 }

错误是 CaptionsEasyError 对象，包含稳定的 code：UNKNOWN_LOOK、BAD_OVERRIDE、BAD_SETTINGS、BAD_WORDS、BAD_ARGS、FILE_NOT_FOUND、ADDON_MISSING、NO_AUDIO、NO_VIDEO、TRANSCRIBE_FAILED 或 RENDER_FAILED。details 字段包含机器可读的上下文，例如有效键、允许范围或安装命令。

覆盖值可以是扁平的点分隔路径（{"active.color": "#FF3366"}），也可以是嵌套对象。颜色可写为 #RGB、#RRGGBB、#RRGGBBAA、rgb()/rgba()/hsl() 或基本颜色名称。

只有在设置了另一个键后，带有 dependsOn 的控件才会生效：

• 自动为你启用无害的开关（描边、阴影、发光、背景、渐变），并发出警告。
• 不会自动为你启用会改变动态效果的开关；系统会报错并说明需要设置什么。

在 Remotion 中使用属性

captionseasy/remotion 导出与 CaptionsEasy 工作室使用的相同合成。它的对等依赖项是 react 和 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
<Composition id="Captions" component={CaptionsOverlay} calculateMetadata={calculateMetadata}
  fps={30} width={1080} height={1920} durationInFrames={300}
  defaultProps={{ ...props, media: { width: 1080, height: 1920, fps: 30, durationMs: 10000 } }} />

// or captions burned over a video
<CaptionedVideo src={staticFile("talk.mp4")} media={{ width: 1080, height: 1920, fps: 30, durationMs: 10000 }} {...props} />

CaptionsEasyCompositions 注册了两个合成（CaptionedVideo、CaptionsOverlay）。渲染时会从 Google Fonts 加载字体（免费，无需密钥）。

命令行工具

captionseasy looks [query] [--tag <tag>] [--section <id>]   list the looks
captionseasy look <number|id>                             one look: defaults + the controls it honours
captionseasy build --words <words.json> --look <n|id> [--set key=value ...] [--out props.json]
captionseasy mcp                                          MCP server on stdio
captionseasy <video> --look <n|id> [--words w.json] ...   render a video          (add-on captionseasy-render)
captionseasy transcribe <video> [--out words.json]        speech to timed words   (add-on captionseasy-transcribe)

选项	含义
--look, -l <n|id>	样式编号（12）或 ID（hormozi_box）
--words <file.json>	[{text,startMs,endMs}] 或 { "words": [...] }
--set key=value	更改样式，可重复使用。样式键和节奏键（maxWordsPerCard、pauseMs、gapBehavior 等）均可通过 captionseasy look <n> 获取
--overlay / --format mov|webm	仅渲染透明字幕（ProRes 4444 .mov 或 VP9 .webm）
--out, -o <path>	输出文件
--language en|hinglish|auto	转录时使用的语音语言
--json	在 stdout 上输出一份 JSON 文档。进度信息输出到 stderr。错误以 {"error":{"code","message","details"}} 的形式打印，并以代码 1 退出

MCP 服务

这些工具包括 list_looks、describe_look、build_captions、caption_video 和 transcribe。它们都接受 JSON，并使用本地文件路径。

• build_captions 仅需核心包即可使用。
• caption_video 和 transcribe 需要安装附加组件。若未安装，它们会返回 ADDON_MISSING 和准确的安装命令。

在 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

对于 Cursor（~/.cursor/mcp.json）、Claude Desktop，或任何使用常见配置格式的客户端：

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

在 Windows 上，如果客户端无法直接启动 npx，请使用 "command": "cmd", "args": ["/c", "npx", "-y", "captionseasy", "mcp"]。

可选：渲染（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 模式会生成保留原始音频的 H.264 MP4 文件。
• Overlay 模式会生成 ProRes 4444 .mov 或 VP9 .webm 文件，两者均带有 alpha 通道，分辨率和时长与视频相同。
• 附加组件内置了预打包的合成内容，因此无需在你的计算机上运行 webpack。它使用 Remotion 自带的 ffmpeg。

可选：转录（captionseasy-transcribe）

还没有词级时间戳？此附加组件会在本地运行 Whisper，通过 transformers.js 和 onnxruntime-node 使用带有词级时间戳的 whisper-base。

• onnxruntime-node 提供预编译的二进制文件，因此无需编译。
• 此附加组件安装后约占 540 MB，此外还会将一个语音模型下载到用户缓存中（英语约 200 MB，Hinglish 约 77 MB）。

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

安装两个附加组件后，运行 captionseasy talk.mp4 --look 12 即可一步完成转录和渲染。

JSON 格式

// 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", "..."] } } }

许可证

• captionseasy：MIT（参见 LICENSE）。
• 渲染使用 Remotion。Remotion 对个人和不超过 3 人的公司免费；规模更大的公司需要获取 Remotion 公司许可证。无论你使用 captionseasy-render 渲染，还是在自己的 Remotion 项目中渲染这些组件，都适用此规定。
• 语音模型（transcribe 附加组件）：OpenAI Whisper（MIT），通过 onnx-community/whisper-base_timestamped 使用。Hinglish 模型为 ishaan-g/whisper-hinglish-swift_timestamped。
• 字体：Google Fonts（开放许可证）。