earshot：代理的聽覺是做什麼的？

你無法聽見聲音。在沒有 earshot 讀數支撐的情況下，絕對不要說音訊聽起來如何，或某個聲音「適合」；並且在回報時要引用數值（例如「強烈匹配，z +3.9；p_real 0.96；-14.2 LUFS」）。earshot 在本地 CPU 上執行（音訊絕不離開機器，可選的 llm 命令除外），並將每個嵌入和結果快取在磁碟上。成本：每次 CLI 呼叫都是一個新程序，需要先載入模型（即使在忙碌的筆電上，即使檔案已快取，也需要約 20-40 秒）；在 MCP 伺服器或單一 Python 腳本中，模型只載入一次，重複呼叫只需數秒。若需要多次呼叫，請使用 MCP 或簡短腳本（from earshot import api; api.find(...); api.realness(...)）。

設定（僅需一次）

pip install -e "/path/to/earshot[mcp,llm]"   # 或使用儲存庫的虛擬環境：/path/to/earshot/.venv/bin/python -m earshot ...
earshot doctor                           # 套件、ffmpeg、模型（固定修訂版本、快取狀態）；--load 會計時

兩種使用方式，功能相同：

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（循環 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：earshot <command>: error: ...，退出碼為 1。

循環 1：選擇資產

earshot rank "a soft felt mallet hit on a wooden block" downloads/sfx/ --top 5 - 從資料夾中篩選清單。
earshot find winner.ogg "a single clean mallet hit" --top 3 - 找出最佳片段作為樣本修剪（開始/結束時間，以秒為單位）。每個區段都有一個 kind：stroke（從一個起音開始，直到衰減結束）和 event（屬於同一組的 stroke，例如一個按鍵的按下+彈起）在起音前 5 毫秒開始，並在衰減後結束；window 是一個邊緣被捕捉到聲音上的時間段（用於一次性查詢的簡單時間段，用於交叉淡入淡出，用於背景音）。head / tail = 前 5 毫秒 / 最後 10 毫秒相對於修剪峰值的音量（-30 dB 或更低 = 乾淨）；標記為 'head cut' 或 'tail cut' 的修剪表示在聲音內部開始或結束：不要直接使用。--kind event 僅回傳基於起音的修剪（撞擊聲、點擊聲、腳步聲），--kind texture 僅回傳簡單視窗（背景音）；預設會讀取查詢內容。
earshot describe winner.ogg --start 1.12 --end 1.48 - 它實際聽起來如何；檢查最熱門的標籤是否符合你的需求，且形狀（起音/衰減）是否與圖像匹配。AudioSet 標籤對短於約 0.5 秒的一次性聲音較弱：'tagger unsure' 或相近類別（Zipper 用於颼颼聲，Finger snapping 用於點擊聲）是中性；只有完全不同的類別（Speech、Music、Engine、Vehicle）才是危險信號。
earshot realness winner.ogg --start 1.12 --end 1.48（或整個資料夾）- 判斷你將使用的修剪：多版本檔案中的 p_real 是所有版本及其之間靜默部分的平均值。當使用者想要真實或專業製作的音效時，不要使用「可能為程式合成」的修剪，並在使用「不確定」的修剪前閱讀其證據（說明你為何保留它）。當合成聲音是重點時（程式化音樂、UI 提示音、用 earshot forge 製作的聲音），真實度是資訊，而非門檻。判斷門檻取決於長度（每個摘要都標明）：長度不超過 6 秒的聲音使用片段門檻（低 0.17 / 高 0.77），較長的檔案則使用其 4 秒視窗的平均值，並採用弱校正的檔案門檻（低 0.40 / 高 0.77），因此應比較判斷結果，而非不同長度檔案間的原始 p_real。真實錄音和專業製作的音樂與音效設計通常會讀取為真實，但 realness 聽的是聲音的聽感，而非來源：乾淨的專業合成音調（UI 音效、鐘聲、合成器刺音）也會讀取為程式合成。如果無法使用 realness（模型缺失），請明白說明未檢查真實與合成；describe 的 AudioSet 類別（Sine wave、Beep、Synthesizer）是較弱的證據。完全數位零點單獨不能證明什麼（該專案 59% 的授權真實錄音都帶有某些編輯或淡入淡出填充）。
要在兩個候選者之間選擇：earshot ab a.ogg b.ogg --query "a crisp fast air whoosh"，並使用 --a-start/--a-end/--b-start/--b-end 指定從 find 取得的修剪（A 和 B 可以是同一個多版本檔案）。可選：earshot match winner.ogg "a deep thocky key press" --alts "a clicky blue switch" "a typewriter key" 測試一個主張，或 earshot compare winner.ogg --refs approved/ [--start --end] 檢查它是否符合整體風格。

循環 2：審查混音或電影

earshot timeline film.mp4 --cues cues.json（或 soundtrack.wav --video film.mp4）- 聆聽文字記錄：帶有時間、音量和標籤的事件、段落、響度曲線、畫面剪輯、每個剪輯/提示的同步狀況。--detail low 較快，high 則標記最多 96 個事件（最重要的優先；摘要會說明標記了多少事件，因此未標記的事件不代表沒有聲音）。閱讀同步統計：offset_ms = 聲音減去畫面（負值表示提前），而 'chance' 分數表示隨機編輯點會得到的分數；只有優於隨機的同步才有意義。列為「無擊中」的剪輯仍可能帶有輕柔的颼颼聲：在加入聲音前，在 sheet 上檢查它。
earshot sheet film.mp4 -o sheet.png --cues cues.json（--from 10 --to 25 可縮放，--detail low 更快）- 帶有註解的 PNG：影格、段落、標記事件、頻譜圖、響度、節拍、按同步顏色標記的提示標記（綠色 = 在一個影格內，琥珀色 = 在 100 毫秒內，紅色 = 無聲音）。使用你的圖片檢視器開啟 PNG：間隙、堆積、遮罩和延遲擊中一目了然。
earshot critique film.mp4（--fast 跳過 AudioSet / realness 階段）- 針對專業發行影片的測量範圍的評分卡：每個指標為 ok / low / high，附帶其權重和帶有時間戳的行動，以及判斷結果（launch-grade / close / needs work / not launch-grade）。先修復關鍵列，然後在新的渲染上重新執行 1-3。其「畫面事件上的起音」比例僅計算 +-100 毫秒內的新起音（參考資料的定義）；其修復和提示會指出完全沒有聲音的剪輯，使用與 timeline 相同的匹配器。如果檔案是設定檔自己的參考影片之一，critique 會說明，並根據其他影片為其評分。
隨時取得精確指標（LUFS、真實峰值 dBTP、LRA、噪底、起音/衰減、亮度、頻段）：earshot measure mix.wav [--music] 或 MCP 的 measure 工具。

循環 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 並比較事件行和同步統計與舊的執行結果。一次只變更一件事。

循環 4：用程式製作聲音（earshot forge）

當使用者想要製作一個聲音，而不是選擇時，使用此功能：一個能聽的 AI 可以編寫合成程式碼、聆聽並改進它。每個樣本都必須是計算出來的（內部不能有錄製的音訊，甚至不能有脈衝響應）；真實錄音僅作為評審比較的參考。

在 earshot/forge/recipes/<name>.py 中編寫或選擇一個配方：SPACE（參數範圍）、DEFAULTS、TARGET、ALTS（合理的混淆項）以及 render(params, r) -> 48 kHz 陣列，使用 earshot.forge.dsp（模態共振器、接觸激發、噪音顏色、時變 SVF、計算空間、帶噪底的麥克風）構建。對真實事物的物理特性進行建模，並在參考資料上進行測量：什麼擊打什麼、什麼發出共鳴、持續多久、在什麼空間中。
執行一輪：earshot forge <recipe> --refs <real refs> --budget 144 --reps 2 --tone 1.5 --keep 4 --robust 8 --dir <round dir>，或在一個 Python 腳本中執行（模型只載入一次）： forge(recipe, critic=Critic(target, alts, refs, tone=1.5), reps=2, space={...})。
- --tone 將無模型的音調平衡和尾音納入目標。
- --reps 2 通過 2 次渲染對每個候選者進行排名，以對抗幸運渲染。
- 在忙碌的筆電 CPU 上，每 160 次渲染大約需要 3-5 分鐘，包括 30-60 秒的模型熱身。
讀取它聽到的內容。每個選取的摘要會說明，例如「聽起來像：軟木塞爆開聲、玻璃叮噹聲」、「衰減比參考資料超出 +2.4」或「音調與參考資料中位數相差 11.2 dB：在 500-630 Hz 處 +16 dB（高於所有參考資料）」。然後以四種方式檢查選取結果：
- 無模型的 tone 詞彙：哪些頻段落在所有參考資料之外、能量份額、尾音、長度（模型分數高時最可信的信號）
- robust：基於新種子的平均值，而非幸運的最佳渲染
- alt_zs：哪個混淆項最接近
- 與參考資料相鄰的頻譜圖：ffmpeg -i x.wav -lavfi showspectrumpic=s=900x360:scale=log:legend=0 x.png
report.json 中的 AudioSet 標籤在你未根據它們進行挑選或指導之前是被保留的。在查看之前先制定選取規則（例如 robust 平均值），然後再報告標籤。
根據錯誤的內容（缺少的釋放滴答聲、金屬共鳴聲、過長的尾音）更改配方的結構，而不僅僅是其範圍。然後重複。保留每輪變更和數字的 LOG。
誠實報告，並與由同一個評審評分的真實參考資料（report.json 中的 ref_scores、leave-one-out）並列比較。

古德哈特法則，請清楚說明：

搜尋最佳化的是 earshot 自己的模型。製作的聲音經常在這些模型上超越真實錄音，這意味著評審滿意，而不是聲音更好。
p_real 很容易被愚弄：模態共振器加上空間和麥克風噪底就會讀取為「真實」。
典型性會獎勵成為參考資料的平均值。
模型檢查會飽和：搜尋之後，每個模型檢查（包括保留的措辭和獨立的真實集合）都將製作的聲音置於真實聲音之內。只有測量結果和人類耳朵仍然可以區分它們。
根據與參考資料的測量接近度來判斷：音調平衡、超出所有參考資料的頻段、尾音、長度。同時使用穩健的重新渲染和頻譜圖。
在稱製作的聲音「與真實一樣好」之前，要求進行人類盲測（隨機順序、響度匹配、隱藏金鑰）。

在第一次測試（demo/forge-test）中，一位獨立評審發現按鍵聲與真實音調平衡相差 8-13 dB，爆裂聲頻段無限且帶有長嘶嘶尾音，而每個模型檢查都稱它們為真實。透過使用無模型檢查進行引導重新製作，它們現在位於真實錄音測量範圍之內。颼颼聲被重新製作成真正的快速音。衝擊聲（較暗、前導膨脹）和點擊聲（短尾音）未被重新製作。還沒有任何人類聽過。

循環 5：製作電影的音效包（earshot sfx / earshot kit）

當程式生成的電影（動態電影、任何提示表）需要其效果時使用：從 earshot 的內建庫中渲染它們，而不是編寫合成語音。無需載入模型；整個套件大約在一分鐘內渲染完成，重新渲染則只需數秒。

從預設開始：earshot kit init --preset calm -o audio/kit.json（calm 用於以文字為主導的電影，crisp 用於充滿活力的產品電影，minimal 用於僅設計效果的電影，launch 用於配合音樂剪輯的電影）。每個角色的 note 會說明為何選擇了它的聲音。calm / crisp / minimal 會關閉 riser、swell 和 suck：揭示時只對一個元素進行解析，鎖定時是一個乾淨的撞擊。launch 在段落變更時使用一個 riser 或倒轉 swell，並使用專為音樂主導電影製作的 0.4 聲音（如下）。
使其適合電影：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] 試聽一個候選者，並讀取其測量的起音/峰值/結束。
渲染：earshot kit render audio/kit.json --out audio/kit。takes 和 kit.lock.json（每個 take 的測量起音、峰值、結束、響度）是混音器放置在提示影格上的內容：撞擊和觸摸的起音在影格上，颼颼聲頂點的峰值在 apex，riser 撞擊的結束在結尾（當角色對齊 peak 時，它會對齊到峰值：launch 的 riser 和 swell 就是這樣：這些成員在其高潮之後落下；kit check 會標註結尾對齊的）。
檢查：earshot kit check audio/kit.json --out audio/kit。它會拒絕渲染無法使用的內容（聲音無法承受的旋鈕或音高，超過 0 d...

…

[已截斷以供翻譯]

earshot：代理的聽覺