Mac Developer Library

Developer

AVFoundation Framework Reference AVMetadataItem Class Reference

Options
Deployment Target:

On This Page
Language:

AVMetadataItem

Inheritance


Conforms To


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in OS X v10.7 and later.

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.

  • key key Property

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

    Declaration

    Swift

    @NSCopying var key: protocol<NSCopying, NSObjectProtocol>! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • keySpace keySpace Property

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

    Declaration

    Swift

    var keySpace: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • commonKey commonKey Property

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

    Declaration

    Swift

    var commonKey: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func loadValuesAsynchronouslyForKeys(_ keys: [AnyObject]!, completionHandler handler: (() -> Void)!)

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func statusOfValueForKey(_ key: String!, error outError: NSErrorPointer) -> AVKeyValueStatus

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • value value Property

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

    Declaration

    Swift

    @NSCopying var value: protocol<NSCopying, NSObjectProtocol>! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • time time Property

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

    Declaration

    Swift

    var time: CMTime { get }

    Objective-C

    @property(readonly) CMTime time

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • duration duration Property

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

    Declaration

    Swift

    var duration: CMTime { get }

    Objective-C

    @property(readonly) CMTime duration

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • locale locale Property

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

    Declaration

    Swift

    @NSCopying var locale: NSLocale! { get }

    Objective-C

    @property(readonly, copy) NSLocale *locale

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • dataValue dataValue Property

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

    Declaration

    Swift

    var dataValue: NSData! { get }

    Objective-C

    @property(readonly) NSData *dataValue

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    var extraAttributes: [NSObject : AnyObject]! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • dataType dataType Property

    Indicates the data type of the metadata item's value. (read-only)

    Declaration

    Swift

    var dataType: String! { get }

    Objective-C

    @property(readonly, copy) NSString *dataType

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.10 and later.

  • The IETF BCP 47 (RFC 4646) language identifier of the metadata item. (read-only)

    Declaration

    Swift

    var extendedLanguageTag: String! { get }

    Objective-C

    @property(readonly, copy) NSString *extendedLanguageTag

    Discussion

    The value may be nil if no language tag information is available.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.10 and later.

  • Indicates the identifier of the metadata item. (read-only)

    Declaration

    Swift

    var identifier: String! { get }

    Objective-C

    @property(readonly, copy) NSString *identifier

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.10 and later.

  • Provides the metadata identifier that’s equivalent to a key and key space.

    Declaration

    Swift

    class func identifierForKey(_ key: AnyObject!, keySpace keySpace: String!) -> String!

    Objective-C

    + (NSString *)identifierForKey:(id)key keySpace:(NSString *)keySpace

    Parameters

    key

    The metadata key.

    keySpace

    The metadata key space.

    Return Value

    A metadata identifier equivalent to key and keySpace, or nil if no identifier can be constructed

    Discussion

    Metadata keys that are not instances of NSString, NSNumber, or NSData cannot be converted to metadata identifiers; they also cannot be written to media resources via AVAssetExportSession or AVAssetWriter. Metadata item keySpaces must be a string of one to four printable ASCII characters.

    For custom identifiers, the keySpace AVMetadataKeySpaceQuickTimeMetadata is recommended. This keySpace defines its key values to be expressed as reverse-DNS strings, which allows third parties to define their own keys in a well established way that avoids collisions.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.10 and later.

  • Returns the metadata key indicated by the identifier.

    Declaration

    Swift

    class func keyForIdentifier(_ identifier: String!) -> AnyObject!

    Objective-C

    + (id)keyForIdentifier:(NSString *)identifier

    Parameters

    identifier

    The metadata identifier.

    Return Value

    A metadata key.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.10 and later.

  • Returns the metadata keySpace indicated by the identifier.

    Declaration

    Swift

    class func keySpaceForIdentifier(_ identifier: String!) -> String!

    Objective-C

    + (NSString *)keySpaceForIdentifier:(NSString *)identifier

    Parameters

    identifier

    The metadata identifier.

    Return Value

    A metadata key.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    var stringValue: String! { get }

    Objective-C

    @property(readonly) NSString *stringValue

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    var numberValue: NSNumber! { get }

    Objective-C

    @property(readonly) NSNumber *numberValue

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • dateValue dateValue Property

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

    Declaration

    Swift

    var dateValue: NSDate! { get }

    Objective-C

    @property(readonly) NSDate *dateValue

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    class func metadataItemsFromArray(_ array: [AnyObject]!, withKey key: AnyObject!, keySpace keySpace: String!) -> [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    class func metadataItemsFromArray(_ array: [AnyObject]!, withLocale locale: NSLocale!) -> [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    class func metadataItemsFromArray(_ metadataItems: [AnyObject]!, filteredAndSortedAccordingToPreferredLanguages preferredLanguages: [AnyObject]!) -> [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    class func metadataItemsFromArray(_ metadataItems: [AnyObject]!, filteredByMetadataItemFilter metadataItemFilter: AVMetadataItemFilter!) -> [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.9 and later.

    See Also

    metadataItemFilterForSharing (AVMetadataItemFilter)

  • Filters an array of metadata items according to identifier.

    Declaration

    Swift

    class func metadataItemsFromArray(_ metadataItems: [AnyObject]!, filteredByIdentifier identifier: String!) -> [AnyObject]!

    Objective-C

    + (NSArray *)metadataItemsFromArray:(NSArray *)metadataItems filteredByIdentifier:(NSString *)identifier

    Parameters

    metadataItems

    An array of metadata items.

    identifier

    The identifier that must be matched for a metadata item to be copied to the output array. Items are considered a match not only when their identifiers are equal to the specified identifier, but also when their identifiers conform to the specified identifier.

    Return Value

    An array containing the metadata items that match the specified identifier.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in OS X v10.10 and later.