/narration-qa

name: narration-qa
description: "ElevenLabsで生成したナレーション音声の品質を自動検証するスキル。 「ナレーションチェック」「音声確認」「発音チェック」等のリクエストで発動。"
triggers:
  - ナレーションチェック
  - 音声確認
  - 発音チェック
  - narration-qa
  - ナレーション品質検証
  - TTS検証

Narration QA Skill

ElevenLabsで生成したナレーション音声の品質を自動検証するスキル。 **ナレーション生成時は必ずこのスキルのフローに従うこと。**

トリガー

• ナレーション生成後の品質チェック依頼
• 「ナレーションチェック」「音声確認」「発音チェック」
• **ナレーション生成を含むすべてのMV制作タスク**（自動適用）

---

Step 0: TTS入力テキストのルール（生成前に必ず適用）

英語IT用語の日本語化ルール

英語をそのまま残すとElevenLabsが誤読する。**全英語を日本語表記に変換してから生成する。**

| ルール | 例 | |------|-----| | 定着カタカナがあればそれを使う | GitHub→ギットハブ, Slack→スラック, Gmail→ジーメール, Google Drive→グーグルドライブ | | カタカナ音写が不自然→日本語に意訳 | TODO→タスク, workflow→ワークフロー | | ブランド名はカタカナ | Claude Code→クロードコード（中黒なし）, LINE→ライン | | 略語はひらがな読み | AI→えーあい, PMO→ぴーえむおー, PPTX→パワーポイント | | 固有名詞が誤読される場合→一般語に置換 | Claude Code→AIエージェント, GitHub Actions→自動ワークフロー |

⚠️ 過剰ひらがな化の禁止（重要）

**全文ひらがな化はTTSモデルを壊す。** PersonalPMODemo v3の実験で、以下が確認された:

• `ぴーえむおー` → ElevenLabsが「ピアノ」と発音
• `えーあい` → 「Eoi」と発音
• 全ひらがな文 → リズム崩壊、意味不明な発音

**正しいアプローチ**: 自然な漢字かな混じり文をベースに、**既知の誤読漢字のみ**をひらがな化する。

漢字のひらがな化ルール（選択的に適用）

ElevenLabs eleven_multilingual_v2 は特定の漢字を誤読する。**以下のパターンに該当する漢字のみ**ひらがなに置換する。それ以外の漢字はそのまま残す。

| 誤読パターン | 原因 | 対策 | |------------|------|------| | 返信→阪神 | 音が近い漢字に化ける | 「へんしん」にひらがな化 | | 受信→閉める | 漢字誤読 | 「届いた」等の平易な表現に言い換え | | 議事録→石立 | 漢字誤読 | 「ぎじろく」にひらがな化 | | 各→夫は | 単漢字の誤読 | 「それぞれの」に言い換え | | 即座に→危機座に | 漢字誤読 | 「すぐに」に言い換え | | 承認→チョンキン | 中国語発音混入 | 「しょうにん」にひらがな化 | | 税理士→推理師 | 中国語発音混入 | 「ぜいりし」にひらがな化 | | 成果→成功 | 類似音 | 「せいか」にひらがな化 | | マッキンゼー→松銀瀬 | 固有名詞の崩壊 | 「コンサル」等の一般語に言い換え |

**原則**: 上記テーブルに該当する漢字のみひらがな化。それ以外は自然な漢字かな混じり文のまま残す。自然な漢字かな混じり文 > 安全のために全ひらがな化（TTSモデルが壊れるため）。

ひらがな化すべきか？ — 決定木

漢字を見つけた
→ 上記の誤読リストに該当する → ひらがな化する
→ リストにないが不安
  → ElevenLabsで1クリップだけテスト生成 → Gemini検証
    → 誤読あり → ひらがな化 or 平易な表現に言い換え → リストに追記
    → 問題なし → 漢字のまま残す
→ リストにない＋一般的な漢字 → 漢字のまま残す（過剰ひらがな化しない）

数字の展開ルール

数字は全てひらがなで書く:

• `7つの` → `ななつの`
• `8種類` → `はっしゅるい`
• `12,800円` → `いちまんにせんはっぴゃくえん`
• `95%` → `きゅうじゅうごパーセント`

避けるべきパターン

| NG | 理由 | OK | |----|------|-----| | 英語をそのまま残す | ElevenLabsが誤読 | 全てカタカナ/ひらがな化 | | 「トゥードゥー」「クロード・コード」 | 日本語として不自然 | 「タスク」「クロードコード」 | | 同一用語の表記揺れ | 混乱 | 統一表記 | | 1文が長すぎる | 早口/尺超過 | 7文字/秒を目安に分割 |

---

Step 1: 原稿の事前チェック（生成前）

1a. Step 0のルール適用確認

原稿テキストに以下がないことを確認:

• [ ] 英語のまま残っている単語
• [ ] 誤読リスクのある漢字（上記テーブル参照）
• [ ] 展開されていない数字
• [ ] 同一用語の表記揺れ

1b. 尺チェック

• 各セグメントのテキスト文字数から推定発話時間を算出（目安: 日本語7文字/秒）
• シーン尺（end - start）と比較
• **atempo 1.35x を超える場合は原稿を短縮**すること（それ以上の加速は不自然）
• 略語をフル読み（えーあい等）にすると尺が伸びる → 短い窓のシーンは特に注意

1c. 文体統一チェック

• 「です・ます」調で統一されているか
• 体言止めが混在していないか（Openingのキャッチコピーは例外OK）
• 主語の省略が自然か

---

Step 2: 音声生成

ElevenLabs設定

voice_settings = {
    "stability": 0.70,       # 0.75以上だと棒読み感
    "similarity_boost": 0.80,
    "style": 0.10,            # 0.15以上だと抑揚過多
    "use_speaker_boost": True
}
model_id = "eleven_multilingual_v2"

生成後の尺チェック

# 各セグメントの尺を確認
for f in data/narration/s*.mp3; do
  dur=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$f")
  echo "$f: ${dur}s"
done

• `ratio = audio_duration / scene_window` を計算
• ratio > 1.35 → **原稿を短縮して再生成**（atempo で無理に収めない）
• ratio <= 1.35 → `ffmpeg -af "atempo={ratio}"` で速度調整

---

Step 3: Gemini Flash 書き起こし検証（必須）

**生成後、必ず全セグメントをGemini Flashで書き起こし検証する。省略不可。**

実行コード

from google import genai
import json, os, time

client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY"))

with open("data/narration_script.json") as f:
    segments = json.load(f)

results = []
for seg in segments:
    sid = seg["id"]
    audio_file = client.files.upload(file=f"data/narration/{sid}.mp3")
    response = client.models.generate_content(
        model="gemini-3-flash-preview",
        contents=[
            "この日本語音声を正確に書き起こしてください。句読点も含めて。テキストのみ返してください。",
            audio_file
        ]
    )
    transcription = response.text.strip()
    # 原稿と照合
    print(f"{sid}:")
    print(f"  Script: {seg['text']}")
    print(f"  Heard:  {transcription}")
    results.append({"id": sid, "script": seg["text"], "heard": transcription})
    time.sleep(1)

# 結果をJSONに保存
with open("data/narration_qa_results.json", "w") as f:
    json.dump(results, f, ensure_ascii=False, indent=2)
print(f"\nQA results saved to data/narration_qa_results.json")

**モデル選択**: `gemini-3-flash-preview` を使用（2.0/2.5 Flash より日本語音声認識精度が大幅に向上）。

NG判定基準

| 深刻度 | 条件 | 対処 | |--------|------|------| | **Critical** | 意味が完全に変わる（返信→阪神、議事録→石立） | 原稿のひらがな化 → 再生成 → 再検証 | | **Major** | 固有名詞が別の単語に化ける（クロードコード→黒度思うこと） | 表現を言い換え → 再生成 | | **Minor** | 音は近いが漢字表記が異なる（同期→登記、成果物→性格物） | Gemini STTの限界。人間の耳で許容範囲なら**OK** | | **Pass** | 書き起こしと原稿の意味が一致 | そのまま使用 |

再生成ループ — 決定木

Gemini検証でNGが出た
→ Critical（意味が変わる）
  → 原稿のひらがな化 or 言い換え → 再生成 → 再検証
  → 2回目もNG → 文章構造自体を大幅に書き直す → 再生成 → 再検証
  → 3回目もNG → そのセグメントを削除 or シーンからナレーションを外す
→ Major（固有名詞崩壊）
  → 一般語に置換（例: クロードコード→AIエージェント）→ 再生成 → 再検証
→ Minor（漢字表記が異なるだけ）
  → Gemini STTの限界の可能性あり。実音声を聴いて許容範囲なら Pass とする（自動Passにしない）
→ Pass → そのまま使用

**最大3ラウンド**。3回でもCriticalが残るなら該当セグメントのナレーションを諦める。

---

Step 4: 音量バランス調整 & 最終ミックス

音量ルール

| トラック | volume | 備考 | |---------|--------|------| | ナレーション | **1.5** | メインコンテンツ。BGMより明確に大きく | | BGM | **0.06** | ナレーションの邪魔をしない。存在感は感じる程度 | | BGM (ナレーションなし区間) | 0.15 - 0.20 | Opening/Closingなどナレーションがない区間はBGMを上げてOK |

**判定**: 実音量比でナレーションがBGMの4倍以上であること。

⚠️ amix禁止 — amerge+pan を使う

`ffmpeg amix` は入力をN分割して正規化するため、volume設定が無視される。 **必ず `amerge + pan` を使うこと。**

# ナレーション全体をタイミング配置
# (adelay で各セグメントを配置 → amerge で結合)

# 動画 + BGM + ナレーションを一発ミックス (amerge + pan)
ffmpeg -y \
  -i out/video.mp4 \
  -i data/bgm.mp3 \
  -i data/narration_mix.mp3 \
  -filter_complex "\
    [1:a]volume=0.06,afade=t=out:st={total-4}:d=4[bgm];\
    [2:a]volume=1.5[narr];\
    [bgm][narr]amerge=inputs=2,pan=stereo|c0=c0+c2|c1=c1+c3[out]" \
  -map 0:v -map "[out]" -c:v copy -shortest \
  out/video_narrated.mp4

**amix vs amerge の違い**:

• `amix=inputs=2`: 各入力を ÷2 に正規化 → BGM 0.06×0.5=0.03, ナレーション 1.5×0.5=0.75 → 比率は保つが全体音量が低下
• `amerge + pan`: