anton-abyzov/vskill

/hyperframes-best-practices

Verwenden Sie dieses Skill immer dann, wenn Sie eine rohe Bildschirmaufnahme, ein Talking-Head-Video oder einen OBS-Export in ein poliertes HyperFrames-Produktvideo verwandeln. Es bündelt zwei Ebenen von Wissen:

1. HyperFrames-Grundlagen — die offiziellen Regelwerke von HeyGen unter github.com/heygen-com/hyperframes (Kompositionserstellung, GSAP-Timelines, data-*-Attribute, die dev-loop-CLI). Installation via npx vskill i heygen-com/hyperframes.
2. Produktionshandwerks-Regeln — Erkenntnisse aus einem langen Iterationszyklus beim Bau eines echten SpecWeave-Produktvideos aus einer einzigen 8:47-OBS-Aufnahme. Dies sind die Regeln, deren Befolgung ein versandbereites Video liefert und deren Missachtung zu Pieptönen, mitten im Wort abgeschnittenen Clips, leeren Übernahmeszenen und Overlays führt, die die Gesichtskamera des Sprechers blockieren.

Lesen Sie beide Ebenen, bevor Sie mit der Arbeit beginnen.

---

Geltungsbereich und Anwendbarkeit

Die Layer-2-Handwerksregeln unten wurden aus einem spezifischen Projekt abgeleitet: der Umwandlung einer 8:47 SpecWeave-Intro-Aufnahme (Anton Abyzov, OBS-Aufnahme, Talking-Head + Screen-Share, Mai 2026) in ein 6:00-minütiges, produktionsreifes Promo-Video. Sie spiegeln das Erscheinungsbild dieses Produkts wider — die getönten Karten-Ästhetik von Studio, die lila/grüne Farbpalette von SpecWeave, ein iOS-Karten-Overlay-Stil und die technischen Realitäten von OBS-Aufnahmen (Start/Stopp-Ticks, Wiederaufnahme-Transienten, doppelte Takes durch dreimaliges Neuaufnehmen derselben Zeile).

Die genauen Konstanten sind projektspezifisch — Overlay-Positionen für den Standort der Gesichtskamera, der Korrekturtext Boris Cherny / Anthropic, die 600+/500+/3K+-Statistiken — übersetzen Sie, kopieren Sie nicht.

Verwenden Sie diese Ebene als Referenz für die zugrunde liegende Technik: den transkriptionsgesteuerten Smart-Cut-Algorithmus, das Einblenden pro Clip zur Unterdrückung von Transienten, die concat-Filter-Render-Pipeline, die Klicks des concat-Demuxers vermeidet, die chirurgische Stummschaltung von Pieptönen, das iOS-Karten-Overlay-Muster, die Quellzeit → Schnittzeit-Zuordnung, die Studio-Wellenform-Cache-Invalidierungsfalle — diese verallgemeinern sich.

---

Wann verwenden

Lösen Sie dieses Skill aus, wenn EINES der folgenden Kriterien zutrifft:

• Ein Benutzer hat eine rohe Bildschirmaufnahme oder OBS-Aufnahme und möchte ein gestrafftes, mit Untertiteln versehenes, gebrandetes Video.
• Die Quelle enthält tote Luft, Pausen oder doppelte "lass mich das nochmal versuchen"-Takes.
• Die Quelle enthält Klicks, Pieptöne oder transiente Artefakte an Aufnahmegrenzen.
• Der Benutzer möchte grafische Overlays (Callouts, Statistik-Karten, Enthüllungen von Marken, Tool-Logos), die die Gesichtskamera des Sprechers nicht verdecken.
• Der Benutzer sagte die Worte "machen Sie das produktionsreif" oder "bereit zum Versand".
• Der Benutzer erwähnte den Wunsch nach "Apple-Keynote-Stil" oder "iOS-Hover-Karten" oder "Milchglas".

Wenn IRGENDEINES dieser Signale vorhanden ist, folgen Sie diesem Workflow. Wenn der Benutzer nur eine schnelle Titelgrafiken auf einer sauberen Quelle möchte, reicht das reine hyperframes-Skill aus.

---

Die Pipeline (10 Phasen)

┌──────────────────────────────────────────────────────────────────┐
│  Phase 0  Tools inventarisieren                                  │
│  Phase 1  Quelle untersuchen (Dauer, Codec, Audio-Samplerate)    │
│  Phase 2  Mit Whisper transkribieren (Wortgenaue Zeitstempel)    │
│  Phase 3  Stille + Szenenwechsel erkennen                        │
│  Phase 4  Die Smart-Cut-Liste erstellen (mit Wortgrenzen-Puffern)│
│  Phase 5  Transiente Pieptöne entfernen (chir. Stummschaltung)   │
│  Phase 6  Den Master via concat-Filter rendern (ein Durchlauf)   │
│  Phase 7  Hero-Bildmaterial generieren (Gemini 3 Pro Image)     │
│  Phase 8  Die HyperFrames-Komposition erstellen (iOS-Karten)    │
│  Phase 9  In Studio linten + verifizieren                        │
└──────────────────────────────────────────────────────────────────┘

Führen Sie die Phasen nacheinander aus. Iterieren Sie innerhalb einer Phase, nicht phasenübergreifend — eine schlechte Schnittliste zerstört jedes nachgelagerte Overlay-Timing, und Sie verbringen eine Stunde damit, Anker neu aufzulösen. Holen Sie zuerst die Schnittliste richtig hin, rendern Sie dann einmal, und bauen Sie dann Overlays gegen die endgültige Zeitleiste auf.

---

Phase 0 — Tools inventarisieren

Stellen Sie vor dem Start sicher, dass diese verfügbar sind. Das Skill setzt macOS / Linux voraus; unter Windows verwenden Sie WSL.

Tool	Verwendung	Installation
ffmpeg (>= 6.0)	Gesamte Video-/Audioverarbeitung	brew install ffmpeg
ffprobe	Stream-Inspektion	im Lieferumfang von ffmpeg enthalten
whisper (OpenAI Python-Paket)	Transkription mit Wortzeitstempeln	pip install openai-whisper
python3	Skripte für Schnittliste / Piepton-Entferner	System
npx hyperframes@latest	Kompositions-CLI (Vorschau, Rendern, Linten)	npx hyperframes init <projekt>
Gemini 3 Pro Image API	Hero-Bilder (optional)	GEMINI_API_KEY-Umgebungsvariable
vskill (>= 1.0)	Skill-Installation	npm i -g vskill

Wenn Whisper nicht installiert ist, holt pip install openai-whisper es nach. Verwenden Sie NICHT large-v3 oder large-v3-turbo auf der CPU — sie brauchen 10–15 Minuten für 8 Minuten Audio. Verwenden Sie base.en für englischen Technik-Monolog: ~30s, für Wortgrenzen völlig ausreichend.

Wenn auf dem Rechner eines Benutzers auto-editor installiert ist, ignorieren Sie es — es macht zwar Stille-Schnitte, aber keine Piepton-Entfernung oder Wortgrenzen-Pufferung, und es erzeugt abgehackte Schnitte mit über 50 Segmenten. Wir machen das von Hand besser.

---

Phase 1 — Quelle untersuchen

Bevor Sie etwas anderes tun, lernen Sie die Form der Datei kennen:

ffprobe -v error -show_entries stream=index,codec_type,codec_name,width,height,r_frame_rate,duration,sample_rate,channels \
  -show_entries format=duration,size,bit_rate -of json "$SRC" | tee source_meta.json

Dinge, die Sie wissen müssen:

• Gesamtdauer — treibt alle Schnittberechnungen an.
• Bildrate — OBS nimmt oft mit 60 fps auf; HyperFrames Studio spielt intern mit 30 fps für das Scrubbing ab. Multiplizieren Sie Sekunden × 30, um Studio-Framenummern zu erhalten, nicht Sekunden × Quell-fps. Das bringt Leute durcheinander.
• Audio-Codec & Samplerate — OBS nimmt üblicherweise pcm_s24le bei 48 kHz auf. Kodieren Sie für die Auslieferung in AAC 192k um; behalten Sie 48 kHz bei, um mit allen nachgelagerten Tools kompatibel zu sein.
• Container — .mov von DaVinci, .mkv von OBS — beides in Ordnung, ffmpeg liest beide.

Speichern Sie die Untersuchung auf der Festplatte, damit spätere Phasen sie erneut lesen können, ohne erneut zu untersuchen.

---

Phase 2 — Mit Whisper transkribieren

Wortgenaue Zeitstempel sind die Grundlage. Ohne sie können Sie nicht:

• Schnittgrenzen an Wortkanten ausrichten (Mitten-im-Wort-Clipping vermeiden).
• Doppelte Takes erkennen (dieselbe Zeile 2-3 Mal gesagt).
• Overlay-Anker gegen Sprachmomente setzen, anstatt gegen Schnittzeiten, die abdriften.

Extrahieren Sie zuerst das Audio, damit Whisper eine saubere mono 16 kHz WAV erhält (spart 80% CPU im Vergleich zur vollen Qualität):

mkdir -p .work
ffmpeg -hide_banner -y -i "$SRC" -vn -ac 1 -ar 16000 -c:a pcm_s16le .work/source.wav

Führen Sie Whisper mit Wortzeitstempeln und JSON-Ausgabe aus:

whisper .work/source.wav \
  --model base.en \
  --language en \
  --word_timestamps True \
  --output_dir .work \
  --output_format json \
  --verbose False

⚠️ Whisper-CLI-Falle: Die Übergabe von --output_format json --output_format srt behält in älteren Versionen nur das letzte Flag. Wenn Sie mehrere benötigen, verwenden Sie --output_format all (schreibt JSON + SRT + VTT + TSV + TXT).

Validieren Sie die Ausgabe: .work/source.json sollte segments[].words[] mit start, end, word enthalten. Wenn words leer ist, haben Sie --word_timestamps True vergessen.

Lesen Sie das vollständige Transkript zu diesem Zeitpunkt. Überspringen Sie es nicht. Sie werden Folgendes entdecken:

• Falsch gehörte Markennamen. Whisper hört "Claude Code at Anthropic" in 90% der Fälle als "Cloud Code at Infropic". "SpecWeave" wird zu "spec with" oder "specs". Diese benötigen Overlay-Korrekturen, keine Neuaufnahme.
• Doppelte Takes. Suchen Sie nach demselben Satz, der wörtlich wiederholt wird. In unserem Projekt kam "And those systems cannot produce skills as you work" dreimal vor (bei 01:14, 01:30, 01:47). Lassen Sie zwei davon weg.
• Füll-Neustarts. Einzelne Wortfragmente wie "And…", "And…" vor dem eigentlichen Satz. Das Schnittskript erkennt diese als "Geister"-Segmente — wir lassen sie in Phase 4 weg.

---

Phase 3 — Stille und Szenenwechsel erkennen

Zwei parallele Erkennungen speisen den Schnittalgorithmus:

3a. Stille-Erkennung

ffmpeg -hide_banner -nostats -i "$SRC" -af "silencedetect=noise=-30dB:duration=1.2" -f null - 2>&1 \
  | grep -E "silence_(start|end)"

-30 dB und 1.2s sind der Sweet Spot. Großzügiger (-25 dB, 0.8s) erfasst Atempausen, die Sie nicht schneiden wollen. Strenger (-35 dB, 2s) übersieht echte tote Luft.

Parsen Sie Start/Ende-Paare in [(s, e, dur), ...] und schreiben Sie sie in silences.json. Siehe scripts/build_cuts.py.

3b. Szenenwechsel-Erkennung

ffmpeg -hide_banner -nostats -i "$SRC" -filter:v "select='gt(scene,0.05)',showinfo" -f null - 2>&1 \
  | grep "showinfo" | grep -oE "pts_time:[0-9. ]+" | sed 's/pts_time://' > scenes.txt

scene>0.05 ist empfindlich genug, um zu erfassen, wenn der Sprecher einen neuen Browser-Tab öffnet, die App wechselt oder signifikant scrollt. Gehen Sie nicht unter 0.03 — Sie erhalten Fehlalarme durch Cursor-Blinken.

Diese beiden zusammen ermöglichen die Smart-Cut-Entscheidung: Stille + kein Szenenwechsel = reine tote Luft, schneiden. Stille + Szenenwechsel = der Sprecher zeigt etwas auf dem Bildschirm, behalten (das Publikum soll auf den Bildschirm schauen, nicht der Erzählung zuhören).

---

Phase 4 — Die Smart-Cut-Liste erstellen

Der Schnittalgorithmus hat 5 harte Regeln, die auf schmerzhafte Weise verdient wurden:

Regel 1 — Reine tote Luft wird geschnitten, aber nicht vollständig

Für jedes stille Segment > MIN_CUT_LEN (1,5s) ohne Szenenwechsel darin: schneiden Sie alles außer einem BREATH von 0,30s. Der Atem bewahrt den natürlichen Rhythmus — die vollständige Eliminierung von Stille lässt Sprache maschinell bearbeitet klingen.

if not in_scenes and (cut_end - cut_start) > MIN_CUT_LEN:
    cuts.append((cut_start + 0.30, cut_end, f"tote Luft {dur:.1f}s"))

Regel 2 — Stille mit Bildschirmaktivität bleibt (begrenzt auf 3,5s)

Wenn die Stille Szenenwechsel enthält, lässt der Sprecher das Publikum lesen. Behalten Sie das Fenster von first_scene - 0.4s bis last_scene + 0.8s, aber nie länger als 3,5s — das Starren auf ein einziges Bild länger als 3,5s verliert die Zuschauer.

Regel 3 — An Wortgrenzen ausrichten

Nach der Berechnung der groben zu behaltenden Bereiche richten Sie jede Grenze an der nächsten Wortkante von Whisper aus, innerhalb einer Toleranz von 0,4s:

def snap(t, words):
    best, bd = t, 0.4
    for s, e, _ in words:
        for cand in (s, e):
            if abs(cand - t) < bd:
                best, bd = cand, abs(cand - t)
    return best

Dadurch wird verhindert, dass Schnitte mitten im Wort kappen. Ohne dies kappt jeder zweite Schnitt ein nachlaufendes 's' oder einen Atemkonsonanten.

Regel 4 — Wortgrenzen-Puffer hinzufügen (das fällt den Nutzern auf)

Selbst mit Ausrichtung an Wortkanten erstrecken sich nachlaufende Konsonanten etwas über den von Whisper gemeldeten Wortende-Zeitstempel hinaus. Whisper timet den Vokaleinsatz bis zum Vokalende, nicht den Konsonantenschwanz. Ein direkter Schnitt bei word.end kappt also das nachlaufende 's', den Atem oder das 'k'.

Die Lösung: Erweitern Sie jeden zu behaltenden Bereich:

• Ende: + 0,30s über das Ende des letzten Wortes hinaus, begrenzt auf die Hälfte der Lücke zum nächsten zu behaltenden Bereich.
• Start: - 0,10s vor dem Start des ersten Wortes, begrenzt auf die Hälfte der Lücke zum vorherigen zu behaltenden Bereich.

END_BUF, START_BUF = 0.30, 0.10
for i, (s, e) in enumerate(keep):
    gap_next = keep[i+1][0] - e if i+1 < len(keep) else TOTAL - e
    gap_prev = s - keep[i-1][1] if i > 0 else s
    add_end   = min(END_BUF,   max(0, gap_next * 0.5))
    add_start = min(START_BUF, max(0, gap_prev * 0.5))
    if gap_next < 0.6: add_end   = max(add_end,   gap_next - 0.05)  # kleine Lücken fressen
    if gap_prev < 0.6: add_start = max(add_start, gap_prev - 0.05)
    final.append([s - add_start, e + add_end])

Das Ergebnis: Der Schnitt "find the tickets" erstreckt sich von src 08:09.26 bis 08:09.56 — das nachlaufende 's' überlebt. Ohne dies wird der Benutzer Ihnen sagen, das Audio "fühle sich gehetzt an" oder "verschlucke Endungen".

Regel 5 — Manuelle Entfernung doppelter Takes

Die programmatische Deduplizierung identischer n-Gramme ist fragil und gefährlich (sie kann legitime Wiederholungen entfernen). Lesen Sie stattdessen das Transkript, finden Sie wörtliche Duplikate selbst und fügen Sie explizite Drop-Bereiche in Quellzeit hinzu:

DUP_RANGES = [
    (78.86, 113.82),   # 01:18.86 - 01:53.82: 2 von 3 Takes von "skills as you work"
]
for ds, de in DUP_RANGES:
    # jeden überlappenden Behalte-Bereich zuschneiden
    ...

Reduziert den Schnitt von 35% gespart auf 32% gespart (die Duplikate sind stille Lücken + Sprache), aber das Ergebnis liest sich sauber.

Ausgabe

Das Skript schreibt:

• cuts.json — Behalte-Bereiche + Schnittbereiche + Zusammenfassungsstatistiken + Quellzeit-Zuordnung (wird von Phase 8 für Overlay-Anker verwendet).
• edl.txt — menschenlesbare EDL mit Transkript-Ausschnitten pro Behalte-Bereich (überprüfen Sie diese mit einem Blick vor dem Rendern).

Siehe scripts/build_cuts.py für die vollständige Implementierung.

---

Phase 5 — Transiente Pieptöne entfernen

OBS-Aufnahmen enthalten oft kurze transiente Artefakte — Boot-Pieptöne, Tastenschaltklicks, Mikrofon-Plosive, die auf einen heißen Eingang treffen. Diese überleben die Stille-Schnitt-Entscheidungen, weil sie laut sind (die Stille-Erkennung ignoriert sie daher) und von Stille umgeben sind. Sie klingen wie ein "Tick" im endgültigen Video bei 4:11 oder 0:52 oder wo auch immer.

Versuchen Sie nicht, dies mit einem globalen Noise Gate oder De-Noiser zu beheben. Sie werden Konsonanten verschmieren und Sprache unter Wasser klingen lassen. Erkennen Sie stattdessen Transienten und schalten Sie jedes 60–100ms-Fenster chirurgisch stumm.

Erkennungsalgorithmus (der Sprache nicht stumm schaltet)

Ein Transient ist genau dann ein "Piepton", wenn:

RMS(window 5ms)  > BEEP_RMS_MIN     (z. B. > 800)
RMS(preceding 150ms) < PRE_QUIET    (z. B. < 200)
RMS(following 200ms) < POST_QUIET   (z. B. < 350)

Die dritte Bedingung ist kritisch. Ohne sie würden Sie Konsonanteneinsätze ('p', 't', 'k') von Sprache erwischen, weil sie in den ersten 5ms identisch aussehen — aber Sprache wird von einem anhaltenden Vokal gefolgt, während ein Piepton zur Stille zurückkehrt. Filtern Sie mit post_avg < 350 und Sie schalten nur isolierte Transienten stumm.

Begrenzen Sie die stummgeschaltete Spanne außerdem auf 0,30s — eine Fehlklassifikation kann niemals ein ganzes Wort auslöschen.

Wenden Sie die chirurgischen Stummschaltungen an

Erstellen Sie einen ffmpeg-volume-Filterausdruck mit den Zielbereichen:

volume=enable='between(t,52.110,52.180)+between(t,169.850,169.920)+between(t,251.245,251.325)+...':volume=0

Dies wendet Null-Verstärkung während jedes 60–100ms-Piepton-Fensters an. Der Rest der Audios ist völlig unberührt.

Wann Sie stattdessen adeclick verwenden sollten

FFmpeg hat einen eingebauten adeclick-Filter, der Klicks erkennt und interpoliert. Er ist nützlich für analoge Aufnahmeklicks (wie Plattenspieler-Pops oder Kabelrauschen), aber nicht für OBS-Transienten. Wenn Sie ihn dennoch verwenden möchten:

ffmpeg -i input.wav -af "adeclick=w=60:t=2:m=10" output.wav

⚠️ adeclick klingt bei Sprache oft dumpf. Verwenden Sie ihn nur, wenn die chirurgische Stummschaltung fehlschlägt (z. B. bei einem 500-ms-Kabelbrummen, das zu lang für eine Stummschaltung ist).

Der vollständige Piepton-Entferner befindet sich in scripts/scrub_beeps.py.

---

Phase 6 — Den Master via concat-Filter rendern (ein Durchlauf)

Sobald die Schnittliste (cuts.json) final ist, rendern Sie die gesamte Sequenz in einem ffmpeg-Befehl. Verwenden Sie NICHT die concat-Demuxer-Methode (Dateiliste) — sie erzeugt Klicks an Übergängen zu 100%. Verwenden Sie den concat-Filter.

Warum concat-Filter? Warum nicht concat-Demuxer oder einzeln rendern und zusammenfügen?

Methode	Ergebnis	Grund
concat-Demuxer (Dateiliste)	❌ Klicks an jedem Übergang	Der Demuxer trimmt auf Keyframes und lässt Audio-Samples fallen, wodurch diskontinuierliche Wellenformen entstehen.
Einzeln rendern + concat-Filter	⚠️ Funktioniert, 2 Durchläufe	Sicher, aber Sie verschwenden einen vollständigen Kodierungsdurchlauf.
concat-Filter (ein Durchlauf)	✅ Sauber, am schnellsten	ffmpeg fügt innerhalb des Filters zusammen, bevor das Audio erneut kodiert wird — kein Abfallen von Samples.

Der Befehl

FILTER=""
SEG_NUM=0
for ((i=0; i<${#SEGMENTS[@]}; i++)); do
    s=${SEGMENTS[$i]} e=${ENDS[$i]}
    if [ "$SEG_NUM" -gt 0 ]; then FILTER+=";"; fi
    FILTER+="[${SEG_NUM}:0] [${SEG_NUM}:1]"
    SEG_NUM=$((SEG_NUM+1))
done
FILTER+=" concat=n=${SEG_NUM}:v=1:a=1 [v] [a]"

Vollständige Implementierung in scripts/render_master.sh.

Das Ergebnis ist eine saubere master.mp4 ohne Klick, ohne Lücke. Diese Datei ist Ihr endgültiger geschnittener Schnitt — sie enthält noch keine HyperFrames-Overlays, keine Hero-Bilder, keine Markierungen. Sie ist das Fundament.

---

Phase 7 — Hero-Bildmaterial generieren (Gemini 3 Pro Image)

HyperFrames-Keynote-Übernahmen und Szenenwechsel brauchen hochwertige Hero-Bilder. Hängen Sie sie nicht auf Screenshots aus dem Quellvideo — die sind in der Regel matschig, haben zufällige Cursorpositionen und spiegeln nicht das Branding wider.

Generativer Prompt-Ansatz

Erstellen Sie für jede Übernahme einen Prompt, der das Branding, die Stimmung ("professionell", "zukunftsweisend", "sauber") und die visuelle Komposition ("Apple-Keynote-Stil, dunkler Hintergrund, hellgrüne/violette Akzente, Glas-Karte") beschreibt. Dieser Prompt-Ansatz hat in unserem Projekt funktioniert:

Erstellen Sie ein Hero-Bild im Apple-Keynote-Stil. 
Dunkler Hintergrund. Großer, fetter Text: "KI-Agenten, die mit Ihnen arbeiten". 
Violette und hellgrüne Akzente. Milchglas-Karte im Vordergrund mit ...

Verwendung von Gemini 3 Pro Image

# API-Schlüssel festlegen (oder in .env)
export GEMINI_API_KEY="..."

# Bild generieren
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Erstellen Sie ein Hero-Bild für eine Keynote-Übernahme: ..."}]
    }]
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 -d > .work/hero_1.png

Speichern Sie die Prompts in einer Datei, damit Sie sie bei Bedarf neu generieren können, ohne jedes Mal den API-Aufruf zu wiederholen.

---

Phase 8 — Die HyperFrames-Komposition erstellen (iOS-Karten)

Jetzt kommt der polierte Look: eine Schicht von durchscheinenden "iOS-Stil"-Karten, die auf dem Vollbild-Video schweben. Das Muster stammt aus HyperFrames Studio und SpecWeave (einem beliebigen Tool-Ökosystem).

Das iOS-Kartenmuster

<div class="card ios-card" data-hf-type="overlay" data-hf-position="bottom-right" data-hf-anchor="cut-time(42.0)">
  <div class="card-content">
    <div class="card-title">Spezifikationen → Skills</div>
    <div class="card-subtitle">In Minuten, nicht Wochen</div>
    <div class="card-stats">
      <span class="stat-highlight">600+</span> Spezifikationen
      <span class="stat-highlight">500+</span> generierte Skills
      <span class="stat-highlight">3K+</span> Stunden eingespart
    </div>
  </div>
</div>

Styling (Milchglas-Effekt)

.ios-card {
  background: rgba(255, 255, 255, 0.15);
  backdrop-filter: blur(20px);
  -webkit-backdrop-filter: blur(20px);
  border: 1px solid rgba(255, 255, 255, 0.25);
  border-radius: 20px;
  padding: 24px;
  width: 340px;
  color: white;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
}

Positionierung (Gesichtskamera vermeiden)

Die größte Fallstrick: decken Sie die Gesichtskamera des Sprechers nicht zu. Wenn die Kamera unten-links ist, sind Karten unten-rechts (oder oben-rechts, oder oben-links). Verwenden Sie data-hf-position mit bottom-right, bottom-left, top-right, top-left. Testen Sie die Position, indem Sie eine Vorschau mit Standbild aus Phase 6 erstellen.

GSAP-Animation (Apple-Keynote-Stil)

gsap.from(".card", {
  opacity: 0,
  y: 40,
  scale: 0.95,
  duration: 0.6,
  ease: "power3.out",
  stagger: 0.1,
  scrollTrigger: {
    trigger: ".card",
    start: "top 80%",
  }
});

Anchoring in Schnittzeit

HyperFrames-Overlay-Anker verwenden standardmäßig Videospuren-Quellzeit. Da wir geschnitten haben (Phase 6), ist das Video kürzer als die Quelle. Sie müssen Anker in Schnittzeit statt in Quellzeit setzen.

Die cuts.json aus Phase 4 enthält eine time_map, die Quellzeit → Schnittzeit abbildet:

{
  "time_map": [
    {"in": 0.000, "out": 120.500, "map_to": 0.000},
    {"in": 121.800, "out": 200.000, "map_to": 119.800}
  ]
}

Verwenden Sie diese Abbildung, um data-hf-anchor-Werte zu berechnen. Wenn eine Textzeile bei Quellzeit 53.0s erscheint, verwenden Sie die gemappte Schnittzeit für die Overlay-Positionierung.

---

Phase 9 — In Studio linten + verifizieren

HyperFrames Studio hat ein eingebautes Lint-Tool. Führen Sie es aus, bevor Sie exportieren.

npx hyperframes lint

Bekannte Studio-Fallstricke

1. Wellenform-Cache wird nach Code-Änderungen nicht ungültig. Studio speichert Audiodateien im Browser-Cache. Wenn Sie data-hf-trim oder data-hf-anchor ändern, müssen Sie den Cache leeren: ⌘+Shift+R (Mac) / Ctrl+Shift+R (Windows). Sonst sehen Sie alte Wellenformen mit falschem Timing.
2. Overlay-Reihenfolge ist z-index-basiert. Spätere Karten im HTML überlagern frühere. Wenn eine Karte hinter der Gesichtskamera verschwindet, verschieben Sie sie im HTML nach oben.
3. Hero-Übernahmen brauchen ein img-Tag mit absoluter Positionierung. Wenn Sie sehen, dass der Hintergrund schwarz ist, fehlt das Bild oder der Pfad ist falsch. Überprüfen Sie src.
4. data-hf-anchor verwendet Standard-Sekunden, keine Frames. 42.0 = 42s, nicht Frame 42. Das ist anders als die Studio-Framenummer (30fps).

Checkliste für die endgültige Überprüfung

• Alle Sprache ist hörbar, kein Mitten-im-Wort-Clipping.
• Keine Pieptöne, Klicks oder Transienten hörbar.
• Alle Karten-Overlays verdecken die Gesichtskamera nicht.
• Hero-Übernahmen laden und haben den beabsichtigten Text.
• GSAP-Animationen laufen flüssig (kein Ruckeln durch eingebettete große Bilder).
• Untertitel (falls verwendet) sind synchron und fehlerfrei (korrigieren Sie Whisper-Fehler von Hand).
• Endgültige Dauer ist innerhalb von ±5s der Zieldauer (unser Projekt: 6:00 Ziel, 6:02 tatsächlich).
• Exportieren als MP4 (H.264, AAC 192k, 30fps).

---

Referenz-Skripte

Alle Skripte befinden sich im scripts/-Verzeichnis dieses Repos. Führen Sie sie mit Python 3.10+ / Bash 5+ aus.

Skript	Eingabe	Ausgabe
scripts/build_cuts.py	.work/source.json (Whisper), .work/silences.json, .work/scenes.txt	cuts.json, edl.txt
scripts/scrub_beeps.py	.work/source.wav	.work/scrubbed.wav, .work/beeps.json
scripts/render_master.sh	$SRC (Quelle), cuts.json	master.mp4
scripts/generate_heroes.sh	Prompt-Datei (hero_prompts.txt)	.work/hero_*.png

---

Abschlusscheck: Wann dieses Skill funktioniert und wann nicht

✅ Funktioniert gut für:

• OBS-Bildschirmaufnahmen (Talking-Head + Screen-Share)
• Loom- / Zoom-Aufnahmen mit Sprecher im Bild
• Rohmaterial mit ~20-40% toter Luft / Duplikaten
• Projekte, die eine Markenidentität benötigen (Farben, Logos, Karten)
• Videos mit Ziel-Zeitbeschränkung (5-8 Minuten endgültige Dauer)

❌ Nicht geeignet für:

• Hochgradig dynamische Videos (Gameplays, Live-Events — Szenenwechsel sind zu häufig)
• Videos mit mehreren Sprechern (Whisper mit base.en hat Probleme mit Überlappungen)
• Videos, die eine Farbkorrektur oder Grading benötigen (dieses Skill macht nur Schnitt + Overlays)
• Projekte, bei denen die Quelle bereits geschnitten und gefeint ist (das Skill ist für Rohmaterial)

---

Dieses Skill ist ein lebendes Dokument. Wenn Sie einen neuen Fallstrick oder eine Verbesserung finden, öffnen Sie ein Issue oder senden Sie eine PR an github.com/anton-abyzov/vskill.