Seek-Engine (Kursschritt 07)
Ein Film ist hier ein Programm, kein Video. Die Seite zeichnet den exakten Frame für jede Zeit t; der Renderer durchläuft die Zeit,
erfasst jeden Frame und leitet ihn an ffmpeg weiter. Nichts ist von einer Uhr abhängig, daher ist ein Render auf jedem Lauf identisch und eine
Korrektur ist eine einzeilige Änderung plus ein erneuter Render. Dies ist Route A, die Route, die Opus standardmäßig wählt. Verwende sie, es sei denn, der Benutzer
nennt Remotion oder HyperFrames (dann lies references/route-b.md).
Führe alles vom Filmprojekt-Root aus (dem Ordner mit studio.json). Wenn es keinen gibt, führe zuerst
/motion-studio:studio-init aus. Die Dateien dieses Skills befinden sich in ${CLAUDE_SKILL_DIR}; die relativen Links unten zeigen
dorthin (${CLAUDE_SKILL_DIR}/references/determinism.md, ${CLAUDE_SKILL_DIR}/references/route-b.md).
1. Die zwei Hälften
| Hälfte | Dateien | Aufgabe |
|---|---|---|
| Seite | index.html, film/film.js, lib/runtime.js (+ lib/*.js) | boot(film) lädt studio.json, audio/beats.json (optional) und gebündelte Schriftarten und gibt dann window.seek(t) und window.__studio frei |
| Treiber | tools/render.mjs (+ tools/studio.mjs) | stellt das Projekt auf http://127.0.0.1:<random> bereit, startet einen kopflosen Browser (Windows: Playwrights Headless-Shell, niemals einen installierten Chrome oder Edge; macOS und Linux: Chrome, Edge, dann den gebündelten), öffnet N Worker-Seiten, erfasst Frames in Reihenfolge, kodiert einen H.264-Stream |
Die Seite wird immer über http bereitgestellt. file:// unterbricht fetch('studio.json'), ES-Module und Pfade, die # oder % enthalten.
2. Der Render-Vertrag
| Mitglied | Vertrag |
|---|---|
?format=9x16&scale=1&render=1 | Query, die der Treiber sendet; format standardmäßig studio.primaryFormat, scale 0.1–1 |
window.seek(t, blur?) | synchrones Zeichnen der Zeit t; Schleifenfilme wickeln mit loopT ab, andere klammern auf [0, duration]; gibt true zurück. Das optionale zweite Argument { frameT, sub, subs } besagt, dass diese Zeichnung der Unterframe sub von subs des Ausgabeframes ist, zentriert auf frameT (Page-Capture sendet es für jeden Screenshot) |
__studio.ready | Promise; löst auf, nachdem Config, Beat-Gitter, Schriftarten (loadFonts bestätigt jede Schriftart) und setup() abgeschlossen sind |
__studio.error | String-Stack, wenn der Boot fehlschlug (der Treiber gibt ihn aus) |
__studio.meta | { title, duration, fps, format, width, height, logicalWidth, logicalHeight, scale, bpm, loop, capture } |
__studio.frame({ t, sub, shutter, fps, wrap }) | PNG-Daten-URL des Frames t; sub > 1 akkumuliert zentrierte Unterframes in der Seite (Bewegungsunschärfe); wrap: false zeichnet die rohe Zeit, die auf [0, duration] geklammert ist, selbst in einem Schleifenfilm |
__studio.hash(t, { wrap, sub, shutter, fps }) | sha256 der Roh-Pixel nach paint(t) (Determinismusprüfungen); hash({ t, wrap: false }) wird ebenfalls akzeptiert. hash(0) versus hash(duration, { wrap: false }) ist die Schleifen-Schließungs-Invariante |
__studio.pixels(t, w) | kleines RGBA-Thumbnail als base64 (Kritikmetriken); wickelt immer in Schleifenfilmen ab |
__studio.cues() / shots() / grid | SFX-Cues, Shot-Fenster, Beat-Gitter als JSON (gelesen von sfx.mjs, stills.mjs --shots, critique.mjs). shots() ist in Zeitreihenfolge und listet nur Szenen, niemals overlays; grid trägt hits |
__studio.textUse() / coverage(family, weight, style, chars) / textTrack | die Glyphenprüfung der Kritik. Mit window.__TEXT_TRACK__ = true vor dem Laden (oder ?texttrack=1) zeichnet lib/draw.js die Zeichen auf, die text(), kinetic() und textWidth() pro Schriftart zeichnen; textUse() löst [{ family, weight, style, chars }] für die bisher gezeichneten Frames auf (seek() zuerst durch den Film); coverage() löst { missing, checked } für eine Schriftart auf. Standardmäßig deaktiviert, ändert niemals ein Pixel; text() und kinetic() werfen keinen Fehler für eine nicht registrierte Schriftart |
Was eine Szene in c sieht, während ein Frame mit Bewegungsunschärfe erstellt wird: c.t ist die Zeit, die gezeichnet wird (die UNTERFRAME-Zeit, sodass
Bewegungsunschärfe von selbst entsteht), c.frameT die Mittenzeit des Ausgabeframes (gleich für jeden Unterframe), c.frame der Ausgabeframe-Index
floor(frameT x fps) (gleich für jeden Unterframe), c.sub / c.subs der Unterframe-Index und die Anzahl. Frame-indiziertes
Rauschen verwendet c.frame (grain(g, W, H, c.frame) sieht dann in Standbildern, Vorschau und Finale gleich aus), und für „auf Zweien“ verwendet man
stepTime(c.frameLt, 12). Details: docs/ARCHITECTURE.md Abschnitt 5.2 im Plugin.
Filmcode befolgt die Regeln in references/determinism.md. Die Kurzform: Jeder Wert ist eine
Funktion von t; gesäte Zufälligkeit pro Element mit rngFor(name, i); kein Math.random, Date, performance.now,
Timer, requestAnimationFrame, CSS-Übergänge oder Zustand, der zwischen Frames weitergegeben wird; Schriftarten und Assets sind lokale Dateien.
npm run lint prüft dies, und der Plugin-Hook lintet jede Bearbeitung von film/, lib/ und index.html.
3. Befehle
| Ziel | Befehl |
|---|---|
Live-Vorschau (Scrubben, Leertaste, Pfeile, [/] Shots, F Formate, G Sicherheitshilfslinien) | npm run preview |
| Umgebungsprüfung (Node, Playwright, Browser, ffmpeg, Schriftarten, Keys vorhanden) | npm run doctor |
| Standardbrowser für Windows installieren (Playwrights Headless-Shell, etwa 115 MB) | npx playwright install chromium-headless-shell (npm run setup:browser) |
| Schnelle Tempo-Prüfung (halbe Skalierung, 30 fps, keine Unschärfe) | npm run animatic (schreibt out/animatic/<fmt>/silent.mp4) |
| Primäres Format rendern | npm run render |
| Einen Zeitbereich für eine Prüfung rendern | node tools/render.mjs --from 4 --to 6 --draft --out out/check (schreibt out/check/<fmt>/clip_4.00-6.00.mp4) |
| Jedes Format rendern | npm run render:all |
| Finaler Render, alle Formate (blockiert, bis das Kritik-Gate bestanden ist; etwa 4 min für das 12 s Demo, also im Hintergrund ausführen) | npm run render:final |
| Lange Form, fortsetzbare Segmente | node tools/render.mjs --format all --final --chunk 10 |
| Hash-Manifest pro Frame | node tools/render.mjs --hash (schreibt frames.sha256; ein Bereich schreibt clip_<von>-<bis>.sha256) |
Ausgabe pro Format: out/<fmt>/silent.mp4, out/<fmt>/poster.png (bei studio.poster oder 0,35 x Dauer) und
out/<fmt>/render.json (fps, Frames, Worker, Browserversion, Capture, Encode-Einstellungen, Sekunden). mix.mjs liest
render.json für die exakte Audiolänge. Alles wird in out/<fmt>/.staging/ erstellt und als eine Einheit veröffentlicht: die
alten Dateien werden zuerst verschoben, die neuen werden mit silent.mp4 zuletzt eingefügt, und jeder Fehler setzt die alten
zurück. Wenn ein anderes Programm eine Ausgabedatei offen hält (ein Videoplayer, ein Bildbetrachter unter Windows), wartet der Render bis zu 30 s
(MOTION_PUBLISH_WAIT_MS), warnt zu Beginn, welche Dateien offen sind, und stoppt andernfalls mit cannot replace <file>: EBUSY ... und BEHÄLT den fertigen Render in out/<fmt>/.staging/ (die vorherigen Ausgaben bleiben unberührt). Schließe das
Programm und kopiere die Dateien aus .staging/ oder rendere erneut. Ein vollständiger Render mit --no-poster entfernt das vorherige
poster.png, und einer ohne --hash entfernt das vorherige frames.sha256, sodass keine Ausgabe einen älteren Schnitt beschreibt.
Ein Bereichs-Render ist nur partiell, wenn --from/--to Frames auslässt; er schreibt stattdessen clip_<von>-<bis>.mp4 mit eigener
.json und .sha256, ersetzt niemals silent.mp4 und kann nicht --final sein. Ein Bereich, der den gesamten Film abdeckt
(oder ein --to über das Ende hinaus), ist ein vollständiger Render. Halte Prüf-Render unter --out out/check, sodass out/<fmt>/ nur den
echten Film enthält.
4. Capture-Modi
| Modus | Gesetzt durch | Wie ein Frame erstellt wird | Verwendung für |
|---|---|---|---|
canvas (Standard) | nichts | __studio.frame zeichnet sub Unterframes bei t + ((j + 0.5) / sub - 0.5) * shutter / fps, summiert Pixel in der Seite, gibt ein PNG zurück | alles, was auf <canvas id="stage"> gezeichnet wird |
page | Factory gibt capture: 'page' zurück oder studio.json "capture": "page" | seek(t) dann page.screenshot pro Unterframe; ffmpeg tmix + select mischt jede Gruppe | DOM-Filme (gestylte Elemente, die von t aktualisiert werden) |
shutter 0,5 ist ein 180-Grad-Verschluss: Die Unschärfe erstreckt sich über ein halbes Frame-Intervall. Schnelle Whips und Schwenks können Geisterkopien zeigen
bei --sub 4; erhöhe auf --sub 8 für diese Filme. Page-Capture ist langsamer (ein Screenshot pro Unterframe) und erbt
DOM-Rendering-Unterschiede, also bevorzuge Canvas.
5. Performance-Knöpfe
Anzahl der Zeichnungen = Frames x Unterframes. Ein 12 s Film bei 60 fps mit --sub 4 sind 2.880 Zeichnungen pro Format.
| Flag | Standard | Effekt | Wann |
|---|---|---|---|
--workers N | min(4, max(1, floor(cpus / 3))) | parallele Seiten in einem Browser speisen einen geordneten Encoder | erhöhe auf großen Maschinen; verringere, wenn RAM knapp ist |
--scale s | 1 | Canvas = even(round(W x s)); 0,5 = ein Viertel der Pixel | Entwürfe, Standbilder langer Filme |
--sub N | studio.subframes (4) | Unterframes pro Frame | --sub 1 für Entwürfe; 8 für schnelle Bewegungen |
--fps N | studio.fps (60) | Ausgabebildrate | 30 für Animatics |
--draft | aus | encode.previewPreset + CRF 23 | jeder nicht finale Render |
--crf N / --preset p | 16 / slow | x264 Qualität / Geschwindigkeit | für Finale lassen |
--chunk S | aus | fortsetzbar out/<fmt>/.parts/seg_<a>_<b>.mp4, dann concat -c copy | Filme über ~30 s, ein Finale von drei Formaten, Über-Nacht-Läufe (eine Unterbrechung setzt dann fort, anstatt neu zu starten) |
--no-poster | Poster an | Poster-Standbild überspringen | Batch-Prüfungen |
Gemisst auf dem Referenz-Laptop (12-Thread i7-1255U, installierter Chrome, 1080x1920, 60 fps, 4 Unterframes, 4 Worker; der Windows-Standard ist jetzt die Headless-Shell, deren Geschwindigkeit pro Frame nicht neu gemessen wurde und die 15 bis 25 s pro Tool-Lauf für den Start auf einer Maschine mit Echtzeit-Antivirus hinzufügt, gemessen):
| Einrichtung | Zeit pro Ausgabeframe | Zeit für 15 s bei 60 fps |
|---|---|---|
| die Screenshot-pro-Unterframe-Schleife des Kurses (nur Capture, synthetische Szene mit 200 Bögen, Text und einem Verlauf) | etwa 1.575 ms | etwa 24 min |
| In-Seite-Akkumulation mit 4 Seiten (dieselbe synthetische Szene, nur Capture, pixelidentisch) | etwa 148 ms | etwa 2,2 min |
| dieser Renderer Ende-zu-Ende auf dem 12 s Demo-Film der Vorlage, finaler x264-Encode | 123 ms in 9x16, 75 ms in 1x1, 118 ms in 16x9 | 1,8 min in 9x16 (etwa 4 min für die drei Formate des 12 s Films) |
Die ersten beiden Zeilen sind der reine Capture-Benchmark, der das Design bestimmte; die letzte Zeile gibt an, was ein echter Film kostet, und ist
der Wert, der als Schätzung angegeben werden sollte (er steigt mit der Szenenkomplexität und mit anderen Programmen, die die Maschine belasten, bis zu
etwa 5 min für die drei Formate). x264 -preset slow kodiert etwa 18 fps bei dieser Größe, daher ist Capture der
Engpass. Fortschritt, fps und ETA werden einmal pro Filmsekunde auf stderr ausgegeben. Starte einen finalen Render im Hintergrund und frage
das Log ab; warte niemals im Vordergrund darauf.
6. Determinismus nachweisen
npm run critiqueführt die Determinismusprüfung durch:__studio.hashzu Zeiten, die jede Shot-Grenze und jeden Cue überschreiten (plus und minus einen Frame), Durchlauf A in Reihenfolge, Durchlauf B gemischt, Durchlauf C nach einem Neuladen.out/review/<fmt>/metrics.jsonlistet jede nicht übereinstimmendetauf.- Nach einem Bereichs-Render beweise, dass der Bereich deterministisch ist, mit zwei Hash-Rendern desselben Bereichs. Variiere die Worker-Anzahl,
damit auch Parallelität abgedeckt ist:
node tools/render.mjs --from 0 --to 2 --hash --draft --no-poster --json --workers 1 --out out/check/aundnode tools/render.mjs --from 0 --to 2 --hash --draft --no-poster --json --workers 4 --out out/check/b. Ein Bereich berührt niemalssilent.mp4. Jeder Lauf schreibtout/check/<a|b>/<fmt>/clip_0.00-2.00.mp4plus.jsonund.sha256(eine Zeile pro Frame:index t sha256), und seine--json-Zeile meldetframesDigest, den sha256 der Hash-Spalte, verbunden durch Zeilenumbrüche. GleicheframesDigest-Werte in jedem Format bedeuten identische Frames. Wenn sie sich unterscheiden, vergleiche die beiden.sha256-Dateien:git diff --no-index --quiet out/check/a/<fmt>/clip_0.00-2.00.sha256 out/check/b/<fmt>/clip_0.00-2.00.sha256beendet mit 0, wenn sie übereinstimmen, undgit diff --no-indexzeigt den ersten Frame, der sich unterscheidet. Verwende niemalsmd5, das es unter Windows oder Linux nicht gibt. - Hashe nicht die mp4: Die x264-Ausgabe ändert sich mit der Thread-Anzahl, daher unterscheiden sich mp4-Hashes zwischen Maschinen. Der
framesDigestdeckt die Frame-PNGs ab, die in den Encoder gehen, worum es beim Determinismus geht.
Das Versprechen sind bitidentische Frames auf derselben Maschine und Browser-Build (aufgezeichnet in render.json). Auf
unterschiedlichen Maschinen rastern Schriftarten unterschiedlich (DirectWrite, CoreText, FreeType); vergleiche visuell.
7. Fehlerbehebung
| Symptom | Ursache | Behebung |
|---|---|---|
Executable doesn't exist ... chromium_headless_shell, oder could not launch a browser: no safe browser found. (Windows) | Playwrights Headless-Shell wurde nicht heruntergeladen (npm install holt sie nicht) | npx playwright install chromium-headless-shell. Auf macOS und Linux funktioniert auch ein installierter Chrome oder Edge; unter Windows ist ein installierter Browser ein bewachtes Opt-in (studio.json "browser": "chrome", MOTION_BROWSER=chrome), weil jeder Start mit einem frischen Profil als fehlgeschlagener Windows-Logon zählt |
Windows-Konto gesperrt, Sicherheitsereignisse 4625 von chrome.exe, oder refusing to start chrome: N launches ... | ein installierter Chrome oder Edge wurde mit einem frischen Profil gestartet (Blank-Passwort-Test = fehlgeschlagener Logon) | wechsle wie oben zur Headless-Shell und setze MOTION_BROWSER / MOTION_CHROME_PATH zurück; die Bestätigungsbefehle und die Gründe sind in ${CLAUDE_SKILL_DIR}/../studio-init/references/troubleshooting.md, "Windows account gets locked out while rendering or testing" |
ffmpeg not found | nicht im PATH, ffmpeg-static fehlt | npm i -D ffmpeg-static oder setze FFMPEG_PATH; npm run doctor gibt OS-spezifische Befehle aus |
spawn EINVAL in deinem eigenen Skript unter Windows | npm/npx .cmd-Shims ohne Shell spawnen | verwende spawn('npm.cmd', args, { shell: true }); die Tools tun dies bereits |
font missing: 700 64px "X" oder Ready-Timeout | Schriftart nicht gebündelt oder falsch geschrieben | npm run fonts -- add "X:400,700"; verwende die Namen in studio.json brand.fonts |
| leere oder teilweise Frames, Seitenfehler im Log | Ausnahme innerhalb einer Szenenzeichnung | der Treiber gibt __studio.error und Konsolenfehler aus; reproduziere mit npm run preview zu dieser Zeit |