real-sound 是做什麼的？
您是您無法聽見的影片的聲音監督。配樂僅由真實、專業錄製或製作的音訊組成（一首獲得授權的音樂曲目、真實的 Foley 音效和 SFX、真實的環境音），由確定性混音器放置在畫面的提示影格上，透過測量而非聆聽來評估，經過五個角度的評論，由一個代理修復，最後進行母帶處理、標註來源並封裝。程式碼負責選擇、修剪、放置、調整音量、聲像、均衡、透過重採樣調整音高、拉伸音樂時間並進行母帶處理；程式碼絕不產生聲音。
標準是專業的發佈影片：螢幕上每個動作都有其對應的聲音，使用同一種材質調色板，音樂在主角登場時達到高潮，其他地方保持克制，一個收尾的標誌，最後歸於寂靜。規則：references/sound-design.md（以及 earshot 儲存庫中的 docs/launch-video-sound.md，其中包含參考設定檔：7 部專業發佈影片）。
<skill> 以下是此資料夾。Python： {{PY}}（以及在每個提示模板中）指的是單一一個包含 numpy、scipy、soundfile 和 earshot 套件的直譯器：即 earshot 儲存庫的虛擬環境（Windows 上為 <earshot repo>/.venv/Scripts/python.exe，其他系統為 <earshot repo>/.venv/bin/python），或任何可以執行 <python> -c "import earshot" 的 Python。Windows 上的裸指令 python 通常是 Microsoft Store 的存根程式，會失敗。當您執行命令或將提示傳遞給子代理時，請用完整路徑取代 {{PY}}（其他預留位置列於 references/process.md）。使用 -I 參數執行腳本（隔離模式：下載的檔案永遠不會遮蔽模組）；除了 scripts/licences.py（audit.py 和 credits.py 匯入的授權政策模組）之外，每個腳本都會印出 --help。
流程
| 步驟 | 執行者 | 輸出 | 關卡 |
|---|---|---|---|
| 0. 提示列表 | 主導 | out/cues.json | 根據影片程式碼計算出的同步影格 |
| 1. 簡報 | 主導 | audio/SOUND_BRIEF.md | 每個提示都有一個聲音需求（或「無聲」） |
| 2. 音源搜尋（依類別並行） | 搜尋代理 | audio/assets/<cat>/，清單 | 每個檔案經過測量 + earshot realness 在被使用的修剪片段上標示為「real 或 pro-produced」（「uncertain」需附上證據及在清單中重新檢查修剪層級） |
| 3. 授權審核 | 審核員 | audit.json | audit.py 對影片使用的音源回傳結束碼 0 |
| 4. 音樂剪輯 | 音樂監督 | audio/design/music.json | 網格已驗證，高潮在揭示點上，拼接處乾淨 |
| 5. 設計片段（依類別並行） | 設計師 | audio/design/<cat>.json | 獨立渲染 + QA 通過 |
| 6. 整合 | 主導 | 配樂、分軌、報告、追蹤 | 母帶關卡 (+-0.5 LU, <= -1.5 dBTP) |
| 7. QA + 聆聽 | 主導 | out/qa/qa.json, earshot 時間軸 / 圖表 / 評論 | 無 QA 失敗 |
| 8. 評論（5 個角度並行，唯讀） | 評論者 | 排列問題 + 測試操作 | |
| 9. 修復 | 一個修復者 | 設計 | QA：無回歸 |
| 10. 母帶、來源、封裝 | 主導 | CREDITS.md，描述文字，影片 | 來源結束碼 0，延遲 0 |
每個步驟的詳細資訊、角色以及每個評論者測量的內容：references/process.md。每個子代理的提示都是 templates/prompts/ 中現成可填寫的簡報。
0. 從畫面建立提示列表
每個聲音都位於影片程式碼計算出的影格上：接觸影格、彈入的 50% 影格、動作的速度峰值、上升音效的撞擊點、商標變得可閱讀的影格。Cinetic 影片已經有 out/cues.json（export-cues.ts）；對於其他情況，請從時間軸常數撰寫相同的格式（templates/cues.json）。穩定的 ID（act:thing:n）允許規則用正則表達式匹配類別的動作。
1. 簡報
複製 templates/SOUND_BRIEF.md 到 audio/SOUND_BRIEF.md：概念（調色板、音樂的起伏、位置）、畫面地圖（每個提示：螢幕上顯示什麼、聲音需求）、環境音區域、允許的授權、品質標準、檔案佈局。這是每個子代理都會收到的合約。選取品牌的個性列（references/sound-design.md §3）。
2. 音源搜尋，依類別（templates/prompts/sourcing.md）
典型的發佈影片類別：ui（點擊、輕敲、切換、爆裂聲）、keyboard、motion（颼颼聲、上升音效）、impacts（揭示撞擊、標誌）、ambience、music；角色影片會增加 foley、其世界、其物體。Freesound（CC0 / CC BY；高品質預覽 cdn.freesound.org/previews/<id//1000>/<id>_<user>-hq.ogg）、Mixkit（WAV assets.mixkit.co/active_storage/sfx/<id>/<id>.wav）、音樂則使用作曲者資料庫；授權在每個項目的頁面上閱讀（references/licences.md）；依序禮貌下載；對每個檔案進行測量：
{{PY}} -I <skill>/scripts/analyze.py audio/assets/ui/* --png out/audio-review/ui --out out/audio-review/ui.json
{{PY}} -m earshot realness audio/assets/ui/ # 關卡："real 或 pro-produced"（重新檢查修剪片段：--start --end）
{{PY}} -m earshot rank "a single crisp trackpad click" audio/assets/ui/ --top 5
{{PY}} -m earshot match <file> "a soft cork pop" --alts "a gunshot" "a balloon burst"
{{PY}} -m earshot find <long take> "a single mechanical key press" --top 8 # 修剪；跳過任何標記為 head cut / tail cut 的片段
3. 授權審核（templates/prompts/licence_audit.md）
審核員記錄每個頁面的說明（licence_seen，licence_confirmed）到 audio/assets/manifests/audit.json；腳本檢查其餘部分（分類、ID 與 URL 比對、檔案解碼、持續時間、來源行）：
{{PY}} -I <skill>/scripts/audit.py --root . --report out/qa/mix_report.json [--fetch]
允許的授權：CC0、公有領域、CC BY 2.0-4.0、Mixkit 免費授權、Pixabay。禁止的授權：NC、ND、SA、Sampling+、個人、自訂、有爭議。未驗證 = 封鎖。
4. 音樂（templates/prompts/music_supervisor.md）
一首符合影片結構的授權曲目。根據影片標準撰寫起伏（templates/arc.json），然後：
{{PY}} -I <skill>/scripts/arrange.py audio/assets/music/<track> --film-bpm 120 --arc audio/arc.json --out out/audio-review/music/arrange.json
它會調整節奏，將網格移動到測量到的攻擊點上（節拍追蹤器延遲 20-50 毫秒），建議下拍相位，將影片高潮錨定在最強烈的高潮候選點上，並在小節線處草擬段落（一個可直接貼上的 music 區塊）。下拍是弱點：當它顯示 LOW 信心（在測試過的兩個曲目中，有一個會差半小節）時，根據第一個音符、段落開頭和條表格中的和弦變化，從印出的兩個網格中決定，然後用 --phase N 重新執行。然後根據判斷進行編輯：和聲在每個拼接處連續，下拍的低音在主角影格上，最後的和弦在標誌上，tail_fade 直到結束。
5. 設計片段，依類別（templates/prompts/designer.md）
audio/design/<category>.json 包含樣本（修剪）、切片（將一個包含多次撞擊的長錄音切成單次撞擊）、音源池、關於提示事件的規則、自由放置、環境音基底、音樂區塊。參考每個鍵值和真實範例：references/design-format.md；一個完整的發佈影片範例：templates/design_fragment.json（其檔案名稱是像 mk-0000_mouse-click.wav 這樣的預留位置：一旦每個檔案被清單中的真實錄音取代後才會渲染；在此之前 mix.py 會停止並列出缺失的檔案）。
單獨驗證：
{{PY}} -I <skill>/scripts/mix.py --only ui --dump out/audio-review/ui/dump # 每個修剪片段為 WAV + 數值
{{PY}} -I <skill>/scripts/mix.py --only ui --trace out/audio-review/ui/adds.json --out out/audio-review/ui/solo.wav
{{PY}} -I <skill>/scripts/qa.py --only ui --report out/audio-review/ui/solo_report.json --stems out/audio-review/ui/solo_stems --trace out/audio-review/ui/adds.json --out out/audio-review/ui/qa.json
{{PY}} -m earshot timeline out/audio-review/ui/solo.wav --cues out/cues.json
6-7. 整合、QA、聆聽
{{PY}} -I <skill>/scripts/mix.py --root . --design audio/sounddesign.json --cues out/cues.json --trace out/qa/adds.json
{{PY}} -I <skill>/scripts/qa.py --layers # 點擊、邊緣、可聽度、刺耳度、響度、覆蓋率、同步、密度
{{PY}} -I <skill>/scripts/qa.py --listen --realness --video out/film.mp4 # + earshot 時間軸、圖表、評論、真實性
{{PY}} -m earshot critique out/audio/soundtrack.wav --video out/film.mp4 # 與專業發佈影片比較的評分卡
{{PY}} -m earshot sheet out/audio/soundtrack.wav -o out/qa/sheet.png --video out/film.mp4 --cues out/qa/cues_sounded.json
qa.py 將每個發現綁定到導致它的規則和樣本（追蹤）。它可以在沒有模型的情況下使用；--listen 會增加 earshot 的逐字稿（out/qa/qa_timeline.txt）、註釋圖表和評分卡。
8-9. 評論和修復
五個唯讀的評論者並行運作，每個都有自己的提示：critic_sync.md、critic_edges.md、critic_masking.md、critic_tonal.md、critic_director.md。每個評論者在其自己的資料夾中將其修復測試為一個變體：
{{PY}} -I <skill>/scripts/variant.py --ops out/audio-review/critic_tonal/ops_v1.json --out out/audio-review/critic_tonal/v1 --render --qa
並回傳排序後的問題，以及確切的操作和前後對比數據。然後由一個修復者（fixer.md）合併操作、解決衝突、檢查合併後的變體與先前的 qa.json，並套用它（variant.py --apply，原始檔案會備份）。對已確認的故意例外情況，用 "qa_ok": "<reason>" 標記。至少進行一輪；當音量或音樂剪輯有變更時進行第二輪。
10. 母帶、來源、封裝
mix.py 使用 master.py 進行母帶處理（-14 LUFS、真實峰值限制器、上限 0.77 線性；閘控 +-0.5 LU 且 <= -1.5 dBTP）。
{{PY}} -I <skill>/scripts/audit.py --root . --report out/qa/mix_report.json # 結束碼 0
{{PY}} -I <skill>/scripts/credits.py --root . --design audio/sounddesign.json --audit audio/assets/manifests/audit.json
node <skill>/scripts/mux.mjs --video out/film.mp4 --audio out/audio/soundtrack.wav --out out/film_sound.mp4
{{PY}} -m earshot timeline out/film_sound.mp4 --cues out/qa/cues_sounded.json # 完成檔案，聽過
CREDITS.md + out/CREDITS_description.txt（貼到影片說明中：CC BY 來源必須放在那裡）。mux.mjs 會串流複製畫面，並將 AAC 音訊裁切至與畫面相同的長度。
發佈影片：聲音地圖
| 畫面 | 聲音 | 位於 |
|---|---|---|
| 游標移動、懸停、滾動、進度、串流文字 | 無聲（由音樂承載） | |
| 點擊 / 輕敲 | 影片中一個真實的點擊音色，按下 + 釋放約 85 毫秒後，每次音量相同 | 按下的影格 |
| 打字 | 一個真實的鍵盤，切片；最多約每秒 12 個鍵，超過約每秒 25 個字元時每個字一個鍵；音樂降低 6-10 dB | 每個發聲的字元 |
| 卡片 / 晶片 / 徽章出現 | 一個柔和的真實爆裂聲或滴答聲，在一串中逐漸升高 | 其移動的 50% 處 |
| 切換、鎖定、計數器的最終值 | 一個真實的鎖扣 / 點擊 / 清脆的滴答聲 | 接觸 / 鎖定影格 |
| 相機縮放移動、揮動、縮放（每部影片約 2 次） | 一個真實的颼颼聲，最高點在速度峰值 | 速度峰值 |
| 硬切 | 無聲 | |
| 緊張到揭示 | 音樂的漸強，或一個真實的上升音效在撞擊前 30-250 毫秒結束 | 撞擊 |
| 英雄揭示 | 音樂的 DROP（剪輯曲目使其下拍落在這裡）+ 可選的一個真實撞擊 | 影格 |
| 標誌 / 鎖定 | 音樂在小節線處停止或濾波，0.2-0.7 秒接近無聲，一個符合調性的柔和音符，尾奏歸於寂靜 | 商標可閱讀的影格 |
音量：-14 LUFS，AAC 後真實峰值 <= -1 dBTP，LRA 5-9 LU，最大聲的時刻在高潮（影片 30-60% 處），標誌比其低 8-20 dB，每 10 秒約 5 個設計音效，音效乾燥且置中。測量標準和廉價的跡象：references/sound-design.md。
工具
| 需求 | 工具 |
|---|---|
| 測量錄音（格式、底噪、頻寬、起音、峰值、節奏 / 調性）+ 頻譜圖 PNG | scripts/analyze.py |
| 聆聽錄音：真實 vs 合成、聽起來像什麼、最佳匹配、長檔案中的最佳片段 | {{PY}} -m earshot realness / describe / match / rank / find / compare / ab |
測量一個檔案或其一段區間的音量 / 亮度 / 起音（--start --end） | {{PY}} -m earshot measure（Python 中：from earshot import api; api.measure(...)，api.find、api.realness 等亦同） |
| 授權 + 檔案審核 | scripts/audit.py（政策在 scripts/licences.py） |
| 音樂網格、下拍、小節線編輯草稿 | scripts/arrange.py |
渲染設計（+ 獨立 --only、--dump 修剪、--trace 用於 QA） | scripts/mix.py |
| 母帶及響度量測 | scripts/master.py（--measure） |
| 與放置相關的客觀 QA | scripts/qa.py（--layers、--listen、--realness） |
| 評論變體、修復者的套用 | scripts/variant.py |
| 給 CREDITS.md 和影片說明的來源 | scripts/credits.py |
| 將配樂放到畫面上 | scripts/mux.mjs |
| 聆聽整個混音 / 影片；附註釋的畫面；發佈影片評分卡 | {{PY}} -m earshot timeline / sheet / critique |
檔案
audio/SOUND_BRIEF.md 合約 (templates/SOUND_BRIEF.md)
audio/assets/<category>/ 下載的錄音檔 (<source>-<id>_<slug>.<ext>；切勿提交或發布)
audio/assets/manifests/<cat>.json 每個錄音檔一個條目 (templates/manifest_entry.json)
audio/assets/manifests/audit.json 授權審核 (templates/audit_entry.json)
audio/sounddesign.json 頂層：包含、匯流排、母帶 (templates/sounddesign.json)
audio/design/<category>.json 每個設計師一個片段 (templates/design_fragment.json)
out/cues.json 畫面的提示事件 (templates/cues.json)
out/audio/soundtrack.wav, stems/ 母帶及其分軌
out/qa/ mix_report.json, adds.json, cues_sounded.json, master.json, qa.json
out/audio-review/ 每個類別和評論者的工作、變體、傾印（稽核軌跡）
CREDITS.md, out/CREDITS_description.txt
參考資料
references/process.md：角色、步驟、每個評論者測量的內容、閾值及其來源references/sound-design.md：發佈影片聲音標準、材質調色板、規避的大忌、廉價的跡象references/design-format.md：設計 JSON 格式、所有鍵值（含類型）、真實範例references/licences.md：每個來源（Freesound / Mixkit / 作曲者）如何閱讀授權資訊，哪些被允許/禁止- 每部發佈影片的參考設定檔：earshot 儲存庫中的
docs/launch-video-sound.md