add-captions

キャプションを追加：アニメーション字幕

Remotion の動画にキャプションを追加できるよう、ユーザーをサポートします。

captions-workflow ルール（ルート、プリセット、安全領域）を確認するため、remotion-production スキルを読み込みます。文字起こしと表示については、公式の remotion-captions スキルも読み込みます。Scribe をフォールバックとして使う場合は、ElevenLabs 公式の speech-to-text スキルも読み込みます。API の詳細については、公式スキルの内容を優先します。

ワークフロー

1. 音声ソースを特定する

ナレーションまたはメインの音声ファイルを探します。

ls public/ public/footage/ 2>/dev/null | grep -E '\.(mp3|wav|m4a|ogg|mp4|mov|webm|srt)$'

ユーザーがすでに .srt ファイルを持っている場合は、それを使います（ステップ 3）。音声ファイルがない場合は、先に /add-voiceover を実行するよう提案します。動画のシーンごとにナレーション（vo-scene1.mp3、vo-scene2.mp3、…）がある場合は、各ファイルを個別にキャプション化します。

Studio がすでに実行中であることを確認します（npx remotion studio を実行するか、アプリ内ブラウザーを使って --no-open を指定し、出力された URL を開きます）。そうすれば、ユーザーはキャプションが表示されるのを確認できます。

2. キャプションのスタイルを選ぶ

希望するスタイルをユーザーに尋ねます。

• TikTok スタイル（デフォルト）：太字で一度に数語を表示し、現在の単語をハイライトカラーで目立たせます。単語レベルのデータが必要です。
• カラオケスタイル：フレーズ全体を画面に表示し、発話に合わせて単語をハイライトします。単語レベルのデータが必要です。
• YouTube スタイル：画面下部に一文ずつ表示します。ユーザーの SRT でも使えます。
• ミニマル：画面左下に控えめな小さい文字で表示します。ユーザーの SRT でも使えます。

3. 文字起こしを行う

どちらの方法でも、単語レベルの Caption JSON が生成されるため、すべてのスタイルで使えます。各ファイルの結果は public/<source>.captions.json として保存します（例：vo-scene1.captions.json）。

デフォルト：公式の whisper-webgpu。 公式の remotion-captions/transcribe-captions.md に従います。@remotion/whisper-webgpu を使って、単語ごとに 1 つの Caption を出力する Node スクリプトを作成します。ローカルで実行でき、無料です。対応 GPU が必要で、Linux arm64 では動作しません。英語には small.en を使い、それ以外の言語では多言語モデルを使って language を渡します。

フォールバック：ElevenLabs Scribe。 スクリプトの canUseWhisperWebGpu() チェックに失敗した場合は、Scribe v2 で文字起こしを行い、@remotion/elevenlabs の elevenLabsTranscriptToCaptions() で変換します（npx remotion add @remotion/elevenlabs）。スクリプトは captions-workflow ルールにあります。ELEVENLABS_API_KEY が必要です（設定されていない場合は、npx -y @elevenlabs/cli@latest onboard init を実行します）。クレジットを消費し、音声を ElevenLabs に送信するため、実行前にユーザーへ伝えます。動画ファイルを直接受け付けます。

ユーザー自身の SRT。 public/ に配置し、公式の import-srt-captions.md に記載されているとおり、@remotion/captions の parseSrt() で読み込みます。SRT は行レベルのデータです。各キャプションは字幕全体の 1 行なので、これを使って単語をハイライトすることはできません。ユーザーが TikTok またはカラオケを選んだ場合は、代わりに音声を文字起こしする方法を提案するか、SRT を使える YouTube スタイルにします。

各文字起こしのタイムスタンプは、それぞれのソースファイルを基準にしたままにします。

4. 公式のキャプション要素を配置する

公式の remotion-captions/display-captions.md に従います。

• 必要に応じて、npx remotion add @remotion/captions で @remotion/captions をインストールします。
• 選択したスタイルの要素を、https://www.remotion.dev/elements/captions/<element>.md からプロジェクトにコピーします。TikTok には Popping Word Captions、カラオケには Word Highlight Captions、YouTube とミニマルには Basic Captions を使います。
• キャプションを付けるクリップごとに、要素を 1 つずつ、そのクリップ専用の <Sequence> 内で <Audio>／<Video> の隣に配置します。コンポジション全体にグローバルなキャプションレイヤーを追加しないでください。
• Studio のキャプションエディターが変更を書き戻せるよう、captions プロパティにはキャプション配列をインラインで記述します。

5. 外観をカスタマイズする

captions-workflow ルールのプリセットを適用し、次のオプションを提示します。要素の width、style、combineTokensWithinMilliseconds プロパティ、またはコピーしたファイルの先頭にあるスタイル定数を変更して調整します。

• 位置：上部（10%）、中央（50%）、下部（縦方向の15～25%、プラットフォームのUIと重ならないようにします）。ルールのセーフゾーン表を参照してください。
• フォントサイズ：小（40px）、中（56px）、大（72px）、幅1080の場合
• ハイライト色：黄色（#FFD700）、シアン（#00FFFF）、緑（#00FF88）、カスタム
• 背景：なし、半透明のボックス
• フォント：Inter、Poppins、またはプロジェクトで使用しているフォント（公式の remotion-markup google-fonts.md の手順に従って読み込みます）
• ページあたりの単語数：combineTokensWithinMilliseconds（値を小さくすると、ページあたりの単語数が減ります）

アニメーションを追加する場合は、style 内で interpolate() を使用し、scale／translate プロパティを設定します。CSS の transition や animation は使用しないでください。レンダリングされません。

6. プレビューで確認する

開いている Studio でキャプションをスクラブして確認するようユーザーに伝えます。よくある調整項目：

• モバイルでテキストが小さすぎる／大きすぎる場合 → フォントサイズを調整します
• 単語の切り替わりが速すぎる場合 → combineTokensWithinMilliseconds の値を大きくします
• タイミングが合わない場合 → キャプションが音声と同じシーケンス内にあること、タイムスタンプがずれていないことを確認します
• 映像やプラットフォームのUIと重なる場合 → 位置を変更します（上部と下部を切り替えます）
• 表現に誤りがある場合 → Studio の Caption エディターで修正するか、インライン配列を編集します

ユーザーから MP4 の作成を依頼されない限り、レンダリングしないでください。