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

TextTrack

Properties

The TextTrack object has the following properties:

Property Type Description
activeCues Cue[] An array of Cue objects that contains the currently active text track cues.
cues Cue[] 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.
label string A user-readable title label of the text track.
language string The language of the text track.
mode 'disabled' OR 'hidden' OR 'showing' Returns the mode of the text track.

Methods

The TextTrack object has the following methods:

Method Type Description
activeCues Cue[] An array of Cue objects that contains the currently active text track cues.
cues Cue[] 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.
label string A user-readable title label of the text track.
language string The language of the text track.
mode 'disabled' OR 'hidden' OR 'showing' Returns the mode of the text track.

This object also dispatches the cuechange-event when the cues in the text track change.

Events

The TextTrack object dispatches the following events:

Event Description
cuechange The cuechange event fires when the TextTrack has changed the currently displaying cues.
timedMetadata The timedMetadata event fires when the TextTrack has changed the currently displaying cues.

Cue

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

Property Type Description
endTime number The end time for when the cue should be active.
id number The id of the cue
startTime number The end time for when the cue should be active.
tag Tag An ID3 tag object that contains the formatted data inside the cue.

Tag

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

Property Type Description
frames ID3Frame[] The id of the cue

ID3Frame

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

Property Type Description
id string The id of the ID3Frame.
flags number Header 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" : []
}

Example

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
    });
});

Support Table

This feature is supported on all browsers supported by THEOplayer.

Internet Explorer 10+

Internet Explorer 10+

Firefox

Firefox

Chrome

Chrome

Safari

Safari

Opera

Opera

Edge

Edge

Windows Phone

Windows Phone

Android

Android

iOS

iOS

Vivaldi

Vivaldi