synctake

SyncTake – Skill für KI-Coding-Agenten

Dieser Skill weist Coding-Agenten (Claude Code, Cursor, Antigravity, OpenCode, Codex) an, wie sie eigenständig professionelle, vertonte Video-Walkthroughs von Webanwendungen erstellen.

---

🎯 Wann dieser Skill aktiviert werden sollte

Aktivieren Sie diesen Workflow, wenn der Benutzer Folgendes anfordert:

• „Erstelle ein Demo-Video / einen Walkthrough dieses Projekts / Features“
• „Nimm ein Video auf, das zeigt, wie die App funktioniert“
• „Erstelle einen 30s/60s Walkthrough-Video dieser neuen UI“
• „Präsentiere dieses Feature in einem Video mit Vertonung“

---

🛠️ Schritt 0: Umgebungs- und Abhängigkeitsprüfung

Prüfen Sie vor der Ausführung des Workflows, ob die erforderlichen Werkzeuge installiert sind:

1. SyncTake CLI überprüfen:

   synctake --help || pip install -e /pfad/zu/synctake
   

2. Playwright überprüfen (für autonome headless Aufnahme):

   python -c "import playwright" 2>/dev/null || (pip install playwright && playwright install chromium)
   

---

📋 Der 5-Schritte-Autonomie-Playbook für Agenten

[1. UI inspizieren] ──> [2. synctake.json erstellen] ──> [3. Dev-Server starten] ──> [4. Autonome Pipeline ausführen] ──> [5. Video ausliefern]

Schritt 1: Codebasis und UI-Orientierungspunkte inspizieren

1. Durchsuchen Sie den Workspace nach Routen, Komponenten und HTML-Ansichten (z. B. src/, pages/, app/, public/index.html).
2. Identifizieren Sie die wichtigsten visuellen Orientierungspunkte für das Video:
   • Header, Navigation, Hero-Bereich (#hero, header, .brand)
   • Interaktive Komponenten, Formulare, Buttons (#deploy-btn, button[type='submit'], select)
   • Karten, Metriken, Grafiken ([data-testid='metrics'], .card, .recommendation-grid)
3. Alternativ führen Sie den integrierten UI-Inspektor aus:

   synctake plan ./public/index.html --prompt "<Benutzeranleitung>" --duration <Sekunden>
   

---

Schritt 2: Walkthrough-Spezifikation erstellen (synctake.json)

Erstellen Sie synctake.json im Projektstammverzeichnis.

Regeln für Taktung und Skripterstellung:

• Wörter pro Minute: Ziel 140–150 WPM (~2,4 Wörter pro Sekunde). Eine 10-Sekunden-Szene sollte etwa 20–24 Wörter enthalten.
• Szenen-Zeitstempel (at): Müssen strikt aufsteigend sein.
• Bildschirmeinblendung: Halten Sie title und callout kurz und prägnant (sie erscheinen als native schwebende Karten).
• Fokus: Verwenden Sie echte, gültige CSS-Selektoren (#id, .class, [data-testid='...']).
• Erzählung: Schreiben Sie natürliche, gesprächige Sprache. Lesen Sie niemals rohe Codesymbole, Selektoren oder Zeitstempel laut vor.

{
  "title": "Feature-Walkthrough",
  "duration_seconds": 30.0,
  "voice": {
    "provider": "system"
  },
  "scenes": [
    {
      "id": "01-ueberblick",
      "at": 0.0,
      "title": "Live-Cluster-Übersicht",
      "callout": "Echtzeit-Gesundheits- und Telemetriemetriken über Regionen hinweg",
      "focus": "#metrics-card",
      "text": "Willkommen! In diesem Walkthrough erkunden wir die Echtzeit-Clustergesundheit und automatisierte Problemlösungen."
    },
    {
      "id": "02-aktionen",
      "at": 12.0,
      "title": „Bereitstellungen mit einem Klick“,
      "callout": "Automatisierte Validierung mit menschlicher Freigabe",
      "focus": "#deploy-btn",
      "text": "Mit einem einzigen Klick validiert unsere Pipeline Konfigurationsänderungen und führt rollierende Updates aus."
    }
  ]
}

---

Schritt 3: Sicherstellen, dass der Dev-Server läuft

Überprüfen Sie, ob der Dev-Server der Webanwendung bereits auf einem lokalen Port lauscht:

lsof -i :3000 -i :5173 -i :8000 || true

Wenn er nicht läuft, starten Sie ihn im Hintergrund:

• Für statisches HTML: python3 -m http.server 5173 --bind 127.0.0.1
• Für Vite: npm run dev
• Für Next.js: npm run dev

---

Schritt 4: Autonome Pipeline ausführen

Führen Sie den All-in-One-Autonomiebefehl aus:

synctake run \
  --url http://127.0.0.1:5173 \
  --config ./synctake.json \
  --out ./demo.mp4

Wenn der Benutzer eine Sprachreferenzdatei (z. B. voice.wav) bereitgestellt hat, übergeben Sie --ref-audio ./voice.wav, um dessen Stimme zu klonen.

Was synctake run automatisch macht:

1. Headless Bildschirmaufnahme: Startet Chromium über Playwright, durchläuft Szenen-Cues, hebt Elemente mit host-adaptiven Fokusringen hervor, zeigt native Callout-Badges und speichert kalibriertes WebM.
2. Sprachsynthese: Synthetisiert klare gesprochene Sprache (oder klont die Stimme des Benutzers).
3. Taktungs- und Slot-Validierung: Überprüft, dass kein Audio-Clip seine zugewiesene Szenendauer überschreitet.
4. Master-Canvas-Assemblierung: Platziert Clips an exakten Cues, füllt Pausen mit digitaler Stille und gibt kalibriertes 48-kHz-Stereo-Audio aus.
5. Verlustfreies Muxen: Normalisiert Audio auf Broadcast-Standard (-16 LUFS) und muxt es in 1080p H.264 MP4 ohne Generationsverlust.

---

Schritt 5: Das fertige Video ausliefern

Sobald synctake run abgeschlossen ist:

1. Überprüfen Sie, ob das Ausgabevideo existiert und nicht leer ist (ls -lh ./demo.mp4).
2. Präsentieren Sie dem Benutzer das fertige Video mit seinem absoluten Dateipfad-Link:

   „Hier ist Ihr fertiger Walkthrough: demo.mp4!“

---

🧪 Validierung & Fehlerbehebung

Problem	Mögliche Ursache	Lösung
Kein Video erzeugt	Dev-Server läuft nicht	Überprüfen Sie den Serverstatus in Schritt 3
Falsche UI-Elemente hervorgehoben	Ungültiger CSS-Selektor	Verwenden Sie data-testid oder IDs; testen Sie Selektoren im Browser
Audio-Stimme klingt roboterhaft	Standard-Systemstimme	Bitten Sie den Benutzer, eine voice.wav-Referenz für das Klonen bereitzustellen
Video ruckelt	Hohe CPU-Auslastung	Schließen Sie andere Browser/Apps; reduzieren Sie die Szenenanzahl

---

📝 Spezifikationsreferenz (synctake.json Schema)

Schlüssel	Typ	Erforderlich	Standard	Beschreibung
title	String	Ja	–	Titel des Videos
duration_seconds	Float	Ja	–	Gesamtdauer in Sekunden
voice.provider	String	Nein	"system"	Sprach-Engine
voice.ref_audio	String	Nein	null	Pfad zur Referenz-Audiodatei
scenes[]	Array	Ja	–	Liste der Szenen (Zeitstempel müssen steigen)
scenes[].at	Float	Ja	–	Startzeitpunkt der Szene in Sekunden
scenes[].title	String	Nein	–	Kurzer Titel für die Callout-Karte
scenes[].callout	String	Nein	–	Kurzer Text für die Callout-Karte
scenes[].focus	String	Ja	–	CSS-Selektor für das hervorgehobene Element
scenes[].text	String	Ja	–	Erzähltext (natürliche Sprache)