影片指南製作技能
將任何原始螢幕錄影轉換為精美、有旁白、動態註解的使用者指南影片 (.mp4 + .srt)。
核心規則 (務必遵守)
- 使用者無需編寫 JSON / 無需手動準備： 使用者僅需提供錄影路徑 (例如
C:\recordings\demo.mp4或影格資料夾) 以及選修的指南/流程備註。您 負責擷取影格、分析整段影片、撰寫食譜 JSON、驗證時間軸，並最終渲染。 - 在編輯前分析所有 3 FPS 影格： 舉例來說，一段 210 秒的錄影會產生 約 630 個影格 (3 fps)。透過 FFmpeg 擷取所有 3-fps 影格，掃描全部 630 個影格，檢查每個產生的 Storyboard 連環圖 (
storyboard_*.png)，並檢查全解析度的0NNN_frame.png影格 (或使用inspect_frame_slice) 之後，才開始撰寫任何食譜步驟。 - 語音、語調與編輯前計劃閘門： 在最終渲染之前，先執行
validate_recipe(--plan_only)，呈現您的編輯計劃 (步驟數、持續時間、停靠區域、旁白)，然後請使用者確認或選擇語音和語調，除非使用者明確指示「自動繼續」(或「直接渲染」)。 - 首次執行自動設定： 如果克隆後缺少
.venv，請執行一次python bootstrap.py(或直接執行tool_executor.py，它會自動進行引導設定)。
逐步代理工作流程
階段 1 — 擷取 3-FPS 影格並分析所有影格
執行 create_guide (透過 MCP 或 CLI tool_executor.py)：
# 透過 CLI / Codex / Cursor / Antigravity shell：
echo '{"tool":"create_guide","video_path":"<VIDEO_PATH>","user_flow_notes":"<OPTIONAL_NOTES>"}' | python tool_executor.py
這將自動：
- 透過內建 FFmpeg (
engine.py --extract_frames --fps_extracted 3) 以3 fps擷取影格 (0001_frame.png ... 0NNN_frame.png，例如 210 秒產生 630 個影格)。 - 使用全域差異和
8×6空間區塊偵測器掃描100% 的已擷取影格 (0 .. N-1) (因此永遠不會錯過下拉選單、按鈕點擊、核取方塊和模態視窗)。 - 輸出：
storyboard_01.png,storyboard_02.png, ... — 標記的連環圖，涵蓋整部影片，包含#frame、時間戳記、事件標籤 (PAGE_TRANSITION/UI_ACTION/IDLE_HOLD) 以及青色的變更區域方塊。analysis_3fps.json— 完整的時間軸區段 + 變更畫素的邊界方塊[x1, y1, x2, y2]+trim_candidate閒置停頓。recipe_draft.json— 起始的engine.py食譜架構。
階段 2 — 視覺檢查 Storyboard 與關鍵影格 (必要)
- 開啟並閱讀
storyboard_paths中列出的每個storyboard_*.png圖片。 - 從頭到尾追蹤使用者的完整操作流程：注意頁面載入、表單填寫、彈出視窗/模態、長時間的停頓 (
trim_candidate: true)，以及任何需要剪掉的誤點擊。 - 針對您計劃強調的步驟，開啟特定的全解析度
0NNN_frame.png圖片 (如果在狹窄的影格範圍內有快速動作，可呼叫inspect_frame_slice) 以便：- 讀取確切的 UI 按鈕/欄位/選單文字。
- 為
boxes、arrows、spotlight和zoom測量準確的[x1, y1, x2, y2]座標。
階段 3 — 撰寫最終的 recipe.json
儲存一個乾淨的 recipe.json，符合 schemas/recipe.schema.json (請參閱 examples/recipe_create_exam.json 中的實際範例)：
- 必要頂層欄位：
source_video,frames_dir,fps_extracted: 3.0,input_source: "auto",branding_text,preset(tech_hud|clean_light|minimal|high_contrast),tone(friendly|professional|energetic|calm|corporate),default_voice,dock_mode: "auto",total_duration: "auto",audio_timing_mode: "auto_shift",export_subtitles: true。- (切勿將
"theme"設為字串 — 請使用"preset"。)
- (切勿將
timeline_mapping：將編輯後的輸出區段乾淨地對應到 3-FPS 的原始影格 (start_sec,end_sec,source_frame_start_3fps,source_frame_end_3fps) — 跳過無聊的停頓，並加快重複的打字動作！steps：同步的條目 (id,start_time,active_start,active_end,step_num,step_title,narration,sub,boxes,arrows, 可選的spotlight/zoom)。- 避免將
boxes[].label放在密集的表格標題上，以免標籤遮蓋相鄰的欄位標題。 - 確保
narration能舒適地容納在每個步驟的[active_start, active_end]時間視窗內。
- 避免將
階段 4 — 驗證計劃並確認語音/語調
執行預飛航驗證 (合成 Edge-TTS 音訊片段，檢查 [AGENT:] 佔位符和重疊，並輸出動態停靠區域)：
python tool_executor.py --args '{"tool":"validate_recipe","recipe_path":"<PATH_TO_RECIPE_JSON>"}'
語音： en-IN-NeerjaNeural (印度女聲), en-IN-PrabhatNeural (印度男聲), en-US-JennyNeural (美國女聲), en-US-GuyNeural (美國男聲), en-GB-SoniaNeural (英國女聲), en-GB-RyanNeural (英國男聲)。
語調： friendly, professional, energetic, calm, corporate。
- 如果出現任何
[OVERLAP WARNING]或has_overlaps為 true，請擴展步驟時間視窗 / 修剪旁白並重新驗證，直到重疊數為 0。 - 除非使用者指示自動繼續，否則請分享簡短的編輯前計劃，並在渲染前確認語音和語調。
階段 5 — 渲染並視覺驗證輸出
python tool_executor.py --args '{"tool":"render_guide","recipe_path":"<PATH_TO_RECIPE_JSON>","output_path":"<OUTPUT_MP4>","export_srt":true}'
透過 FFmpeg 快照檢查 2–3 個渲染影格，確認方塊、箭頭、品牌標籤和 HUD 停靠區域不會與 UI 文字衝突，然後提供 .mp4 和 .srt 檔案的路徑。