Skip to main content
Version: 11.7.0

How to track ID3 cues and tags on Web

ID3 is a type of metadata which can be inserted in HTTP live streams. Once an ID3 cue is inserted, it is added to a THEOplayer text track.

Developers commonly track ID3 cues because they want to introduce a certain behavior depending on the metadata contained by the ID3 cues, for example:

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

The demo at https://demo.theoplayer.com/audio-id3-metadata demonstrates a usage of ID3 metadata. Just before the song changes, an enter event is dispatched. The song information (title, album, etc.) is contained within this enter event, and can be used to update the UI.

This article describes how you can listen for timed metadata events, and how you can track the enter event.

Listening for timed metadata events​

Listen for the cuechange event of a TextTrack.

player.textTracks.addEventListener('addtrack', function (addTrackEvent) {
  const track = addTrackEvent.track;
  if (track.kind !== 'metadata') {
    return;
  }

  track.addEventListener('cuechange', function (cueChangeEvent) {
    // here you can access the cues of the track, and display the metadata to the outside
  });
});

Tracking the enter event​

The enter event, which is part of the TextTrack API, maps to the moment in time when the ID3 cue becomes relevant.

Listen for the entercue event of the track, which is fired for every cue of that track that becomes active. The entered cue is available as event.cue.

player.textTracks.addEventListener('addtrack', function (addTrackEvent) {
  const track = addTrackEvent.track;
  if (track.kind !== 'metadata') {
    return;
  }

  track.addEventListener('entercue', function (enterCueEvent) {
    // log entercue event
    console.log(enterCueEvent);
  });
});

Alternatively, you can listen for the enter event on each individual cue. Note that you have to add a listener to every cue, including the cues that are added to the track later on.

function enterListener(event) {
  // log enter event
  console.log(event);
}
function handleTrackCreation(addTrackEvent) {
  const track = addTrackEvent.track;
  if (track.kind !== 'metadata') {
    return;
  }

  track.cues.forEach(function (cue) {
    cue.addEventListener('enter', enterListener);
  });

  // detect cues being added to the track
  track.addEventListener('addcue', function (addCueEvent) {
    // detect a cue being shown from a track
    addCueEvent.cue.addEventListener('enter', enterListener);
  });
}
player.textTracks.addEventListener('addtrack', handleTrackCreation);

Resources​