Skip to main content
Version: 7.3.0

Using hlsDateRange property

This article explains how to enable the DateRange feature, so that a text track and cues are created.

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


Web SDKAndroid SDKiOS SDKtvOS SDKAndroid TV SDKChromecast SDK


#EXT-X-DATERANGE is a way of providing timed metadata in an HLS manifest. It is used to define date range metadata in a media playlist. A possible use case is defining timed metadata for interstitial regions such as advertisements, but can be used to define any timed metadata needed by your stream.

#EXT-X-DATERANGE is supported in THEOplayer as of 2.61.0. However, the feature is not enabled by default. To enable it, add hlsDateRange to the player configuration and set it to true. You can also choose (instead) to enable/disable the feature per source by adding the same option to a source in your source description.

//in playerConfiguration
var element = document.querySelector(".theoplayer-container");

var player = new THEOplayer.Player(element, {
libraryLocation: libraryLocation,
license: "your-license-here",
hlsDateRange: true

//in the source description
player.source = {
hlsDateRange: true,
sources: {
src: "Example-Stream.m3u8",
type: "application/x-mpegurl"
Legacy iOS/tvOS SDK (4.12.x)
//in playerConfiguration
func setupTheoPlayer() {
var frame: CGRect = UIScreen.main.bounds
frame.size.height = 350
let stylePath1 = Bundle.main.path(forResource:"style1", ofType: "css")!
let scriptPath = Bundle.main.path(forResource:"script1", ofType: "js")!
//Add here at the end of playerConfig
let playerConfig = THEOplayerConfiguration(defaultCSS: true, cssPaths:[stylePath1, stylePath2], jsPaths: [scriptPath], googleIMA: true, hlsDateRange: true)
self.theoplayer = THEOplayer(configuration: playerConfig)
self.theoplayer.frame = frame
self.theoplayer.addAsSubview(of: playerView)

//in the source description
source: TypedSource(
src: src,
type: stream,
hlsDateRange: true
Android SDk
//in playerConfiguration
THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
.ui(new UIConfiguration.Builder().language("nl").build())
THEOplayerView tpv = new THEOplayerView(this, playerConfig);

The TextTrack API is used to retrieve the timed metadata. A MetadataTextTrack will provide cues which contain the timed metadata and will dispatch an event when started and ended.

Using and interacting with date-range variables

function handleTimedMetadata(player, onTimeMetadataEnter, onTimeMetadataExit) {
console.log("function handleTimedMetadata is starting! yeeee");
const onTrackAdded = (event) => {
const track = event.track;
console.log("track", track.kind, track.cues);
if (track.kind !== "metadata") {
track.mode = "hidden"; // By default, tracks are disabled and do not expose cues
track.addEventListener("addcue", onCueAdded);
track.addEventListener("removecue", onCueRemoved);
const onTrackRemoved = (event) => {
const track = event.track;
if (track.kind !== "metadata") {
track.removeEventListener("addcue", onCueAdded);
track.removeEventListener("removecue", onCueRemoved);
const onCueAdded = (event) => {
const cue = event.cue;
console.log("cueadded", cue);
cue.addEventListener("enter", onTimeMetadataEnter);
cue.addEventListener("exit", onTimeMetadataExit);
const onCueRemoved = (event) => {
const cue = event.cue;
cue.removeEventListener("enter", onTimeMetadataEnter);
cue.removeEventListener("exit", onTimeMetadataExit);
player.textTracks.addEventListener("addtrack", onTrackAdded);
player.textTracks.addEventListener("removetrack", onTrackRemoved);
(event) => console.log("Do something with timed metadata starting", event),
(event) => console.log("Do something with metadata ending", event)
iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x) and Android

To be added


HLS spec. :