quibex/reel-subs

reel-subs — Untertitel & Animationen für Reels

Du verwandelst einen fertig geschnittenen Talking-Head-Export (aus CapCut / Premiere / Handy) in ein Reel mit phrase-by-phrase Untertiteln und sauberen Bewegungsgrafiken. Alles läuft lokal auf dem Rechner des Nutzers.

Wie es funktioniert: Sprache → Wörter mit Zeitangaben (sherpa-onnx, offline) → du schreibst edit.json (Untertitel + Grafikelemente) → Remotion rendert NUR eine transparente Grafikebene → ffmpeg legt sie über das unberührte Quellvideo mit dessen eigenen Farbeinstellungen. Niemals das gesamte Video durch Remotion rendern: das kodiert mit einer anderen Farbmatrix neu und verschiebt die Hauttöne.

SKILL_DIR unten = der Ordner, der diese Datei enthält. ENGINE = ~/.reel-subs/engine (unter Windows %USERPROFILE%\.reel-subs\engine; oder $REELS_HOME/engine, falls diese Umgebungsvariable gesetzt ist). Alle Skripte sind reine Node-Skripte – führe sie mit node aus, auf macOS, Windows und Linux gleichermaßen.

Sprich mit dem Nutzer in seiner Sprache. Antworte in der Sprache, in der der Nutzer dir schreibt (normalerweise Russisch), auch wenn diese Datei auf Englisch ist: Fortschrittszeilen, Fragen, Fehler, die abschließende Zusammenfassung. Befehle, Pfade und JSON-Schlüssel bleiben wie sie sind.

Lies zuerst die Präferenzen des Nutzers. Falls ~/.reel-subs/preferences.md existiert (oder $REELS_HOME/preferences.md), lies es vor Schritt 1 und befolge es: es enthält, worum der Nutzer in früheren Sitzungen gebeten hat, und überschreibt die Standardwerte in dieser Datei. Siehe „Die Vorlieben des Nutzers lernen“ unten.

0. Einrichtung (beim ersten Mal, oder wenn doctor NICHT BEREIT meldet)

node SKILL_DIR/scripts/setup.mjs            # Russisches Spracherkennungsmodell (Standard)
node SKILL_DIR/scripts/setup.mjs --lang multi   # Englisch + 24 europäische Sprachen

Erfordert nur Node.js 18+. Falls node fehlt, sage dem Nutzer, er solle die LTS-Version von nodejs.org installieren (macOS: brew install node funktioniert auch; Windows: winget install OpenJS.NodeJS.LTS) und brich ab. Das Setup kopiert die Engine nach ENGINE, führt npm install aus (Remotion, ffmpeg/ffprobe-Binärdateien, sherpa-onnx), lädt das Spracherkennungsmodell (~170 MB ru / ~490 MB multi) und Headless Chrome herunter. Es ist idempotent. Dauer beim ersten Mal 2–5 Minuten – sag das in einem Satz. Es endet mit READY.

Wenn ✗ headless browser ausgegeben wird: Der Chrome-Download von Remotion ist in diesem Netzwerk blockiert und es wurde kein installiertes Chrome/Edge gefunden → bitte den Nutzer, Google Chrome zu installieren, und führe das Setup erneut aus.

1. Vorbereiten

node ENGINE/scripts/prepare.mjs "<video>" [--lang ru|multi] [--audio clean_voice.wav]

• --lang: ru (GigaAM, am besten für Russisch) oder multi (Englisch, Deutsch, Spanisch, Französisch, Ukrainisch…). Wähle anhand der im Video gesprochenen Sprache; frage nur, wenn es unklar ist. Fehlende Modelle werden automatisch heruntergeladen.
• --audio: falls der Nutzer eine bereinigte Sprachspur hat (Auphonic, Adobe Podcast…), verwende sie – bessere Erkennung, und der Render fügt sie in das finale Video ein.
• Erstellt <video name>.reels/ neben dem Video: transcript.txt, words.json, edit.json (Entwurf).
• Stoppt bei HDR-Video mit einer Erklärung (Überlagerung auf HDR verschiebt Farben) – leite sie an den Nutzer weiter.

2. Das Video verstehen

1. Lese transcript.txt (Phrasen mit Zeitcodes) und überfliege words.json für genaue Wortzeiten.
2. Betrachte die Einzelbilder: node ENGINE/scripts/look.mjs "<video>" --every 1 → öffne das Übersichtsbild. Notiere, wo das Gesicht ist (oben / Mitte), wo die Hände gestikulieren, wo ein Bildschirm / Produkt gezeigt wird, wo Schnitte stattfinden. Bei einem langen Video in Teilen (--from 0 --to 30).

3. Untertitel korrigieren (edit.json → captions)

Die Seiten des Entwurfs sind bereits nach Phrasen aufgeteilt (~2 s, ≤ 32 Zeichen). Deine Aufgabe:

• Erkennungsfehler korrigieren: Produktnamen, englische Begriffe, Zahlen (четыре бакса → $4), Markenschreibweisen. Die Erkennung hat keine Satzzeichen – füge nur hinzu, was das Lesen unterstützt, meist nichts.
• Behalte die eigenen Worte und Sprache des Sprechers bei; übersetze nicht, es sei denn, du wirst darum gebeten.
• Fasse Seiten zusammen / teile sie auf, so dass jede eine natürliche Phrase darstellt. Halte startMs/endMs an words.json ausgerichtet.
• Markup im Untertiteltext: *Wort* → Akzentfarbe (selten, für das Schlüsselwort), ~Wort~ → rot (ein Versprecher, über den der Sprecher scherzt).
• Liste Wörter, bei denen du unsicher warst, in deiner abschließenden Nachricht auf, anstatt stillschweigend zu raten.

4. Grafiken planen (edit.json → items)

Vollständige Feldreferenz mit Beispielen: SKILL_DIR/reference/edit-schema.md – lies es, bevor du Items schreibst.

• hook – die ersten 2–4 s, bis zum ersten Schnitt oder Witz: die Essenz des Videos in einem kurzen Satz, in der Sprache des Sprechers. Untertitel werden automatisch ausgeblendet, während es angezeigt wird.
• card – ein Schlüsselpunkt: label (Kapitälchen) + title und/oder chips, die zu den Wörtern erscheinen, die sie illustrieren (at), on: true für den Ergebnis-Chip, strikeAt um etwas durchzustreichen.
• big – eine Zahl oder ein Wort, das der Sprecher betont („$1“, „5000“).
• terminal – nur, wenn über Code, Agents, Befehle gesprochen wird.
• punch – ein Witz / Selbstironie: a wird durchgestrichen, b erscheint groß. Untertitel werden automatisch ausgeblendet.
• pop – kleine HUD-Widgets, die neben den Händen einrasten, wenn der Sprecher gestikuliert („und diese Animationen gehen…“). Platziere sie ~0,3 s vor dem Wort: erkannte Zeitangaben hinken hinterher.
• badge – ein dauerhaftes Etikett oben links (Folgennummer usw.), nur wenn der Nutzer es wünscht.

Regeln:

• Verdecke niemals das Gesicht. Karten standardmäßig im oberen Drittel (top: 260). Wenn das Gesicht in der oberen Hälfte des Bildes ist, verwende top: 1110 (tief). Verdecke auch nicht, worauf der Sprecher zeigt.
• Alles bleibt innerhalb der sicheren Zone (Karten sind 840 px breit, zentriert) – verschiebe nichts an die Ränder.
• Dichte: durchschnittlich eine Grafik pro 5–10 s, zeitlich auf die Wörter abgestimmt. Keine Untertitel-in-einer-Box, die das Gesagte wiederholen, kein Offensichtliches erklären, keine wackelige/kindische Bewegung.
• Erste Erwähnung eines Produkts/Projekts: die Karte sollte in wenigen Worten sagen, was es ist – Zuschauer sind neu.
• Zeiten sind Sekunden im Quellvideo. Items können Untertitel überlappen; hook/punch blenden sie aus.
• Keine Fakten erfinden: Chips und Karten sagen genau das, was der Sprecher sagt.

5. Vorschau – immer vor dem vollständigen Render ansehen

node ENGINE/scripts/preview.mjs "<work>/edit.json"            # Ein Bild pro Item
node ENGINE/scripts/preview.mjs "<work>/edit.json" --at 1.2,7,15

Öffne previews/sheet.jpg (und einzelne at_<t>.jpg bei Bedarf). Prüfe: Gesicht frei, Text passt, nichts berührt die Ränder, Untertitel lesbar. Korrigiere edit.json und mache erneut eine Vorschau. ~10–30 s pro Durchlauf.

6. Rendern

node ENGINE/scripts/render.mjs "<work>/edit.json" [--out datei.mp4]

~1–4 min pro Minute Video. Ausgabe standardmäßig <video name>_final.mp4 neben der Quelle. Es gibt die Anzahl der Ausgabebilder im Vergleich zur Quelle aus – bei MISMATCH, informiere den Nutzer. Gib dem Nutzer dann: den Ausgabepfad, eine 2–3-zeilige Zusammenfassung dessen, was du hinzugefügt hast, unsichere Wörter.

Überarbeitungen

Bearbeite edit.json → mache eine Vorschau der geänderten Momente → rendere erneut. Führe niemals prepare.mjs --force aus, nachdem der Nutzer die Untertitel genehmigt hat (es würde sie zurücksetzen). Kopiere edit.json vor größeren Änderungen.

Die Vorlieben des Nutzers lernen

Das Skill sollte mit jeder Nutzung besser für diesen Nutzer werden. Seine Notizen leben in ~/.reel-subs/preferences.md ($REELS_HOME/preferences.md falls gesetzt) – außerhalb des Skill-Ordners und außerhalb von ENGINE, sodass ein Update des Skills oder ein erneutes Setup sie niemals löscht.

Wann anbieten zu speichern:

• Der Nutzer korrigiert zweimal die gleiche Art von Sache (Schriftart, Farben, Untertitelgröße oder -position, wie viel Grafik, Hook-Formulierung, welche Wörter die Betonung bekommen…).
• Der Nutzer sagt so etwas wie «запомни», «в следующий раз делай так», «мне так больше нравится».
• Am Ende einer Sitzung mit Überarbeitungen: Liste die Korrekturen in 2–4 kurzen Zeilen auf und frage einmal, ob sie für das nächste Mal gespeichert werden sollen.

Wie:

• Frage immer zuerst, zeige genau, was du schreiben wirst, schreibe nur nach einem Ja. Speichere niemals eigenständig.
• Schreibe Regeln, keine Historie: «Schriftgröße der Untertitel größer: captionSize 60», «Hook ohne Emojis», «Maximal eine Karte pro 10 s». Gruppiere sie unter kurzen Überschriften (Style, Captions, Graphics, Wording). Aktualisiere oder entferne eine alte Regel, anstatt eine widersprüchliche hinzuzufügen.
• Style-Werte, die edit.json → style unterstützt, werden als exakte Werte angegeben, sodass du sie in jede neue edit.json kopieren kannst.
• Wenn ein Wunsch eine Codeänderung erfordert (eine neue Schriftart, eine neue Animation, ein anderes Kartenaussehen), nimm sie in ENGINE/src/ vor und dokumentiere sie auch unter Engine changes in preferences.md: welche Datei, was geändert wurde, warum. Das Setup kopiert die Engine erneut und überschreibt bearbeitete Dateien (neue Dateien bleiben erhalten). Überprüfe daher nach jedem Setup-Durchlauf diese Liste und wende an, was fehlt.
• Der Nutzer kann preferences.md auch von Hand bearbeiten oder dir einfach sagen, was du darin ändern sollst.

Anpassung

• Farben / Größen: edit.json → style (accent, captionSize, captionTop, font).
• Neue Grafikarten: Füge eine Komponente in ENGINE/src/components/, einen Typ in src/types.ts und einen Fall in src/Overlay.tsx hinzu – das Bundle wird bei der nächsten Vorschau automatisch neu erstellt. Halte die Ebene transparent (kein Hintergrund, kein Video in Remotion).
• npm run studio innerhalb von ENGINE öffnet Remotion Studio für Live-Anpassungen.

Fehlerbehebung

• doctor: node ENGINE/scripts/doctor.mjs – gibt ✓/✗ für jede Abhängigkeit aus.
• Warnung zu variabler Bildrate → bitte den Nutzer, mit konstanten 30 oder 60 fps zu exportieren.
• Nicht 9:16 – die Grafiken sind für vertikale Videos ausgelegt; sie werden skaliert, um zu passen, aber sag es.
• Windows: Verwende die gleichen Befehle; setze Pfade mit Leerzeichen in Anführungszeichen. PowerShell und cmd funktionieren beide.
• Nichts wird hochgeladen: Modelle und Chrome werden einmal heruntergeladen, dann läuft alles offline.