diff --git a/packages/image_picker/image_picker/README.md b/packages/image_picker/image_picker/README.md index a112479edf4..dac9b7c32c2 100755 --- a/packages/image_picker/image_picker/README.md +++ b/packages/image_picker/image_picker/README.md @@ -183,6 +183,44 @@ final XFile? media = await picker.pickMedia(); final List 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 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 diff --git a/packages/image_picker/image_picker/lib/image_picker.dart b/packages/image_picker/image_picker/lib/image_picker.dart index 0294b4b8b8d..54b26f78d82 100755 --- a/packages/image_picker/image_picker/lib/image_picker.dart +++ b/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.