wjs-dubbing-video

wjs-dubbing-video

動画＋目標言語の SRT → 時間が同期した TTS 音声付きの *_<lang>_dub.mp4。**このスキルの処理は吹き替え音声トラックまでです。**映像への字幕焼き込みと音声ベッドのミキシングは次のスキルで行います（/wjs-burning-subtitles/render.py がすべてを 1 回の最終エンコードで合成します）。

使用する場合

• ユーザーが目標言語の SRT（例：entrevista.zh-CN.srt）を持っており、動画の音声をその言語にしたい場合。
• ユーザーが「中国語で吹き替え／吹き替え／吹き替えを作って／吹き替えて／ナレーションを入れて」と言った場合。
• ユーザーがカメラの前に複数の話者がいる動画を持っており、話者ごとに異なる音声を使いたい場合。

使用しない場合

• まだ SRT がない場合 → 先に /wjs-transcribing-audio を実行し、その後 /wjs-translating-subtitles を実行します。
• 原言語の TTS のみ（まれです。通常は先に翻訳します）→ それでもこのスキルを使用しますが、原言語の SRT を渡します。
• 音声を変更せず、字幕の焼き込みのみを行う場合 → /wjs-burning-subtitles に進みます。

話者数 — デフォルトは 1 人

**デフォルトでは、話者は 1 人だと想定します。**吹き替え全体に 1 つの音声を使います。これは、独白、Vlog、収録された講演、ナレーターのみのクリップ、そしてユーザーから依頼される動画の圧倒的多数に適しています。話者ダイアライゼーションを実行したり、SRT に [A]／[B] のタグを付けたり、複数話者の複雑さを持ち出したりしないでください。

複数話者に切り替えるのは、ユーザーが明示的に希望した場合のみです。「2 人」「インタビュー」「対話」「会話」「話者を分ける」「それぞれに別の声を使う」といった表現や、話者ダイアライゼーションを直接依頼された場合が該当します。その場合は、以下の「複数話者の吹き替え」セクションに従ってください。

動画の話者が 1 人か複数か判断できない場合は、まず 1 つの音声によるバージョンを作成してください。後から話者を分離するのは簡単です（吹き替えを再生成するだけです）。デフォルトで話者が混乱した出力を作ると、ユーザーの時間を無駄にします。

エンジンの振り分け — 音声 ID に基づく

scripts/dub.py は、音声 ID のプレフィックスに基づいて自動的に振り分けます。

音声 ID のパターン	エンジン	認証
zh_..._bigtts	Volcano（字节跳动豆包）TTS	VOLC_TTS_APPID + VOLC_TTS_ACCESS_TOKEN
zh-CN-...Neural／en-US-...Neural／など	edge-tts（Microsoft Edge ニューラル）	なし（無料）

北京語では、特に感情表現や思索的な内容において、Volcano のほうが edge-tts より明らかに自然です。Volcano の認証情報がない場合、またはデバッグ時の代替手段として edge-tts を使用してください。

Volcano TTS（中国語のみ）

エンドポイント：https://openspeech.bytedance.com/api/v3/tts/unidirectional（TTS 1.0 と 2.0 の両方で使用します。バックエンドは Resource-Id ヘッダーで選択されます）。

ヘッダー：

X-Api-App-Id:       (env: VOLC_TTS_APPID)         # 10-digit speech App ID
X-Api-Access-Key:   (env: VOLC_TTS_ACCESS_TOKEN)  # 32-char token from speech console
X-Api-Resource-Id:  volc.service_type.10029       # see resource ID note below
Content-Type:       application/json

認証情報の読み込み：ほとんどのユーザーは ~/code/.env に保存しています。各セッションの最初に、次の方法で読み込みます。

set -a; source ~/code/.env; set +a

Resource ID — 重要な注意点

ドキュメントには seed-tts-2.0 が「TTS 2.0（推奨）」のリソースとして記載されていますが、一般的な TTS-SeedTTS2.0 のコンソールインスタンスには、人気の *_bigtts 話者カタログ（爽快斯斯、高冷御姐、开朗姐姐など）が含まれていません。これらの話者を seed-tts-2.0 で使うと、200 code=55000000 "resource ID is mismatched with speaker related resource" が返されます。解決するには volc.service_type.10029（TTS 1.0 の V3 エンドポイント）を使用します。bigtts 話者の音質は同等で、すべてこのリソースで動作します。同梱の dub.py はデフォルトで volc.service_type.10029 を使用します。別のインスタンスを使っている場合は、VOLC_TTS_RESOURCE 環境変数で上書きしてください。

その他の 401／403 エラー：

• 401 code=45000010 "load grant: requested grant not found in SaaS storage" — App ID とキーの組み合わせはゲートウェイで有効ですが、ユーザーがこのリソースを有効化していません。火山引擎 → 语音技术 → 语音合成大模型 → 实例管理 に移動し、サービスを开通 する必要があります。回避策はありません。
• 403 code=45000030 — 話者がユーザーのインスタンスバンドルに含まれていません。

応答形式

ドキュメントの簡略な説明とは異なり、応答は単一の JSON オブジェクトでも生の音声バイト列でもなく、ストリーミング NDJSON です。各行は個別の JSON イベントで、data に Base64 エンコードされた MP3 チャンクが含まれます。最後のイベントには code: 20000000 が含まれます（この API の成功コードでは OK を意味します。code: 0 とは異なります）。デコードしたチャンクを連結すると、完全な MP3 になります。

import base64, json, requests
audio = b""
r = requests.post(url, headers=h, json=payload, timeout=60, stream=True)
for line in r.iter_lines():
    if not line: continue
    evt = json.loads(line)
    if evt.get("code") not in (0, None, 20000000):
        raise RuntimeError(f"code={evt.get('code')} {evt.get('message')}")
    if evt.get("data"):
        audio += base64.b64decode(evt["data"])

話者カタログ（volc.service_type.10029 で動作確認済み）

全リストは volcengine.com/docs/6561/1257544 にありますが、利用可否はインスタンスのバンドルによって異なります。一般的な SeedTTS-2.0 スターターインスタンスで動作を確認済みの女性の声は次のとおりです。

Speaker ID	中文名	Feel
zh_female_gaolengyujie_moon_bigtts	高冷御姐	思索的・スピリチュアルなコンテンツに最適です。 落ち着いた大人の雰囲気で、控えめです。
zh_female_kailangjiejie_moon_bigtts	开朗姐姐	温かみのある年上のお姉さんの語り口です。
zh_female_shuangkuaisisi_moon_bigtts	爽快斯斯	汎用性が高く、会話調の基準となる声です。
zh_female_linjianvhai_moon_bigtts	邻家女孩	カジュアルで、ライフスタイル系の Vlog に向いています。
zh_female_yuanqinvyou_moon_bigtts	元气女友	活気があり、明るい声です。
zh_female_meilinvyou_moon_bigtts	美丽女友	柔らかく、親密な雰囲気です。
zh_female_shuangkuaisisi_emo_v2_mars_bigtts	斯斯情感版	幅広い感情表現が可能です。明示的な感情指定とスケールを組み合わせてください。

ドキュメントには記載されていますが、一般的なインスタンスでは、次の音声を指定すると 55000000 が返されます。テストせずに利用できると約束しないでください。vv_uranus_bigtts、wenroushunv_moon_bigtts、qingxin_moon_bigtts、yingmaoxiaoyuan_moon_bigtts、tianxinxiaoling_moon_bigtts、shaoergushi_moon_bigtts。

音声パラメーター

speech_rate は Volcano 固有のスケール [-50, +100] で、値は変化率をパーセントで表します（つまり、-8 は 8% 遅くなります）。スクリプトでは --rate -8% をそのまま -8 として渡します。

便利な感情プリセット：

• emotion="calm"、emotion_scale=4 — 思索的な雰囲気です。このスキルが対象とするスピリチュアル系コンテンツでは、デフォルトとして使います。
• emotion="gentle" — より柔らかく、親密な雰囲気です。
• emotion="neutral" — 抑揚のない、情報を伝える声です。
• emotion="sad" — メランコリックな雰囲気です。控えめに使ってください。

コードを編集せずに、VOLC_TTS_EMOTION と VOLC_TTS_EMOTION_SCALE の環境変数で dub.py のデフォルト値を上書きできます。

このスキルでは Volcano の英語音声は設定されていません。英語には edge-tts（次のセクション）を使ってください。Volcano には英語話者（en_male_*_bigtts、en_female_*_bigtts）もありますが、通常、TTS-SeedTTS-2.0 のスターターインスタンスには含まれていません。動作を確認できたら、dub.py の音声ルーティングを拡張して追加してください。

edge-tts（Microsoft Edge ニューラル TTS）

無料で API キーは不要です。高品質ですが、Volcano ほど表現力はありません。プロジェクトの仮想環境にインストールしてください。セグメントごとに uvx から呼び出すことは避けてください。uvx を呼び出すたびに新しい Python プロセスが起動し、bing エンドポイントが数回の連続リクエスト後にレート制限をかけるか、接続を RST するため、レンダリングの途中で失敗します。

uv venv .venv
uv pip install --python .venv/bin/python edge-tts

その後、edge_tts.Communicate(...) を直接使い、失敗時の再試行ロジックを組み込んだ、単一の長時間実行 Python プロセスから呼び出してください。付属の scripts/dub.py はこの方法を使います。

音声の選択 — 元の話者に合わせる

言語をまたいで完全に一致する声はありません。性別、年齢の印象、声のトーンを慎重に選び、速度やピッチで調整してください。

中国語の音声（Volcano を優先し、edge-tts をフォールバックとして使用）

Volcano の zh_female_gaolengyujie_moon_bigtts（高冷御姐、落ち着いた声、speech_rate=-8）は、成熟した思索的な女性話者向けに検証されたベースラインです。このプロファイルでは、edge-tts のどの選択肢にも匹敵するか、それ以上です。それ以外の音声については、上記の Volcano 話者一覧を参照してください。

edge-tts の音声カタログ（中国語）：

音声	性別	標準的な印象
zh-CN-XiaoxiaoNeural	女性	温かみがあり、ニュース／小説向け
zh-CN-XiaoyiNeural	女性	生き生きとして若々しい
zh-CN-YunjianNeural	男性	情熱的で、スポーツ向け
zh-CN-YunxiNeural	男性	明るく、生き生きとしている
zh-CN-YunyangNeural	男性	プロフェッショナルなニュース読み上げ
zh-HK-HiuMaanNeural	女性	親しみやすく、やや成熟した印象
zh-TW-HsiaoChenNeural	女性	親しみやすい

英語の音声（edge-tts ニューラル音声、すべて多言語対応）

以下の音声はすべて、流暢なアメリカ英語／イギリス英語／オーストラリア英語を話します。*Multilingual* の音声は、スペイン語の名前やフランス語／イタリア語の借用語なども、発音を誤ることなく読み上げられます。

音声	性別	標準的な印象
en-US-AvaMultilingualNeural	女性	温かみ／成熟／思いやりの表現に最適 — 精神性やコーチングに関するコンテンツに自然です
en-US-EmmaMultilingualNeural	女性	陽気で会話調、若々しい
en-US-AndrewMultilingualNeural	男性	温かみがあり、自信に満ち、誠実
en-US-BrianMultilingualNeural	男性	親しみやすく、くだけた印象
en-US-AriaNeural	女性	明瞭なニュース読み上げ
en-US-GuyNeural	男性	落ち着いた男性のニュース読み上げ
en-GB-SoniaNeural	女性	イギリス英語の女性（RP）
en-GB-RyanNeural	男性	イギリス英語の男性（RP）
en-AU-WilliamMultilingualNeural	男性	オーストラリア英語の男性
fr-FR-VivienneMultilingualNeural	女性	英語も読み上げる、成熟したヨーロッパ系の女性

成熟した思索的なスペイン語の女性話者（このスキルの標準的なユースケース）に合わせる場合は、まず en-US-AvaMultilingualNeural を --rate -5% --pitch -3Hz で試してください。精神性に関するコンテンツには、ニュース調の Aria や Guy は使わないでください。事務的な印象になります。

選択の目安

• 成熟した思索的な女性話者（ヨガ／精神性／コーチング）： zh-CN-XiaoxiaoNeural を --rate=-8% --pitch=-10Hz で使用します（または Volcano の gaolengyujie）。
• 成熟したプロフェッショナルな男性： zh-CN-YunyangNeural を --rate=-5% で使用します。Yunjian／Yunxi はエネルギッシュすぎるため避けてください。
• 若く、くだけた話者： デフォルトのまま使用し、ピッチは変更しません。
• 欧米風の発音： *MultilingualNeural 音声のいずれかを使用します。

コミット前に必ずサンプルを確認する

🛑 チェックポイント — 全編の吹き替え前にサンプルを確認してください。 全編の吹き替えは最もコストがかかる工程です（TTS API 呼び出し＋atempo＋ffmpeg による多重化）。SRT 全体に対して dub.py を実行する前に、次の手順を行ってください。

1. テキストが最も長いキュー（最も時間調整が厳しいケース）と、短くカジュアルなキュー（声質の確認用）を1つずつ選びます。
2. 音声・速度・ピッチの組み合わせを3〜4種類、各3〜8秒で合成します。
3. ユーザーに音声パネルを見せて、「どの voice を選びますか？ rate/pitch は調整しますか？確認後に全編を実行します。」と尋ねます。明示的な選択を待ってください。

ユーザーが最初に特定の voice を指定しており、かつこの動画でその voice のサンプルをすでに聞いている場合に限り、このチェックポイントを省略できます。

スクリプトの scripts/sample_voices.py がある場合は（存在するとき）、まさにこの用途の簡易ラッパーです。ない場合は、吹き替えスクリプトと同じ Python ループを実行してください。

新しいアカウントで Volcano の voice を提示する前に、必ずスモークテストを実施してください。 まず、その speaker ID で約5語のキューを1つ合成します。スモークテストで空でない MP3 が返された場合に限り、ユーザーにその voice を提示してください。スモークテストが code=45000010（「grant not found」）で 401 エラーになった場合は、Volcano Engine のコンソールでリソースを開通する必要があることをユーザーに伝えてください。再試行すれば動作するかのように伝えてはいけません。

dub.py の実行

.venv/bin/python ~/.claude/skills/wjs-dubbing-video/scripts/dub.py [voice] [rate] [pitch]

# Mature Chinese contemplative female (Volcano):
.venv/bin/python ~/.claude/skills/wjs-dubbing-video/scripts/dub.py \
    zh_female_gaolengyujie_moon_bigtts -8% +0Hz

# Warm English caring female (edge-tts, multilingual):
.venv/bin/python ~/.claude/skills/wjs-dubbing-video/scripts/dub.py \
    en-US-AvaMultilingualNeural -5% -3Hz

# Default Chinese fallback (no Volcano creds needed):
.venv/bin/python ~/.claude/skills/wjs-dubbing-video/scripts/dub.py \
    zh-CN-XiaoxiaoNeural -8% -10Hz

このスクリプトは次の処理を行います。

1. SRT を読み込みます（*.zh-CN.srt、*.en.srt などを自動検出するか、--srt を渡します）。
2. 各キューにつき1つの MP3 を dub_work/seg_NN.mp3 に合成します。
3. ffprobe で各クリップの実際の長さを調べます。
4. 各キューについて、TTS が SRT の時間枠より長い場合は atempo フィルターを連結して速度を上げ、短い場合は後ろに無音を追加します。
5. SRT の空白区間と末尾の余りに無音セグメントを挿入し、出力音声の長さを元の動画と完全に一致させます。
6. -c:v copy で元の動画ストリームを保持しながら、新しい音声を *_zh_dub.mp4／*_en_dub.mp4 に多重化します。

出力：<source-stem>_<lang>_dub.mp4（例：entrevista_zh_dub.mp4）。これは次の手順である /wjs-burning-subtitles/render.py への入力となり、最終動画を合成します。

不自然な無音区間を埋める

同じ内容を話す場合、標準中国語はスペイン語の60〜80％の時間で済みます。キューごとにタイミングを厳密に合わせると、ほとんどのキューの末尾に不自然な2〜4秒の無音区間ができます。英語はスペイン語の約85％です。効果の小さい順に、次の3つの方法があります。

1. ネイティブの TTS 速度を落とします。 --rate を +0% から -12%、さらに -15% に変更すると、自然で聞き取りやすいゆっくりした音声になります（後からタイムストレッチするよりはるかに優れています）。まず -12% を試し、非常に思索的な内容では -15%／-20% を試してください。

2. キューごとに軽くスローストレッチします。 キューの TTS が時間枠より短い場合は、atempo を0.82×〜0.95×に設定します。dub.py はこれを自動で行います。余裕が0.5秒を超える場合は atempo = max(0.82, tts_dur / target_dur) を設定し、残りを無音で埋めます。0.82×を下回ると声が薬でぼんやりしたように聞こえ始め、0.92×を上回るとストレッチはほぼ聞き取れません。

3. 問題が大きいキューでは、ターゲット言語のテキストを長くします。 時間枠が長すぎて、0.82×にストレッチしても2秒を超える無音が残る場合、最も自然な対処法は翻訳を長くすることです。自然な中国語の助詞（「嗯，」「其实」「也就是说」「你知道」）を加えるか、圧縮された表現を本来の意味が伝わるように展開します。これは画面上の字幕を変更するため、実施前にユーザーの確認を取ってください。SRT を編集し、該当する dub_work/seg_NN.mp3 を削除してから dub.py を再実行し、それらのセグメントだけを再生成します。

これらの方法を組み合わせてください。ネイティブ速度を -12% にし、ストレッチで時間枠に合わせれば、約80％のケースに対応できます。テキストの拡張は、特に問題の大きい2〜3件に限定してください。

複数話者の吹き替え（オプトイン）

ユーザーがソースに複数の話者がいると明示した場合にのみ、このセクションを実行してください（「interview」「two people」「dialogue」「separate the speakers」「different voice for each」、または話者識別を直接依頼された場合）。

この条件に該当する場合は、話者ごとに異なる voice を使って吹き替えを生成し、誰が話しているかを聞き手が追えるようにします。方法は2つあります。

パス 1（カメラに映っている話者に推奨）：視覚的な話者分離

scripts/visual_diarize.py は、フレームごとに顔の口の動きを確認し、各キューに主な話者のタグを付けます。単体で動作し、API キーも音声フィンガープリントも不要です。

uv pip install --python .venv/bin/python mediapipe opencv-python

.venv/bin/python ~/.claude/skills/wjs-dubbing-video/scripts/visual_diarize.py \
    --video input.mp4 --srt input.en.srt \
    --out input.en.diarized.srt \
    --report diarization_report.json \
    --sample-fps 5 --num-speakers 2

仕組み：

1. 1 秒あたり N フレームをサンプリングします（既定値は 5）。
2. MediaPipe FaceLandmarker（Tasks API）を実行し、各フレームで最大 --num-speakers 個の顔を検出します。各顔につき 478 個のランドマークを使用します。
3. 顔ごとに、内側の上唇（idx 13）と内側の下唇（idx 14）の垂直距離から口の開き具合を測定します。
4. 顔を画面上の水平方向の位置（x 分位点）で分類し、左から右へ話者 A、B、... を割り当てます。
5. 各キューの [start, end] 区間について、話者ごとのフレーム間の口の開き具合の変化を合計します。最も動きが大きい話者をタグとして割り当てます。
6. [A]／[B] のプレフィックス付き SRT と、キューごとのスコアおよび信頼度比（最も高いスコア／2 番目に高いスコア）を含む JSON レポートを書き出します。

初回実行時に、FaceLandmarker モデル（約 3.6 MB）を /tmp/mp_models/face_landmarker.task にダウンロードします。

視覚的な判定は、テキストから推測するよりも明らかに優れています。 ある検証では、テキストに基づく手動ラベル付けでは話者ごとの分配が 6/50 でしたが、視覚的な話者分離では実際の分配が 29/27 であると判明しました。2 人が似たような話し方をするため、テキストからの推測は大きく外れていました。話者がカメラに映っている場合は、必ず視覚的な判定を優先してください。

信頼度の低いキューを抜き取り確認してください。 JSON レポートで confidence_ratio < 1.5 のキューは、判定が不確かです。通常、発話が重なっているか、話者が一時的にフレーム外にいます。吹き替えの前に手動で修正してください。

パス 2（代替手段）：手動でタグ付け

非常に短いクリップ（1～2 分）の場合、話者がカメラに映っていない場合、または視覚的な話者分離に失敗した場合：

1
00:00:00,000 --> 00:00:03,400
[A] So what about that AI rewrite thing?

2
00:00:03,400 --> 00:00:08,200
[B] Right — let me explain the workflow.

*.tagged.srt として保存してください。後続の /wjs-burning-subtitles による焼き込みには、タグのないクリーンな SRT を使用してください。

dub.py での音声の割り当て

--voice-map に speaker=voice のペアを指定します。位置引数の音声は、タグのないキューに使用される既定値です。

.venv/bin/python ~/.claude/skills/wjs-dubbing-video/scripts/dub.py \
    en-US-AndrewMultilingualNeural -3% +0Hz \
    --srt input.en.tagged.srt \
    --voice-map "A=en-US-BrianMultilingualNeural,B=en-US-AndrewMultilingualNeural"

音声を組み合わせる際のヒント：

• 同じ性別の 2 人： 聴き分けやすい音色の音声を選んでください。アメリカ人男性 2 人には Brian（カジュアル）＋ Andrew（温かみがある）の組み合わせが適しています。女性 2 人には Ava（温かみがある女性）＋ Emma（明るい女性）が適しています。
• 男女の組み合わせ： Ava ＋ Andrew は無難な組み合わせです。
• アクセントの違い： en-US- と en-GB- を組み合わせると、違いがはっきりします。
• 中国語： zh_female_gaolengyujie_moon_bigtts（成熟した声）＋ zh_female_kailangjiejie_moon_bigtts（温かみのある姉のような声）のように、Volcano の音声を組み合わせます。

制限事項

視覚的な話者分離は、次の場合に失敗します。

• 話者が話している間、常にカメラに映っていない場合。
• カメラの切り替えやズームにより、キュー間で顔の位置が安定しない場合。
• 3 人以上の話者が似たような水平方向の位置にいる場合（x 分位点による分類では粗すぎます。代わりに (x, y) を使った k-means に切り替えるか、音声ベースの話者分離を使用してください）。

音声のみの素材（ポッドキャスト、ナレーション）では、pyannote.audio または whisperx --diarize を使用してください。このスキルには、音声ベースの話者分離はまだ含まれていません。

出力

• <source-stem>_<lang>_dub.mp4 — 映像ストリームはソースからそのままコピーし、音声を時間調整済みの吹き替えトラックに置き換えた動画です。/wjs-burning-subtitles/render.py への入力として、そのまま使用できます。
• dub_work/seg_NN.mp3 — キューごとの TTS クリップです（再開やキュー単位での再生成に備えて保持されます）。

後続処理

• /wjs-burning-subtitles — 元の音声を小音量の背景音としてミックスする場合、SRT を焼き込む場合、またはその両方を行う場合に使用します。最終エンコードはそこで ffmpeg 1 回の実行で行われます（連続エンコードはありません）。その render.py に --video <source.mp4> --dub <source_lang_dub.mp4> [--srt <srt>] を渡してください。
• 吹き替えのみのファイル（*_<lang>_dub.mp4）は技術的には完成した動画で、そのまま公開できますが、吹き替えられた音声になっています。元の音声を下にミックスすると「プロによる翻訳」のような仕上がりになります。これは /wjs-burning-subtitles で行ってください。

アンチパターン

• ❌ キューごとに uvx edge-tts を1回呼び出すこと。 実行のたびに Python プロセスが起動し、レンダリング中に Bing のエンドポイントでレート制限がかかったり、RST が発生したりします。dub.py 内の永続ライブラリの経路を使用してください。
• ❌ 音声を聞かずに audio_source を信頼すること。 確定する前に、必ず30秒のクリップを試聴してください。
• ❌ atempo を0.82倍未満に引き伸ばすこと。 声が薬でぼんやりしたように聞こえ始めます。無音を追加するか、テキストを増やしてください。
• ❌ 単一話者の SRT に [A] を付けること。 時間の無駄になり、吹き替えも同じように聞こえます。デフォルトでは1つの音声を使用してください。
• ❌ ユーザーのインスタンスでスモークテストせずに、Volcano の音声が使えると約束すること。 ドキュメントには多数の音声が掲載されていますが、一般的な SeedTTS-2.0 のスターターバンドルでは code=55000000 エラーが発生します。見積もりを提示する前に、必ず5単語のスモークテストを合成してください。
• ❌ Volcano のレスポンスを1つの JSON ドキュメントとして解析すること。 レスポンスは NDJSON のストリーミング形式です。成功を示す終端コードは code=0 ではなく code=20000000 です。完全な MP3 を取得するには、base64 デコードした data チャンクを連結してください。