embedded-captions — Mute-Feed-Ship

Plugin-Installation: Befor Setup- oder Freshness-Befehlen befolgen Sie die Plugin-Ausführungsregeln, wenn sich diese Fähigkeit innerhalb eines HyperFrames-Plugins befindet. Eigenständige Installationen behalten die folgenden Aktualisierungsanweisungen.

Zuerst: Halten Sie diese Fähigkeit frisch – bestätigen Sie mit dem Benutzer vor der Ausführung: npx hyperframes skills update embedded-captions. Eine schnelle No-Op, wenn alles aktuell ist; andernfalls wird diese Fähigkeit sowie die Kern-Domain-Fähigkeiten, von denen sie abhängt, aktualisiert, bevor Sie sich darauf verlassen.

Embedded Captions

Ein Katalog, vorne ausgewählt (CATALOG.md — 35 Identitäten; die dahinterliegenden Engines sind Backend-Details). Standard (Standard) baut eine saubere, wörtliche Schiene (unteres Drittel Untertitel mit dem meisten Text) + einen Embed-Höhepunkt, der am Höhepunkt in die Szene hinter dem Subjekt komponiert wird. Cinematic ist reines Embed – keine Schiene, jede Bildunterschrift wird hinter dem Subjekt komponiert (Hero-Typografie, Akkumulation, Verdeckung als Effekt). Theme ist eine vollständig thematisierte Verfassung – Körper-Paradigma × Hero-Setpiece × Front-Effekte × Plattform-Reaktion, 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 („炸“, „特效“, „像 AE 做的“).

---

Laufzeitvoraussetzungen

Plugin-Installationen verwenden die gebündelte, manifest-pinierte CLI für Matting, Transkription und Rendering; kein Source-Checkout erforderlich. Die lokale Vorschau und die Hilfsprogramme zur Caption-Messung benötigen außerdem Sharp, Puppeteer (mit seinem Chromium-Browser) und GSAP. Installieren Sie diese im Caption-Projekt, nicht im schreibgeschützten Plugin:

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

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

Das Rendering wartet, bis die CLI erfolgreich beendet ist, bevor es komponiert. 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 ist. Ein explizites built-checkout-Argument oder HYPERFRAMES_ROOT wählt die Contributor-CLI anstelle des Plugin-Pins aus. Brechen Sie ein steckengebliebenes Rendering normal über die CLI/das Terminal ab; das Caption-Helper-Programm beendet oder stellt ein Rendering aus einem Prozess-Snapshot nicht zwangsweise wieder her.

Betriebsablauf (Kurzfassung)

Über /hyperframes geroutet, bestätigt die Intent-Ebene nur die Eingabe (welches Clip) und kündigt die Identitätsauswahl als verzögerte Anfrage an – die Shortlist benötigt den untersuchten Clip, daher bleibt sie bei Schritt 1 unten; die Run-Shape-Fragen der Ebene treffen nicht zu (das Filmmaterial ist unberührt, es gibt kein Storyboard zur Überprüfung). Ein BRIEF.md, falls vorhanden, enthält die bestätigte Eingabe und etwaige Benutzernotizen – lesen Sie es zuerst.

Die handwerkliche Prosa unten ist lang; die Pipeline selbst ist kurz – und alles Deterministische wird berechnet oder kompiliert, niemals handgeschrieben:

1. Entscheidungsgate (schlechte Clips ablehnen) → EINE Identität aus CATALOG.md auswählen (35 Identitäten; Engine/Compiler durch Lookup abgeleitet – niemals eine Modus-/Kategoriefrage stellen)
2. hyperframes init (überspringen, wenn das Projektverzeichnis bereits mit dem Video darin existiert – matte.cjs/transcribe.cjs übernehmen jedes Video im Verzeichnis als source.mp4) → bash scripts/prepare.sh <project> (Matte ∥ Transkription ∥ Audio-Hüllkurve parallel, dann safe-zones v2 mit Szenen-Palette/Optik/Beleuchtung – ein Befehl, nichts vergessen)
3. ein kleines JSON mit kreativen Entscheidungen verfassen (zuerst safe-zones.json lesen): Cinematic → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs; Theme → theme.json → make-theme.cjs (Schienen/Panel/Gedicht/Übernahme-Paradigmen; anchor ist die ruhige Schienen-Standardeinstellung)
4. Visuelle Qualitätssicherung: node scripts/preview-frames.cjs <project> → originalgetreue Composite-Vorschauen in ~2s/Bild (kein Rendering). Überprüfen Sie § Visuelle Qualitätssicherung, bevor Sie für ein Rendering bezahlen.
5. render-and-composite.sh → Gates (Timing / Verdeckung+Hero / Überlauf / Übergabe) → final.mp4

Tragende Regeln, die Leute übersehen:

• Schiene (Standard) + Embed (Promotion). drop (Füllwort, nicht angezeigt) / rail (wörtlicher unterer Drittel Untertitel, vorne, trägt den meisten Text) / embed (ein Höhepunkt-Wort, das hinter dem Subjekt komponiert wird). Der Standard-Modus macht beides und bettet nur den/die Höhepunkte ein. Siehe § Caption-Modell.
• Das Video wird UNBERÜHRT geliefert (Standard/Cinematic; das PLATE-Budget des Theme-Modus ist die einzig zulässige Ausnahme – registergesteuerte Reaktionsbeats (Aufladungs-Dimmen, Schlag, Schütteln, Körnung), definiert pro Theme-DNA und nach dem Matte-Composite angewendet, sodass Subjekt+Text+Platte sich als ein Frame bewegen) – Bildunterschriften sind das Einzige, was hinzugefügt wird; das Matte lässt das Subjekt lediglich die Embed-Spur verdecken. Nie das Filmmaterial gradieren/nachfärben/Scanlines hinzufügen.
• Zwei Regelwerke: Schiene → references/rail.md (dünn), Embed-Handwerk → references/composition-craft.md (reichhaltig, nur Embed). Bei Bedarf überfliegen.

---

Caption-Modell – Schiene + Embed

Jeder gesprochene Satz ist eines von drei Dingen:

	Was	Wie es angezeigt wird
drop	Füllwort – ähm/äh, Stottern, Selbstkorrekturen	nicht angezeigt
rail	der Standard – gewöhnlicher gesprochener Inhalt (wörtlich)	sauberer unterer Drittel Untertitel, vorne, lesbar. Ein Punch-Wort kann einen inline-emphasis-Hervorhebung erhalten (Akzentfarbe / aktiver Wort-Pop) – es bleibt auf der Schiene.
embed	ein beworbener Höhepunkt – der Schlagzeilen-Beat	ein großes Wort, das hinter dem Subjekt komponiert wird (Matte-Verdeckung), gestalteter Eintritt + Austritt

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

Schienen-Oberflächen-Identitäten bauen genau dies (Schiene = rail.html, Embed = der Höhepunkt in index.html). Spaltenfluss-Identitäten lassen die Schiene weg und machen alles Embed-Stil – empfehlen Sie sie nur für Stimmungs-über-wörtliche Anfragen, niemals für Erklär-/Voiceover-Videos, in denen die Worte lesbar sein müssen (CATALOG.md codiert dies pro Identität).

---

Schritt 0 – EINE Identität aus dem CATALOG auswählen

Ein Frontend, drei Engines dahinter. Der Benutzer wählt eine IDENTITÄT aus CATALOG.md (35 Einträge: 10 klassisch + 25 thematisch); die Engine, der Compiler und die Autorendatei werden durch Lookup aus der Katalogzeile abgeleitet. Fragen Sie nie „Standard vs. Cinematic vs. Theme“ – das sind Backend-Namen (ein Produkt hat eine UX, auch mit mehreren Engines). Der Katalog codiert alles, was das Routing benötigt: Leseoberfläche, Stimme, Empfehlung-für, Szenenbedarf, 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): Im autonomen Modus („überrasche mich“ / „entscheide für mich“) wählen Sie aus Ihrer Shortlist selbst und geben den einzeiligen Grund an, anstatt zu fragen.

Vorgehensweise: Clip untersuchen → 2–3 Identitäten aus dem Katalog in die Shortlist aufnehmen → EINE mit einem einzeiligen Grund empfehlen → der Benutzer wählt aus (autonomer Modus: Sie wählen aus und geben den Grund an) → die Datei dieser Identität verfassen. 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 Verfassen auswählen. Gehen Sie nicht stillschweigend von der Standardeinstellung aus.

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

CATALOG.md ist der gesamte Antwortraum hier: Dieser Workflow durchsucht nicht das HyperFrames-Komponentenregister. Die Kompositions-Workflows führen npx hyperframes catalog vor dem Verfassen eines benannten Looks aus; dieser hier darf es 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 montiert werden könnte. Ein Registerblock stylt Text auf einer entworfenen Leinwand; diese Fähigkeit brennt Bildunterschriften in das Filmmaterial einer Person durch ein 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 auf Identitätsebene (z. B. „炸“ → shortlistet ordnance/stomp/terminal/loud und wählt basierend darauf, WAS explodieren soll), niemals auf Kategorieebene. Unsicher → anchor.

• Cinematic → plan.json für eine gesperrte Vorlage schreiben, kompiliert von make-composition.cjs.
• Theme → themes/README.md lesen, theme.json verfassen, scripts/render-theme.sh ausführen (kompiliert + rendert + Plattenreaktion → final_fx.mp4).

---

Entscheidungsgate – 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 Proben. Ablehnen, wenn:

• Mehrere Sprecher / harte Schnitte (jeden Take splitten & rendern oder ablehnen)
• Kein menschliches Subjekt (diese Fähigkeit ist für Talking-Head)
• Unter 3 Sekunden, keine Sprache oder Gesicht nie klar sichtbar – transcribe.cjs warnt, wenn Audio nahezu still ist (Whisper halluziniert Wörter wie „Danke.“ über Stille); beachten Sie die Warnung und lehnen Sie ab, anstatt erfundene Wörter zu beschriften
• Quelle hat bereits eingebrannte Untertitel / schwere Textgrafiken – das Hinzufügen eines zweiten Untertitelsystems führt zu Konflikten und das Filmmaterial wird unberührt ausgeliefert (kein Überdecken/Inpainting). Eingebrannter Text erscheint oft nur in der Mitte des Clips: Mustern Sie ein 1fps-Kontaktblatt (ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), verlassen Sie sich nicht auf 3 Spot-Frames.
• Transkription ist Müll – nicht-muttersprachliche/stark akzentuierte Sprache kann zu selbstbewusstem Blödsinn transkribiert werden. Lesen Sie transcript.json vor dem Verfassen auf Verstand; wenn es sich nicht als Sprache parsen lässt, versuchen Sie es einmal mit WHISPER_MODEL=medium, sonst ablehnen (eine wörtliche Schiene erfundener Wörter ist schlimmer als keine Bildunterschriften).
• Hektische Handkamera mit schneller Bewegung (Matte flackert)

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

1. Schnitt-Probe. Rahmenproben bei 20%, 50%, 80%. Wenn ein anderes Subjekt/Szene erscheint, trimmen Sie den Clip vor dem Schnitt.
2. Letterbox / Pillarbox-Probe. Schwarze Balken im ersten Frame? Sicheren Inhaltsrechteck berechnen und Caption-Platzierung darin einschränken.
3. Luminanz-Probe. Durchschnittliche Luminanz des Caption-Bereichs abtasten – unter 60 → heller Text liest sich wie er ist, 60-180 → den Glyphen-Scrim hinzufügen, 180+ → deckender Text + Scrim (niemals bloßer heller Text). Cinematic-Vorlagen sind creme+screen und GESPERRT – verwenden Sie diese Sonde, um eine passende Identität auszuwählen (helle Szenen → ink, oder das deckende Schienen-anchor-Theme), niemals um eine umzufärben.
4. Identitätsempfehlung nach Tonfall (Sie empfehlen; der Benutzer wählt aus – siehe Schritt 0 + CATALOG.md). Erklärvideo / Interview / Wörter müssen lesbar sein → Schienen-/Panel-Oberflächen-Identitäten; poetisch / sozial / „filmisch“ → Spaltenfluss-Identitäten nach Register; „炸 / 特效 / VFX“ / benannte Welten → thematische Identitäten. Wenn unsicher → 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] ein kleines JSON verfassen; siehe unten nach Modus
   Cinematic: plan.json verfassen → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Theme:     theme.json verfassen → 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>  # Gates → final.mp4 + history/ Snapshot
   (Theme-Modus: SCHRITTE 3b/5 ÜBERSPRINGEN – render-theme.sh führt bereits Kompilierung + render-and-composite
    + _postfx.sh aus; das Lieferobjekt ist final_fx.mp4, final.mp4 ist vor Plattenreaktion)

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

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 ANGRENZEND an die Silhouette (Text weit vom Körper entfernt liest sich als schwebend, nicht eingebettet; entfernte Ecken sind die Ausweichlösung, nicht der Standard). Der Held standardmäßig auf heroAnchor/heroBands.best (ZENTRIERT auf dem Subjekt, ~30–55% verdeckt). recommendation:"fg" verschiebt ERZÄHLUNG nach vorne für Lesbarkeit; der Held bleibt eingebettet, solange heroBands.feasible – Held-Vordergrund ist die letzte Rettung.
2. Die DNA ist die Identität, die Sie

…