kylefritz/video-skill

Was macht video-skill?

Skripte liegen in scripts/ neben dieser Datei; schreibe es unten als $S, aber gib den absoluten Pfad in jedem Befehl aus, weil Shell-Variablen nicht zwischen Bash-Aufrufen weitergegeben werden.

Du kannst kein Video ansehen, daher wird jeder Schritt in etwas verwandelt, das du lesen kannst: Frames, die du dir ansiehst, und Zahlen, die du prüfst. Einen Film zu machen bedeutet: schreiben → Frames rendern → Kontaktbogen lesen → korrigieren. Material verstehen bedeutet: untersuchen → Proxy erstellen → Zeitgestempelte Bögen + Transkript → bewerten. Ausliefern bedeutet ein Skript, das Codec, Bildrate, Faststart und Lautstärke prüft, damit „es läuft überall“ eine Tatsache ist.

Erstmals auf einem Mac

Führe sh $S/setup.sh selbst aus. Es prüft mise und ffmpeg (installiert ffmpeg mit Homebrew, wenn möglich), installiert die festgelegte OpenFilm-Version bei der ersten Nutzung und führt openfilm doctor aus. Korrigiere jedes TODO, das es ausgibt, oder erkläre es der Person klar. Kann problemlos wiederholt werden.

Einen Film erstellen: OpenFilm

OpenFilm (MIT) ist das Autorenformat: Ein Film ist ein Ordner mit einer film.html, die HTML-Seiten, Filmmaterial, Bilder und Ton zusammenschneidet; jede Seite zeichnet jeden gefragten Moment t. Studio ist der lokale Browser-Editor.

1. Drucke das Handbuch und lies es vollständig (es ist kurz und ändert sich zwischen den Versionen): $S/openfilm. Folge ihm, wobei diese Datei Vorrang hat, wenn sie abweicht.
2. $S/openfilm ist der einzige Weg, OpenFilm hier auszuführen: Es legt die Version fest, installiert es bei der ersten Nutzung über mise und verhindert, dass Studio ein Browserfenster öffnet. Verwende nicht npx openfilm (umgeht die Festlegung) oder npx skills add openfilm/openfilm (ein Upstream-Skill, das mit diesem konkurriert).
3. FILM ist immer ein absoluter Pfad, $HOME/Movies/OpenFilm/Projects/<film-name>. Ein relativer Name landet im aktuellen Ordner, z. B. im Git-Repo einer Person. Filme kommen nie in ein Repo.

Schritt	Befehl
Erstellen oder öffnen	$S/openfilm open FILM
Ganzen Film prüfen	$S/openfilm -C FILM look
Moment, Abschnitt, Datei prüfen	… look 4.5, look 3-6, look assets/bed.wav
Schnellen Einstieg prüfen	… look 0-2 --count 24
MP4 rendern	$S/openfilm -C FILM render
Welche Mediendienste verbunden sind	$S/openfilm get
Installation diagnostizieren	$S/openfilm doctor

look und render laufen ohne geöffnetes Studio und geben Pfade relativ zu FILM aus. Die Adresse von Studio enthält einen Zugangsschlüssel: Gib ihn nur der Person, mit der du arbeitest (es ist 127.0.0.1, Chrome oder Edge, nicht vom Telefon).

Lies jeden look-Bogen, bevor du etwas zeigst, und behebe, was du siehst. Seine Prüfungen (gleiches t zeichnet das gleiche Bild, Schriftarten geladen, Text beschnitten, Lautstärke) sagen nichts über Geschmack oder Layout aus. Ein ! wegen abgeschnittenem Text während eines Einstiegs ist in Ordnung; abgeschnitten im Ruhezustand ist ein Fehler. Dann sieh dir ein paar Momente in voller Größe an (look 12.5): Eine 300 px-Kachel versteckt kleine Dinge, einschließlich Personen.

Wie ein Film aufgebaut wird, gelernt beim Erstellen eines:

• Eine Seite pro Einstellung; was Seiten gemeinsam haben (eine Ken-Burns-Bewegung, Schriftarten, Farben), kommt in ein Modul, das sie importieren. Jeder Wert ist nur eine Funktion von t: keine Timer, keine Animationsschleife, kein Zustand.
• Seiten blenden sich selbst ein/aus (Deckkraft von t); ein Schwarzblend zwischen Einstellungen auf einer Spur ist der einfachste Übergang. Eine Überblendung benötigt die eingehende Einstellung auf einer Spur über der ausgehenden.
• Text über Fotos benötigt einen Schatten dahinter (einen unteren Farbverlauf), sonst verschwindet er in geschäftigen Szenen.
• Schriftarten kommen in FILM/fonts/ mit @font-face, erwartet über window.film.ready (document.fonts.ready). Bei Fotos: ready: img.decode().
• Schneiden mit #t=in,out, niemals durch Schneiden neuer Dateien; ein Ton, der länger als der Film ist, verlängert den Film.

Ton

$S/openfilm get zeigt, was verbunden ist; generierte Stimme, Musik und Effekte benötigen die eigenen Anbieterschlüssel der Person (Studio: OpenFilm-Logo → Einstellungen → Anbieter). Ohne diese erzeuge Ton mit ffmpeg, speichere ihn unter FILM/assets/, notiere den Befehl in FILM/sound-notes.txt, damit er neu erstellt werden kann, und sage, welcher Dienst es besser machen würde. Du kannst ihn nicht hören, also beurteile nach Zahlen:

• -16 LUFS integriert für einen fertigen Mix (Podcasts, die meisten Webvideos); Streaming-Plattformen normalisieren auf etwa -14. Halte den wahren Spitzenwert bei oder unter -1 dBTP. Eine Tonspur unter einer Stimme liegt bei etwa -22.
• Messen: ffmpeg -i X -af ebur128=peak=true -f null -. Normalisiere eine generierte Tonspur mit loudnorm=I=-16:TP=-1.5:LRA=7; für ein endgültiges Master führe loudnorm zweimal aus (messen, dann die measured_*-Werte zurückgeben), damit die Verstärkung linear ist.
• look gibt die Lautstärke des Mixes aus, und footage.py check lässt ein Rendering, das das Ziel verfehlt, fehlschlagen.

Erhaltenes Filmmaterial: Aufnahme

Handyvideo ist selten das, was es zu sein scheint. Führe dies bei allem aus, bevor du es dir ansiehst oder schneidest:

uv run --no-project --with pillow python -I $S/footage.py probe CLIP.mov ...
uv run --no-project --with pillow python -I $S/footage.py proxy CLIP.mov <scratch>/clip.mp4

probe warnt vor jedem dieser Punkte, und proxy behebt alle in einem Durchgang (SDR BT.709, Rotation eingebrannt, konstante 30 fps, gerade Größe, H.264 yuv420p, AAC 48 kHz, faststart):

• HDR (iPhones zeichnen standardmäßig HLG auf: color_transfer=arib-std-b67, BT.2020). Als SDR gelesen wirkt es blass und verschiebt Farben: Zinnober wird orange. proxy tonemappt mit macOS' eingebautem avconvert, sonst ffmpeg zscale (fehlt in vielen Homebrew-Builds), sonst warnt es.
• Rotation: Telefone speichern Hochformat-Video seitwärts mit einem Rotations-Flag; einige Tools ignorieren es.
• Variable Bildrate: nominal 24, durchschnittlich 23,997. Bildzeiten driften und Audio gerät nach Schnitten aus dem Takt. probe meldet jede Abweichung über 0,001 fps.
• Ungerade Maße: H.264 yuv420p benötigt gerade Breite und Höhe.

Sieh dir den Proxy an und schneide ihn; behalte das Original für alles, das in voller Qualität bleiben muss.

Filmmaterial verstehen

uv run --no-project --with pillow python -I $S/footage.py frames <scratch>/clip.mp4 <scratch>/sheets --every 4

Das nimmt ein Bild bei jedem Szenenwechsel (--scene 0.3) und mindestens eines alle --every Sekunden, begrenzt auf --max 60, auf Bögen mit 5×6 Kacheln, beschriftet mit 0007 · 1:23.4, mit manifest.json, das jede ID ihrer Zeit zuordnet. Lies die Bögen und antworte mit IDs und Zeiten. Übung, nicht Doktrin:

• Erstellte Filme: gleichmäßige Abtastung in der Einstellungslänge. Gefundenes Material: Szenenwechsel plus mindestens ein Bild alle 2-5 s. Schnelle Action: einen kurzen Abschnitt mit --every 0.5.
• Halte einen Bogen unter ~2.500 px auf der langen Seite und lies einige auf einmal; bei langem Material verteile auf Unter-Agenten über Bögen, die jeweils ein JSONL-Urteil pro Kachel-ID schreiben, dann python3 -I $S/check_verdicts.py manifest.json out/*.jsonl (fehlende, doppelte oder erfundene IDs schlagen fehl; ein Bogen, bei dem jede Kachel die gleiche Antwort erhielt, wurde wahrscheinlich überflogen).
• Das meiste eines Sprechvideos liegt in seinem Audio. Transkribiere geräteintern mit Wortzeiten: uvx parakeet-mlx AUDIO.wav --output-format json --output-dir <scratch> (extrahiere zuerst Audio: ffmpeg -i clip.mp4 -ar 16000 -ac 1 audio.wav). Verbinde Wörter mit Bildern über die Zeit. Eigennamen kommen falsch heraus („torii“ → „Torrey“), also überprüfe Namen anhand des Gesehenen, bevor du sie zitierst.

Ausliefern

uv run --no-project --with pillow python -I $S/footage.py check FILM/<name>.mp4 --duration 30
uv run --no-project --with pillow python -I $S/footage.py share FILM/<name>.mp4 <scratch>/<name>-share.mp4
uv run --no-project --with pillow python -I $S/footage.py gif FILM/<name>.mp4 <scratch>/loop.webp --start 2.5 --duration 6 --width 480

• check muss bestanden sein, bevor du eine Datei übergibst: H.264, yuv420p, gerade Größe, konstante Bildrate, moov vor mdat (faststart: spielt während des Herunterladens ab), Dauer, Lautstärke ±1,5 LU, wahrer Spitzenwert.
• Rendere, wenn die Person nach der Datei fragt oder nicht an diesem Mac sein kann; führe look auf dem MP4 selbst als letzte Prüfung aus. share erstellt eine kleine Kopie (1280 breit, CRF 28: ein 30 s 1080p-Render ging von 34 MB auf 3,8 MB) für eine Webseite oder einen Chat; das eigene MP4 des Films bleibt unberührt.
• Schleifen: Animated WebP statt GIF. Eine 5,6 s Fotoloop mit langsamem Zoom war 6,7 MB als GIF und 1,6 MB als WebP: GIF kann Pixel nicht wiederverwenden, wenn sich jeder Pixel bewegt. GIF nur, wenn das Ziel WebP nicht anzeigen kann; dann verwendet footage.py gif X.gif eine generierte Palette (palettegen/paletteuse).
• Entferne, was nicht reisen sollte: iPhone-Video trägt GPS, das Telefonmodell und die Uhrzeit in seinen Metadaten. proxy und share entfernen alles davon (-map_metadata -1). Die Originaldatei oder eine Kopie per AirDrop oder Fotos-Export behält sie. Prüfe mit exiftool -GPSCoordinates DATEI.

Fotos in einem Film

Verwende das photo-skill-Skill (github.com/kylefritz/photo-skill; falls es nicht installiert ist, biete an, es in ~/.claude/skills/photo-skill zu klonen), um sie zu finden (durchsuche die Bibliothek nach Beschreibung, beurteile dann Kontaktbögen) und um Originale in voller Auflösung herunterzuladen: Vorschauen sind zu klein für 1080p. Kopiere, was der Film verwendet, in FILM/assets/, neu gespeichert ohne EXIF. Bevor ein Film mit den Fotos einer Person irgendwohin geht, sieh dir jede Einstellung in voller Größe an: Gesichtserkennung übersieht Menschenmengen, und eine 300 px-Kachel versteckt Personen, die ein 1080p-Bild zeigt.

Andere Tools

OpenFilm passt am besten zu einem Agenten, weil ein Film reines HTML ist und look genau das zurückgibt, was du sehen musst. Alternativen, Stand Ende 2026:

Tool	Autorensystem	Hinweise
HyperFrames (HeyGen, Apache-2.0)	HTML/CSS + GSAP, gerendert durch headless Chrome	der nächste Verwandte; check --json Lint/Layout/Kontrast-Gate, Snapshots, ein Claude Code-Plugin
Remotion	React-Komponenten	ausgereift, offizielle Agent-Skills; Source-available-Lizenz, Unternehmen ab einer bestimmten Größe benötigen eine
Manim (MIT)	Python-Szenen	Mathematik- und Diagramm-Erklärvideos
MoviePy (MIT) / rohes ffmpeg	Python / Filtergraphen	einfache Schnitte und Überlagerungen; ffmpeg bleibt am besten als I/O-Ebene

OpenFilm aktualisieren

Upstream veröffentlicht oft. Lies die Versionshinweise und führe zuerst npm view openfilm scripts aus (ein preinstall- oder postinstall-Eintrag verdient einen Blick), ändere dann OPENFILM_VERSION in scripts/openfilm und führe setup.sh erneut aus. Danach ls ~/Library/Caches/ms-playwright: Der erste Start von OpenFilm löscht Playwright-Browser, die keinen Link-Marker haben; setup.sh meldet alle, die entfernt wurden, und npx playwright install chromium im Projekt, das einen benötigt, setzt ihn zurück.

Häufige Fehler

Fehler	Korrektur
npx openfilm …	$S/openfilm …: npx umgeht die Festlegung
look oder render im falschen Ordner	$S/openfilm -C FILM …
Den Prüfungen von look vertrauen, ohne das PNG zu öffnen	Lies den Bogen; eine bestandene Prüfung sagt nichts über das Layout
iPhone-Material direkt schneiden oder ansehen	probe, dann proxy: HDR, Rotation und VFR beißen alle
Das Master-MP4 an einen Chat senden	share it, dann check die Kopie
Ein GIF für eine README oder eine Seite	WebP, ~4× kleiner
Veraltetes Studio nach einem Update	Stoppe die alten studio/server/main.mjs-Prozesse (pgrep -fl openfilm); ein Studio sind zwei Prozesse