mkt-hyperframe-talking-head-video
Pipeline zur Erstellung eines vollständigen HyperFrames-Vorschauprojekts aus einer voraufgezeichneten MP4-Datei (Talking-Head im 9:16-Format) mit Untertiteln, Soundeffekten, Zoom-Hooks, B-Roll-Szenen mit reichhaltigen Effekten und einem CTA-Finale.
Wann verwenden
- Der Benutzer hat ein 9:16 Face-Cam-Video (TikTok/Reels/Shorts) aufgenommen und möchte Untertitel, visuelle Hooks und Soundeffekte hinzufügen
- Der Benutzer hat zusätzliche B-Roll-Bilder oder -Videos, die eingefügt werden sollen (mit Angabe des Verwendungszwecks)
- Der Benutzer möchte eine Studio-Vorschauausgabe, um die Optik vor dem Rendern des MP4 zu prüfen
Verwende diese Fähigkeit NICHT, wenn:
- Der Benutzer hat noch kein Video aufgenommen – verwende
mkt-create-script-short-video, um zuerst ein Skript zu schreiben, oder eine andere Fähigkeit, um Voiceover + KI-Avatar zu erstellen - Der Benutzer hat bereits ein HyperFrames-Projekt und möchte nur kleine Anpassungen vornehmen – bearbeite die Datei direkt, anstatt das Projekt neu zu strukturieren
- Der Benutzer möchte ein MP4 aus einem vorhandenen Projekt rendern – führe direkt
npx hyperframes renderaus
Pipeline-Übersicht
9:16 Talking-Head MP4 + (optional) B-Roll-Dateien
│
▼
1. MP4 prüfen ────────── ffprobe → Dauer, Auflösung, FPS
│
▼
2. Struktur planen ───── automatische Erkennung von Lektionsmarkierungen aus Benutzereingabe ODER aus Transkript
│
▼
3. Transkribieren ────── npx hyperframes transcribe --model medium --language vi
│
▼
4. Transkript bereinigen ──── VN Whisper-Fehlerwörterbuch anwenden (alphabit→Alphabet, usw.)
│
▼
5. Untertitel gruppieren ─── 3-5 Wörter/Gruppe, bei >0.45s Pause trennen, Timing beibehalten
│
▼
6. B-Roll zuordnen ───── Benutzer nach Verwendungszweck fragen → Lektionsszenen zuweisen
│
▼
7. Projektstruktur erstellen ──── workspace/video-projects/<slug>/
├── index.html (Stammverzeichnis)
├── source.mp4
├── transcript.json + caption-groups.json
├── compositions/
│ ├── captions.html
│ ├── fs-lesson-N.html (eine pro Lektion, unterschiedliche Effekte)
│ ├── recap-card.html (falls zutreffend)
│ └── fs-cta.html
└── sfx/ (6 Soundeffekte)
│
▼
8. Lint ──────────────── npx hyperframes lint → Fehler beheben
│
▼
9. Vorschau öffnen ──── npx hyperframes preview (Hintergrund) → URL Studio
│
▼
10. An Benutzer übergeben ──── KEIN automatisches MP4-Rendern
Vorschau-zuerst-Regel (nicht verhandelbar): Die Fähigkeit endet bei Schritt 9 mit der Studio-URL. Das MP4-Rendern wird nur ausgeführt, wenn der Benutzer nach der Vorschau explizit zustimmt.
Schritt 1: Eingabe + Plan überprüfen
Der Benutzer wird Folgendes bereitstellen:
| Eingabe | Erforderlich | Format |
|---|---|---|
| 9:16 Face-Cam MP4 | Ja | Dateipfad |
| Slug / Projektname | Nein | Automatisch aus Dateinamen abgeleitet, falls nicht angegeben |
| B-Roll-Liste | Nein | [{path: "screenshot.png", purpose: "Lektion 1 — Testillustration"}, ...] |
| Videostruktur | Nein | "3 Lektionen + Intro + CTA" / "5 Tipps" / usw. — automatisch erkannt, falls nicht angegeben |
Prüfe das MP4, bevor du etwas unternimmst:
ffprobe -v error -show_entries format=duration:stream=codec_type,width,height,r_frame_rate \
-of json "<mp4_path>"
Überprüfe:
- Auflösung ist 9:16 (z. B. 1080x1920, 1440x2560) — wenn Querformat, warne, aber fahre trotzdem fort (object-fit:cover wird zuschneiden)
- Dauer < 180s ideal; > 180s ist in Ordnung, aber warne den Benutzer, dass TikTok-Algorithmus ≤90s bevorzugt
- FPS 24/25/30/60 sind alle OK — Ausgabe wird standardmäßig 30fps sein
Slug: Aus Dateinamen ableiten, Kleinbuchstaben, vietnamesische Zeichen → ASCII, Leerzeichen → Bindestrich. Beispiel "3 bài học .mp4" → 3-bai-hoc. Benutzer kann überschreiben.
Ausgabeverzeichnis: workspace/video-projects/<slug>/
Schritt 2: Transkribieren + bereinigen
cd workspace/video-projects/<slug>/
cp <user_mp4> source.mp4
npx hyperframes transcribe source.mp4 --model medium --language vi
Verwende NIE --model medium.en oder small.en für vietnamesisches Audio — .en-Modelle ÜBERSETZEN ins Englische anstatt zu transkribieren. Verwende immer --language vi für vietnamesisches Audio.
Nach Abschluss das Transkript bereinigen:
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/clean_transcript.py \
transcript.json
# schreibt: transcript.json (bereinigt) + caption-groups.json (automatisch gruppiert)
Das Skript hat die VN Whisper-Fehlerersetzungen angewendet (alphabit→Alphabet, Cod→Code, kontextabhängige dụng/dùng-Ersetzung, đ��ng→đắc, usw.) und automatisch in 3-5 Wort-Untertitelphrasen mit Pause bei >0.45s Lücke gruppiert.
Kritische Untertitel-Synchronisationsregel: Das Timing MUSS originalgetreu aus dem Wort-für-Wort-Transkript übernommen werden. Bearbeite das Timing NICHT von Hand. Wenn Text korrigiert werden muss, korrigiere nur den Text – das Skript clean_transcript.py erledigt dies. Typischer Fehler: Text von Hand bearbeiten und dabei versehentlich das Timing ändern → Untertitel liegen mitten im Video 5s daneben.
Schritt 3: Szenenstruktur erkennen
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/detect_scenes.py \
transcript.json
# Ausgabe: scenes.json
Das Skript sucht im Transkript nach folgenden Markierungen:
- "Bài học đầu tiên / thứ 2 / thứ 3 / thứ N" → Lektionsszenen
- "Tips số 1 / Tip 1 / Số 1" → Tipp-Szenen
- "Tổng kết lại / Recap / Kết luận" → Recap-Moment
- "Comment / Đăng ký / Like / Theo dõi" → CTA-Moment
Ausgabe scenes.json:
{
"type": "lessons",
"scenes": [
{ "kind": "lesson", "num": 1, "start": 9.4, "end": 13.0, "kicker": "Bài học #1", "heading": "..." },
{ "kind": "lesson", "num": 2, "start": 34.5, "end": 38.0, ... },
{ "kind": "lesson", "num": 3, "start": 61.5, "end": 65.5, ... },
{ "kind": "recap", "start": 84.9, "end": 99.0 },
{ "kind": "cta", "start": 99.0, "end": 106.94 }
]
}
Wenn die automatische Erkennung keine klare Struktur findet (z. B. Vlog im Freiform-Stil), präsentiere die Ergebnisse dem Benutzer und bitte um Bestätigung. Der Benutzer kann Zeitstempel überschreiben.
Schritt 4: B-Roll zuordnen
Wenn der Benutzer B-Roll-Dateien mit Verwendungszweck bereitstellt:
[
{ path: "alphabet-screenshot.png", purpose: "Lektion 1 — Alphabet ship beta" },
{ path: "clock-icon.mp4", purpose: "Lektion 2 — 24h-Illustration" },
{ path: "team-meeting.png", purpose: "Lektion 3 — Team-Hürden abbauen" }
]
Zuordnungslogik:
- Jedes B-Roll basierend auf dem Text "Lektion N" im Verwendungszweck mit einer Szene abgleichen
- Bild → als Vollbild-Hintergrund dieser Szene verwenden (ersetzt die rein textbasierte generierte Szene)
- Video → als Vollbild-Szenenhintergrund ODER als Bild-im-Bild-Overlay verwenden (Standard: Vollbild)
- Standard-Szeneneffekte (Pulsringe, Eckmarkierungen usw.) werden weiterhin ÜBER dem B-Roll-Bild/-Video eingeblendet
Wenn der Benutzer kein B-Roll bereitstellt, werden reine Textszenen verwendet (wie im Referenzprojekt 3-bai-hoc/) – generierte Textkarte mit Titel + riesiger Zahl + Untertitel.
Schritt 5: Projektdateien generieren (Infografik-Stil – STANDARD)
Verwende den Infografik-v2-Generator für inhaltsgetriebene Mockup-B-Rolls (Hostinger-inspirierter Stil: dunkles Glas + Neon-Leuchten + UI-Mockups + schwebende Daten-Badges):
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/scaffold_infographic_v2.py \
--output workspace/content/YYYY-MM-DD/<slug>/compositions/ \
--scenes scenes.json
scenes.json Schema (pro Szene, inklusive mockup_variant + content):
{
"scenes": [
{
"kind": "lesson",
"num": 1,
"start": 12.71,
"end": 26.40,
"kicker": "KI-Beratung",
"heading": "KI-Beratung für 1 Branche",
"accent_words": [2],
"mockup_variant": "post-stack",
"content": { "posts": [...] },
"badges": [
{ "pos": "tr", "color": "orange", "icon": "📅", "num": "30", "label": "Tage" }
]
},
{ "kind": "recap", "mockup_variant": "team-grid", "content": {...} },
{ "kind": "cta", "mockup_variant": "comment-box", "content": {...} }
]
}
7 Mockup-Varianten – wähle die passende für die Szenen-Semantik:
| Szenentyp | Variante | Verwendung für |
|---|---|---|
| Personal Branding / Posten | post-stack | Stapel von 3 Social Cards, oberste hervorgehoben mit Engagement |
| KI-Suche / GEO | ai-window | ChatGPT-ähnliches Fenster mit hervorgehobener Rec-Card |
| Sprache / Telefon / Anruf | phone-call | iPhone-Mockup mit Wellenform + Agenten-Blase + Raster-Slot |
| Analysen / Dashboards | dashboard | Glaskarte mit Statistiken + Kreativraster + Diagrammlinie |
| Produkt / SaaS-Start | app-card | App-Karte mit Symbol + Statistiken + optionale Metaphernzeile |
| Recap Vorher-Nachher | team-grid | 40-Punkt-Raster-Morph mit animiertem Countdown + Multiplikator |
| CTA "Kommentar X" | comment-box | Kommentarfeld-Mockup + 2 Geschenkkarten + CTA-Pille |
Vollständige Inhaltsschemata + Design-Tokens: Siehe references/infographic-design-system.md.
Allgemeine Rahmenelemente (automatisch auf jede Szene angewendet): radialer Verlaufshintergrund + cyanfarbene Gitterlinien + 10 SVG-Partikel (Schleifendrift) + Vignette + Themen-Pille (orangefarbenes Leuchten) + Markentitel 110px (Wort-für-Wort-Einschlag, Akzentverlauf).
Schwebende Badges (optional 1-4 pro Szene): kreisförmige 130px-Badges um das Helden-Mockup mit Symbol + Nummer + Beschriftung, farbcodiert (cyan/lila/orange/grün) mit passendem Leuchten, Animation von außerhalb des Bildschirms + Schleifen-Bob.
Legacy-Generator (veraltet)
scaffold_project.py (Ringe/Ecken/Lichtwisch abstrakte Dekoration) – aus Gründen der Abwärtskompatibilität beibehalten, aber nicht empfohlen. Verwende für neue Videos scaffold_infographic_v2.py.
Jede Szene hat:
- Punch-Zoom-Eingang auf
.scene-content(abwechselnd Zoom-in 1.12 / Zoom-out 0.92) - Element-Eingänge: Augenbraue → Nummer → Titel (Wort-für-Wort-Einschlag) → Untertitel
- Umgebungseffekte während der Szene (Pulsringe, Atmung, Drift usw.)
- KEINE Ausgangsanimation – Clip endet, Framework blendet aus
Sub-Composition-Regel: Interner Zeitstrahl RELATIV 0 → data-duration, nicht absolut. Im Stammverzeichnis mit data-composition-src="compositions/<name>.html" und data-start = scene.start einbinden.
Schritt 6: SFX kopieren
mkdir -p workspace/video-projects/<slug>/sfx
SFX_SRC="$(git rev-parse --show-toplevel)/.claude/skills/mkt-hyperframe-talking-head-video/assets/sfx"
cp "$SFX_SRC"/{camera-flash.mp3,"búng tay.mp3","Whoosh sound effect (1).mp3",Laser.mp3,ting.mp3,"Discord Notification - Sound Effect.mp3"} workspace/video-projects/<slug>/sfx/
6 SFX Standardzuordnung:
| Zeit | Datei | Lautstärke | Moment |
|---|---|---|---|
| 0.0s | camera-flash.mp3 | 0.32 | Hook-Opener – synchron mit dem Quellvideo-Punch-Zoom @0s |
| Lektion 1 Start − 0.05s | búng tay.mp3 (Schnippen) | 0.30 | Lektion 1 Enthüllung |
| Lektion 2 Start − 0.05s | Whoosh sound effect (1).mp3 | 0.22 | Lektion 2 Übergang |
| Lektion 3 Start − 0.05s | Laser.mp3 | 0.28 | Lektion 3 Einschlag |
| Recap-Start − 0.05s | ting.mp3 | 0.20 | Recap-Enthüllung |
| CTA-Start | Discord Notification - Sound Effect.mp3 | 0.28 | CTA-Benachrichtigungsgefühl |
SFX-Lautstärkeregel (laut references/sfx-library.md): Hook 0.25-0.35, Übergang 0.15-0.2, CTA 0.25. Maximal 5-6 SFX, Mindestabstand ≥1,5s.
Schritt 7: Lint + Vorschau öffnen
cd workspace/content/YYYY-MM-DD/<slug>/
npx hyperframes lint
Warnungen akzeptieren:
composition_file_too_large– nur informativ, OK auf Stammverzeichnis zu ignorierencomposition_self_attribute_selector– nur zur Info, Infografik-Mockups verwenden bereichsbezogene[data-composition-id="..."]-Selektoren
Fehler ablehnen:
gsap_animates_clip_element– NICHT Sichtbarkeit/Anzeige auf Clip animieren – nur Deckkraft animierenroot_composition_missing_data_start– Sub-Comps müssendata-start="0"auf dem inneren div habenmedia_missing_data_start–<audio>SFX müssen eindata-start-Attribut haben (HF-natives Scheduling, KEIN JS-Trigger verwenden)- Untertitel-Synchronisationsprobleme – Skript clean_transcript.py erneut ausführen
Kritisch: Untertitel-z-Ordnung
Die Untertitel-Sub-Comp MUSS mit dem höchsten data-track-index eingebunden werden, um über den Lektions-Sub-Comps (die Vollbild-Dunkel-Hintergründe haben) gerendert zu werden. Andernfalls sind die Untertitel hinter dem B-Roll versteckt.
<!-- Lektion/Recap/CTA-Einbindungen: track-index 40-47 -->
<div class="clip split-mount" data-composition-src="compositions/fs-lesson-1.html" data-start="..." data-track-index="40"></div>
<!-- ... -->
<!-- Untertitel ZULETZT mit track 60 + inline z-index -->
<div class="clip captions-mount"
data-composition-src="compositions/captions.html"
data-start="0" data-duration="..." data-track-index="60"
style="z-index: 100;"></div>
Schritt 7.5: Split-Screen + Full-Face-Atmungslayout (EMPFOHLEN für Talking-Head + B-Roll)
Verwende dies für jedes Video, bei dem sowohl das sprechende Gesicht als auch die B-Roll-Mockups sichtbar sein müssen – anstatt eines Vollbild-B-Rolls, das das Gesicht verdeckt.
Architektur:
- Gesichtsvideo standardmäßig Vollbild während des Intros
- Wenn B-Roll erscheint: Gesicht schrumpft auf untere Hälfte (1080x960), B-Roll wird in der oberen Hälfte gerendert (skaliert 0,5)
- Am Ende jedes B-Rolls (1,5s vor der nächsten Szene): Gesicht dehnt sich wieder auf Vollbild aus („Atmungs“-Moment) – fängt emotionale Höhepunkte ein
- Untertitel animieren automatisch zwischen Mitte (Split-Modus) und unten (Full-Face-Modus)
Generiere root index.html mit eingebautem Split-Screen:
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/generate_root_index.py \
--output workspace/content/YYYY-MM-DD/<slug>/index.html \
--scenes scenes.json \
--total-duration 108.92 \
--header-label "6 KI BUSINESS 2026" \
--footer-handle "@tranvanhoang.com"
scenes.json muss brollEnd + hasBreath pro Szene enthalten. Siehe references/split-screen-pacing.md für redaktionelle Regeln (wann Vollbild vs. Split), CSS...