real-sfx

real-sfx: モーションビデオにリアルなサウンドを

目標：フィルムが、質の良いライブラリを持つ人物が編集したかのように聞こえること。そのために：

• 音は決して合成されません。 ソース：ユーザーのライブラリ（config.json）とuisfx（既製CC0インターフェースサウンドパック、それ自体は合成音：唯一の例外。インターフェースの瞬間のみ使用。「合成なし」はこれをオフにします：--ui library）。適切な音がない場合：その瞬間は無音となり、レポートに記載されます。これはmotion-standardsの「トラックなし：合成」を上書きします。
• あなたは聞くことができません。 音は数値、言葉、画像として読み取られます（references/listening.md）。ピックを「聞いた」と提示しないでください：何を目視と測定で確認し、ユーザーが何を聞くべきかを述べてください。
• 音楽と音声は保持し、それらがフィルムを支えている場合。結果は常に新しいMP4 と別個のWAVトラックです。
• 二重にしないでください。 レンダリングのオーディオに焼き付けられた合成は、その下に重ねるのではなく、実際のサウンドで置き換えます（ステップ1）。批評はこれを数値として測定します（doubling軸）。
• プロジェクトやスキルフォルダーは変更しないでください。 すべての作業ファイルは自身のフォルダー（work/、result/）に置きます。

Video Director内部での動作

(Video Directorのコピーで追加。Clipwingのオリジナルにはありません。UPSTREAM.mdにすべての変更がリストされています。) このコピーはVideo Directorスキル内にあり、そのサウンドステージによって実行されます：../references/sound-stage.md、「サウンドエンジニアリング」。これらのステップはどの瞬間にサウンドを付けるかを決定し、このスキルにはそれらのみ（build/audio/sfx/events.json）を渡し、ユーザーが選択した録音を固定し（sound_handoff.py pins）、--ui library、--no-loudnorm、テクスチャレイヤーやベッドなしで実行し、エフェクトトラックと解決済みキュー（sound_handoff.py collect）のみを受け取ります。それらに従い、このファイルはそれらがカバーしないオプションについてのみ読んでください。REAL_SFX_CONFIG、REAL_SFX_INDEX、REAL_SFX_TASTE、REAL_SFX_RATINGS、REAL_SFX_STEADY、REAL_SFX_STYLESを~/.config/real-sfx/ 以下のパスに設定してください（プラグインは各バージョンを新しいフォルダーにインストールするため、ここに書き込まれたものは次回アップデート時に残されます）。--rememberはこのフォルダーに書き込むため（learn_style.pyも同様：学習したスタイルは~/.config/real-sfx/styles/ にコピーしてください）、使用しないでください。

クイックパス

最初に python scripts/setup.py check（ffmpeg、メイン/追加ライブラリ、インデックス、uisfx）と python scripts/look.py FILM.mp4 --out work/look（時間とその下の元のサウンドを含むフレーム）を実行します。その後、状況に応じて：

# 1. プロジェクトにイベントリスト（docs/cues.json、scripts/cues.json）またはサウンドを合成するスクリプト（audio.cjs）がある場合
python scripts/from_cues.py PROJECT_FOLDER|docs/cues.json --video RENDER.mp4 --out work/cues.json
# 2. リストのない画面録画：ui_events.py ...（references/screencast.md）、次にfrom_cues.py work/ui/events.json
# 3. 画像のみ：                    find_moments.py FILM.mp4 --out work/moments; suggest_cues.py work/moments/moments.json --out work/cues.json
# 3b. ソフトカラーアニメーション（リストなし、UIプレビュー、イラスト、モーショングラフィックス）：自動化は40のうち5-6の動きを検出。
#     ステップ2、「リストのないサイレントアニメーション」：find_moments.py FILM --out work/moments --fine; look.py FILM --at T --span 2.4
#     --step 0.1 --out work/at.png; フレームからの独自のイベントリスト（references/typed-cues.md）-> from_cues.py - --ui library
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --plan     # 何がどこに行くかを確認; 次に--planなしで実行
python scripts/critique.py result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav
python scripts/levels.py   result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav --json work/edits.json
# SFXのみのサウンドのフィルム（独自の音楽や音声なし）：隙間に小さなサウンドを入れ、再度mix.py（ステップ4、「スモールサウンドレイヤー」）
python scripts/texture.py work/cues.json --moments work/moments/moments.json
# 同じフィルム：ベッド（フィルム全体の下に置く長く暗い実際の録音；ステップ4、「ベッド」）、その後再度mix.py
python scripts/bed.py work/cues.json [--list]
# 9つの完成したSFXリールに対する数値（ステップ6、「リファレンスとの比較」）：スコアなし、判定には影響しません
python scripts/critique.py RESOLVED.json WAV --style clean-sfx-refs
# 安価な人間の耳（ステップ6）：批評の質問とワンタップ判定を含むページ；マスキングモデル
python scripts/listen_page.py build work/listen --moments result/film_sfx.mp4 --critique RESOLVED.json WAV
python scripts/listen_page.py serve work/listen [--lan]        # その後：listen_page.py results work/listen --log
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --masking        # 残りが隠すサウンド（venvが必要）

プロジェクトフォルダーは自身のイベントリストを見つけます（docs/、scripts/、assets/）；リストがない場合のみシンセサイザースクリプトが読み取られます。シートを編集する前にすべてのfrom_cues.pyフラグを選択してください：再実行すると手動編集が消去されます（その後sheet.py apply）。 フィルム内の音声：mix.py ... --voice-safe（深さ normal；静かなテクスチャが多い場合は --voice-depth light、deep はポーズ中のまれなサウンドのみ：インターフェースをミックスから完全に除去します）。音楽がフィルムを支える場合：--duck。ラウドネス：デフォルトで再構築されたベースはオリジナルに一致します；独自の設定：--target-lufs NUMBER。 インデックスがない、またはライブラリが移動した場合：python scripts/build_index.py、その後 python scripts/listen.py tag-index。 uisfxがない場合：setup.py init --uisfx。別のマシンの場合：setup.py scan FOLDER、setup.py add-library NAME PATH [--tier main|extra] --index。スキルフォルダーからスクリプトを実行；パスにスペースや非ラテン文字がある場合は引用符で囲む；Windowsで非ラテンパスを使用する独自のPython：PYTHONUTF8=1。PowerShellでは、引用符がJSON引数を壊します：ファイルに入れてください。

サウンドの出所

必要なもの	出所
ベース：風切り音、ヒット音、ライザー、ポップ、チャイム、キー、紙、フォーリー、アンビエンス	メインライブラリ（tier: main、config.jsonのパス）。catalog.json / catalog.csvを持つ整頓済みパックで、すべてのサウンドにタイプとソース録音が与えられ、ファイル名からの推測を不要にします
メインライブラリに不足しているもの：低いドロップ、コイン、短いグリッチ	フォールバックライブラリ（tier: extra、結果では~と表示）：メインライブラリに適切なサウンドが3つ未満の場合のみ
独自の役割を持つデザインパック	役割 granular、atmosphere、power、music_transition、voiceは自動選択では要求されません：明示的に取得（--role、"pick": {"role": ...}）
インターフェースの瞬間：クリック、チック、ウィンドウ、通知	uisfx（--ui auto）：リスト自体がインターフェースの種類（クリック、チャイム...）を指定する場合：from_cuesは理由と場所を示します（routes: key -> library:click, pop -> uisfx:select）
タイピング	常にライブラリの実際のキーボード。--ui autoの場合も同様。8個以上のclickイベントが35～170ミリ秒間隔で連続する場合、from_cues自身がタイピングとして認識します（--no-typing-detect）
物理的な接触：ボール、ステップ、ビーズ、物体	常にライブラリ：床のボールは鈍いドスンという音であり、selectではありません（以下のレシピ）

まだライブラリがない場合：setup.py init --uisfx だけで78のCC0 UIキューが得られます。チェックする価値のある無料の実際の録音ソース（各ライセンスを読んでください）：Freesound（CC0フィルター）、Sonniss GDCバンドル、Mixkit、Pixabayサウンドエフェクト。

「私のライブラリから」、「合成なし」、または「サウンドが合成的」：--ui library。uisfxインターフェースサウンドを使用するプロジェクトのロゴのアクセントや「チャリン」という音：--from-library pop,bell（リストからの種類名）；1つのサウンドの場合：sheet.py set --at T --label bell id=65。 調性音楽の下：

• uisfxの繰り返しとライブラリの調性サウンド（チャイム、ポップ、ガラス、コイン）のピッチステップは、プロジェクトにスコアがある場合に自動的にオフになります（--ui-pitch off|cycle）；
• 実際のサウンドのピッチは音楽の音符に合わせられます：mix.pyはシートのmusic_ref（エフェクトなしのベッド、音楽ステム）または--music-ref FILEを取得し、調性サウンドを最大2半音プラス音符に合わせるセント（合計2.5）シフトします。それが音符に合う場合。ノイズはそのまま残されます（--no-tonal-fit；scripts/tonal.py SOUND --music FILE --at Tで音符を表示）；
• 作者自身の周波数のインターバル（tick(t, 1800 * 2 ** (4 * i / 12))）は、置き換えのピッチステップになります（melody:）。

ワークフロー

1. サウンドにすでにあるもの

look.pyは元のサウンドのスペクトログラムを表示します（音声はフレーズの帯、音楽はビートのあるカーペット、無音は黒）；listen.py voice FILM.mp4は音声と音楽の割合を示します。3つのケース：

• 作者の音楽または音声：それらは保持され、SFXは上に重ねられます（--duck / --voice-safe）。 例外（実際のフィルムに対する人物の回答、2026-10-19）：フィルムは「サウンドデザインを依頼」され、元のサウンドは音楽のみ（listen.py voice：音声0％）、人物は音楽なしで、自分のクリーンなSFXリールのようにしたい場合。音楽なしのバージョンを作成し（from_cues.py ... --ui library --drop-original、次にbed.py --id ... --level -46をお気に入りのアトモスフィアで）、音楽ありのバージョンも有用なら作成し、どちらかを明示します。3つの盲点選択（オリジナル / 音楽上のエフェクト / エフェクトのみ）で、人物は何の不満もなく最後のものを選びました。from_cuesは焼き付けられた合成がないにもかかわらずそのようなフィルムにBAKED:を出力します（音声0％、音楽84％、アタックはイベントと一致しない：偶然による9％に対して7％）：これは誤警報です。
• トラックに焼き付けられた合成（プロジェクトが合成スコア用に書かれた場合）：その上に実際のサウンドを重ねると二重になります。from_cues.pyはこれを自身でチェックし（BAKED:、unbake:）、音楽と音声に触れずにベースから合成を除去します。正確な方法、およびスクリプトが失敗した場合や合成が音楽ステム内にある場合（--extra-synth）に何をすべきか：references/project-audio.md（出力にBAKED、WARN stems、unbake: not possibleがある場合、またはプロジェクトがスクリプトでサウンドを合成する場合はすぐに読んでください）。ビルド後、critique.pyはdoubling軸を出力します：レイヤーとオリジナルおよび新しいフィルムとの相関（約0になるはず）。
• 画面録画のウィンドウ内で再生されるクリップのサウンド：ネイティブ、保持されます。それらのウィンドウ内のイベントはドロップされます。

2. 瞬間を見つける（最良のソースから最悪へ）

• プロジェクトのイベントリストまたはシンセサイザースクリプト → from_cues.py（以下）。詳細：references/typed-cues.md。
• 画面録画 → references/screencast.md（ui_events.py領域、キーストロークと文字の一致、クリップサウンド）。
• data-startを持つHyperFramesでリストなし：from_hyperframes.py PROJECT --out work/moments.json。 「1 moments」で18要素の場合、モーションがdata-startに従っていないことを意味します：シンセサイザースクリプトを探してください。
• ビデオのみ：find_moments.py FILM --out work/moments [--roi x,y,w,h] [--from A --to B] [--fine]；種類 cut、burst、onset、settle（settleは空フレームや静止ループでも発火します：フレームを見てください）； look.py --moments ...は瞬間のフレームを描画します。スケルトン：suggest_cues.py（references/recipes.md）；ドラフトは開始点であり、答えではありません。--fine はソフトカラーアニメーション用（グラデーション、グロー、明るさではなく色が変わるパステルシェイプ）：クロマ変化も読み取ります。瞬間はsrc=chroma|lumaを取得します。3つのそのようなフィルムで、エージェントがフレームから書き留めたイベントの33～69％を検出（80ミリ秒以内）、明るさのみからは13～25％でした。候補は3～4倍多くなります（10秒あたり15～25）。これらは候補であり、フレームが決定します。
• 音楽下：beats.py FILM --out work/beats.json --plot work/beats.png；usable: trueの場合、mix.py --snap-beats（±50ミリ秒）。グリッドはキックに対してチェックされます（低バンド<125 Hzを個別に）：40ミリ秒以内にキックに合ったビートの数を出力します。キックの隣にあるグリッド（トラッカーがハイハットに乗った、「0.22秒ずれている」）はそれに移動されます；何にも合わないグリッドはusable: falseを取得し、--snap-beatsはそれを無視します。--plotはバンド、キック（緑のマーカー）、グリッド（赤い線）を描画します：マーカーが線上にあるか、グリッドを信頼しないでください。音楽があなたのもので、画像に合わせられる場合：beats.py FILM --suggest-offset work/moments.jsonは、カットやヒットがビートに合うように音楽をどれだけシフトすべきかを示します（アドバイスのみ；音楽は変更されません）。

from_cues.py：python scripts/from_cues.py LIST|PROJECT_FOLDER|SCRIPT.cjs|- --video RENDER.mp4 --out work/cues.json（-は標準入力からリストを読み取ります；PowerShellからのBOMも認識されます）。それが行い、言うこと：

• 正しいレンダリングか：リストが画像を見逃している（VERDICT）；音声にタイミングを合わせたレンダリングに対するデザインタイムリスト：プロジェクトのアンカーからのタイムマップ（timing.json with `a