foley: フレームにピタリと合う効果音

あなたは聞こえません。earshot があなたの耳です。「合っている」「同期している」と言う代わりに、必ず earshot の数値を引用してください。 SKILL_DIR はこのスキル自身のフォルダ（スキル読み込み時に表示されるベースディレクトリ）を指します。作業は動画のフォルダ内で行い、動画の隣に foley/ ディレクトリを作成してすべての生成物をそこに保存します。

必要条件

ffmpeg と ffprobe が PATH に存在すること、Python 3.10+。
earshot が PATH に存在すること: uv tool install "earshot[mcp] @ git+https://github.com/Leonxlnx/earshot" を実行し、その後 earshot doctor --fetch（約1.1GBのモデル、CPUのみ）。
Openverse へのインターネット接続（匿名制限: 1分あたり約20リクエスト、1日あたり200リクエスト）。

1. キューを見つける（見て、測る）

python3 SKILL_DIR/scripts/find_cues.py VIDEO --out foley/cues-candidates.json を実行すると、動きのピーク（フレーム間の変化）が表示され、コンタクトシートが foley/sheets/ に書き出されます。
コンタクトシートを確認します。効果音が必要な瞬間（打撃、足音、ドア、素早いターンの風音、衝突、アンビエンスベッド）それぞれに名前を付け、正確なフレームを選びます。動きのピークを絞り込みの参考にしますが、実際に見えるものを信頼してください。実際に見えないコンタクトはスキップします。
foley/cues.json を記述します: [{"id": "hit1", "t": 0.625, "kind": "hit", "what": "拳が開いた手のひらに当たる"}, ...]

2. CC0 サウンドを取得する

種類ごとに2〜4個の検索ワードを指定します: python3 SKILL_DIR/scripts/fetch_cc0.py "パンチ衝撃" foley/sounds/hit --limit 8 このコマンドは source=freesound から license=cc0 の結果のみを保持し、タイトル、作成者、ライセンス、ソースページを foley/sounds/sources.json に記録します。CC0 はクレジットを必要としませんが、商用利用の場合はユーザーにソースページを開くように伝えてください。Openverse はライセンスの正確性を保証しません。

3. earshot で選択とトリミング

earshot rank "<その瞬間の音の説明>" foley/sounds/<kind> --top 3 --out foley/rank-<kind>.json。音を説明してください（「拳が開いた手のひらに当たる短く鋭い平手打ち」のように）。
earshot find FILE "<同じ検索ワード>" --kind event --top 3 --out foley/find-<id>.json（ワンショットの場合）。--kind texture はアンビエンスベッド用です。頭切れ・尻切れとマークされたトリムは除外します。
各トリムの同期ポイントをメモします: 打撃の場合はアタック（開始 + 約5ms）、風音の場合は開始ではなく最も大きなポイント。

4. 配置

foley/plan_v1.json（scripts/mix.py のヘッダーを参照）を作成し、python3 SKILL_DIR/scripts/mix.py foley/plan_v1.json を実行します。動画はコピーされ、再エンコードはされません。

5. 聴き直して修正する（重要な部分）

earshot timeline OUT.mp4 --cues "t1,t2,..." --out foley/timeline_v1.json
python3 SKILL_DIR/scripts/check.py foley/timeline_v1.json id1,id2,... foley/check_v1.json キューが合格となる条件は、聴こえた onset がフレームから 40ms 以内で、かつベッドに対して 6dB 以上であることです。
失敗したものだけを、測定されたずれの量に基づいて修正します:
- 遅い / 早い → そのイベントをオフセット分シフトします（風音は通常、ピークが開始より後にあるため遅くなります）;
- 埋もれている（ベッドに対して 6dB 未満）→ そのイベントを上げるか、ベッドを下げます;
- トゥルーピークが −1 dBTP を超えている、またはクリッピングしている → 最も大きな打撃音を下げます（リミッターは最初のサンプルでトランジェントを補足できません）。
plan_v2.json を書き、レンダリングし、再度聴きます。すべて合格かつトゥルーピーク ≤ −1 dBTP になるまで繰り返します。
ラウドネス: 効果音のみのトラックはピーキーで、通常トゥルーピーク ≤ −1 dBTP で約 −20 LUFS になります。これは想定内です。最終的なラウドネスは後で編集（ボイス/音楽と合わせるとき）に設定します。ここではこれ以上大きくしないでください。

6. レポート

foley/report.md を記述します: すべてのキュー（時間、フレーム、内容）、使用したファイル（タイトル、作成者、CC0 ソースページ）、初回のオフセットとレベル、変更内容、最終的な数値を記載します。これらのチェックは earshot による測定であり、人間の聴取ではないことを明記し、ユーザーに一度自分で聴くよう提案します。

ルール

ユーザーが別途依頼しない限り、CC0 サウンドのみを使用します。sources.json の行がないサウンドは決して使用しないでください。
見えない打撃をでっち上げないでください。「音が合っている」と主張せず、earshot の数値を引用してください。
元の動画は変更せず、<名前>-sfx.mp4 として書き出します。

フォーリー