Bikash-Meher/antigravity

Skill zur Erstellung von Video-Anleitungen

Wandeln Sie jede rohe Bildschirmaufnahme in eine polierte, kommentierte und dynamisch annotierte Video-Benutzeranleitung (.mp4 + .srt) um.

Kernregeln (immer befolgen)

1. Null JSON / Null manuelle Vorbereitung durch den Benutzer: Der Benutzer stellt nur einen Aufnahmepfad (z.B. C:\recordings\demo.mp4 oder einen Frames-Ordner) und optionale Anmerkungen zum Ablauf bereit. Sie extrahieren Frames, analysieren das gesamte Video, schreiben das Rezept-JSON, validieren das Timing und rendern.
2. Alle 3-FPS-Frames VOR der Bearbeitung analysieren: Beispielsweise liefert eine 210-Sekunden-Aufnahme ~630 Frames @ 3 fps. Extrahieren Sie jeden 3-fps-Frame via FFmpeg, scannen Sie alle 630 Frames, untersuchen Sie jedes generierte Storyboard-Kontaktblatt (storyboard_*.png) und die hochauflösenden 0NNN_frame.png-Frames (oder verwenden Sie inspect_frame_slice), bevor Sie Rezeptschritte erstellen.
3. Sprache, Ton & Vor-Bearbeitungs-Plan-Schleuse: Führen Sie vor dem endgültigen Rendern validate_recipe (--plan_only) aus, präsentieren Sie Ihren Bearbeitungsplan (Schrittzahl, Dauer, Dock-Zonen, Kommentare) und bitten Sie 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 Start: Wenn .venv nach dem Klonen fehlt, führen Sie einmal python bootstrap.py aus (oder führen Sie tool_executor.py direkt aus, das automatisch bootet).

---

Schritt-für-Schritt Agenten-Workflow

Phase 1 – 3-FPS-Frames extrahieren & alle Frames analysieren

Führen Sie 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 automatisch:

1. Extrahiert 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. Scannt 100% der extrahierten Frames (0 .. N-1) mittels globalem Diff und einem 8×6 räumlichen Blockdetektor (damit Dropdowns, Button-Klicks, Checkboxen und Modals niemals übersehen werden).
3. Erzeugt:
   • storyboard_01.png, storyboard_02.png, … – beschriftete Kontaktblätter, die das gesamte Video mit #frame, Zeitstempel, Ereignis-Tag (PAGE_TRANSITION / UI_ACTION / IDLE_HOLD) und cyanfarbenen geänderten Bereichsboxen abdecken.
   • analysis_3fps.json – vollständige Timeline-Segmente + Begrenzungsrahmen geänderter Pixel [x1, y1, x2, y2] + trim_candidate Leerlauf-Holds.
   • recipe_draft.json – Start-Rezept-Schema für engine.py.

---

Phase 2 – Storyboards & Schlüsselframes visuell inspizieren (Pflicht)

1. Öffnen und lesen Sie jedes storyboard_*.png-Bild, das in storyboard_paths aufgeführt ist.
2. Verfolgen Sie die gesamte Reise des Benutzers von Anfang bis Ende: Notieren Sie Seitenladevorgänge, Formularausfüllungen, Popups/Modals, lange tote Pausen (trim_candidate: true) und Fehlklicks, die herausgeschnitten werden sollen.
3. Öffnen Sie spezifische hochauflösende 0NNN_frame.png-Bilder aus dem frames_dir für die Schritte, die Sie hervorheben möchten (und rufen Sie 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.

---

Phase 3 – Finales recipe.json erstellen

Speichern Sie 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.
  • (Setzen Sie "theme" niemals auf einen String – verwenden Sie stattdessen "preset".)
• timeline_mapping: Ordnen Sie bearbeitete Ausgabesegmente sauber den 3-FPS-Quellframes zu (start_sec, end_sec, source_frame_start_3fps, source_frame_end_3fps) – überspringen Sie langweilige Pausen und beschleunigen Sie sich wiederholende Tipper!
• steps: Synchronisierte Einträge (id, start_time, active_start, active_end, step_num, step_title, narration, sub, boxes, arrows, optional spotlight / zoom).
  • Vermeiden Sie boxes[].label auf dichten Tabellenüberschriften, wo eine Markierung benachbarte Spaltenbeschriftungen überdecken könnte.
  • Stellen Sie sicher, dass narration bequem in das [active_start, active_end]-Fenster jedes Schritts passt.

---

Phase 4 – Plan validieren & Sprache/Ton bestätigen

Führen Sie die Pre-Flight-Validierung durch (synthetisiert Edge-TTS-Clips, prüft [AGENT:]-Platzhalter und Überlappungen, gibt dynamische Dock-Zonen aus):

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

Stimmen: en-IN-NeerjaNeural (IN Female), en-IN-PrabhatNeural (IN Male), en-US-JennyNeural (US Female), en-US-GuyNeural (US Male), en-GB-SoniaNeural (UK Female), en-GB-RyanNeural (UK Male).
Töne: friendly, professional, energetic, calm, corporate.

• Wenn eine [OVERLAP WARNING] erscheint oder has_overlaps true ist, erweitern Sie Schrittfenster / kürzen Sie die Erzählung und validieren Sie erneut, bis 0 Überlappungen vorhanden sind.
• Teilen Sie, sofern der Benutzer nicht "auto proceed" angeordnet hat, den kurzen Pre-Edit-Plan mit und bestätigen Sie Sprache & Ton vor dem Rendern.

---

Phase 5 – Rendern & Ausgabe visuell prüfen

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

Überprüfen Sie 2–3 gerenderte Frames via FFmpeg-Schnappschussprüfung, um sicherzustellen, dass Boxen, Pfeile, Branding-Pill und HUD-Dock niemals mit UI-Text kollidieren, und übergeben Sie dann die .mp4- und .srt-Pfade.