lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

mkt-hyperframe-talking-head-video-16-9

Dedizierter 16:9 (1920×1080) Landschaftseditor — Eingabe ist ein vorhandener Arbeitsordner mit voiceover.mp3 + source.mp4 + script.txt, Ausgabe ist derselbe Ordner, der vollständig als HyperFrames-Vorschauprojekt (npx hyperframes preview) eingerichtet ist.

Dies ist eine operative Ebene unter dem Orchestrator mkt-full-video-with-11-hyperframe-heygen-16-9. Der Orchestrator übernimmt Phase 1 (TTS) + Phase 2 (HeyGen-Avatar) → übergibt den Ordner an dieses Skill für Phase 3 (Transkribieren + Einrichten + Linting + Vorschau).

---

Was dieses Skill produziert

<workspace_folder>/
├── voiceover.mp3                 # Eingabe (unverändert)
├── source.mp4                    # Eingabe (HeyGen-Avatar-Lip-Sync, unverändert)
├── script.txt                    # Eingabe (unverändert)
├── transcript.json               # generiert — Whisper-Ausgabe auf Wortebene
├── transcript-cleaned.json       # generiert — bereinigt von vietnamesischen Tippfehlern
├── scenes-outline.json           # generiert — Vorschaugliederung (5 Szenen)
├── scenes.json                   # generiert — endgültige Metadaten pro Szene
├── index.html                    # generiert — Hauptkomposition 1920×1080
├── compositions/
│   ├── scene-1.html              # 1 Datei pro Szene, unabhängig von der Anzahl N
│   ├── scene-2.html              # erstellt von parallelen LLM-Sub-Agenten (Phase 3d)
│   ├── scene-3.html              # NICHT von Python-Vorlagen generiert (veraltet)
│   ├── ...
│   └── scene-N.html
├── sfx/                          # 6 SFX als Symlink/Kopie aus Skill-Assets
│   ├── camera-flash.mp3
│   ├── Whoosh sound effect (1).mp3
│   ├── búng tay.mp3
│   ├── Laser.mp3
│   ├── ting.mp3
│   └── Discord Notification - Sound Effect.mp3
└── (optional) infographics/
    ├── 1.png  2.png  3.png       # falls --with-infographics
    └── prompts.md                # Redaktionelle Aufforderungen im Cream-Paper-Stil pro Szene

Leinwand:

• Root: data-width="1920" data-height="1080".
• Avatar-Rahmen Standard SPLIT: top:100, left:1290, width:540, height:880, borderRadius:32.
• Avatar-Rahmen PIP-Ecke: top:600, left:1540, width:320, height:420, borderRadius:20.
• Folienhalterung: 1200×1080 SPLIT, animierbar auf 1920×1080 während PIP.
• Eigene Größe jeder Komposition: data-width="1200" data-height="1080" (füllt 100% der Halterung, dehnt sich aus, wenn die Halterung breiter wird).

---

Benötigte Eingaben (Arbeitsordner-Konvention)

Datei	Erforderlich	Hinweis
voiceover.mp3	Ja	ElevenLabs TTS-Ausgabe (Hoàngs Stimme).
source.mp4	Ja	HeyGen-Avatar-Lip-Sync. Derzeit 9:16 Hochformat — der Landschaftsrahmen verwendet object-fit: cover; object-position: center 25%, um es vernünftig zuzuschneiden. Siehe references/source-mp4-cropping.md.
script.txt	Ja	Vietnamesisches Skript, das voiceover.mp3 erzeugt hat. Wird für die Rechtschreibkorrektur und die Ableitung von Szenenüberschriften verwendet.
scenes-outline.json	Nein	Wenn der Benutzer 5 Szenen vordefiniert hat, wird die automatische Erkennung übersprungen. Schema: siehe Schritt 3.

Slug = Basisname des Arbeitsordners (keine Ableitung erforderlich). Alle Skripte lesen/schreiben innerhalb dieses Ordners. Skripte akzeptieren das Flag --workspace <path> und verwenden standardmäßig das aktuelle Arbeitsverzeichnis (CWD).

---

Die Pipeline (sequentielle Skriptausführung)

voiceover.mp3 + source.mp4 + script.txt
    │
    ▼
1. transcribe_audio.py        ── Whisper VN → transcript.json (Wortebene)
    │
    ▼
2. clean_transcript.py        ── Whisper-Artefakte entfernen, VN-Wörterbuch anwenden
    │
    ▼
3. detect_scenes.py           ── Transkript + script.txt → scenes-outline.json (5 Szenen)
    │
    ▼
4. [optionaler KONTROLLPUNKT] ── Benutzer überprüft die Gliederung / bearbeitet Kicker, Überschrift
    │
    ▼
5. scaffold_project.py        ── schreibt scenes.json (vollständiges Schema), erstellt sfx/ + logos/ + avatar.jpg + yt-lower-third.html
    │
    ▼
6. 🔥 LLM-SUB-AGENT-FANOUT 🔥 ── Der Orchestrator startet N parallele Allzweck-Agenten
                                  (1 pro Szene) in einer einzigen Nachricht, jeder erstellt
                                  compositions/scene-{num}.html basierend auf
                                  visual-plan.json + references/composition-patterns.md.
                                  NICHT generate_compositions.py (Jinja2-Generator
                                  VERALTET — reduziert sich auf 5 Archetypen, kann nicht an
                                  szenenspezifische Metaphern anpassen, bricht bei Listen mit 6+ Szenen).
    │
    ▼
7. generate_root_index.py     ── schreibt index.html mit Folienhalterung (lädt scene-{num}.html
                                  für ALLE Szenen, keine kind→fs-lesson-Zuordnung) +
                                  Avatar-Rahmen (Claude-Orange #d97757 Markenrand) +
                                  GSAP-Timeline (SPLIT↔PIP, Atmung, Punch-In,
                                  PIP_EVENTS, hybrider Hook-Zoom) + 6 SFX verdrahtet +
                                  Cream-Paper-B-Roll-Bildebene auf Root (volle 1920×1080)
    │
    ▼
8. [optional] scaffold_infographic_slots.py
                              ── fügt <img onerror>-Platzhalter hinzu + schreibt prompts.md
                                  (Cream-Paper-Redaktion pro Szenenmetapher)
    │
    ▼
9. lint_and_preview.py        ── npx hyperframes lint → 0 Fehler, dann Vorschau
    │
    ▼
ÜBERGABE — Studio-URL wird ausgegeben; Benutzer überprüft; Orchestrator entscheidet über Rendering.

Vorschauregel (nicht verhandelbar): Das Skill endet bei Schritt 9 mit der Studio-URL. Die MP4-Renderung erfolgt erst nach expliziter Bestätigung des Benutzers – dieser Schritt gehört zum Orchestrator oder zur manuellen Benutzeraktion.

Schritt 1: transcribe_audio.py

python3 scripts/transcribe_audio.py --workspace <ordner>

Verwendet das vorhandene Skill mkt-ai-video-extract-srt-segment, falls lokal verfügbar; anderenfalls Rückgriff auf whisper CLI direkt:

whisper voiceover.mp3 --model medium --language vi --word_timestamps True \
  --output_format json --output_dir .

NIEMALS --model medium.en für vietnamesische Audiodaten verwenden – .en übersetzt anstatt zu transkribieren. Immer --language vi.

Ausgabe: transcript.json — Array mit {text, start, end}-Einträgen auf Wortebene.

Schritt 2: clean_transcript.py

Verwendet die Logik des verwandten 9:16-Editors (mkt-hyperframe-talking-head-video/scripts/clean_transcript.py) erneut. Entfernt U+FFFD, wendet ein VN-Wörterbuch auf Wort- und Phrasenebene an (alphabit→Alphabet, Cod→Code, usw.), gruppiert in 3-5-Wort-Phrasen. Ausgabe: transcript-cleaned.json. (Kein caption-groups.json — Untertitel sind bei 16:9 AUS.)

Schritt 3: detect_scenes.py

Liest transcript-cleaned.json + script.txt → leitet 5 Szenengrenzen unter Verwendung eines standardmäßigen Knowledge-Video-Skeletts ab:

#	Art	Standard-Kicker-Hinweis	Variante
1	Hook	Erster Satz des Skripts	tier-row (Post-Stack-Gefühl durch kind=hook)
2	Problem	Wo das Skript zu „ChatGPT/AI cũ“, „khó“, „đứt mạch“, „vấn đề“… übergeht	chats-stack
3	Lösung	Wo das Skript das Tool/die Methode vorstellt	hero-orb
4	Zusammenfassung	Wo das Skript ein numerisches Ergebnis zeigt („X tiếng“, „Y khách hàng“)	counter-row
5	CTA	Letzter Satz mit Kommentar/speichern/folgen-Auslöser	terminal-row

Wenn das Skript keine klaren 5 Teile hat, werden weniger ausgegeben (mindestens 3) und der Benutzer gewarnt. Heuristik: Transkript an Satzgrenzen in ~5 Blöcke aufteilen, gewichtet mit 1,5x für Szene 3 (Lösung ist normalerweise am längsten).

Ausgabe scenes-outline.json:

[
  { "num": 1, "kind": "hook",     "start": 0.07,  "end": 13.73, "kicker": "...", "heading": "...", "variant": "tier-row" },
  { "num": 2, "kind": "problem",  "start": 13.73, "end": 27.37, "kicker": "...", "heading": "...", "variant": "chats-stack" },
  { "num": 3, "kind": "solution", "start": 27.37, "end": 47.75, "kicker": "...", "heading": "...", "variant": "hero-orb" },
  { "num": 4, "kind": "recap",    "start": 47.75, "end": 53.80, "kicker": "...", "heading": "...", "variant": "counter-row" },
  { "num": 5, "kind": "cta",      "start": 53.80, "end": 60.68, "kicker": "...", "heading": "...", "variant": "terminal-row" }
]

KONTROLLPUNKT — Gliederung zur Überprüfung durch den Benutzer ausgeben. Benutzer können Kicker/Überschrift/Variante inline bearbeiten und dann fortfahren. Kontrollpunkt überspringen, wenn das Skill mit --auto (Orchestrator-Modus) aufgerufen wird.

Schritt 4: scaffold_project.py

Liest scenes-outline.json → reichert jede Szene an mit:

• accent_words — von der Überschrift ableiten (Zahlen + letzte 2-3 Nomen extrahieren)
• content — musterspezifisches Schema (siehe assets/templates/)
• badges — 1-3 schwebende Abzeichen pro Szene
• brollEnd, hasBreath — für SPLIT↔PIP-Planung
• pip_events — von accent_words-Timing innerhalb der Szene abgeleitet

Schreibt scenes.json. Kopiert außerdem automatisch diese eigenständigen Assets aus den skill-gebündelten assets/ in den Arbeitsordner:

Asset	Quelle	Ziel	Zweck
6 SFX-Dateien	assets/sfx/	<workspace>/sfx/	Beat-Sounds (Kamera-Blitz, Whoosh, Finger-Schnippen, Laser, Ting, Discord-Benachrichtigung)
Markenlogos	assets/logos/{chatgpt,gemini,claude,claude-code}.{png,jpg}	<workspace>/assets/logos/	Automatisch an Kompositionen angehängt (Chats-Stack-Avatare, Hero-Orb, Tier-Row-Tool-Abzeichen)
Avatar	assets/avatar.jpg	<workspace>/assets/avatar.jpg	Kanal-Thumbnail für das YT-Lower-Third-Abo-Banner
YT Lower-Third	assets/compositions/yt-lower-third.html	<workspace>/compositions/yt-lower-third.html	Abo-Banner-Halterung, letzte 3s des Videos

Wenn ein Quell-Asset im Skill-Bundle fehlt, erfolgt ein stiller Rückgriff auf den Legacy-Arbeitsordner-Pfad (workspace/assets/...). Wenn keines gefunden wird, wird dieses Asset übersprungen (Kompositionen degradieren elegant – Text-Avatare anstelle von Logos, kein Lower-Third).

Schritt 5: 🔥 LLM-SUB-AGENT-FANOUT (Kompositionserstellung) 🔥

generate_compositions.py ist VERALTET. Rufen Sie es nicht auf. Der Python-Jinja2-Generator reduziert jede Szene auf einen von 5 festen Archetypen (Hook → tier-row, Problem → chats-stack, Lösung → hero-orb, Zusammenfassung → counter-row, CTA → terminal-row), kann nicht an szenenspezifische Metaphern angepasst werden (z. B. „scroll-tape-wasted“, „two-clock-comparison“, „right-tool-vehicles“) und bricht bei Listen mit 6+ Szenen (mehrere tip-N reduzieren sich auf denselben Dateinamen → Überschreibung).

Kanonische Methode: Der Orchestrator (oder Benutzer) startet N parallele general-purpose-Agenten (1 pro Szene) in einer einzigen Nachricht, sodass sie gleichzeitig laufen. Jeder Sub-Agent:

1. Liest seinen Szenenblock aus visual-plan.json (Pfad: <workspace>/visual-plan.json, Szenenindex num-1)
2. Liest Referenzen aus dem Orchestrator-Skill: references/composition-patterns.md (8 produktionserprobte Muster), references/slide-design-tokens.md (Palette + Typografie)
3. Wählt das richtige Muster für die Metapher seiner Szene aus – passt frei an (hero-orb kann zu vault+spokes werden, stats-3card kann zu two-clock-comparison werden)
4. Erstellt compositions/scene-{num}.html von Grund auf mit: 1200×1080 Viewport, bereichsbezogenem CSS via [data-composition-id="scene-{num}"], GSAP-Timeline registriert unter window.__timelines["scene-{num}"], kein !important, kein eingebetteter image-slot (Cream-Paper-Bild lebt nur auf der Root-Ebene)

Das Ergebnis: Jede Szene erhält eine einzigartige, metapherangepasste Kompositionsdatei. Keine Kollisionen, keine langweilige 5-Archetypen-Beschränkung.

Siehe die mkt-full-video-with-11-hyperframe-heygen-16-9/SKILL.md des Orchestrators, Schritt 4d, für die vollständige Sub-Agent-Prompt-Vorlage.

Markenlogos in Kompositionen (Sub-Agenten referenzieren diese)

Sub-Agenten betten Markenlogos ein, wenn ihr Muster sie benötigt. Logos befinden sich unter <workspace>/assets/logos/:

Musterverwendung	Markenelement
Hook Tier-Row „nachher“	tool-badge-Pille (oben rechts) – Claude-Logo + Name.
Problem Chats-Stack-Fail-Zeilen	ChatGPT/Gemini-Logos automatisch angehängt, wenn name mit einem Schlüsselwort übereinstimmt (chatgpt/gpt → chatgpt.png; gemini/google → gemini.jpg).
Lösung Hero-Orb / Vault	Markenlogo im Inneren des Orb-Leuchtens (Standard Claude).
CTA Terminal-Row	Standardmäßig keine Logos.

Sub-Agenten greifen auf Text-Avatar zurück, wenn assets/logos/ nicht existiert (kein Flackern).

Musterreferenz (8 Archetypen, Sub-Agenten wählen aus + passen an)

Die references/composition-patterns.md des Orchestrators enthält 8 produktionserprobte Muster:

Muster	Am besten geeignet für	Internes Motiv
tier-row before-after	Hook-Kontrast	2 Tier-Rows (vorher rosa/rot + nachher limette/grün) mit Buchstabe + Elementen
chats-stack	Problem / Fehler / Edit-Regen-Demo	Benutzerzeile + 2-3 AI-Fail-Zeilen + Broken-Chain-Stempel
hero-orb + spec-trio	Lösung / Mechanismus / zentrales Vault	Leuchtender Orb + Aufgaben-Symbole + 3 Spezifikations-Tier-Rows
counter-row	Zusammenfassung / Zahlenbeweis	Großer Zähler (VON → BIS) + Kunden + Delta-Tag
comment-terminal	CTA / „Kommentar X“	Tier-Buchstabe + macOS-Terminal-Mock + 2 Geschenkkarten
stats-3card	Wissenseinführung / 3-Fakten-Enthüllung	3 Spalten im Landing-Stil mit // LBL + Farbverlaufsnummer
comparison-2col	„Wann was verwenden“	2-Spalten Ja/Ja-Chips
image-slot	(VERALTET — Bild auf Root-Ebene)	—

Sub-Agenten passen frei an: z. B. hero-orb → „Vault + 5 Chat-Spokes“, stats-3card → „two-clock-comparison“, comparison-2col → „3-stufige Fahrzeugkarten“. Das Musterdokument gibt das Skelett (HTML + CSS + GSAP) vor, das LLM übernimmt die kreative Anpassung.

Schritt 6: generate_root_index.py

Liest scenes.json + total_duration aus dem Transkript → rendert assets/templates/index.html.j2:

• 1920×1080 Root mit #slide-bg, #heygen-bg, #avatar-frame > .avatar-breathing > .avatar-punch > #v-source
• <audio id="a-source"> verfolgt das Audio der ursprünglichen source.mp4 (Spur 1)
• 6 <audio> SFX verdrahtet mit absoluten data-start (Szenengrenzen)
• Markenzeichen oben links
• GSAP-Block:
  • Anfänglicher Eintritt (Avatar-Einblendung, Marken-Einblendung)
  • SPLIT/PIP-Konstanten + goPIP(t) / goSplit(t)-Helfer
  • PIP_EVENTS-Array, gesteuert von den szenenspezifischen pip_events aus scenes.json
  • „Hybride Hook“-visuelle Zoom-Strategie auf .avatar-breathing:
    • HOOK-Szene: Langsamer Anstieg 1,0 → 1,10 über die Szenendauer (Spannungsaufbau, power2.in)
    • HOOK→BODY-Übergang: Schneller Reset 1,10 → 1,0 (Spannung lösen, 0,5s power3.in)
    • BODY-Szenen (2..N-1) bei PIP-IN-Ereignissen: 1,06 Punch-Beats (Rhythmus, power2.out → power3.out)
    • CTA-Szene: Sanfter Push 1,0 → 1,04 (Abschluss, sine.inOut)
  • Pro-Szenen-Start kleiner Punch (1,06) auf .avatar-punch für Übergangsbeat

(Ab hier gekürzt, das Original endet hier.)