TextTrackCue constructor is not exposed in the web interface

[rjksmith]

What is the issue with the HTML Standard?

Intro

The TextTrackCue interface is an abstract base class for various derived cue types - such as VTTCue for timed text and DataCue for timed metadata - which is well-supported in modern web browsers.

TextTrackCue defines the timing information required for event generation by a cue scheduler such as TextTrack or the WebVMT engine, though omits the cue content interface which is the abstract component that must be defined by the derived cue type in accordance with the HTML guidelines.

Problem

Derived types require access to their parent's constructor to allow correct inheritance behaviour. TextTrackCue's constructor is not currently exposed in the web interface because browser builtin subclasses were not possible in 2014 when TextTrackCue was published. This prevents cue types from being derived directly from TextTrackCue without using VTTCue, which incurs significant and unnecessary overheads.

Cue content must be correctly identified to enable proper access and the derived cue type provides a mechanism for accurate identification. This design avoids sniffing and guesswork which would increase access overheads and reduce accuracy. Content may be genuinely unrecognisable because there are an infinite number of data types, so sniffing can produce false results where content is misinterpreted. Adding a type field to the cue content would introduce a circular dependency because the content type must be known to read the type field which identifies the content type.

Solution

Progress since 2014 now permits builtin subclasses such as EventTarget, so TextTrackCue's constructor could be exposed in the web interface to enable custom cues to be derived. Such exposure would require minimal changes to browser implementations, leave the existing HTML design otherwise unchanged and provide significant benefits to the web community, without obstructing parallel proposals. This solution was discussed with stakeholders at WICG DataCue meeting on 14 October 2025 and a consensus was reached to raise the following proposal.

Proposal

1. Expose TextTrackCue's constructor in the web interface as new TextTrackCue(startTime, endTime, id) where id defaults to '' if omitted.
2. Introduce constructor steps that prevent direct instantiation without extension, so that TextTrackCue remains as an abstract base class.

Related Issues & Benefits

1. Web developer access reduces reliance on browser developers to implement derived cue types such as DataCue, and encourages community engagement that can highlight future requirements.
2. Event handlers can be agnostic of how cues are created or scheduled - in-band or out-of-band, by browser or application, from TextTrack or a custom scheduler. For example, cues in the video metadata search use case can be accessed agnostically of video encoding and without requiring a scheduler.
3. Parallel proposals such as the WebKit enhancements are not obstructed by these changes. Constructor steps allow differentiation between input parameter types such as DocumentFragment to avoid conflict as discussed on 14 October 2025.
4. Web Platform Tests can be streamlined by removing VTTCue dependency from TextTrackCue and TextTrack tests for a cleaner design.

Additional Resources

• WICG DataCue: TextTrackCue constructor explainer
• WebVMT sync examples: DataCue and custom cue demos based on TextTrackCue polyfill
• Sync on the Web CG: DMX lighting demo based on DataCue polyfill

[foolip]

cc @whatwg/media

[foolip]

This proposal makes sense to me, to allow real subclasses of TextTrackCue and not requiring using VTTCue and adding extra properties to those objects.

These cues wouldn't render anything, so a possible followup would be allowing custom cue rendering to avoid overlapping the native controls just like WebVTT does. However, I'm not sure there will be actual developer demand for this.