a flutter package that creates immersive, music-app-style animated backgrounds from any image. drop in a widget, pass an image, get a fluid background with orbital motion, heavy blur, and corner glows, all extracted from the image's dominant colors.
how it works
- 1pass an image to FluidBackground. it shows a matte fallback instantly (0ms startup)
- 2in the background, the extractor samples every 10th pixel, weights by vibrancy and center proximity, then clusters into 6 colors using weighted k-means
- 3the palette cross-fades in (1400ms): 4 layered image shaders with orbital motion, 80σ gaussian blur, corner radial glows
- 4results are cached by content hash. repeated calls return instantly
key decisions
one widget, not a theme system
v2 tried to do material design theming, WCAG compliance, multiple widget variants, and theme animations. too many problems. v3 does one thing: fluid backgrounds. simpler API, better result.
weighted k-means over simple averaging
averaging gives muddy colors. k-means with vibrancy weighting (saturation × 0.75 + lightness × 0.25) and center proximity boost produces the colors your eye actually notices in the image.
instant matte fallback
image extraction takes 60-140ms. showing nothing during that time feels broken. the matte gradient appears at 0ms, then the real palette cross-fades in. users never see a blank screen.
animation off by default
orbital motion looks great but drains battery. defaulting to static with opt-in animation respects the user's device. the toggle is smooth, resumes from frozen phase instead of jumping.
what i built
- FluidBackground widget: one-line immersive backgrounds with 4 layered shaders
- FluidPaletteExtractor: color extraction with smart sampling, vibrancy weighting, and perceptual scoring
- LRU cache (30 entries, SHA-1 keyed) with warmup API for pre-loading upcoming images
- matte treatment: blends near-whites with 14% gray, enforces dark base ≤ 0.22 lightness
- v1 → v2 → v3 migration path with full backward compatibility and deprecation warnings
- 59 unit tests covering all core algorithms
timeline
v1.0: CAM16 color extraction, WCAG compliance, 3 pre-built widgets
adaptive scoring for different image types, perceptual color space
v2.0: architectural rewrite. 12 modules from one monolithic file, 59 unit tests
original single-file approach didn't scale. modularized everything and added proper test coverage.
v3.0: complete redesign. dropped material theming, built FluidBackground widget
v2 was trying to solve too many problems. v3 does one thing: beautiful fluid backgrounds. simpler API, better result.
v3.1: fallback modes, palette caching, new extraction api