EditAtlas/サウンドデザイン

サウンドデザイン：完成した動画にリアルな効果音を配置する

目的：映画が、優れたライブラリを持つ編集者によってカットされたかのようなサウンドになること。すべての音はEditAtlasの実ファイルであり、あなたが確認したフレームに、数値で正当化できるレベルで配置されます。

プロセス全体を通して二つのことが真実なので、それらを前提に計画してください。

• 聴くことはできません。 説明と測定値（sounds.py info）から音を選択し、配置とレベルをcheck.pyで確認し、人間に聴いてもらうべき瞬間の短いリストを渡します。「音が良い」とは決して言わず、何を測定したか、どこに人間の耳が必要かを伝えてください。
• 創作してはいけません。 与えられた動画のみを扱ってください。動画がない場合は、それを要求してください。ライブラリに適切な音がない瞬間がある場合は、そのまま静かにし、レポートでその旨を報告してください。

全てのスクリプトはscripts/にあります（Python 3.9+、numpy、Pillow（フレームシート用）、FFmpeg（ffprobeがPATHに含まれていること））。スキルフォルダのパスを指定して、自身の作業フォルダ（work/、result/）から実行してください。プロジェクトフォルダやこのスキルフォルダに書き込まないでください。

python SKILL/scripts/moments.py FILM.mp4 --out work/moments             # moments.json, sheet.png, overview.png
python SKILL/scripts/moments.py FILM.mp4 --at 10.4 --out work/at        # 特定の時間の前後0.1秒ごとのフレーム
python SKILL/scripts/sounds.py search "glass clink" --max-dur 2         # 公開インデックスからのID
python SKILL/scripts/sounds.py info sfx-ID sfx-ID                       # 1回ダウンロード、SHA-256、測定値
python SKILL/scripts/sounds.py sheet sfx-ID sfx-ID --out work/c.png     # 候補の波形+スペクトログラム
python SKILL/scripts/mix.py work/cues.json --out result/FILM_sfx.mp4    # MP4 + _track.wav + _resolved.json
python SKILL/scripts/check.py result/FILM_sfx_resolved.json --moments work/moments/moments.json --listen-out result/listen.wav

音声ファイルは https://raw.githubusercontent.com/EditAtlas/sfx/main/ から取得され、~/.cache/editatlas-sfx にキャッシュされます（EDITATLAS_SFX_CACHEで変更可能）。EditAtlas/sfxのローカルクローンがある場合は、sounds.pyのサブコマンドの前に--mirror PATHを渡すと、ダウンロードは行われません。

1. 映像とその音声を確認する

moments.py を実行します。既存の音声情報（has_audio、LUFS、無音の割合）を報告し、ピクセルの差分から3種類の瞬間を検出します：cut（シーンチェンジ）、move（動きの開始またはピーク）、land（動きの停止：何かが収まる）。次に Readツールで overview.png と sheet.png を開きます：数値はソフトなアニメーション（静止した顔の上でバッジが拡大してもカットとは判定されない）を見逃し、カメラのブレを過剰に報告します。重要な部分では、--at T で特定の時間の周囲のフレームを描画し、対象が現れる、着地する、または方向を変える正確なフレームを見つけてください。

映像自体の音声について判断します：

数値と映像からわかること	キューシート設定
音声なし、または silent_share が1に近い	"keep_audio": false：効果音が映像を支え、約-16 LUFSに調整される
音楽のみ	"keep_audio": true：効果音は音楽より約3 LU低く設定。可能であればビートに合わせてアクセントを配置
誰かが話している（字幕、顔、ラベリアマイク）	"keep_audio": true, "under_voice": true：音声より約8 LU低く、より少なく、より軽い効果音
合成されたビープ音がすでにミックスに含まれている	確認が必要：置き換えるにはステムが必要。リアルな音を重ねると二重になる

映像の音声を保持するかどうかが明確でない場合は、ユーザーに確認してください。

2. 確認した内容からイベントリストを作成する

音が必要な瞬間ごとに1行：時間、何が起こるか、どのような音か。編集者のように考えてください。

• 現れるもの（バッジ、チップ、ボタン、キャプションカード）：短いポップ、チック、またはソフトなディング、anchor: start。
• 横切るもの、またはトランジション：最も大きなポイントが到着時に来るウィッシュ、anchor: peak。
• 重みを持って着地するもの（ロゴ、製品、スタンプ）：停止したフレームにヒットまたはサウンド、anchor: peak。
• 画面上の実際の物体（グラス、氷、紙、鍵、飲み物）：UIサウンドではなく、対応するフォーリー。
• 成功/エラー状態：成功にはディング、エラーには短いブザーまたはアラート。1つの映像につき1つのインターフェースサウンドファミリー。
• 何かが構築されるもの：終わりが成果物に着地するライザー、anchor: end。

すべての動きに音が必要なわけではありません。テンポとセンスに関する数値ルールは references/taste.md にあります。セッションの最初のキューシートの前に読んでください。

3. 音を選ぶ：読み取り、測定、比較

1. 検索します。EditAtlas MCPが接続されている場合、search_sfx の方が良い結果をランク付けします（ベトナム語も理解します）。そうでない場合は sounds.py search を使用します。タイトルはソースファイルの単語を意図的に避けています（例：「camera shutter」は「Lens Aperture Tick」）、そのため音が何であるかで検索し、同義語やカテゴリフィルターを試してください。
2. 2～4個の候補に対して sounds.py info を実行します。以下の値を確認します：audible_s（実際に聞こえる長さ。ファイル自体はもっと長い可能性あり）、attack_s（0.0x=即座に立ち上がる、0.3+=徐々に大きくなる）、peak_t_s、centroid_hz（約1500未満=暗い、約6000超=明るい）、mono_loss_db（-6未満=スマートフォンでチャンネルがキャンセルされる。mix.py は大きい方のチャンネルのみ再生）。
3. 2つの候補が同じように読める場合、sounds.py sheet を使用します：鋭い垂直線はクリック、広がりはウィッシュ、下部のエネルギーは重みを示します。
4. 何が動き、何に触れるかで選び、次に長さで選びます：0.3秒のチップポップに1.8秒の漫画ポップは使えません。max_len を使用して長いファイルをフェードアウトで切り詰めます。
5. 同じ種類の繰り返しの瞬間（3つのチップ）には、同じファミリーの異なるテイク（Tiny Plop 05、06、Empty Plop 06）を使用し、同じファイルを3回使用しないでください。

ライブラリは一部の分野で薄いです（2026-11-07測定）：液体の注ぎや発泡、ルームトーン、スタンプ、水滴やサウンドはほとんどありません。適切な音がない場合は、最も近い正直な音を選び、レポートでギャップを報告し、無理に間違った音を使わないでください。

4. キューシートを作成してレンダリングする

{
  "video": "work/film.mp4",
  "keep_audio": false,
  "under_voice": false,
  "cues": [
    {"t": 0.30, "id": "sfx-988dafbd36", "role": "whoosh", "label": "タイトル着地"},
    {"t": 0.62, "id": "sfx-mi630472",  "role": "foley", "anchor": "start", "max_len": 0.9, "gain_db": -2, "label": "氷がグラスに入る"},
    {"t": 8.30, "id": "sfx-fs339114",  "role": "hit", "label": "ボトル着地"},
    {"t": 0.00, "id": "sfx-c7d271e90f", "role": "ambience", "bed": true}
  ]
}

• t は瞬間のフレームの秒単位の時間です。role はレベルとデフォルトのアンカーを設定します（references/taste.md）。
• anchor：start は t に可聴開始点を、peak は最大点を、end は可聴終了点を配置します。
• キューごと：gain_db（ロールレベルからの相対値）、max_len、fade_in、fade_out、offset_in、pan（-1..1）。
• "bed": true：映像全体の下に、-54 dBFS（かろうじて聞こえる程度）で1つの長く安定したアンビエンスを配置します。効果音のみの映像にのみ使用し、音声や音楽の下には決して使用しません。映像が長い場合は、それ自身にクロスフェードします。

mix.py を実行します。すべての音の着地時間とピークレベルを出力し、瞬間が非常に早く、音がファイルの途中から開始しなければならなかった場合に通知します。

5. チェック、修正、再チェック

レンダリングのたびに check.py を実行します。終了コード1は、何かフラグが立ったことを意味します。このスクリプトは、mix.py が _resolved.json の隣に書き込むWAVトラックを読み取るため、結果をコピーする際はこれらのファイルを一緒に保持してください。レンダリングされたトラック内の各音を独自の波形で見つけるため、sync は実際の同期です：1フレーム以上のずれは、シートのバグです。また、10秒あたりのジェスチャー数、最長の隙間、強いヒット、繰り返し、デジタルサイレンス、マスターラウドネスとトゥルーピーク、モノラルフォールダウン、および強い映像の瞬間に音が割り当てられたかどうかを測定します。

各フラグに対して、修正するか（隙間に音を追加、繰り返しを入れ替え、キューを移動）、それが正しいと判断してレポートで理由を説明します（「7.8秒の隙間は会話の区間であり、声がそれを支えている」）。アタックが遅いという注意はヒントです：瞬間が音のピークである場合は、そのキューを anchor: peak に切り替えてください。通常、2～3ラウンドの調整が必要です。

6. 納品する

ユーザーに以下のものを渡します：

1. FILM_sfx.mp4 および FILM_sfx_track.wav（効果音のみ、フルレングス、ユーザー自身の編集の下に配置するため）。
2. 簡単な表：時間、瞬間、効果音のタイトルとID、その音を選んだ理由。
3. check.py の数値（テンポ、最長隙間、LUFS、トゥルーピーク）と、残っている各フラグの意味。
4. 聴取リスト（listen.wav はそれらの瞬間を1つのファイルにまとめます）：「ヘッドフォンとスマートフォンの両方で聴いてください」。
5. ギャップ：音がなく残された瞬間と、ライブラリに不足していた音。

レポートはユーザーの言語で書いてください。自分が聴いたとは主張しないでください。

オプション：real-sfxエンジン

Clipwingの real-sfx スキル（MITスクリプト、Alexander Korbanov作）は、よりヘビーなエンジン（型付きキューリスト、シンセレイヤー除去、ビートグリッド、9軸批評）で同じ処理を行います。EditAtlasライブラリ全体をメインパックとして使用できます。アダプターと検証済みの内容については references/real-sfx.md を参照してください。