Metadata Events Reference (iOS)

By listening to metadata events, you can gather more information about the playing content or response to custom cues. Each metadata class contains unique media information.

You can listen for metadata events either through the JWPlayerViewController or the JWPlayerView.

JWPlayerViewController

When using the JWPlayerViewController to display your content, this class subscribes to all metadata events and is assigned as each delegate.

Use the following steps to listen for events:

Call super() to inform the JWPlayerViewController of the event.
Override the delegate methods and read the needed data.

JWPlayerView

🚧
The JWPlayerViewController does not support this approach.
Attempting to follow these steps using the JWPlayerViewController will produce the following results:

The assignment will be unsuccessful.

A warning will be printed to the console announcing that JWPlayerViewController cannot be overridden as a delegate for these events.

If you are not using JWPlayerViewController, use the following steps:

Create your own class which conforms to a specific metadata delegate.
Assign it as the delegate through the JWPlayer object.

class ID3MetadataDelegate: JWID3MetadataDelegate {
     func jwplayer(_ player: JWPlayer, id3Metadata metadata: JWID3Metadata)
}

class PlayerViewController: UIViewController {
     @IBOutlet var playerView: JWPlayerView! // Your player view
     let <var delegateName> = <JWDelegateName>()

     override func viewDidLoad() {
          playerView.metadataDelegates.<JWMetadataDelegates> = <var delegateName>
     }
}

JWMetadataDelegates	Description
dateRangeMetadataDelegate	Surfaces date range metadata
externalMetadataDelegate	Surfaces metadata defined by the developer
id3MetadataDelegate	Surfaces ID3 metadata
mediaMetadataDelegate	Surfaces metadata about the media content when it first loads
programDateTimeMetadataDelegate	Surfaces program-date-time metadata

Delegate Methods Reference

When listening for metadata events, use one of the following delegate methods.

Date Range

Metadata from the EXT-X-DATERANGE tag such as ad markers, content metadata, synchronized events, and program boundaries

Use the following delegate method to listen for Date Range metadata events.

JWDateRangeMetadataDelegate	Notes
`func jwplayer(\_ player: JWPlayer, dateRangeMetadata metadata: JWDateRangeMetadata)`	Event triggered when the content has entered the date range defined by the metadata cue
`func jwplayer(\_ player: JWPlayer, dateRangeMetadataCueParsed metadata: JWDateRangeMetadata)`	Event triggered when the metadata has been parsed and buffered

JWDateRangeMetadata Class

The JWDateRangeMetadata class contains the following information.

Property	Description
attributes [JSONObject]	`EXT-X-DATERANGE` attribute list
duration TimeInterval	Duration of the date range
end TimeInterval	End time of the cue, expressed in seconds from the beginning of the content
endDate Date	`EXT-X-DATERANGE` end date
start Double	Start time of the cue, expressed in seconds from the beginning of the content
startDate Date	`EXT-X-DATERANGE` start date

External

Metadata cues that can be inserted into the video content and surfaced for specialized use within the application

For example, you can insert an external metadata event to represent a video segment that a user can skip. You may display a button to allow the user to bypass the segment if desired.

The following recipe shows how to add metadata cues to a media item.

📱

iOS: Add external metadata to a playlist

Open Recipe

Use the following delegate method to listening for external metadata events.

JWExternalMetadataDelegate	Notes
`func jwplayer(\_ player: JWPlayer, externalMetadata metadata: JWExternalMetadata)`	Event triggered when the content has entered the time range defined by the metadata cue
`func jwplayer(\_ player: JWPlayer, externalMetadataCueParsed metadata: JWExternalMetadata)`	Event triggered when the metadata has been parsed and buffered

JWExternalMetadata Class

The JWExternalMetadata class has the following information.

Property	Description
endTime TimeInterval	End time of the cue, expressed in seconds from the beginning of the content
identifier String	Unique identifier used to represent the metadata cue
startTime TimeInterval	Start time of the cue, expressed in seconds from the beginning of the content

ID3

Timed metadata contained in ID3 tags embedded within an HLS stream that carries information such as ad markers, content metadata, and synchronized events

Use the following delegate method to listen for ID3 tag metadata events.

JWID3MetadataDelegate
`func jwplayer(\_ player: JWPlayer, id3Metadata metadata: JWID3Metadata)`

JWID3Metadata Class

The JWID3Metadata class contains the following information.

Property	Description
start Double	Start time of the cue, expressed in seconds from the beginning of the content
metadata JSONObject	Data stored within the ID3 tag

Media

Additional information about video content known once the video has loaded

Once the media item has been loaded into the player, media metadata can be retrieved. The duration of the content and the base width and height of the content for optimal viewing are examples of media metadata.

The following delegate method is used for listening to media metadata events.

JWMediaMetadataDelegate	Notes
`func jwplayer(\_ player: JWPlayer, didReceiveMediaMetadata metadata: JWMediaMetadata)`	Event triggered when the video has loaded

JWMediaMetadata Class

The JWMediaMetadata class has the following information.

Property	Description
drmEncryption JWDRMEncryption	Type of DRM encryption being used by the content Possible Values: `.fairplay` `.none`
duration TimeInterval	Duration of the content expressed in seconds
frameRate Double	Number of frames displayed per second for video content
height Double	Height of the content
seekRange JWTimeRange	Time range representing how much content is available to buffer in live stream or for seeking in DVR
width Double	Width of the content

Program Date Time

Absolute data and time at which a particular media segment starts

The EXT-X-PROGRAM-DATE-TIME tag contains the program date time metadata. This tag provides synchronization information to the media player, especially when playing back live streams, as it helps align and synchronize different media segments to their correct playback positions.

The following delegate method is used for listening to Program Date Time metadata events.

JWProgramDateTimeMetadataDelegate	Notes
`func jwplayer(\_ player: JWPlayer, programDateTimeMetadata metadata: JWProgramDateTimeMetadata)`	Event triggered when the content has entered the time range defined by the metadata cue
`func jwplayer(\_ player: JWPlayer, programDateTimeMetadataCueParsed metadata: JWProgramDateTimeMetadata)`	Event triggered when the metadata has been parsed and buffered

JWProgramDateTimeMetadata Class

The JWProgramDateTimeMetadata class has the following information.

Property	Description
endTime TimeInterval	End time of the cue, expressed in seconds from the beginning of the content
programDateTime Date	Duration of the content expressed in seconds
startTime TimeInterval	Start time of the cue, expressed in seconds from the beginning of the content