muneebsajjad/demo-reel

Was macht demo-reel?

Sie produzieren das gesamte Video selbst: Die Person gibt Ihnen das Produkt und was gezeigt werden soll, und erhält eine MP4-Datei zurück, die sie posten kann. Alles auf dem Bildschirm ist das echte Produkt, live aufgenommen; die Verfeinerung (Fensterrahmen, Kamerabewegungen, Untertitel, Titel- und Endkarten) wird im Anschluss aus der Aufnahme hinzugefügt.

Die Pipeline und die Datei, die jeder Schritt erzeugt:

Schritt	Befehl	Erzeugt
1. Storyboard	Sie, mit der Person	3–5 Funktionen, jeweils ein Untertitel
2. Szenario	scenario.mjs schreiben	Die Schritte, die ein Benutzer ausführen würde
3. Aufnahme	bin/reel take scenario.mjs takes/take1	take1.mov (Bild + Ton der App), take1.json (Ereignisse, Elementpositionen)
4. Bearbeitung	edit.json schreiben	Szenen, Aufnahmen, Untertitel, Marke
5. Standbilder	bin/reel check edit.json, bin/reel layers edit.json, dann bin/reel stills edit.json 1,4,9	Probleme frühzeitig erkannt; Vorschaubilder
6. Untertitel	bin/reel subtitles edit.json, dann build/subtitles.srt lesen und korrigieren	Was gesagt wird, als Untertitel
7. Rendern	bin/reel render edit.json renders/x.mp4 --format all	Das Video in jedem Format, mit zugehöriger .srt
8. Prüfung	bin/reel sheet renders/x.mp4 1,4,9,…	Kontaktbogen, Länge, Lautstärke

examples/sawt/ ist ein vollständiges, ausgearbeitetes Beispiel (eine Chrome-Erweiterung, die Artikel vorliest). Öffnen Sie dessen scenario.mjs und edit.json, bevor Sie Ihre eigenen schreiben. docs/edit-format.md ist die Referenz für die Bearbeitungsdatei; docs/lessons.md listet auf, was beim ersten Mal schiefging – lesen Sie es vor der Aufnahme.

0. Einrichtung (einmalig)

Führen Sie zuerst bin/reel doctor aus: Es überprüft jedes Werkzeug und jede Berechtigung und sagt, was zu beheben ist. bin/reel setup erstellt den Rekorder (Swift, ScreenCaptureKit), installiert playwright-core und Chrome for Testing. Außerdem erforderlich: ffmpeg, uv, Google Chrome (zum Rendern der Overlay-Ebenen). Das Terminal, das Sie ausführt, benötigt die Berechtigung Bildschirm- und Systemaudiowiedergabe (Systemeinstellungen → Datenschutz & Sicherheit); wenn der Rekorder meldet, dass er nicht berechtigt ist, bitten Sie die Person, diese zu gewähren und das Terminal neu zu starten.

1. Storyboard

Vereinbaren Sie vor der Aufnahme in wenigen Zeilen:

• Die Funktionen in Reihenfolge, jeweils mit einem Untertitel: einem kurzen Teaser („Wort-Zoom“) und einer Überschrift von höchstens zwei kurzen Zeilen, wobei der Nutzen in <b> steht („Folgen Sie mit. Jedes Wortwächst beim Vorlesen.“);
• Welche echten Inhalte für die Demo verwendet werden sollen: eine öffentliche Seite, ein Beispielkonto, Seed-Daten. Wählen Sie Inhalte, die die Funktion bestmöglich zur Geltung bringen, und überprüfen Sie dies (bei Sawt: ein Artikel, dessen schwierige Wörter Karten erhalten, auf einer Seite, auf der die Karten neben der Spalte Platz haben);
• Die Marke: Akzentfarbe, eine helle Variante, Hintergrundtönungen, Logo; Text für Titel- und Endkarte.

Standardformat: 1080×1350 (4:5), 25–35 s – es füllt den meisten Platz im Smartphone-Feed, und die meisten schauen stummgeschaltet zu, daher müssen die Untertitel die Geschichte allein erzählen. Fragen Sie, wo es gepostet wird: 1:1, 9:16 und 16:9 werden aus derselben Bearbeitung erstellt (--format), bieten Sie sie an. Überprüfen Sie Standbilder jedes Formats, das Sie rendern: Eine Aufnahme, die in 4:5 gut passt, kann in 1:1 eine Überschrift abschneiden; passen Sie sie pro Format an ("1:1": {"dy": 20}).

Wenn das Produkt spricht (oder die Aufnahme einen Kommentar enthält), erstellen Sie Untertitel: reel subtitles, lesen Sie dann die .srt und korrigieren Sie Namen und Fachbegriffe vor dem Rendern – die Transkription ist gut, aber nicht perfekt. Fügen Sie schwierige Wörter in subtitles.words ein, um sie zu lenken.

2. Szenario

Ein Szenario ist ein ES-Modul (siehe drive/take.mjs für die vollständige API):

export const config = { url: "https://…", width: 1700, height: 1090, extension: "./ext" };
export async function setup(api) { /* Einstellungen, Login; api.rect("title", "h1") für Kameraziele */ }
export async function run(api)   { /* Die Demo; api.mark("step") bei jedem Moment, an dem Sie schneiden werden */ }
export async function after(api) { /* Standbilder, die als Bildszenen angezeigt werden, z. B. ein Popup bei 3x */ }

• Markieren Sie jeden Moment, an dem Sie schneiden oder die Kamera bewegen werden (api.mark("sentence", {n})). Die Bearbeitung verankert sich an diesen Markierungen, sodass eine Aufnahme, die schneller oder langsamer läuft, dennoch an der richtigen Stelle schneidet.
• Nehmen Sie Kameraziele mit api.rect(name, selector | fn, arg) in Viewport-Pixeln auf. Elemente in einem geschlossenen Shadow Root können nicht gemessen werden: Berechnen Sie, wo sie sein werden (siehe die Sawt-Karten).
• Klickgesteuerte Produkte benötigen einen sichtbaren Zeiger. Die Automatisierung bewegt keinen echten Cursor, daher erscheinen Formen und Schaltflächen drücken sich von selbst. Rufen Sie api.pointer.show() in setup auf, steuern Sie dann mit api.pointer.click(selector | [x, y]), .drag(from, to), .move(x, y), .type(text) und .key(k): Ein Pfeil auf der Seite folgt, Klicks erzeugen Wellen, Bewegungen sind abgerundet und die Texteingabe hat menschlichen Rhythmus. Steuern Sie Klicks per Selektor (ein title oder aria-label ist in der Regel stabil), sodass ihre Positionen von der Seite stammen.
• Canvas-Inhalte (Zeichnungen, Diagramme, Karten) haben keine messbaren Elemente: Nehmen Sie die Box, in die Sie gezeichnet haben, mit api.rect(name, {x, y, width, height}) in CSS-Pixeln auf.
• Chrome-Erweiterungen: Führen Sie Aktionen über den eigenen Code der Erweiterung mit api.inWorker(fn) aus. Eine Erweiterung, die auf activeTab angewiesen ist, benötigt eine Aufnahmekopie mit Host-Zugriff, da die Automatisierung keine Browser-Tastenkürzel drücken kann (siehe examples/sawt/prepare.sh). Ändern Sie nichts, was ein Betrachter sieht.
• Popups und andere kleine UI-Elemente: Nehmen Sie sie in after() mit deviceScaleFactor 3 via CDP auf (siehe das Beispiel) und zeigen Sie sie als Bildszene. Nehmen Sie beide Zustände eines Umschalters zum gleichen Zeitpunkt auf, indem Sie das echte Steuerelement anklicken, nicht durch Neuladen.

Führen Sie es aus, dann sehen Sie sich die Aufnahme an, bevor Sie sie bearbeiten: ffmpeg -ss 6 -i takes/take1.mov -frames:v 1 x.png und lesen Sie das PNG. Überprüfen Sie, ob die Seite gestylt ist, die Funktion ausgelöst wurde, nichts sie verdeckt. Wiederholen Sie die Aufnahme ruhig – eine Aufnahme kostet eine Minute.

3. Bearbeitung

Schreiben Sie edit.json (Referenz: docs/edit-format.md). Regeln, die es professionell aussehen lassen, nicht wie eine Aufnahme:

• Schneiden Sie in Pausen. bin/reel speech take1.mov listet auf, wo Ton ist; nehmen Sie Stücke kurz vor einem Schritt und enden Sie vor dem nächsten Schritt. Verankern Sie sie an Markierungen: "sentence#5-0.15".
• Nebeneinander angeordnete Inhalte passen nicht in hohe Fenster. Eine Symbolleiste links und ein Diagramm rechts benötigen möglicherweise mehr Breite, als ein 4:5-Fenster zeigt; reel check warnt pro Format, wie viel eine eingepasste Aufnahme verlieren wird. Passen Sie weniger Elemente ein, oder verschieben Sie die Aufnahme für dieses Format.
• Aufnahmen aus Rechtecken. {"fit": ["title", {"rect": "card1", "dh": 330}], "pad": 60}. Eine breite Einstellungsaufnahme, dann hineinzoomen zu dem, worüber der Untertitel spricht. Halten Sie Text im Output mindestens ~20 px hoch; eine weite Einstellung kann kurzzeitig kleiner sein, niemals lange.
• Ein Untertitel pro Szene, für die gesamte Szene sichtbar; wechseln Sie Untertitel nur bei einer Kamerabewegung.
• Lassen Sie Bewegungen atmen: 1,0–1,5 s pro Kamerabewegung, mindestens 1,5 s halten, nachdem sie angekommen ist.
• Titel-Karte 2–2,5 s, End-Karte 3–3,5 s. Bildszenen (ein Popup, ein Einstellungsfeld) 3–4 s.

Geschwindigkeit

Ein 30-Sekunden-4:5-Render dauert etwa 3 Minuten auf einem 6-Kern-Laptop: Bilder werden in parallelen Blöcken gerendert (standardmäßig 4; --jobs N), ohne Neucodierung zusammengefügt, und unveränderte Ebenen werden wiederverwendet. Während die Bearbeitung noch in Bewegung ist, verwenden Sie reel render … --draft (15 fps, schneller Encoder, etwa halbe Zeit) und reel stills; rendern Sie das Echte, sobald die Standbilder richtig aussehen.

4. Überprüfung, jedes Mal

1. bin/reel layers und bin/reel stills am Anfang, in der Mitte und am Ende jeder Szene sowie bei jeder Kamerabewegung. Lesen Sie jedes PNG. Achten Sie auf: abgeschnittenen Text oder UI an den Bildrändern, eine halb sichtbare Überschrift oben, einen Untertitel über etwas Wichtigem, ein Bild, das nur aus einer leeren Seite besteht.
2. Rendern, dann bin/reel sheet über das gesamte Video und lesen Sie es.
3. Die Länge sollte Ihren Planungen entsprechen; die Lautstärke etwa −16 LUFS, wenn das Produkt Ton erzeugt.
4. Synchronität: Der Moment, in dem ein Schritt auf dem Bildschirm erscheint, und sein Ton sollten mit der Aufnahme übereinstimmen.

Geben Sie dann der Person die MP4, zusammen mit dem Vorschaubild (build/layers/title.png), und sagen Sie klar, was echt ist und was für die Aufnahme geändert wurde.

Musik

Standardmäßig wählt das System einen Hintergrundtrack, der zum Video passt (docs/music.md): Es profiliert das Video (Länge, Sprache, Tempo, Untertitelwörter), bewertet lizenzierte instrumentale Kandidaten – der eigene music/-Ordner der Person, dann die gebündelte CC0-Bibliothek (library/), dann online nur, wenn nichts Lokales passt – nach gemessenem Tempo, Energie und Beständigkeit und behält den besten. Führen Sie reel music auto edit.json --audition renders/x.mp4 aus, um die Rangfolge zu sehen und eine Vorschau der besten Tracks zu erhalten. Sie können nicht hören, daher geben Sie der Person die Vorschauen, bevor Sie das Video als fertig bezeichnen. Wenn die besten Tracks nur per Link verfügbar sind (die Website blockiert Skript-Downloads), geben Sie der Person die Links; sie laden einen herunter und führen reel music add <datei> --candidate N aus. Wenn die Person einen eigenen Track mitbringt, zeichnen Sie dessen Lizenz mit reel music add auf und fügen Sie ihn in die Bearbeitung ein. Geben Sie ihnen immer die .credits.txt neben dem Render und sagen Sie, wenn die Lizenz eine öffentliche Nennung erfordert.

Grenzen

• Die Aufnahme ist nur unter macOS möglich (ScreenCaptureKit). Compositing und Ebenen laufen überall.
• Bisher nur Browser-Produkte; eine Desktop-App benötigt einen eigenen Treiber (Accessibility Scripting), aber der Rekorder (--app <bundle id>) und alles danach funktionieren bereits für jede App.
• Musik generieren (reel music generate) benötigt ein lokales Modell; ACE-Step wird vorgeschlagen, ist aber noch nicht mit demo-reel getestet.