Metadata Events Reference (iOS)

Learn how to gather information from metadata events

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:

  1. Call super() to inform the JWPlayerViewController of the event.
  2. 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:

  1. Create your own class which conforms to a specific metadata delegate.
  2. 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>
     }
}

JWMetadataDelegatesDescription
dateRangeMetadataDelegateSurfaces date range metadata
externalMetadataDelegateSurfaces metadata defined by the developer
id3MetadataDelegateSurfaces ID3 metadata
mediaMetadataDelegateSurfaces metadata about the media content when it first loads
programDateTimeMetadataDelegateSurfaces 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.

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

​

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

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

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

JWProgramDateTimeMetadataDelegateNotes
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