Plugin-Installation: Befolgen Sie vor Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln, wenn sich diese Fähigkeit innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die folgenden Aktualisierungshinweise.
Halten Sie diese Fähigkeit zunächst aktuell – bestätigen Sie mit dem Benutzer, bevor Sie Folgendes ausführen:
npx hyperframes skills update embedded-captions. Eine schnelle No-Op, wenn alles aktuell ist; andernfalls wird diese Fähigkeit zusammen mit den Kernfähigkeiten der Domäne aktualisiert, bevor Sie sich darauf verlassen.
Eingebettete Untertitel
Ein Katalog, vorab ausgewählt (CATALOG.md – 35 Identitäten; die dahinterstehenden Engines sind Backend-Details). Standard (Standard) erstellt eine saubere wörtliche Rail (Untertitelleiste im unteren Drittel, die den Großteil des Textes trägt) + einen Embed-Höhepunkt, der am Höhepunkt in die Szene hinter der Person eingefügt wird. Cinematic ist reines Embed – keine Rail, jeder Untertitel wird hinter der Person eingefügt (heroische Typografie, Akkumulation, Verdeckung als Effekt). Theme ist eine vollständige thematische Verfassung – Körperparadigma × heroisches Setpiece × Front-Effekt × Plattenreaktion, zusammengesetzt aus Registern (themes/README.md): ordnance terminal neonsign stardust stomp. Die meisten Erklär-/Voiceover-Videos verwenden Standard; Embed ist der seltene, verdiente Höhepunkt – jeden Satz einzubetten ist der häufige Fehler; Theme ist für VFX-Anfragen gedacht („炸“, „特效“, „wie in AE gemacht").
Laufzeitvoraussetzungen
Plugin-Installationen verwenden die gebündelte, manifest-verankerte CLI für Matting, Transkription und Rendering; kein Source-Checkout erforderlich. Die lokale Vorschau und die Hilfsprogramme zur Untertitelvermessung 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. Matting und Transkription laden möglicherweise bei erster Verwendung eigene Modelle herunter.
Das Rendering wartet auf den erfolgreichen Abschluss der CLI, bevor es die Compositierung durchführt. Der alte Shell-Watchdog HF_TIMEOUT_S 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 Mitwirkenden-CLI aus anstatt des Plugin-Pins. Brechen Sie ein hängendes Rendering normal über die CLI/das Terminal ab; das Untertitel-Hilfsprogramm beendet oder stellt ein Rendering aus einem Prozess-Snapshot nicht zwangsweise wieder her.
Arbeitsablauf (TL;DR)
Über /hyperframes geroutet, bestätigt die Intent-Ebene nur die Eingabe (welcher Clip) und kündigt die Identitätsauswahl als aufgeschobene Anfrage an – die Shortlist benötigt den untersuchten Clip, daher bleibt sie bei Schritt 1 unten; die Fragen zur Ausführungsform der Ebene treffen nicht zu (das Filmmaterial ist unberührt, es gibt kein Storyboard zu überprüfen). Eine BRIEF.md enthält, falls vorhanden, die bestätigte Eingabe und alle Benutzernotizen – lesen Sie diese zuerst.
Der folgende handwerkliche Text ist lang; die Pipeline selbst ist kurz – und alles Deterministische wird berechnet oder kompiliert, niemals von Hand geschrieben:
- Entscheidungstor (schlechte Clips ablehnen) → EINE Identität aus CATALOG.md auswählen (35 Identitäten; Engine/Compiler durch Nachschlagen abgeleitet – niemals eine Modus-/Kategoriefrage stellen)
hyperframes init(überspringen, wenn das Projektverzeichnis bereits existiert und das Video darin liegt –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)- Erstellen Sie ein kleines 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/Gedicht/Übernahme-Paradigmen;anchorist die Standard-Rail) - Visuelle Qualitätssicherung:
node scripts/preview-frames.cjs <project>→ originalgetue Composite-Vorschauen in ~2s/Frame (kein Rendern). Überprüfen Sie § Visuelle Qualitätssicherung, bevor Sie für ein Rendern bezahlen. render-and-composite.sh→ Tore (Timing / Verdeckung+Held / Überlauf / Übergabe) →final.mp4
Wichtige Regeln, die oft übersehen werden:
- Rail (Standard) + Embed (Promotion).
drop(Füller, nicht angezeigt) /rail(wörtliche Untertitelleiste im unteren Drittel, vorne, trägt den meisten Text) /embed(ein Höhepunkt-Wort, das hinter der Person eingefügt wird). Der Standardmodus macht beides und bettet nur die Höhepunkte ein. Siehe § Untertitelmodell. - Das Video wird UNBERÜHRT ausgeliefert (Standard/Cinematic; Das PLATE-Budget des Theme-Modus ist die einzig zugelassene Ausnahme – registrierte Reaktionsbeats (Aufladungs-Dim, Punch, Shake, Grain), die pro Theme-DNA definiert sind und NACH der Matte-Composite angewendet werden, sodass sich Person+Text+Platte als ein Frame bewegen) – Untertitel sind das einzige, was hinzugefügt wird; die Matte dient nur dazu, dass die Person die Embed-Spur verdecken kann. Niemals das Filmmaterial gradieren/nachfärben/überlagern.
- Zwei Regelwerke: Rail → references/rail.md (dünn), Embed-Craft → references/composition-craft.md (reichhaltig, nur Embed). Nach Bedarf überfliegen.
Untertitelmodell – Rail + Embed
Jeder gesprochene Satz ist eines von drei Dingen:
| Was | Wie es angezeigt wird | |
|---|---|---|
| drop | Füllwörter – ähm/äh, Stottern, Selbstkorrekturen | nicht angezeigt |
| rail | der Standard – normale gesprochene Inhalte (wörtlich) | saubere Untertitelleiste im unteren Drittel, vorne, lesbar. Ein Punch-Wort kann eine inline emphasis-Hervorhebung erhalten (Akzentfarbe/aktives Wort-Pop) – es bleibt auf der Rail. |
| embed | ein promovierter Höhepunkt – das Schlagzeilen-Beat | ein großes Wort, das hinter der Person eingefügt wird (Matte-Verdeckung), mit gestaltetem 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 Held pro Block (Gedanke), niemals zwei gleichzeitig sichtbar, mindestens ein Beat Luft zwischen Heldenfenstern (der Compiler warnt unter 0,6s). Ein kurzer Clip → normalerweise 1–2; eine lange Erklärung → etwa einer pro Abschnitt. Bei mehreren Helden ist der größte erstellte der APEX (nur er erhält die vollständige Lockup-Einbettung + Breitenanpassung); kleinere sind MINOR-Peaks, die ihre 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. Jeden Satz einzubetten ist immer noch der häufige Fehler.
Rail-Oberflächen-Identitäten bauen genau dies (Rail = rail.html, Embed = der Höhepunkt in index.html). Spaltenfluss-Identitäten lassen die Rail weg und machen alles im Embed-Stil – empfehlen Sie diese nur für stimmungsbetonte/wörtliche 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 – EINE Identität aus dem KATALOG auswählen
Ein Frontend, drei Engines dahinter. Der Benutzer wählt eine IDENTITÄT aus CATALOG.md (35 Einträge: 10 klassische + 25 themenbasierte); die Engine, der Compiler und die Erstellungsdatei 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 kodiert alles, was das Routing benötigt: Lesefläche, Stimme, Empfehlungsgrund, 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): im autonomen Modus („überrasche mich"/„entscheide für mich") wählen Sie selbst aus Ihrer Shortlist und nennen den einzeiligen Grund anstatt zu fragen.
Vorgehensweise: Clip untersuchen → 2–3 Identitäten aus dem Katalog in die Shortlist aufnehmen → EINE mit einzeiligem Grund empfehlen → der Benutzer wählt aus (autonomer Modus: Sie wählen aus, nennen den Grund) → die Datei dieser Identität erstellen. Identitäten sind engine-gesperrt (keine Cross-Kombos; das Öffnen einer Identität 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 die Standardeinstellung zurückfallen.
(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 Erstellungsvertrag 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 ein benannter Look erstellt wird; dieser hier 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 hat, worin er montiert werden könnte. Ein Registerblock stylt Text auf einer gestalteten Leinwand; diese Fähigkeit brennt Untertitel in das Filmmaterial einer Person mittels einer Matte. Wenn keine Identität zur Anfrage passt, sagen Sie das und wählen Sie die nächstbeste, anstatt außerhalb des Katalogs zu suchen.
Empfehlungsheuristik: Verwenden Sie die „Shortlisting-Hürden" in CATALOG.md – sie sind auf Identitätsebene (z. B. „炸" shortlistet ordnance/stomp/terminal/loud und wählt aus, 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, erstellen Sie
theme.json, führen Siescripts/render-theme.shaus (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 Szene getrennt rendern oder ablehnen)
- Kein menschliches Motiv (diese Fähigkeit 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 dies 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 unberührt ausgeliefert (kein Abdecken/Nachmalen). Eingebrannter Text erscheint oft nur mittendrin: Mustern Sie ein 1fps-Kontaktbogen (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), vertrauen Sie nicht auf 3 Einzelframes. - Transkription ist Müll – nicht-muttersprachliche/stark akzentuierte Sprache kann in sicheres Kauderwelsch transkribiert werden. Lesen Sie
transcript.jsonauf Plausibilität, bevor Sie etwas erstellen; wenn es sich nicht wie Sprache anfühlt, versuchen Sie es einmal mitWHISPER_MODEL=medium, sonst ablehnen (eine wörtliche Rail aus erfundenen Wörtern ist schlimmer als keine Untertitel). - Verwackelte Handkamera mit schneller Bewegung (Matte flackert)
Preflight-Sonden (kosten nichts, verhindern die schlimmsten Fehler)
- Schnitt-Sonde. Mustern Sie Frames bei 20%, 50%, 80%. Wenn ein anderes Motiv/Szene erscheint, schneiden Sie den Clip vor dem Schnitt.
- Letterbox-/Pillarbox-Sonde. Schwarze Balken auf dem ersten Frame? Berechnen Sie das sichere Inhaltsrechteck und beschränken Sie die Untertitelplatzierung darauf.
- Luminanz-Sonde. Messen Sie die durchschnittliche Luminanz des Untertitelbereichs –
unter 60→ heller Text lesbar wie er ist,60-180→ Glyphen-Schirm hinzufügen,180+→ opaker Text + Schirm (niemals nackten hellen Text). Cinematic-Vorlagen sind creme+screenund GESPERRT – verwenden Sie diese Sonde, um eine passende Identität auszuwählen (helle Szenen →ink, oder die opake Railanchor-Theme), niemals um eine neu 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 → Rail/Panel-Oberflächenidentitäten; poetisch / sozial / „cinematic" → Spaltenflussidentitä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 ein kleines JSON; 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 + Platten-FX)
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> # Tore → final.mp4 + history/ Snapshot
(Theme-Modus: 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 1 init überprü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 – 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; ferne Ecken sind die Ausweichlösung, nicht der Standard). Der Held standardisiert aufheroAnchor/heroBands.best(zentriert AUF dem Motiv, ~30–55% verdeckt).recommendation:"fg"verschiebt ERZÄHLUNG nach vorne für Lesbarkeit; der Held bleibt eingebettet, wann immerheroBands.feasible– Held-FG ist die letzte Lösung. - Die DNA ist die Identität, die Sie in Schritt 0 ausgewählt haben. ...