Plugin-Installationen: Führen Sie vor Einrichtungs- oder Aktualisierungsbefehlen die Plugin-Installationsregeln aus, wenn dieses Skill innerhalb eines HyperFrames-Plugins verwendet wird. Eigenständige Installationen behalten die folgenden Update-Anweisungen bei.
Zunächst: Halten Sie dieses Skill aktuell – bestätigen Sie mit dem Benutzer, bevor Sie Folgendes ausführen:
npx hyperframes skills update embedded-captions. Ein schneller No-Op, wenn alles aktuell ist; andernfalls wird dieses Skill sowie die Kern-Domain-Skills, von denen es abhängt, aktualisiert, bevor Sie sich darauf verlassen.
Eingebettete Untertitel
Ein Katalog, vorab ausgewählt (CATALOG.md – 35 Identitäten; die dahinter liegenden Engines sind Backend-Details). Standard (Standard) erstellt eine saubere, wörtliche Schiene (Untertitel im unteren Drittel, die den Großteil des Textes tragen) + einen Embed-Höhepunkt, der im Höhepunkt in die Szene hinter der Person eingefügt wird. Cinematic ist reines Embed – keine Schiene, jeder Untertitel wird hinter der Person eingefügt (Hero-Typografie, Akkumulation, Verdeckung als Effekt). Theme ist eine vollständige thematische Konstitution – Körperparadigma × Hero-Setpiece × Front-FX × Plattenreaktion, zusammengesetzt aus Registern (themes/README.md): ordnance terminal neonsign stardust stomp. Die meisten Erklärvideos / Voiceover sind Standard; Embed ist der seltene, verdiente Höhepunkt – jedes Wort einzubetten ist der häufige Fehler; Theme ist für VFX-Anfragen („炸“, „特效“, „wie in After Effects gemacht“).
Laufzeitvoraussetzungen
Plugin-Installationen verwenden das gebündelte, manifest-pinnierte CLI für Freistellung, Transkription und Rendering; kein Source-Checkout erforderlich. Die lokalen Vorschau- und Untertitel-Messwerkzeuge benötigen außerdem Sharp, Puppeteer (mit seinem Chromium-Browser) und GSAP. Installieren Sie diese im Untertitel-Projekt, nicht innerhalb des schreibgeschützten Plugins:
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. Freistellung und Transkription laden möglicherweise beim ersten Gebrauch eigene Modelle herunter.
Das Rendering wartet auf den erfolgreichen Abschluss des CLIs, bevor es die Komposition durchführt. 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 das Contributor-CLI anstelle des Plugin-Pins aus. Brechen Sie ein steckengebliebenes Rendering normal über das CLI/Terminal ab; das Untertitel-Helper beendet keinen Rendervorgang gewaltsam und stellt auch keinen aus einem Prozess-Snapshot wieder her.
Betriebsablauf (Kurzzusammenfassung)
Gesteuert über /hyperframes bestätigt die Intent-Ebene nur die Eingabe (welcher Clip) und kündigt die Identitätsauswahl als verzögerte Anfrage an – die Shortlist benötigt den untersuchten Clip, also bleibt sie bei Schritt 1 unten; die Fragen zur Laufzeitform der Ebene 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 sie zuerst.
Der handwerkliche Prosa unten ist lang; die Pipeline selbst ist kurz – und alles Deterministische wird berechnet oder kompiliert, niemals von Hand geschrieben:
- Entscheidungs-Tor (schlechte Clips ablehnen) → WÄHLEN SIE EINE Identität aus CATALOG.md (35 Identitäten; Engine/Compiler durch Nachschlagen abgeleitet – niemals eine Modus-/Kategoriefrage stellen)
hyperframes init(überspringen, wenn das Projektverzeichnis bereits mit dem Video 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)- Autor einer kleinen JSON mit kreativen Entscheidungen (zuerst
safe-zones.jsonlesen): Cinematic →cinematic.json→make-cinematic.cjs(leitetplan.jsonab und kompiliert es); Theme →theme.json→make-theme.cjs(Rail/Panel/Poem/Takeover-Paradigmen;anchorist die Standard-Leise-Schiene) - Visuelle Qualitätskontrolle:
node scripts/preview-frames.cjs <project>→ originalgetreue Composite-Vorschauen in ~2s/Frame (kein Rendering). Überprüfen Sie § Visuelle Qualitätskontrolle, bevor Sie für ein Rendering bezahlen. render-and-composite.sh→ Tore (Timing / Verdeckung+Hero / Überlauf / Übergabe) →final.mp4
Tragende Regeln, die oft übersehen werden:
- Schiene (Standard) + Embed (Beförderung).
drop(Füllmaterial, nicht angezeigt) /rail(wörtlicher unterer Drittel-Untertitel, vorne, trägt den meisten Text) /embed(ein Höhepunktswort, das hinter der Person eingefügt wird). Der Standardmodus macht beides, wobei nur die Höhepunkte eingebettet werden. Siehe § Untertitelmodell. - Das Video wird UNBERÜHRT geliefert (Standard/Cinematic; Das PLATE-Budget des Theme-Modus ist die eine genehmigte Ausnahme – registrierungsgesteuerte Reaktionsbeats (Charge-Dim, Punch, Shake, Grain), definiert pro Theme-DNA und nach dem Matte-Composite angewendet, sodass Person+Text+Platte sich als ein Frame bewegen) – Untertitel sind das Einzige, was hinzugefügt wird; das Matte dient nur dazu, dass die Person die Embed-Spur verdeckt. Niemals das Filmmaterial gradieren/neu einfärben/Scanlines hinzufügen.
- Zwei Regelwerke: Schiene → references/rail.md (dünn), Embed-Handwerk → references/composition-craft.md (reichhaltig, nur Embed). Nach Bedarf überfliegen.
Untertitelmodell – Schiene + 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 unterer Drittel-Untertitel, vorne, lesbar. Ein betontes Wort kann eine inline emphasis-Hervorhebung erhalten (Akzentfarbe / aktives Wort-Pop) – es bleibt auf der Schiene. |
| embed | ein beförderter Höhepunkt – der Schlagzeilen-Beat | ein großes Wort, das hinter der Person eingefügt wird (Matte-Verdeckung), gestalteter Ein- und Ausgang |
Die Schiene trägt den meisten Text; 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 Luft zwischen Hero-Fenstern (der Compiler warnt unter 0,6 s). Ein kurzer Clip → normalerweise 1–2; ein langes Erklärvideo → etwa einer pro Abschnitt. Bei mehreren Heroen ist der größte autorierte der APEX (er allein erhält das vollständige Lockup-Embed + Breitenanpassung); kleinere sind MINOR-Höhepunkte, die ihre Spalte als überdimensionierte Betonungszeilen (Vordergrund, gedämpfte Bewegung) reiten – nicht jeder Beat braucht die Matte-Inszenierung, und genau das macht den Apex zu einem Ereignis. Jedes Wort einzubetten ist immer noch der häufige Fehler.
Schienen-Oberflächenidentitäten erstellen genau dies (Schiene = rail.html, Embed = der Höhepunkt in index.html). Spaltenfluss-Identitäten lassen die Schiene weg und machen alles Embed-artig – empfehlen Sie diese nur für Stimmungs-über-wörtliche Anfragen, niemals für Erklärvideos / Voiceover, bei denen die Worte 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 durch Nachschlagen aus der Katalogzeile abgeleitet. Stellen Sie niemals „Standard vs. Cinematic vs. Theme“ als Frage – das sind Backend-Namen (ein Produkt hat eine UX, auch mit mehreren Engines). Der Katalog codiert alles, was das Routing benötigt: Lesefläche, Stimme, Empfehlungsbereich, Szenenanforderungen, Nachbarschaftshinweise für die wirklich ähnlichen Paare (loud↔ordnance, neon↔neonsign, cream↔stardust).
Die Identitätsauswahl ist ein Präferenz-Tor (../hyperframes/references/brief-contract.md § 1): Im autonomen Modus („überrasche mich“ / „entscheide für mich“) wählen Sie selbst aus Ihrer Shortlist und nennen das einzeilige Warum, anstatt zu fragen.
Vorgehen: Clip untersuchen → Shortlist mit 2–3 Identitäten aus dem Katalog → EINE mit einem einzeiligen Warum empfehlen → der Benutzer wählt (autonomer Modus: Sie wählen, nennen das Warum) → die Datei dieser Identität autorieren. Identitäten sind Engine-gebunden (keine Cross-Kombos; das Öffnen einer ist ein Validierungsereignis – siehe dna/README.md).
Präsentieren Sie immer Ihre Empfehlung und lassen Sie den Benutzer wählen, bevor Sie autorieren. Nicht stillschweigend standardmäßig vorgehen.
(Die vollständige Identitätstabelle befindet sich in CATALOG.md – die alleinige 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 aus, bevor sie einen benannten Look autorieren; dieser darf es nicht. Seine Engines sind gesperrte Compiler, die cinematic.json / theme.json konsumieren und die Komposition selbst erzeugen, sodass ein Registereintrag – einschließlich der caption-*-Blöcke – nichts zum Einbinden hat. Ein Registerblock formatiert Text auf einer gestalteten Leinwand; dieses Skill brennt Untertitel in das Filmmaterial einer anderen Person durch ein Matte. Wenn keine Identität zur Anfrage passt, sagen Sie dies und wählen Sie die nächste, anstatt außerhalb des Katalogs zu suchen.
Empfehlungsheuristik: Verwenden Sie die „Shortlist-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 → schreiben Sie
cinematic.jsonfür eine gesperrte Vorlage, kompiliert vonmake-cinematic.cjs. - Theme → lesen Sie themes/README.md, autorieren Sie
theme.json, führen Siescripts/render-theme.shaus (kompiliert + rendert + Plattenreaktion → final_fx.mp4).
Entscheidungs-Tor – 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 Samples. Ablehnen, wenn:
- Mehrere Sprecher / harte Schnitte (Aufnahme teilen & jede Einstellung rendern, oder ablehnen)
- Kein menschliches Motiv (dieses Skill ist für Talking-Head)
- Unter 3 Sekunden, keine Sprache, oder Gesicht nie klar sichtbar –
transcribe.cjswarnt, wenn Audio nahezu still ist (Whisper halluziniert Wörter wie „Thank you.“ über Stille); beachten Sie die Warnung und lehnen Sie ab, anstatt erfundene Wörter zu beschriften - Quelle hat bereits eingebrannte Untertitel / Beschriftungen / 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 mittendrin: Erstellen Sie ein 1fps-Kontaktblatt (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), vertrauen Sie nicht 3 Einzelbildern. - Transkription ist Müll – nicht-muttersprachliche/stark akzentuierte Sprache kann in selbstbewussten Unsinn transkribiert werden. Lesen Sie
transcript.jsonvor dem Autoren auf Verständlichkeit; wenn es nicht wie eine Sprache aussieht, versuchen Sie es einmal mitWHISPER_MODEL=medium, sonst ablehnen (eine wörtliche Schiene aus erfundenen Wörtern ist schlimmer als keine Untertitel). - Verwackelte Handkamera mit schneller Bewegung (Matte flackert)
Pre-Flight-Prüfungen (kosten nichts, verhindern die schlimmsten Fehler)
- Schnitt-Prüfung. Beispielbilder bei 20%, 50%, 80%. Wenn ein anderes Motiv/Szene erscheint, schneiden Sie den Clip vor dem Schnitt zurecht.
- Letterbox-/Pillarbox-Prüfung. Schwarze Balken im ersten Frame? Berechnen Sie den sicheren Inhaltsrechteck und beschränken Sie die Untertitelplatzierung darauf.
- Luminanz-Prüfung. Messen Sie die durchschnittliche Luminanz des Untertitelbereichs –
unter 60→ heller Text liest sich gut,60-180→ Glyphen-Scrim hinzufügen,180+→ deckender Text + Scrim (niemals nackten hellen Text). Cinematic-Vorlagen sind creme+screenund GESPERRT – verwenden Sie diese Prüfung, um eine passende Identität auszuwählen (helle Szenen →ink, oder das deckende-Schiene-Themaanchor), niemals, um eine neu einzufärben. - Identitätsempfehlung nach Ton (Sie empfehlen; der Benutzer wählt – siehe Schritt 0 + CATALOG.md). Erklärvideo / Interview / Worte müssen lesbar sein → Schienen-/Panel-Oberflächenidentitäten; poetisch / sozial / „cinematic“ → Spaltenflussidentitäten nach Register; „炸 / 特效 / VFX“ / benannte Welten → thematische Identitäten. Bei Unsicherheit →
anchor(Worte 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] Autor einer kleinen JSON; siehe unten nach Modus
Cinematic: autorieren Sie cinematic.json → node scripts/make-cinematic.cjs <project>
Theme: autorieren Sie theme.json → bash scripts/render-theme.sh <project> (kompiliert + rendert + Platten-FX)
4. node scripts/preview-frames.cjs <project> # ~2s/Frame Composite-Vorschauen → § Visuelle Qualitätskontrolle (VOR dem Rendering)
5. bash scripts/render-and-composite.sh <project> # Tore → final.mp4 + history/ Schnappschuss
(Theme-Modus: SCHRITTE 3b/5 ÜBERSPRINGEN – render-theme.sh führt bereits Compile + render-and-composite aus
+ _postfx.sh; das Ergebnis ist final_fx.mp4, final.mp4 ist vor der Plattenreaktion)
Schritt 1s init prüft die installierten Skills gegen die neuesten auf GitHub und aktualisiert die globale Menge, wenn welche veraltet sind.
Schritt 3 unterscheidet sich je nach Modus:
Schritt 3 – Cinematic-Modus (reines Embed)
- Lesen Sie zuerst
safe-zones.json. Erzählebenen gehen inzones.hugLeft/hugRight– saubere Streifen ANGRENZEND an die Silhouette (Text weit weg vom Körper wirkt schwebend, nicht eingebettet; weite Ecken sind der Notfallplan, nicht der Standard). Der Hero verwendet standardmäßigheroAnchor/heroBands.best(ZENTRIERT auf die Person, ~30–55% verdeckt).recommendation:"fg"verschiebt die ERZÄHLUNG nach vorne für Lesbarkeit; der Hero bleibt eingebettet, wann immerheroBands.feasible– Hero-Vordergrund ist die letzte Wahl. - **Die DNA ist die Identität, die Sie in Schritt 0 ausgewählt haben.