suggest-sfx

suggest-sfx — SFX パス

レンダリング済みのナレーション付きショートに、映像のビートとナレーションに同期した上品な効果音を追加します。効果音は共有され、拡充していく SFX ライブラリから選びます。ビートごとに協力して作業し、ユーザーがプランを確認してフィードバックします。

全体の流れ：宣言型プラン（sfx-plan.json）を信頼できる情報源とし、ツール（tools/mix_sfx.py）で読み込み、ライブラリ（media/library/sfx/）を拡充し、ミックス前に必ず USER-AUDIT を実施します。

音のセンスはブランドとの約束です。毎回、brand.md §7を読んでください。基本スタイルは落ち着きと上質さ（Linear / Anthropic / Vercel）を重視し、聞こえるより感じられる程度に抑え、常に音声より小さくします。MrBeast のように大音量にはしません。

入力（毎回、最初に読むもの）

• brand.md §7（サウンドデザイン） — 繊細さ、密度、音色、音量、同期、シグネチャーモチーフ、音源ポリシーに関する SFX の基準です。必ず守ってください。
• shorts/short-N-<niche>/beats.json — ビートと、単語ごとの正確な音声タイミング（gen_voice.pyによって書き戻されています）。これらの単語に合わせて同期の合図を設定します（「boom」でポップ音、「free」でチャイム音など）。
• ショットのソース remotion/src/shots/short-N/*.tsx — 実際の映像上のビート（ピースが着地する、数字が現れる、バッジが押されるなど）は、ショット内のアニメーションフレームにあります。ショットを読み、ローカルフレームをグローバル時間に変換します：at_s = (local_frame + sequence_from) / fps。推測しないでください。キューは対象の出来事が起きる正確なフレームに合わせます。
• media/library/sfx/catalog.json ＋ palette.json — 使用・拡充するライブラリです。

ライブラリ（media/library/sfx/）— 長期利用できるアセット

• palette.json — 生成レシピです。汎用的で再利用可能なサウンド ID、プロンプト、長さ、タグを定義します。ライブラリに含めるべき内容の信頼できる情報源です。
• catalog.json — 実在するアセットのマニフェストです。クリップごとに {id, file, category, tags, duration_s, peak_dbfs, loudness_lufs, source, model, license, prompt, used_in} を記録します。gen_sfx.pyによって書き込まれます。
• clips/*.mp3 — 音量を正規化したクリップです（約−20 LUFS、上限−1.5 dBFS）。そのため、プランで指定するキューごとの gain_db は、知覚上の音量として意味を持ちます。
• まずは常にライブラリから選びます。 新しく生成する前に、既存のクリップを再利用してください。クリップには汎用的な名前とタグを付けます（ui-toggle-on、whoosh-soft、pop-revealなど）。今後の動画でも再利用できるようにします。ライブラリは長期利用できるアセットであり、各動画ではその中から選んで使います。本当に不足している音だけをpalette.jsonに追加して生成します。

ワークフロー

1. 確認する：ブランド§7、beats.json、ショットのソース、カタログを確認します。正確なキュー時刻を割り出します。候補となるビートごとに、ビジュアル上の瞬間に対応するショット内のローカルフレーム、またはナレーションの単語を特定し、グローバル秒数に変換します。
2. 好みをユーザーと先に決めます：まだ決まっていない場合は、存在感、密度、種類、ソースについて確認し、その後ブランド§7を適用します。すでに決まったことは聞き直しません。
3. キューリストを機能優先で提案します。 各ビートについて、必要なもの（ブランド§7）を検討します：動き（whoosh）· 緊張感（riser）· 強調（impact/pop）· 切れ味（click）。重要なトランジション、明かし、効果的なクリックの連続を評価します。3～4ショットのクリックの連続は1つのジェスチャーとして数えます。実際に省いてもよいテクスチャには "optional": true を付けます。最大の見せ場2～3か所にレイヤーを重ねます（ビルドからの落とし）：台本上の明かしにriser→impactを重ねる、カットを際立たせるためにwhoosh→popを重ねる、といった形です。プランでは、レイヤーは同じ、または隣接する at_s に配置した2つのイベントで構成されます。各キューをビジュアル上のビート、そして多くの場合は正確な単語に同期させます。
4. まずライブラリから探します。 プランで必要な特徴的なサウンドごとに、合うカタログクリップがあれば再利用します。見つからない場合は、汎用的なレシピを palette.json に追加して生成します：python tools/gen_sfx.py（ElevenLabs Sound Effects API → 正規化したクリップ → カタログ）。生成品質が低い場合に限り、厳選したロイヤリティフリー素材を使います。いずれの場合も source と license を記録します。
5. shorts/short-N-<niche>/sfx-plan.json を作成します — キューごとに1つのイベントを指定し、at_s はグローバル秒数で記述します。（スキーマは以下を参照。）
6. ユーザー監査ゲート（必須）。 確定したキューシート（python tools/mix_sfx.py <plan> --print）を提示し、ミックス前にユーザーの承認とメモを得ます。
7. 承認後に試聴用プレビューをミックスします：python tools/mix_sfx.py shorts/short-N-<niche>/sfx-plan.json → プランの render.out に出力します。声の下で軽くサイドチェインダッキングし、安全用リミッターをかけます。ユーザーのメモに基づいて（ゲイン、タイミング、キューの追加・削除）調整し、再度プリントしてミックスします。
   • 期待ではなく数値で可聴性を確認します。 ミックス後、各キューのウィンドウでミックス音声と声のみのプレビューのRMS差を測定します。ストーリー上重要なキューは**+4 dB以上**、テクスチャは+1～3 dBの差が必要です。可聴性の低いキューはキューシート上では見落とされがちです。実際に届くことを確認していないキューは納品しないでください。
   • トランジェントクリップのゲインに関する注意点。 短いパーカッシブなクリップ（knock/stamp/keys/snap）は、−20 LUFSのラウドネス目標に達する前にピーク上限の−1.5 dBFSに達するため、カタログでは持続音のクリップより約3～5 dB小さくなります。ブランド表が示す値より、プランの gain_db を約3～5 dB高くする必要があります。これが前述の可聴性チェックで明らかになります。
   • ショート動画のキャリブレーション。 ほとんど途切れないナレーション（約2.7語/秒、間はわずか）の下では、控えめなゲイン表では全般的に4～8 dB低すぎます — ダッキングと声によるマスキングでほとんど聞こえなくなります。実績のある適正範囲は、トランジション／whooshが**−3**、ストーリー上のpop／impactが0..+3、stamp／snapが0..+7、レイヤーを重ねた見せ場のriserが0..+2です。ショート動画のプランはこの範囲から始めます。
   • 連続したセリフの下に完全に埋もれるキューは、測定できません。感じるだけで聞こえなくてもよしとするか、削除します。 サイドチェインダッキングにより、声がある間は小さなクリップがずっと抑えられます（クリックの連続は、どのゲインでも+0 dBと測定されることがあります）。そうしたキューは妥当な+6前後に設定して単語間の隙間に収めるか、削除します。ゲインを上げて無理に聞こえるようにしないでください（無音部分で音が急に大きくなります）。
   • トランジェントは短いウィンドウで測定します。 0.6秒のRMSでは50 msのクリックが平均化されてほとんど検出されず、隣接する大きなキューが混入して誤って合格となることもあります。snap/pop/zap/stampには約0.3秒のウィンドウを使い、riserはエネルギーが最後に集中するため、最後の3分の1で測定します。
   • ノイズの多いテクスチャはゲインでは直せません。 静電気音／グリッチ音／ハム音のようなクリップは、−4 dBでもセリフの上でノイズとして聞こえます。音量を下げると小さなノイズになるだけです。ユーザーから「ノイズが多い」と言われたら、サウンドの特性を変えて（クリーンな機械的スナップなど）、または無音にします — ブランド§7「ナレーション中に静電気音／グリッチ系のテクスチャを入れない」を参照してください。
8. ライブラリに保存します。 新しいクリップはライブラリとカタログに残り、次の動画でも利用できます。used_in を更新します。

sfx-plan.json（信頼できる情報源）

{
  "master": "remotion/out/ShortNName-voiced.mp4", "master_fps": 30,
  "catalog": "media/library/sfx/catalog.json",
  "render": {
    "preview": "remotion/out/ShortNName-voiced.mp4",   // the voiced render to mix over
    "out": "shorts/short-N-<niche>/output/short-N-sfx.mp4",
    "end_s": 42, "duck": true
  },
  "events": [
    { "at_s": 4.9, "sfx_id": "chess-piece-thock", "gain_db": -8, "shot": "MainScene",
      "cue": "e4 pawn lands (local f51)", "note": "diegetic board foley" },
    { "at_s": 13.03, "sfx_id": "ui-click-soft", "gain_db": -18, "optional": true, "cue": "card locks" }
  ]
}

• at_s — グローバルタイムライン上の秒数（beats.jsonと同じ時計です）。
• gain_db — クリップの正規化レベルに対するdB値（値が小さいほど音量が小さくなります）。初期値は上記のSHORTSのキャリブレーションを参照してください。
• optional: true — 削除可能なテクスチャです。mix_sfx.py --no-optionalで除外できます。監査対象がコアセットになるよう、積極的に使用してください。
• cue / note — 人が読めるアンカー（正確なフレーム／単語）で、監査時に内容がわかりやすくなります。

ツールのクイックリファレンス

• ライブラリを拡充する：python tools/gen_sfx.py [--dry-run] [--only id1,id2] [--force] [--renorm]。 --renormは既存のクリップを音量ターゲットに合わせて再調整します（API／課金は不要です）。.envに ELEVENLABS_API_KEYが必要です。
• キューシート（監査用アーティファクト）を出力する：python tools/mix_sfx.py <plan> --print [--no-optional]。
• ミックスする：python tools/mix_sfx.py <plan> [--no-optional] [--no-duck] [--end S] [--out path]。

原則（標準スタイル — 必ず適用してください）

• 常に声より小さく。 効果音は味付けであり、主役は声です。ダッキングし、音量を抑え、ナレーションを超えるピークを出さないでください。無音もミックスの一部です。
• 重要な転換と発見に限る — それに加えて、合成ショートのコンテンツそのものとなる劇中の動作音（駒のトクッという音、数字が現れる音）を使用します。それ以外はすべてoptionalにします。
• 映像のビートと単語に同期させる。 トグルが切り替わる瞬間にクリック音を、発見の瞬間にポップ音を正確に合わせます。100ミリ秒ずれるだけで雑に聞こえます。実際のフレーム／単語のタイミングを使ってください。
• 再利用を優先する。 汎用的な名前とタグを付け、動画を重ねるごとにライブラリが充実するようにします。生成する前に再利用してください。この動画が終わった後も残る成果物はライブラリです。
• 雰囲気より機能を優先する。 カタログを見て「しっくりくる」音を探すのではなく、役割（動き／緊張感／強調／鋭さ（ブランド§7））に応じて音を選びます。基盤となる少数のサウンドが大部分を担います。数を増やせばよいわけではありません。シグネチャーモチーフの一貫性を保ってください。
• 重要な場面は重ね、それ以外は単音にする。 ビルドアップからドロップ（ライザー→インパクト、ウーシュ→ポップ）への流れが効果音の真価を発揮する場面ですが、ヒーロービートのうち2〜3箇所に限ってください。
• 構成を取り入れ、ドラマは避ける。 落ち着いた高級感を保つため、シンバルで切迫感を煽るライザー、予告編のような激しい打撃音、動作のたびに入れるウーシュは避けてください。
• ミックス前に監査する。 ユーザーがまずsfx-plan.jsonを確認して承認します。これは必須です。

完了の条件は、必要なクリップが（出典とライセンスを記録して）ライブラリに登録されていること、sfx-plan.jsonが作成されユーザーによる監査を受けていること、効果音をミックスしたプレビューがレンダリングされ耳で確認されていること、新しいクリップとused_inがライブラリに保存されていることです。