<!--
{
  "availability" : [
    "iOS: 4.0.0 -",
    "iPadOS: 4.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.7.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AVFoundation",
  "identifier" : "/documentation/AVFoundation/AVMetadataItem",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AVFoundation"
    ],
    "preciseIdentifier" : "c:objc(cs)AVMetadataItem"
  },
  "title" : "AVMetadataItem"
}
-->

# AVMetadataItem

A metadata item for an audiovisual asset or one of its tracks.

```
class AVMetadataItem
```

## Overview

To effectively use `AVMetadataItem`, you need to understand how [`AVFoundation`](/documentation/AVFoundation) organizes metadata. To simplify finding and filtering metadata items, the framework groups related metadata into key spaces:

- **Format-specific key spaces.** The framework defines several format-specific key spaces. They roughly correlate to a particular container or file format, such as QuickTime (QuickTime metadata and user data) or MP3 (ID3). However, a single asset may contain metadata values across multiple key spaces. To retrieve an asset’s complete collection of format-specific metadata, you use its [`metadata`](/documentation/AVFoundation/AVAsset/metadata) property.
- **Common key space.** There are several common metadata values, such as a movie’s creation date or description, that can exist across multiple key spaces. To help normalize access to this common metadata, the framework provides a common key space that gives access to a limited set of metadata values common to several key spaces. This makes it easy to retrieve commonly used metadata without concern for the specific format. To retrieve an asset’s collection of common metadata, you use its [`commonMetadata`](/documentation/AVFoundation/AVAsset/commonMetadata) property.

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 AVFoundation are available in [`AVMetadataKeySpace`](/documentation/AVFoundation/AVMetadataKeySpace) and [`AVMetadataKey`](/documentation/AVFoundation/AVMetadataKey).

To load values of a metadata item when you access them for the first time, use the methods from the [`AVAsynchronousKeyValueLoading`](/documentation/AVFoundation/AVAsynchronousKeyValueLoading) protocol. The [`AVAsset`](/documentation/AVFoundation/AVAsset) class and other classes in turn provide their metadata as needed so that you can obtain objects from those arrays without incurring overhead for items you don’t inspect.

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

## Topics

### Creating a metadata item

[`init(propertiesOfMetadataItem:valueLoadingHandler:)`](/documentation/AVFoundation/AVMetadataItem/init(propertiesOfMetadataItem:valueLoadingHandler:))

Creates a metadata item whose value loads on an on-demand basis only.

[`AVMetadataItemValueRequest`](/documentation/AVFoundation/AVMetadataItemValueRequest)

An object that responds to a request to load the value of a metadata item.

### Identifying metadata items

[`identifier`](/documentation/AVFoundation/AVMetadataItem/identifier)

An identifier for a metadata item.

### Loading values

[`dataType`](/documentation/AVFoundation/AVMetadataItem/dataType)

The data type of the metadata item’s value.

[`value`](/documentation/AVFoundation/AVPartialAsyncProperty/value)

The value of the metadata item.

[`stringValue`](/documentation/AVFoundation/AVPartialAsyncProperty/stringValue)

The value of the metadata item as a string.

[`numberValue`](/documentation/AVFoundation/AVPartialAsyncProperty/numberValue)

The value of the metadata item as a number.

[`dateValue`](/documentation/AVFoundation/AVPartialAsyncProperty/dateValue)

The value of the metadata item as a date.

[`dataValue`](/documentation/AVFoundation/AVPartialAsyncProperty/dataValue)

The value of the metadata item as a data value.

[`extraAttributes`](/documentation/AVFoundation/AVPartialAsyncProperty/extraAttributes)

A dictionary of additional attributes for the item.

### Accessing keys and key spaces

[`key`](/documentation/AVFoundation/AVMetadataItem/key)

The key of the metadata item.

[`commonKey`](/documentation/AVFoundation/AVMetadataItem/commonKey)

The common key of the metadata item.

[`keySpace`](/documentation/AVFoundation/AVMetadataItem/keySpace)

The key space for the metadata item’s key.

### Accessing timing

[`time`](/documentation/AVFoundation/AVMetadataItem/time)

The timestamp of the metadata item.

[`startDate`](/documentation/AVFoundation/AVMetadataItem/startDate)

The start date of the timed metadata.

[`duration`](/documentation/AVFoundation/AVMetadataItem/duration)

The duration of the metadata item.

### Accessing language support

[`locale`](/documentation/AVFoundation/AVMetadataItem/locale)

The locale of the metadata item.

[`extendedLanguageTag`](/documentation/AVFoundation/AVMetadataItem/extendedLanguageTag)

The IETF BCP 47 (RFC 4646) language identifier of the metadata item.

### Filtering arrays of metadata items

[`metadataItems(from:filteredByIdentifier:)`](/documentation/AVFoundation/AVMetadataItem/metadataItems(from:filteredByIdentifier:))

Returns metadata items for the specified identifier.

[`metadataItems(from:withKey:keySpace:)`](/documentation/AVFoundation/AVMetadataItem/metadataItems(from:withKey:keySpace:))

Returns metadata items that match a specified key or key space.

[`metadataItems(from:with:)`](/documentation/AVFoundation/AVMetadataItem/metadataItems(from:with:))

Returns metadata items that match a specified locale.

[`metadataItems(from:filteredAndSortedAccordingToPreferredLanguages:)`](/documentation/AVFoundation/AVMetadataItem/metadataItems(from:filteredAndSortedAccordingToPreferredLanguages:))

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

[`metadataItems(from:filteredBy:)`](/documentation/AVFoundation/AVMetadataItem/metadataItems(from:filteredBy:))

Returns filtered metadata items.

### Translating metadata items

[`identifier(forKey:keySpace:)`](/documentation/AVFoundation/AVMetadataItem/identifier(forKey:keySpace:))

Returns a metadata identifier for the specified key and key space.

[`key(forIdentifier:)`](/documentation/AVFoundation/AVMetadataItem/key(forIdentifier:))

Returns a metadata key for the specified identifier.

[`keySpace(forIdentifier:)`](/documentation/AVFoundation/AVMetadataItem/keySpace(forIdentifier:))

Returns a metadata key space for the specified identifier.

### Accessing values

Prefer loading values asynchronously using the symbols in Loading Values.

[`value`](/documentation/AVFoundation/AVMetadataItem/value)

The value of the metadata item.

[`extraAttributes`](/documentation/AVFoundation/AVMetadataItem/extraAttributes)

A dictionary of additional attributes for a metadata item.

[`stringValue`](/documentation/AVFoundation/AVMetadataItem/stringValue)

The value of the metadata item as a string.

[`numberValue`](/documentation/AVFoundation/AVMetadataItem/numberValue)

The value of the metadata item as a number.

[`dateValue`](/documentation/AVFoundation/AVMetadataItem/dateValue)

The value of the metadata item as a date.

[`dataValue`](/documentation/AVFoundation/AVMetadataItem/dataValue)

The value of the metadata item as a data value.

[`loadValuesAsynchronouslyForKeys:completionHandler:`](/documentation/AVFoundation/AVMetadataItem/loadValuesAsynchronouslyForKeys:completionHandler:)

Tells the object to load the values of any of the specified keys that aren’t already loaded.

[`statusOfValueForKey:error:`](/documentation/AVFoundation/AVMetadataItem/statusOfValueForKey:error:)

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


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)