LucasLBrito/narracao-voz

ニューラル音声によるナレーション

パス: ${CLAUDE_PLUGIN_ROOT} はこのプラグインのルートです。変数が定義されていない場合、 ルートはこのスキルの「ベースディレクトリ」から2階層上のフォルダになります（<raiz>/skills/<skill>）。 スキルが ~/.claude/skills に直接コピーされた場合は、${CLAUDE_PLUGIN_ROOT}/skills の代わりに ~/.claude/skills を使用してください。

スクリプト: ${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py。pip install edge-tts と インターネット接続が必要です：テキストはMicrosoftの音声サービス（無料、キー不要）に送信されます。 ユーザーが外部に送信したくない内容を台本に含めないでください。

使用方法

N=${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py
python $N <pasta>                    # audio/cena01.mp3 ... + cena01.json (単語のタイミング)
python $N <pasta> --mostrar          # 発音置換後のテキストを表示（生成はしない）
python $N <pasta> --so 3 7           # シーン3と7のみを再生成
python $N <pasta> --tempos 3         # 「 2.41s  chave」... アニメーション同期用
python $N <pasta> --voz pt-BR-FranciscaNeural --rate +0%
python $N --vozes                    # ポルトガル語の音声一覧を表示

入力: <pasta>/roteiro.json、文字列のリスト（各シーンのセリフ）。音声とレートは video.json に設定できます（"voz"、"rate"）。デフォルト: pt-BR-AntonioNeural、+8%。

単発発話（ジングル、お知らせ、メッセージ、音声テスト）、フォルダや台本なし：

python $N --texto "Fala, pessoal! Hoje o assunto é Docker." --saida C:/tmp/vinheta.mp3
python $N --texto "..." --saida C:/tmp/f.mp3 --voz pt-BR-FranciscaNeural --rate +0%

基本の発音マップもここで適用されます。複数の単発発話がある場合は、roteiro.json を含むフォルダを使用することをお勧めします：発話ごとに1つのMP3が生成されます。

便利なpt-BR音声: pt-BR-AntonioNeural（男性、ビデオ用）、pt-BR-FranciscaNeural（女性）、 pt-BR-ThalitaMultilingualNeural（女性、英語の用語をより適切に処理）。完全なリスト: --vozes。 ポルトガルの音声（pt-PT-...）や他の言語の音声もあります。

話されるように書く

台本は機械によって読み上げられます。書かれたままではなく、話されるように書きましょう：

画面/書き言葉	台本内
1995	mil novecentos e noventa e cinco
porta 22	porta vinte e dois
SCP, AWS (略語の綴り)	S C P, A W S (文字を区切る)
git push -u origin main	git push, traço u, origin main
feat/login	feat barra login
.gitignore, .env	ponto gitignore, ponto env
~/.ssh/known_hosts	o arquivo known hosts
<, >, =	menos de, mais de, igual a

• 短い文。カンマは休止になります：リズムを作るために使用してください（「Conexão, troca de chaves, e autenticação.」）。
• 会話調：「bora entender」、「sabe aquela...?」、「e o melhor:」、「resumindo:」。
• シーンあたり25～45語（+8%で10～16秒）。
• 括弧やダッシュは避けてください：音声が適切に処理できません。

英語の用語の発音

pt-BR音声は英語をポルトガル語のように読みます。補正は、用語を正しく聞こえる綴りに置き換えることで、音声のみで行われます（台本と画面は元の単語のままです）。

• 開発用語の基本マップ（約70語）：scripts/pronuncia_base.json（git, commit, push, GitHub, branch, Docker, deploy, API, JSON, frontend, Python, npm...）。
• プロジェクトの用語：<pasta>/pronuncia.json、同じ形式。基本マップよりも優先されます。 基本マップの置換を無効にするには、用語をそれ自体にマッピングします：{"status": "status"}。
• 置換は単語全体に対して行われ、大文字小文字は区別されず、長い用語が最初に置換されます（「Pull Request」は「pull」の前）。

正しい綴りを見つける方法：

1. ブラジル人が声に出して読むように、強勢音節にアクセントを付けて書きます：commit → 「comít」、push → 「púch」、GitHub → 「guít-râb」、release → 「rilís」、cache → 「kéch」。
2. ハイフンを使用して部分を区切ります：「és-és-êitch」（SSH）、「ci-él-ái」（CLI）。
3. そのシーンのみを生成し（--so N）、聞いて調整します。ユーザーが何かが間違って聞こえたと言った場合は、プロジェクトの pronuncia.json で修正します。それが一般的な開発用語である場合は、pronuncia_base.json にも追加してください。そうすれば、今後のビデオで自動的に正しくなります。

アニメーションとの同期

各 audio/cenaNN.json には [{"t": 2.41, "palavra": "chave"}, ...] が含まれ、シーンの開始からの秒数です。この t（または0.2秒前）を、その単語を表す要素の登場タイミングとして使用します。単語はすでに置換された綴り（「comít」）で表示されますが、これは正常です。

よくある問題

症状	原因 / 解決策
No module named edge_tts	python -m pip install edge-tts
接続エラー / 403	インターネットなし、またはMicrosoftが何か変更した場合：pip install -U edge-tts
音声が速すぎる、または遅すぎる	--rate +0%（遅くする）または +15%（速くする）
用語の読み上げが間違っている	pronuncia.json（上記参照）
シーンが長すぎる（> 20秒）	セリフを2つのシーンに分割する