language-swap

/pika:language-swap

以下のツールは Pika MCP ツールです。名前にプレフィックスは付いていません。Pika MCP に対してセッションで公開されている任意のプレフィックスを付けて呼び出してください。

元の話者の声を保ちながら、動画を別の言語に翻訳して吹き替えます。パイプライン：吹き替え（ワーカー呼び出し1回）→ リップシンク（デフォルトでオン）→ 翻訳先言語の字幕または二言語字幕を焼き付けます。

吹き替えワーカーは、1回の呼び出しで大部分の処理を担います。文字起こしと翻訳を行い、サーバー側で各話者の声を保ったまま（個別のクローン作成ステップは不要）、音声と映像が完全に同期した動画を返します。そのため、文字起こし、クローン作成、TTS、置き換えを手動で連続して行う必要はなく、再生時間のずれを手作業で調整する必要もありません。

セグメント分割／多言語吹き替え（範囲ごとの言語指定）

1本の動画の異なる部分に異なる言語を割り当てたい場合（例：前半はスペイン語、後半は日本語）、または一部のセクションのみ翻訳し、残りは元の音声のままにしたい場合に使用します。どちらも同じ仕組みです。各セグメントに言語を指定したタイムラインを作成し、どのセグメントにも含まれない範囲は元の音声のままにします。

dub_video では target_language の代わりに segments プランを指定します（どちらか一方だけを渡してください。相互に排他的です）。

dub_video(source_video_url=<video_url>, segments=[
  {start_s: 0,  end_s: 30, target_language: "es"},
  {start_s: 30, end_s: 60, target_language: "ja"}
])

プランの作成方法：ユーザーが範囲を選ぶには、まずコンテンツがどこにあるか把握する必要があります。そのため、最初に文字起こしを行ってください。extract_audio_from_video で音声を抽出し、続いて transcribe_audio(audio=<audio_url>, timestamps=true) を実行します。タイムスタンプ付きのセグメントをユーザーに提示し、どの時間範囲をどの言語にするか指定してもらいます。その後、segments[]（秒単位、順序どおり、重複なし）を組み立てて、dub_video を1回だけ呼び出します。独立した「動画理解」ツールはありません。タイムスタンプ付きの文字起こしが理解のステップを担います。

セグメント分割パスの動作：

• すべてのセグメントで同じ声を使用します。 元の話者の声を一度だけクローンし、すべてのセグメントで、どの言語であっても、その同じクローン音声で発話してからクローンを破棄します。これらはすべて1回の dub_video 呼び出し内で行われます。自分で声をクローンしたり削除したりする必要はありません。
• 元の音声を維持します。 セグメントでカバーされていない時間範囲は、元の音声（声と背景音）をそのまま再生します。動画の一部のみを翻訳するには、翻訳したい部分だけを指定してください。
• 長さを固定します。 出力の長さは元の動画と完全に同じです（各吹き替え範囲は指定された時間内に収まるよう速度調整されます）。そのため、境界は元のタイムラインと一致します。
• プロバイダー。 範囲ごとの混在言語指定では、常に音声クローン作成経路が自動的に使用されます。動画全体を1回で吹き替える経路では範囲ごとに言語を混在させられないため、セグメント分割プランで単一呼び出しのプロバイダーを強制しないでください。指定したすべての言語が音声クローン作成経路でサポートされている必要があります。サポートされていない言語がある場合は、エラーを提示して references/language-coverage.md を参照してください。
• 結果。 吹き替え動画の結果は同じです。target_language には対象範囲の言語がカンマ区切りで返されます（例："spa,jpn"）。トラックが多言語のため、単一の transcript_language は返されません。リップシンク（ステップ2、デフォルトでオン、5分以下）は、吹き替え後の動画全体に引き続き適用されます。字幕（ステップ3）には、返された多言語の subtitles[] を caption_mode="manual" で使用してください。自動での再文字起こしでは、混在トラックの言語を1つに特定できません。

dub_video が segments を拒否する場合（セグメント分割に対応していない古いデプロイメント）、各範囲を個別に単一言語で吹き替えてから連結してください。ただし、利用可能な場合は1回の呼び出しで行うセグメント分割パスを優先してください。

動作のデフォルト設定

• 対象言語：--to <language> で指定する必要があります。言語コードを推奨します：es、fr、ja、de、pt-BR、zh-Hans。吹き替えワーカーは ISO/BCP-47 に類似したタグを受け付け、ElevenLabs を呼び出す前にスクリプト／地域のサブタグを正規化します（例：zh-Hans → zh、zh-Hant-TW → zh）。
• リップシンク：デフォルトでオンです。翻訳音声に合わせて話者の口の動きを再調整します（fal sync-lipsync。ポートレート画像アニメーターとは異なる、フル動画のリップマッチャーです）。映像にカメラの前に映る顔がない場合や、相応のコスト（sync-2-pro ティアで約 $4/min）を避けたい場合は、--no-lipsync を指定してスキップします。対象は長さが 5 min 以下の動画のみです — edit_lipsync は上流で 300 s に上限が設定されているため、それより長いソースではリップシンクが自動的にスキップされます（Step 2 を参照）。吹き替え自体に長さの制限はありません。
• BGM／バックグラウンドミュージック：デフォルトで保持されます。吹き替え音声は、元の音楽／効果音のトラックに重ねられます。翻訳のみの出力にするには、--no-bgm を指定します。ワーカーは元の音楽を削除し、翻訳された音声のみを残します（drop_background_audio=true）。
• 字幕：デフォルトで対象言語の字幕が動画に焼き込まれます。ユーザーがバイリンガル字幕／二言語字幕を求めた場合は、対象言語（翻訳）の行を上に、ソース言語（原文）の行を下に焼き込みます。吹き替え後は翻訳された音声が実際に話される内容なので、こちらを主となる行にし、原文は補助的な参照として表示します。
• バイリンガル字幕：ユーザーが --bilingual-subtitles を指定するか、「バイリンガル字幕」、「二言語字幕」、「2 言語の字幕」、「原文＋翻訳字幕」、「双语字幕」、または「原文+译文字幕」を求めた場合に有効にします。
• 言語の対応状況：言語サポートについて質問された場合や、上流で言語関連のエラーが発生した場合は、references/language-coverage.md を参照してください。通常のユーザーへの返信では、プロバイダー固有の言語リストの詳細を先回りして提示しないでください。

生成・使用される状態変数

• video_url：入力 — 位置引数から取得
• source_input_url：元の位置引数の URL — video_url が再ホストされた場合に備えて、診断用に保持
• target_language：テキスト — --to <language> から取得
• with_lipsync：ブール値 — デフォルトは true。--no-lipsync を指定した場合のみ false
• no_bgm：ブール値 — --no-bgm の指定時に true（drop_background_audio=true に対応）
• bilingual_subtitles：ブール値 — ユーザーがバイリンガル字幕／二言語字幕を求めた場合に true
• dubbed_video_url：吹き替え済みの A/V 同期動画 — Step 1 で生成
• dub_subtitles：吹き替え結果に含まれる任意の対象言語のタイムコード付き字幕 — Step 3 で使用
• source_subtitles：吹き替え結果に含まれる任意のソース言語のタイムコード付き字幕 — バイリンガル字幕の場合に Step 3 で使用
• dub_transcript_srt：任意の対象言語の SRT — 確認／デバッグ用に返却
• source_transcript_srt：任意のソース言語の SRT — 確認／デバッグ用に返却
• source_transcript_language：吹き替え結果に含まれる任意のソース言語コード
• lipsynced_video_url：口の動きを再調整した吹き替え動画 — リップシンクを実行した場合に Step 2 で生成
• caption_target_video_url：字幕を焼き込む前の最終映像 URL
• final_video_url：対象言語の字幕を焼き込んだ動画 — Step 3 で生成

Step 0 — 入力を解析する

必須：

• 位置引数 video_url — https://... である必要があります
• --to <language> — 対象言語（自由記述または BCP-47 コード）

任意：

• --no-lipsync — デフォルトの口の動きの同期手順をスキップします。
• --no-bgm — 翻訳のみの出力にします。元の音楽／効果音の音声トラックを削除します。
• --bilingual-subtitles — 原文言語と対象言語の字幕を焼き付けます。

明示的なフラグがなくても、ユーザーの表現から bilingual_subtitles=true を推定してください。

--to が指定されていない場合は、ユーザーが異なる部分に異なる言語を指定したい場合、または一部のセクションだけを翻訳したい場合を除き、処理を停止してユーザーに確認してください。これらは範囲ごとのセグメント化パスです（上記の「セグメント化／多言語吹き替え」を参照）。このパスでは --to の代わりに segments プランを使用します。

セグメント化パスでは、まず時間範囲のプランを作成します。extract_audio_from_video で音声を抽出し、次に transcribe_audio(audio=<audio_url>, timestamps=true) でタイムスタンプ付きの文字起こしを行います。タイムスタンプ付きのセグメントをユーザーに提示し、各時間範囲に対応する言語を segments[] に記録します。

出力：video_url、target_language、with_lipsync（デフォルトは true）、no_bgm（デフォルトは false）、bilingual_subtitles（デフォルトは false）。

Step 1 — 動画を吹き替える（状態：dubbed_video_url）

以下を指定して dub_video を呼び出します：

• source_video_url — <video_url>
• target_language — <target_language>（ISO／BCP-47 形式に準じたタグ。例：es、pt-BR、zh-Hans）
• source_language — "auto"
• drop_background_audio — no_bgm が設定されている場合のみ true。それ以外は省略します（元の音楽の音声トラックを保持します）

dub_video はプラグイン専用の Pika MCP ツールです。claude.ai コネクターの提供機能はプラグインのビルドに遅れることがあるため、コネクターのセッションでは利用できない場合があります。ツール一覧にない場合は、その旨を伝え、別のツールで代用しないでください。

dub_video はワーカーによって処理されます。応答が {task_id, status} の場合は、task_status を completed になるまでポーリングし、その後、結果から吹き替え済み動画（動画ソースの場合は video_url、音声ソースの場合は audio_url）を取得します。また、省略可能な subtitles[]、transcript_srt、transcript_language も取得してください。これらは吹き替えワーカーが生成した対象言語の文字起こしメタデータで、Step 3 で使用します。

バイリンガル字幕を付ける場合は、省略可能な source_subtitles[]、source_transcript_srt、source_transcript_language も取得してください。これらの原文言語の文字起こしフィールドは、取得できる場合にのみ利用できます。文字起こしフィールドがなくても、吹き替え済みメディアは有効です。

ソースをワーカーが取得できない場合： ソース URL を取得できないために dub_video が失敗した場合、特に HTTP 403／4xx、ホットリンク保護、ユーザーエージェントが制限されているホスト（Wikimedia／ニュース CDN）、または「Access Denied」エラーが発生した場合は、同じ呼び出しを繰り返さないでください。まず別の場所に再ホストします。

1. 通常のブラウザー／ダウンロード手段、または実際のユーザーエージェントを設定した HTTP クライアントを使って、クライアント／ホスト環境にソースのバイト列をダウンロードします。
2. ダウンロードしたファイル名、MIME タイプ、正確なバイトサイズを指定して upload_asset を呼び出し、返された署名付き URL にバイト列をアップロードします。
3. source_input_url = <original URL> を設定し、video_url を返された Pika CDN の public_url に置き換えます。CDN URL を手動で組み立てないでください。
4. Pika CDN の URL に対して Step 1 を一度だけ再試行します。それ以降のすべてのステップでは、更新後の video_url を使用してください。

クライアント／ホストでもソースのバイト列をダウンロードできない場合は、処理を停止し、ホストが直接取得をブロックしていることをユーザーに伝え、ファイルをアップロードするか別の URL を提供するよう依頼してください。

出力：dubbed_video_url、dub_subtitles、source_subtitles、dub_transcript_srt、source_transcript_srt、source_transcript_language。

ステップ 2 — リップシンク（状態：lipsynced_video_url）

デフォルトで有効です。--no-lipsync が渡された場合は完全にスキップします（その場合、ステップ 3 では dubbed_video_url に字幕を付けます）。

5 分の厳格な上限 — 呼び出す前に長さを確認してください。 edit_lipsync は上流（sync.so）で300 秒（5 分）の音声上限を適用しており、それを超える長さは課金前に invalid_input で拒否されます。すべての variant ティアで上限は同じなので、ティアを順に切り替えても解決しません。吹き替え動画の duration_seconds（ステップ 1 で返されます）が 300 を超える場合は、リップシンクを完全にスキップし、ステップ 3 で dubbed_video_url に直接字幕を付けて、5 分を超える動画ではリップシンクを利用できないことをユーザーに伝えてください（吹き替え自体は長さを問わず利用できます）。以下のリップシンク呼び出しは、duration_seconds ≤ 300 の場合にのみ実行してください。

まず費用について伝えてください。 リップシンクが主な費用（v2-pro ティアで約 $4/分）となります。呼び出す前に、吹き替え動画の duration_seconds（ステップ 1 で返されます）を使い、cost_usd = duration_seconds / 60 * 4 で見積もってください。短いクリップを 1 分に切り上げないでください。7 秒のクリップは約 $4 ではなく、約 $0.47 です。実際の長さと按分した見積もりを含む一行の案内をユーザーに送ってください。例：「リップシンクを実行します — 動画は約 7 秒、$4/分で見積もり約 $0.47 です（スキップするには --no-lipsync を渡してください）。これから開始します。」duration_seconds がなく、信頼できるメディアの長さも取得できない場合は、金額をでっち上げずに $4/分 の料金を伝えてください。その後、すぐに呼び出しを実行します。これは事前案内であり、承認を求めるものではありません。

audio_url は指定せず、edit_lipsync(video_url=<dubbed_video_url>) を呼び出してください。ワーカーは、吹き替え動画に埋め込まれた翻訳済み音声に同期します。音声を抽出して再度渡さないでください。（variant のデフォルトは v2-pro で、フォールバックとして sync-3 / v2 を使用します。）

出力：lipsynced_video_url（レスポンスの url から読み取ります）。このステップを実行した場合、ステップ 3 では dubbed_video_url ではなく、この動画に字幕を付けます。そうしないと、リップマッチングが失われます。

ステップ 3 — 対象言語の字幕を焼き込む（状態：final_video_url）

最終動画に字幕を付け、読みやすい字幕が表示されるようにします（一般的な「翻訳＋字幕」の期待に応えます）。リップシンクを実行した場合（デフォルト）は caption_target_video_url に lipsynced_video_url を設定し、--no-lipsync によりスキップした場合は dubbed_video_url を設定します。

このリクエストが Double 動画／分割画面の比較フローの一部である場合は、先に Double 動画を作成し、caption_target_video_url に最終的に合成された動画の URL を設定します。Double 動画を合成する前に片方のパネルだけに字幕を焼き込まないでください。二言語字幕の焼き込みは、最終的な映像に対して一度だけ行います。

caption_target_video_url に対して add_captions を一度呼び出します。

bilingual_subtitles=true の場合、両方のトラックが利用可能であれば、手動の二言語モードを使用します：add_captions(video_url=<caption_target_video_url>, caption_mode="manual", subtitles=<dub_subtitles>, secondary_subtitles=<source_subtitles>, language=<target_language>, secondary_language=<source_transcript_language if available>, secondary_subtitles_position="below", style="branded-space-mono", position="bottom") を呼び出します。対象言語（翻訳）の行がプライマリの subtitles となり、上に表示されます。原文であるソース言語の行は参照用のセカンダリとして、その下に表示されます（secondary_subtitles_position="below"）。吹き替え後に実際に話されるのは翻訳された音声なので、こちらを先に表示します。dub_video が両方の字幕トラックを返す限り、これはすべての吹き替えワーカーのプロバイダーブランチで機能します。

bilingual_subtitles=true でも source_subtitles がない場合は、対象言語の字幕のみを使用し、吹き替えプロバイダーからソースの文字起こしを取得できなかったことをユーザーに伝えます。最終的な吹き替え音声を再文字起こしして、ソース言語の行を作り出さないでください。その音声はすでに対象言語です。

対象言語のみの字幕では、吹き替えワーカーが返した対象言語の字幕を優先します：dub_subtitles が空でない場合は、add_captions(video_url=<caption_target_video_url>, caption_mode="manual", subtitles=<dub_subtitles>, language=<target_language>, style="branded-space-mono", position="bottom") を呼び出します。手動モードでは、重複する文字起こし処理を省略し、吹き替えプロバイダーの対象言語のテキストを保持します。

dub_subtitles がない、空である、または add_captions に拒否された場合は、自動モードにフォールバックします：add_captions(video_url=<caption_target_video_url>, caption_mode="auto", language=<target_language>, style="branded-space-mono", position="bottom") を呼び出します。自動モードでは吹き替え音声を再文字起こしします。余計な時間がかかり、CJK／固有名詞にずれが生じる可能性があるため、フォールバックとしてのみ使用してください。

ユーザーがより目立つスタイル（tiktok／hormozi／karaoke）を希望した場合を除き、style="branded-space-mono" を使用します。ユーザーが字幕なしの音声のみの吹き替えを明示的に希望した場合に限り、このステップをスキップします。

出力：final_video_url（レスポンスの url から取得）。

ステップ 4 — 返却

ユーザーが確認できるよう、final_video_url と翻訳済みの文字起こし（dub_transcript_srt／吹き替え結果から取得）を返します。

二言語字幕版を提案してください。 この実行で対象言語のみの字幕を焼き込み（bilingual_subtitles=false）、ソースの文字起こしが利用可能（source_subtitles が空でない）な場合は、返信の最後に、原文と翻訳の字幕を上下に並べた二言語版も希望するか尋ねます。例：「原文と翻訳の字幕を上下に並べた二言語版も必要ですか？追加できます。」希望する場合は、同じ caption_target_video_url（字幕を焼き込む前の映像）に対して、ステップ 3 を二言語手動モードで再実行します。再吹き替えや再リップシンクは不要で、字幕の焼き込みだけを変更し、新しい final_video_url を返します。二言語字幕がすでに焼き込まれている場合（bilingual_subtitles=true）、または source_subtitles がない場合は提案を省略します。ソースの文字起こしがなければ二言語版は作成できません（吹き替え音声はすでに対象言語です）。提供できないものを提案しないでください。

失敗モード

分類	発生条件	対処方法	フォールバック
ソース URL をワーカーが取得できない	dub_video が 403 / 4xx を返す、ホットリンク / UA による取得制限で失敗する、または公開 HTTPS URL に対して「Access Denied」が返される	クライアント／ホスト環境でソースのバイトデータをダウンロードし、upload_asset で Pika にアップロードして、video_url を Pika の CDN URL に置き換えた後、ステップ 1 を 1 回だけ再試行します	ローカルでのダウンロードも失敗した場合は、ファイルをアップロードするか、別の URL を指定するようユーザーに依頼します
対象言語が追加で必要	対象が広東語（yue / cantonese / zh-HK）、タイ語、ヘブライ語、ペルシャ語、スロベニア語、カタルーニャ語、ノルウェー語ニーノシュク、またはアフリカーンス語である	対応しています。通常どおり、対象言語を指定して dub_video を呼び出します。元の話者の声は保持されます	これらの言語では、BGM は保持されません（吹き替え音声のみ）
吹き替えの呼び出しに失敗（取得可能性の問題ではない）	未対応の対象言語、プロバイダー／ワーカーの 5xx、task_status の status: failed など、別の理由で dub_video がエラーになる	エラーをユーザーに伝えます。メッセージが言語に関するものであれば、references/language-coverage.md を確認して対応するタグを提案します。それ以外の場合は、再試行を提案します。フォールバック用の手動チェーンはありません。吹き替えが唯一の処理経路です	なし。エラーを返し、吹き替えなしの動画を黙って生成しないでください
吹き替えで音声が検出されない	無音の動画で、翻訳する内容がありません	ユーザーに「動画内で検出可能な音声がありません。翻訳する内容がありません」と伝えます	なし
元の声を保持できない	上記の言語では、ソースが短すぎる、またはノイズが多すぎて元の話者の声を保持できない	エラーを伝え、よりクリアで長いソースクリップを提供するようユーザーに依頼します	なし。別の声を使うのではなく、吹き替えを失敗させます
リップシンクのソースが長すぎる	吹き替え動画が 5 分を超えているため、edit_lipsync が invalid_input で拒否する（sync.so の上限は 300 秒）。すべてのバリアント層で上限は共通のため、再試行しても解決しません	まずステップ 1 の duration_seconds を確認し、300 を超える場合はリップシンクをスキップします。dubbed_video_url に直接字幕を付け、リップシンクの上限は 5 分であることをユーザーに伝えます	口の動きが合っていない吹き替え動画
リップシンクのステップに失敗	edit_lipsync がエラーになる（明確な顔のトラックがない、プロバイダーの 4xx など）	variant の層（v2-pro → sync-3 → v2）を順に試します。すべて失敗した場合は、口の動きを合わせずに吹き替え動画を返し、その旨をユーザーに伝えます	口の動きが合っていない音声置換済み動画
字幕の言語が誤っている	ステップ 3 の自動文字起こしで言語が誤検出される	明示的な language タグを渡します。dub_subtitles がある場合は、自動処理の代わりに caption_mode="manual" を使用します	手動の subtitles[]
バイリンガル字幕のソース行を利用できない	ユーザーがバイリンガル字幕を求めているが、source_subtitles が存在しない	対象言語の字幕を使用し、ソースの書き起こしを利用できなかったことを説明します	対象言語の字幕のみ