captionseasy

captionseasy

言葉を用意するだけで、スタイル付き字幕が完成します。 CaptionsEasy は、開発者や AI 編集エージェント向けの字幕スタイルレイヤーです。デザインされた99種類のアニメーション字幕スタイル、タイミング付き単語とスタイルからレンダリング可能な字幕プロパティを生成するバリデーター、それらを描画する React／Remotion コンポーネント、CLI、MCP サーバーを備えています。

• 軽量で依存関係なし。 npm i captionseasy で約1.6 MBのパッケージを1つ追加するだけで、実行時の依存関係はありません。
• 設定項目の寄せ集めではなく、デザインされたスタイル。 各スタイルには固定の番号（#12 Jumping Box、#105 Classic Subtitle）があります。それぞれのスタイルで実際に反映される少数の設定項目が明示されます。それ以外の設定は何も起きずに無視されるのではなく、明確なエラーとともに拒否されます。
• エージェント対応。 すべての CLI コマンドで --json を使用できます。MCP ツールは JSON を受け取り、JSON を返します。
• 完全にローカルで無料。 サーバーも API キーも不要です。レンダリングと音声テキスト変換はオプションのアドオンで、どちらもお使いのマシン上で実行されます。

30秒で始める

エディター、ASR、エージェントなどから取得した単語のタイミングデータがすでにある場合：

[{ "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 }

エラーは、安定した code を持つ CaptionsEasyError オブジェクトです。コードは 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 からフォントが読み込まれます（無料、キー不要）。

CLI

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 }

• 焼き込みモードでは、元の音声を含む H.264 MP4 が出力されます。
• オーバーレイモードでは、動画と同じサイズおよび長さで、アルファチャンネル付きの ProRes 4444 .mov または VP9 .webm が出力されます。
• アドオンにはコンポジションがあらかじめバンドルされているため、お使いのマシンで webpack が実行されることはありません。Remotion に付属する ffmpeg を使用します。

オプション：文字起こし（captionseasy-transcribe）

まだ単語ごとのタイミングがありませんか？このアドオンは Whisper をローカルで実行し、onnxruntime-node 上の transformers.js を通じて、単語タイムスタンプ付きの 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 アドオン）：onnx-community/whisper-base_timestamped 経由の OpenAI Whisper（MIT）。Hinglish モデルは ishaan-g/whisper-hinglish-swift_timestamped です。
• フォント：Google Fonts（オープンライセンス）。