photo_manager

What's Changed

Features

• Add an optional type parameter to AssetPathEntity.getAssetListPaged and AssetPathEntity.getAssetListRange so callers can filter to a specific RequestType within a single album (e.g. read videos out of a common album) without constructing a new AssetPathEntity. Defaults to the album's own type when omitted.
• Add Darwin (iOS/macOS) only namespaced accessors AssetEntity.darwin and AssetPathEntity.darwin that group PhotoKit-specific reads without bloating the shared entity classes:
  • asset.darwin.cloudIdentifier and the batch PhotoManager.plugin.getCloudIdentifiers resolve stable cross-device cloud identifiers (iOS 15+/macOS 12+).
  • asset.darwin.hasAdjustments reports whether an asset has edits, and asset.darwin.getBaseFile() exports the unedited base file.
  • asset.darwin.getAdjustmentData() exports the raw AAE adjustment (edit-history) data backing an asset's edits, so callers can access the original resource, the edit metadata, and the rendered result separately (non-destructive editing).
  • path.darwin.getParentPathList() returns the parent folders containing an album or folder.
• Add updateCreationDate to PhotoManager.editor.darwin and PhotoManager.editor.android for modifying an asset's creation date after it has been saved.
  • On iOS/macOS: updates the PHAsset.creationDate property.
  • On Android Q (API 29)+: updates the MediaStore DATE_TAKEN field; unsupported on API 28 and below.
• Add PhotoManager.canManageMedia() and PhotoManager.requestManageMedia() for the Android 12 (API 31+) MANAGE_MEDIA special permission.

Improvements

• Migrate the Android plugin to Flutter's built-in Kotlin integration with a compatibility fallback for projects that still require kotlin-android, without changing the package's public Flutter or Dart version constraints.
• Fix the Android plugin namespace to com.fluttercandies.photo_manager so it matches the plugin package and Kotlin sources.

Fixes

• Fix Android PlatformExceptions from IllegalArgumentException: Volume external_primary not found by returning an empty cursor when MediaProvider reports the primary volume as unavailable, and guard the media-store ContentObserver against the same exception.
• Fix Darwin AssetEntity.originFile returning the locally-downsampled proxy for iCloud + "Optimize iPhone Storage"-affected photos by preferring PHImageManager with HighQualityFormat over writeDataForAssetResource on unedited raster primaries.
• Fix Darwin PhotoManager.editor.darwin.saveLivePhoto returning PHPhotosErrorDomain (-1) when the caller-supplied image and video lacked the shared Live Photo pairing identifier PHAssetCreationRequest requires.
• Fix iOS 18+ raising Unsupported fetch for asset collections with type 2 and subtype 2 when navigating into the primary album, caused by an invalid SmartAlbum + AlbumRegular combination in the recent-collection check.
• Fix Darwin AssetEntity.loadFile / originFile sporadically failing with PHPhotosErrorDomain (-1) for edited assets and Live Photos by walking multiple PHAssetResource candidates and falling back to PHImageManager for plain videos/images when writeDataForAssetResource exhausts them.
• Reduce built-in Kotlin migration warnings for supported project configurations while preserving legacy Flutter compatibility.
• Fix Darwin crashes when querying assets by local identifier by catching PhotoKit exceptions and returning safe fallback results instead of aborting the process.
• Fix the AssetEntity.duration API docs to clarify that audio and video durations are returned in seconds across supported platforms, preserving the existing API behavior.
• Fix Android 14+ limited permission photo selection not reflecting deselection in Flutter layer. When users modify their photo selection via presentLimited(), the changes are now properly notified to the Flutter layer.
• Fix delayed native deletion confirmation dialogs on iOS by elevating the dispatch queue priority of deleteWithIds, removeInAlbum, and deleteAlbum to QOS_CLASS_USER_INITIATED.
• Fix Android 14+ permission requests incorrectly short-circuiting when only part of the requested media access was already granted.
• Fix Android permission requests always asking for both image and video access regardless of RequestType. The plugin now only requests READ_MEDIA_IMAGES / READ_MEDIA_VIDEO matching the caller's RequestType, so the Android 14+ system photo picker only shows the media types the app actually asked for.
• Fix Darwin video durations being truncated instead of rounded, so AssetEntity.duration matches the system album display more closely.
• Fix Darwin getTitleAsync returning a null channel result by falling back to an empty string.
• Fix Darwin Live Photo exports with an explicit darwinFileType, restoring iOS conversions such as Live Photo MOV-to-MP4 output.
• Fix Darwin image loadFile(isOrigin: false) blocking the iOS UI thread by making the request asynchronous and moving JPEG file conversion off the main thread, allowing PMProgressHandler updates to arrive while loading.
• Fix presentLimited() on iOS resolving the presenting view controller through the deprecated UIApplication.keyWindow, which can return the wrong window (or none) once an app adopts the UIScene life cycle. The plugin now prefers the FlutterViewController attached to its own engine and falls back to scanning the foreground-active UIWindowScene for the key window.
• Fix latitude/longitude/latLng being dropped whenever a coordinate component was exactly 0.0 (e.g. assets near the equator or prime meridian). Dart, Android, and iOS/macOS all used 0.0 as a "no location" sentinel; 0.0 is now treated as a valid coordinate, and the native platforms report the absence of location data as an explicit null instead.
• Replace the internal CC_MD5-based hash used to derive Darwin full-image cache filenames from PHAsset.localIdentifier with CC_SHA256, silencing the macOS 10.15+ deprecation warnings from CommonCrypto without changing observable behavior. Existing cached files under the plugin cache directory are re-created on first access after upgrade.

What's Changed

Improvements

• Improve output file extension recognition for Darwin platforms.
• Refactor CustomColumns to use platform-separated architecture.
• Add public platform behavior classes
  (AndroidCustomColumns, DarwinCustomColumns, OhosCustomColumns) for CustomColumns.
• Avoid UnsupportedError when using CustomFilter in non-mobile environments (e.g., CI/Unit tests).
• Bump compileSdkVersion to 36 for Android.
• Bump EXIF interface and Glide for Android.
• Code lints update for Android.

Full Changelog: v3.8.3...v3.9.0

What's Changed

Fixes

• Fix all media assets being returned when filterOption is not specified instead of respecting the requested type.

Full Changelog: v3.8.2...v3.8.3

What's Changed

Fixes

• Fix presentLimited type error.

Full Changelog: v3.8.1...v3.8.2

What's Changed

Fixes

• Fix SQL syntax error on Android when querying assets with pagination.

Full Changelog: v3.8.0...v3.8.1

What's Changed

Features

• Add Swift Package Manager support for iOS and macOS.
• Add cancelToken parameter to AssetEntity.loadFile.
• Add cancelAllRequest method to PhotoManager.
• The AssetEntity.getFile and AssetEntity.getOriginBytes methods are public.
• Add relativePathAsync getter to AssetPathEntity.
• Add iOS 18 smart album subtypes support:
  • smartAlbumSpatial - For spatial/3D photos
  • smartAlbumProRes - For ProRes videos
  • smartAlbumScreenRecordings - For screen recordings
  • smartAlbumReceipts - For receipts in the Utilities section
  • smartAlbumHandwriting - For handwriting in the Utilities section
  • smartAlbumIllustrations - For illustrations in the Utilities section
  • smartAlbumQRCodes - For QR codes in the Utilities section
• Add optional latitude, longitude, and creationDate parameters to saveImage, saveImageWithPath, and saveVideo methods.
  • On iOS: Sets location and creation date metadata for saved assets.
  • On Android Q+: Sets DATE_TAKEN field and location metadata for saved assets.
• Add batch asset move functionality using createWriteRequest API for Android 11+.

Improvements

• Remove implied FilterOptionGroups when querying paths and assets.
  This fixes assets finding when they were created in the future.
  Some edge cases regarding performance drops caused by the complicated sort queries might also get fixed.
• Add PermissionState.isLimited.

Fixes

• Fix type 'Null' is not a subtype of type 'Map<dynamic, dynamic>' error on Android when copying or moving assets fails.
  • Android now properly throws exceptions instead of returning null when copyAssetToGallery or moveAssetToGallery operations fail.
  • Dart side now handles null responses gracefully by throwing a PlatformException.
• Fix PHImageManager crash on iOS by ensuring all PHImageManager/PHCachingImageManager methods are called on the main thread.
  This resolves race conditions and deadlocks when thumbnail operations are dispatched to QoS background queues.
• Fix EXC_BAD_ACCESS crash caused by accessing deallocated memory in async blocks on iOS.
  • Fixed PHCachingImageManager methods: fetchThumb, exportAssetToFile, fetchFullSizeImageFile.
  • Fixed PHAssetResourceManager methods: fetchVideoResourceToFile, fetchOriginImageFile.
  • Fixed PHPhotoLibrary save methods: saveImage, saveImageWithPath, saveVideo, saveLivePhoto.
• Fix AssetEntity.latlngAsync() returning zero location for videos on Android by using MediaMetadataRetriever to extract location data from video files.
• Fix nullability mismatch for title parameter in saveVideo and saveImageWithPath methods.

New Contributors

• @ColaFanta made their first contribution in #1312
• @HubHive made their first contribution in #1295
• @toyaji made their first contribution in #1320

Full Changelog: v3.7.1...v3.8.0

What's Changed

• jvmTarget update by @AlexV525 in #1292

Full Changelog: v3.7.0...v3.7.1

What's Changed

Features

• Add includeHiddenAssets option to PMFilter and FilterOptionGroup to include hidden assets in the results on iOS.

Fixes

• Fix SizeConstraint not working for videos on Android. (#1275)
• Fix inconsistent resizing behavior between iOS and Android in thumbnailDataWithSize. (#1271)

Improvements

• No longer set sourceCompatibility and targetCompatibility for Android dynamically.
• Make native library's version parsed from the yaml.

New Contributors

• @benmccann made their first contribution in #1277

Full Changelog: v3.6.4...v3.7.0

Fixes

• Fix potential nil class value when unwrapping caught exceptions on Darwin.

Improvements

• Optimize task priority handling on Darwin by automatically assigning QoS levels based on method types.
• Optimize the default sort descriptors on Darwin.

Fixes

• Fix the incorrect type of conversion with the Live-Photo's duration on Darwin.

Fixes

• Fix request permissions for images and videos on Android API 33+.

Fixes

• Do not throw when querying non-existing assets in bulk on Android.

Features

• Allows to get the duration of a Live Photo with AssetEntity.durationWithOptions on iOS and macOS.

Improvements

• Improves the options when fetching a fixed number of assets on iOS and macOS.

Fixes

• Do not use privateFileURL on iOS 18+.
• Fixes saving MP4 videos will result in 3GP on Android API 30-.
• Fixes nullable results returned when saving images and videos on Android.

Improvements

• Get rid of @try @catch when toggling favorite on Darwin.

Fixes

• Fix no returned IDs after successful deletion on Android API 29+.
• Fix mediaLocation = true does not work on Android API 34.

Improvements

• Reuse files when saving images on Darwin.
• Returns non-nullable results as much as possible.
• Fix export session file type with videos for the first time on Darwin.

Features

• Provide PMDarwinAVFileType to help convert entities' files on iOS and macOS by making explicit exports.

Improvements

• Improve cache output path equality on iOS and macOS.
• Get the current resource filename rather than the raw one on iOS and macOS. Also the plugin expands the ability when getting titles.
• Use PHCachingImageManager to improve image memory caches on iOS and macOS.

Fixes

• Fix incorrect download finished prediction during iCloud file downloading.

Breaking Changes

saveLivePhoto now requires title rather than filename.

Features

• Add getPermissionState method to PhotoManager.

Improvements

• Adds a detached state for managers. Callers with those managers will first be aware of the detaching state before any actual calls to avoid crashes.
• Errors replied by the channel do not include detailed messages before. Now the code will unwrap certain exceptions to extract details from them.
• Expose progressHandler for AssetEntity.getMediaUrl.
• Expose withSubtype for AssetEntity.isLocallyAvailable to request if a Live Photo resource is available.

Fixes

• PHAssetResource with the type PHAssetResourceTypeFullSizeVideo does not count as a video type before, making the resource obtain ignore them.
• Fixes potential range exception when converting NSTimeInterval on Darwin.
• Fixes progress not being updated when getting the non-original video file on iOS.
• Fixes incorrect Live Photo resource being obtained which will result in a wrong aspect ratio.
• Fixes Live Photos saving exceptions with the paired video.
• Other lints and type promotion fixes.

Breaking Changes

saveImage now requires filename rather than title, other save methods do not require title anymore.

Improvements

• Allows saving assets with a given orientation value.
• Improves the reading sequence when saving assets, which likely fixes issues with wrong orientation value.
• Reads image size from EXIF rather than decoding from the bitmap factory.
• Upgrades Android EXIF library.
• Add verbose log for MethodChannelPlugin. (Use PhotoManager.setLog and pass verboseFilePath to enable it.)
• Add getVerboseFilePath for PhotoManager.

Fixes

• Access PMProgressHandler more safely on iOS/macOS to avoid crashes and unfinished results.

Fixes

• Do not require WRITE_EXTERNAL_STORAGE if not declared in the manifest with Android 29-.
• Fix fetchPathProperties exception on Android of API 28.

Improvements

• Declare NSPrivacyAccessedAPICategoryFileTimestamp for iOS privacy policies.

Fixes

• Fixes compile exceptions with Xcode versions that are not compatible with iOS 17.0.
• Modified the way to read the Java version in build.gradle.

Improvements

• Restores containsLivePhotos to true by default and deprecates it.
• Use the main resource's filename for the title by default on iOS.
• Support more methods on the OpenHarmony.

Fixes

• Fix obtaining the correct resource from various types of resources on iOS.
• Fix isLocallyAvailable for edited assets on iOS.

Improvements

• Update plugin structure for OpenHarmony.

Breaking Changes

• AssetPathEntity.darwinType and AssetPathEntity.darwinSubtype are deprecated.
• containsLivePhotos now defaults to false.

See the [Migration Guide][] for details of breaking changes.

Features

• Support OpenHarmony.

Fixes

• Do not predicate subtype images as adjusted on Darwin.
• Fix PMProgressHandler not getting notified when failed on Darwin.
• Merge Android API 29 and 30 PermissionDelegates which allows Android API 29 to grant permissions without WRITE_EXTERNAL_STORAGE.

Improvements

• Improve code formatting.
• Add privacy file for iOS/macOS. (#1120)

Breaking Changes

See the [Migration Guide][] for details of breaking changes.

Improvements

• Remove the restriction of getMediaUrl.

Fixes

• Fix PhotoManager.editor.deleteWithIds method not working on Android API 29.
• Dispatch channel calls in main thread on Darwin.
• Fix presentLimit did not finish on Android. (#1052)
• Fix requestPermissionExtend returns the incorrect status on Android API 34.

Fixes

• Upgrade android/build.gradle to load the current java version from some environment variables.
• Fix the setIgnorePermissionCheck method not working on Android.

Breaking Changes

See the [Migration Guide][] for details of breaking changes.

Features

• Support Android 14 with limited access to assets.

Fixes

• Correct the key when fetching video info with MMR on Android. (#997)
• Retrieve original media instead of one with adjustments/filters for subtype files on iOS. (#976)
• Returns original file name instead of FullSizeRender.* if this has adjustments on iOS. (#976)

Improvements

• Add locks to the image provider.

Fixes

• Fix namespace on Android.
• Remove the package definition from the manifest.
• Use math.pow(2^63)-1 to make Web compile work again.
• Fix the end argument of PhotoManager.getAssetListRange is being handled incorrectly on Darwin. (#962)

Features

• Support darwinType and darwinSubType in AssetPathEntity on iOS and macOS. (#950)

Improvements

• Roll dependencies on Android. (#933)

Fixes

• Fix filter option group. (#919)
• Fix originFileWithSubtype and fileWithSubtype for livePhoto.
• Fix: support only add permission for iOS/macOS. (#944)
• Fix: modified the output path for iOS(add id in next path).
• Fix: Fixed a possible problem with the permission for darwin.
• Fix: needTitle for CustomFilter.

Features

• Support CustomFilter for more filter options. (#901)
• Add two new static methods for PhotoManager:
  • getAssetCount for getting assets count.
  • getAssetListRange for getting assets between start and end.

Improvements

• Reply errors when thumbnails are failed to load on Android. (#883)

Improvements

• Always declare READ_EXTERNAL_STORAGE permission on Android. (#874)
• Upgrade Glide and Kotlin libraries version. (#872)
• Avoid using file-based saving methods on Android. (#871)
• Use ContentUris for retrieving Media URIs on Android. (#870)
• Improve media subtype on iOS. (#863)

Fixes

• Fix pending permissions request on Android. (#879)

Features

• Support saving Live Photos on iOS and macOS. (#851)
• Introduce DarwinEditor to replace IosEditor. (#855)

Improvements

• Use last modified date for Glide caches key on Android. (#848)

Features

• Support both legacy and scoped storage on Android. (#833)

Fixes

• Avoid duplicate copyItemAtURL for videos on iOS. (#840)
• Correct permission checks with requestPermissionExtend on Android 13. (#843)

Features

• Support Android 13 (API 33) permissions.

Improvements

• Adapt Flutter 3.3. (#820)
• Retrieve metadata for videos when empty on Android. (#819)

Fixes

• Fix saving videos with path on Android 29-. (#829)

Fixes

• Fix saving images with path on Android 29-. (#815)

Breaking Changes

• Introduce AssetPathEntity.assetCountAsync getter, which improves the speed when loading paths mainly on iOS, also:
  • Deprecate AssetPathEntity.assetCount.
  • Remove FilterOptionGroup.containsEmptyAlbum.

Improvements

• Improve assets change notify with better methods signature and checks. (#790)
• Add PermissionState.hasAccess getter for better condition judgement. (#792)
• Remove unnecessary assets fetch in getMediaUrl on iOS. (#793)
• Improve AssetEntity.obtainForNewProperties on iOS. (#794)
• Improve MD5Utils on iOS. (#802)
• Improve cache container mutations on iOS. (#803)
• Improve assets count assignments. (#804)
• Improve cursors conversion on Android. (#806)

Fixes

• Purpose video creation correctly on iOS. (#791)
• Mark assets as favorite on iOS. (#794)
• Fix not replied method calls (#800).
• Fix invalid RELATIVE_PATH obtains with cursors on Android Q-. (#810)

Improvements

• [iOS] Check canPerformEditOperation before performing change requests. (#782)

Fixes

• [Android] Fix orientation missing during conversions. (#783)

Improvements

• Expose PhotoManager.plugin. (#778)

Fixes

• Fix forceOldApi not well-called. (#778)
• Fix invalid type cast with AssetEntity.exists. (#777)

Improvements

• Correct PermissionRequestOption typo with a class type alias. Which also raised the Dart SDK constraint to 2.13.0.
• Catch throwables when reading EXIF.
• Improve Live-Photos filtering.