embedded-captions

Plugin-Installationen: Führen Sie vor Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln aus, wenn sich dieses Skill innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen bleiben die folgenden Update-Anweisungen gültig.

Wichtig: Halten Sie dieses Skill auf dem neuesten Stand – bestätigen Sie mit dem Benutzer vor der Ausführung: npx hyperframes skills update embedded-captions. Eine schnelle No-Operation, wenn alles aktuell ist; andernfalls wird dieses Skill zusammen mit den abhängigen Kernbereichs-Skills aktualisiert, bevor Sie sich darauf verlassen.

Eingebettete Untertitel

Ein Katalog, von Anfang an ausgewählt (CATALOG.md – 35 Identitäten; die dahinterliegenden Engines sind Backend-Details). Standard (Standard) erstellt eine saubere, wörtliche Rail (untere Bildschirmleiste, die den Großteil des Textes trägt) + einen Embed-Höhepunkt, der am Höhepunkt in die Szene hinter das Motiv eingefügt wird. Cinematic ist reines Embed – keine Rail, jeder Untertitel wird hinter das Motiv eingefügt (Hero-Typografie, Akkumulation, Okklusion als Effekt). Theme ist eine vollständige thematische Verfassung – Körperparadigma × Hero-Setpiece × Front-Effekte × Tafelreaktion, zusammengesetzt aus Registern (themes/README.md): ordnance terminal neonsign stardust stomp. Die meisten Erklär-/Voiceover-Videos sind Standard; Embed ist der seltene, verdiente Höhepunkt – jedes Wort einzubetten ist der häufige Fehler; Theme ist für VFX-gradige Anfragen („炸“, „特效“, „wie in AE gemacht“).

---

Laufzeitvoraussetzungen

Plugin-Installationen verwenden die gebündelte, manifest-gesicherte CLI für Freistellung, Transkription und Rendering; kein Quellcode-Checkout erforderlich. Die lokalen Vorschau- und Untertitel-Messhilfsprogramme benötigen zusätzlich Sharp, Puppeteer (mit seinem Chromium-Browser) und GSAP. Installieren Sie diese im Untertitel-Projektverzeichnis, nicht innerhalb des schreibgeschützten Plugins:

npm install --prefix <project> --save-dev --save-exact [email protected] [email protected] [email protected]

Behalten Sie die Lock-Datei des Projekts bei. Wenn diese Abhängigkeiten bereits vorhanden sind, verwenden Sie deren gesperrte Versionen, anstatt sie zu überschreiben. Bash und FFmpeg/ffprobe müssen im PATH sein. Freistellung und Transkription laden möglicherweise beim ersten Gebrauch eigene Modelle herunter.

Das Rendering wartet auf den erfolgreichen Abschluss der CLI, bevor es mit dem Compositing beginnt. Der alte HF_TIMEOUT_S-Shell-Watchdog wird nicht mehr verwendet: Eine große partielle Datei ist kein Beweis dafür, dass das Rendering abgeschlossen wurde. Ein explizites Build-Checkout-Argument oder HYPERFRAMES_ROOT wählt die Beitrags-CLI anstelle des Plugin-Pins aus. Brechen Sie ein hängendes Rendering normal über die CLI/das Terminal ab; das Untertitel-Hilfsprogramm beendet oder stellt ein Rendering nicht gewaltsam aus einem Prozess-Snapshot wieder her.

Betriebsablauf (Kurzzusammenfassung)

Weitergeleitet über /hyperframes, bestätigt die Intentschicht nur die Eingabe (welcher Clip) und kündigt die Identitätsauswahl als aufgeschobene Anfrage an – die Shortlist benötigt den geprüften Clip, daher bleibt es bei Schritt 1 unten; die Lauf-Shape-Fragen der Schicht treffen nicht zu (das Filmmaterial ist unberührt, es gibt kein Storyboard zu prüfen). Eine BRIEF.md, falls vorhanden, enthält die bestätigte Eingabe und etwaige Benutzernotizen – lesen Sie diese zuerst.

Der folgende Handwerkstext ist lang; die Pipeline selbst ist kurz – und alles Deterministische wird berechnet oder kompiliert, niemals handschriftlich erstellt:

1. Entscheidungsschleuse (schlechte Clips ablehnen) → wählen Sie EINE Identität aus CATALOG.md (35 Identitäten; Engine/Compiler werden per Lookup abgeleitet – niemals eine Modus-/Kategoriefrage stellen)
2. hyperframes init (überspringen, wenn das Projektverzeichnis mit dem Video bereits existiert – matte.cjs/transcribe.cjs übernehmen jedes Video im Verzeichnis als source.mp4) → bash scripts/prepare.sh <project> (Matte ∥ Transkription ∥ Audio-Envelope parallel, dann Safe Zones v2 mit Szenenpalette/Optik/Beleuchtung – ein Befehl, nichts vergessen)
3. Erstellen Sie eine kleine JSON-Datei mit kreativen Entscheidungen (zuerst safe-zones.json lesen): Cinematic → cinematic.json → make-cinematic.cjs (leitet plan.json ab und kompiliert es); Theme → theme.json → make-theme.cjs (Rail/Panel/Gedicht/Übernahme-Paradigmen; anchor ist die ruhige Standard-Rail)
4. Visuelle Qualitätssicherung: node scripts/preview-frames.cjs <project> → originalgetue Composite-Vorschauen in ~2s/Frame (kein Rendern). § Visuelle Qualitätssicherung vor dem Bezahlen eines Renderings prüfen.
5. render-and-composite.sh → Prüfungen (Timing / Okklusion+Hero / Überlauf / Übergabe) → final.mp4

Tragende Regeln, die Leute übersehen:

• Rail (Standard) + Embed (Beförderung). drop (Füllmaterial, nicht gezeigt) / rail (wörtlicher unterer Bildschirmbereich, im Vordergrund, trägt den meisten Text) / embed (ein Höhepunkt-Wort, das hinter das Motiv eingefügt wird). Der Standardmodus macht beides, wobei nur der/die Höhepunkt(e) eingebettet werden. Siehe § Untertitel-Modell.
• Das Video wird UNVERÄNDERT geliefert (Standard/Cinematic; das PLATE-Budget des Themamodus ist die einzige genehmigte Ausnahme – registrierungsgesteuerte Reaktionsbeats (Aufladungs-Dim, Schlag, Wackeln, Körnung), die pro Themen-DNA definiert und NACH dem Matte-Composite angewendet werden, sodass Motiv+Text+Bewegungsplatte als ein Frame agieren) – Untertitel sind das Einzige, was hinzugefügt wird; die Matte lässt das Motiv lediglich die Embed-Spur verdecken. Niemals das Filmmaterial farblich korrigieren/nachfärben/abtasten.
• Zwei Regelwerke: Rail → references/rail.md (dünn), Embed-Handwerk → references/composition-craft.md (reichhaltig, nur Embed). Nach Bedarf überfliegen.

---

Untertitel-Modell – Rail + Embed

Jeder gesprochene Satz ist eine von drei Kategorien:

	Was	Wie es angezeigt wird
drop	Füllmaterial – ähm/äh, Stottern, Selbstkorrekturen	nicht angezeigt
rail	der Standard – gewöhnlicher gesprochener Inhalt (wörtlich)	sauberer unterer Bildschirmbereich, im Vordergrund, lesbar. Ein besonderes Wort kann eine eingebettete emphasis-Hervorhebung erhalten (Akzentfarbe / aktiver Wort-Pop) – es bleibt in der Rail.
embed	ein beförderter Höhepunkt – der Schlagzeilen-Beat	ein großes Wort, das hinter das Motiv eingefügt wird (Matte-Okklusion), entworfen mit Ein- und Ausgang

Die Rail trägt den Großteil des Textes; Embed ist der seltene, verdiente Höhepunkt. Knappheit ist pro Beat/Block, nicht pro Clip: ≤1 Hero pro Block (Gedanke), niemals zwei gleichzeitig sichtbar, ≥ ein Beat Pause zwischen Hero-Fenstern (der Compiler warnt unter 0,6s). Ein kurzer Clip → normalerweise 1–2; ein langes Erklärvideo → etwa eines pro Abschnitt. Bei mehreren Hero-Wörtern ist das größte erstellte der APEX (nur er erhält das vollständige Lockup-Embed + Breitenanpassungs-Anhebung); kleinere sind MINOR-Höhepunkte, die in ihrer Spalte als überdimensionierte Hervorhebungszeilen im Vordergrund fahren (gedämpfte Bewegung) – nicht jeder Beat braucht die Matte-Inszenierung, genau das macht den Apex zu einem Ereignis. Jedes Wort einzubetten ist immer noch der häufige Fehler.

Rail-Oberflächenidentitäten bauen genau dies auf (Rail = rail.html, Embed = der Höhepunkt in index.html). Spaltenfluss-Identitäten entfernen die Rail und lassen alles Embed-artig erscheinen – empfehlen Sie diese nur für stimmungsbetonte Anfragen, niemals für Erklär-/Voiceover-Videos, bei denen die Wörter lesbar sein müssen (CATALOG.md codiert dies pro Identität).

---

Schritt 0 – wählen Sie 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 Lookup aus der Katalogzeile abgeleitet. Stellen Sie niemals „Standard vs. Cinematic vs. Theme“ als Frage – das sind Backend-Namen (ein Produkt hat eine Benutzererfahrung, selbst mit mehreren Engines). Der Katalog codiert alles, was das Routing benötigt: Lesefläche, Stimme, Empfehlungsziel, Szenenanforderungen, Adjazenznotizen für die wirklich nahen Paare (loud↔ordnance, neon↔neonsign, cream↔stardust).

Die Identitätsauswahl ist ein Präferenz-Gate (../hyperframes/references/brief-contract.md § 1): Wählen Sie im autonomen Modus („überrasche mich“ / „entscheide für mich“) selbst aus Ihrer Shortlist aus und nennen Sie das einzeilige Warum, anstatt zu fragen.

Vorgehen: Clip prüfen → 2–3 Identitäten aus dem Katalog in die Shortlist aufnehmen → EINE mit einem einzeiligen Warum empfehlen → der Benutzer wählt aus (autonomer Modus: Sie wählen aus und nennen das Warum) → die Datei für diese Identität erstellen. Identitäten sind engine-gebunden (keine Querkombinationen; das Öffnen einer Identität ist ein Validierungsereignis – siehe dna/README.md).

Präsentieren Sie immer Ihre Empfehlung und lassen Sie den Benutzer vor dem Erstellen wählen. Gehen Sie nicht stillschweigend von der Standardeinstellung aus.

(Der vollständige Identitätstabelle befindet sich in CATALOG.md – die alleinige Wahrheitsquelle für das Routing. Die Engine-Dokumente unten beschreiben den Autorenvertrag jedes Backends.)

CATALOG.md ist hier der gesamte Antwortraum: Dieser Workflow durchsucht nicht das HyperFrames-Komponentenregister. Die Kompositions-Workflows führen vor dem Erstellen eines benannten Looks npx hyperframes catalog aus; dieser hier darf das nicht. Seine Engines sind gesperrte Compiler, die cinematic.json/theme.json konsumieren und die Komposition selbst ausgeben, sodass ein Registereintrag – einschließlich der caption-*-Blöcke – nichts hat, worin er eingebunden werden könnte. Ein Registerblock formatiert Text auf einer entworfenen Leinwand; dieses Skill brennt Untertitel in das Filmmaterial von jemandem durch eine Matte. Wenn keine Identität zur Anfrage passt, sagen Sie das und wählen Sie die nächstgelegene, anstatt außerhalb des Katalogs zu suchen.

Empfehlungsheuristik: Verwenden Sie die „Shortlisting-Heuristiken“ in CATALOG.md – sie sind identitätsbezogen (z. B. „炸“ kurzlistet ordnance/stomp/terminal/loud und wählt danach aus, WAS explodieren soll), niemals kategorienbezogen. Unsicher → anchor.

• Cinematic → schreiben Sie cinematic.json für eine gesperrte Vorlage, kompiliert von make-cinematic.cjs.
• Theme → lesen Sie themes/README.md, erstellen Sie theme.json, führen Sie scripts/render-theme.sh aus (kompiliert + rendert + Tafelreaktion → final_fx.mp4).

---

Entscheidungsschleuse – ZUERST AUSFÜHREN

Untersuchen Sie das Video und klassifizieren Sie die Szene vor beiden Modi.

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

Lesen Sie die Muster. Ablehnen, wenn:

• Mehrere Sprecher / harte Schnitte (jede Einstellung getrennt rendern oder ablehnen)
• Kein menschliches Motiv (dieses Skill ist für Talking-Head)
• Unter 3 Sekunden, keine Sprache oder das Gesicht nie klar sichtbar – transcribe.cjs warnt, wenn Audio nahezu stumm ist (Whisper halluziniert Wörter wie „Danke.“ über Stille); beachten Sie die Warnung und lehnen Sie ab, anstatt erfundene Wörter zu untertiteln
• Quelle hat bereits eingebrannte Untertitel / schwere Textgrafiken – das Hinzufügen eines zweiten Untertitelsystems führt zu Konflikten und das Filmmaterial wird unbearbeitet ausgeliefert (kein Abdecken/Inpainting). Eingebrannter Text erscheint oft nur mittendrin: Erstellen Sie ein 1fps-Kontaktblatt (ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), verlassen Sie sich nicht auf 3 Einzelbilder.
• Transkription ist Müll – nicht-muttersprachliche/stark akzentbelastete Sprache kann als selbstbewusster Unsinn transkribiert werden. Lesen Sie transcript.json vor dem Erstellen auf Plausibilität; wenn es sich nicht wie eine Sprache anfühlt, versuchen Sie WHISPER_MODEL=medium einmalig, sonst ablehnen (eine wörtliche Schiene mit erfundenen Wörtern ist schlimmer als keine Untertitel).
• Verwackelte Handkamera mit schneller Bewegung (Matte flackert)

Vorflug-Überprüfungen (kosten nichts, verhindern die schlimmsten Fehler)

1. Schnitt-Überprüfung. Musterbilder bei 20 %, 50 %, 80 % des Videos. Wenn ein anderes Motiv/Szene erscheint, schneiden Sie den Clip vor dem Schnitt zu.
2. Letterbox / Pillarbox-Überprüfung. Schwarze Balken im ersten Bild? Berechnen Sie das sichere Inhaltsrechteck und beschränken Sie die Untertitelplatzierung darauf.
3. Luminanz-Überprüfung. Messen Sie die durchschnittliche Luminanz des Untertitelbereichs – unter 60 → heller Text liest sich wie er ist, 60-180 → fügen Sie den Glyphen-Schirm hinzu, 180+ → deckender Text + Schirm (niemals nackten hellen Text). Cinematic-Vorlagen sind cream+screen und GESPERRT – verwenden Sie diese Überprüfung, um eine passende Identität auszuwählen (helle Szenen → ink oder die deckende Rail anchor-Theme), niemals, um eine einzufärben.
4. Identitätsempfehlung nach Ton (Sie empfehlen; der Benutzer wählt – siehe Schritt 0 + CATALOG.md). Erklärvideo / Interview / Wörter müssen lesbar sein → Rail/Panel-Oberflächenidentitäten; poetisch / sozial / „cinematic“ → Spaltenfluss-Identitäten nach Register; „炸 / 特效 / VFX“ / benannte Welten → thematische Identitäten. Bei Unsicherheit → anchor (Wörter lesbar, Szene sicher) – aber präsentieren Sie eine Shortlist und lassen Sie 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 ∥ Transkription (parallel) → Safe Zones. Ein Befehl.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [AGENT-SCHRITT – der einzige kreative Schritt] Erstellen Sie eine kleine JSON-Datei; siehe unten nach Modus
   Cinematic: cinematic.json erstellen → node scripts/make-cinematic.cjs <project>
   Theme:     theme.json erstellen → bash scripts/render-theme.sh <project>   (kompiliert + rendert + Tafel-Effekte)
4. node scripts/preview-frames.cjs <project>   # ~2s/Frame Composite-Vorschauen → § Visuelle Qualitätssicherung (VOR dem Rendern)
5. bash scripts/render-and-composite.sh <project>  # Prüfungen → final.mp4 + history/ snapshot
   (Thememodus: SCHRITTE 3b/5 ÜBERSPRINGEN – render-theme.sh führt bereits Kompilierung + render-and-composite
    + _postfx.sh aus; das Ergebnis ist final_fx.mp4, final.mp4 ist vor der Tafelreaktion)

Schritt 1 von init prüft die installierten Skills gegen die neuesten auf GitHub und aktualisiert das globale Set, falls eines veraltet ist.

Schritt 3 unterscheidet sich je nach Modus:

Schritt 3 – Cinematic-Modus (reines Embed)

1. Lesen Sie zuerst safe-zones.json. Erzählebenen gehen in zones.hugLeft/hugRight – saubere Streifen, die an die Silhouette angrenzen (Text weit weg vom Körper wirkt schwebend, nicht eingebettet; entfernte Ecken sind die Ausweichlösung, nicht der Standard). Der Hero standardmäßig auf heroAnchor/heroBands.best (zentriert AUF dem Motiv, ~30–55 % verdeckt). recommendation:"fg" verschiebt die ERZÄHLUNG in den Vordergrund für Lesbarkeit; der Hero bleibt eingebettet, wann immer heroBands.feasible – Hero im Vordergrund ist die letzte Option.
2. Die DNA ist die Identität, die Sie in Schritt 0 ausgewählt haben (aus CATALOG.md). Sie definiert bewegte Typografie (nicht statisch). Der Compiler erwartet cinematic.json mit: "identity", "transcriptPath", "safeZonesPath", "projectRoot":