notasimrazzaq/AI-Video-Editor

在用戶自己的影片上加入動態圖形

安裝在 HyperFrames 技能之上的工作區層。對於 HTML/時間軸機制，請載入 hyperframes-core（合成合約）和 hyperframes-animation（GSAP 規則）；最接近的 上游路線是 talking-head-recut。此技能加入了創作者的家規，衝突時以家規為準。

快速路徑（已在 reel-sep30 上驗證，3:20 烏爾都語/英語 Reels，Paper Cut 風格）

1. powershell -NoProfile -ExecutionPolicy Bypass -File tools/new-project.ps1 -Name <n> -Video raw/<file> -Transcribe → 數秒內取得 Deepgram 轉錄稿。
2. 匯出 transcript-words.txt（index:text@start）→ 閱讀、摘要、挑選重點時刻。
3. 字幕：captions-src.json（按字詞索引的羅馬化 Hinglish 區塊）→ node tools/build-captions.mjs projects/<n>。
4. 樣式範本：複製 kit/templates/paper-cut-vertical.html → index.html；設定兩個 data-duration；將 EXAMPLE 呼叫替換為此影片的重點時刻。
5. lint → snapshot --at ...（2 批約 12 幀）→ 檢視聯絡表 → 修正。
6. 音效：根據 mg-sound 中的偏移表編寫 sfx.json → node tools/sfx.mjs projects/<n>（在渲染之前執行，以便一次渲染包含音效）。
7. 事先告知用戶渲染時間（請參閱 mg-export：在 4 核筆電上，1080x1920 影片每分鐘約需 25–30 分鐘），然後渲染一次，複製到 exports/。
8. 後續調整：僅音訊 → sfx.mjs --mix（以秒為單位，無需重新渲染）。視覺調整 → 先做快照，然後重新渲染一次。

不要：安裝本地語音模型、恢復已停止的下載、為了『檢查』而渲染（使用快照），或在 VS Code 的播放器中預覽（無 AAC 音訊 — 請使用 VLC）。

1. 設定專案

1. 如果影片不在 raw/ 中，它可以留在原處。從檔名中選取一個簡短的 kebab-case 專案名稱。
2. 從工作區根目錄執行：

   powershell -NoProfile -ExecutionPolicy Bypass -File tools/new-project.ps1 -Name "<name>" -Video "<path>" -Transcribe
   

   • 轉錄使用 Deepgram（nova-3，預設 language=multi：處理烏爾都語/印地語 + 英語代碼切換；印地語/烏爾都語單詞可能以天城文返回 — 請羅馬化為 Hinglish，保留時間戳）。需要用戶的環境變數 DEEPGRAM_API_KEY；如果缺少，請要求用戶自行執行 powershell -NoProfile -ExecutionPolicy Bypass -File tools/set-deepgram-key.ps1（切勿在聊天中執行）。純英語影片：使用 -Language en。單獨重新執行：powershell -NoProfile -ExecutionPolicy Bypass -File tools/transcribe-deepgram.ps1 -Project projects/<name>。
   • 不要使用 npx hyperframes transcribe 搭配 whisper 或安裝它（太慢/太吵）；請使用 Deepgram。
   • 產生 projects/<name>/ 目錄，包含 clip.mp4（CFR H.264）、audio.mp3、metadata.json、transcript.json、fonts/、sfx/、renders/。
   • 如果用戶為某個時刻提供了螢幕截圖，請加上 -Screenshots "<folder>"。
3. 從這裡開始在 projects/<name>/ 目錄內工作（在執行任何 npx hyperframes 指令之前，先 cd 到該目錄）。

2. 仔細分析影片

• 讀取 metadata.json（寬度、高度、fps = r_frame_rate、時長）和 transcript.json（扁平化 [{text,start,end}]）。
• 就地修正明顯的 ASR 錯誤，保留時間戳。語音轉文字可能有大約 1 秒的誤差：當某個時刻很重要時，請使用 ffmpeg -ss <t-0.5> -t 2 -i clip.mp4 ... 或快照來驗證，而不是完全相信數值。
• 長篇或混合語言的轉錄稿：將索引化的詞彙清單（index:text@start，每行一個句子）匯出到 transcript-words.txt 並閱讀。

字幕（當用戶需要時）

• 編寫 captions-src.json：[[firstWordIndex, lastWordIndex, "caption text", ["key","words"]], ...]，每個區塊 3–7 個詞，涵蓋每個詞。 烏爾都語/印地語/Hinglish 語音 → 使用羅馬化 Hinglish 編寫文字（例如 "ke 9 maah guzar gaye hain"），保留原樣說的英語單詞，根據上下文修正誤聽（"नौ मां" → 9 maah，"New York" → New Year）。
• 建置：node tools/build-captions.mjs projects/<name> → captions.js（window.CAPTIONS = [{s,e,text,key}]），會警告未涵蓋的詞。使用 <script src="captions.js"> 載入。
• 找出人臉位置：在合成存在之前無法使用 npx hyperframes snapshot，因此請提取影格： ffmpeg -nostdin -v error -ss <t> -i clip.mp4 -frames:v 1 renders/_probe_<t>.png 在 3–4 個時間點提取並檢視。
• 撰寫一段摘要：影片內容是什麼，以及 3–8 個重要的時刻（數字、清單、前後對比、關鍵主張、CTA）。
• 如果用戶尚未指定，詢問他們想要的風格（請參閱 mg-styles）。預設：乾淨的白色磨砂卡片（Liquid Glass）。

3. 規劃（如果影片長度 > 30 秒或需求不明確，請在開始建置前向用戶展示）

針對每個時刻：觸發詞及其確切的 start、圖形類型、內容、區域、結束時間。圖形類型應與語音內容相符：

• 數字 → 計數 · 清單 → 核對清單勾選 · 前/後對比 → 比較 · 關鍵台詞 → 放大或大字型
• 螢幕截圖 / 證明 → 依序彈出（提示 12） · 新主題 → 重新構圖（影片縮小為卡片） 動作詞彙和樣式存在 mg-styles 技能中。

4. 家規（不可協商）

1. 完全保持影片原樣：相同的尺寸、fps、音訊、剪輯。合成的 data-width/height = 影片尺寸，fps = 影片 fps， 根元素 data-duration = 影片時長（限制在 metadata.json 的值）。影片是 <video id="a-roll" class="clip" src="clip.mp4" data-has-audio="true" data-start="0" ...>，沒有 muted，沒有 crossorigin。
2. 每個圖形從確切的單詞開始（轉錄稿中該單詞的 start）。
3. 整個影片使用一種風格。
4. 前 3 秒不要有任何內容 — 那是鉤子。
5. 讓圖形避開人臉，避開下方三分之一區域（字幕用），並保持在寬度中間 80% 的範圍內（左右各留 10% 邊距）。
6. 字型僅使用專案 fonts/ 資料夾中的字型，透過 @font-face 宣告（絕不使用 Google Fonts URL）；GSAP 透過 <script src="vendor/gsap.min.js"> 載入。
7. 磨砂玻璃效果需要有背景襯底；在畫面上方使用時可行，若要透明匯出則應使用實心卡片。

5. 建置、檢查、審閱

1. 編寫 index.html（獨立合成，一個暫停的 GSAP 時間軸，註冊為 window.__timelines["<id>"]）。Paper Cut 風格：從 kit/templates/paper-cut-vertical.html 開始。 低解析度手機影片（例如 480x864 WhatsApp）：仍在 1080x1920 畫布上創作，以保持圖形/字幕的銳利度；影片會在下方放大。
2. npx hyperframes lint 然後 npx hyperframes check — 修正所有錯誤。
3. npx hyperframes snapshot --at <t1>,<t2>,... 在每個圖形的中點進行快照，並檢視 PNG 圖片 — 檢查人臉/字幕重疊以及文字裁剪。
4. 渲染草稿：npx hyperframes render . -o renders/with-cards.mp4（在一般 PC 上渲染很慢；使用快照進行迭代，只有當影格看起來正確時才渲染）。
5. 將最終批准的檔案複製到 exports/<name>.mp4。

6. 後續處理（同一個工作階段）

• 單一位置（提示 12）：『當我說 <片語> 時，顯示 <東西>』。在轉錄稿中找到該片語，僅更改該時刻，保持其他所有內容完全相同，然後重新渲染到同一個檔案。
• 音效：使用 mg-sound 技能。匯出變體 / 透明背景：使用 mg-export 技能。
• 以簡單文字進行調整（表面、顏色、字型、動作、時間、版面） → 僅編輯該項目，保持其他所有內容相同，再次渲染。

先做基礎，然後一次處理一個位置。不要試圖在一次通過中完成所有事情。