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. Mit „Ergebnis ansehen“ das fertige Video direkt in der App prüfen. In der Clip-Nachbearbeitung Segmentstarts oder Varianten ändern und „Änderungen neu rendern“ wählen. Diese Aktion erhält gewählte Ausschnitte. „Segmente neu planen“ berechnet alle Ausschnitte mit aktueller Länge, Mitte/Offset und automatischer Segmentwahl neu; manuelle Ausschnitte werden erst nach erfolgreichem Rendern ersetzt. Die globale Variantenwahl gilt für einen neuen Import; vorhandene Varianten werden pro Clip gewechselt. „Projekt laden“ stellt die gespeicherten Render-Einstellungen wieder her.

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
GrowthLapse-<UUID>.growthlapse-cache/	Eigener Arbeitsbereich mit Zwischenclips und Eigentumsmarkierung
Ergebnis.growthlapse-report.txt	Render-Protokoll

Im Menü „Projekt“ löscht „Render-Cache löschen“ ausschließlich einen von der neuen Version markierten Cache. Historische, unmarkierte Cache-Verzeichnisse bleiben erhalten und können nach Prüfung im Finder entfernt werden. Fehlende Zwischenclips werden beim erneuten Rendern neu erzeugt; Quellen müssen weiterhin vorhanden sein.

Jeder Render schreibt in einen eigenen Arbeitsbereich und kopiert verwendbare Cache-Clips dorthin. Die vorhandene Ausgabe und ihr Cache bleiben während des Renders erhalten. Erst nach erfolgreichem Rendern werden Video und Projektdatei übernommen; bei einem Fehler während der Übernahme wird eine Wiederherstellung versucht. Das ist keine absturzsichere Transaktion über mehrere Dateien. Der alte, markierte Cache desselben Ausgabeziels wird erst nach Erfolg entfernt. „Speichern unter“ auf ein anderes Ausgabeziel erhält das ursprüngliche Projekt und dessen Cache.

Projekte enthalten Render-Einstellungen und absolute Dateipfade. Sie sind daher nicht ohne Anpassung zwischen Rechnern verschiebbar. Die lokalen Werkzeugpfade bleiben beim Laden unverändert. Ältere Projekte ohne gespeicherte Einstellungen zeigen einen Hinweis und verwenden die aktuellen Werte. Die globalen Einstellungen liegen unter ~/Library/Application Support/GrowthLapse/settings.json; „Defaults“ setzt sie zurück.

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 XCTest-Tests prüfen neutrale Startwerte, JSON-Speicherung und die Kompatibilität älterer Einstellungen.

Für Integrationstests genügt die Command-Line-Tools-Umgebung mit FFmpeg und FFprobe:

bash scripts/integration-tests.sh

Dieser Test baut einen eigenen Test-Einstieg mit den produktiven Render-Klassen, erzeugt synthetische Videos und prüft unter anderem Speichern/Laden, Cache, Tonspuren, Überblendungen, Endausgabe-Fehler, Wiederherstellung und Abbruch. Er verändert keine persönlichen Einstellungen. Testdateien werden automatisch entfernt; mit GROWTHLAPSE_KEEP_TEST_OUTPUT=1 bleiben sie zur Kontrolle erhalten.

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, Encoder-Prüfung und abbrechbare Prozessausführung
RenderWorkspace.swift	Isolierte Arbeitsverzeichnisse, sichere Cache-Löschung und Übernahme der Ausgabe
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 vorhandenes Deshake verwendet; ohne passenden Filter endet die Vorabprüfung mit einer klaren Fehlermeldung.
• Gesichtserkennung garantiert keine passende Ausrichtung für jede Aufnahme.
• Synthetische Tests decken zentrale Renderpfade ab; eine Qualitätsprüfung mit realen Gesichts-, HDR- und langen Videos bleibt erforderlich.
• Im Repository ist bisher keine Lizenz festgelegt.

Weitere technische Befunde stehen in docs/ANALYSE.md.

Die Änderungen der Zuverlässigkeitsüberarbeitung sind in docs/VERBESSERUNGEN.md dokumentiert.