justcaptions

エージェント向け Just Captions

Codex、Claude Code、あらゆる MCP クライアント、またはターミナルから動画に字幕を付けられます。このスキルは音声を書き起こして SRT／VTT／JSON ファイルを作成し、TikTok／Reels 風の字幕を動画に焼き込みます。一度に処理できるのは、動画 1 本またはフォルダー全体です。

アニメーション付きのポータブルなプリセット 15 種類は、Just Captions アプリのスタイルファミリーに準じています。タイポグラフィとサンプリングしたアニメーションは、iOS ネイティブ版と異なる場合があります。レンダリングは Pillow と ffmpeg を使ってお使いのマシン上で実行されます。

スタイルを選んでタスクをコピー · API ドキュメント · OpenAPI · スタイルカタログ

絵文字	メガ	リビール

ネオン	白いボックス	黄色いボックス

グレーのボックス	黄色のアウトライン	単語のハイライト

ハイライトボックス	インパクト	ポップイン

タイプライター	シネマ	エディトリアル

MCP クイックスタート

パッケージ版の MCP／CLI には Python 3.10 以降、uv および ffmpeg が必要です。プレーンなスキルは Python 3.9 以降と Pillow で引き続き動作します。

Codex — ~/.codex/config.toml に追加します：

[mcp_servers.justcaptions]
command = "uvx"
args = ["--from", "https://github.com/SpaceSheepBoy/justcaptions-skill/releases/download/v1.3.1/justcaptions_agent-1.3.1-py3-none-any.whl", "justcaptions-mcp"]
startup_timeout_sec = 120

[mcp_servers.justcaptions_cloud]
url = "https://api.justcaptions.com/mcp"
bearer_token_env_var = "JUSTCAPTIONS_API_KEY"

Claude Code — プロジェクトの .mcp.json にマージします：

{
  "mcpServers": {
    "justcaptions": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "https://github.com/SpaceSheepBoy/justcaptions-skill/releases/download/v1.3.1/justcaptions_agent-1.3.1-py3-none-any.whl", "justcaptions-mcp"]
    },
    "justcaptions_cloud": {
      "type": "http",
      "url": "https://api.justcaptions.com/mcp",
      "headers": {"Authorization": "Bearer ${JUSTCAPTIONS_API_KEY}"}
    }
  }
}

JUSTCAPTIONS_API_KEY を設定するか、CLI の --signup YOUR_EMAIL でキーを保存してください。ローカル MCP は ~/.config/justcaptions/api_key も読み込みます。キーをプロンプトやコミットに含めないでください。キーなしで音声認識を行うには、uvx の引数で "--from" の前に "--with", "faster-whisper" を追加します。オフラインモデルは初回使用時にダウンロードされます。

次のように依頼します：「~/Movies/intro.mp4 に TikTok 用の Word Highlight スタイルで字幕を付けてください。MP4、SRT、VTT、JSON を ./captioned/ に保存し、元のファイルは保持してください。」

ツール	目的
check_environment	メディアツールと音声認識／キーの利用可否を確認します。認証情報は表示しません
list_styles	15 種類のプリセット、受け付ける上書き設定、エイリアス、安全領域の余白を確認します
preview_style	有料 API の呼び出しなしで、選択した設定からインライン PNG をレンダリングします
caption_video	動画／フォルダーのジョブを開始し、ジョブ ID をすぐに返します
get_job	ステージと、ファイルごとに検証済みの出力パスを確認します
get_usage	現在の API 使用量と月額料金の見積もりを確認します

caption_video では input_path、output_dir、style_id、size、position、safe_area、length、overrides、captions_path、engine、language、translate_to、correct、glossary、burn、overwrite を指定します。型付きスキーマについては MCP の検出機能を参照してください。フォルダージョブでは最大 100 ファイルを処理でき、同時に実行できるジョブは 2 件です。ジョブはプロセスの再起動後もローカルに保持されます。復旧するには list_jobs と resume_job を使用してください。既存の出力は、明示的に上書きするよう指定しない限り保護されます。フォルダージョブでは、ソースごとに出力ディレクトリが作成されます。

リモート MCP

https://api.justcaptions.com/mcp は、Streamable HTTP と API キーを使用します。音声と字幕テキストを処理します。ローカルファイルへのアクセス、スタイルのプレビュー、MP4 のレンダリングは行いません。

Codex の場合：

[mcp_servers.justcaptions_cloud]
url = "https://api.justcaptions.com/mcp"
bearer_token_env_var = "JUSTCAPTIONS_API_KEY"

Claude Code の場合は、プロジェクトの .mcp.json に次のエントリーを追加します。

{"mcpServers":{"justcaptions_cloud":{"type":"http","url":"https://api.justcaptions.com/mcp","headers":{"Authorization":"Bearer ${JUSTCAPTIONS_API_KEY}"}}}}

ツール：list_styles、get_pricing、get_usage、transcribe_audio、correct_captions、translate_captions、pick_emojis。クラウド操作には、既存の API 料金と利用制限が適用されます。一意の request_id を指定し、同一リクエストの再試行に限り再利用してください。リクエストハッシュと完了した応答は 24 時間の再実行ウィンドウに保持され、その後、次回のリクエスト時または毎日のクリーンアップ時（48 時間以内）に削除されます。再実行用のストアに音声は保持されません。

スタイルとカスタマイズ

15 種類すべてのプリセットは、動画への書き出し時にアニメーションし、ウェブサイトのプレビューにも表示されます。アニメーションには、話し言葉に合わせたハイライトや表示、ポップ表示、フェード、タイプライター表示、脈打つグローが使われます。

正式なバージョン管理済みカタログは skills/justcaptions/assets/styles.json です。Emoji、Mega、Reveal、Neon、White box、Yellow box、Gray box、Yellow outline、Word Highlight、Highlight Box、Impact、Pop In、Typewriter、Cinema、Editorial が含まれています。過去の karaoke、black-box、white-outline CLI 名も引き続き使用できます。wordHighlight などのアプリ ID は、移植可能なプリセット ID に解決されます。

ローカル MCP では、たとえば次のように overrides を指定できます。

{"highlight_color":"#1A9E7A","text_color":"#FFFFFF","font_multiplier":1.2,"max_words":3}

ローカルでのレンダリング結果を安定させるため、名前付きフォントがバンドルされています。justcaptions --list-fonts を実行するか、MCP の list_fonts を呼び出してください。公開されている GET /v1/fonts エンドポイントからも同じカタログを取得できます。overrides またはスタイル設定ファイルに {"font_id":"anton"} を設定します。Inter、Poppins、Montserrat、Merriweather、Bebas Neue、Oswald、Roboto Flex、Anton、Barlow Condensed、Nunito、Caveat、Patrick Hand、Permanent Marker の 13 種類から選べます。可変フォントには、カタログの太字軸設定が使用されます。名前付きフォントは font_family より優先されます。"font_id":null を指定すると、一般的なフォントファミリーの選択に戻ります。これらの名前付きフォントはラテン文字の字幕を対象としており、その他の文字体系にはレンダラーのシステムフォントへのフォールバックが適用されます。SRT/VTT はプレーンな字幕のままで、フォントは埋め込まれません。

CLI では、同じオブジェクトを --style-config FILE.json で指定します。不明なキーや無効な値は拒否されます。色、背景、アウトライン、フォントファミリー、サイズ、単語数、大文字・小文字を設定できます。--safe-area tiktok|reels|shorts|none を使用してください。余裕を持たせたマージンにより、字幕は水平方向の中央に配置されます。プラットフォームの UI レイアウトは異なる場合があります。

テキストに変更がない場合、認識された単語のタイムスタンプは保持されます。修正・翻訳されたテキストと、字幕のみのインポートファイルでは、強制アラインメントではなく推定された単語タイミングが使用されます。Serif／Regular ファミリーには利用可能なシステムフォントが使われ、該当するフォントがない場合はバンドル済みの Geist にフォールバックします。

インストール

ffmpeg と Pillow を含む Python 3.9 以降が必要です。

brew install ffmpeg          # or: sudo apt install ffmpeg
pip install Pillow
pip install faster-whisper   # optional: offline transcription

Claude Code プラグインとして

/plugin marketplace add SpaceSheepBoy/justcaptions-skill
/plugin install justcaptions@justcaptions

通常のスキルとして

git clone https://github.com/SpaceSheepBoy/justcaptions-skill
cp -r justcaptions-skill/skills/justcaptions ~/.claude/skills/

その後、Claude に "emoji スタイルで interview.mp4 に字幕を付けて" や "./clips" 内のすべての動画にスペイン語字幕を焼き込んで のように依頼してください。

Claude を使わずに利用する

S=skills/justcaptions/scripts
python3 $S/jc.py talk.mp4 --burn                      # talk.srt, talk.json, talk.captioned.mp4
python3 $S/jc.py clips/ --style karaoke --burn        # batch: every video in the folder
python3 $S/jc.py talk.mp4 --style emoji --burn
python3 $S/jc.py talk.mp4 --formats srt,vtt           # subtitle files only
python3 $S/jc.py talk.mp4 --captions talk.srt --burn  # burn a subtitle file you edited
python3 $S/jc.py talk.mp4 --style word-highlight --safe-area tiktok --burn --json
python3 $S/jc.py --help

オプション	値
--style	15 種類すべてのプリセット ID と従来の名前を指定できます。--list-styles --json でカタログを取得できます
--position	top、middle、bottom、または 0.7 のような割合
--size	small、medium、large
--length	short、medium、long：画面に表示する単語数
--language	音声の言語ヒント。例：en、zh、es
--glossary	正しい表記を指定する名前や用語："Kila Labs, Just Captions"
--engine	api または local（キーが設定されている場合、デフォルトでは API が使用されます）
--correct	認識ミスを AI で修正します（API キーが必要です）
--translate LANG	字幕を翻訳します（API キーが必要です）

字幕を焼き込む前に文言を変更するには、--burn を付けずにスクリプトを実行し、NAME.json または NAME.srt を編集してから、--captions NAME.json --burn を付けて再実行します。JSON ファイルには、カラオケ表示や絵文字表示に使う単語ごとのタイミングが保持されます。

Just Captions API

キーがなくても、すべての処理は faster-whisper を使ってオフラインで実行されます。キーを使うと、次の機能を利用できます。

• クラウド文字起こし（アクセントのある音声、ノイズの多い音声、多くの言語で精度が向上します）
• --correct と --translate
• Emoji スタイル用の AI 絵文字選択（オフライン時はキーワードテーブルを使用します）

キーはすぐに取得でき、カードも不要です。

python3 skills/justcaptions/scripts/jc.py --signup [email protected]

キーは ~/.config/justcaptions/api_key に保存されます（読み取り可能なのは本人のみです）。JUSTCAPTIONS_API_KEY が設定されている場合は、そちらが使用されます。

python3 skills/justcaptions/scripts/jc.py --account   # usage this month and estimated charge

料金

	料金	毎月の無料利用枠
文字起こし	音声1分あたり $0.01、秒単位で課金	30分
修正、翻訳、絵文字	送信する字幕1,000文字あたり $0.01	50,000文字

• 無料プラン（カード不要）：無料利用枠を使い切ると停止します。faster-whisper がインストールされている場合、文字起こしはローカルで続行されます。
• 従量課金制：無料利用枠を超えて使い続けるには、https://justcaptions.com/api/account/ でカードを追加してください。Stripe から毎月請求され、デフォルトの利用上限は月額 $100 です。
• 失敗したリクエストは課金されません。

API に送信するのは音声のみです。スクリプトは動画から小さなモノラルトラックを取り出すため、動画そのものがアップロードされることはなく、字幕の焼き付けも常にお使いのマシン上で行われます。API リファレンス：https://justcaptions.com/api/

iPhone で使いたいですか？

App Store の Just Captions では、オンデバイス文字起こし、編集、バッチエクスポートを備えた、ネイティブの字幕スタイル機能を利用できます。

開発

uv pip install -e . を実行して、分離された環境にインストールしてください。ワーカーの MCP アダプターは remote/mcp.mjs でオープンソースとして公開されています。ホストは既存の認証済み API ハンドラーを注入します。tools/sync-agent-assets.py --site SITE_DIR --backend BACKEND_DIR を実行すると、正式なカタログ、OpenAPI、アダプターがサイトと Worker のソースに公開されます。生成されたコピーを個別に編集しないでください。

python3 -m unittest discover -s tests
python3 tools/smoke-mcp.py  # exercise the installed MCP with synthetic media
python3 tools/agent-previews.py --site SITE_DIR  # regenerate videos/posters and animated README previews
python3 tools/gallery.py   # regenerate the legacy five-style PNG gallery

字幕の焼き付けの仕組み：各字幕状態（カラオケと絵文字では単語ごとに1つ）を、フレーム全体に広がる透明な PNG として描画します。concat デマルチプレクサーで PNG を正確な表示時間の単一画像ストリームとして再生し、1つの overlay フィルターで動画に重ねます。これにより、字幕の数にかかわらず ffmpeg コマンドのサイズを一定に保てます。

ライセンス

コードは MIT ライセンスです。フォントの名称付きライセンスと元のソース URL はカタログに記録されています。ライセンステキストは assets/fonts/licenses/ に収録されています（SIL OFL 1.1、および Permanent Marker の Apache 2.0）。同梱の Geist フォントは SIL OFL 1.1 です（skills/justcaptions/assets/fonts/OFL.txt）。

最初のエクスポートを完了する

Python 3.10 以降、ffmpeg、パッケージをインストールした後、justcaptions --demo --out-dir ./demo --style word-highlight を実行してください。同梱の人間によるナレーションのサンプルには単語ごとのタイムスタンプが含まれており、API キーもモデルのダウンロードも不要です。MCP では run_demo を実行し、その後 get_job を実行してください。ナレーションのクレジットはデモのクレジットに記載されています。

永続ジョブとアカウント管理

list_jobs、get_job、cancel_job、resume_job は、~/.local/share/justcaptions に保存されたジョブを操作します（JUSTCAPTIONS_STATE_DIR で変更できます）。再開時には完了済みのファイルをスキップし、成功したクラウド応答を再利用します。ソースファイルは変更しないでください。処理中のクラウドリクエストは、キャンセル後に完了して課金される場合があります。サーバーのリプレイ可能期間を過ぎた不確実なクラウドリクエストについては、有料処理を黙って繰り返すのではなく、手動で利用状況を確認する必要があります。

認識を開始する前に estimate_video を使用し、編集の場合は既知の text_chars を指定してください。見積もりには将来追加される不明なテキストは含まれず、クレジットも確保されません。API は同時リクエストに対して容量を原子的に確保し、すべての専用キーは 1 つのアカウントの利用枠を共有します。月間支出上限、スコープ付きキー、有効期限、取り消しは https://justcaptions.com/api/account/ で管理できます。上限を引き下げても、既存の課金や実行中の保留は取り消されません。

セットアップ／エクスポート統計は任意です。JUSTCAPTIONS_METRICS_ID を設定すると、ウェブサイトの訪問者がオプトインした場合に限り、コピーされた設定に含まれるカウンターが有効になります。これらのカウンターからファイルパス、字幕、API キーが送信されることはありません。インストール済みクライアントのレポートを無効にするには、この変数を削除して MCP サーバーを再起動してください。

配布

最新の GitHub リリースから標準の wheel をインストールします。

pip install https://github.com/SpaceSheepBoy/justcaptions-skill/releases/download/v1.3.1/justcaptions_agent-1.3.1-py3-none-any.whl

GitHub Actions は wheel／sdist アーティファクトをビルドしてチェックし、リリースに添付するとともに、GitHub OIDC を使用して server.json を公式 MCP Registry に公開します。オーナーが有効にした場合、PyPI への公開にはトラステッドパブリッシャーを使用します。それが完了するまでは、ウェブサイトでリリースの wheel を使用します。

PyPI のトラステッドパブリッシャー設定は保留中です。プロジェクト：justcaptions-agent、GitHub オーナー：SpaceSheepBoy、リポジトリ：justcaptions-skill、ワークフロー：release.yml、環境：pypi。登録後、リポジトリ変数 PYPI_PUBLISH_ENABLED=true を有効にして、リリースワークフローを再実行してください。