Bikash-Meher/video-guide-skill

Video Guide Maker Skill

Verwandle jede rohe Bildschirmaufnahme in ein poliertes, kommentiertes, dynamisch annotiertes Benutzerhandbuch-Video (.mp4 + .srt).

Kernregeln (Immer beachten)

1. Kein JSON / Keine manuelle Vorbereitung durch den Benutzer: Der Benutzer gibt nur den Pfad zur Aufnahme an (z.B. C:\recordings\demo.mp4 oder einen Frames-Ordner) und optionale Notizen zum Ablauf/Workflow. Du extrahierst Frames, analysierst das gesamte Video, schreibst das Rezept-JSON, validierst das Timing und renderst.
2. Analysiere ALLE 3-FPS-Frames vor der Bearbeitung: Für eine 210s Aufnahme erhältst du z.B. ~630 Frames @ 3 fps. Extrahiere jeden 3-fps-Frame via FFmpeg, scanne alle 630 Frames, überprüfe jedes generierte Storyboard-Kontaktblatt (storyboard_*.png) und inspiziere Full-Resolution 0NNN_frame.png Frames (oder verwende inspect_frame_slice), bevor du Rezept-Schritte schreibst.
3. Gate für Sprache, Ton und Vorab-Bearbeitungsplan: Vor dem finalen Rendern führe validate_recipe (--plan_only) aus, präsentiere deinen Bearbeitungsplan (Schrittanzahl, Dauer, Dock-Zonen, Erzählungen) und bitte den Benutzer um Bestätigung oder Auswahl von Sprache & Ton — es sei denn, der Benutzer hat explizit "auto proceed" (oder "just render") angeordnet.
4. Auto-Setup beim ersten Durchlauf: Wenn .venv nach dem Klonen fehlt, führe einmal python bootstrap.py aus (oder führe tool_executor.py direkt aus, was automatisch bootet).

---

Schritt-für-Schritt-Agenten-Workflow

Stufe 1 — 3-FPS-Frames extrahieren & alle Frames analysieren

Führe create_guide aus (via MCP oder CLI tool_executor.py):

# Via CLI / Codex / Cursor / Antigravity shell:
echo '{"tool":"create_guide","video_path":"<VIDEO_PATH>","user_flow_notes":"<OPTIONAL_NOTES>"}' | python tool_executor.py

Dies automatisiert:

1. Extrahiere 3 fps Frames (0001_frame.png ... 0NNN_frame.png, z.B. 630 Frames für 210s) via gebündeltem FFmpeg (engine.py --extract_frames --fps_extracted 3).
2. Scanne 100% der extrahierten Frames (0 .. N-1) mit sowohl globalem Diff als auch einem 8×6 räumlichen Blockdetektor (damit Dropdowns, Button-Klicks, Checkboxen und Modals nie übersehen werden).
3. Erzeuge:
   • storyboard_01.png, storyboard_02.png, ... — beschriftete Kontaktblätter, die das gesamte Video mit #frame, Timestamp, Ereignis-Tag (PAGE_TRANSITION / UI_ACTION / IDLE_HOLD) und cyanen geänderten Regionsboxen abdecken.
   • analysis_3fps.json — vollständige Timeline-Segmente + geänderte Pixel-Bounding-Boxes [x1, y1, x2, y2] + trim_candidate Leerlauf-Holds.
   • recipe_draft.json — Starter engine.py Rezept-Schema.

---

Stufe 2 — Storyboards & Schlüsselframes visuell inspizieren (Pflicht)

1. Öffne und lies jedes in storyboard_paths aufgeführte storyboard_*.png-Bild.
2. Verfolge den gesamten Weg des Benutzers von Anfang bis Ende: Notiere Seitenladevorgänge, Formularausfüllungen, Popups/Modals, lange tote Pausen (trim_candidate: true) und Fehlklicks zum Herausschneiden.
3. Öffne spezifische Full-Resolution 0NNN_frame.png-Bilder aus frames_dir für die Schritte, die du hervorheben möchtest (und rufe inspect_frame_slice auf, wenn eine Aktion schnell in einem engen Frame-Bereich stattfindet), um:
   • Exakten UI-Button/Feld/Menü-Text zu lesen.
   • Genaue [x1, y1, x2, y2]-Koordinaten für boxes, arrows, spotlight und zoom zu messen.

---

Stufe 3 — Finales recipe.json schreiben

Speichere ein sauberes recipe.json gemäß schemas/recipe.schema.json (siehe echte Beispiele in examples/recipe_create_exam.json):

• Erforderliche Top-Level-Felder: 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.
  • (Setze "theme" nie auf einen String — verwende stattdessen "preset".)
• timeline_mapping: Ordne bearbeitete Ausgabesegmente sauber den 3-FPS-Quellframes zu (start_sec, end_sec, source_frame_start_3fps, source_frame_end_3fps) — überspringe langweilige Pausen und beschleunige sich wiederholendes Tippen!
• steps: Synchronisierte Einträge (id, start_time, active_start, active_end, step_num, step_title, narration, sub, boxes, arrows, optional spotlight / zoom).
  • Halte boxes[].label von dichten Tabellenköpfen fern, wo ein Pill benachbarte Spaltenbeschriftungen überdecken könnte.
  • Stelle sicher, dass narration bequem in das jeweilige Fenster [active_start, active_end] jedes Schrittes passt.

---

Stufe 4 — Plan validieren & Sprache/Ton bestätigen

Führe den Pre-Flight-Check durch (synthetisiert Edge-TTS-Clips, prüft auf [AGENT:] Platzhalter und Überlappungen, gibt dynamische Dock-Zonen aus):

python tool_executor.py --args '{"tool":"validate_recipe","recipe_path":"<PATH_TO_RECIPE_JSON>"}'

Sprachen: en-IN-NeerjaNeural (IN Weiblich), en-IN-PrabhatNeural (IN Männlich), en-US-JennyNeural (US Weiblich), en-US-GuyNeural (US Männlich), en-GB-SoniaNeural (UK Weiblich), en-GB-RyanNeural (UK Männlich).
Töne: friendly, professional, energetic, calm, corporate.

• Wenn eine [ÜBERLAPPUNGSWARNUNG] erscheint oder has_overlaps wahr ist, erweitere die Schrittfenster / kürze die Erzählung und validiere erneut, bis 0 Überlappungen vorhanden sind.
• Sofern der Benutzer nicht den Auto-Vorgang angeordnet hat, teile den kurzen Vorab-Bearbeitungsplan und bestätige Sprache & Ton vor dem Rendern.

---

Stufe 5 — Rendern & Ausgabe visuell verifizieren

python tool_executor.py --args '{"tool":"render_guide","recipe_path":"<PATH_TO_RECIPE_JSON>","output_path":"<OUTPUT_MP4>","export_srt":true}'

Überprüfe 2–3 gerenderte Frames via FFmpeg-Snapshot-Check, um sicherzustellen, dass Boxen, Pfeile, Branding-Pill und HUD-Dock niemals mit UI-Text kollidieren, und liefere dann die Pfade zur .mp4 und .srt aus.