feat: add configurable minimum frame duration

Author: LOCKEDFILE

cached_network_image/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [4.1.0] - 2026-10-27
+
+* Add an opt-in `minFrameDuration` setting for short frames in animated images, including WebP and APNG
+
 ## [4.0.5] - 2026-10-17
 
 * Stop decoding a static image again each time a listener is re-added, which blanked images on web (Firefox and Safari) after navigating back to a route

cached_network_image/lib/src/cached_image_widget.dart

@@ -199,6 +199,13 @@ class CachedNetworkImage extends StatelessWidget {
   /// Listener to be called when images fails to load.
   final ValueChanged<Object>? errorListener;
 
+  /// Minimum duration for frames in animated images, including WebP and APNG.
+  ///
+  /// Frames with a duration of 10ms or less are displayed for at least this
+  /// duration, and never less than 100ms. Defaults to null, which preserves
+  /// the duration reported by the image codec.
+  final Duration? minFrameDuration;
+
   /// CachedNetworkImage shows a network image using a caching mechanism. It also
   /// provides support for a placeholder, showing an error and fading into the
   /// loaded image. Next to that it supports most features of a default Image
@@ -236,6 +243,7 @@ class CachedNetworkImage extends StatelessWidget {
     ImageRenderMethodForWeb imageRenderMethodForWeb =
         ImageRenderMethodForWeb.HtmlImage,
     double scale = 1.0,
+    this.minFrameDuration,
   }) : _image = CachedNetworkImageProvider(
          imageUrl,
          headers: httpHeaders,
@@ -246,6 +254,7 @@ class CachedNetworkImage extends StatelessWidget {
          maxHeight: maxHeightDiskCache,
          errorListener: errorListener,
          scale: scale,
+         minFrameDuration: minFrameDuration,
        );
 
   @override

cached_network_image/lib/src/image_provider/cached_network_image_provider.dart

@@ -29,6 +29,7 @@ class CachedNetworkImageProvider
     this.cacheManager,
     this.cacheKey,
     this.imageRenderMethodForWeb = ImageRenderMethodForWeb.HtmlImage,
+    this.minFrameDuration,
   });
 
   /// CacheManager from which the image files are loaded.
@@ -63,6 +64,13 @@ class CachedNetworkImageProvider
   /// Render option for images on the web platform.
   final ImageRenderMethodForWeb imageRenderMethodForWeb;
 
+  /// Minimum duration for frames in animated images, including WebP and APNG.
+  ///
+  /// Frames with a duration of 10ms or less are displayed for at least this
+  /// duration, and never less than 100ms. Defaults to null, which preserves
+  /// the duration reported by the image codec.
+  final Duration? minFrameDuration;
+
   @override
   Future<CachedNetworkImageProvider> obtainKey(
     ImageConfiguration configuration,
@@ -81,6 +89,7 @@ class CachedNetworkImageProvider
       codec: _loadBufferAsync(key, chunkEvents, decode),
       chunkEvents: chunkEvents.stream,
       scale: key.scale,
+      minFrameDuration: key.minFrameDuration,
       debugLabel: key.url,
       informationCollector: () => <DiagnosticsNode>[
         DiagnosticsProperty<ImageProvider>('Image provider', this),
@@ -133,6 +142,7 @@ class CachedNetworkImageProvider
       codec: _loadImageAsync(key, chunkEvents, decode),
       chunkEvents: chunkEvents.stream,
       scale: key.scale,
+      minFrameDuration: key.minFrameDuration,
       debugLabel: key.url,
       informationCollector: () => <DiagnosticsNode>[
         DiagnosticsProperty<ImageProvider>('Image provider', this),
@@ -180,13 +190,15 @@ class CachedNetworkImageProvider
       return ((cacheKey ?? url) == (other.cacheKey ?? other.url)) &&
           scale == other.scale &&
           maxHeight == other.maxHeight &&
-          maxWidth == other.maxWidth;
+          maxWidth == other.maxWidth &&
+          minFrameDuration == other.minFrameDuration;
     }
     return false;
   }
 
   @override
-  int get hashCode => Object.hash(cacheKey ?? url, scale, maxHeight, maxWidth);
+  int get hashCode => Object.hash(
+      cacheKey ?? url, scale, maxHeight, maxWidth, minFrameDuration);
 
   @override
   String toString() => 'CachedNetworkImageProvider("$url", scale: $scale)';

cached_network_image/lib/src/image_provider/multi_image_stream_completer.dart

@@ -9,6 +9,10 @@ import 'package:flutter/scheduler.dart';
 double get timeDilation => _timeDilation;
 double _timeDilation = 1;
 
+// Browsers commonly clamp animated image frame delays below 10ms to 100ms.
+const Duration _browserMinimumFrameDelay = Duration(milliseconds: 10);
+const Duration _browserFrameDelayFallback = Duration(milliseconds: 100);
+
 /// An ImageStreamCompleter with support for loading multiple images.
 class MultiImageStreamCompleter extends ImageStreamCompleter {
   /// The constructor to create an MultiImageStreamCompleter. The [codec]
@@ -18,6 +22,7 @@ class MultiImageStreamCompleter extends ImageStreamCompleter {
   MultiImageStreamCompleter({
     required Stream<ui.Codec> codec,
     required this._scale,
+    this.minFrameDuration,
     String? debugLabel,
     Stream<ImageChunkEvent>? chunkEvents,
     InformationCollector? informationCollector,
@@ -57,6 +62,13 @@ class MultiImageStreamCompleter extends ImageStreamCompleter {
     }
   }
 
+  /// Minimum duration for frames in animated images, including WebP and APNG.
+  ///
+  /// Frames with a duration of 10ms or less are displayed for at least this
+  /// duration, and never less than 100ms. If null, frame durations are used
+  /// without adjustment.
+  final Duration? minFrameDuration;
+
   ui.Codec? _codec;
   ui.Codec? _nextImageCodec;
   final double _scale;
@@ -108,6 +120,14 @@ class MultiImageStreamCompleter extends ImageStreamCompleter {
     _frameCallbackScheduled = false;
     if (!hasListeners || _nextFrame == null) return;
     if (_isFirstFrame() || _hasFrameDurationPassed(timestamp)) {
+      final frameDuration = _nextFrame!.duration;
+      _frameDuration = minFrameDuration != null &&
+              frameDuration <= _browserMinimumFrameDelay &&
+              frameDuration < minFrameDuration!
+          ? minFrameDuration! > _browserFrameDelayFallback
+              ? minFrameDuration!
+              : _browserFrameDelayFallback
+          : frameDuration;
       _emitFrame(
         ImageInfo(
           image: _nextFrame!.image,
@@ -116,11 +136,6 @@ class MultiImageStreamCompleter extends ImageStreamCompleter {
         ),
       );
       _shownTimestamp = timestamp;
-      _frameDuration = _nextFrame!.duration;
-
-      if (_frameDuration! <= const Duration(milliseconds: 10)) {
-        _frameDuration = const Duration(milliseconds: 100);
-      }
 
       _nextFrame = null;
       if (_framesEmitted % _codec!.frameCount == 0 && _nextImageCodec != null) {

cached_network_image/pubspec.yaml

@@ -6,7 +6,7 @@ topics:
   - cache
   - image
   - network-image
-version: 4.0.5
+version: 4.1.0
 
 environment:
   sdk: ^3.12.0

cached_network_image/test/image_stream_completer_test.dart

@@ -90,6 +90,67 @@ void main() {
     expect(tester.takeException(), 'failure message');
   });
 
+  testWidgets('minimum frame duration clamps 0ms and 10ms, not 11ms', (
+    WidgetTester tester,
+  ) async {
+    final codecStream = StreamController<Codec>();
+    final mockCodec = MockCodec()..frameCount = 5;
+    final images = <Image>[];
+    final completer = MultiImageStreamCompleter(
+      codec: codecStream.stream,
+      scale: 1.0,
+      minFrameDuration: const Duration(milliseconds: 100),
+    );
+    completer.addListener(
+      ImageStreamListener((ImageInfo info, bool synchronousCall) {
+        images.add(info.image);
+      }),
+    );
+    codecStream.add(mockCodec);
+    await tester.idle();
+
+    mockCodec.completeNextFrame(
+      FakeFrameInfo(const Duration(milliseconds: 200), image20x10),
+    );
+    await tester.pump();
+    expect(images, <Image>[image20x10]);
+
+    // The zero-duration frame must be held for at least 100ms.
+    mockCodec.completeNextFrame(FakeFrameInfo(Duration.zero, image200x100));
+    await tester.idle();
+    await tester.pump(const Duration(milliseconds: 199));
+    expect(images, hasLength(1));
+    await tester.pump(const Duration(milliseconds: 1));
+    expect(images, hasLength(2));
+
+    mockCodec.completeNextFrame(
+      FakeFrameInfo(const Duration(milliseconds: 10), image300x100),
+    );
+    await tester.idle();
+    await tester.pump(const Duration(milliseconds: 99));
+    expect(images, hasLength(2));
+    await tester.pump(const Duration(milliseconds: 1));
+    expect(images, hasLength(3));
+
+    // The 11ms frame is not clamped, so the following frame appears after
+    // 11ms rather than 100ms.
+    mockCodec.completeNextFrame(
+      FakeFrameInfo(const Duration(milliseconds: 11), image20x10),
+    );
+    await tester.idle();
+    await tester.pump(Duration.zero);
+    expect(images, hasLength(4));
+
+    mockCodec.completeNextFrame(
+      FakeFrameInfo(const Duration(milliseconds: 200), image200x100),
+    );
+    await tester.idle();
+    await tester.pump(const Duration(milliseconds: 10));
+    expect(images, hasLength(4));
+    await tester.pump(const Duration(milliseconds: 1));
+    expect(images, hasLength(5));
+  });
+
   test('Completer unsubscribes to chunk events when disposed', () async {
     final codecStream = StreamController<Codec>();
     final chunkStream = StreamController<ImageChunkEvent>();