Skip to main content
Version: 11.8.0

HLS date ranges on Web

The #EXT-X-DATERANGE tag associates a date range (i.e. a range of time defined by a starting and ending date) with a set of attribute/value pairs. It is a way of providing timed metadata in an HLS manifest. A possible use case is defining timed metadata for interstitial regions such as advertisements, but it can be used for any timed metadata needed by your stream.

Date ranges are not parsed by default. To enable them, set hlsDateRange to true, either on the player configuration (for all sources) or on an individual source.

Once enabled, the player exposes the date ranges as cues on a metadata text track, which you can consume through the text tracks API.

Enabling date ranges​

// in the player configuration
const element = document.querySelector('.theoplayer-container');

const player = new THEOplayer.Player(element, {
  libraryLocation: libraryLocation,
  license: 'your-license-here',
  hlsDateRange: true,
});

// or in the source description
player.source = {
  sources: {
    src: 'https://example.com/example-stream.m3u8',
    type: 'application/x-mpegurl',
    hlsDateRange: true,
  },
};

Reading date range cues​

Date ranges are exposed as cues on a metadata text track. Listen for the metadata track being added, and for its cues, to interact with the date range attributes.

player.textTracks.addEventListener('addtrack', (event) => {
  const track = event.track;
  if (track.kind !== 'metadata') {
    return;
  }
  // By default, metadata tracks are disabled and do not expose cues
  track.mode = 'hidden';
  track.addEventListener('entercue', (enterCueEvent) => {
    console.log('Date range started', enterCueEvent.cue.content);
  });
  track.addEventListener('exitcue', (exitCueEvent) => {
    console.log('Date range ended', exitCueEvent.cue.content);
  });
});

See "How to detect active text track cues" for more information.

Resources​