Communitygithub.com

yazzang-homelab/motion-studio

Erstelle, debugge oder beschleunige die Seek(t)-Render-Engine: Render-Vertrag, Canvas- vs. Page-Capture, Worker/Subframes/Chunks, Determinismus-Korrekturen, Übergabe an Remotion oder HyperFrames. Verwende dies bei 'Render ist langsam', 'Frames unterscheiden sich', 'Nutze Remotion'.

Was ist motion-studio?

Dieses Skill für KI-Agenten (wie Claude Code, Cursor oder Codex) bietet eine vollständige Render-Engine für programmatische Filme, die auf der Idee basieren, dass ein Film ein Programm und kein Video ist. Die Engine zeichnet exakte Frames für jede Zeit `t`, ohne von einer Uhr abhängig zu sein, sodass jeder Render-Vorgang identisch ist und ein Fix nur eine einzeilige Änderung plus einen erneuten Render erfordert. Sie unterstützt Canvas-Capture (Standardeinstellung) für von `<canvas>` gezeichnete Filme und Page-Capture für DOM-basierte Filme, wobei Subframes und Motion Blur zur Steigerung der visuellen Qualität integriert sind. Das Skill enthält Befehle für Live-Vorschau, Umgebungsprüfung, schnelle Pacing-Checks und finale Render für mehrere Formate, wobei es die Arbeit auf mehrere Worker in einem einzigen Browser verteilt. Determinismus wird durch einen Hash-basierten Ansatz sichergestellt: `__studio.hash(t)` berechnet einen SHA-256-Hash der Roh-Pixel jedes Frames, und die `critique`-Komponente validiert diese Hashes über mehrere Durchläufe und Worker-Konfigurationen hinweg. Das Skill behandelt auch die Übergabe an Drittanbieter-Plattformen wie Remotion oder HyperFrames und stellt sicher, dass die Filmcode-Regeln (kein `Math.random`, keine `Date`, keine zustandsbehafteten Werte) eingehalten werden, um bitgenaue Ergebnisse auf derselben Maschine zu gewährleisten. Fehlerbehebung, Performance-Knöpfe (Worker-Anzahl, Skalierung, Subframes, FPS, Draft-Qualität) und eine vollständige Befehlsreferenz sind in der Dokumentation enthalten.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/yazzang-homelab/motion-studio/tree/HEAD/skills/seek-engine

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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älfteDateienAufgabe
Seiteindex.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
Treibertools/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

MitgliedVertrag
?format=9x16&scale=1&render=1Query, 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.readyPromise; löst auf, nachdem Config, Beat-Gitter, Schriftarten (loadFonts bestätigt jede Schriftart) und setup() abgeschlossen sind
__studio.errorString-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() / gridSFX-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) / textTrackdie 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

ZielBefehl
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 rendernnpm run render
Einen Zeitbereich für eine Prüfung rendernnode tools/render.mjs --from 4 --to 6 --draft --out out/check (schreibt out/check/<fmt>/clip_4.00-6.00.mp4)
Jedes Format rendernnpm 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 Segmentenode tools/render.mjs --format all --final --chunk 10
Hash-Manifest pro Framenode 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

ModusGesetzt durchWie ein Frame erstellt wirdVerwendung 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ückalles, was auf <canvas id="stage"> gezeichnet wird
pageFactory gibt capture: 'page' zurück oder studio.json "capture": "page"seek(t) dann page.screenshot pro Unterframe; ffmpeg tmix + select mischt jede GruppeDOM-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.

FlagStandardEffektWann
--workers Nmin(4, max(1, floor(cpus / 3)))parallele Seiten in einem Browser speisen einen geordneten Encodererhöhe auf großen Maschinen; verringere, wenn RAM knapp ist
--scale s1Canvas = even(round(W x s)); 0,5 = ein Viertel der PixelEntwürfe, Standbilder langer Filme
--sub Nstudio.subframes (4)Unterframes pro Frame--sub 1 für Entwürfe; 8 für schnelle Bewegungen
--fps Nstudio.fps (60)Ausgabebildrate30 für Animatics
--draftausencode.previewPreset + CRF 23jeder nicht finale Render
--crf N / --preset p16 / slowx264 Qualität / Geschwindigkeitfür Finale lassen
--chunk Sausfortsetzbar out/<fmt>/.parts/seg_<a>_<b>.mp4, dann concat -c copyFilme über ~30 s, ein Finale von drei Formaten, Über-Nacht-Läufe (eine Unterbrechung setzt dann fort, anstatt neu zu starten)
--no-posterPoster anPoster-Standbild überspringenBatch-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):

EinrichtungZeit pro AusgabeframeZeit 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 msetwa 24 min
In-Seite-Akkumulation mit 4 Seiten (dieselbe synthetische Szene, nur Capture, pixelidentisch)etwa 148 msetwa 2,2 min
dieser Renderer Ende-zu-Ende auf dem 12 s Demo-Film der Vorlage, finaler x264-Encode123 ms in 9x16, 75 ms in 1x1, 118 ms in 16x91,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

  1. npm run critique führt die Determinismusprüfung durch: __studio.hash zu 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.json listet jede nicht übereinstimmende t auf.
  2. 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/a und node tools/render.mjs --from 0 --to 2 --hash --draft --no-poster --json --workers 4 --out out/check/b. Ein Bereich berührt niemals silent.mp4. Jeder Lauf schreibt out/check/<a|b>/<fmt>/clip_0.00-2.00.mp4 plus .json und .sha256 (eine Zeile pro Frame: index t sha256), und seine --json-Zeile meldet framesDigest, den sha256 der Hash-Spalte, verbunden durch Zeilenumbrüche. Gleiche framesDigest-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.sha256 beendet mit 0, wenn sie übereinstimmen, und git diff --no-index zeigt den ersten Frame, der sich unterscheidet. Verwende niemals md5, das es unter Windows oder Linux nicht gibt.
  3. Hashe nicht die mp4: Die x264-Ausgabe ändert sich mit der Thread-Anzahl, daher unterscheiden sich mp4-Hashes zwischen Maschinen. Der framesDigest deckt 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

SymptomUrsacheBehebung
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 foundnicht im PATH, ffmpeg-static fehltnpm i -D ffmpeg-static oder setze FFMPEG_PATH; npm run doctor gibt OS-spezifische Befehle aus
spawn EINVAL in deinem eigenen Skript unter Windowsnpm/npx .cmd-Shims ohne Shell spawnenverwende spawn('npm.cmd', args, { shell: true }); die Tools tun dies bereits
font missing: 700 64px "X" oder Ready-TimeoutSchriftart nicht gebündelt oder falsch geschriebennpm run fonts -- add "X:400,700"; verwende die Namen in studio.json brand.fonts
leere oder teilweise Frames, Seitenfehler im LogAusnahme innerhalb einer Szenenzeichnungder Treiber gibt __studio.error und Konsolenfehler aus; reproduziere mit npm run preview zu dieser Zeit

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

yazzang-homelab/motion-studio

Make Claude watch its own frames: critique.mjs evidence, harsh 7-axis scores, timestamped P0/P1/P2 problems in docs/review_log.md, fix the 3 worst, re-check, pass the gate. Use for 'critique it', 'review the frames', 'is it good'.

yazzang-homelab/motion-studio

Plan long-form or overnight films: director's brief (PLAN FIRST or GO, budget, definition of done), ANIMATION_GUIDE + STORYBOARD, chapter subagents, gates, chunked render. Use for 'overnight film', 'music video', '2-minute film'.

yazzang-homelab/motion-studio

Make a launch video, app or product reel, explainer or motion ad from code, end to end: brand assets from a URL, beat-grid shot list, synced sound, critique loop, all formats. Default for new video requests; not footage edits.

yazzang-homelab/motion-studio

Brand-asset stage of a product film (motion-reel runs the whole film): capture real screenshots, logo, colors and fonts from a URL, never redraw UI; brand story beats; voice + mascot. Use to grab or fix a brand's assets.

yazzang-homelab/motion-studio

Turn a reference (a frame, a video or an image library) into docs/style_guide.md and a beat-grid shot list: measure cuts, palette and pace, take grammar not content, wait for OK. Use when the user supplies or names a look.

yazzang-homelab/motion-studio

Ship every format from one timeline, then package it: layout() reframing (never crop), render all formats, per-format checks, deliver.mjs, a brand skill, a service offer. Use for 'export 9:16 and 16:9', 'deliver', 'make a skill'.

yazzang-homelab/motion-studio

The viral one-line 'showreel for a résumé' prompt: why it works (anatomy), the credited quote, and seeded variants that avoid look-alike reels; runs it as an engine test. Use for that prompt, its variations, or a showreel.

yazzang-homelab/motion-studio

Score a film to its beat grid: measure a track (beats.mjs) or synthesize one (score.mjs), cue SFX from the film, add voice, mix to -14 LUFS / -1 dBTP at exact length. Use for 'add music', 'sync to the beat', 'SFX', 'loudness'.

yazzang-homelab/motion-studio

Make motion feel physical with closed-form springs from lib/motion.js: presets, springFromFeel, track() for multi-target values, loopTrack loops, indicators, text swaps. Use for 'feels linear', 'add bounce', 'easing to springs'.

yazzang-homelab/motion-studio

Scaffold a motion-studio film project (seek(t) renderer, springs, beat grid, synthesized sound, critique tools), install it, set up the browser, run doctor. Use for 'set up the motion studio', 'new film project', 'init studio'.

yazzang-homelab/motion-studio

Write a six-part XML state spec for a one-shape UI morph film (inputs, direction, structure, build, gotchas, start): states on downbeats, cursor-driven changes, seamless loop, approval gate. Use for 'UI morph', 'state list'.

Verwandte Skills