Plugin-Installationen: Führen Sie vor Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln aus, wenn diese Fähigkeit Teil eines HyperFrames-Plugins ist. Bei eigenständigen Installationen gelten die unten stehenden Aktualisierungshinweise.
Zuerst die Fähigkeit aktuell halten — bestätigen Sie mit dem Benutzer, bevor Sie ausführen:
npx hyperframes skills update embedded-captions. Ein schneller No-op, wenn alles auf dem neuesten Stand ist; andernfalls wird diese Fähigkeit zusammen mit den Kernfähigkeiten, von denen sie abhängt, aktualisiert, bevor Sie darauf zurückgreifen.
Eingebettete Bildunterschriften
Ein Katalog, vorab ausgewählt (CATALOG.md — 35 Identitäten; die Motoren dahinter sind Backend-Details). Standard (Standard) erstellt eine saubere wörtliche Schiene (untere Drittel-Untertitel, die den Großteil des Textes enthalten) + einen Embed-Höhepunkt, der in die Szene hinter dem Motiv compositet wird. Cinematic ist reiner Embed — keine Schiene, jede Bildunterschrift wird hinter dem Motiv compositet (Hero-Typografie, Akkumulation, Verdeckung als Effekt). Theme ist eine vollständige thematische Verfassung — Körper-Paradigma × Hero-Setpiece × Front-FX × Plattenreaktion, 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-Anfragen ("炸", "特效", "wie mit AE gemacht").
Laufzeitvoraussetzungen
Plugin-Installationen verwenden die gebündelte, im Manifest festgelegte CLI für Freistellung, Transkription und Rendering; kein Source-Checkout ist erforderlich. Die lokale Vorschau und die Hilfsprogramme zur Bildunterschriftenmessung benötigen außerdem Sharp, Puppeteer (mit seinem Chromium-Browser) und GSAP. Installieren Sie diese im Bildunterschriftenprojekt, nicht innerhalb des schreibgeschützten Plugins:
npm install --prefix <projekt> --save-dev --save-exact [email protected] [email protected] [email protected]
Behalten Sie die Lock-Datei des Projekts. Wenn diese Abhängigkeiten bereits vorhanden sind, verwenden Sie deren gesperrte Versionen, anstatt sie zu überschreiben. Bash und FFmpeg/ffprobe müssen im PATH verfügbar sein. Freistellung und Transkription laden möglicherweise bei der ersten Verwendung eigene Modelle herunter.
Das Rendering wartet auf den erfolgreichen Abschluss der CLI, bevor es compositet. Der alte Shell-Watchdog HF_TIMEOUT_S wird nicht mehr verwendet: Eine große partielle Datei ist kein Beweis für den Abschluss des Renderings. Ein explizites built-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 Bildunterschriften-Hilfsprogramm beendet kein Rendering zwangsweise oder stellt es aus einem Prozess-Snapshot wieder her.
Betriebsablauf (Kurzfassung)
Über /hyperframes weitergeleitet, bestätigt die Absichtsebene nur die Eingabe (welcher Clip) und kündigt die Identitätsauswahl als aufgeschobene 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). Wenn eine BRIEF.md vorhanden ist, enthält sie die bestätigte Eingabe und etwaige Benutzernotizen — lesen Sie sie zuerst.
Der handwerkliche Text unten ist lang; die Pipeline selbst ist kurz — und alles Deterministische wird berechnet oder kompiliert, niemals handgeschrieben:
- Entscheidungstor (schlechte Clips ablehnen) → wählen Sie EINE Identität aus CATALOG.md (35 Identitäten; Engine/Compiler werden durch Nachschlagen abgeleitet — keine Modus-/Kategoriefrage stellen)
hyperframes init(überspringen, wenn das Projektverzeichnis bereits mit dem Video vorhanden ist —matte.cjs/transcribe.cjsübernehmen jedes Video im Verzeichnis als source.mp4) →bash scripts/prepare.sh <projekt>(matte ∥ transcribe ∥ audio-envelope parallel, dann safe-zones v2 mit Szenenpalette/Optik/Beleuchtung — ein Befehl, nichts vergessen)- ein kleines JSON mit kreativen Entscheidungen schreiben (zuerst
safe-zones.jsonlesen): Cinematic →cinematic.json→make-cinematic.cjs(leitetplan.jsonab und kompiliert es); Theme →theme.json→make-theme.cjs(Schienen-/Panel-/Gedicht-/Übernahme-Paradigmen;anchorist die ruhige Schienen-Standardeinstellung) - Visuelle Qualitätskontrolle:
node scripts/preview-frames.cjs <projekt>→ originalgetreue Composite-Vorschauen in ~2s/Bild (kein Rendering). Überprüfen Sie § Visuelle Qualitätskontrolle, bevor Sie ein Rendering bezahlen. render-and-composite.sh→ Tore (Timing / Verdeckung+Held / Überlauf / Übergabe) →final.mp4
Belastbare Regeln, die oft übersehen werden:
- Schiene (Standard) + Embed (Beförderung).
drop(Füllmaterial, nicht angezeigt) /rail(wörtliche untere Drittel-Untertitel, vorne, trägt den Großteil des Textes) /embed(ein Höhepunktwort, das hinter dem Motiv compositet wird). Der Standardmodus macht beides und bettet nur die Höhepunkte ein. Siehe § Caption-Modell. - Das Video wird UNVERÄNDERT geliefert (Standard/Cinematic; das PLATE-Budget des Themenmodus ist die einzige zugelassene Ausnahme — registergesteuerte Reaktionsbeats (Aufladungsabdunklung, Schlag, Schütteln, Körnung) werden pro Themen-DNA definiert und NACH dem Matte-Composite angewendet, sodass Motiv+Text+Platte sich als ein Bild bewegen) — Bildunterschriften sind das Einzige, was hinzugefügt wird; die Matte erlaubt nur, dass das Motiv die Embed-Spur verdeckt. Niemals das Filmmaterial abmessen/umfärben/Scanlines hinzufügen.
- Zwei Regelbücher: Schiene → references/rail.md (dünn), Embed-Craft → references/composition-craft.md (umfangreich, nur Embed). Nach Bedarf überfliegen.
Caption-Modell — Schiene + Embed
Jeder gesprochene Satz ist eines von drei Dingen:
| Was | Wie es angezeigt wird | |
|---|---|---|
| drop | Füllwörter — ähm/äh, Stotterer, Selbstkorrekturen | nicht angezeigt |
| rail | Standard — gewöhnlicher gesprochener Inhalt (wörtlich) | sauberer unterer Drittel-Untertitel, vorne, lesbar. Ein betontes Wort kann einen Inline-emphasis-Highlight 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 dem Motiv compositet wird (Matte-Verdeckung), gestalteter Ein- und Ausgang |
Die Schiene trägt den Großteil des Textes; 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 Abstand zwischen Heldenfenstern (der Compiler warnt unter 0,6s). Ein kurzer Clip → normalerweise 1–2; ein langes Erklärvideo → ungefähr einer pro Abschnitt. Bei mehreren Helden ist der größte erstellte der APEX (nur er bekommt das vollständige Lockup-Embed + Breitenanpassung); kleinere sind MINOR-Höhepunkte, die in ihrer Spalte als übergroße Betonungszeilen (Vordergrund, gedämpfte Bewegung) fahren — nicht jeder Beat braucht das Matte-Schaufenster, und genau das macht den Apex zu einem Ereignis. Jedes Wort einzubetten ist immer noch der häufige Fehler.
Schienen-Oberflächen-Identitäten bauen genau das (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örtlichkeit-Anfragen, niemals für Erklär-/Voiceover-Videos, wo 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); Engine, Compiler und Autoren-Datei 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, selbst mit mehreren Engines). Der Katalog codiert alles, was die Weiterleitung benötigt: Lesefläche, Stimme, Empfehlung für, Szenenanforderungen, Adjazenznotizen für die wirklich nahen Paare (loud↔ordnance, neon↔neonsign, cream↔stardust).
Die Identitätsauswahl ist ein Präferenz-Tor (../hyperframes/references/brief-contract.md § 1): Wählen Sie im autonomen Modus ("überraschen Sie mich" / "entscheiden Sie für mich") selbst aus Ihrer Shortlist und geben Sie 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 (autonomer Modus: Sie wählen, mit Begründung) → die Datei dieser Identität erstellen. Identitäten sind Engine-gebunden (keine Querkombinationen; 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 etwas erstellen. Nicht stillschweigend auf Standard zurückfallen.
(Die vollständige Identitätstabelle befindet sich in CATALOG.md — einzige Quelle der Wahrheit für die Weiterleitung. Die Engine-Dokumente unten beschreiben den Auslieferungsvertrag jedes Backends.)
CATALOG.md ist der gesamte Antwortraum: Dieser Workflow durchsucht nicht das HyperFrames-Komponentenregister. Die Kompositions-Workflows führen vor der Erstellung eines benannten Looks npx hyperframes catalog aus; dieser darf das nicht. Seine Engines sind gesperrte Compiler, die cinematic.json / theme.json verbrauchen und die Komposition selbst ausgeben, sodass ein Registereintrag — einschließlich der caption-*-Blöcke — nichts zum Einbinden hat. Ein Registerblock formatiert Text auf einer gestalteten Leinwand; diese Fähigkeit brennt Bildunterschriften durch eine Matte in das Filmmaterial eines Benutzers. 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 nach WAS explodieren soll), niemals auf Kategorieebene. Unsicher → anchor.
- Cinematic →
cinematic.jsonfür eine gesperrte Vorlage schreiben, kompiliert vonmake-cinematic.cjs. - Theme → themes/README.md lesen,
theme.jsonschreiben,scripts/render-theme.shausführen (kompiliert + rendert + Plattenreaktion → final_fx.mp4).
Entscheidungstor — ZUERST AUSFÜHREN
Untersuchen Sie das Video und klassifizieren Sie die Szene, bevor Sie einen Modus wählen.
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 (jede Einstellung einzeln rendern oder ablehnen)
- Kein menschliches Motiv (diese Fähigkeit ist für Talking-Head)
- Unter 3 Sekunden, keine Sprache, oder das Gesicht niemals klar sichtbar —
transcribe.cjswarnt, wenn Audio fast still ist (Whisper halluziniert Wörter wie "Thank you." über Stille); beachten Sie dies und lehnen Sie ab, anstatt erfundene Wörter zu beschriften - Quelle enthält bereits eingebrannte Untertitel / Bildunterschriften / schwere Textgrafiken — das Hinzufügen eines zweiten Untertitel-Systems verursacht Konflikte, und das Filmmaterial wird unverändert ausgeliefert (kein Überdecken/Inpainting). Eingebrannter Text erscheint oft nur mitten im Clip: Muster-Sie mit einem 1fps-Kontaktbogen (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), verlassen Sie sich nicht auf 3 Einzelbilder. - Transkript ist Müll — nicht-muttersprachliche/stark akzentuierte Sprache kann mit großer Sicherheit in Nonsens transkribiert werden. Überprüfen Sie
transcript.jsonauf Sinnhaftigkeit, bevor Sie etwas erstellen; wenn es nicht als Sprache erkennbar ist, versuchen Sie einmalWHISPER_MODEL=medium, sonst ablehnen (eine wörtliche Schiene aus erfundenen Wörtern ist schlimmer als keine Bildunterschriften). - Hektische Handkamera mit schnellen Bewegungen (Matte flackert)
Preflight-Prüfungen (kosten nichts, verhindern die schlimmsten Fehler)
- Schnitt-Prüfung. Muster-Bilder bei 20 %, 50 %, 80 %. Wenn ein anderes Motiv/Szene erscheint, den Clip vor dem Schnitt zuschneiden.
- Letterbox-/Pillarbox-Prüfung. Schwarze Balken im ersten Bild? Sicheren Inhaltsbereich berechnen und die Bildunterschriftenposition darin einschränken.
- Luminanz-Prüfung. Die durchschnittliche Luminanz des Bildunterschriftenbereichs abtasten —
unter 60→ heller Text ist lesbar,60-180→ die Glyphen-Scrim hinzufügen,180+→ deckender Text + Scrim (niemals nackten hellen Text). Cinematic-Vorlagen sind cream+screenund GESPERRT — verwenden Sie diese Prüfung, um eine passende Identität zu wählen (helle Szenen →inkoder das deckende Schienen-anchor-Thema), niemals um eine einzufärben. - Identitätsempfehlung nach Ton (Sie empfehlen; der Benutzer wählt — siehe Schritt 0 + CATALOG.md). Erklärvideo / Interview / Wörter müssen lesbar sein → Schienen-/Panel-Oberflächen-Identitäten; poetisch / sozial / "cinematic" → Spaltenfluss-Identitäten nach Register; "炸 / 特效 / VFX" / benannte Welten → thematische Identitäten. 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 <projekt> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <projekt> # matte ∥ transcribe (parallel) → safe-zones. Ein Befehl.
# → frames_fg/ transcript.json safe-zones.json
3. [AGENT-SCHRITT — der einzige kreative Schritt] ein kleines JSON schreiben; siehe unten nach Modus
Cinematic: cinematic.json schreiben → node scripts/make-cinematic.cjs <projekt>
Theme: theme.json schreiben → bash scripts/render-theme.sh <projekt> (kompiliert + rendert + Platten-FX)
4. node scripts/preview-frames.cjs <projekt> # ~2s/Bild Composite-Vorschauen → § Visuelle Qualitätskontrolle (VOR dem Rendering)
5. bash scripts/render-and-composite.sh <projekt> # Tore → final.mp4 + history/-Snapshot
(Themenmodus: 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 Plattenreaktion)
Schritt 1s 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 nach Modus:
Schritt 3 — Cinematic-Modus (reiner Embed)
- Zuerst
safe-zones.jsonlesen. Erzählebenen kommen inzones.hugLeft/hugRight— saubere Streifen, die AN die Silhouette GRENZEN (Text weit vom Körper entfernt wirkt als schwebend, nicht eingebettet; ferne Ecken sind der Notfallplan, nicht der Standard). Der Held standardmäßig aufheroAnchor/heroBands.best(auf das Motiv zentriert, ~30–55 % verdeckt).recommendation:"fg"verschiebt die ERZÄHLUNG zur Lesbarkeit in den Vordergrund; der Held bleibt eingebettet, wann immerheroBands.feasible— Held-Vordergrund ist die letzte Option. - Die DNA ist die Identität, die Sie in Schritt 0 ausgewählt haben
Schritt 3 — Themenmodus (komponierte Verfassung)
- Zuerst
safe-zones.jsonlesen für Körper-/Held-Positionierung. theme.jsongemäß der Verfassung des gewählten Themas schreiben: Sieg-Bedingung, DNA kennzeichnet den komponierten Look. Siehe themes/README.md für vollständige Details und dastheme.json-Schema.bash scripts/render-theme.sh <projekt>ausführen — dies kompiliert + rendert + wendet Plattenreaktions-FX an →final_fx.mp4.
Visuelle Qualitätskontrolle (muss vor Schritt 5 erfolgen)
Überprüfen Sie die generierten Composite-Vorschauen in <projekt>/preview/.
# Standard-Prüfung
ls <projekt>/preview/ # 5–10 repräsentative Vorschauen
# Detaillierte Inspektion mit Zwischensequenzen
node scripts/preview-frames.cjs <projekt> --skip-rail # überspringt Schienen-Vorschauen für schnelle Embed-Inspektion
Zu prüfende Dinge:
- Embed-Positionierung. Ist der Held ~30–55 %verdeckt und auf das Motiv ausgerichtet? Text darf sich nicht mit Gesicht/Mund/Mimik überschneiden. Nicht verdeckter Text schwebt im Vordergrund — lesbar, aber nicht filmisch.
- Schienen-Lesbarkeit. Untere Drittel-Position, sauberer Kontrast. Nicht mit bestehenden UI-Elementen/Logos überlappend. Wörtlich und genau.
- Timing. Stimmen die Ein-/Ausgänge mit dem natürlichen Sprachrhythmus überein? Der Compiler gibt Timing-Warnungen aus; achten Sie darauf.
- Kein Text auf reinem Hintergrund (z.B. Himmel). Der Matte-Container des Helden muss das Motiv für Verdeckung überlappen.
- Luminanz-Prüfung. Helle Szenen ≠ heller Text. Kontrollieren Sie die Glyphen-Scrim-Anwendung.
- Platten-FX (Themenmodus). Reaktionsbeats sind dramaturgisch angemessen und nicht übertrieben.
Wenn der Look falsch ist, ändern Sie die Autoren-Entscheidungen und führen Sie Schritt 3 erneut aus — kein erneutes Rendern der gesamten Pipeline.
Fehlerbehebung
| Problem | Ursache | Lösung |
|---|---|---|
transcribe.cjs ist still/leer | Audio nahezu still oder Whisper-Modell-Halluzination | WHISPER_MODEL=medium versuchen; wenn immer noch leer, ablehnen (es ist kein gesprochener Inhalt vorhanden) |
matte.cjs erzeugt flackernde Silhouette | Schnelle Kamerabewegung oder geringer Kontrast Motiv/Hintergrund | Clip zuschneiden auf ruhige Sequenz; manuelle Keyframe-Anpassungen sind nicht unterstützt |
| Embed erscheint vor dem Motiv, nicht dahinter | Falsche zones.hugRight/hugLeft für Embed-Positionierung | safe-zones.json neu lesen; wenn heroBands nicht realisierbar, recommendation:"fg" setzen |
| Plattenreaktion ist übertrieben | theme.json-Amplituden zu hoch | theme.json-Parameter gemäß Themen-DNA anpassen; siehe themes/<thema>/dna.json für gültige Bereiche |
| Schiene überlappt mit bestehender UI/Logo | safe-zones.json hat die falsche Safe-Zone-Definition | safe-zones.json manuell anpassen, um die Überlappung auszuschließen; preview-frames.cjs erneut laufen lassen |
render-and-composite.sh hängt | Rendering stürzt in der CLI ab oder das Zeitlimit wird überschritten | Rendering normal über das Terminal abbrechen; große partielle Dateien sind kein Beweis für den Abschluss. HYPERFRAMES_ROOT prüfen |
Referenzen
- CATALOG.md — 35 Identitäten, Single Source of Truth für die Weiterleitung
- themes/README.md — vollständige Themen-Verfassungs-Dokumentation
- references/rail.md — Regeln für Schienen-Bildunterschriften (vereinfacht)
- references/composition-craft.md — umfassende Embed-Craft-Regeln
scripts/prepare.sh— parallel: Freistellung + Transkription + Hüllkurve → sichere Zonen (ein Befehl)scripts/make-cinematic.cjs— kompiliertcinematic.jsoninplan.json(reine Embed-Vorlage)scripts/render-theme.sh— kompiliert + rendert + fügt Plattenreaktions-FX hinzu (Themenmodus:final_fx.mp4)scripts/render-and-composite.sh— Rendering-Tor + Composite + Snapshot (Standardmodus:final.mp4)scripts/preview-frames.cjs— schnelle Vorschau der Composite (~2s/Bild) vor dem Rendering