[image_picker] Clarify maxDuration parameter behavior

packages/image_picker/image_picker/README.md

@@ -183,6 +183,44 @@ final XFile? media = await picker.pickMedia();
 final List<XFile> medias = await picker.pickMultipleMedia();
 ```
 
+### Video Duration Limitations
+
+When using `pickVideo()` or `pickMultiVideo()` with the `maxDuration` parameter, it's important to understand its behavior:
+
+- **Camera recording** (`ImageSource.camera` for `pickVideo()`): The recording will automatically stop when the specified `maxDuration` is reached.
+- **Gallery selection** (`ImageSource.gallery` for `pickVideo()`, or `pickMultiVideo()` which only picks from gallery): The `maxDuration` parameter does **not** filter available videos. Users can select videos of any length, regardless of the `maxDuration` value.
+
+If your application needs to enforce duration limits on gallery-selected videos, you must validate the video duration programmatically after selection.
+
+**Example:**
+
+```dart
+final ImagePicker picker = ImagePicker();
+
+// Recording from camera - stops automatically at 30 seconds
+final XFile? recordedVideo = await picker.pickVideo(
+  source: ImageSource.camera,
+  maxDuration: const Duration(seconds: 30),
+);
+
+// Selecting from gallery - maxDuration is ignored, user can select any video
+final XFile? galleryVideo = await picker.pickVideo(
+  source: ImageSource.gallery,
+  maxDuration: const Duration(seconds: 30), // This does NOT filter gallery videos!
+);
+
+// You must validate gallery video duration yourself if needed
+if (galleryVideo != null) {
+  // Use a video player package to check duration
+  // and handle videos that exceed your requirements
+}
+
+// pickMultiVideo() also ignores maxDuration - it only picks from gallery
+final List<XFile> multipleVideos = await picker.pickMultiVideo(
+  maxDuration: const Duration(seconds: 30), // This does NOT filter gallery videos!
+);
+```
+
 ## Migrating to 1.0
 
 Starting with version 0.8.2 of the image_picker plugin, new methods were

packages/image_picker/image_picker/lib/image_picker.dart

@@ -271,8 +271,14 @@ class ImagePicker {
   /// The [source] argument controls where the video comes from. This can
   /// be either [ImageSource.camera] or [ImageSource.gallery].
   ///
-  /// The [maxDuration] argument specifies the maximum duration of the captured video. If no [maxDuration] is specified,
-  /// the maximum duration will be infinite.
+  /// The [maxDuration] argument specifies the maximum duration of the captured video when recording
+  /// from the camera ([ImageSource.camera]). The recording will automatically stop when this duration
+  /// is reached. If no [maxDuration] is specified, the maximum duration will be infinite.
+  ///
+  /// **Important:** The [maxDuration] parameter is ignored when selecting videos from the gallery
+  /// ([ImageSource.gallery]). Users can select videos of any duration from the gallery, regardless
+  /// of the [maxDuration] value. If you need to enforce duration limits on gallery-selected videos,
+  /// you must validate the video duration programmatically after selection.
   ///
   /// Use `preferredCameraDevice` to specify the camera to use when the `source` is [ImageSource.camera].
   /// The `preferredCameraDevice` is ignored when `source` is [ImageSource.gallery]. It is also ignored if the chosen camera is not supported on the device.
@@ -305,9 +311,13 @@ class ImagePicker {
   ///
   /// The videos come from the gallery.
   ///
-  /// The [maxDuration] argument specifies the maximum duration of the captured
-  /// videos. If no [maxDuration] is specified, the maximum duration will be
-  /// infinite. This value may be ignored by platforms that cannot support it.
+  /// The [maxDuration] argument specifies the maximum duration of the videos.
+  /// If no [maxDuration] is specified, the maximum duration will be infinite.
+  ///
+  /// **Important:** This method only picks videos from the gallery. The [maxDuration]
+  /// parameter is ignored and users can select videos of any duration. If you need
+  /// to enforce duration limits, you must validate the video durations programmatically
+  /// after selection.
   ///
   /// The `limit` parameter modifies the maximum number of videos that can be
   /// selected. This value may be ignored by platforms that cannot support it.