lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

mkt-full-video-with-11-hyperframe-heygen

End-to-End-Orchestrator: Skript → fertiges TikTok/Reels MP4 9:16.

Pipeline mit 2 Benutzer-Checkpoints:

1. MP3-Checkpoint (Orchestrator) — nach Phase 1 prüft der Benutzer das Voiceover.
2. Szenen-Outline-Checkpoint (Phase 3 Sub-Agent) — Benutzer prüft die Szenenstruktur + Varianten, bevor die Inhaltsautoren (fan-out) gestartet werden. Kann übersprungen werden, wenn der Benutzer auto_scenes=true übergibt.

Wann verwenden

• Benutzer hat ein vietnamesisches/englisches Skript ≤ 5000 Zeichen und möchte ein fertiges TikTok-Video
• Optional sind B-Roll-Bilder oder -Videos mit Verwendungszweck vorhanden
• Benutzer möchte einen nahtlosen Workflow vom Drehbuch bis zur Studio-Vorschau

Diese Fähigkeit nicht verwenden, wenn:

• Benutzer bereits eine MP3-Datei hat → direkt heygen-mp3-to-mp4 verwenden
• Benutzer bereits ein MP4-Talking-Head-Video hat → direkt mkt-hyperframe-talking-head-video verwenden
• Benutzer möchte, dass HeyGen den Text selbst liest (nicht über ElevenLabs) → heygen-script-to-mp4 verwenden
• Skript > 5000 Zeichen → semantisch aufteilen und die Pipeline für jedes Segment erneut aufrufen

Pipeline-Übersicht

Skript (Text + optionales B-Roll + tts_provider)
    |
    ▼
Phase 1 ── TTS (elevenlabs | minimax) ──► voiceover.mp3
    |                                         |
    |                                         ▼
    |                              CHECKPOINT #1 — Benutzer hört und prüft MP3
    |                                         |
    |                                         ▼ (OK)
Phase 2 ── heygen-mp3-to-mp4 ──────────► source.mp4 (9:16 Lip-Sync)
    |
    ▼
Phase 3 ── Starte Agent mkt-full-video-phase3-packager (isolierter Kontext)
            |
            ├─ transkribieren + bereinigen + Untertitel gruppieren
            ├─ Szenengrenzen erkennen + mockup_variant klassifizieren
            ├─ CHECKPOINT #2 — Benutzer prüft Szenen-Outline
            ├─ FAN-OUT N allgemeine Sub-Agents (1 pro Szene) parallel
            │   → jeder Sub-Agent erstellt Content-JSON nach Varianten-Schema
            ├─ zusammenführen → scenes.json
            ├─ parallel: Sub-Compositions bereitstellen + SFX kopieren + Untertitel einfügen
            ├─ root index.html generieren
            └─ lint + Vorschau im Studio
    |
    ▼
Benutzer prüft Vorschau → "render" → finales MP4

Checkpoint-Regel: Der Orchestrator verwaltet Checkpoint #1 (MP3). Phase 2 → 3 läuft automatisch. Checkpoint #2 (Szenen-Outline) wird vom Phase 3 Sub-Agenten verwaltet. Das finale Render-Gate liegt beim Benutzer im Studio.

Eingaben

Eingabe	Erforderlich	Format / Beispiel
Skripttext	Ja	Dateipfad (.txt/.md) oder Inline-String. ≤ 5000 Zeichen.
Slug-Projekt	Nein	Wird automatisch aus den ersten 5 Wörtern des Skripts abgeleitet. Kleinbuchstaben, ASCII, Bindestrich.
B-Roll-Liste	Nein	Array [{path: "...", purpose: "Lektion 1 — Veranschaulichung X"}, ...].
tts_provider	Nein	elevenlabs (Standard — Hoàngs Stimme, ausdrucksstark) oder minimax (speech-2.8-hd, günstiger, liest Vietnamesisch natürlicher). Benutzer sagt "minimax verwenden" / "eleven verwenden" → entsprechend setzen.
Voice-ID-Überschreibung	Nein	Überschreibt den Standardwert aus .env. ElevenLabs liest ELEVENLABS_VOICE_ID, MiniMax liest MINIMAX_VOICE_ID. CLI-Flag --voice_id für beide.
Voice-Einstellungen überschreiben	Nein	ElevenLabs: {stability, similarity_boost, style}. MiniMax: {speed, vol, pitch}.
Avatar-Aussehen	Nein	1 ID aus der HEYGEN_AVATAR_LOOKS-Env-Variable (.env, kommagetrennt). Zufallsauswahl, wenn nicht ausgewählt.
auto_scenes	Nein	Standard false. true, um den Szenen-Outline-Checkpoint in Phase 3 zu überspringen.

Arbeitsbereich-Layout

workspace/content/YYYY-MM-DD/<slug>/
├── script.txt              # Phase 0
├── voiceover.mp3           # Phase 1
├── source.mp4              # Phase 2
├── broll/                  # Vom Benutzer bereitgestelltes B-Roll (Kopie)
├── transcript.json         # Phase 3
├── caption-groups.json     # Phase 3
├── scenes-outline.json     # Phase 3 — Outline vor Checkpoint
├── scenes/                 # Phase 3 — Fan-Out pro Szene schreibt hier Content
│   ├── scene-1.json
│   └── ...
├── scenes.json             # Phase 3 — zusammengeführtes Finale
├── compositions/           # Phase 3 — HF-Sub-Comps
├── sfx/                    # Phase 3 — 6 Soundeffekte
└── index.html              # Phase 3 — Root-Composition

YYYY-MM-DD = heutiges Datum (UTC+7).

Workflow

Schritt 0 — Einrichtung

1. Validieren len(script_text) <= 5000. Überschritten → anhalten, Benutzer bitten, semantisch zu teilen.
2. Slug ableiten, falls nicht vorhanden: erste 5 Wörter → Kleinbuchstaben → Akzente entfernen → Leerzeichen→Bindestrich.
3. TTS-Anbieter auflösen — tts_provider aus Benutzereingabe lesen (Standard elevenlabs). Wenn Benutzer "minimax verwenden" / "zu minimax wechseln" sagt → minimax. Wenn Benutzer "eleven verwenden" / "elevenlabs" sagt → elevenlabs. Validieren, dass der entsprechende API-Key in .env vorhanden ist:
   • elevenlabs → benötigt ELEVENLABS_API_KEY (optional ELEVENLABS_VOICE_ID zum Überschreiben des Standards K7ewtjKRNtwwt3lKQ6M0).
   • minimax → benötigt MINIMAX_API_KEY (optional MINIMAX_VOICE_ID zum Überschreiben des Standards moss_audio_c56d6120-ef9c-11f0-9649-8ee40147f116). Fehlender Key → anhalten, Benutzer informieren, ihn zu .env hinzuzufügen.
4. Erstelle workspace/content/YYYY-MM-DD/<slug>/. Speichere script.txt.
5. Wenn Benutzer B-Roll hat: erstelle <folder>/broll/, kopiere Datei, behalte Originalnamen.
6. Benutzer informieren: "Arbeitsbereich erstellt unter <folder>. TTS-Anbieter: <elevenlabs|minimax>. Starte Phase 1."

Schritt 1 — Phase 1: Skript → MP3 (TTS)

Führe genau 1 der beiden Zweige je nach tts_provider aus:

Zweig A — ElevenLabs (Standard):

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

Voice-ID: automatisch ELEVENLABS_VOICE_ID aus .env lesen (Fallback Standard Hoàng's Markenstimme). Überschreibung per CLI: --voice_id <id>. Voice-Einstellungen: --stability / --similarity_boost / --style hinzufügen, wenn Benutzer eine Anpassung wünscht.

Zweig B — MiniMax:

uv run .claude/skills/mkt-video-script-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

Voice-ID: automatisch MINIMAX_VOICE_ID aus .env lesen (Fallback Standard moss_audio_…). Überschreibung per CLI: --voice_id <id>. Voice-Einstellungen: --speed (Standard 1.08), --vol, --pitch, --language_boost Vietnamese.

Ausgabedateiname unveränderlich in beiden Zweigen: voiceover.mp3, damit Phase 2 (HeyGen) den richtigen Pfad findet.

Nach Abschluss die Dauer prüfen (für beide Anbieter gleich):

uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py \
  workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

TOO_LONG → anhalten, Benutzer informieren, dass MP3 > 5 Minuten HeyGen-Limit, Skript kürzen.

Schritt 2 — CHECKPOINT #1: Benutzer hört MP3

Einziger vom Orchestrator verwalteter Stoppunkt. Benutzer im richtigen Format informieren:

## Voiceover bereit — bitte prüfen

**Datei:** `workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3`
**Dauer:** <X.X>s
**Größe:** <Y.Y> MB
**Anbieter:** <`elevenlabs` | `minimax`>
**Stimme:** <`ElevenLabs Markenstimme von Hoàng (K7ewtjKRNtwwt3lKQ6M0)`> oder <`MiniMax speech-2.8-hd (moss_audio_…)`> (aus `.env`-Voice-ID, falls Benutzer überschrieben hat)

Öffne die Datei zum Anhören. Antworte mit 1 von:
- **`OK`** / **`weiter`** → ich starte Phase 2 (HeyGen Avatar Lip-Sync)
- **`regen`** + (optional) Grund → ich passe Voice-Einstellungen an und generiere MP3 neu
- **`Skript bearbeiten`** + neuer Inhalt → ich speichere neues Skript und führe Phase 1 erneut aus

Tool-Aufrufe stoppen. Auf klare Benutzerantwort warten.

Wenn Benutzer OK → Phase 2. Wenn Benutzer regen → TTS-Skript des aktuellen Anbieters mit neuen Einstellungen erneut ausführen, zurück zum Checkpoint. Wenn Benutzer "zu minimax wechseln" / "eleven probieren" sagt → tts_provider wechseln, Phase 1 neu starten. Wenn Benutzer Skript bearbeitet → script.txt überschreiben, Phase 1 von vorne starten (gleicher Anbieter).

Schritt 3 — Phase 2: MP3 → HeyGen MP4 (automatisch)

Gemäß Sub-Skill heygen-mp3-to-mp4:

1. Avatar-ID auswählen — HEYGEN_AVATAR_LOOKS aus .env lesen (kommagetrennt), zufällig auswählen, wenn Benutzer keine Angabe macht:

   HEYGEN_AVATAR_LOOKS=$(grep '^HEYGEN_AVATAR_LOOKS=' .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
   echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'
   

   Wenn Env-Variable fehlt/leer ist → anhalten und Benutzer informieren, HEYGEN_AVATAR_LOOKS=<id1>,<id2> zu .env hinzuzufügen. Benutzer vor dem MCP-Aufruf auswählen lassen.

2. MP3 hochladen zu HeyGen via MCP (upload_asset, asset type audio). KEIN curl https://upload.heygen.com/....

3. Avatar-Video erstellen via MCP (generate_avatar_video):

   character: { type: avatar, avatar_id: <ausgewählt>, scale: 1.0 }
   voice:     { type: audio, audio_asset_id: <vom Upload> }
   dimension: { width: 720, height: 1280 }   # 9:16
   title:     "<slug>-<Zeitstempel>"
   

4. Status abfragen alle ~10s → completed (max. 10 Min.). failed → anhalten, Fehler anzeigen.

5. MP4 herunterladen → workspace/content/YYYY-MM-DD/<slug>/source.mp4 (Dateiname unveränderlich):

   uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py \
     "<video_url>" "workspace/content/YYYY-MM-DD/<slug>/source.mp4"
   

6. Benutzer in einer Zeile informieren: "Phase 2 erledigt — <path> (Avatar <id>, s, <Größe>MB). Starte Phase 3 Packager…"

Hier nicht anhalten. Automatischer Übergang zu Phase 3.

Schritt 4 — Phase 3: Sub-Agent Packager starten

Das Task-Tool mit subagent_type: "mkt-full-video-phase3-packager" verwenden. Ein in sich geschlossenes Prompt mit den benötigten Eingaben für den Agenten übergeben. Beispiel:

Arbeitsbereich: workspace/content/2026-05-03/hom-nay-minh-chia-se/
Slug: hom-nay-minh-chia-se
Skript: <vollständiger Skripttext>
B-Roll: [
  {"path": "workspace/content/2026-05-03/hom-nay-minh-chia-se/broll/alphabet.png", "purpose": "Lektion 1"},
  ...
]
auto_scenes: false
header_label: "3 LEKTIONEN KI"
footer_handle: "@tranvanhoang.com"

Führe die vollständige Phase-3-Packaging-Pipeline gemäß deiner Agentendefinition aus. Gib die Studio-URL zurück, wenn die Vorschau geöffnet ist.

Der Sub-Agent:

• Transkribiert source.mp4, erstellt eine Szenenstruktur
• Hält an, um den Benutzer um Freigabe der Struktur zu bitten (CHECKPOINT #2), es sei denn, auto_scenes: true
• Startet N Szenen-Inhaltsautoren parallel (fan-out)
• Führt zusammen + bereitet vor + lint + öffnet Vorschau
• Gibt Studio-URL zurück

Während der Sub-Agent läuft, besteht die einzige Aufgabe des Orchestrators darin, Benutzerantworten an den Sub-Agenten weiterzuleiten (die Benutzerantwort am Szenenstruktur-Checkpoint wird in dieser Konversation ankommen; leite sie an den Sub-Agenten weiter, wenn er noch aktiv ist, behandle sie andernfalls als Folgeanweisung).

Schritt 5 — Übergabe

Wenn der Sub-Agent die Studio-URL zurückgibt, den abschließenden Bericht formatieren:

## Full Video Pipeline FERTIG — Vorschau bereit

**Arbeitsbereich:** `workspace/content/YYYY-MM-DD/<slug>/`

**Phase 1 (`<elevenlabs|minimax>`):** voiceover.mp3 — <D1>s, <S1>MB (Voice-ID `<id>`)
**Phase 2 (HeyGen):** source.mp4 — Avatar `<avatar_id>`, <D2>s, <S2>MB
**Phase 3 (HyperFrames):** <N> Szenen (<Liste der Varianten>), <K> Untertitelgruppen, 6 Soundeffekte

**Studio-URL:** http://localhost:3002

Öffne Browser, scrub timeline. Sage **`render`**, wenn OK → ich führe `npx hyperframes render` aus, um MP4 1080×1920 30fps zu exportieren.

Hier anhalten. Kein Auto-Render. Erst wenn der Benutzer bestätigt, npx hyperframes render aufrufen.

Kritische Orchestrierungsregeln

1. 2 Benutzer-Checkpoints, 1 Orchestrator-Gate — Orchestrator hält nur bei MP3 an (Schritt 2). Den Szenenstruktur-Checkpoint verwaltet der Phase-3-Sub-Agent. Das Render-Gate im Studio liegt beim Benutzer.

2. Pfadkonventionen unveränderlich — Voiceover muss voiceover.mp3 heißen, Talking-Head muss source.mp4 heißen. Der HF-Sub-Skill erwartet den Namen source.mp4.

3. Nur HeyGen MCP — niemals https://api.heygen.com/... curlen. Harte Einschränkung von heygen-mp3-to-mp4.

4. Voice-ID in .env gespeichert, nicht im Skill hartcodiert. ElevenLabs liest ELEVENLABS_VOICE_ID (Fallback K7ewtjKRNtwwt3lKQ6M0). MiniMax liest MINIMAX_VOICE_ID (Fallback moss_audio_…). Überschreibung pro Aufruf via --voice_id. Pipeline gibt Anbieter + ausgewählte Voice-ID in Schritt 0 und Checkpoint #1 klar an.

5. Skriptlängen-Hardcap 5000 Zeichen — frühzeitig fehlschlagen in Schritt 0.1.

6. MP3-Dauer ≤ 300s — HeyGen-Single-Video-Limit. Direkt nach Phase 1 prüfen.

7. Vorschau zuerst — Phase 3 KEIN Auto-Render. Speicher feedback_hyperframes_workflow.md.

8. Phase 3 Isolation — Phase 3 läuft in einem separaten Sub-Agent-Kontext. HF-Skill-Body + 4 Referenzdokumente (~40KB) werden in den Sub-Agenten geladen, nicht in den Haupt-Orchestrator.

Fehlermodi & Fallbacks

Symptom	Aktion
Skript > 5000 Zeichen	Anhalten, Benutzer bitten, semantisch zu teilen
ElevenLabs API-Fehler	Fehler melden, vorschlagen ELEVENLABS_API_KEY in .env zu prüfen (optional ELEVENLABS_VOICE_ID). Oder zu tts_provider=minimax wechseln und Phase 1 erneut ausführen
MiniMax API-Fehler	Fehler melden, vorschlagen MINIMAX_API_KEY in .env zu prüfen (optional MINIMAX_VOICE_ID). Oder zu tts_provider=elevenlabs wechseln und Phase 1 erneut ausführen
MP3 > 300s nach Phase 1	Pipeline anhalten, heygen-short-video (Chunking) vorschlagen
HeyGen MCP nicht verbunden	Anhalten, claude mcp list zur Überprüfung melden
HeyGen Render fehlgeschlagen	Fehler anzeigen, vorschlagen, Credits via mcp__heygen__get_current_user zu prüfen
Phase 3 Sub-Agent Fehler	Fehler-Trace lesen, vorschlagen, Phase 3 eigenständig mit dem Skill mkt-hyperframe-talking-head-video erneut auszuführen
Szenenautor gibt fehlerhaftes JSON zurück	Sub-Agent startet für diese Szene automatisch neu (nicht Aufgabe des Orchestrators)
Benutzer lehnt MP3-Stimme ab	Zurück zu Phase 1 mit angepassten Voice-Einstellungen

Beispiel Ende-zu-Ende

Benutzer:

Ich habe ein Skript, führe die gesamte Pipeline für ein TikTok-Video aus. Dazu 2 B-Roll-Bilder für Lektion 1 und Lektion 2. Skript: "Heute teile ich 3 Lektionen von Anthropic. Die erste Lektion ist Alphabet Ship Beta. Die zweite Lektion ist 24h…" B-Roll: alphabet.png (Lektion 1), clock.png (Lektion 2)

Pipeline:

1. Schritt 0 — Slug hom-nay-minh-chia-se. Ordner workspace/content/2026-05-03/hom-nay-minh-chia-se/. script.txt speichern, B-Roll kopieren.
2. Schritt 1 — text_to_mp3.py → voiceover.mp3 (45s, 0.7MB).
3. Schritt 2 — CHECKPOINT #1 — Benutzer Pfad + Dauer melden. Auf Antwort warten.
4. Benutzer: OK.
5. Schritt 3 — Avatar auswählen (zufällig aus HEYGEN_AVATAR_LOOKS, z.B. 66e75e22…). MP3 hochladen → asset_id. Video generieren → poll → source.mp4 herunterladen (45s, 7.5MB).
6. Schritt 4 — Sub-Agenten mkt-full-video-phase3-packager starten.
7. Sub-Agent transkribiert (35s), erstellt Struktur (3 Lektionen + Zusammenfassung + CTA), zeigt Struktur → CHECKPOINT #2.
8. Benutzer: OK.
9. Sub-Agent startet 5 Szenenautoren parallel (~8s Wanduhr vs. ~40s seriell).
10. Sub-Agent führt zusammen → scenes.json → prepare + SFX + Untertitel parallel. ...

[truncated for translation]