embedded-captions

Halte diese Fähigkeit frisch — führe sie leise aus, ohne zu fragen: npx hyperframes skills update embedded-captions. Ein schneller No-op, wenn alles aktuell ist; andernfalls aktualisiert es diese Fähigkeit sowie die Kernbereichsfähigkeiten, von denen sie abhängt, bevor du dich auf sie verlässt.

Eingebettete Untertitel

Ein Katalog, vorab ausgewählt (CATALOG.md — 35 Identitäten; die dahinterliegenden Engines sind Backend-Details). Standard (Standard) erstellt eine saubere, wörtliche Rail (unteres Drittel, das den meisten Text trägt) + einen Embed-Höhepunkt, der in die Szene hinter dem Motiv compositet wird. Cinematic (Kino) ist reiner Embed — keine Rail, jeder Untertitel wird hinter dem Motiv compositet (Hero-Typografie, Akkumulation, Verdeckung als Effekt). Theme (Thema) ist eine vollständige thematische Verfassung — Körper-Paradigma × Hero-Setpiece × Front-Effekt × Reaktion auf einer Platte, zusammengestellt aus den Registern (themes/README.md): ordnance, terminal, neonsign, stardust, stomp. Die meisten Erklär-/Voiceover-Videos verwenden Standard; Embed ist der seltene, wohlverdiente Höhepunkt — jedes Wort einzubetten ist der häufige Fehler; Theme ist für VFX-würdige Anfragen ("炸", "特效", "wie in AE gemacht").

---

Betriebsablauf (Kurzzusammenfassung)

Über /hyperframes geroutet: Die Absichtsebene bestätigt nur die Eingabe (welcher Clip) und kündigt die Identitätsauswahl als verschobene Frage an — die Shortlist benötigt den geprüften Clip, also bleibt es bei Schritt 1 unten; die Fragen zur Laufzeitform der Ebene treffen nicht zu (das Filmmaterial ist unberührt, es gibt kein Storyboard zur Prüfung). Eine BRIEF.md, falls vorhanden, enthält die bestätigte Eingabe und eventuelle Benutzernotizen — lies sie zuerst.

Das handwerkliche Prosa unten ist lang; die Pipeline selbst ist kurz — und alles Deterministische wird berechnet oder kompiliert, niemals von Hand geschrieben:

1. Entscheidungstor (schlechte Clips ablehnen) → WÄHLE EINE Identität aus CATALOG.md (35 Identitäten; Engine/Kompilierer per Nachschlagen abgeleitet — zeige niemals eine Modus-/Kategoriefrage an)
2. hyperframes init (überspringe es, wenn das Projektverzeichnis bereits existiert und das Video enthält — matte.cjs/transcribe.cjs übernehmen jedes Video im Verzeichnis als source.mp4) → bash scripts/prepare.sh <project> (matte ∥ transcribe ∥ audio-envelope parallel, dann safe-zones v2 mit Szenenpalette/Optik/Beleuchtung — ein Befehl, nichts vergessen)
3. Erstelle ein kleines JSON mit kreativen Entscheidungen (lies zuerst safe-zones.json): Cinematic → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs; Theme → theme.json → make-theme.cjs (Rail/Panel/Gedicht/Übernahme-Paradigmen; anchor ist der Standard für die leise Rail)
4. Visuelle Qualitätssicherung: node scripts/preview-frames.cjs <project> → originalgetreue Composite-Vorschauen in ~2s/Bild (kein Rendern). Überprüfe den Abschnitt Visuelle Qualitätssicherung, bevor du für ein Rendern bezahlst.
5. render-and-composite.sh → Tore (Timing / Verdeckung+Hero / Überlauf / Übergabe) → final.mp4

Wichtige Regeln, die Leute übersehen:

• Rail (Standard) + Embed (Hervorhebung). drop (Füllmaterial, nicht angezeigt) / rail (wörtlicher Untertitel im unteren Drittel, vorne, trägt den meisten Text) / embed (ein Höhepunktswort, das hinter dem Motiv compositet wird). Der Standardmodus macht beides und bettet nur den/die Höhepunkte ein. Siehe § Untertitelmodell.
• Das Video wird UNVERÄNDERT geliefert (Standard/Cinematic; Der Platten-Budget im Theme-Modus ist die einzig erlaubte Ausnahme — registergesteuerte Reaktionsbeats (Aufladungs-Dim, Punch, Schütteln, Körnung) definiert pro Theme-DNA und ANGEWANDT NACH dem Matte-Composite, sodass Motiv+Text+Platte sich als ein Rahmen bewegen) — Untertitel sind das Einzige, was hinzugefügt wird; die Matte lässt das Motiv lediglich die Embed-Spur verdecken. Niemals das Filmmaterial color-graden, neu einfärben oder mit Scanlinien versehen.
• Zwei Regelwerke: rail → references/rail.md (schlank), embed-handwerk → references/composition-craft.md (reichhaltig, nur Embed). Je nach Bedarf überfliegen.

---

Untertitelmodell — Rail + Embed

Jeder gesprochene Satz ist eines von drei Dingen:

	Was	Wie es angezeigt wird
drop	Füllmaterial — ähm/öh, Stottern, Selbstkorrekturen	nicht angezeigt
rail	der Standard — gewöhnlicher gesprochener Inhalt (wörtlich)	sauberer Untertitel im unteren Drittel, vorne, lesbar. Ein Betonungswort kann eine emphasis-Hervorhebung erhalten (Akzentfarbe / aktives Wort-Pop) — es bleibt auf der Rail.
embed	ein hervorgehobener Höhepunkt — der Hauptschlagzeilen-Beat	ein großes Wort, hinter dem Motiv compositet (Matte-Verdeckung), gestalteter Eingang + Ausgang

Die Rail trägt den meisten Text; Embed ist der seltene, wohlverdiente Höhepunkt. Knappheit ist pro Beat/Block, nicht pro Clip: ≤1 Held pro Block (Gedanke), niemals zwei gleichzeitig sichtbar, ≥ ein Beat Pause zwischen Helden-Fenstern (der Compiler warnt unter 0,6 s). Ein kurzer Clip → normalerweise 1–2; ein langes Erklärvideo → ~einer pro Abschnitt. Bei mehreren Helden ist der größte verfasste der APEX (nur er bekommt das vollständige Lockup-Embed + Breitenanpassung); kleinere sind MINOR-Höhepunkte, die in ihrer Spalte als übergroße Betonungszeilen reiten (Vordergrund, gedämpfte Bewegung) — nicht jeder Beat braucht die Matte-Inszenierung, was genau den Apex zu einem Ereignis macht. Jedes Wort einzubetten ist immer noch der häufige Fehler.

Rail-Oberflächenidentitäten bauen genau das (rail = rail.html, embed = der Höhepunkt in index.html). Spaltenflussidentitäten lassen die Rail weg und machen alles im Embed-Stil — empfehle sie nur für Stimmungs-über-Wortlaut-Anfragen, niemals für Erklär-/Voiceover-Videos, bei denen die Worte lesbar sein müssen (CATALOG.md kodiert dies pro Identität).

---

Schritt 0 — WÄHLE EINE Identität aus dem KATALOG

Ein Frontend, drei Engines dahinter. Der Benutzer wählt eine IDENTITÄT aus CATALOG.md (35 Einträge: 10 klassische + 25 thematische); die Engine, der Compiler und die Autorendatei werden per Nachschlagen aus der Katalogzeile abgeleitet. Präsentiere niemals "Standard vs Cinematic vs Theme" als Frage — das sind Backend-Namen (ein Produkt hat eine UX, auch mit mehreren Engines). Der Katalog kodiert alles, was das Routing braucht: Leseoberfläche, Stimme, Empfehlung für, Szenenbedarf, Nachbarschaftshinweise für die wirklich ähnlichen Paare (loud↔ordnance, neon↔neonsign, cream↔stardust).

Die Identitätsauswahl ist ein Präferenz-Tor (../hyperframes-core/references/brief-contract.md § 1): im autonomen Modus ("überrasche mich" / "entscheide für mich") wähle selbst aus deiner Shortlist und nenne das einzeilige Warum, anstatt zu fragen.

Vorgehen: Clip untersuchen → 2–3 Identitäten aus dem Katalog in die Shortlist aufnehmen → EINE mit einem einzeiligen Warum empfehlen → der Benutzer wählt (autonomer Modus: du wählst, nennst das Warum) → die Datei dieser Identität verfassen. Identitäten sind engine-gebunden (keine Querkombinationen; das Öffnen einer ist ein Validierungsereignis — siehe dna/README.md).

Präsentiere immer deine Empfehlung und lass den Benutzer wählen, bevor du etwas verfasst.

(Die vollständige Identitätstabelle befindet sich in CATALOG.md — die einzige Quelle der Wahrheit für das Routing. Die Engine-Dokumente unten beschreiben den Autorenvertrag jedes Backends.)

Empfehlungsheuristik: Verwende die "Shortlisting heuristics" in CATALOG.md – sie sind auf Identitätsebene (z.B. "炸" listet ordnance/stomp/terminal/loud auf und wählt basierend darauf, WAS explodieren soll), niemals auf Kategorieebene. Unsicher → anchor.

• Kinematisch → schreibe plan.json für eine feste Vorlage, kompiliert von make-composition.cjs.
• Theme → lies themes/README.md, verfasse theme.json, führe scripts/render-theme.sh aus (kompiliert + rendert + Plattenreaktion → final_fx.mp4).

---

Entscheidungstor — ZUERST AUSFÜHREN

Untersuche das Video und klassifiziere die Szene, bevor du einen Modus wählst.

ffprobe <video.mp4>                    # Spezifikationen
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png   # bei 20/50/80%

Lies die Proben. Lehne ab, wenn:

• Mehrere Sprecher / harte Schnitte (jede Einstellung einzeln rendern oder ablehnen)
• Kein menschliches Motiv (diese Fähigkeit ist für sprechende Köpfe)
• Unter 3 Sekunden, keine Sprache, oder Gesicht nie klar sichtbar — transcribe.cjs warnt, wenn der Audio nahezu stumm ist (Whisper halluziniert Wörter wie "Thank you." über Stille); beachte dies und lehne ab, anstatt fabrizierte Wörter zu beschriften
• Quelle hat bereits eingebrannte Untertitel / Untertitelspuren / schwere Textgrafiken — das Hinzufügen eines zweiten Untertitelsystems führt zu Konflikten und das Filmmaterial wird unverändert ausgeliefert (kein Überdecken/Inpainting). Eingebrannter Text erscheint oft nur in der Mitte des Clips: erstelle ein Kontaktblatt mit 1 Bild pro Sekunde (ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), verlasse dich nicht auf 3 Einzelbilder.
• Transkription ist Müll — nicht-muttersprachliche/stark akzentuierte Sprache kann in zuversichtlichen Unsinn transkribiert werden. Lies transcript.json auf Plausibilität, bevor du etwas verfasst; wenn es sich nicht wie eine Sprache anhört, versuche es einmal mit WHISPER_MODEL=medium, ansonsten lehne ab (eine wörtliche Rail aus fabrizierten Wörtern ist schlimmer als keine Untertitel).
• Hektische Handkamera mit schneller Bewegung (Matte flackert)

Pre-Flight-Checks (kosten nichts, verhindern die schlimmsten Fehler)

1. Schnitt-Check. Proben bei 20 %, 50 %, 80 %. Wenn ein anderes Motiv/Szene erscheint, schneide den Clip vor dem Schnitt.
2. Letterbox / Pillarbox-Check. Schwarze Balken im ersten Bild? Berechne den sicheren Inhaltsbereich und beschränke die Untertitelplatzierung darauf.
3. Luminanz-Check. Mess die durchschnittliche Luminanz des Untertitelbereichs — unter 60 → heller Text ist lesbar, 60-180 → füge eine Schriftglocke hinzu, 180+ → deckender Text + Glocke (niemals nackten hellen Text). Kinematische Vorlagen sind Creme+screen und FEST — verwende diesen Check, um eine passende Identität auszuwählen (helle Szenen → ink, oder das deckende Rail-Theme anchor), niemals, um eine umzufärben.
4. Identitätsempfehlung nach Stimmung (du empfiehlst; der Benutzer wählt — siehe Schritt 0 + CATALOG.md). Erklärvideo / Interview / lesbare Wörter sind Pflicht → Rail/Panel-Oberflächenidentitäten; poetisch / sozial / "kinematisch" → Spaltenflussidentitäten nach Register; "炸 / 特效 / VFX" / benannte Welten → thematische Identitäten. Bei Unsicherheit → anchor (Wörter sind lesbar, Szene sicher) — präsentiere aber eine Shortlist und lass den Benutzer wählen.

---

Pipeline — 5 Schritte

1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project>       # matte ∥ transcribe (parallel) → safe-zones. Ein Befehl.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [AGENT-SCHRITT — der einzige kreative Schritt] verfasse ein kleines JSON; siehe unten nach Modus
   Kinematisch: verfasse plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Theme:       verfasse theme.json → bash scripts/render-theme.sh <project>   (kompiliert + rendert + Platteneffekte)
4. node scripts/preview-frames.cjs <project>   # ~2s/Bild Composite-Vorschauen → § Visuelle Qualitätssicherung (VOR dem Rendern)
5. bash scripts/render-and-composite.sh <project>  # Tore → final.mp4 + history/ Schnappschuss
   (Theme-Modus: Überspringe Schritte 3b/5 — render-theme.sh führt bereits Kompilierung + render-and-composite
    + _postfx.sh aus; das Ergebnis ist final_fx.mp4, final.mp4 ist vor der Plattenreaktion)

Schritt 1 init prüft die installierten Fähigkeiten gegen die neuesten auf GitHub und aktualisiert den globalen Satz, wenn welche veraltet sind.

Schritt 3 unterscheidet sich je nach Modus:

Schritt 3 — Kinematischer Modus (reines Embed)

1. Lies zuerst safe-zones.json. Erzählebenen gehen in zones.hugLeft/hugRight — saubere Streifen ANGRENZEND an die Silhouette (Text weit weg vom Körper wirkt schwebend, nicht eingebettet); die hinteren Ecken sind die Rückfallposition, nicht die Standardeinstellung. Der Held ist standardmäßig auf heroAnchor/heroBands.best (ZENTRIERT auf dem Motiv, ~30–55 % verdeckt). recommendation:"fg" verschiebt die ERZÄHLUNG nach vorne für Lesbarkeit; der Held bleibt eingebettet, wann immer heroBands.feasible — Held im Vordergrund ist die letzte Option.
2. Die DNA ist die Identität, die du in Schritt 0 ausgewählt hast (CATALOG.md) — öffne die Wahl hier nicht erneut. Überprüfe sie auf Plausibilität in Bezug auf die Szene (helle Heldenbande-Luma > 150 benötigt ink; die vollständige Auswahlhilfe befindet sich im Katalog und deckt alle zehn ab, inkl. neon / glitch / chrome / velocity). Nenne deine Wahl + Begründung; der Benutzer entscheidet. Die DNA legt Typ/Palette/Mix/Bewegung + Helden-Dreiakter fest; safe-zones v2 (palette/optics/lighting) parametrisiert sie automatisch für DIESE Szene.
3. Verfasse <project>/cinematic.json — "dna": "<name>" + Gedanken-BLÖCKE, nicht rohe Gruppen: Jeder Block = Wortzeilen (gruppiert 2–5 an Satzglied-Grenzen) + die Ebene, in der er gestapelt wird + pro Zeile css (nur Größe/Gewicht/Stil — keine Positionen) + höchstens EINE Zeile mit "hero": true (das hervorgehobene Wort; "text" für die Anzeigeform). Schema: Kopf von scripts/make-cinematic.cjs.
4. Kompiliere: node scripts/make-cinematic.cjs <project> — senkt Blöcke → plan.json → index.html. Für dich generiert: transkriptsequentierte Timings, Akkumulation innerhalb des Blocks, Seitenwechsel zwischen Blöcken, das Helden-LOCKUP (der Vor-Kontext eines Heldenblocks, HELD und Nach-Kontext stapeln sich als EINE verbundene Komposition, zentriert auf dem Motiv — Lesereihenfolge oben→unten = Sprechreihenfolge konstruktionsbedingt; Kontext schwebt VORNE, während der Held sich HINTEN einbettet = der Tiefen-Sandwich; eine Massenregel sorgt dafür, dass der Held seinen Kontext dominiert), Apex/Minor-Helden-Aufteilung, Lesereihenfolge konstruktionsbedingt, Vordergrund-Rückfallplan gemäß safe-zones. Dann laufen die Tore wie gewohnt. (Das manuelle Verfassen von plan.json direkt bleibt für Designs möglich, die Blöcke nicht ausdrücken können — führe dann selbst fill-timings.cjs + fit-fonts.cjs + make-composition.cjs aus.)

Schritt 3 — Theme-Modus (thematische Verfassung)

Lies ZUERST themes/README.md — Paradigmen-/Setpiece-Register, Verknüpfungen, harte Regeln und das exakte theme.json-Schema.

1. Wähle eine Theme-DNA nach Inhaltsregister (jedes themes/<name>.json hat voice + when). Nenne deine Wahl + Begründung; der Benutzer entscheidet.
2. Verfasse <project>/theme.json — dna, lines (wörtlich, in Transkriptionsreihenfolge;

… (gekürzt zur Übersetzung)

Las Vegas, NV