<!--
{
  "documentType" : "article",
  "framework" : "AVFoundation",
  "identifier" : "/documentation/AVFoundation/presenting-chapter-markers",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Presenting chapter markers"
}
-->

# Presenting chapter markers

Add chapter markers to enable users to quickly navigate your content.

## Discussion

Chapter markers enable users to quickly navigate your content. <doc://com.apple.documentation/documentation/AVKit/AVPlayerViewController> automatically presents a chapter-selection interface if it finds chapter markers in the currently played asset. You can also directly retrieve this data whenever you want to create your own custom chapter-selection interface.

### Retrieve the timed metadata

Chapter markers are a type of timed metadata that apply only to ranges of time within the asset’s timeline. You retrieve an asset’s chapter metadata using either the [`chapterMetadataGroups(bestMatchingPreferredLanguages:)`](/documentation/AVFoundation/AVAsset/chapterMetadataGroups(bestMatchingPreferredLanguages:)) or [`chapterMetadataGroups(withTitleLocale:containingItemsWithCommonKeys:)`](/documentation/AVFoundation/AVAsset/chapterMetadataGroups(withTitleLocale:containingItemsWithCommonKeys:)) methods. These methods become callable without blocking after you asynchronously load the value of the asset’s [`availableChapterLocales`](/documentation/AVFoundation/AVAsset/availableChapterLocales) key.

```swift
let asset = AVAsset(url: <# Asset URL #>)
let chapterLocalesKey = "availableChapterLocales"
 
asset.loadValuesAsynchronously(forKeys: [chapterLocalesKey]) {
    var error: NSError?
    let status = asset.statusOfValue(forKey: chapterLocalesKey, error: &error)
    if status == .loaded {
        let languages = Locale.preferredLanguages
        let chapterMetadata = asset.chapterMetadataGroups(bestMatchingPreferredLanguages: languages)
        // Process chapter metadata.
    }
    else {
        // Handle other status cases.
    }
}
```

### Convert timed metadata into chapter data

The value returned from the methods described above is an array of [`AVTimedMetadataGroup`](/documentation/AVFoundation/AVTimedMetadataGroup) objects, each representing an individual chapter marker. An [`AVTimedMetadataGroup`](/documentation/AVFoundation/AVTimedMetadataGroup) object contains a <doc://com.apple.documentation/documentation/CoreMedia/CMTimeRange>, defining the time range to which its metadata applies, an array of [`AVMetadataItem`](/documentation/AVFoundation/AVMetadataItem) objects representing the chapter’s title, and optionally, its thumbnail image. The following example shows how to convert the [`AVTimedMetadataGroup`](/documentation/AVFoundation/AVTimedMetadataGroup) data into an array of custom model objects, called `Chapter`, to pass to the app’s view layer.

```swift
func convertTimedMetadataGroupsToChapters(groups: [AVTimedMetadataGroup]) -> [Chapter] {
    return groups.map { group in
        // Retrieve the title metadata items.
        let titleItems = AVMetadataItem.metadataItems(from: group.items,
                                                      filteredByIdentifier: .commonIdentifierTitle)

        // Retrieve the artwork metadata items.
        let artworkItems = AVMetadataItem.metadataItems(from: group.items,
                                                        filteredByIdentifier: .commonIdentifierArtwork)

        var title = "Default Title"
        var image = UIImage(named: "placeholder")!

        if let titleValue = titleItems.first?.stringValue {
            title = titleValue
        }

        if let imgData = artworkItems.first?.dataValue, let imageValue = UIImage(data: imgData) {
            image = imageValue
        }

        return Chapter(time: group.timeRange.start, title: title, image: image)
    }
}
```

With the relevant data converted, you can build a chapter-selection interface and use the time value of the chapter object to seek the current presentation using an [`AVPlayer`](/documentation/AVFoundation/AVPlayer) object’s [`seek(to:)`](/documentation/AVFoundation/AVPlayer/seek(to:)-87h2r) method.

---

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)