איך בנינו פילטרי וידאו בסגנון אינסטגרם ב-GPU ב-Flutter

מחוון אחד, שלושה מנגנוני רינדור: איך בנינו פילטרי וידאו בסגנון אינסטגרם עם GPU shaders לתצוגה מקדימה, Skia color matrices לכל מקום אחר, ו-FFmpeg לייצוא — ושמרנו על כך שכולם יספרו את אותו סיפור ויזואלי.

פילטרים נראים קלים. פילטרי וידאו אינם כאלה.

החלת גוון ספיה על תמונה ב-Flutter היא פעולה של שורה אחת – עוטפים אותה בווידג'ט ColorFiltered וסיימנו. החלתה על וידאו היא עניין שונה לחלוטין:

• התצוגה המקדימה חייבת לפעול ב-30–60 פריימים לשנייה על גבי וידאו מתנגן, בכל מכשיר שבבעלות המשתמש.
• המשתמש חייב להיות מסוגל לגרור מחוונים (בהירות, ניגודיות, גוון, טמפרטורה...) ולראות את התוצאה בשידור חי.
• והחלק האכזר: כשהם לוחצים על ייצוא, קובץ ה-MP4 עם הפילטר חייב להיראות בדיוק כמו שראו בתצוגה המקדימה – אך מנגנון הרינדור של התצוגה המקדימה (Flutter/GPU) ומנגנון הרינדור של הייצוא (FFmpeg) הם מנועים שונים לחלוטין שמעולם לא שמעו זה על זה.

פוסט זה עוסק באופן שבו בנינו את הצינור הזה בעורך וידאו של Flutter: קטלוג פילטרים עם הגדרות קבועות מראש והתאמות לפי פרמטר, תצוגה מקדימה חיה שבוחרת את מנגנון הרינדור הזול ביותר שיכול לבצע את המשימה, ונתיב ייצוא של FFmpeg שמשחזר את המראה. הלקח העיקרי מראש:

כל פילטר מיושם בסופו של דבר שלוש פעמים – כתצורת GPU shader, כ-Skia 4×5 color matrix, וכ-FFmpeg filter string – כולם מונעים על ידי מפת פרמטרים משותפת אחת. שמירה על עקביות ויזואלית בין שלושת היישומים החוזרים הללו היא האתגר ההנדסי האמיתי.

הארכיטקטורה: מפת פרמטרים אחת, שלושה מנגנוני רינדור

                       ┌────────────────────────────┐
                      │   מפת פרמטרים משותפת     │
                      │ {filterId, params, עוצמה 0–1     │
                      │        intensity}          │
                      └─────┬───────┬───────┬──────┘
                            │       │       │
              ┌──────────────┘       │       └───────────────┐
              ▼                      ▼                       ▼
  תצוגה מקדימה של GPU shader      Skia ColorFilter.matrix     FFmpeg -vf string
(flutter_gpu_video_       (תצוגה מקדימה חיה ראשית,      (ייצוא — הדבר היחיד
  filters, קליפים מקומיים)     פתרון גיבוי אוניברסלי)         שהמשתמשים שומרים)

שלושת הנתיבים קיימים מכיוון שלכל אחד מהם יתרון כלשהו:

1. GPU shaders (flutter_gpu_video_filters) מספקים אפקטים אמיתיים באיכות shader — עיוותים, טשטושים, מיפוי גוונים — אך החבילה מבצעת רינדור למשטח משלה ועובדת בצורה הטובה ביותר עם קבצי וידאו מקומיים.
2. Skia ColorFilter.matrix — מטריצת צבע 4×5 העוטפת את ווידג'ט הווידאו באמצעות ColorFiltered — היא כמעט ללא עלות, עובדת על כל ווידג'ט וידאו (כולל זרמי רשת), ומכסה את שני עשרות הפילטרים הנפוצים ביותר: בהירות, ניגודיות, ספיה, גווני אפור, גוון, צבעי-שניים (duotones)...
3. FFmpeg הוא מנגנון הרינדור היחיד שהפלט שלו נשמר בפועל על ידי המשתמש. הייצוא משחזר כל מראה כמחרוזת filter-graph (eq=, hue=, colorchannelmixer=...).

נתב אסטרטגיה קטן מחליט עבור כל פילטר איזה מנוע תצוגה מקדימה להשתמש בו:

// איזו אסטרטגיית תצוגה מקדימה יכולה לרנדר פילטר זה?
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 → stack a CustomPainter overlay on the video (vignette, pixelation, halftone — things a color matrix can't express)
• exportOnly → הצג את הווידאו המקורי בתוספת תג המודיע למשתמש שהאפקט יופיע בייצוא

נתב זה הוא ההחלטה היעילה ביותר מבחינת עלות במערכת: הוא מספק לכ-24 פילטרים תצוגה מקדימה חיה ללא עלות כמעט בכל מכשיר, ושומר את המנגנונים הכבדים עבור הפילטרים שדורשים זאת.

1. קטלוג הפילטרים, הגדרות קבועות והתאמות

כל פילטר בקטלוג הוא פריט דקלרטי קטן — ID, שם תצוגה, קטגוריה, ו (כאשר נתיב ה-GPU תומך בכך) מפעל לתצורת ה-shader:

const GpuVideoFilterItem({
  required this.id,
  required this.name,
  required this.icon,
  required this.category,
  this.createConfiguration, // () => GPUFilterConfiguration, כאשר תומך ב-GPU
});

GPUFilterConfiguration? getConfiguration() => createConfiguration?.call();

הגדרות קבועות מראש (Presets) הן פשוט חבילות פרמטרים בעלות שם המצביעות על פילטר — המראות המהירות "P1–P5" בממשק המשתמש:

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}),
];

התאמות הן מתארי פרמטרים מוגדרים עם טווחים, ערכי ברירת מחדל, ואף רמז לגרדיאנט כך שכל מחוון יכול לרנדר מסלול משמעותי (שחור←לבן לבהירות, קשת צבעים לגוון):

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)];

ערכי המחוון הנוכחיים חיים באובייקט מצב בלתי ניתן לשינוי, המוזן מערכי ברירת המחדל:

factory FilterAdjustmentState.fromDefaults(String filterId, List<FilterParameter> parameters) {
  return FilterAdjustmentState(
    filterId: filterId,
    parameterValues: Map.fromEntries(parameters.map((p) => MapEntry(p.id, p.defaultValue))),
  );
}

ופרט אחד בממשק המשתמש שחשוב יותר ממה שהוא נראה: עדכוני מחוון נכתבים למצב באופן מיידי (כך שהאצבע עוקבת אחר האגודל), אך רינדור התצוגה המקדימה מבוטל לאחר 300 מילישניות. ללא הביטול, גרירת מחוון בונה מחדש את תת-עץ הווידאו המסונן עשרות פעמים בשנייה והגרירה נתקעת; איתו, התצוגה המקדימה קופצת לערך הסופי ברגע שהאצבע מאטה.

מה שנשמר על הקליפ מינימלי בכוונה:

class Filters {
  final String? adjust;     // ID פילטר שנבחר ידנית, לדוגמה 'sepia'
  final String? presets;    // ID של הגדרה קבועה מראש, לדוגמה 'P1'
  final double? intensity;  // 0.0–1.0; null פירושו 1.0 (נשמר רק כאשר < 1.0)
  final Map<String, double>? parameters; // ערכי מחוון לפי פילטר
}

2. תצוגה מקדימה חיה, נתיב אחר נתיב

סוס העבודה: מטריצת צבע 4×5

רוב הקטלוג הוא מתמטיקת צבע, ומטריצות הצבע של Skia מבצעות מתמטיקת צבע בחינם. מנהל הפילטרים הופך ID פילטר + פרמטרים ל-ColorFilter.matrix:

static ColorFilter getColorFilter(String filterId, [Map<String, double> parameters = const {}]) {
  final matrix = _getColorMatrixWithParams(filterId, parameters);
  return ColorFilter.matrix(matrix);
}

מטריצות של פילטרים עם פרמטרים נבנות באופן דינמי. שתי דוגמאות – ושימו לב ל-×255, מכיוון שהיסטים של מטריצה נמצאים במרחב צבעים 0–255:

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];

עוצמת פילטר — מחוון ה-"כמה מהמראה הזה" הגלובלי — מיושמת כאינטרפולציה ישרה בין מטריצת האפקט למטריצת הזהות:

final interpolatedMatrix = List<double>.generate(20, (i) {
  return identityMatrix[i] + (effectMatrix[i] - identityMatrix[i]) * intensity;
});

שורה אחת זו מעניקה לכל פילטר צבע בקרת עוצמה של 0–100% בחינם, ללא עבודת shader או pipeline נוספת.

נתיב ה-GPU האמיתי

עבור קליפים מקומיים, העורך מחליף משטח מסונן GPU אמיתי מ-flutter_gpu_video_filters. מכיוון שהווידג'ט מקושר, שינוי הקליפ או הפילטר גורם להריסה וליצירה מחדש של המשטח כולו (בקר החבילה אינו אוהב החלפות תצורה חמות תוך כדי פעולה):

return GPUVideoSurfacePreview(
  key: ValueKey(filterKey), // '${clipIndex}_${filterId}' — כופה יצירה מחדש מלאה
  configuration: _gpuFilterConfiguration!,
  onViewCreated: (controller, sizeStream) async {
    _gpuPreviewController = controller;
    if (_mainController != null && _isPlaying) {
      _mainController!.pause(); // הימנע מהפעלה כפולה (ושמע כפול!)
    }
    await controller.setVideoSource(FileInputSource(File(clipInfo.assetPath!)));
    if (mounted) setState(() => _isGpuPreviewInitialized = true);
  },
);

תצורת ה-shader מורכבת עבור כל פילטר מתצורות הטיפוסים של החבילה, המוזנת על ידי אותה מפת פרמטרים שהמחוונים כותבים אליה:

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);

שני שיעורי מחזור חיים שנלמדו בשעות של דיבוג:

• השהה את הנגן הבסיסי לפני שמשטח ה-GPU מתחיל. תצוגת ה-GPU המקדימה מנגנת את הווידאו עצמו; שכח את ההשהיה ותקבל שני מפענחים המנגנים את אותו קליפ – כולל שמע כפול, מוסט מעט.
• פנה משאבים כראוי בשינוי פילטר: disconnect() את התצורה הישנה, צור פרמטרים חדשים לתצוגה מקדימה, connect() את החדשה, ופנה() את הבקר (בנוסף לבטל את המנוי ל-size-stream) בעת עזיבת המסך.

הפתעה שולחנית

במחשבים שולחניים, קצה-העורפי של הווידאו מבצע רינדור לתוך טקסטורה חיצונית העוקפת את הרכבת השכבות של Skia – לכן עטיפת הנגן ב-ColorFiltered אינה עושה כלום בשקט; אין שכבת Skia לשנות. הפתרון הוא לכפות רישום פיקסלים (rasterization) של השכבה הבסיסית (לדוגמה, BackdropFilter מוכנס מעל SizedBox.expand) כך שלמטריצת הצבע יהיו פיקסלים ממשיים לפעול עליהם. אם הפילטרים שלך "עובדים באנדרואיד אבל לא במחשב שולחני", זו כמעט בוודאות הסיבה.

3. ייצוא: בנייה מחדש של המראה ב-FFmpeg

התצוגה המקדימה מושכרת; הייצוא בבעלותנו. בזמן הייצוא, מודל ה-Filters השמור נפתר (פילטר שנבחר ידנית מקבל עדיפות על פני preset; מזהי preset ממופים בחזרה לפילטר + פרמטרים שלהם) ומתורגם למחרוזת פילטר של FFmpeg:

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)
}

עוצמה בייצוא: טריק הפיצול/מיזוג

זכור שהתצוגה המקדימה מיישמת עוצמה על ידי ביצוע lerp למטריצת הצבע לכיוון הזהות. ל-FFmpeg אין "matrix lerp" — אבל יש לו הרכבת זרמים. לכן, ייצוא בעוצמה חלקית מפצל את הווידאו, מסנן ענף אחד, וממזג אותו בחזרה על המקור באטימות השמורה:

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(' ');
}

זה לא זהה מתמטית ל-matrix lerp, אך תפיסתית זה קרוב — וזה עובד עבור כל מחרוזת פילטר, לא רק מטריצות צבע.

מעבר הפילטר הוא קידוד מחדש מבודד אחד בשרשרת ייצוא ארוכה יותר (התאמת קנבס ← פילטר ← אפקטים ← שכבות-על ← מיקס אודיו ← שרשור), עם -c:a copy ששומר על האודיו ללא שינוי עד לשלב המיקסינג הייעודי, ומשך המקור נבדק בכל שלב כדי לזהות סחף מוקדם.

4. טבלת השוויון: היכן שלושה מנגנוני רינדור מסכימים — והיכן לא

זהו החלק שאף אחד לא כותב עליו. ערך שמור אחד, שלוש פרשנויות:

שיעורים שנלמדו בעמל רב על שוויון:

• בחר פילטר אחד כאמת המידה שלך. ספיה משיגה שוויון מדויק מכיוון שאותם מקדמים 3×3 מופיעים הן במטריצת Skia והן ב-colorchannelmixer של FFmpeg. בנה אותו קודם והשתמש בו כדי לאמת את ה-pipeline שלך מקצה לקצה.
• היזהר מחוסר התאמה ביחידות. היסט הבהירות של Skia נמצא במרחב 0–255 בעוד ש-GPU shader עובד בטווח −1…1 — אותו ערך מחוון אגרסיבי באופן דרמטי יותר בנתיב אחד אלא אם כן אתה מנרמל בכוונה.
• חלק מהמיפויים הם קירובים, וזו החלטה. ל-eq של FFmpeg אין בקרת חשיפה, ולכן הייצוא מקרב חשיפה באמצעות עקומת גמא הפוכה. תצוגה מקדימה עם הגבר ליניארי מול ייצוא עם עקומת גמא חורגים בצללים. מקובל? אולי — אבל החלט זאת במודע ורשום זאת.
• שים לב לפרמטרים המדרדרים בשקט. בגרסה מוקדמת, מחוון קלווין לאיזון לבן הניע את תצוגת ה-GPU המקדימה בצורה יפהפייה – בעוד שהייצוא פלט טמפרטורת צבע קבועה. המשתמש גרר מחוון שלא עשה דבר לווידאו הסופי שלו. בקר כל פרמטר בכל שלושת הנתיבים.
• פילטרים לתצוגה מקדימה בלבד חייבים לציין זאת. אפקטי עיוות וסגנון (swirl, bulge, toon, kuwahara...) קיימים רק כ-GPU shaders; תרגום הייצוא שלהם מחזיר מחרוזת ריקה וה-pipeline מעביר את הווידאו המקורי. ממשק המשתמש חייב לחשוף זאת בכנות — חוסר התאמה שקט בין התצוגה המקדימה לייצוא הוא הדרך המהירה ביותר לאבד את אמון המשתמש.

5. הערות ביצועים מפיתוח

• אל תסנן GPU-filter מה שמטריצה יכולה לרנדר. נתב האסטרטגיה שולח כ-24 פילטרי צבע דרך ColorFiltered — למעשה בחינם, עובד על זרמי רשת, עובד בכל מקום ש-Skia מרכיבה. משטח ה-GPU שמור לקבצים מקומיים ואפקטים מבוססי shader בלבד.
• קשר את משטח ה-GPU; אל תשנה אותו. ValueKey('${clipIndex}_${filterId}') ויצירה מחדש מלאה עדיפים על ניסיון להחליף תצורות shader חמות בבקר חי.
• בטל רעידות במחוונים (≈300 מילישניות) — עדכן מצב מיד לאגודל מגיב, רנדר מחדש את התצוגה המקדימה המסוננת באופן עצל.
• דלג על רינדור תמונות ממוזערות לכל פילטר אלא אם אתה זקוק לכך. קרוסלת הפילטרים שלנו משתמשת באריחי אייקונים במקום 30 תמונות ממוזערות של וידאו מסונן; יצירה ואיפוס של תצוגות מקדימות מסוננות אמיתיות לכל פילטר ולכל קליפ היא עלות גדולה באופן מטעה במכשירים חלשים עבור שיפור שולי בממשק המשתמש (UX).
• שמור באופן דליל. עוצמה נכתבת רק כאשר < 1.0; null פירושו "עוצמה מלאה". בחירות קטנות כאלה שומרות על JSON רזה לכל קליפ כאשר לפרויקטים יש עשרות קליפים.

לקחים שנלמדו

1. אין "יישום פילטר" יחיד. קבל שתצוגה מקדימה וייצוא הם מנועים שונים; עצב מפת פרמטרים קנונית אחת והתייחס לכל מנגנון רינדור כאל היטל שלה.
2. נתב לפי יכולת. אסטרטגיה תלת-שכבתית (מטריצת צבע ← custom painter ← GPU/ייצוא בלבד) מעניקה לרוב הפילטרים תצוגה מקדימה חיה בחינם ושומרת את הנתיב היקר לאפקטים שזקוקים לו.
3. עוצמה היא התכונה הפרימיום הזולה ביותר שתשלח אי פעם — matrix lerp בתצוגה מקדימה, split/blend ב-FFmpeg.
4. שוויון הוא משטח בדיקה. רנדר פריימים דרך כל נתיב עם אותם פרמטרים והשווה. חוסר ההתאמות שתמצא (יחידות, גמא מול הגבר, קבועים קשיחים) הם בדיוק אלה שהמשתמשים היו מוצאים עבורך.
5. היה כן בממשק המשתמש. אם פילטר קיים רק בייצוא – או רק בתצוגה מקדימה – סמן זאת. אמון שורד תכונות חסרות; הוא לא שורד הפתעות.

התוצאה: מערכת פילטרים עם תצוגה מקדימה חיה על כל דבר, מטלפון אנדרואיד זול ועד בניית שולחן עבודה, התאמות ברמת מחוון עם משוב מיידי, הגדרות קבועות מראש בעלות שם, וייצוא שנראה כמו מה שהמשתמש ראה – בנויה ממפת פרמטרים אחת ושלושה מנגנוני רינדור מתואמים בקפידה.