Plugin-Installation: Befolgen Sie vor dem Ausführen von Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln, wenn sich diese Fähigkeit in einem HyperFrames-Plugin befindet. Bei eigenständigen Installationen gelten die folgenden Aktualisierungshinweise.
Aktualisieren Sie diese Fähigkeit zuerst — Fragen Sie den Benutzer vor der Ausführung:
npx hyperframes skills update embedded-captions. Eine schnelle No-Operation, wenn alles aktuell ist; andernfalls wird diese Fähigkeit sowie die Kern-Domänenfähigkeiten, von denen sie abhängt, aktualisiert, bevor Sie sich auf sie verlassen.
Was macht 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 (Untertitel im unteren Drittel, die den Großteil des Textes tragen) + einen Embed-Höhepunkt, der in die Szene hinter dem Motiv auf dem Höhepunkt eingefügt wird. Cinematic ist reines Embed — keine Rail, jeder Untertitel wird hinter dem Motiv eingefügt (Hero-Typografie, Akkumulation, Verdeckung als Effekt). Theme ist eine vollständig thematische Verfassung — Körper-Paradigma × Hero-Setpiece × Front-Effekt × Platten-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-würdige Anfragen ("炸", "特效", "像 AE 做的").
Laufzeitvoraussetzungen
Plugin-Installationen verwenden das gebündelte, manifest-verankerte CLI für Freistellung, Transkription und Rendering; kein Quellcode-Checkout erforderlich. Die lokale Vorschau- und Untertitelmaß-Hilfsprogramme 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 <Projekt> --save-dev --save-exact [email protected] [email protected] [email protected]
Behalten Sie die Lockfile 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 sein. Freistellung und Transkription laden möglicherweise bei erster Verwendung eigene Modelle herunter.
Das Rendern wartet, bis das CLI erfolgreich beendet wurde, bevor es das Compositing 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 Rendern abgeschlossen wurde. Ein explizites --built-checkout-Argument oder HYPERFRAMES_ROOT wählt das Beitrags-CLI anstelle des Plugin-Pins aus. Brechen Sie ein hängendes Rendern normal über das CLI/Terminal ab; das Untertitel-Hilfsprogramm beendet oder stellt ein Rendern nicht zwangsweise aus einem Prozess-Snapshot wieder her.
Betriebsablauf (TL;DR)
Über /hyperframes geroutet, bestätigt die Intentionsebene nur die Eingabe (welcher Clip) und kündigt die Identitätsauswahl als aufgeschobene Frage an — die Shortlist benötigt den untersuchten Clip, also bleibt sie bei Schritt 1 unten; die Run-Shape-Fragen der Ebene treffen nicht zu (das Filmmaterial ist unberührt, es gibt kein Storyboard zu überprüfen). Eine BRIEF.md, falls vorhanden, enthält die bestätigte Eingabe und alle Benutzernotizen — lesen Sie diese zuerst.
Die folgende Handwerksprosa ist lang; die Pipeline selbst ist kurz — und alles Deterministische wird berechnet oder kompiliert, niemals von Hand geschrieben:
- Entscheidungstor (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 <Projekt>(Freistellung ∥ Transkription ∥ Audio-Hüllkurve parallel, dann Safe-Zones v2 mit Szenenpalette/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 ruhige Rail-Voreinstellung) - Visuelle Qualitätssicherung:
node scripts/preview-frames.cjs <Projekt>→ getreue Verbundvorschauen in ~2s/Bild (kein Rendern). Prüfen Sie § Visuelle Qualitätssicherung, bevor Sie für ein Rendern bezahlen. render-and-composite.sh→ Tore (Timing / Verdeckung+Hero / Überlauf / Übergabe) →final.mp4
Tragfähige Regeln, die Leute übersehen:
- Rail (Standard) + Embed (Höherstufung).
drop(Füllmaterial, nicht angezeigt) /rail(wörtlicher Untertitel im unteren Drittel, vorne, trägt den meisten Text) /embed(ein Höhepunktswort, das hinter dem Motiv eingefügt wird). Der Standardmodus macht beides und bettet nur den/die Höhepunkt(e) ein. Siehe § Untertitelmodell. - Das Video wird UNBERÜHRT geliefert (Standard/Cinematic; das PLATE-Budget des Theme-Modus ist die einzig erlaubte Ausnahme — registergesteuerte Reaktionsbeats (Ladungsabdunklung, Schlag, Schütteln, Körnung), die pro Theme-DNA definiert und NACH dem Matte-Composite angewendet werden, sodass Motiv+Text+Platte sich als ein Rahmen bewegen) — Untertitel sind das Einzige, was hinzugefügt wird; das Matte lässt das Motiv nur die Embed-Spur verdecken. Niemals das Filmmaterial abtönen/umfärben/Scanlines hinzufügen.
- Zwei Regelwerke: Rail → references/rail.md (dünn), Embed-Handwerk → references/composition-craft.md (reichhaltig, nur Embed). Überfliegen Sie nach Bedarf.
Untertitelmodell — Rail + Embed
Jede gesprochene Phrase 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 Untertitel im unteren Drittel, vorne, lesbar. Ein Schlagwort kann eine Inline-emphasis-Hervorhebung erhalten (Akzentfarbe / aktives Wort-Pop) — es bleibt auf der Rail. |
| embed | eine höhergestufte Spitze — der Schlagzeilenbeat | ein großes Wort, das hinter dem Motiv eingefügt wird (Matte-Verdeckung), gestalteter Ein- und Ausgang |
Die Rail 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,6s). Ein kurzer Clip → normalerweise 1–2; ein langes Erklärvideo → ~einer pro Abschnitt. Unter mehreren Heroes ist der größte erstellte der APEX (er allein erhält das volle Lockup-Embed + Breitenanpassungserhöhung); kleinere sind MINOR-Peaks, die auf ihrer Spalte als übergroße Hervorhebungszeilen (Vordergrund, gedämpfte Bewegung) reiten — nicht jeder Beat braucht die Matte-Inszenierung, und genau das hält den Apex zu einem Ereignis. Jedes Wort einzubetten ist immer noch der häufige Fehler.
Rail-Oberflächenidentitäten bilden genau dies ab (Rail = rail.html, Embed = der Höhepunkt in index.html). Spaltenflussidentitäten verwerfen die Rail und machen alles im Embed-Stil — empfehlen Sie diese nur für Anfragen, bei denen Stimmung über Wörtlichkeit geht, niemals für Erklär-/Voiceover-Videos, bei denen die Worte lesbar sein müssen (CATALOG.md kodiert 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 Authoring-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 kodiert alles, was das Routing benötigt: Lesefläche, Stimme, Empfehlung-für, Szenenanforderungen, Nähehinweise 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): Im autonomen Modus („überrasche mich“ / „entscheide für mich“) wählen Sie aus Ihrer Shortlist selbst aus und nennen das Einzeiler-Warum anstatt zu fragen.
Verfahren: Clip untersuchen → 2–3 Identitäten aus dem Katalog kurzlisten → EINE mit einem Einzeiler-Warum empfehlen → der Benutzer wählt (autonomer Modus: Sie wählen und nennen das Warum) → die Datei dieser Identität erstellen. Identitäten sind engine-gesperrt (keine Querkombos; 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 voreingestellt.
(Die vollständige Identitätstabelle befindet sich in CATALOG.md — einzige Quelle der Wahrheit für das Routing. Die Engine-Dokumente unten beschreiben den Authoring-Vertrag 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 erstellen; dieser hier darf das nicht. Seine Engines sind gesperrte Compiler, die cinematic.json / theme.json konsumieren und die Komposition selbst ausgeben, sodass ein Registereintrag — die caption-*-Blöcke eingeschlossen — nichts hat, worin er eingehängt werden könnte. Ein Registerblock gestaltet Text auf einer entworfenen Leinwand; diese Fähigkeit brennt Untertitel in das Filmmaterial einer anderen Person durch ein Matte. Wenn keine Identität zur Anfrage passt, sagen Sie das und wählen die nächstgelegene, anstatt außerhalb des Katalogs zu suchen.
Empfehlungsheuristik: Verwenden Sie die „Shortlisting-Heuristiken“ in CATALOG.md — sie sind identitätsbasiert (z. B. „炸“ listet ordnance/stomp/terminal/loud kurz und wählt basierend darauf, WAS explodieren soll), niemals kategoriebasiert. 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 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 (jede Einstellung einzeln rendern & ablehnen)
- Kein menschliches Motiv (diese Fähigkeit ist für Talking-Head)
- Unter 3 Sekunden, keine Sprache, oder Gesicht nie deutlich sichtbar —
transcribe.cjswarnt, wenn Audio nahezu still ist (Whisper halluziniert Wörter wie „Danke.“ über Stille); beachten Sie das und lehnen Sie ab, anstatt erfundene Wörter zu untertiteln - Quelle hat bereits eingebrannte Untertitel / Untertitel / schwere Textgrafiken — das Hinzufügen eines zweiten Untertitelsystems verursacht Konflikte und das Filmmaterial wird unberührt geliefert (kein Abdecken/Inpaint). Eingebrannter Text erscheint oft nur in der Mitte des Clips: 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 einzelne Frames. - Transkription ist Müll — nicht-muttersprachliche/stark akzentuierte Sprache kann sich in zuversichtliches Kauderwelsch transkribieren. Lesen Sie
transcript.jsonvor dem Erstellen; wenn es sich nicht wie eine Sprache anhört, versuchen Sie es einmal mitWHISPER_MODEL=medium, lehnen Sie es sonst ab (eine wörtliche Rail aus erfundenen Wörtern ist schlimmer als keine Untertitel). - Hektische Handkamera mit schneller Bewegung (Matte flackert)
Vorflug-Untersuchungen (kosten nichts, verhindern die schlimmsten Fehler)
- Einstellungs-Schnitt-Untersuchung. Rahmenproben bei 20 %, 50 %, 80 %. Wenn ein anderes Motiv/eine andere Szene erscheint, schneiden Sie den Clip vor dem Schnitt.
- Letterbox-/Pillarbox-Untersuchung. Schwarze Balken im ersten Rahmen? Berechnen Sie das sichere Inhaltsrechteck und beschränken Sie die Untertitelplatzierung darauf.
- Luminanz-Untersuchung. Messen Sie die durchschnittliche Luminanz des Untertitelbereichs —
unter 60→ heller Text liest sich wie er ist,60-180→ Fügen Sie den Glyphen-Scrim hinzu,180+→ deckender Text + Scrim (niemals nackten hellen Text). Cinematic-Vorlagen sind creme+screenund GESPERRT — verwenden Sie diese Untersuchung, um eine passende Identität auszuwählen (helle Szenen →inkoder die deckende Railanchor-Theme), niemals, um eine umzufärben. - Identitätsempfehlung nach Ton (Sie empfehlen; der Benutzer wählt — siehe Schritt 0 + CATALOG.md). Erklärvideo / Interview / Worte müssen lesbar sein → Identitäten mit Rail/Panel-Oberfläche; poetisch / sozial / „cinematic“ → Spaltenfluss-Identitäten nach Register; „炸 / 特效 / VFX“ / benannte Welten → thematische Identitäten. Wenn unsicher →
anchor(Worte 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> # Freistellung ∥ Transkription (parallel) → Safe-Zones. Ein Befehl.
# → frames_fg/ transcript.json safe-zones.json
3. [AGENTEN-SCHRITT — der einzige kreative Schritt] Erstellen Sie ein kleines JSON; siehe unten nach Modus
Cinematic: Erstellen Sie cinematic.json → node scripts/make-cinematic.cjs <Projekt>
Theme: Erstellen Sie theme.json → bash scripts/render-theme.sh <Projekt> (kompiliert + rendert + Platteneffekte)
4. node scripts/preview-frames.cjs <Projekt> # ~2s/Rahmen-Verbundvorschauen → § Visuelle Qualitätssicherung (VOR dem Rendern)
5. bash scripts/render-and-composite.sh <Projekt> # Tore → final.mp4 + history/ Schnappschuss
(Theme-Modus: SCHRITTE 3b/5 ÜBERSPRINGEN — render-theme.sh führt bereits Kompilierung + render-and-composite
+ _postfx.sh aus; das Auslieferungsobjekt ist final_fx.mp4, final.mp4 ist vor der Plattenreaktion)
Schritt 1 init überprüft die installierten Fähigkeiten auf dem neuesten Stand auf GitHub und aktualisiert den globalen Satz, wenn eine veraltet ist.
Schritt 3 unterscheidet sich je nach Modus:
Schritt 3 — Cinematic-Modus (reines Embed)
- Lesen Sie zuerst
safe-zones.json. Erzählungsebenen gehen inzones.hugLeft/hugRight— saubere Streifen GRENZEND an die Silhouette (Text weit vom Körper entfernt liest sich als schwebend, nicht eingebettet; entfernte Ecken sind die Ausweichlösung, nicht die Voreinstellung). Der Hero standardmäßig aufheroAnchor/heroBands.best(ZENTRIERT auf dem Motiv, ~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 Option. - Die DNA ist die Identität, die Sie in Schritt 0 ausgewählt haben. Lesen Sie
dna/<identität>.md. Wenden Sie ihr Typografie-/Timing-Preset auf die JSON-Felder an. Dercinematic.json-Vertrag benötigt:hero(Schlüsselwort, Timing, Band, „Hero-Embed“ ist die einzige Rolle; setzen Sierole: "emphasis"für MINOR-Peaks, der größte ist der APEX)narration(Sequenz von{phrase, timing, location: hugLeft|hugRight|corner, role}, wo jede Phrase einbreakdownvon Wörtern sein kann; setzen Sierecommendation:"fg"bedeutet, dass die Narration VORNE landet, wobei die letzte führende Phraserole: "lead-in"ist)
- Führen Sie
node scripts/make-cinematic.cjs <Projekt>aus (es liestcinematic.jsonundsafe-zones.json, leitet das vollständige Layout ab, mit Fehlerprüfung und taktilem Feedback). Ausgabe:plan.json(vollständig kompilierte Szenenaufteilung — Animationen, Übergänge) undindex.html/rail.html(gerendert durch die Identitäts-Engine nach Modellprinzip).
Schritt 3 — Theme-Modus
- Lesen Sie themes/README.md und das DNA des ausgewählten Themas (
dna/<name>.md). Das Theme-Definition enthält: Typografie-Palette, Timing-Budget (Beats für den Aufbau, zeigen, verblassen), Effektkarte (Front-Effekte, Platten-Reaktions-Trigger), das Körper-Paradigma (siehe unten). - Erstellen Sie
theme.json— ein einzelnes JSON-Objekt mit:identity(Zeichenfolge, muss mit dem Katalogeintrag übereinstimmen)hero(Array von Hero-Ereignissen: jedes mit{phrase, startBeat, endBeat, location: hinter|vorne, emphasis: boolean})narration(Array von Erzählungsblöcken: jedes mit{phrases: [{text, emphasis: boolean}], startBeat, endBeat, location: links|rechts|mitte|über|unt— ungültige Standorte werden in der thematischen DNA pro Thema neu zugeordnet)plate(optional — ein Objekt{reaction: ladungsabdunklung|schlag|schütteln|körnung, triggerBeat}, Gültigkeit registergeprüft)scene(optional —{palette: [hex...], lighting: weich|hart, mood: düster|hell|neutral}— validiert gegen die Themen-DNA, die Palette überstimmt das Standard-Background-Overlay, aber nicht das Video selbst)- Das
postfx.sh-Hook des Themas kann den Platteneffekt ändern, aber immer innerhalb des Registervertrags. Der Compiler warnt bei Abweichungen, lehnt aber nicht ab.
- Führen Sie
bash scripts/render-theme.sh <Projekt>aus — es kompiliert die Szene, rendert den Verbund (in zwei Durchgängen mit einem temporären Zwischenergebnis für die Plattenreaktionssynthese) und wendet dann den Platteneffekt an. Ausgabe:final_fx.mp4(das Auslieferungsobjekt). Das Skript protokolliert die Kompilierungswarnungen und die Engine-Preset-Anwendung; die Felder intheme.jsonkönnen während der Laufzeit nicht überschrieben werden. Wie bei Cinematic erfordert der Theme-Modus, dass Sie die Genehmigung zur Ausführung des Renderings einholen, indem Sie Bilder aus Schritt 4 überprüfen.
Visuelle Qualitätssicherung (vor dem endgültigen Rendern)
Führen Sie node scripts/preview-frames.cjs <Projekt> aus. Es erzeugt getreue Rahmenvorschauen (keine temporäre Wiedergabe), die der Benutzer genehmigen muss, bevor Sie Schritt 5 ausführen. Überprüfen Sie:
- Verdeckung. Der Embed-Text erscheint hinter dem Motiv. Wenn die Freistellung nicht gut ist (z. B. fehlende Gliedmaßen, flackernde Ränder), ziehen Sie das Freistellungsmodell in Betracht oder wechseln Sie zu einer Rail/Ink-Identität, die den Text vorne hält.
- Position. Der Rail-Text ist im unteren Drittel, der Embed-Text ist zentriert auf dem Körper oder der bandenfähigen Zone. Wenn der Text vom Bildschirm abgeschnitten wird (Safe-Zone-Problem), kehren Sie zu Schritt 2 zurück und überprüfen Sie
safe-zones.jsonoder ändern Sie intheme.jsondielocation. - Lesbarkeit des Glyphen-Scrim. Wenn der Text schwer zu lesen ist (helles Video, weißer Text), kehren Sie zu Schritt 3 zurück und passen Sie den Glyphen-Scrim in der Konfiguration an, oder wählen Sie eine deckende Identität.
Referenzen
- CATALOG.md — Vollständiger Identitätskatalog (35 Stile)
- references/rail.md — Regeln für Rail-Untertitel (Standard-Textanzeige)
- references/composition-craft.md — Anleitung zur Embed-Komposition (nur Hero-Höhepunkte)
- themes/README.md — Theme-Registerdokumentation (Ordnance, Terminal, Neonsign, Stardust, Stomp)
- dna/README.md — Identitäts-DNA-Definitionen und Validierungsregeln
- ../hyperframes/references/brief-contract.md — Vertrag für das Briefing des HyperFrames-Agenten
- ../hyperframes/references/plugin-installation.md — Plugin-Installationsregeln
Lizenz & Urheberrecht
Diese Fähigkeit ist Teil des HyperFrames-Projekts. Siehe Lizenzinformationen im Stammverzeichnis des Repositorys.