SonuSV7719/earshot

earshot: エージェントのための耳

あなたは音を聞くことができません。耳で聞いたかのように音の感じを述べたり、音が「合う」と言ったりしてはいけません。必ずearshotの測定結果を引用し、報告する際には数値を添えてください（「強い一致、z +3.9; p_real 0.96; -14.2 LUFS」）。earshotはローカルのCPU上で動作し（オプションの llm コマンドを除き、音声がマシンの外部に出ることはありません）、すべての埋め込みと結果をディスクにキャッシュします。コスト：各CLI呼び出しは新しいプロセスで最初にモデルをロードします（キャッシュされたファイルでも、ビジーなラップトップで約20～40秒）。MCPサーバー内または1つのPythonスクリプト内ではモデルは一度だけロードされ、その後の呼び出しは数秒で完了します。数回以上の呼び出しには、MCPまたは短いスクリプト（from earshot import api; api.find(...); api.realness(...)）を使用してください。

セットアップ（1回限り）

pip install -e "/path/to/earshot[mcp,llm]"   # またはリポジトリのvenv: /path/to/earshot/.venv/bin/python -m earshot ...
earshot doctor                           # パッケージ、ffmpeg、モデル（固定リビジョン、キャッシュ状態）をチェック; --load でタイムを計測

2つの方法があり、機能は同じです:

• CLI: earshot <command> ... [--json] [--out result.json]。テキスト出力はプレーンなサマリーで始まります。時間はテキストでは m:ss.ss、JSONでは秒単位です。
• MCP（モデルは呼び出し間でロードされたまま）: claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /path/to/earshot/.venv/bin/python -m earshot mcp、または任意のクライアントの .mcp.json で: {"mcpServers": {"earshot": {"command": "/path/to/earshot/.venv/bin/python", "args": ["-m", "earshot", "mcp"], "env": {"EARSHOT_THREADS": "3", "GEMINI_API_KEY": "${GEMINI_API_KEY:-}"}}}}（キー行はオプションのllmツールのみ必要; Claude Codeはユーザーの環境から自動入力しますが、他のクライアントでは起動時にキーを環境変数に設定する必要がある場合があります: プロジェクトファイルにリテラルなキーを記述しないでください）。 ツール: measure, describe, match, rank, find, compare, ab, realness, timeline, sheet, critique, doctor, llm_critique; サウンドバンク（モデル不要）: sfx_list, sfx_render, kit_render (Loop 5)。絶対パスを渡してください; full=true ですべてのJSONを返します。サーバーは数秒以内に応答しますが、初回起動時やビジーなマシンでは時間がかかることがあります。Claude Codeでearshotツールが表示されない場合は、MCP_TIMEOUT=60000 を指定して起動してください（PowerShell: $env:MCP_TIMEOUT=60000; claude）。earshot mcp --warm は起動時にモデルをプリロードします。 マシンが共有されている場合は、EARSHOT_THREADS=2-3（または任意のコマンドに --threads 2）を設定してください。プロセスの最初のモデル呼び出しはCLAP + ASTをロードします（約20～60秒）。同じプロセス内の後続の呼び出しは高速です。ffmpegが読み取れるファイルなら何でも動作し、mp4の音声（オーディオトラックのない動画の場合はその旨が表示されます）も含まれます。エラーはstderrに1行で表示されます: earshot <command>: error: ...、終了コード1。

Loop 1: アセットを選ぶ

1. earshot rank "a soft felt mallet hit on a wooden block" downloads/sfx/ --top 5 - フォルダから候補を絞り込みます。
2. earshot find winner.ogg "a single clean mallet hit" --top 3 - 最適な瞬間をサンプルトリム（開始/終了時間（秒））として見つけます。各セグメントには種類があります: stroke（1つのオンセットから減衰するまで）と event（一緒に属するストローク、例えばキーのダウン+アップ）はアタックの5ミリ秒前に開始し、減衰後に終了します。window はエッジがワンショットクエリ用に音にスナップされたストレッチ（プレーンなストレッチ、クロスフェード用、ベッド用）です。head / tail = トリムのピークに対する最初の5ミリ秒/最後の10ミリ秒の大きさ（-30 dB以下 = クリーン）。'head cut' または 'tail cut' とマークされたトリムは、音の中で開始または終了しています: そのまま使用しないでください。--kind event はオンセットベースのトリムのみ（ヒット、クリック、ステップ）、--kind texture はプレーンなウィンドウのみ（ベッド）を返します。デフォルトはクエリを読み取ります。
3. earshot describe winner.ogg --start 1.12 --end 1.48 - 実際にどのように聞こえるかを説明します。トップタグがニーズに合っているか、形状（アタック/ディケイ）が映像に合っているかを確認します。AudioSetラベルは約0.5秒未満のワンショットには弱いです: 'tagger unsure' または近いクラス（スウッシュのZipper、クリックのFinger snapping）は問題ありません。完全に異なるクラス（Speech, Music, Engine, Vehicle）だけが危険信号です。
4. earshot realness winner.ogg --start 1.12 --end 1.48（またはフォルダ全体）- 使用するトリムを評価します。マルチテイクファイルのp_realは、すべてのテイクとその間の無音の平均です。ユーザーがリアルな音、またはプロフェッショナルに制作された音を求めている場合、「コード合成の可能性が高い」トリムは使用せず、「不明」なトリムの証拠を読んでから使用してください（なぜ使用したかを記述すること）。合成音が目的である場合（プロシージャル音楽、UIトーン、earshot forgeで作られた音）、realnessは情報であり、ゲートではありません。判定のしきい値は長さによって異なります（各サマリーに名前が記載されています）。最大6秒の音声はクリップしきい値（低 0.17 / 高 0.77）を使用し、より長いファイルは4秒ウィンドウの平均を弱くキャリブレーションされたファイルしきい値（低 0.40 / 高 0.77）で使用するため、異なる長さのファイル間で判定を比較するには、生のp_realではなく判定結果を比較してください。実際の録音やプロフェッショナルに制作された音楽やサウンドデザインは通常、リアルと判定されますが、realnessは音の発生源ではなく、音の聞こえ方を評価します。クリーンなプロフェッショナルに合成されたトーン（UIサウンド、チャイム、シンセスタブ）もコード合成と判定される可能性があります。realnessが利用できない場合（モデルがない）、リアル対合成のチェックが行われなかったことを明確に述べてください。describeのAudioSetクラス（Sine wave, Beep, Synthesizer）はより弱い証拠です。正確なデジタルゼロだけでは何も証明できません（プロジェクトのライセンス取得済みリアル録音の59%には、何らかの編集またはフェードパディングがあります）。
5. 2つの候補から選択する: earshot ab a.ogg b.ogg --query "a crisp fast air whoosh"。findからのトリムには --a-start/--a-end/--b-start/--b-end を使用します（AとBは同じマルチテイクファイルでも可）。オプション: earshot match winner.ogg "a deep thocky key press" --alts "a clicky blue switch" "a typewriter key" で1つの主張をテスト、または earshot compare winner.ogg --refs approved/ [--start --end] でパレットに合うかを確認します。

Loop 2: ミックスまたはフィルムをレビューする

1. earshot timeline film.mp4 --cues cues.json（または soundtrack.wav --video film.mp4）- リスニングトランスクリプト: 時間、レベル、タグ、セクション、ラウドネスカーブ、ピクチャーカット、カット/キューごとの同期を備えたイベント。--detail low は高速、high は最大96個のイベントをタグ付けします（最も重要なものから順に。サマリーにはタグ付けされたイベントの数が表示されるため、タグ付けされていないイベントは音が欠落していることを意味しません）。同期統計を読んでください: offset_ms = 音声マイナスピクチャー（負の値は早い）、'chance' の割合はランダムな編集ポイントで期待されるスコアを示します。偶然以上の同期だけが意味を持ちます。ヒットのない状態でリストされたカットでも、ソフトなスーッという音が含まれている可能性があります。シートで確認してからサウンドを追加してください。
2. earshot sheet film.mp4 -o sheet.png --cues cues.json（--from 10 --to 25 でズーム、--detail low で高速）- 注釈付きPNG: フレーム、セクション、ラベル付きイベント、スペクトログラム、ラウドネス、ビート、同期によって色分けされたキュー（緑 = 1フレーム以内、アンバー = 100ミリ秒以内、赤 = サウンドなし）。画像ビューアでPNGを開いてください: ギャップ、パイルアップ、マスキング、遅れたヒットが一目でわかります。
3. earshot critique film.mp4（--fast はAudioSet / realnessパスをスキップ）- プロフェッショナルなローンチフィルムの測定範囲に対するスコアカード: 各メトリックは ok / low / high とその重み、タイムスタンプ付きのアクション、および評決（launch-grade / close / needs work / not launch-grade）を表示します。最初にクリティカルな行を修正し、新しいレンダリングで1-3を再実行します。その「視覚イベント上のオンセット」シェアは、±100ミリ秒以内の新しいアタックのみをカウントします（リファレンスの定義による）。その修正とヒントは、timelineと同じマッチャーによって、まったく音のないカットを名前で示します。ファイルがプロファイル自身のリファレンスフィルムの1つである場合、critiqueはその旨を伝え、他のフィルムに対してスコアを付けます。
4. いつでも正確なメーターを取得（LUFS、トゥルーピークdBTP、LRA、ノイズフロア、アタック/ディケイ、ブライトネス、バンド）: earshot measure mix.wav [--music] またはMCP measure ツール。

Loop 3: 変更のA/B比較

• earshot ab before.wav after.wav --query "warm punchy kick" または --refs pro_refs/ - どちらが近いか、BがAとどのように異なるかを測定された言葉（より大きい、より明るい、より長いディケイ）で示します。長いファイル内のサウンドの場合はトリムを渡します（--a-start 1.217 --a-end 1.615 --b-start 7.881 --b-end 8.285）。マルチテイクファイルのファイル全体のA/B比較は、すべてのテイクとその間の無音を比較します。次に earshot timeline after.wav を実行し、イベントラインと同期統計を以前の実行と比較します。一度に1つのことを変更してください。

Loop 4: コードでサウンドを作る（earshot forge）

これは、ユーザーが選択ではなく作成されたサウンドを必要とする場合に使用します。聞くことができるAIは、合成コードを書き、聞き、改善することができます。すべてのサンプルは計算されなければなりません（内部に録音されたオーディオはなく、インパルス応答も含みません）。実際の録音は、批評家が比較するリファレンスのみです。

1. earshot/forge/recipes/<name>.py にレシピを書くか選択します: SPACE（パラメータ範囲）、DEFAULTS、TARGET、ALTS（現実的な混同）および render(params, r) -> 48 kHz array。earshot.forge.dsp（モーダルレゾネーター、接触励起、ノイズカラー、時変SVF、計算された部屋、ノイズフロアのあるマイク）から構築します。リファレンスで測定された、実際の物理をモデル化します: 何が何を打つのか、何が鳴るのか、どのくらいの時間、どの部屋で。

2. ラウンドを1回実行する: earshot forge <recipe> --refs <real refs> --budget 144 --reps 2 --tone 1.5 --keep 4 --robust 8 --dir <round dir>、またはモデルを1回だけロードするPythonスクリプトでラウンドごとに: forge(recipe, critic=Critic(target, alts, refs, tone=1.5), reps=2, space={...})。

   • --tone はモデルフリーのトーンバランスとテールを目的関数に追加します。
   • --reps 2 は各候補を2つのレンダリングでランク付けし、ラッキーなレンダリングを排除します。
   • ビジーなラップトップCPUで、160レンダリングあたり約3～5分かかります（30～60秒のモデルウォームアップを含む）。

3. 聞いた結果を読みます。各ピックのサマリーには、例えば「sounds like: a cork pop, a glass ting」、「decay +2.4 outside the refs」または「tone 11.2 dB from the refs' median: +16 dB at 500-630 Hz (above every ref)」と表示されます。次に、4つの方法でピックを確認します:

   • モデルフリーの tone ワード: どのバンドがすべてのリファレンスから外れているか、エネルギーシェア、テール、長さ（モデルスコアが高い場合に最も信頼できるシグナル）
   • robust: 最もラッキーなベストレンダリングではなく、新しいシードの平均
   • alt_zs: どの混同が最も近いか
   • リファレンスの隣のスペクトログラム: ffmpeg -i x.wav -lavfi showspectrumpic=s=900x360:scale=log:legend=0 x.png

   report.jsonのAudioSetタグは、それらによって選択したり方向付けたりしない間は保留されます。ルックアップの前に選択ルール（例えば、ロバスト平均）を修正し、その後でタグを報告します。

4. 問題がある部分（リリースチックの欠落、金属的なリング、長すぎるテール）については、範囲だけでなくレシピの構造を変更します。その後、繰り返します。各ラウンドの変更と数値のLOGを保持します。

5. 正直に報告します。同じ批評家によってスコアリングされた実際のリファレンスの隣に（report.json ref_scores, leave-one-out）。

Goodhartの法則、明確に述べます:

• 検索はearshot自身のモデルを最適化します。作成されたサウンドは、それらのモデルで実際の録音を日常的に上回ります。これは批評家が満足していることを意味し、サウンドが優れていることを意味するわけではありません。
• p_realは簡単に騙せます: モーダルレゾネーターに部屋とマイクノイズフロアを加えると「リアル」と読み取られます。
• 典型性はリファレンスの平均であることに対する報酬です。
• モデルチェックは飽和します: 検索後、すべてのモデルチェック、保留された言い回し、独立したリアルセットを含めて、作成されたサウンドを実際のサウンドの内側に配置します。それらを区別できるのは、測定値と耳だけです。
• リファレンスへの測定された近さで判断します: トーンバランス、すべてのリファレンスの外側のバンド、テール、長さ。また、ロバストな再レンダリングとスペクトログラムを使用します。
• 作成されたサウンドを「リアルと同等」と呼ぶ前に、人間によるブラインドテスト（ランダム順序、ラウドネス一致、隠しキー）を依頼します。

最初のテスト（demo/forge-test）では、独立した審査員がキープレスが実際のトーンバランスから8〜13 dBずれており、ポップスが長いヒスノイズテールを持つバンド無制限であることを発見しましたが、すべてのモデルチェックはそれらをリアルと呼びました。モデルフリーチェックで方向付けて作り直した後、それらは実際の録音の測定された広がりの内側に収まりました。スーッという音は真に速いものとして作り直されました。インパクト（より暗く、スウェル主導）とクリック（短いテール）は作り直されませんでした。まだ誰も人間による試聴を行っていません。

Loop 5: 映画のサウンドキットを作る（earshot sfx / earshot kit）

コードで作られた映画（シネティックフィルム、任意のキュ―シート）が効果音を必要とする場合に使用します。シンセボイスを書く代わりに、earshotの出荷済みバンクからレンダリングします。モデルはロードされません。キット全体のレンダリングは約1分で完了し、再レンダリングは数秒です。

1. プリセットから開始: earshot kit init --preset calm -o audio/kit.json（calm はテキスト主導のフィルム用、crisp はエネルギッシュなプロダクトフィルム用、minimal はデザインされた効果音のみのフィルム用、launch は音楽にカットされたフィルム用）。各ロールの note は、そのサウンドが選ばれた理由を示します。calm / crisp / minimal は riser, swell, suck をオフにします: リビールは1つの要素で解決し、ロックアップは1つのクリーンなヒットです。launch はセクション変更時に1つの riser またはリバーススウェルを鳴らし、音楽主導のフィルム用に作られた0.4サウンドを使用します（以下）。
2. フィルムに適合させる: earshot sfx list --kind hit（または --category）は、長さ、ピーク時間、ツマミとともに候補を表示します。ロールの sound を変更し、edits（ヒットまたはドロップの場合はフィルムのルートに pitch、固定ムーブの場合は dur / apex）、takes（タイピングでは12以上、その他では2-4）、level_db を設定します。earshot sfx render ID -o x.wav [--pitch E5] [--dur 0.8 --apex 0.32] で1つの候補を試聴し、測定されたオンセット/ピーク/エンドを読みます。
3. レンダリング: earshot kit render audio/kit.json --out audio/kit。テイクと kit.lock.json（測定されたオンセット、ピーク、エンド、テイクごとのラウドネス）は、ミキサーがキューフレームに配置するものです。ヒットとタッチはオンセットをフレームに、スーッという音の頂点はピークを、ライザーのヒットはエンドを（そのロールが peak に合わせている場合、そのピークはlaunchのライザーとスウェルが行うように、それらのメンバーはクライマックスの後に落ちます。kit check はエンド揃えのものに注意します）。
4. チェック: earshot kit check audio/kit.json --out audio/kit。レンダリングで使用できないもの（サウンドが取れないツマミやピッチ、0 dを超えるレベル...）を拒否します。

使用上の注意

• earshotは音を聞く代わりをするものであり、耳ではありません。特に、モデルフリーの測定（トーンバランス、テール、長さ）とロバストな再レンダリングに常に注意してください。
• すべての結果は絶対ではなく、確率的です。複数の測定を相互検証してください。
• 大きなファイルや多数のファイルを扱う場合は、MCPまたはPython APIを使用してモデルのロード時間を節約してください。
• 合成音のリアルさの判定は簡単に騙される可能性があります。常に測定値と客観的な指標を参照してください。

詳細情報

• GitHub: https://github.com/SonuSV7719/earshot
• 作者: SonuSV7719