Document setup and rendering, add app build and settings tests

README.md

@@ -0,0 +1,89 @@
+# 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
+
+```sh
+git clone https://git.casaderoll.de/michael/GrowthLapse.git
+cd GrowthLapse
+swift build
+swift run GrowthLapse
+```
+
+Für eine lokal startbare App mit Icon:
+
+```sh
+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`.
+
+```sh
+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](docs/ANALYSE.md).