AVAsset Class Reference

Inherits from
NSObject
Conforms to
NSCopying
AVAsynchronousKeyValueLoading
NSObject (NSObject)
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Companion guide
AV Foundation Programming Guide
Declared in
AVAsset.h
AVVideoComposition.h
Related sample code

Overview

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 a concrete subclass of AVAsset; for example, you can initialize an instance of AVURLAsset using an URL that refers to an audiovisual media file, such as a QuickTime movie file or an MP3 files (amongst 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. To assemble audiovisual constructs from one or more source assets, you can insert assets into instances of AVMutableComposition.

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 will always return 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 tem 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 can also be inserted 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.

Tasks

Creating an Asset

Loading Data

Accessing Metadata

Accessing Tracks

Determining Usability

Getting a New Track ID

Accessing Common Metadata

Preferred Asset Attributes

Managing Reference Restrictions

Media Selections.

Properties

availableChapterLocales

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

@property(readonly) NSArray *availableChapterLocales
Discussion

The array contains instances of NSLocale.

Availability
  • Available in iOS 4.3 and later.
See Also
Declared In
AVAsset.h

availableMediaCharacteristicsWithMediaSelectionOptions

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

@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.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVAsset.h

availableMetadataFormats

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

@property(nonatomic, readonly) NSArray *availableMetadataFormats
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsset.h

commonMetadata

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

@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).

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVAsset.h

compatibleWithSavedPhotosAlbum

Indicates whether the asset can be written to the Saved Photos album. (read-only)

@property(nonatomic, readonly, getter=isCompatibleWithSavedPhotosAlbum) BOOL compatibleWithSavedPhotosAlbum
Availability
  • Available in iOS 5.0 and later.
Declared In
AVAsset.h

composable

Indicates whether the asset can be used within a segment of an AVCompositionTrack object. (read-only)

@property(nonatomic, readonly, getter=isComposable) BOOL composable
Availability
  • Available in iOS 4.3 and later.
Declared In
AVAsset.h

creationDate

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

@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 will provide an instance of NSDate. Otherwise the creation date is available only as a string value, using the AVMetadataItem stringValue method.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVAsset.h

duration

The duration of the asset. (read-only)

@property(nonatomic, readonly) CMTime duration
Discussion

If providesPreciseDurationAndTiming is NO, 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).

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVAsset.h

exportable

Indicates whether the asset can be exported using AVAssetExportSession. (read-only)

@property(nonatomic, readonly, getter=isExportable) BOOL exportable
Availability
  • Available in iOS 4.3 and later.
Declared In
AVAsset.h

hasProtectedContent

Indicates whether the asset has protected content. (read-only)

@property(nonatomic, readonly) BOOL hasProtectedContent
Availability
  • Available in iOS 4.2 and later.
Declared In
AVAsset.h

lyrics

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

@property(nonatomic, readonly) NSString *lyrics
Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsset.h

playable

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

@property(nonatomic, readonly, getter=isPlayable) BOOL playable
Availability
  • Available in iOS 4.3 and later.
Related Sample Code
Declared In
AVAsset.h

preferredRate

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

@property(nonatomic, readonly) float preferredRate
Discussion

This value is often, but not always, 1.0.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsset.h

preferredTransform

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

@property(nonatomic, readonly) CGAffineTransform preferredTransform
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsset.h

preferredVolume

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

@property(nonatomic, readonly) float preferredVolume
Discussion

This value is often, but not always, 1.0.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsset.h

providesPreciseDurationAndTiming

Indicates whether the asset provides precise timing. (read-only)

@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).

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVAsset.h

readable

Indicates whether the asset’s media data can be extracted using AVAssetReader. (read-only)

@property(nonatomic, readonly, getter=isReadable) BOOL readable
Availability
  • Available in iOS 4.3 and later.
Declared In
AVAsset.h

referenceRestrictions

The reference restrictions being used by the receiver. (read-only)

@property(nonatomic, readonly) AVAssetReferenceRestrictions referenceRestrictions
Discussion

For AVURLAsset, this property reflects the value passed in for AVURLAssetReferenceRestrictionsKey, if any.

The default value for this property is availableMediaCharacteristicsWithMediaSelectionOptions. See AVURLAssetReferenceRestrictionsKey for a full discussion of reference restrictions.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVAsset.h

tracks

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

@property(nonatomic, readonly) NSArray *tracks
Discussion

Tracks are instances of AVAssetTrack.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVAsset.h

Class Methods

assetWithURL:

Returns an asset for inspection of a media resource.

+ (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.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVAsset.h

Instance Methods

cancelLoading

Cancels the loading of all values for all observers.

- (void)cancelLoading
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsset.h

chapterMetadataGroupsBestMatchingPreferredLanguages:

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

- (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.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAsset.h

chapterMetadataGroupsWithTitleLocale:containingItemsWithCommonKeys:

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

- (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:.

Availability
  • Available in iOS 4.3 and later.
Declared In
AVAsset.h

mediaSelectionGroupForMediaCharacteristic:

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

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

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

Only AVMediaCharacteristicAudible and AVMediaCharacteristicLegible are currently supported.

  • Pass AVMediaCharacteristicAudible to obtain the group of available options for audio media in various languages and for various purposes, such as descriptive audio.

  • Pass AVMediaCharacteristicLegible to obtain the group of available options for subtitles in various languages and for various purposes.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVAsset.h

metadataForFormat:

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

- (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 metadataItemsFromArray:withLocale: (AVMetadataItem) or by key using metadataItemsFromArray:withKey:keySpace: (AVMetadataItem).

Special Considerations

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAsset.h

tracksWithMediaCharacteristic:

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

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

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

For valid values, see AVAssetTrack.

Return Value

An array of AVAssetTrack objects that present media with mediaCharacteristic, or nil 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.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVAsset.h

tracksWithMediaType:

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

- (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.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
AVAsset.h

trackWithTrackID:

Returns the track with a specified track ID.

- (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.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVAsset.h

unusedTrackID

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

- (CMPersistentTrackID)unusedTrackID
Availability
  • Available in iOS 4.0 and later.
Declared In
AVVideoComposition.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...