Framework

Photos

Work with image and video assets managed by the Photos app, including those from iCloud Photo Library and Live Photos. Fetch and cache full-sized assets or thumbnails asynchronously, revise content, and sync revisions to multiple devices.

Overview

In iOS and macOS, the Photos framework provides classes that support building photo editing extensions for the Photos app. In iOS and tvOS, the Photos framework also provides direct access to the photo and video assets managed by the Photos app, including the iCloud Photo Library. Use this framework to retrieve assets for display and playback, edit their image or video content, or work with collections of assets such as albums, moments, and iCloud Shared Albums.

Features & Concepts

In iOS and tvOS, the Photos framework includes a number of features for working directly with a user’s Photos library.

  • Fetching objects and requesting changes. Instances of the Photos framework model classes (PHAsset, PHAssetCollection, and PHCollectionList) represent the items a user works with in the Photos app: assets (images, videos, and Live Photos), collections of assets (such as albums or moments), and lists of collections (such as album folders or moment clusters). These objects are read-only, immutable, and contain only metadata.

    You work with assets and collections by fetching those that you’re interested in and then using those objects to fetch the data you need to work with. To make changes, you create change request objects and explicitly commit them to the shared PHPhotoLibrary object. This architecture makes it easy, safe, and efficient to work with the same assets from multiple threads or multiple apps and app extensions.

  • Change observing. Use the shared PHPhotoLibrary object to register a change handler for the assets and collections you fetch. Photos tells your app whenever another app or device changes the content or metadata of an asset or the list of assets in a collection. PHChange objects provide information about object state before and after each change with semantics that make it easy to update a collection view or similar interface.

  • Support for Photos app features. Use the PHCollectionList class to find assets corresponding to the Moments hierarchy in the Photos App. Use the PHAsset class to identify burst photos, panoramic photos, and high-frame-rate videos. When the iCloud Photo Library is enabled, assets and collections in the Photos framework reflect content available across all devices on the same iCloud account.

  • Asset and thumbnail loading and caching. Use the PHImageManager class to request images of assets at a specified size, or AV Foundation objects to work with video assets. The Photos framework automatically downloads or generates images to your specification, caching them for quick reuse. For faster performance with large numbers of assets—for example, when populating a collection view with thumbnails—the PHCachingImageManager subclass adds bulk preloading.

  • Asset content editing. The PHAsset and PHAssetChangeRequest classes define methods to request photo or video content for editing and to commit your edits to the photo library. To support continuity of editing between different apps and extensions, Photos keeps the current and previous versions of each asset, along a with PHAdjustmentData object that describes the last edit. If your app supports the adjustment data from a previous edit, you can allow the user to revert or alter the edit.

In iOS and macOS, the Photos framework provides classes for use in developing photo editing extensions for use in the Photos app; however, the principal class of an extension must adopt the PHContentEditingController protocol defined by the PhotosUI framework. For details on Photos app extensions, see App Extension Programming Guide and PhotosUI.

Symbols

Interacting with the Photos Library

You use the shared photo library object to get the user's permission for your app to access Photos content, to perform changes to assets and collections, and to register for update messages sent when the Photos library changes.

PHPhotoLibrary

A shared object that manages access to and changes in the user’s Photos library.

Retrieving and Examining Assets

These model classes represent the content of the Photos library: assets and collections. Instances of these classes are read-only, immutable, and contain only metadata. To work with assets and collections, you use these classes to fetch a set of objects matching a specified query.

PHAsset

A representation of an image, video or Live Photo in the Photos library.

PHAssetCollection

A representation of a Photos asset grouping, such as a moment, user-created album, or smart album.

PHCollectionList

A representation of a group containing Photos asset collections, such as a moments year or a folder of user-created albums.

PHCollection

The abstract superclass for Photos asset collections and collection lists.

PHObject

The abstract superclass for Photos model objects (assets and collections).

PHFetchResult

An ordered list of assets or collections returned from a Photos fetch method.

PHFetchOptions

A set of options that affect the filtering, sorting, and management of results that Photos returns when you fetch asset or collection objects.

Loading Asset Content

Use these classes to request the image, video, or Live Photo content associated with Photos assets. Photos automatically downloads or generates images to your specification, caching them for quick reuse. You can also request to preload images in batches for faster performance with large numbers of assets.

PHImageManager

Provides methods for retrieving or generating preview thumbnails and full-size image or video data associated with Photos assets.

PHCachingImageManager

Provides methods for retrieving or generating preview thumbnails and full-size image or video data associated with Photos assets, optimized for batch preloading large numbers of assets.

PHImageRequestOptions

A set of options affecting the delivery of still image representations of Photos assets you request from an image manager.

PHVideoRequestOptions

A set of options affecting the delivery of video asset data that you request from an image manager.

PHLivePhotoRequestOptions

A set of options affecting the delivery of Live Photo assets you request from an image manager.

PHLivePhoto

A displayable representation of a Live Photo—a picture that includes motion and sound from the moments just before and after its capture.

Requesting Changes

To make changes to assets or collections, you create change request objects describing your edits and explicitly commit them to the Photos library. This architecture makes it easy, safe, and efficient to work with the same assets from multiple threads or multiple apps and app extensions.

PHAssetChangeRequest

A request to create, delete, change metadata for, or edit the content of a Photos asset, for use in a photo library change block.

PHAssetCollectionChangeRequest

A request to create, delete, or modify a Photos asset collection, for use in a photo library change block.

PHCollectionListChangeRequest

A request to create, delete, or modify a Photos collection list, for use in a photo library change block.

PHObjectPlaceholder

A read-only proxy representing a Photos asset or collection object yet to be created by a change request.

Editing Asset Content

Use these classes in an app or extension to access asset data for editing and commit edits to the Photos library. Photos manages multiple versions of assets and adjustment data that describes each edit, so that your app or extension can allow a user to revert or continue working with edits made earlier, even on a different device.

To build photo editing extensions for the Photos app, use these classes together with the PhotosUI framework.

PHContentEditingInput

A container that provides information about and access to the image, video, or Live Photo content of an asset to be edited.

PHContentEditingOutput

A container to which you provide the results of editing the photo, video, or Live Photo content of a Photos asset.

PHAdjustmentData

A description of the edits made to an asset's photo, video, or Live Photo content, which allows your app to reconstruct or revert the effects of prior editing sessions.

PHContentEditingInputRequestOptions

A set of options affecting the delivery of image or video data when you request to edit the content of a Photos asset.

PHLivePhotoEditingContext

An editing session for modifying the photo, video, and audio content of a Live Photo.

PHLivePhotoFrame

A container that provides image content for a single frame of a Live Photo in an editing context.

Observing Changes

Photos tells your app whenever another app, another device, or code elsewhere in your app changes the content or metadata of an asset or the list of assets in a collection. These objects provide information about object state before and after each change, making it easy to update your user interface to match.

PHPhotoLibraryChangeObserver

A protocol you can implement to be notified of changes that occur in the Photos library.

PHChange

A description of a change that occurred in the Photos library.

PHObjectChangeDetails

A description of changes that occurred in an asset or collection object.

PHFetchResultChangeDetails

A description of changes that occurred in the set of asset or collection objects listed in a fetch result.

Working with Asset Resources

One or more asset resource objects represent the underlying data storage for each Photos asset. Use these objects to work with those resources directly—for example, to back up and restore assets.

PHAssetResource

An underlying data resource associated with a photo, video, or Live Photo asset in the Photos library.

PHAssetCreationRequest

A request to create a new Photos asset from underlying data resources, for use in a photo library change block.

PHAssetResourceCreationOptions

A set of options affecting the creation of a new Photos asset from underlying resources.

PHAssetResourceManager

Provides methods for accessing the underlying data storage for the resources associated with a Photos asset.

PHAssetResourceRequestOptions

A set of options affecting the delivery of underlying asset data that you request from the asset resource manager.

Media Types and Subtypes

Constants used with the PHAsset and PHContentEditingInput classes to identify or request different kinds of assets.

PHAssetMediaType

Constants identifying the general type of an asset, such as image or video.

PHAssetMediaSubtype

Constants identifying specific variations of asset media, such as panorama or screenshot photos and time lapse or high frame rate video.

Structures

PHAssetBurstSelectionType

Bit mask values indicating whether and how an asset is marked as a favorite member of a burst photo sequence. Used by the burstSelectionTypes property.

PHAssetSourceType

Means by which an asset enters the Photos library, used by the PHAssetSourceType property.

PHLivePhotoEditingOption

Reference

Photos Enumerations
Photos Constants

This document describes constants used throughout the Photos framework.

Photos Data Types