AIチュートリアル

Earshotでコーディングエージェントに音声分析とサウンド合成機能を与える方法

Earshotのインストール方法、コマンドラインまたはPythonからの音声検査、録音内のイベント検出、映画サウンドトラックの評価、永続MCPサーバーの実行、Forgeによるコード合成エフェクトの生成方法を学びます。

2026年10月16日約18分で読了

Earshotでコーディングエージェントに音声分析とサウンド合成機能を与える方法

Earshotの機能

Earshotは、AIコーディングエージェント向けに設計されたローカル音声分析・音響合成ツールキットです。音声を、自然言語による説明、較正済みの一致スコア、時刻付きイベント、客観的な測定値、ビジュアル音響シート、ローンチ映像の批評など、構造化された根拠に変換します。

たとえば、ある効果音が深い機械式キー押下のように聞こえるか、長い録音のどこで特定のイベントが発生するか、2つの候補音がどのように異なるか、サウンドトラックが映像のカットと同期しているか、といった質問に答えられます。また、earshot forgeを使ってコードから効果音を合成することもできます。

EarshotはCPU上でローカル実行でき、コマンドラインインターフェース、Python API、Claude Codeなどのツール向けMCPサーバーから利用できます。初回のモデルダウンロード後は、標準的な分析機能をオフラインで実行できます。

主な機能

音声を説明: describeは、較正済みタグ、別解釈、AudioSetラベル、測定値を返します。
候補を照合・順位付け: matchは1つのファイルが説明にどの程度合うかを評価し、rankはクエリに対して複数ファイルを並べ替えます。
イベントを検出: findは長い録音内で最も一致する瞬間を特定し、トリミングに使える開始時刻と終了時刻を返します。
音声を比較: compareは参照録音を検索し、abは2つの音声またはトリミングの違いを説明します。
リアルさを評価: realnessは、音声がコードで合成された音ではなく、実録音またはプロ品質の録音に似ているかを推定します。
サウンドトラックを分析: timelineは、イベント、セクション、レベル、ビート、映像のカットまたはキューフレームとの同期を特定します。
ビジュアルレポートを作成: sheetは、映像フレーム、イベント、セクション、波形、スペクトログラム、ラウドネス、同期マーカーを含む注釈付きPNGを生成します。
ローンチ映像を批評: critiqueは、プロが制作した7本のローンチ映像から構築したプロファイルと映像を比較し、タイムスタンプ付きの修正案を提示します。
客観的に測定: measureは、モデルを使わずにLUFS、トゥルーピーク、ラウドネスレンジ、エンベロープ、スペクトル、テンポ、キーなどの特性を報告します。
効果音を合成: forgeはコードから音声をレンダリングし、Earshotの批評機能とモデル非依存の測定値を使ってレシピパラメーターを検索します。

Earshotをインストールする

前提条件

Python 3.10以降、およびシステムのパスから利用できるffmpegとffprobeが必要です。EarshotはCPU専用で、GPUは使用しません。

環境を作成する

git clone https://github.com/Leonxlnx/earshot
cd earshot
python -m venv .venv
.venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv/bin/python -m pip install -e ".[mcp,llm,dev]"
.venv/bin/python -m earshot doctor --load

Windowsでは、.venv/bin/pythonを.venv/Scripts/pythonに置き換えてください。

モデルを使用する最初の操作では、EARSHOT_HOMEを設定していない限り、リポジトリ内の.cache/hfに約1.4 GBがダウンロードされます。Earshotは、テキストと音声の埋め込みにCLAPモデルlaion/larger_clap_generalを、AudioSetタグ付けにMIT/ast-finetuned-audioset-10-10-0.4593を使用します。

依存関係、データファイル、モデル、精度、CPU設定を確認する必要があるときは、診断コマンドを実行してください。

.venv/bin/python -m earshot doctor --load

CPUとキャッシュの設定

EARSHOT_THREADSはTorchのCPUスレッド数を制御します。
EARSHOT_HOMEはキャッシュのルートを変更します。
EARSHOT_PRECISION=fp32はFP32を強制します。デフォルトでは、ネイティブサポートのあるCPUではBF16、それ以外ではFP32が使用されます。
EARSHOT_OFFLINE=1は、モデルのダウンロード後にオフライン動作を有効にします。

基本的なコマンドラインの使い方

音声を説明する

未知のファイルについて簡潔な説明が必要な場合は、describeから始めます。

earshot describe enter.ogg

概要には、長さ、トランジェント形状、考えられる音のカテゴリ、較正済みzスコア、ピークレベル、明るさ、別の解釈などが含まれます。完全な構造化結果を得るには--jsonを、保存するには--out result.jsonを追加します。

特定の説明をテストする

求める音がすでに分かっている場合はmatchを使用します。別の説明を加えると、対象と混同されやすい音を区別しやすくなります。

earshot match key.ogg "a deep thocky mechanical keyboard press" --alts "a clicky blue switch keyboard" "a mouse click"

結果には、コサイン類似度、語彙で較正されたzスコア、strong、plausible、weak、no matchなどの判定が含まれます。

複数の候補ファイルを順位付けする

コレクションから最適な候補を選ぶには、説明に続けてパスを渡します。

earshot rank "a fast crisp air whoosh" sounds/one.wav sounds/two.wav sounds/three.wav

エージェントが複数の効果音をダウンロードまたはレンダリングし、根拠に基づいて順位付けする必要がある場合に便利です。

長い録音内のイベントを検出する

findコマンドは録音内を検索し、サンプルのトリミングに使える時刻を返します。

earshot find keys.ogg "a single mechanical key press" --top 4

各結果には、開始時刻、終了時刻、長さ、スコア、判定が含まれます。これらのタイムスタンプを使って、より大きなソースからイベントだけを正確に抽出できます。

モデルの解釈なしで測定する

意味的な判定ではなく、再現可能な音声特性が必要な場合は、measureを使用します。

earshot measure soundtrack.wav --json

音量、真のピーク、ラウドネスレンジ、エンベロープ、スペクトル、テンポ、キーなどの客観的な情報が出力されます。

映画のサウンドトラックを分析する

リスニングタイムラインを作成する

timelineを使うと、秒単位のリスニングトランスクリプトを作成できます。動画を指定すると、Earshotは映像のカットやキーフレームとの同期を評価できます。

earshot timeline soundtrack.wav --video film.mp4 --json

結果には、検出されたイベント、セクション、レベル、ラウドネス、ビートグリッド、音声と映像の同期に関する証拠などを含められます。

注釈付きサウンドシートを作成する

サウンドシートは、主要な分析レイヤーを1枚の画像にまとめ、ビジュアルエージェントが確認できるようにします。

earshot sheet soundtrack.wav --video film.mp4 -o out.png

フレーム、音声イベント、波形、スペクトログラム、同期を表示するEarshotのシート

生成されるPNGには、代表フレーム、ラベル付きイベント、セクション、波形、スペクトログラム、ラウドネス、ビート、同期マーカーをまとめて表示できます。

ローンチフィルムの批評を生成する

critiqueを実行すると、映画をEarshotに付属する7本のプロ向けローンチフィルムのプロファイルと比較できます。

earshot critique film.mp4

レポートには判定、プロファイル範囲内または範囲外にある指標、タイムスタンプ付きの修正案の優先順位が示されます。これは品質を普遍的に測るものではなく、特定のローンチフィルムのスタイルとの比較として扱ってください。

好みの映画からプロファイルを作成することもできます。

earshot profile reference-one.mp4 reference-two.mp4 reference-three.mp4 -o custom-profile.json

PythonからEarshotを使う

Pythonインターフェースを使うと、操作ごとに新しいプロセスを起動せずに済みます。個々のCLI呼び出しではモデルが読み込まれるため、応答まで約20～40秒かかることがあり、この方法は有用です。

import earshot

earshot.describe("whoosh.wav")
earshot.find("typing.ogg", "a single isolated key press")
earshot.timeline("soundtrack.wav", video="film.mp4")

from earshot import api
api.rank("a crisp UI click", ["click-a.wav", "click-b.wav"])
api.critique("film.mp4")

earshot.api名前空間では、ランキング、批評、複数ファイルのリアリティ分析などの操作を利用できます。これらの呼び出しを1つのPythonプロセス内で行うと、読み込み済みのモデルを再利用できます。

EarshotをMCPサーバーとして実行する

繰り返しリクエストを行うエージェントでは、モデルが初回リクエスト後もウォームな状態に保たれるため、個別のCLI呼び出しよりMCPサーバーが適しています。

claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /path/to/earshot/.venv/bin/python -m earshot mcp

別のMCP互換クライアントでは、同等の設定をその.mcp.jsonに追加します。

{"mcpServers":{"earshot":{"command":"/path/to/earshot/.venv/bin/python","args":["-m","earshot","mcp"],"env":{"EARSHOT_THREADS":"3"}}}}

低速なマシンでは、MCP_TIMEOUT=60000を指定してClaude Codeを起動します。オプションのllm_critiqueツールは、環境変数からGEMINI_API_KEYを読み取ります。設定ファイルにAPIキーを直接記載しないでください。

Earshot Forgeでサウンドを生成する

Forgeは録音音声を埋め込まずにサウンドを生成します。レシピでは、モーダル共鳴器、接触励振、フィルタリングしたノイズ、計算された部屋、マイクモデルなどの物理合成コンポーネントを使用します。

まず、付属のレシピを一覧表示します。

earshot forge

リポジトリには、クリック、衝撃音、キー入力、ポップ音、風切り音のレシピが含まれています。実録音をリファレンスとしてキー入力音を検索するには、次を実行します。

earshot forge keypress --refs path/to/real/keypresses/ --budget 144 --reps 2 --tone 1.5 --keep 4 --robust 8 --dir made/keypress

想定される混同対象を指定しながら、具体的な説明を目標にするには、次を実行します。

earshot forge whoosh --target "a fast crisp air whoosh" --alts "a wind gust" "a sword swing" --refs path/to/real/whooshes/ --tone 1.5 --dir made/whoosh

Forgeはパラメーター化した候補をレンダリングし、批評モデルでスコアを付け、良好な結果を保持しながら進化的探索によって変異させます。スコアリングでは、説明との一致、指定された代替候補、推定されるリアリティ、リファレンスとの近さ、測定された形状、音色バランス、余韻の挙動、長さが考慮されます。

出力には、多様なWAVファイルと、候補パラメーターおよびスコアを含むreport.jsonが含まれます。--robust Nを指定すると、選択した候補が新しい乱数シードで再度レンダリングされます。これにより、1回だけ成功したのではなく、レシピが安定して機能するかを確認できます。

Forgeの結果を慎重に評価する

ForgeはEarshot独自のモデルに対して最適化するため、モデルスコアが高くても、そのサウンドが知覚的に優れているとは限りません。

生成されたサウンドの1/3オクターブバランス、余韻、長さをリファレンス録音と比較してください。リファレンスと並べてスペクトログラムを確認し、堅牢性を確認する再レンダリングを試し、品質が重要な場合は人間によるブラインドテストを実施してください。READMEでは、モーダル共鳴器、部屋の応答、ノイズフロアを組み合わせる手法などによって、リアリティモデルが欺かれる可能性があると明確に警告しています。

高度なワークフローのヒント

作業内容に合ったインターフェースを使う。 CLIは少数の調査に便利です。繰り返し分析する場合は、モデルを読み込んだままにできるよう、1つのPythonプロセスまたはMCPサーバーを使います。
広く調べてから仮説を検証する。 describeを実行して目標の説明を作成し、その後、明示的な代替候補とともにmatchを使います。
意味的な証拠と客観的な証拠を分ける。 モデルベースの判定を、measure、音調バランスの確認、波形の検査、スペクトログラムと組み合わせます。
構造化された出力を保存する。 別のプログラムやエージェントが自然言語の要約ではなく、すべてのフィールドを検査する必要がある場合は、--jsonまたは--outを使います。
実際のリファレンス録音を使う。 リファレンスディレクトリは比較とForgeの評価を向上させますが、録音の出所とライセンスについては、引き続き利用者が責任を負います。
付属のエージェントスキルをインストールする。 skills/earshotとskills/real-soundを~/.claude/skills/またはプロジェクトの.claude/skills/にコピーするか、シンボリックリンクを作成します。これらには、コマンドの選択、判定の解釈、サウンドトラック制作、ミキシング、QA、ライセンス確認についての説明があります。

限界を理解する

Earshotは、ラウドネス、タイミング、映像との同期、単独で目立つ音のマッチング、候補のランキング、明らかにコードで合成された音源の特定に最も強みを発揮します。複雑なミックスから抽出されたタグや、音楽のジャンルおよびムードに関する判定は、手がかりとして扱ってください。

好み、感情、出所、ライセンス、発話内容を判定することはできません。また、モデルは14 kHzを超える周波数を評価しません。リアルさの判定は証拠であって証明ではなく、組み込みのローンチプロファイルも、それを作成するために使用された7本の映画だけを反映しています。

本番ワークフローでスコアを信頼する前に、測定結果についてはリポジトリの検証ドキュメントを、限界については限界に関するドキュメントを確認してください。

まとめ

Earshotは、ローカルCPUツールを使ってコーディングエージェントが音を検査・作成するための実用的な方法を提供します。まずdescribe、match、findから始め、完成した映画作品にはtimeline、sheet、critiqueへ進み、すべてコードで作成したパラメータ化エフェクトが必要な場合はForgeを使います。信頼できる判断を行うには、モデルの判定を測定、リファレンスとの比較、目視検査、人間による試聴と組み合わせてください。