iOS Developer Library

Developer

AVFoundation Framework Reference AVAsset Class Reference

Options
Deployment Target:

On This Page
Language:

AVAsset

Inherits From


Conforms To


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later

AVAsset is an abstract class to represent timed audiovisual media such as videos and sounds. Each asset contains a collection of tracks that are intended to be presented or processed together, each of a uniform media type, including but not limited to audio, video, text, closed captions, and subtitles.

An AVAsset object defines the collective properties of the tracks that comprise the asset. (You can access the instances of AVAssetTrack representing tracks of the collection, so you can examine each of these independently if you need to.)

You often instantiate an asset using AVURLAsset—a concrete subclass of AVAsset—with NSURLs that refer to audiovisual media resources, such as streams (including HTTP live streams), QuickTime movie files, MP3 files, and files of other types. You can also instantiate an asset using other concrete subclasses that extend the basic model for audiovisual media in useful ways, as AVComposition does for temporal editing.

Properties of assets as a whole are defined by AVAsset. Additionally, references to instances of AVAssetTrack representing tracks of the collection can be obtained, so that each of these can be examined independently.

Because of the nature of timed audiovisual media, upon successful initialization of an asset some or all of the values for its keys may not be immediately available. The value of any key can be requested at any time, and asset always returns its value synchronously, although it may have to block the calling thread in order to do so. In order to avoid blocking, you can register your interest in particular keys and to become notified when their values become available. For further details, see AVAsynchronousKeyValueLoading.

To play an instance of AVAsset, initialize an instance of AVPlayerItem with it, use the player item to set up its presentation state (such as whether only a limited timeRange of the asset should be played, etc.), and provide the player item to an AVPlayer object according to whether the items is to be played by itself or together with a collection of other items.

You can insert AVAsset objects into an AVMutableComposition object in order to assemble audiovisual constructs from one or more source assets.

Subclassing Notes

It is not currently possible to subclass AVAsset to handle streaming protocols or file formats that are not supported by the framework.

  • Returns an asset for inspection of a media resource.

    Declaration

    Swift

    class func assetWithURL(_ URL: NSURL!) -> AnyObject!

    Objective-C

    + (id)assetWithURL:(NSURL *)URL

    Parameters

    URL

    A URL that references a media resource.

    Return Value

    An instance of a subclass of AVAsset initialized with URL.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later

  • Cancels the loading of all values for all observers.

    Declaration

    Swift

    func cancelLoading()

    Objective-C

    - (void)cancelLoading

    Discussion

    Deallocation of an instance of the asset implicitly invokes this method if any loading requests are still outstanding.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • An array of metadata items for each common metadata key for which a value is available. (read-only)

    Declaration

    Swift

    var commonMetadata: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *commonMetadata

    Discussion

    The value is an array of AVMetadataItem objects, one for each metadata key from the common key space for which the asset has an available value. You can filter the array by locale using metadataItemsFromArray:withLocale: (AVMetadataItem) or by key using metadataItemsFromArray:withKey:keySpace: (AVMetadataItem).

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • An array of strings, each representing a metadata format that’s available to the asset. (read-only)

    Declaration

    Swift

    var availableMetadataFormats: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *availableMetadataFormats

    Discussion

    Metadata formats may include ID3, iTunes metadata, and so on. For more details, see AVMetadataItem.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • Returns an array of AVMetadataItem objects, one for each metadata item in the container of the specified format

    Declaration

    Swift

    func metadataForFormat(_ format: String!) -> [AnyObject]!

    Objective-C

    - (NSArray *)metadataForFormat:(NSString *)format

    Parameters

    format

    The metadata format for which you want items.

    Return Value

    An array of AVMetadataItem objects, one for each metadata item in the container of the specified format, or nil if there is no metadata of the specified format.

    Discussion

    You can filter the array by locale using the AVMetadataItem method metadataItemsFromArray:withLocale: or by key using the AVMetadataItem method metadataItemsFromArray:withKey:keySpace:. See the AVMetadataItemFilter and AVMetadataItem classes for additional methods for filtering.

    Special Considerations

    This method becomes callable without blocking when the data in the availableMetadataFormats property is already loaded.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • lyrics lyrics Property

    The lyrics of the asset suitable for the current locale. (read-only)

    Declaration

    Swift

    var lyrics: String! { get }

    Objective-C

    @property(nonatomic, readonly) NSString *lyrics

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • The locales available for chapters in the asset. (read-only)

    Declaration

    Swift

    var availableChapterLocales: [AnyObject]! { get }

    Objective-C

    @property(readonly) NSArray *availableChapterLocales

    Discussion

    The array contains instances of NSLocale.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.3 and later

  • Returns an array of chapters with a given title locale and containing specified keys.

    Declaration

    Swift

    func chapterMetadataGroupsWithTitleLocale(_ locale: NSLocale!, containingItemsWithCommonKeys commonKeys: [AnyObject]!) -> [AnyObject]!

    Objective-C

    - (NSArray *)chapterMetadataGroupsWithTitleLocale:(NSLocale *)locale containingItemsWithCommonKeys:(NSArray *)commonKeys

    Parameters

    locale

    The locale of the metadata items carrying chapter titles to be returned (the method supports the IETF BCP 47 specification of locales).

    commonKeys

    An array of common keys of AVMetadataItem to include in the returned array. AVMetadataCommonKeyArtwork is the only supported key.

    Return Value

    An array of AVTimedMetadataGroup objects.

    Discussion

    Each object in the returned array contains an AVMetadataItem object representing the chapter title, and the time range property of the AVTimedMetadataGroup object is equal to the time range of the chapter title item.

    An AVMetadataItem with the specified common key is added to an existing AVTimedMetadataGroup object if the time range (timestamp and duration) of the metadata item and the metadata group overlap.

    The locale of items not carrying chapter titles need not match the specified locale parameter. You can filter the returned items based on locale using metadataItemsFromArray:withLocale:.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.3 and later

  • Returns an array of chapters whose locale best matches the the list of preferred languages.

    Declaration

    Swift

    func chapterMetadataGroupsBestMatchingPreferredLanguages(_ preferredLanguages: [AnyObject]!) -> [AnyObject]!

    Objective-C

    - (NSArray *)chapterMetadataGroupsBestMatchingPreferredLanguages:(NSArray *)preferredLanguages

    Parameters

    preferredLanguages

    An array of NSString objects, each of which contains a canonicalized IETF BCP 47 language identifier. The order of the identifiers in the array reflects the preferred language order, with the most preferred language being first in the array. Typically, you pass the user’s preferred languages by retrieving this array from the preferredLanguages class method of NSLocale.

    Return Value

    An array of AVTimedMetadataGroup objects.

    Discussion

    Each object in the returned array contains an AVMetadataItem object representing the chapter title. The time range property of the AVTimedMetadataGroup object is equal to the time range of the chapter title item.

    All of the available chapter metadata is included in the metadata groups, including items with the common key AVMetadataCommonKeyArtwork, if such items are present. Items not carrying chapter titles are added to an existing AVTimedMetadataGroup object if the time range (timestamp and duration) of the metadata item and that of the metadata group overlaps. The locale of such items need not match the locale of the chapter titles.

    You can use the metadataItemsFromArray:filteredAndSortedAccordingToPreferredLanguages: method to further filter the metadata items in each group. You can also filter the returned items based on locale using the metadataItemsFromArray:withLocale: method.

    Special Considerations

    Becomes callable without blocking when the data in the availableChapterLocales property is already loaded.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later

  • tracks tracks Property

    The tracks contained by the asset. (read-only)

    Declaration

    Swift

    var tracks: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *tracks

    Discussion

    Tracks are instances of AVAssetTrack.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • Returns the track with a specified track ID.

    Declaration

    Swift

    func trackWithTrackID(_ trackID: CMPersistentTrackID) -> AVAssetTrack!

    Objective-C

    - (AVAssetTrack *)trackWithTrackID:(CMPersistentTrackID)trackID

    Parameters

    trackID

    The trackID of the requested asset track.

    Return Value

    The track with track ID trackID, or nil if no track with the specified ID is available.

    Discussion

    You can call this method without blocking when the data in the tracks property is already loaded.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • Returns an array of AVAssetTrack objects of the asset that present media with a specified characteristic.

    Declaration

    Swift

    func tracksWithMediaCharacteristic(_ mediaCharacteristic: String!) -> [AnyObject]!

    Objective-C

    - (NSArray *)tracksWithMediaCharacteristic:(NSString *)mediaCharacteristic

    Parameters

    mediaCharacteristic

    The media characteristic according to which receiver filters its asset tracks.

    For valid values, see Media Characteristics.

    Return Value

    An array of AVAssetTrack objects that present media with mediaCharacteristic, or an empty array if no tracks with the specified characteristic are available.

    Discussion

    You can call this method without blocking when the data in the tracks property is already loaded.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • Returns an array of the asset tracks of the asset that present media of a specified type.

    Declaration

    Swift

    func tracksWithMediaType(_ mediaType: String!) -> [AnyObject]!

    Objective-C

    - (NSArray *)tracksWithMediaType:(NSString *)mediaType

    Parameters

    mediaType

    The media type according to which the asset filters its tracks.

    Media types are defined in AVAssetTrack.

    Return Value

    An array of AVAssetTrack objects of the asset that present media of mediaType.

    Discussion

    You can call this method without blocking when the data in the tracks property is already loaded.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • An array containing all of the track groups in the asset. (read-only)

    Declaration

    Swift

    var trackGroups: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *trackGroups

    Discussion

    This is an array of AVAssetTrackGroup instances, each representing a different grouping of tracks in the asset.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

  • A Boolean value that indicates whether the asset has protected content. (read-only)

    Declaration

    Swift

    var hasProtectedContent: Bool { get }

    Objective-C

    @property(nonatomic, readonly) BOOL hasProtectedContent

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.2 and later

  • playable playable Property

    Indicates whether the asset, or its URL, can be used to initialize an instance of AVPlayerItem. (read-only)

    Declaration

    Swift

    var playable: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isPlayable) BOOL playable

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.3 and later

  • A Boolean value that indicates whether the asset can be exported using AVAssetExportSession. (read-only)

    Declaration

    Swift

    var exportable: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isExportable) BOOL exportable

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.3 and later

  • readable readable Property

    A Boolean value that indicates whether the asset’s media data can be extracted using AVAssetReader. (read-only)

    Declaration

    Swift

    var readable: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isReadable) BOOL readable

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.3 and later

  • A Boolean value that indicates whether the asset can be used within a segment of an AVCompositionTrack object. (read-only)

    Declaration

    Swift

    var composable: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isComposable) BOOL composable

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.3 and later

  • Returns an ID that is currently unused by any of the tracks in the asset.

    Declaration

    Swift

    func unusedTrackID() -> CMPersistentTrackID

    Objective-C

    - (CMPersistentTrackID)unusedTrackID

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • metadata metadata Property

    An array of metadata items for all metadata identifiers for which a value is available. (read-only)

    Declaration

    Swift

    var metadata: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *metadata

    Discussion

    The array of AVMetadataItem instances can be filtered according to language using the metadataItemsFromArray:filteredAndSortedAccordingToPreferredLanguages: method. They can be filtered by identifier using the metadataItemsFromArray:filteredByIdentifier: method.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later

  • duration duration Property

    The duration of the asset. (read-only)

    Declaration

    Swift

    var duration: CMTime { get }

    Objective-C

    @property(nonatomic, readonly) CMTime duration

    Discussion

    If providesPreciseDurationAndTiming is NOfalse, a best-available estimate of the duration is returned. You can set the degree of precision required for timing-related properties at initialization time for assets initialized with URLs (see AVURLAssetPreferPreciseDurationAndTimingKey in AVURLAsset).

    If providesPreciseDurationAndTiming is YEStrue the absolute precision, at whatever processing cost that entails–and cost can be significant for certain media formats, such as .mpg. If providesPreciseDurationAndTiming is set to NOfalse, a balance between precision and processing cost is returned as the duration. Setting the providesPreciseDurationAndTiming property to NOfalseis always sufficient for typical playback scenarios, and in that case for some media formats, such as .mov and .mp4, the precision is absolute anyway.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • A Boolean value that indicates whether the asset provides precise timing. (read-only)

    Declaration

    Swift

    var providesPreciseDurationAndTiming: Bool { get }

    Objective-C

    @property(nonatomic, readonly) BOOL providesPreciseDurationAndTiming

    Discussion

    You can set the degree of precision required for timing-related properties at initialization time for assets initialized with URLs (see AVURLAssetPreferPreciseDurationAndTimingKey in AVURLAsset).

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

    See Also

    duration

  • naturalSize naturalSize (iOS 5.0) Property

    The encoded or authored size of the visual portion of the asset. (read-only)

    Deprecation Statement

    Use the naturalSize and preferredTransform, as appropriate, of the asset’s video tracks instead (see also tracksWithMediaType:).

    Declaration

    Objective-C

    @property(nonatomic, readonly) CGSize naturalSize

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later

    Deprecated in iOS 5.0

  • The natural rate at which the asset is to be played. (read-only)

    Declaration

    Swift

    var preferredRate: Float { get }

    Objective-C

    @property(nonatomic, readonly) float preferredRate

    Discussion

    This value is often, but not always, 1.0.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • The preferred transform to apply to the visual content of the asset for presentation or processing. (read-only)

    Declaration

    Swift

    var preferredTransform: CGAffineTransform { get }

    Objective-C

    @property(nonatomic, readonly) CGAffineTransform preferredTransform

    Discussion

    The value is often, but not always, the identity transform.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • The preferred volume at which the audible media of asset is to be played. (read-only)

    Declaration

    Swift

    var preferredVolume: Float { get }

    Objective-C

    @property(nonatomic, readonly) float preferredVolume

    Discussion

    This value is often, but not always, 1.0.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later

  • An array of media characteristics for which a media selection option is available. (read-only)

    Declaration

    Swift

    var availableMediaCharacteristicsWithMediaSelectionOptions: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *availableMediaCharacteristicsWithMediaSelectionOptions

    Discussion

    The value of this property is an array of NSString objects, each string indicating a media characteristic for which a media selection option is available.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later

  • Returns an AVMediaSelectionGroup object that contains one or more options with the specified media characteristic.

    Declaration

    Swift

    func mediaSelectionGroupForMediaCharacteristic(_ mediaCharacteristic: String!) -> AVMediaSelectionGroup!

    Objective-C

    - (AVMediaSelectionGroup *)mediaSelectionGroupForMediaCharacteristic:(NSString *)mediaCharacteristic

    Parameters

    mediaCharacteristic

    A media characteristic for which you wish to obtain the available media selection options.

    Only AVMediaCharacteristicAudible, AVMediaCharacteristicVisual, and AVMediaCharacteristicLegible are currently supported.

    Return Value

    An AVMediaSelectionGroup object that contains one or more options with the media characteristic specified by mediaCharacteristic, or nil if none could be found.

    Discussion

    You can invoke this method without blocking when the key availableMediaCharacteristicsWithMediaSelectionOptions has been loaded.

    You can filter the options in the returned media selection group according to playability, locale, and additional media characteristics can be accomplished using the filtering methods defined in the AVMediaSelectionGroup class.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later

  • A Boolean value that indicates whether the asset can be written to the Saved Photos album. (read-only)

    Declaration

    Swift

    var compatibleWithSavedPhotosAlbum: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isCompatibleWithSavedPhotosAlbum) BOOL compatibleWithSavedPhotosAlbum

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later

  • Indicates the creation date of the asset. (read-only)

    Declaration

    Swift

    var creationDate: AVMetadataItem! { get }

    Objective-C

    @property(nonatomic, readonly) AVMetadataItem *creationDate

    Discussion

    The value of this property may be nil.

    If a creation date has been stored by the asset in a form that can be converted to an NSDate object, the dateValue property of the metadata item provides an instance of NSDate. Otherwise the creation date is available only as a string value, using the AVMetadataItem class’s stringValue method.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later