Ein Schieberegler, drei Renderer: Wie wir Instagram-ähnliche Videofilter mit GPU-Shadern für die Vorschau, Skia-Farbmatrizen für alle anderen Bereiche und FFmpeg für den Export gebaut haben – und dabei sichergestellt haben, dass sie alle dieselbe visuelle Geschichte erzählen.
Filter sehen einfach aus. Videofilter sind es nicht.
Das Anwenden eines Sepia-Tons auf ein Bild in Flutter ist ein Einzeiler — man umwickelt es mit einem ColorFiltered-Widget und ist fertig. Es auf ein Video anzuwenden, ist eine ganz andere Sache:
- Die Vorschau muss mit 30–60 fps über einem abgespielten Video laufen, auf jedem Gerät, das der Benutzer besitzt.
- Der Benutzer muss in der Lage sein, Schieberegler zu ziehen (Helligkeit, Kontrast, Farbton, Temperatur…) und das Ergebnis live zu sehen.
- Und der harte Teil: Wenn sie auf Export klicken, muss die eingebrannte MP4 wie die Vorschau aussehen – aber Ihr Vorschau-Renderer (Flutter/GPU) und Ihr Export-Renderer (FFmpeg) sind komplett unterschiedliche Engines, die noch nie voneinander gehört haben.
Dieser Beitrag handelt davon, wie wir diese Pipeline in einem Flutter-Videoeditor aufgebaut haben: ein Filterkatalog mit Presets und Anpassungen pro Parameter, eine Live-Vorschau, die den günstigsten Renderer wählt, der die Aufgabe erfüllen kann, und einen FFmpeg-Exportpfad, der das Aussehen reproduziert. Die wichtigste Erkenntnis vorab:
Jeder Filter wird letztendlich dreimal implementiert — als GPU-Shader-Konfiguration, als Skia 4×5 Farbmatrix und als FFmpeg-Filterstring — alle gesteuert von einer gemeinsamen Parameter-Map. Die Aufrechterhaltung der visuellen Konsistenz dieser drei Reimplementierungen ist die wahre Ingenieursleistung.
Die Architektur: eine Parameter-Map, drei Renderer
┌────────────────────────────┐
│ shared parameter map │
│ {filterId, params, 0–1 │
│ intensity} │
└─────┬───────┬───────┬──────┘
│ │ │
┌──────────────┘ │ └───────────────┐
▼ ▼ ▼
GPU shader preview Skia ColorFilter.matrix FFmpeg -vf string
(flutter_gpu_video_ (primary live preview, (export — the only
filters, local clips) universal fallback) thing users keep)
Die drei Pfade existieren, weil jeder irgendwo seine Vorteile hat:
- GPU-Shader (flutter_gpu_video_filters) bieten echte Shader-Qualitätseffekte — Verzerrungen, Unschärfen, Tone-Mapping — aber das Paket rendert auf seine eigene Oberfläche und funktioniert am besten mit lokalen Videodateien.
- Skia ColorFilter.matrix — eine 4×5 Farbmatrix, die um das Video-Widget mit ColorFiltered gewickelt ist — ist nahezu kostenlos, funktioniert mit jedem Video-Widget (einschließlich Netzwerk-Streams) und deckt die meistgenutzten zwei Dutzend Filter ab: Helligkeit, Kontrast, Sepia, Graustufen, Farbton, Duotöne…
- FFmpeg ist der einzige Renderer, dessen Ausgabe der Benutzer tatsächlich behält. Der Export leitet jedes Aussehen als Filter-Graph-String neu ab (eq=, hue=, colorchannelmixer=…).
Ein kleiner Strategie-Router entscheidet pro Filter, welche Vorschau-Engine verwendet werden soll:
// Which preview strategy can render this filter?
static FilterStrategy getFilterStrategy(String filterId) {
if (_colorFilterIds.contains(filterId)) return FilterStrategy.colorFilter;
if (_customPainterFilterIds.contains(filterId)) return FilterStrategy.customPainter;
return FilterStrategy.exportOnly;
}
- colorFilter → wrap the player in ColorFiltered(colorFilter: getColorFilter(id, params))
- customPainter → legt ein CustomPainter-Overlay über das Video (Vignette, Pixelierung, Raster — Dinge, die eine Farbmatrix nicht ausdrücken kann)
- exportOnly → zeigt das Originalvideo plus ein Abzeichen, das dem Benutzer mitteilt, dass der Effekt im Export erscheint
Dieser Router ist die kostengünstigste Entscheidung im System: er bietet ~24 Filtern eine wirklich kostenlose Echtzeit-Vorschau auf jedem Gerät und reserviert die Schwergewichts-Maschinerie für die Filter, die sie benötigen.
1. Der Filterkatalog, Presets und Anpassungen
Jeder Filter im Katalog ist ein kleines deklaratives Element — eine ID, ein Anzeigename, eine Kategorie und (wenn der GPU-Pfad es unterstützt) eine Factory für die Shader-Konfiguration:
const GpuVideoFilterItem({
required this.id,
required this.name,
required this.icon,
required this.category,
this.createConfiguration, // () => GPUFilterConfiguration, when GPU-capable
});
GPUFilterConfiguration? getConfiguration() => createConfiguration?.call();
Presets sind benannte Parameter-Bundles, die auf einen Filter zeigen — die „P1–P5“ Schnellansichten in der UI:
static List<FilterPreset> get allPresets => [
const FilterPreset(id: 'P1', name: 'Warm Vintage',
filterId: 'sepia', parameters: {'intensity': 0.8}),
const FilterPreset(id: 'P2', name: 'Classic B&W',
filterId: 'grayscale', parameters: {'intensity': 1.0}),
const FilterPreset(id: 'P3', name: 'Vivid Colors',
filterId: 'vibrance', parameters: {'vibrance': 0.5}),
const FilterPreset(id: 'P4', name: 'High Contrast',
filterId: 'contrast', parameters: {'contrast': 1.4}),
const FilterPreset(id: 'P5', name: 'Cinematic',
filterId: 'vignette', parameters: {'vignetteStart': 0.3, 'vignetteEnd': 0.75}),
];
Anpassungen sind typisierte Parameter-Deskriptoren mit Bereichen, Standardwerten und sogar einem Gradienten-Hinweis, damit jeder Schieberegler eine aussagekräftige Spur rendern kann (Schwarz→Weiß für Helligkeit, ein Regenbogen für Farbton):
case 'brightness':
return [const FilterParameter(id: 'brightness', displayName: 'Brightness',
minValue: -1.0, maxValue: 1.0, defaultValue: 0.0,
gradientType: FilterParameterGradientType.blackToWhite)];
case 'contrast':
return [const FilterParameter(id: 'contrast', displayName: 'Contrast',
minValue: 0.5,
maxValue: 2.0, defaultValue: 1.0,
gradientType: FilterParameterGradientType.grayToWhite)];
case 'hue':
return [const FilterParameter(id: 'hue', displayName: 'Hue',
minValue: -180.0, maxValue
: 180.0, defaultValue: 0.0, unit: '°',
gradientType: FilterParameterGradientType.rainbow)];
Die aktuellen Schiebereglerwerte leben in einem unveränderlichen State-Objekt, das von Standardwerten initialisiert wird:
factory FilterAdjustmentState.fromDefaults(String filterId, List<FilterParameter> parameters) {
return FilterAdjustmentState(
filterId: filterId,
parameterValues: Map.fromEntries(parameters.map((p) => MapEntry(p.id, p.defaultValue))),
);
}
Und ein UX-Detail, das wichtiger ist, als es aussieht: Schieberegler-Updates schreiben sofort in den State (damit der Daumen dem Finger folgt), aber das Neu-Rendern der Vorschau wird um 300 ms verzögert. Ohne die Verzögerung würde das Ziehen eines Schiebereglers den gefilterten Video-Subtree Dutzende Male pro Sekunde neu aufbauen und das Ziehen würde stottern; damit springt die Vorschau sofort auf den endgültigen Wert, sobald der Finger langsamer wird.
Was auf dem Clip persistent gespeichert wird, ist bewusst minimal gehalten:
class Filters {
final String? adjust; // manuell gewählte Filter-ID, z.B. 'sepia'
final String? presets; // Preset-ID, z.B. 'P1'
final double? intensity; // 0.0–1.0; null bedeutet 1.0 (wird nur gespeichert, wenn < 1.0)
final Map<String, double>? parameters; // Schiebereglerwerte pro Filter
}
2. Live-Vorschau, Pfad für Pfad
Das Arbeitspferd: eine 4×5 Farbmatrix
Der größte Teil des Katalogs besteht aus Farbmathematik, und Skia-Farbmatrizen erledigen Farbmathematik kostenlos. Der Filter-Manager wandelt eine Filter-ID + Parameter in eine ColorFilter.matrix um:
static ColorFilter getColorFilter(String filterId, [Map<String, double> parameters = const {}]) {
final matrix = _getColorMatrixWithParams(filterId, parameters);
return ColorFilter.matrix(matrix);
}
Die Matrizen parametrisierter Filter werden dynamisch konstruiert. Zwei Beispiele — und beachten Sie die ×255, da Matrix-Offsets im 0–255 Farbraum liegen:
case 'brightness':
final brightness = (params['brightness'] ?? 0.0) * 255.0;
return [1,0,0
,0,brightness, 0,1,0,0,brightness,
0,0,1,0,brightness, 0,0,0,1,0];
case 'contrast':
final contrast = params['contrast'] ?? 1.0;
final offset = -(0.5 * contrast) + 0.5;
return [contrast,0,0,0,offset*255, 0,contrast,0,0,offset*255,
0,0,contrast,0,offset*255, 0,0,0,1,0];
Filterintensität — der globale „Wie viel von diesem Look“-Schieberegler — wird als direkte Interpolation zwischen der Effektmatrix und der Identitätsmatrix implementiert:
final interpolatedMatrix = List<double>.generate(20, (i) {
return identityMatrix[i] + (effectMatrix[i] - identityMatrix[i]) * intensity;
});
Dieser Einzeiler verleiht jedem Farbfilter eine kostenlose 0–100%ige Stärkeregelung ohne zusätzlichen Shader- oder Pipeline-Aufwand.
Der echte GPU-Pfad
Für lokale Clips tauscht der Editor eine echte GPU-gefilterte Oberfläche von flutter_gpu_video_filters ein. Da das Widget schlüsselbasiert ist, führt das Ändern des Clips oder Filters dazu, dass die gesamte Oberfläche zerstört und neu erstellt wird (der Controller des Pakets mag keine Hot-Configuration-Switches während des Betriebs):
return GPUVideoSurfacePreview(
key: ValueKey(filterKey), // '${clipIndex}_${filterId}' — erzwingt vollständige Neuerstellung
configuration: _gpuFilterConfiguration!,
onViewCreated: (controller, sizeStream) async {
_gpuPreviewController = controller;
if (_mainController != null && _isPlaying) {
_mainController!.pause(); // vermeidet doppelte Wiedergabe (und verdoppelten Ton!)
}
await controller.setVideoSource(FileInputSource(File(clipInfo.assetPath!)));
if (mounted) setState(() => _isGpuPreviewInitialized = true);
},
);
Die Shader-Konfiguration wird pro Filter aus den typisierten Konfigurationen des Pakets zusammengestellt, gespeist durch dieselbe Parameter-Map, in die die Schieberegler schreiben:
case 'brightness': return GPUBrightnessConfiguration()..brightness = getParam('brightness', 0.0);
case 'contrast': return GPUContrastConfiguration()..contrast = getParam('contrast', 1.0);
case 'saturation': return GPUSaturationConfiguration()..saturation = getParam('saturation', 1.0);
case 'hue': return GPUHueConfiguration()..hue = getParam('hue', 0.0);
case 'white_balance': return GPUWhiteBalanceConfiguration()..temperature = getParam('temperature', 5000.0);
Zwei Lebenszyklus-Lektionen, die in Debugging-Stunden bezahlt wurden:
- Pausieren Sie den zugrunde liegenden Player, bevor die GPU-Oberfläche startet. Die GPU-Vorschau spielt das Video selbst ab; vergessen Sie das Pausieren und Sie erhalten zwei Decoder, die denselben Clip abspielen — einschließlich doppeltem, leicht versetztem Audio.
- Richtig entsorgen bei Filteränderung: disconnect() die alte Konfiguration, neue Vorschau-Parameter erstellen, connect() die neue, und dispose() den Controller (plus das size-stream-Abonnement kündigen) beim Verlassen des Bildschirms.
Der Desktop-Haken
Auf dem Desktop rendert das Video-Backend in eine externe Textur, die Skia’s Layer-Compositing umgeht — so hat das Umwickeln des Players mit ColorFiltered im Stillen keine Wirkung; es gibt keine Skia-Schicht, die transformiert werden könnte. Der Workaround besteht darin, die Rasterung der zugrunde liegenden Schicht zu erzwingen (z.B. einen dazwischenliegenden BackdropFilter über ein SizedBox.expand), damit die Farbmatrix tatsächliche Pixel hat, auf denen sie operieren kann. Wenn Ihre Filter „auf Android funktionieren, aber nicht auf dem Desktop“, ist dies höchstwahrscheinlich der Grund.
3. Export: Das Aussehen in FFmpeg neu erstellen
Die Vorschau ist geliehen; der Export gehört Ihnen. Zum Zeitpunkt des Exports wird das gespeicherte Filters-Modell aufgelöst (ein manuell gewählter Filter hat Vorrang vor einem Preset; Preset-IDs werden auf ihren Filter + Parameter zurückgemappt) und in einen FFmpeg-Filterstring übersetzt:
switch (normalizedId) {
case 'grayscale': return 'hue=s=0';
case 'sepia': return 'colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131';
case 'invert': return 'negate';
case 'brightness':
final b = params?['brightness'] ?? 0.3; return 'eq=brightness=${b.toStringAsFixed(3)}';
case 'contrast':
final c = params?['contrast'] ?? 1.5; return 'eq=contrast=${c.toStringAsFixed(3)}';
case 'saturation':
final s = params?['saturation'] ?? 1.5; return 'eq=saturation=${s.toStringAsFixed(3)}';
case 'exposure':
final e = params?['exposure'] ?? 0.4; // FFmpeg eq has no exposure — fake it with gamma
final gamma = e >= 0 ? (1.0 - e * 0.5).clamp(0.1, 10.0)
: (1.0 / (1.0 + (-e) * 0.5)).clamp(0.1, 10.0);
return 'eq=gamma=${gamma.toStringAsFixed(3)}';
case 'hue':
final h = params?['hue'] ?? 90.0; return 'hue=h=${h.toStringAsFixed(1)}';
case 'gaussian_blur':
final sigma = (params?['sigma'] ?? 5.0).clamp(0.1, 50.0);
return 'gblur=sigma=${sigma.toStringAsFixed(1)}';
case 'vignette': return "vignette='PI/4'";
// swirl / bulge / toon / kuwahara / crosshatch ... → return '' (preview-only)
}
Intensität beim Export: der Split/Blend-Trick
Denken Sie daran, dass die Vorschau die Intensität implementiert, indem sie die Farbmatrix in Richtung Identität lerpt. FFmpeg hat kein „Matrix-Lerp“ — aber es verfügt über Stream-Compositing. Ein Export mit teilweiser Intensität teilt das Video auf, filtert einen Zweig und mischt ihn mit der gespeicherten Opazität über das Original zurück:
if (intensity >= 0.99) {
command = ['-i','"$videoPath"','-vf', filterCommand,
'-c:v','libx264','-preset',options.preset,'-crf','${options.crf}',
'-c:a','copy','-movflags','+faststart','-y','"$outputPath"'].join(' ');
} else {
final opacity = intensity.toStringAsFixed(2);
command = ['-i','"$videoPath"','-filter_complex',
'[0:v]split[orig][tofilter];'
'[tofilter]$filterCommand[filtered];'
'[orig][filtered]blend=all_mode=normal:all_opacity=$opacity[out]',
'-map','[out]','-c:v','libx264','-preset',options.preset,'-crf','${options.crf}',
'-c:a','copy','-movflags','+faststart','-y','"$outputPath"'].join(' ');
}
Es ist mathematisch nicht identisch mit dem Matrix-Lerp, aber perzeptuell kommt es dem nahe — und es funktioniert für jeden Filterstring, nicht nur für Farbmatrizen.
Der Filterdurchlauf ist eine isolierte Neu-Kodierung in einer längeren Exportkette (Canvas-Fit → Filter → Effekte → Overlays → Audio-Mix → Concat), wobei -c:a copy Audio unberührt lässt, bis zur dedizierten Mischstufe, und die Quelldauer in jeder Phase geprüft wird, um Drifts frühzeitig zu erkennen.
4. Die Paritätstabelle: wo drei Renderer übereinstimmen — und wo nicht
Das ist der Teil, über den niemand schreibt. Ein gespeicherter Wert, drei Interpretationen:
| Parameter | Schiebereglerbereich | GPU-Shader | Skia-Matrix | FFmpeg-Export |
|---|---|---|---|---|
| brightness | −1 … 1 | natürlich −1…1 | Offset = v × 255 | eq=brightness=v |
| contrast | 0.5 … 2 | natürlich | Diagonale v, Offset neu zentriert | eq=contrast=v |
| saturation | 0 … 2 | natürlich | Rec.709 Luma-gewichteter Blend | eq=saturation=v |
| exposure | −1 … 1 | linearer Gain | linearer Gain | gefälscht über Gammakurve |
| hue | −180° … 180° | natürlich | volle Cos/Sin Rotationsmatrix | hue=h=v |
| sepia | intensity | Shader | Matrix .393/.769/.189… | colorchannelmixer — gleiche Koeffizienten, exakte Parität |
| intensity | 0 … 1 | Preset-Multiplikator | Lerp Matrix → Identität | Split + Blend=all_opacity |
Mühsam erarbeitete Paritätslektionen:
- Wählen Sie einen Filter als Ihre Grundwahrheit. Sepia erreicht exakte Parität, weil die identischen 3×3 Koeffizienten sowohl in der Skia-Matrix als auch im colorchannelmixer von FFmpeg erscheinen. Bauen Sie diesen zuerst und verwenden Sie ihn, um Ihre Pipeline End-to-End zu validieren.
- Achten Sie auf Einheitskonflikte. Der Skia-Helligkeits-Offset liegt im 0–255 Bereich, während der GPU-Shader in −1…1 arbeitet — derselbe Schiebereglerwert ist auf einem Pfad dramatisch aggressiver, es sei denn, Sie normalisieren bewusst.
- Manche Mappings sind Annäherungen, und das ist eine Entscheidung. FFmpeg’s eq hat keine Belichtungssteuerung, daher approximiert der Export die Belichtung mit einer inversen Gammakurve. Lineare Gain-Vorschau vs. Gammakurven-Export weichen in den Schatten ab. Akzeptabel? Vielleicht — aber entscheiden Sie es bewusst und schreiben Sie es auf.
- Achten Sie auf Parameter, die stillschweigend degradieren. In einer frühen Version steuerte der Weißabgleich-Kelvin-Schieberegler die GPU-Vorschau wunderschön — während der Export eine fest codierte Farbtemperatur ausgab. Der Benutzer zog einen Schieberegler, der nichts an seinem endgültigen Video änderte. Überprüfen Sie jeden Parameter über alle drei Pfade hinweg.
- Nur-Vorschau-Filter müssen dies angeben. Verzerrungs- und Stilisierungseffekte (swirl, bulge, toon, kuwahara…) existieren nur als GPU-Shader; ihre Exportübersetzung gibt einen leeren String zurück und die Pipeline leitet das Originalvideo durch. Die UI muss dies ehrlich offenlegen — eine stille Diskrepanz zwischen Vorschau und Export ist der schnellste Weg, das Vertrauen eines Benutzers zu verlieren.
5. Performance-Notizen aus der Produktion
- GPU-Filter nicht verwenden, wenn eine Matrix es rendern kann. Der Strategie-Router sendet ~24 Farbfilter durch ColorFiltered — effektiv kostenlos, funktioniert mit Netzwerk-Streams, funktioniert überall dort, wo Skia komponiert. Die GPU-Oberfläche ist für lokale Dateien und Shader-spezifische Effekte reserviert.
- Schlüsseln Sie die GPU-Oberfläche; mutieren Sie sie nicht. ValueKey('${clipIndex}_${filterId}') und vollständige Neuerstellung ist besser, als zu versuchen, Shader-Konfigurationen auf einem Live-Controller Hot-zu-swappen.
- Schieberegler entprellen (≈300 ms) — aktualisieren Sie den Status sofort für einen reaktionsschnellen Daumen, rendern Sie die gefilterte Vorschau träge neu.
- Überspringen Sie das Rendern von Miniaturansichten pro Filter, es sei denn, Sie benötigen es. Unser Filterkarussell verwendet Icon-Kacheln anstelle von 30 gefilterten Video-Miniaturansichten; das Generieren und Zwischenspeichern echter gefilterter Vorschauen pro Filter pro Clip ist ein trügerisch hoher Aufwand auf Low-End-Geräten für einen marginalen UX-Gewinn.
- Spärlich persistent speichern. Intensität wird nur geschrieben, wenn < 1.0; null bedeutet „volle Stärke“. Kleine Entscheidungen wie diese halten pro-Clip-JSON schlank, wenn Projekte Dutzende von Clips enthalten.
Gelernte Lektionen
- Es gibt keine einzige „Filterimplementierung“. Akzeptieren Sie, dass Vorschau und Export unterschiedliche Engines sind; entwerfen Sie eine kanonische Parameter-Map und behandeln Sie jeden Renderer als eine Projektion davon.
- Routen nach Fähigkeit. Eine dreistufige Strategie (Farbmatrix → Custom Painter → GPU/nur Export) bietet den meisten Filtern eine kostenlose Echtzeit-Vorschau und spart den teuren Pfad für Effekte, die ihn verdienen.
- Intensität ist die günstigste Premium-Funktion, die Sie je ausliefern werden — ein Matrix-Lerp in der Vorschau, ein Split/Blend in FFmpeg.
- Parität ist eine Testoberfläche. Rendern Sie einen Frame durch jeden Pfad mit denselben Parametern und vergleichen Sie. Die Diskrepanzen, die Sie finden werden (Einheiten, Gamma vs. Gain, fest codierte Konstanten), sind genau die, die Benutzer für Sie gefunden hätten.
- Seien Sie ehrlich in der UI. Wenn ein Filter nur beim Export — oder nur in der Vorschau — existiert, kennzeichnen Sie ihn. Vertrauen überlebt fehlende Funktionen; es überlebt keine Überraschungen.
Das Ergebnis: ein Filtersystem mit Live-Vorschau auf allem, von einem preisgünstigen Android-Telefon bis zu einem Desktop-Build, Schieberegler-Anpassungen mit sofortigem Feedback, benannten Presets und Exporten, die so aussehen, wie der Benutzer sie gesehen hat — aufgebaut aus einer Parameter-Map und drei sorgfältig abgeglichenen Renderern.
