歌曲編輯分析是做什麼的？

概述

使用此技能將歌曲轉化為實用的編輯智慧：節奏、節拍格、段落映射、能量曲線、剪輯優先順序、素材適用性備註、時間軸標記，以及一份給代理人使用的素材選擇簡報。

內建腳本是預設路徑，因為它能保持分析的可重現性，並同時產生人類可讀與機器可讀的輸出。

工作流程

確認音頻路徑，並為交付成果建立輸出資料夾。
確保 Python 相依套件已安裝：librosa、numpy、scipy、matplotlib、pandas、scikit-learn 與 soundfile。
執行 scripts/analyze_song_for_editing.py <audio-file> --out <output-folder>。
檢查產生的能量時間軸圖片與段落 CSV。若自動分段將忙碌的段落過度拆分，請在最終回覆或獨立的 markdown 檔案中合成一個更簡單的巨觀段落映射。
當另一位代理人將選擇素材、組合編輯或對素材候選項目評分時，使用代理人素材簡報。
對於下游製作，使用 $footage-review-pack 策劃來源，$beat-synced-montage-builder 組合編輯，以及 $edit-delivery-qa 驗證最終渲染。

腳本輸出

對於名為 my_song.mp3 的輸入，腳本會寫入：

my_song_beats.csv：每個偵測到的節拍，包含時間、估計小節/節拍位置、能量、低頻、亮度、瞬態強度以及剪輯優先順序。
my_song_cut_markers_30fps.csv：主要及次要剪輯標記，含 30fps 時間碼與簡潔的標記備註。
my_song_sections.csv：偵測到的結構區域，含平均能量、聲音特性、素材適用性與剪輯策略。
my_song_phrases.csv：8 拍樂句層級的編輯備註。
my_song_energy_timeline.png：波形、能量曲線、素材提示與偵測到的段落。
my_song_editing_guide.md：人類可讀的編輯指引。
my_song_agent_footage_brief.json：結構化的素材選擇指令（供另一位代理人使用）。
my_song_analysis.json：機器可讀的整體摘要。

發音鎖定剪輯格（v2 引擎，密集剪輯時優先使用）

當編輯需要在歌曲每個容許的時刻進行剪輯（包括快速爆發段），跳過標記閾值，直接建構原始發音格：

env    = librosa.onset.onset_strength(y=y, sr=sr, hop_length=512)
onsets = librosa.onset.onset_detect(onset_envelope=env, sr=sr, hop_length=512,
                                    backtrack=False, delta=0.02, units="time")

delta=0.02 會捕捉所有發音（使用 0.03-0.04 可獲得較乾淨的格）。合併距離小於 0.13 秒的發音，保留較強者；量化至幀：int(round((t-t0)*FPS))；強制在第 0 幀剪輯；刪除距離結尾 2 幀以內的剪輯。在稀疏段落保持靜態，在忙碌段落則爆發剪輯——絕不插入格點外的填充剪輯。強度位於前四分位數的發音可獲得強調效果（如推近縮放）。將任何估計的節拍格對齊到 60ms 內最近的實際發音（瞬態可能偏離穩定節奏格約 35ms）；對於轉換/風格切換的時刻，使用無條件進位而非四捨五入進行量化，使變化落在包含該瞬態的幀上。

包絡跟隨器（驅動連續特效）

對於音頻反應式特效，將發音包絡重新取樣至幀格，以第 95 百分位數歸一化，然後使用單極點峰值保持（即時起音，衰減爲 exp(-1/(fps*0.22..0.25))）。節拍脈衝用於推近/綻放效果：每個節拍加上 amp * exp(-(t-t_beat)/0.16)，其中 amp 為能量加權。保持低頻/能量/高頻/瞬態作為獨立歸一化通道——絕不使用單一響度標量——並讓發音事件通道保持未平滑狀態。渲染特效時，使用與編輯完全相同的開始/持續時間視窗，使脈衝與剪輯共用一個包絡（透過建構同步）。

解讀規則

將節奏、節拍和小節視為估計值，直到對照波形或透過聽覺確認。節拍格通常足以進行粗略編輯，但強拍標記可能會偏移一個節拍或樂句。

使用以下能量階梯進行素材選擇：

能量 1 / 極低：氛圍、標題、細節鏡頭、慢速平移、安靜鋪陳。
能量 2 / 低：準備、期待、背景、慢動作、動作前。
能量 3 / 中等：可見動作、反應、節奏性 B-roll、2-4 拍剪輯。
能量 4 / 高：主動動作、衝擊相關鏡頭、快速 B-roll、1-2 拍剪輯。
能量 5 / 最高：最強素材、碰撞、揭示、快速甩鏡、VFX 特效、快速交替、0.5-1 拍剪輯。

使用主要剪輯點進行主體變化、衝擊、硬切、揭示、速度斜變落地與標題出現。使用次要剪輯點進行角度變化、連續剪輯、較小的 B-roll 切換與速度斜變開始。

代理人素材選擇

當代理人將選擇素材時，將 *_agent_footage_brief.json 與任何可用的素材庫傳遞給它。指示代理人：

根據簡報的分類法，為每個候選素材標記 content_type。
為每個候選素材評分 motion_intensity（1-5 分）。
將素材強度與每個段落的 energy_level 匹配，允許加減 1 級，除非編輯需要刻意對比。
將 peak_impact 與動作強度 5 的素材保留給能量最高的段落。
將主體變化、衝擊與揭示放在主要剪輯點上。
當可用素材強度低於音樂時，使用較短持續時間、較緊湊裁切、速度斜變或重複衝擊細節。

人類面對向指引

除了原始數據外，始終提供簡潔的巨觀地圖。編輯需要音樂判斷，而不僅僅是節拍列表。指出：

何處應保持鏡頭停頓。
何處開始第一個有意義的節奏剪輯。
何處開始高峰或高潮。
哪個段落值得使用最佳素材。
最強剪輯點的時間戳。
任何不確定性，尤其是當段落偵測過度拆分或強拍可能偏移時。

下游技能

此技能產生音樂智慧。使用配套技能完成其餘可重複工作流程：

$footage-review-pack：建構入圍名單、檢閱圖庫、清單與來源出處。
$beat-synced-montage-builder：將素材映射到剪輯標記，並渲染社群媒體混合版本。
$edit-delivery-qa：檢查最終渲染結果、聯絡表、時間軸密度與交付就緒狀態。

歌曲編輯分析