mohamed-stifi/explainer-short

Explainer Short (Idee → fertiges Video)

Du erstellst EXAKT EIN fertiges Video pro Anfrage, indem du die 7 Schritte unten der Reihe nach, einmal durchführst. Jeder Schritt hat einen Befehl, eine Ausgabe und eine Stopp-Bedingung. Erfinde keine zusätzlichen Schritte.

Pfade: SKILL = der Ordner, der diese Datei enthält. STUDIO = der Video-Arbeitsbereich (Standard: ./explainer-studio im aktuellen Projekt; verwende ihn erneut, wenn er existiert). SLUG = Kebab-Case-ID des Videos, z. B. how-https-works.

Harte Grenzen (hält den Durchlauf kurz und günstig)

• Frage den Benutzer höchstens eine Frage, und nur, wenn es gar kein Thema gibt. Ansonsten entscheide selbst (Länge, Format, Brand) mit den unten stehenden Standardwerten und gib deine Entscheidungen in der finalen Antwort an.
• check.sh → beheben → check.sh maximal 2 Fix-Runden. Dann rendern und alle verbleibenden Probleme in der Antwort aufführen.
• Stimme maximal 2 Mal neu generieren (nur wegen Länge oder einem falsch ausgesprochenen Wort).
• Bearbeite src/kit/ nicht (außer um ein Icon hinzuzufügen). Installiere keine anderen Pakete oder Tools.
• Lese template/src/videos/example/ einmal (es ist die Referenzimplementierung). Lese den Kit-Quellcode nicht; references/kit-api.md dokumentiert ihn.

"Short", "Reel", "Explainer Short" = das vertikale FORMAT, nicht der Längenmodus. Verwende den Längenmodus "short" nur, wenn der Benutzer nach einem schnellen/sehr kurzen/unter 1 Minute Video fragt oder Sekunden angibt.

Standards: Länge 95–120 s (300–370 Wörter; "short" = 55–70 s, "full" = die Referenzlänge 160–175 s — siehe references/script-guide.md), Stimme am_michael Geschwindigkeit 1,18, Brand = Name/Kanal des Benutzers falls bekannt, sonst "YourBrand". Die Stilregeln stammen aus der Vermessung von 23 Referenzvideos; die Belege sind in references/style-evidence/ (nur Menschen — du musst sie nicht lesen).

Schritt 1 — Setup (einmal pro Maschine, ~3 min beim ersten Mal, ~2 s danach)

bash SKILL/scripts/setup.sh STUDIO

Stopp-Bedingung: letzte Zeile READY: …. Falls MISSING TOOLS ausgegeben wird, sag dem Benutzer genau, was zu installieren ist, und stoppe. (Setze zuerst KOKORO_MODELS=<verzeichnis>, falls die Sprachmodell-Dateien bereits irgendwo existieren, um einen 340 MB Download zu überspringen.)

Schritt 2 — Planen (noch kein Code)

Lese references/script-guide.md. Schreibe dann STUDIO/src/videos/SLUG/plan.md (≤ 25 Zeilen, nachdem Schritt 3 den Ordner erstellt hat):

1. Titel in einem der Formate (Wie X funktioniert · X vs Y · Interview: … · Systemdesign: wie X macht).
2. Laufendes Beispiel: eine benannte Person + ein konkretes Produkt/Input/Wert, das von Anfang bis Ende verwendet wird.
3. Beats (Abschnitte) mit IDs, 6–9 Stück, jeder = eine Idee.
4. Stages: Lese references/visual-guide.md, schreibe dann eine Zeile pro Abschnitt: Abschnitt → hinzugefügt / bewegt / fokussiert (Spotlight-IDs) / verlässt (siehe "Planning stages" dort). Wähle 3–4 Akzente und binde jeden an eine Sache.

Schritt 3 — Skript

bash SKILL/scripts/new_video.sh STUDIO SLUG

Schreibe STUDIO/src/videos/SLUG/script.json (Format: siehe die script.json des Beispiels). Regeln, die Probleme verursachen:

• sections[].id eindeutig, einfach (hook, scenario, mechanism, …). Letzter Abschnitt ist der CTA.
• Schreibe Zahlen/Symbole so, wie du sie zeigen möchtest, und ordne sie dem zu, wie sie gesagt werden in pronounce ("429": "four twenty nine", "API": "A P I", "SQL": "sequel", "k8s": "kubernetes").
• Sätze ≤ 18 Wörter. Nur . ! ? beenden Sätze (jeder Satz wird separat synthetisiert). Selbstprüfung anhand der Regelliste am Ende von script-guide.md, bevor du fortfährst.

Schritt 4 — Stimme

bash SKILL/scripts/voice.sh STUDIO SLUG

Gibt Start/Ende jedes Abschnitts aus und Done: <sek>s, <wörter> Wörter, <wpm> wpm. Stopp-Bedingung: Dauer innerhalb des Ziels ±15 %. Zu lang → Sätze kürzen (nicht die Geschwindigkeit) und noch einmal ausführen.

Schritt 5 — Visuals

Lese references/kit-api.md und das Beispiel (STUDIO/src/videos/example/Video.tsx + stages/*.tsx). Schreibe STUDIO/src/videos/SLUG/Video.tsx + eine Datei pro Stage in stages/. Nicht verhandelbar:

• Jedes Element hat at von cue(section, word) oder sec(section).from – niemals fest codierte Sekunden.
• Ein durchgehender Canvas: Dinge bleiben bestehen, bewegen sich, werden abgedunkelt und wiederverwendet. Keine Vollbild-Löschungen außer zwischen Stages.
• Mindestens alle ~3 s Erzählung ändert sich etwas sichtbar (neues Element, Hervorhebung, Zustandsänderung, Bewegung).
• Fokus = Spotlight-Plan auf <Canvas focus> (den Rest abdunkeln) – das Hauptmittel des Stils.
• Keine Untertitel. Bildunterschriften (Takeaway) ≤ 7 Wörter, 2–6 pro Video.
• Inhalt in der sicheren Zone halten (x 60–1020, y 280–1480; Titel ≈150; Bildunterschrift direkt unter dem Diagramm).
• Breite ausfüllen: Hauptpanels w 960 (oder 2 × 465). Nichts kleiner als 26 px.

Schritt 6 — Check (maximal 2 Fix-Runden)

check.sh und render.sh starten einen lokalen Server + Headless Chrome. Führe in einem gesandboxten Agenten beide Befehle außerhalb des Sandbox aus. Falls deine Umgebung das gar nicht kann (No available ports found, Chrome startet nicht, unsandboxed-Aufrufe verweigert): stoppe nach Schritt 5 und sage dem Benutzer, er solle check.sh und dann render.sh selbst ausführen (gib beide vollständigen Befehle an). Versuche keine Workarounds.

bash SKILL/scripts/check.sh STUDIO SLUG          # optionales 3. Argument: "12.5,30,41" = zusätzliche Sekunden zum Prüfen

Es lintet jedes cue() gegen das Voice-Timing (sofort), typecheckt, rendert ~3 Frames pro Abschnitt + Endkarte und schreibt out/SLUG/check/sheet.jpg (+ NN.jpg Einzelframes). Sieh dir das Sheet-Bild an (und 2–3 Einzelframes in voller Größe). Behebe nur, was fehlschlägt:

Prüfung	Fehlschlag bei
Überlappung	Text/Boxen kollidieren oder werden vom Bildschirmrand abgeschnitten
Skalierung	Das Diagramm nutzt < 80 % der Breite oder lässt y 900–1400 in einem belebten Abschnitt leer; Text, den du in einem 540 px breiten Frame zusammenkneifen musst
Lesbarkeit	Jedes Label kleiner als ~28 px, oder Text über einem belebten Bereich
Synchronisation	Ein Element erscheint vor seinem Wort, oder ein Frame zeigt einen leeren/veralteten Canvas, während die Erzählung über etwas anderes spricht
Kontinuität	Eine Stage sieht ohne Bezug zur vorherigen aus (alles ersetzt), obwohl die Geschichte weitergeht
Fokus	Das besprochene Ding ist nicht hervorgehoben (Focus / Amber / andere abdunkeln)
Dichte	Ein Frame mit > 9 sichtbaren Elementen, oder > 2 Zeilen Takeaway-Text

Typfehler / cue not found-Fehler geben den Fix aus (die Liste der gültigen Wörter). Beheben und erneut ausführen.

Schritt 7 — Rendern + liefern

bash SKILL/scripts/render.sh STUDIO SLUG

(Falls Headless Chrome durch einen Sandbox blockiert ist, führe diesen Befehl außerhalb des Sandbox erneut aus.) Schreibe dann STUDIO/out/SLUG/upload.md: Titel (= der Videotitel, ≤ 60 Zeichen, 1 Emoji am Ende erlaubt), 2-Satz-Beschreibung, 5 Hashtags und eine "Zu überprüfende Fakten"-Liste (jede Zahl/Behauptung, die du aus dem Gedächtnis genannt hast).

Finale Antwort (kurz): Der MP4-Pfad, die Dauer, die SRT/Cover/upload.md-Pfade, die von dir getroffenen Entscheidungen (Format, Länge, laufendes Beispiel) und alle verbleibenden bekannten Probleme. Dann stoppen.

Fehlerbehebung

Symptom	Lösung
cue not found: "x" #1 in section "y". Words: …	Verwende ein Wort aus der gedruckten Liste, oder den richtigen Abschnitt
ein Wort wird falsch ausgesprochen	Füge es zu pronounce hinzu und führe Schritt 4 erneut aus
Cannot find module './timing.json'	Schritt 4 für diesen SLUG nicht ausgeführt
Komposition SLUG nicht gefunden	Führe voice.sh aus (es registriert das Video)
Chrome / SIGABRT / ENOTFOUND remotion.media / No available ports found	Sandbox blockiert Browser/Port: Führe den Befehl unsandboxed aus (siehe Schritt 6)
failed to canonicalize path …/voice/.venv/bin/python3 oder andere uv/venv-Fehler	Lösche STUDIO/voice/.venv und führe setup.sh erneut aus
ein Frame zeigt Text, der aus einem Panel überläuft	Gib dem <El> eine größere h, weniger Zeilen oder eine kleinere Schrift (≥ 26 px)
Video zu lang/kurz	Bearbeite das Skript (≈3.1 Wörter pro Sekunde bei Geschwindigkeit 1.18), führe Schritt 4 erneut aus