| name | viewer-voice |
| description | Use when 承認済みベンチマーク競合のコメントを収集・分析して視聴者インサイトを抽出したいとき。「視聴者の声」「コメント分析」「視聴者が求めていること」「コメント調査」「ユーザーリサーチ」「TTP の語彙版」など。/audience-persona や /viewing-scene の前提データを作る任意後続スキルとして使用すること |
Overview
承認済みベンチマークチャンネルの1万再生以上の動画から YouTube Data API でコメントを取得し、
感情・利用シーン・リクエスト・キャラ愛着の4軸で分析する。
/channel-new の標準フローでは実行せず、コメントを含む視聴者インサイトが必要になった時点で明示的に実行する。
TTP 原則（ベンチマーク参照）
視聴者の声分析は TTP（徹底的にパクる）の語彙版。
ベンチマーク競合のコメントから利用シーン・感情表現・リクエストの 型 を抽出し、
自チャンネルが応えるべきインサイトの初期セットとして転写する。
独自インサイトは、転写した型をベースに加える順序を取る。
実行フロー
Phase 1: コメント取得（スクリプト実行）
uv run yt-benchmark-comments --force
スクリプトが自動で以下を実行:
- ベンチマークデータの鮮度チェック → 古ければ全チャンネル一括更新
- 1万再生以上の動画を特定
- 各動画のコメントを最大100件取得（relevance 順）
data/comments_YYYYMMDD.json に保存
Phase 2: コメント分析（サブエージェント並列）
data/comments_YYYYMMDD.json を Read ツールで読み込み、3つのサブエージェントを並列起動（Agent ツール、単一メッセージで3つの Agent コール）:
Agent 1: 感情・没入分析
- 全コメントから感情表現を抽出・分類
- 没入体験の報告（「別世界に入った」「転送された」等）
- キャラクターへの愛着・言及（「サムネのイケメン」等）
- RP（ロールプレイ）コメントの検出
- チャンネル別の感情深度比較
Agent 2: 利用シーン・リクエスト分析
- 利用シーンの抽出と頻度集計（勉強、睡眠、読書、DnD、創作等）
- 直接的リクエスト（Spotify 配信、壁紙、フル版等）
- 暗黙的リクエスト（概要欄ストーリーへの需要、楽器への関心等）
- 繰り返し視聴の動機
- TTP 対象として転写する利用シーン・リクエストの 型 を明示（後段ペルソナ・シーン定義の初期セット）
Agent 3: 言語・国際性分析
- コメントの言語分布（日本語、英語、韓国語、スペイン語等）
- チャンネルごとのオーディエンス地域傾向
- 多言語対応の示唆
Phase 3: レポート統合・保存
3つのサブエージェントの結果を統合し、以下を生成:
docs/plans/viewer-voice-analysis.md — 視聴者の声分析レポート
レポート構成:
- データソース（動画一覧・コメント数）
- 感情表現の分析
- 利用シーンの分析
- リクエスト・要望の分析
- キャラクター愛着の分析
- 繰り返し視聴の動機
- 言語・国際性の分析
- 自チャンネルへの戦略的示唆
Phase 4: プレビュー・確認
生成されたレポートの主要発見をユーザーに要約して提示。
障害時ガイダンス
| 状況 | 兆候 | 対処 |
|---|
| OAuth 未認証/失効 | auth.oauth_handler の FileNotFoundError（client_secrets.json 不在）/ AuthError / HTTP 403 | 初回認証フローを再実行。403 が続く場合は auth/token.json を削除しスコープを確認のうえ再認証 |
| YouTube quota / rate | HTTP 429 / 403 quotaExceeded | 日次 quota（既定 10,000 units・太平洋時間 0 時リセット）を待つか呼び出しを抑える |
| API 障害 / サービス停止 | HTTP 503 / タイムアウト | Google Cloud / YouTube のステータスを確認し、時間を置いて再実行 |
関連ファイル
yt-benchmark-comments (youtube_automation.scripts.fetch_benchmark_comments) — コメント収集スクリプトdata/comments_YYYYMMDD.json — コメント生データdata/benchmark_YYYYMMDD.json — ベンチマーク動画データ（自動更新）data/video_analysis/<slug>/<video_id>.json — /video-analyze の scene_timeline 出力（コメント言及シーンを動画タイムスタンプにマッピング）
