dmtrKovalenko/fframes

Videos mit fframes erstellen

fframes ist eine Rust-Bibliothek, die Videos aus Code rendert. Ein Video ist eine Rust-Struktur mit einer Methode render_frame(frame) -> Svgr: für jeden Frame gibt sie einen SVG-Baum zurück, der mit dem Makro svgr! erstellt wird (SVG-Markup mit {Rust-Ausdrücken}). Szenen unterteilen die Zeitachse, timeline! und Federn animieren Werte, eine Audiokarte platziert den Ton und ffmpeg codiert das Ergebnis.

Jedes Projekt erhält eine Befehlszeile (von fframes::cli). Verwenden Sie sie für alles: Rendern eines Videos, Öffnen des Echtzeit-Vorschaufensters und Betrachten von Frames, Kontaktbögen und Lautstärkewerten als Dateien, die Sie lesen können. Lesen Sie vor dem Entwerfen references/design.md, während des Schreibens von Code references/api.md, für Audio references/audio.md und für 3D-Aufnahmen (fframes::three_d) references/3d.md.

Wenn ein bereitgestelltes Video abgestimmt werden soll, folgen Sie zuerst der Referenzanalyse-Anleitung in references/design.md. Dessen Schnitte, Tempo und Bewegung haben Vorrang vor den untenstehenden Designstandards; schnelle Bearbeitungen und absichtliche schwarze Frames können Teil des angeforderten Ergebnisses sein.

Zwei Regeln vor allem anderen

Planen Sie, bevor Sie Code schreiben

Öffnen Sie nicht die Vorlage und beginnen Sie nicht zu animieren. Zuerst:

1. Legen Sie das Briefing fest: Wer sieht es und wo (die Plattform bestimmt Format und Länge), das Eine, an das sich der Zuschauer erinnern muss, den Ton und die vorhandenen Assets (Logo, Produktaufnahmen, Filmmaterial, Musik, Voice-Over). Fragen Sie den Benutzer, was fehlt und wichtig ist. Erfinden Sie niemals Produktdaten, Zahlen oder Zitate.
2. Wenn das Video auf Musik oder eine Stimme geschnitten wird, wählen Sie zuerst den Ton. Dessen Tempo, Beats und Phrasen bestimmen das Timing von allem anderen.
3. Planen Sie zuerst das Bewegungsdesign, synchronisieren Sie das Bewegungsdesign mit den Audiospitzen, um einen einzigen, einzigartigen Ablauf zu schaffen: wo die Elemente erscheinen, wie sie sich transformieren. Versuchen Sie, für jede Szene ein einzigartiges Bewegungsdesign zu erstellen, damit es einzigartig und poliert aussieht. Das Video sollte nicht wie eine Diashow aussehen.
4. Versuchen Sie, über das Gefühl der Person nachzudenken, die das endgültige Video sieht, und passen Sie jedes Designelement entsprechend an: den Ablauf, das Tempo, die Beats, die Bewegung und die Farben.

Kein "Slop"

"Slop" ist ein Video aus Standardentscheidungen: Es könnte jedes beliebige Produkt betreffen, nur der Text ist geändert, und Zuschauer erkennen es innerhalb einer Sekunde. Sofern der Benutzer nicht ausdrücklich darum bittet, liefern Sie nicht aus:

• Vorlagenreste: das Start-Layout, die Farben, Schriftart oder Dekorationen, Platzhaltertext, gefälschte Logos, erfundene Zahlen.
• Beat-Spam: Der gesamte Frame zoomt, wackelt oder blinkt bei jedem Beat. Synchronisieren Sie kleine Dinge auf den Beat (einen Strich, ein Wort, einen Funken) und ändern Sie den gesamten Frame nur bei wenigen Schnitten.
• Eine Bewegung für alles: Jedes Element blendet mit der gleichen Beschleunigung und Dauer 40 Pixel nach oben ein.
• Statische Szenen: Ein Element erscheint, bleibt stehen und blendet aus, während sich nichts anderes bewegt.
• Generischer Text: "Einführung", "Entfesseln", "Nahtlos", "Next-Level", Drei-Wort-Slogans ("Schnell. Einfach. Leistungsstark."). Schreiben Sie Bildschirmtext so, wie eine Person es sagen würde.
• Text im Allgemeinen: Die Textmenge sollte begrenzt und punktgenau sein.

Geben Sie stattdessen jedem Element einen Grund, der mit dem Thema verbunden ist, und entfernen Sie alles, was keinen hat. Investieren Sie die Mühe in Details und Bewegung statt in Worte: sekundäre Bewegungen, gestaffelte Eingänge, gezeichnete Striche, Objekte, die aufeinander reagieren, Elemente, die über Schnitte hinweg mitgeführt werden. Bevor Sie dem Benutzer etwas zeigen, betrachten Sie einen Streifen und fragen Sie sich, ob das Video immer noch für ein anderes Produkt funktionieren würde, wenn man nur den Text ändert. Wenn ja, ändern Sie die Idee, nicht die Farben.

1. Installation

Rust von https://rustup.rs, dann die Systembibliotheken, mit denen ffmpeg erstellt wurde:

# macOS
brew install pkg-config ffmpeg x264 x265 opus nasm ninja
# Debian / Ubuntu
sudo apt-get install -y yasm nasm ffmpeg libx264-dev libx265-dev libopus-dev libclang-dev clang ninja-build libvpx-dev libasound2-dev
# Arch
sudo pacman -S ninja yasm nasm ffmpeg x264 x265 opus clang

Windows verlinkt stattdessen einen vorgefertigten FFmpeg 9 Shared Build (setzen Sie FFMPEG_DIR auf den entpackten ffmpeg-n9.0-latest-win64-gpl-shared Build von BtbN/FFmpeg-Builds, fügen Sie dessen bin zum PATH hinzu, installieren Sie LLVM mit winget install LLVM.LLVM und setzen Sie LIBCLANG_PATH). Details finden Sie in der fframes README.

2. Ein Projekt erstellen

curl -fsSL https://raw.githubusercontent.com/dmtrKovalenko/fframes/main/scripts/new-video.sh | bash -s -- my-video --yes
# oder den Generator einmal installieren und direkt verwenden:
cargo install --locked cargo-fframes
cargo fframes new my-video --format landscape --fps 30 --yes

Optionen: --template single-scene|multi-scene, --format landscape|portrait|square|uhd, --fps, --title, --backend, --dir. Das Projekt hängt von der fframes-Version ab, die mit dem installierten cargo-fframes übereinstimmt; --git verwendet stattdessen den main-Branch des Repositorys. Übergeben Sie immer --yes, damit nichts auf Eingabe wartet.

Vorlagen:

• single-scene (Standard): eine Szene. Passt sich jedem Format an; beginnen Sie hier für Einzelaufnahme-Clips, Titelcards und Hochformat-Videos.
• multi-scene: zwei Szenen. Beginnen Sie hier für alles mit mehreren Szenen; akzeptiert nur landscape und uhd.

Der Vorlageninhalt ist Platzhaltercode, der die API zeigt. Ersetzen Sie dessen Layout, Farben, Schriftarten und Dekorationen durch ein Design, das für das vom Benutzer angeforderte Video erstellt wurde.

Verwenden Sie das Skia GPU-Backend (Standard). cargo fframes new wählt Skia auf Metal (macOS) oder Vulkan (Linux, Windows). Es rendert etwa 10x schneller als das CPU-Backend und bietet Ihnen das Echtzeit preview-Fenster. Auf macOS und Linux lädt der erste Build vorgefertigte Skia- und ffmpeg-Binärdateien herunter und kompiliert nur die Rust-Abhängigkeiten (ca. eine Minute; andere Ziele oder metal und vulkan zusammen kompilieren Skia aus dem Quellcode für ~20 Minuten). Starten Sie es sofort und schreiben Sie das Video, während es läuft:

cd my-video && cargo build --release        # im Hintergrund ausführen, der erste Build ist der langsame

--backend cpu benötigt kein Skia, hat aber kein Vorschaufenster; wählen Sie es nur, wenn keine GPU vorhanden ist.

Das Projekt rendert wie generiert:

my-video/
  src/lib.rs        # das Video (aus der Vorlage)
  src/main.rs       # die Befehlszeile
  media/            # Schriftarten, Bilder und Audio, die in die Binärdatei kompiliert werden (eine Start-Schriftart)
  README.md         # die folgenden Befehle

Jeder folgende Befehl ist cargo run --release -- <Befehl>. Definieren Sie eine kurze Shell-Funktion (eine Variable wie R="cargo run --release --" wird in zsh, der macOS-Shell, nicht in Wörter aufgeteilt):

R() { cargo run --release -- "$@"; }

3. Die Schleife

Schreiben Sie bei Verwendung dieser Fähigkeit überhaupt keine Tests. Erstellen Sie keine Unit-, Integrations-, Snapshot- oder visuellen Regressionstests, Testmodule oder Test-Harnesses. Validieren Sie das Video mit inspect, gerenderten Frames, Kontaktbögen, Audio-Checks und der nativen Vorschau.

Vorschau, nicht rendern. Wenn das Video das GPU-Render-Backend verwendet und eine GPU auf diesem Rechner verfügbar ist, führen Sie die native Vorschau aus (oder zeigen Sie dem Benutzer den Befehl), anstatt das Video nach jeder Änderung erneut zu rendern. Sobald die Änderungen zur Überprüfung bereit sind:

1. Zeigen Sie einen vollständigen Befehl in einem kopierbaren Shell-Codeblock an, der den tatsächlichen Projektpfad und Paketnamen verwendet; verlangen Sie nicht, dass der Benutzer den $R-Helfer definiert hat. Zum Beispiel: cd /absoluter/pfad/zu/fframes && cargo run --release -p my-video -- preview 0s.
2. Bieten Sie explizit an, diese Vorschau für den Benutzer auszuführen. Wenn der Benutzer bereits autorisiert hat, die Vorschau zu öffnen oder zu aktualisieren, zeigen Sie den Befehl an und fahren Sie innerhalb dieser Autorisierung fort.

Stellen Sie nach einer gewünschten Änderung die Startzeit des Befehls auf eine bestimmte Sekunde ein, die bei oder kurz vor dem geänderten Abschnitt liegt, mit genügend Vorlauf, um dessen Eingang oder Übergang zu sehen. Zum Beispiel lässt preview 8.5s den Benutzer eine Änderung um 9 Sekunden herum überprüfen, ohne den Anfang erneut abzuspielen. Geben Sie an, welchen Abschnitt sie sehen werden. Rendern Sie das vollständige Video, wenn der Benutzer den finalen Export anfordert; fordern Sie keine weitere Bestätigung an, wenn diese Anfrage bereits explizit ist.

Nach jeder Änderung:

1. $R timeline listet die Szenen mit ihren Frame- und Sekundenbereichen sowie jede Audiospur auf. Überprüfen Sie hier die Struktur und das Tempo, bevor Sie sich Pixel ansehen.
2. $R inspect prüft alle 0,25 s einen Frame plus den ersten und letzten Frame jeder Szene. Es meldet fehlende Bilder, Schriftarten oder Glyphen, Text, der am Rand der Leinwand abgeschnitten wird, ungültiges SVG (Rechtecke mit Größe Null, schlechte Radien), defekte Transformationen und Abstürze, jeweils mit Zeit und Szene. Es beendet sich mit Code 2 bei Fehlern. Beheben Sie alles, was es meldet. Eine Warnung, die nur in den ersten Frames einer Szene erscheint, ist normalerweise ein Eingang; überprüfen Sie sie mit einem Streifen.
3. $R strip <Szene oder Bereich> -n 12 schreibt einen Kontaktbogen (strip.png): gleichmäßig verteilte Frames in einem beschrifteten Bild. Öffnen Sie es mit Ihrem Bildtool. Es ist der schnellste Weg, um Layout, Rhythmus und Bewegung zu beurteilen. $R strip 2s,5s,9s setzt ausgewählte Zeiten nebeneinander.
4. $R frame Intro@Ende,Outro@50% schreibt vollformatige PNGs in frames/ für Detailprüfungen (Typografie, Ausrichtung, Kontrast) und druckt Probleme, die in diesen Frames gefunden wurden. Beurteilen Sie kleine Details (Kontakt zwischen Elementen, Kanten, kleine Formen) auf einem scharfen, vergrößerten Ausschnitt, niemals auf einem verkleinerten Frame: $R frame 3s --crop 1100,520,240,120 (Videopixel, auf etwa 960 px Breite vergrößert). --ids umreißt und benennt jedes Element, das eine id hat, um herauszufinden, welche Form welche ist.
5. $R onion "[email protected]@1s" -n 6 mischt Frames zu einem Bild (onion.png), um den Pfad und den Abstand einer Bewegung zu zeigen: Beschleunigung, Überschwingen, Staffelung.
6. $R preview Intro öffnet ein Echtzeit-Fenster mit Ton, das der Benutzer ansehen kann (Leertaste Abspielen/Pause, h/l eine Sekunde springen, j/k einen Frame schrittweise, q beenden). Es blockiert, bis es geschlossen wird, also starten Sie es im Hintergrund, wenn Sie es für den Benutzer ausführen. Zeigen Sie den Befehl an und bieten Sie an, ihn wie oben beschrieben zu starten; nach Bearbeitungen verwenden Sie eine bestimmte Sekunde in der Nähe der Änderung.

Wenn eine codierte Probe benötigt wird, codiert $R render Intro --draft eine Szene mit halber Auflösung. $R render schreibt das vollständige Video für einen angeforderten finalen Export.

Bevor Sie ein fertiges Video zeigen, führen Sie $R inspect --pops aus: Es rendert jeden Frame klein und warnt vor "Pops", Teilen des Bildes, die in einem Frame zwischen Standbildern wechseln, wie ein Element, das erscheint, verschwindet oder vor einem anderen springt, anstatt sich dorthin zu bewegen. Jede Warnung gibt den frame ... --crop ...-Befehl an, um es anzusehen; Wiederholungen derselben Region (Zähler, blinkende Lichter) werden zu einer Warnung zusammengefasst.

Regeln:

• Sehen Sie sich die PNGs an, bevor Sie sagen, dass etwas gut aussieht.
• Bevorzugen Sie strip gegenüber vielen frame-Aufrufen; fügen Sie --scale 0.5 hinzu, wenn Sie nur die Komposition benötigen.
• Fügen Sie --json hinzu, wenn Sie die Ausgabe parsen: das Ergebnis geht an stdout, der Fortschritt an stderr.
• Behalten Sie --release bei: Debug-Builds rendern um ein Vielfaches langsamer.

Zeitangaben

120 (Frame), 3.2s, 500ms, 1:05.5, 50%, start, end; Szenen nach Strukturnamen, Intro (passt auch auf IntroScene, Groß-/Kleinschreibung wird ignoriert), #3 (Szenenindex), Intro[1] (zweite Szene dieses Typs); innerhalb einer Szene [email protected], Intro@12, Intro@50%, Intro@ende. Bereiche: a..b (Ende exklusive), a.., ..b, all, oder ein Szenenname für die gesamte Szene. Trennen Sie mehrere Zeiten durch Kommas.

Alle Befehle

Befehl	Verwenden ihn, um
timeline	Szenen, Dauern, Audiospuren und deren Mischungseinstellungen anzuzeigen
inspect [BEREICH] [--every 0.1s | --all-frames] [--fail-on warning] [--pops]	Probleme zu finden, ohne Pixel zu rendern; --pops findet auch Elemente, die ein- oder ausblenden
strip [BEREICH | ZEITEN] -n N [--columns 4] [--width 480] [--crop x,y,w,h]	Ablauf und Bewegung in einem Bild zu überprüfen
frame ZEITEN [-o verzeichnis] [--svg] [--crop x,y,w,h] [--zoom N] [--ids]	Vollformat-PNGs (und das ausgelegte SVG) ausgewählter Frames, scharfe Ausschnitte, beschriftete Elemente
onion BEREICH -n N	die Flugbahn und Beschleunigung einer Bewegung zu sehen
svg ZEIT	das endgültige SVG eines Frames als Text zu lesen (Positionen, Text, Farben)
preview [ZEIT] [--paused] [--mute]	Echtzeit-Fenster mit Ton für den Benutzer
render [BEREICH] [-o aus.mp4] [--draft]	das Video oder einen Teil davon zu codieren (Audio entsprechend geschnitten)
audio analyze [BEREICH] [--waveform w.png]	Lautstärke (LUFS), True Peak, Clipping, Stille, pro Szene
audio at ZEITEN	welche Töne zu einem bestimmten Zeitpunkt spielen, wo in ihrer Datei und wie laut
audio render [BEREICH] -o a.wav	den Mix als WAV-Datei

Browser-Editor

fframes hat auch einen Web-Editor mit einer Zeitleiste und Scrubbing, nützlich, wenn jemand ein Video interaktiv bearbeiten möchte. Er führt das nach WebAssembly kompilierte Video aus und benötigt Node.js plus wasm-pack; die Einrichtung ist der Ordner editor/ des Hello-World-Beispiels im fframes-Repository (https://github.com/dmtrKovalenko/fframes/tree/main/examples/hello-world). Erwähnen Sie ihn, wenn der Benutzer nach einem GUI-Editor fragt. Zum Ansehen verwenden Sie preview, und für Ihre eigene Überprüfung verwenden Sie die CLI.

4. Das Video schreiben

impl Video for MyVideo<'_> {
    const FPS: usize = 30; const WIDTH: usize = 1920; const HEIGHT: usize = 1080;
    fn duration(&self) -> Duration<'_> { Duration::Auto }            // Summe der Szenen
    fn audio(&self) -> AudioMap<'_> { AudioMap::none() }              // siehe references/audio.md
    fn define_scenes(&self) -> Scenes<'_> { Scenes::from(vec![&self.intro as &dyn Scene, &self.main]) }
    fn render_frame<'a>(&'a self, frame: Frame, ctx: &FFramesContext<'a, '_>) -> Svgr<'a> {
        fframes::svgr!(<svg xmlns="http://www.w3.org/2000/svg" width={Self::WIDTH} height={Self::HEIGHT}>
            <rect width={Self::WIDTH} height={Self::HEIGHT} fill={BACKGROUND} />
            {ctx.render_scenes(&frame)}
        </svg>)
    }
}

• Eine Szene pro Idee, 2-6 s pro Szene. Innerhalb einer Szene zählt frame.seconds() ab dem Szenenstart.
• Standardmäßig frame.animate(fframes::timeline!(...)) direkt in svgr!-Attributen für Bewegungen mit festen Werten verwenden. svgr! hebt diese Animationen in gecachte Statics. Definieren Sie Beschleunigungen inline in der Timeline, einschließlich Easing::Spring { mass: 1.0, stiffness: 180.0, damping: 20.0 }; benannte Beschleunigungskonstanten sind optional. Lassen Sie die Endzeit einer Feder weg, damit sie

... [für die Übersetzung gekürzt]