Class

PHAsset

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

Overview

You fetch assets to begin working with them. Use the class methods listed in Fetching Assets to retrieve one or more PHAsset instances representing the assets you want to display or edit. For example, to fetch all the assets in an asset collection (such as an album or moment), use the fetchAssets(in:options:) method. Each fetch method takes a PHFetchOptions parameter that you can use to specify which assets you want to retrieve and how to sort them.

Assets contain only metadata. The underlying image or video data for any given asset might not be stored on the local device. However, depending on how you plan to use this data, you may not need to download all of it. For example, if you need to populate a collection view with thumbnail images, the Photos framework can manage downloading, generating, and caching thumbnails for each asset. For details, see PHImageManager.

Asset objects are immutable. To edit an asset’s metadata (for example, to mark it as a favorite photo), create a PHAssetChangeRequest object within a photo library change block. For more details on using change requests and change blocks to update the photo library, see PHPhotoLibrary.

Asset Versions and Editing Asset Content

For each photo asset, Photos keeps a previous and a current version of its image data, as well as a PHAdjustmentData object that describes the last edit the user made to each asset’s content. Your app uses this information to support resumable editing.

When you begin editing an asset, Photos first asks whether your app can interpret the adjustment data from the most recent edit. If so, Photos provides the previous version of the asset as input for your editing session. After you read the adjustment data and reconstruct the edit it describes, your app might let the user alter or revert the last edit or make further changes. (For example, adjustment data may describe filters applied to a photo. Your app reapplies those filters and allows the user to change filter parameters, add new filters, or remove filters.)

If your app does not support an asset’s adjustment data, Photos provides the current version of the asset as input to your editing session. The current version contains the rendered output of all past edits, so your app can further edit the asset but cannot alter or revert most recent edit.

For video assets, Photos does not store a previous version. If your app cannot read a video asset’s adjustment data, you must work with the current version of the video and future edits cannot make use of your app’s adjustment data.

To edit a PHAsset object’€™s photo or video content:

  1. Call the asset’s requestContentEditingInput(with:completionHandler:) method. The PHContentEditingInputRequestOptions object you provide for the options parameter controls whether your app can handle the asset’s adjustment data.

  2. Photos calls your completionHandler block, providing a PHContentEditingInput object you can use for retrieving the image or video data to be edited.

  3. Apply your edits to the asset. To allow a user to continue working with your edits later, create a new PHAdjustmentData object describing the changes.

  4. Initialize a PHContentEditingOutput object. For photo- or video-only assets, use the editing output’s properties to provide edited asset data. For Live Photo assets, create a PHLivePhotoEditingContext object to edit the Live Photo content.

  5. Commit your edits to the photo library by posting a change block to the shared PHPhotoLibrary object. In the block, create a PHAssetChangeRequest object and set its contentEditingOutput property to the editing output that you created.

    Each PHPhotoLibrary performChanges call prompts the user for permission to edit the contents of the photo library—to edit multiple assets in one batch, create multiple PHAssetChangeRequest objects within the same change block, each with its own corresponding PHContentEditingOutput object.

Symbols

Fetching Assets

class func fetchAssets(in: PHAssetCollection, options: PHFetchOptions?)

Retrieves assets from the specified asset collection.

class func fetchAssets(withLocalIdentifiers: [String], options: PHFetchOptions?)

Retrieves assets with the specified local-device-specific unique identifiers.

class func fetchKeyAssets(in: PHAssetCollection, options: PHFetchOptions?)

Retrieves assets marked as key assets in the specified asset collection.

class func fetchAssets(with: PHFetchOptions?)

Retrieves all assets matching the specified options.

class func fetchAssets(withBurstIdentifier: String, options: PHFetchOptions?)

Retrieves assets with the specified burst photo sequence identifier.

class func fetchAssets(withALAssetURLs: [URL], options: PHFetchOptions?)

Retrieves assets using URLs provided by the Assets Library framework.

Reading Asset Metadata

var mediaType: PHAssetMediaType

The type of the asset, such as video or audio.

var mediaSubtypes: PHAssetMediaSubtype

The subtypes of the asset, identifying special kinds of assets such as panoramic photo or high-framerate video.

var sourceType: PHAssetSourceType

The means by which the asset entered the user’s Photos library.

var pixelWidth: Int

The width, in pixels, of the asset’s image or video data.

var pixelHeight: Int

The height, in pixels, of the asset’s image or video data.

var creationDate: Date?

The date and time at which the asset was originally created.

var modificationDate: Date?

The date and time at which the asset was last modified.

var location: CLLocation?

The location information saved with the asset.

var duration: TimeInterval

The duration, in seconds, of the video asset.

var isFavorite: Bool

A Boolean value that indicates whether the user has marked the asset as a favorite.

var isHidden: Bool

A Boolean value that indicates whether the user has hidden the asset.

Editing an Asset

func canPerform(PHAssetEditOperation)

Returns whether the asset supports the specified editing operation.

func cancelContentEditingInputRequest(PHContentEditingInputRequestID)

Cancels a request for editing the asset’s content.

Working with Burst Photo Assets

var burstIdentifier: String?

The unique identifier shared by photo assets from the same burst sequence.

var burstSelectionTypes: PHAssetBurstSelectionType

The selection type of the asset in a burst photo sequence.

var representsBurst: Bool

A Boolean value that indicates whether the asset is the representative photo from a burst photo sequence.

Constants

PHAssetEditOperation

Values identifying possible actions an asset can support, used by the canPerform(_:) method.

PHContentEditingInputRequestID

An identifier for an asset content editing session.

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.

Editing Request Info Keys

Keys indicating the status of an asset content editing request, used in the completion handler of the requestContentEditingInput(with:completionHandler:) method.

Relationships

Inherits From