Article

Presenting Navigation Markers (tvOS)

Present navigation markers in the Info panel to help users quickly navigate your content.

Overview

In addition to displaying metadata, the Info panel can also present navigation markers to help users quickly navigate your content. These markers represent points of interest within the media’s timeline to which you can skip by selecting the desired marker with the Siri Remote.

Apple TV Info panel showing chapter markers along the bottom of the panel.

Set the Navigation Markers

AVPlayerItem in tvOS adds a navigationMarkerGroups property. You can set this property with an array of AVNavigationMarkersGroup objects to define the navigation markers for the current media.

An AVNavigationMarkersGroup is composed of one or more AVTimedMetadataGroup objects, each representing an individual marker presented in the player’s Info panel. Each AVTimedMetadataGroup is composed of a time range in the asset’s timeline to which this marker applies, an array of AVMetadataItem objects to define the marker’s title, and optionally, its thumbnail artwork.

Top-down component diagram showing a player item containing navigation markers groups at the top. The middle component shows a navigation markers group containing timed metadata groups. The bottom component shows a timed metadata group containing multiple metadata items.

The following code example shows how you can present a chapter list for your media:

func setupPlayback() {
    ...
    playerItem.navigationMarkerGroups = makeNavigationMarkerGroups()
    ...
}

private func makeNavigationMarkerGroups() -> [AVNavigationMarkersGroup] {

    let chapters = [
        ["title": "Chapter 1", "imageName": "chapter1", "start": 0.0, "end": 60.0],
        ["title": "Chapter 2", "imageName": "chapter2", "start": 60.0, "end": 120.0],
        ["title": "Chapter 3", "imageName": "chapter3", "start": 120.0, "end": 180.0],
        ["title": "Chapter 4", "imageName": "chapter4", "start": 180.0, "end": 240.0]
    ]

    var metadataGroups = [AVTimedMetadataGroup]()

    // Iterate over the defined chapters, building an AVTimedMetadataGroup for each
    for chapter in chapters {
        metadataGroups.append(makeTimedMetadataGroup(for: chapter))
    }

    return [AVNavigationMarkersGroup(title: nil, timedNavigationMarkers: metadataGroups)]
}

private func makeTimedMetadataGroup(for chapter: [String: Any]) -> AVTimedMetadataGroup {
    var metadata = [AVMetadataItem]()

    // Create chapter title item
    let title = chapter["title"] as! String
    let titleItem = makeMetadataItem(AVMetadataCommonIdentifierTitle, value: title)
    metadata.append(titleItem)
    let imageName = chapter["imageName"] as! String

    if let image = UIImage(named: imageName), let pngData = UIImagePNGRepresentation(image) {
        // Create chapter thumbnail item
        let imageItem = makeMetadataItem(AVMetadataCommonIdentifierArtwork, value: pngData)
        metadata.append(imageItem)
    }

    // Create CMTimeRange
    let timescale: Int32 = 600
    let cmStartTime = CMTimeMakeWithSeconds(chapter["start"] as! TimeInterval, timescale)
    let cmEndTime = CMTimeMakeWithSeconds(chapter["end"] as! TimeInterval, timescale)
    let timeRange = CMTimeRangeFromTimeToTime(cmStartTime, cmEndTime)

    return AVTimedMetadataGroup(items: metadata, timeRange: timeRange)
}

private func makeMetadataItem(_ identifier: String, value: Any) -> AVMetadataItem {
    let item = AVMutableMetadataItem()

    item.identifier = identifier
    item.value = value as? NSCopying & NSObjectProtocol
    item.extendedLanguageTag = "und"
    return item.copy() as! AVMetadataItem
}

See Also

Info Panel Information

Presenting Metadata in the Info Panel (tvOS)

Add metadata information to the Info panel in Apple TV.