Version: 2.67.0

ID3 Timed Metadata

Introduction to ID3

The HTTP Live Streaming protocol contains a feature which allows for including timed metadata within the media stream. This feature makes it possible to incorporate ID3 metadata in your video streams and synchronize this metadata with the content. Having these two data streams allows you to display this information, invoke time-aligned actions and so on.

ID3 is a container for metadata and allows information such as the title, artist, album, track number, and other information about the content to be stored in the file itself. The ID3 specification details a number of frames for each kind of metadata which can be added. There are standard frames for containing cover art, BPM, copyright and license, lyrics, and arbitrary text and URL data, as well as other things.

Timed Metadata in THEOplayer

When ID3 metadata is embedded in a media stream, THEOplayer will automatically detect this metadata and expose it through the JavaScript API. The way the metadata is exposed in the stream is the same way as the W3 draft specification detailing how this information should be made available. When you are familiar with how text-tracks are handled in HTML5, using timed metadata with THEOplayer will be a piece of cake.

ID3 in the API

THEOplayer instances contain the textTracks-property. This property will return an array of TextTracks



The TextTrack object has the following properties:

activeCuesCue[]An array of Cue objects that contains the currently active text track cues.
cuesCue[]An array of Cue objects that contains all the cues for this text track.
kind'subtitles' OR 'captions' OR 'descriptions' OR 'chapters' OR 'metadata'How the text track is meant to be used. If omitted the default kind is subtitles. If the attribute is not present, it will use the subtitles. If the attribute contains an invalid value, it will use metadata.
labelstringA user-readable title label of the text track.
languagestringThe language of the text track.
mode'disabled' OR 'hidden' OR 'showing'Returns the mode of the text track.


The TextTrack object has the following methods:

| Method | Arguments | Description | | addEventListener | type : string, listener : EventListener | Adds the given listener to the TextTrack for the given event type. | | removeEventListener | type : string, listener : EventListener | Removes the given listener from the TextTrack for the given event type. |


The TextTrack object dispatches the following events:

cuechangeThe cuechange event fires when the TextTrack has changed the currently displaying cues.
timedMetadataThe timedMetadata event fires when the TextTrack has changed the currently displaying cues.


Cues contain the ID3 tags linked to the content and have the following properties:

endTimenumberThe end time for when the cue should be active.
idnumberThe id of the cue
startTimenumberThe end time for when the cue should be active.
tagTagAn ID3 tag object that contains the formatted data inside the cue.


Tags contain the formatted data linked to the content and has the following property:

framesID3Frame[]The id of the cue


ID3Frames contain the ID3 metadata to the media content and always have the following properties:

idstringThe id of the ID3Frame.
flagsnumberHeader flags for the ID3 frame.

Depending on the of the ID3 metadata, other fields that are contained in the object may vary.\ An example of a metadata text track would be:

"kind": "metadata",
"label": "",
"language": "",
"mode": "disabled",
"cues": [
"id": "",
"startTime": 0,
"endTime": 10,
"tag": {
"frames": [
"id": "TXXX",
"description": "",
"text": "An example of user defined text information embedded metadata which is placed 10 seconds into the stream."
"activeCues": []


Listening for timed metadata events

Below you can find an example of how timed metadata events can be captured when using THEOplayer.

var player = theoplayer.player(0);
player.textTracks.addEventListener("addtrack", function(addTrackEvent) {
var track = addTrackEvent.track;
// assert track.kind === "metadata"
track.addEventListener("cuechange", function(cueChangeEvent) {
// here you can access the cue and other properties of the track and display the metadata to the outside