From 3d8803420e3f053ca1dc7bcc8e64aa2db5060384 Mon Sep 17 00:00:00 2001 From: iliya Date: Wed, 19 Nov 2025 21:09:08 +0200 Subject: [PATCH 1/3] [image_picker] Clarify maxDuration parameter behavior Updates documentation to explicitly state that the maxDuration parameter only applies when recording videos from the camera (ImageSource.camera), and is ignored when selecting videos from the gallery (ImageSource.gallery). This addresses confusion reported in issue #83630 where developers expected maxDuration to filter gallery video selections, but it only controls camera recording duration. Changes: - Updated README.md with detailed explanation and code examples - Enhanced dartdoc comments for pickVideo() method - Added important notes about gallery selection behavior Fixes https://github.com/flutter/flutter/issues/83630 --- packages/image_picker/image_picker/README.md | 33 +++++++++++++++++++ .../image_picker/lib/image_picker.dart | 10 ++++-- 2 files changed, 41 insertions(+), 2 deletions(-) diff --git a/packages/image_picker/image_picker/README.md b/packages/image_picker/image_picker/README.md index a112479edf4..0754a2ae754 100755 --- a/packages/image_picker/image_picker/README.md +++ b/packages/image_picker/image_picker/README.md @@ -183,6 +183,39 @@ final XFile? media = await picker.pickMedia(); final List medias = await picker.pickMultipleMedia(); ``` +### Video Duration Limitations + +When using `pickVideo()` with the `maxDuration` parameter, it's important to understand its behavior: + +- **Camera recording** (`ImageSource.camera`): The recording will automatically stop when the specified `maxDuration` is reached. +- **Gallery selection** (`ImageSource.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 +} +``` + ## 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..ceae6135d3e 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. From 63c0ec77abf5530ee1af5ab2e1e280713c39efec Mon Sep 17 00:00:00 2001 From: iliya Date: Wed, 19 Nov 2025 21:16:07 +0200 Subject: [PATCH 2/3] Add maxDuration clarification to pickMultiVideo() documentation Extends the documentation clarification to pickMultiVideo() method to maintain consistency across the API. This method only selects from the gallery, so maxDuration is always ignored. Addresses feedback from code review. --- .../image_picker/image_picker/lib/image_picker.dart | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/packages/image_picker/image_picker/lib/image_picker.dart b/packages/image_picker/image_picker/lib/image_picker.dart index ceae6135d3e..54b26f78d82 100755 --- a/packages/image_picker/image_picker/lib/image_picker.dart +++ b/packages/image_picker/image_picker/lib/image_picker.dart @@ -311,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. From 54e42afa2a3528efccd812d75871b68c44552ab8 Mon Sep 17 00:00:00 2001 From: iliya Date: Wed, 19 Nov 2025 21:23:58 +0200 Subject: [PATCH 3/3] Update README to mention pickMultiVideo() behavior Addresses remaining code review feedback by adding pickMultiVideo() to the Video Duration Limitations section in README. The maxDuration parameter is ignored for pickMultiVideo() as well, since it only selects from the gallery. Also added example code showing pickMultiVideo() usage with maxDuration. --- packages/image_picker/image_picker/README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/packages/image_picker/image_picker/README.md b/packages/image_picker/image_picker/README.md index 0754a2ae754..dac9b7c32c2 100755 --- a/packages/image_picker/image_picker/README.md +++ b/packages/image_picker/image_picker/README.md @@ -185,10 +185,10 @@ final List medias = await picker.pickMultipleMedia(); ### Video Duration Limitations -When using `pickVideo()` with the `maxDuration` parameter, it's important to understand its behavior: +When using `pickVideo()` or `pickMultiVideo()` with the `maxDuration` parameter, it's important to understand its behavior: -- **Camera recording** (`ImageSource.camera`): The recording will automatically stop when the specified `maxDuration` is reached. -- **Gallery selection** (`ImageSource.gallery`): The `maxDuration` parameter does **not** filter available videos. Users can select videos of any length, regardless of the `maxDuration` value. +- **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. @@ -214,6 +214,11 @@ 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