AVMetadataItem Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Declared in
AVMetadataItem.h
Related sample code

Overview

An AVMetadataItem object represents an item of metadata associated with an audiovisual asset or with one of its tracks. To create metadata items for your own assets, you use the mutable subclass, AVMutableMetadataItem.

Metadata items have keys that accord with the specification of the container format from which they’re drawn. Full details of the metadata formats, metadata keys, and metadata key spaces supported by AV Foundation are available among the defines in AV Foundation Metadata Key Constants Reference and AV Foundation iTunes Metadata Constants.

You can load values of a metadata item “lazily” using the methods from the AVAsynchronousKeyValueLoading protocol (see “Asynchronous Loading”). The AVAsset class and other classes in turn provide their metadata lazily so that you can obtain objects from those arrays without incurring overhead for items you don’t ultimately inspect.

You can filter arrays of metadata items using the methods of this class. For example, you can filter by key and key space, by locale, and by preferred language.

Tasks

Keys and Key Spaces

Asynchronous Loading

Accessing Values

Type Coercion

Filtering Arrays of Metadata Items

Properties

commonKey

The common key of the metadata item. (read-only)

@property(readonly, copy) NSString *commonKey
Discussion

This property contains the key that most closely corresponds to the key in the key property but that belongs to the common key space (AVMetadataKeySpaceCommon) as opposed to a format-specific key space. You can use this key to locate metadata items irrespective of the underlying media format.

If the value of the keySpace property is AVMetadataKeySpaceCommon, this property contains the same key as the key property.

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

dataValue

Provides the raw bytes of the value of the metadata item. (read-only)

@property(readonly) NSData *dataValue
Availability
  • Available in iOS 4.0 and later.
Declared In
AVMetadataItem.h

dateValue

The value of the metadata item formatted as a date. (read-only)

@property(readonly) NSDate *dateValue
Discussion

The value of this property is nil if the metadata value cannot be represented as a date.

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

duration

The duration of the metadata item. (read-only)

@property(readonly) CMTime duration
Availability
  • Available in iOS 4.2 and later.
Declared In
AVMetadataItem.h

extraAttributes

The additional attributes supplied by the metadata item. (read-only)

@property(readonly, copy) NSDictionary *extraAttributes
Discussion

Extra attributes, when they are present, are specific to metadata container formats and keys in their associated key-spaces. For example, the "attached picture" frame defined by the ID3 tag specification can be represented by an AVMetadataItem with keyspace AVMetadataKeySpaceID3, key AVMetadataID3MetadataKeyAttachedPicture, a value that carries the image data, and extra attributes that include a description of the picture as carried in the 'APIC' frame of the ID3 tag.

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

key

The key of the metadata item. (read-only)

@property(readonly, copy) id<NSObject, NSCopying> key
Discussion

The key property contains the true key used to identify the contents of the metadata item. This value is specific to the key space of the metadata item.

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

keySpace

The key space of metadata item’s key. (read-only)

@property(readonly, copy) NSString *keySpace
Discussion

The key space specified by this property is typically the default key space for the metadata container in which the metadata item is stored.

AV Foundation uses key spaces to group related sets of keys. For example, the framework defines different key spaces for common keys, iTunes keys, ID3 keys, and QuickTime keys. Key spaces aid in filtering arrays of metadata items.

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

locale

The locale of the metadata item. (read-only)

@property(readonly, copy) NSLocale *locale
Discussion

The locale may be nil if no locale information is available for the metadata item.

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

numberValue

The value of the metadata item formatted as a number. (read-only)

@property(readonly) NSNumber *numberValue
Discussion

The value of this property is nil if the metadata value cannot be represented as a number.

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

stringValue

The value of the metadata item formatted as a string. (read-only)

@property(readonly) NSString *stringValue
Discussion

The value of this property is nil if the metadata value cannot be represented as a string.

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

time

The timestamp of the metadata item. (read-only)

@property(readonly) CMTime time
Availability
  • Available in iOS 4.0 and later.
Declared In
AVMetadataItem.h

value

The value of the metadata item. (read-only)

@property(readonly, copy) id<NSObject, NSCopying> value
Availability
  • Available in iOS 4.0 and later.
Declared In
AVMetadataItem.h

Class Methods

metadataItemsFromArray:filteredAndSortedAccordingToPreferredLanguages:

Returns the subset of metadata items whose locales match one of the specified language identifiers.

+ (NSArray *)metadataItemsFromArray:(NSArray *)metadataItems filteredAndSortedAccordingToPreferredLanguages:(NSArray *)preferredLanguages
Parameters
metadataItems

An array of AVMetadataItem objects to be filtered and sorted.

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 containing the AVMetadataItem objects from the metadataItems parameter that match one of the specified languages.

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

metadataItemsFromArray:filteredByMetadataItemFilter:

Filters an array of metadata items using the metadata item filter.

+ (NSArray *)metadataItemsFromArray:(NSArray *)metadataItems filteredByMetadataItemFilter:(AVMetadataItemFilter *)metadataItemFilter
Parameters
metadataItems

An array of AVMetadataItems to be filtered.

metadataItemFilter

The AVMetadataItemFilter object for filtering the metadataItems.

Return Value

An instance of NSArray containing the metadata items in metadataItems that have not been removed by metadataItemFilter.

Availability
  • Available in iOS 7.0 and later.
See Also
Declared In
AVMetadataItem.h

metadataItemsFromArray:withKey:keySpace:

Returns from a given array an array of metadata items that match a specified key or key space.

+ (NSArray *)metadataItemsFromArray:(NSArray *)array withKey:(id)key keySpace:(NSString *)keySpace
Parameters
array

The array of AVMetadataItem objects to be filtered.

key

The key that must be matched for a metadata item to be included in the output array. The key is compared to the keys in the metadata in the array using isEqual:.

If you do not want to filter by key, pass nil.

keySpace

The key space that must be matched for a metadata item to be included in the output array. The key space is compared to the key spaces in the metadata in the array using isEqualToString:.

If you do not want to filter by key space, pass nil.

Return Value

An array of the metadata items from array that match key or keySpace.

Discussion

If the value in the keySpace parameter is AVMetadataKeySpaceCommon, the value of the metadata item’s commonKey property must match the value in the key parameter for the item to be returned. If the key parameter is nil, then all metadata items in the common key space are returned.

If the value in the keySpace parameter is nil or is not the constant for the common key space, the value of the metadata item’s key property must match the value in the key parameter for the item to be returned. If the key parameter itself is nil, then all metadata items in the specified key space are returned.

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

metadataItemsFromArray:withLocale:

Returns from a given array an array of metadata items that match a specified locale.

+ (NSArray *)metadataItemsFromArray:(NSArray *)array withLocale:(NSLocale *)locale
Parameters
array

The array of AVMetadataItem objects to be filtered.

locale

The locale that must be matched for a metadata item to be included in the output array.

Return Value

An array containing the AVMetadataItem objects from the array parameter that match the specified locale.

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

Instance Methods

loadValuesAsynchronouslyForKeys:completionHandler:

Tells the receiver to load the values of any of the specified keys that are not already loaded.

- (void)loadValuesAsynchronouslyForKeys:(NSArray *)keys completionHandler:(void (^)(void))handler
Parameters
keys

An array of NSString objects, each of which represents one of the required keys.

handler

The block to be invoked when loading succeeds, fails, or is cancelled.

Discussion

For full discussion, see AVAsynchronousKeyValueLoading.

Availability
  • Available in iOS 4.2 and later.
Declared In
AVMetadataItem.h

statusOfValueForKey:error:

Reports whether the value for a given key is immediately available without blocking.

- (AVKeyValueStatus)statusOfValueForKey:(NSString *)key error:(NSError **)outError
Parameters
key

The key whose status you want.

outError

If the status of the value for the key is AVKeyValueStatusFailed, upon return contains an NSError object that describes the failure that occurred.

Return Value

The current loading status of the value for key.

Discussion

For full discussion, see AVAsynchronousKeyValueLoading.

Availability
  • Available in iOS 4.2 and later.
Declared In
AVMetadataItem.h