GrowthLapse

GrowthLapse ist eine native macOS-App in SwiftUI, die aus mehreren Videos einen Wachstums-Zeitraffer erstellt. Aus jedem Video wird ein Ausschnitt gewählt, optional stabilisiert und am Gesicht ausgerichtet, beschleunigt und mit den übrigen Clips verbunden. Die Verarbeitung läuft lokal mit Apple Vision/AVFoundation und externem FFmpeg.

Voraussetzungen

• macOS 13 oder neuer.
• Swift 5.9 oder neuer mit macOS SDK, etwa über Xcode bzw. die Xcode Command Line Tools.
• ffmpeg und ffprobe als ausführbare Dateien. Die App enthält diese Werkzeuge nicht.
• Für VidStab: FFmpeg mit vidstabdetect und vidstabtransform; alternativ deshake. Für eingeblendete Clipnummern ist drawtext erforderlich.

Eine Installation über Homebrew ist mit brew install ffmpeg möglich. Welche optionalen Filter dein Build enthält, zeigt ffmpeg -hide_banner -filters.

GrowthLapse sucht Werkzeuge zuerst in /opt/homebrew/bin, /usr/local/bin und /usr/bin, danach im PATH. In der Oberfläche lassen sich eigene ausführbare Dateien auswählen. Bei alten gespeicherten Pfaden hilft „Automatische Suche verwenden“.

Bauen und starten

git clone https://git.casaderoll.de/michael/GrowthLapse.git
cd GrowthLapse
swift build
swift run GrowthLapse

Für eine lokal startbare App mit Icon:

bash scripts/build-app.sh
open build/GrowthLapse.app

Das Skript baut im Release-Modus für die Architektur des ausführenden Macs und signiert die App ad hoc. Es erzeugt keine notarisiert veröffentlichte oder universelle App. Die bereits eingecheckte App in dist/ ist ein historisches Build-Artefakt; Änderungen am Quellcode werden erst durch einen neuen Build wirksam.

Bedienung

1. Input-Ordner und Output-MP4 auswählen. Unterstützt werden mp4, mov, m4v, avi, mkv und webm direkt im gewählten Ordner; Unterordner werden nicht durchsucht.
2. Sortierung und gegebenenfalls Variantenwahl einstellen. Die Wochen-Sortierung erkennt beispielsweise 12 Wochen alt V1.mov. Dateien ohne erkennbares Wochenalter stehen dahinter. Varianten werden anhand eines abschließenden Leerzeichens mit Zahl oder V und Zahl gruppiert, etwa 12 Wochen alt V1.mov und 12 Wochen alt V2.mov.
3. Ausschnittlänge, Ziellänge und Übergang festlegen. Standard: 8 Sekunden Quelle, 1,5 Sekunden pro Ergebnisclip, 0,6 Sekunden Überblendung und 30 FPS. Die Übergangslänge muss kleiner als die Ziellänge sein; 0 bedeutet einen harten Schnitt.
4. Ausgabeformat, Encoder und optionale Stabilisierung/Gesichtsausrichtung wählen. Unterstützt sind 1920×1080, 1080×1920 oder die Abmessungen des ersten Videos. Für H.264 stehen CPU (libx264) und VideoToolbox zur Auswahl. Audio wird standardmäßig entfernt.
5. „Render starten“ wählen. Fortschritt und Log erscheinen in der App; „STOP“ bricht die Verarbeitung ab.
6. In der Clip-Nachbearbeitung Segmentstarts oder Varianten ändern und „Änderungen neu rendern“ wählen. „Projekt laden“ öffnet eine gespeicherte Projektdatei.

Die automatische Segmentwahl sucht nach geeigneten Gesicht-/Augenaufnahmen. Gesichtsausrichtung und Stabilisierung sind heuristisch und sollten anhand des Ergebnisses geprüft werden.

Dateien und Einstellungen

Neben Ergebnis.mp4 können folgende Dateien entstehen:

Datei	Zweck
Ergebnis.growthlapse-project.json	Quellen, Ausschnitte, Varianten und Cache-Verweise
Ergebnis.growthlapse-cache/	Zwischenclips für die Nachbearbeitung
Ergebnis.growthlapse-report.txt	Render-Protokoll

„Ergebnis bestätigen“ löscht den Projekt-Cache. Fehlende Zwischenclips werden beim erneuten Rendern neu erzeugt; die Quelldateien müssen weiterhin vorhanden sein. Ein neuer Render mit demselben Ausgabeziel setzt dessen Review-Cache zurück und kann die vorhandene Ausgabe überschreiben.

Projekte verwenden absolute Dateipfade und sind daher nicht ohne Anpassung zwischen Rechnern verschiebbar. Die globalen Einstellungen liegen unter ~/Library/Application Support/GrowthLapse/settings.json. „Defaults“ setzt sie zurück. Projektdateien ersetzen keine vollständige Sicherung der globalen Render-Einstellungen.

Entwicklung und Prüfung

Für die XCTest-Tests ist eine vollständige Xcode-Installation mit ausgewählter Xcode-Entwicklerumgebung erforderlich; die Command Line Tools allein enthalten hier kein XCTest.

swift test

Die Tests prüfen neutrale Startwerte, die JSON-Speicherung und die Kompatibilität älterer Einstellungen. Sie ersetzen keine Prüfung der Videoausgabe.

Für einen manuellen Funktionstest zwei kurze Videos in einen separaten Testordner legen und ein neues Ausgabeziel wählen. Zunächst ohne Stabilisierung und ohne Übergang rendern, danach mit Überblendung und den gewünschten Filtern. Ergebnis abspielen, einen Segmentstart ändern, erneut rendern, Projekt laden und Abbruch während eines weiteren Renders prüfen.

Quellcode	Aufgabe
GrowthLapseApp.swift	App-Einstieg und Fensterlebenszyklus
ContentView.swift	Einstellungen, Vorschau und Clip-Nachbearbeitung
RenderSettings.swift	Datenmodelle und persistierte Einstellungen
FFmpegService.swift	Werkzeugsuche und asynchrone Prozessausführung
VideoProcessor.swift	Videoanalyse, Render-Pipeline, Cache und Gesichtserkennung

Alle genannten Swift-Dateien liegen unter Sources/GrowthLapse/.

Bekannte Grenzen

• Foto-Morphing ist im Quellcode enthalten, aber derzeit deaktiviert.
• Verfügbare FFmpeg-Filter und Encoder hängen von der lokalen Installation ab. Wenn VidStab fehlt, wird Deshake versucht; ohne passenden Filter Stabilisierung deaktivieren oder einen geeigneten Build verwenden.
• Gesichtserkennung garantiert keine passende Ausrichtung für jede Aufnahme.
• Automatische Tests für die vollständige Render-Pipeline fehlen bislang.
• Im Repository ist bisher keine Lizenz festgelegt.

Weitere technische Befunde stehen in docs/ANALYSE.md.