Version: 2.67.0

How to track ID3 cues/tags (metadata)?

Thequestion above is commonly asked because the developer wants to introduce a certain behavior depending on the metadata contained by the ID3 cues. For example, the developer

  • wants to schedule advertisements dynamically by using information passed on by the ID3 metadata.
  • wants to overlay certain text on top of the player (e.g. the score of a football match).
  • ...

The snippet below explains how you correctly track the exit event, which is part of the TextTrack API. The exit event maps to the moment in time when the ID3 cue is relevant.

Web SDK

function exitListener(e2) {
// log exit event
console.log(e2);
}
function handleTrackCreation(e0) {
e0.track.cues.forEach(function(cue) {
cue.addEventListener("exit", exitListener);
});
// detect cues being added to the track
e0.track.addEventListener("addcue", function(e1) {
// detect a cue being shown from a track
e1.cue.addEventListener("exit", exitListener);
});
}
player.textTracks.addEventListener("addtrack", handleTrackCreation);

Android SDK

final EventListener<ExitCueEvent> exitListener = new EventListener<ExitCueEvent>() {
@Override
public void handleEvent(ExitCueEvent exitCueEvent) {
System.out.println("exitCueEvent: " + exitCueEvent.getCue().getContent());
}
};
EventListener<AddTrackEvent> handleTrackCreation = new EventListener<AddTrackEvent>() {
@Override
public void handleEvent(AddTrackEvent addTrackEvent) {
addTrackEvent.getTrack().addEventListener(TextTrackEventTypes.EXITCUE, exitListener);
}
};
tpv.getPlayer().getTextTracks().addEventListener(TextTrackListEventTypes.ADDTRACK, handleTrackCreation);

ID3 is a type of metadata which can be inserted in HTTP livestreams. Once an ID3 cue is inserted, it'll be added to a THEOplayer [TextTrack](/docs/api-reference/theoplayer-texttrack). The demo at https://demo.theoplayer.com/audio-id3-metadata demonstrates a usage of ID3 metadata. Just before the song changes, an exit event will be dispatched, the song information (title, album, etc.) is contained within this exit event, and can be used to update the UI.