Skip to content

Commit fb241f6

Browse files
pepelsbeychrisdavidmills
pepelsbey
and
chrisdavidmills
authored
Document DataCue interface, constructor, and properties (mdn#43087)
* Document DataCue interface, constructor, and properties * Apply suggestions from code review Co-authored-by: Chris Mills <chrisdavidmills@gmail.com> * Apply suggestions from code review --------- Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
1 parent f509688 commit fb241f6

File tree

6 files changed

+363
-1
lines changed

6 files changed

+363
-1
lines changed

‎files/en-us/web/api/datacue/datacue/index.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: "DataCue: DataCue() constructor"
3+
short-title: DataCue()
4+
slug: Web/API/DataCue/DataCue
5+
page-type: web-api-constructor
6+
status:
7+
- experimental
8+
browser-compat: api.DataCue.DataCue
9+
---
10+
11+
{{APIRef("WebVTT")}}{{SeeCompatTable}}
12+
13+
The **`DataCue()`** constructor creates and returns a new {{domxref("DataCue")}} object that represents a timed metadata cue over a given time range. The resulting cue can be added to a metadata {{domxref("TextTrack")}} using {{domxref("TextTrack.addCue()")}}, allowing arbitrary data to be synchronized with audio or video playback.
14+
15+
## Syntax
16+
17+
```js-nolint
18+
new DataCue(startTime, endTime, value)
19+
new DataCue(startTime, endTime, value, type)
20+
```
21+
22+
### Parameters
23+
24+
- `startTime`
25+
- : A number representing the start time, in seconds, for the cue's time range. This corresponds to the point on the media timeline at which the cue becomes active and its {{domxref("TextTrackCue/enter_event", "enter")}} event fires.
26+
- `endTime`
27+
- : A number representing the end time, in seconds, for the cue's time range. When the media playback reaches this time, the cue's {{domxref("TextTrackCue/exit_event", "exit")}} event fires. Use `Infinity` for a cue that remains active until the end of the media.
28+
- `value`
29+
- : The data payload associated with the cue. This can be any type, such as a string, a JavaScript object, or an {{jsxref("ArrayBuffer")}}. The value is stored in the cue's {{domxref("DataCue.value", "value")}} property.
30+
- `type` {{optional_inline}}
31+
- : A string identifying the type or schema of the data in `value`. This is typically a reverse-domain notation string (e.g., `"org.id3"`, `"org.mp4ra"`). The value is stored in the cue's {{domxref("DataCue.type", "type")}} property and defaults to an empty string if not provided.
32+
33+
### Return value
34+
35+
A new {{domxref("DataCue")}} object.
36+
37+
## Examples
38+
39+
### Creating a DataCue with geolocation data
40+
41+
This example creates a `DataCue` that carries geolocation coordinates, using a reverse-domain string as the `type` to identify the data format.
42+
43+
```html
44+
<video controls src="video.mp4"></video>
45+
```
46+
47+
```js
48+
const video = document.querySelector("video");
49+
const track = video.addTextTrack("metadata", "Geo Track");
50+
track.mode = "hidden";
51+
52+
// Create a cue from 5 seconds to the end of the media
53+
const data = { latitude: 51.5043, longitude: -0.0762 };
54+
const cue = new DataCue(5.0, Infinity, data, "org.example.geo");
55+
56+
cue.addEventListener("enter", (e) => {
57+
const { latitude, longitude } = e.target.value;
58+
console.log(`Pan map to: ${latitude}, ${longitude}`);
59+
});
60+
61+
track.addCue(cue);
62+
```
63+
64+
## Specifications
65+
66+
{{Specifications}}
67+
68+
## Browser compatibility
69+
70+
{{Compat}}
71+
72+
## See also
73+
74+
- {{domxref("DataCue")}}
75+
- {{domxref("TextTrack")}}
76+
- {{domxref("TextTrack.addCue()")}}
77+
- {{domxref("TextTrackCue/enter_event", "enter")}} event
78+
- {{domxref("TextTrackCue/exit_event", "exit")}} event

‎files/en-us/web/api/datacue/index.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: DataCue
3+
slug: Web/API/DataCue
4+
page-type: web-api-interface
5+
status:
6+
- experimental
7+
browser-compat: api.DataCue
8+
---
9+
10+
{{APIRef("WebVTT")}}{{SeeCompatTable}}
11+
12+
The **`DataCue`** interface represents a cue that associates arbitrary timed data with an audio or video media resource, or exposes timed data from a media resource to web pages. It extends the {{domxref("TextTrackCue")}} interface with a {{domxref("DataCue.value", "value")}} property that can hold any data type, and a {{domxref("DataCue.type", "type")}} property that identifies the kind of data.
13+
14+
Unlike {{domxref("VTTCue")}}, which is designed for displaying subtitle and caption text, `DataCue` is intended for non-rendered timed metadata. Use cases include dynamic content replacement, ad insertion, presentation of supplemental content alongside audio or video, or more generally, triggering application logic at specific points on the media timeline.
15+
16+
Some user agents may also automatically generate `DataCue` objects for in-band timed metadata carried within media streams, such as ID3 tags in [HTTP Live Streaming (HLS)](/en-US/docs/Web/Media/Guides/Audio_and_video_delivery/Setting_up_adaptive_streaming_media_sources#hls_encoding).
17+
18+
{{InheritanceDiagram}}
19+
20+
## Constructor
21+
22+
- {{domxref("DataCue.DataCue", "DataCue()")}} {{experimental_inline}}
23+
- : Creates a new `DataCue` object.
24+
25+
## Instance properties
26+
27+
_This interface also inherits properties from {{domxref("TextTrackCue")}}._
28+
29+
- {{domxref("DataCue.type")}} {{ReadOnlyInline}} {{experimental_inline}}
30+
- : A string identifying the type of the cue's {{domxref("DataCue.value", "value")}}, typically using reverse-domain notation (e.g., `"org.mp4ra"`, `"org.id3"`).
31+
- {{domxref("DataCue.value")}} {{experimental_inline}}
32+
- : The data payload associated with the cue. Can be any type.
33+
34+
## Instance methods
35+
36+
_This interface has no methods of its own but inherits methods from {{domxref("TextTrackCue")}}._
37+
38+
## Examples
39+
40+
### Associating timed metadata with a video
41+
42+
The following example creates a metadata {{domxref("TextTrack")}} on a video element and adds `DataCue` objects containing geolocation coordinates. When each cue becomes active during playback, its {{domxref("TextTrackCue/enter_event", "enter")}} event fires, allowing the page to react — for example, by updating a map view.
43+
44+
```html
45+
<video controls src="video.mp4"></video>
46+
```
47+
48+
```js
49+
const video = document.querySelector("video");
50+
const track = video.addTextTrack("metadata", "Geo Track");
51+
track.mode = "hidden";
52+
53+
const points = [
54+
{ start: 0, end: 10, data: { latitude: 51.5043, longitude: -0.0762 } },
55+
{ start: 10, end: 20, data: { latitude: 48.8566, longitude: 2.3522 } },
56+
{ start: 20, end: 30, data: { latitude: 40.4168, longitude: -3.7038 } },
57+
];
58+
59+
for (const point of points) {
60+
const cue = new DataCue(
61+
point.start,
62+
point.end,
63+
point.data,
64+
"org.example.geo",
65+
);
66+
cue.addEventListener("enter", (e) => {
67+
const { latitude, longitude } = e.target.value;
68+
console.log(`Map pan to: ${latitude}, ${longitude}`);
69+
});
70+
track.addCue(cue);
71+
}
72+
73+
// At 0s: "Map pan to: 51.5043, -0.0762"
74+
// At 10s: "Map pan to: 48.8566, 2.3522"
75+
// At 20s: "Map pan to: 40.4168, -3.7038"
76+
```
77+
78+
## Specifications
79+
80+
{{Specifications}}
81+
82+
## Browser compatibility
83+
84+
{{Compat}}
85+
86+
## See also
87+
88+
- {{domxref("TextTrackCue")}}
89+
- {{domxref("VTTCue")}}
90+
- {{domxref("TextTrack")}}
91+
- {{domxref("TextTrackCue/enter_event", "enter")}} event
92+
- {{domxref("TextTrackCue/exit_event", "exit")}} event

‎files/en-us/web/api/datacue/type/index.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: "DataCue: type property"
3+
short-title: type
4+
slug: Web/API/DataCue/type
5+
page-type: web-api-instance-property
6+
status:
7+
- experimental
8+
browser-compat: api.DataCue.type
9+
---
10+
11+
{{APIRef("WebVTT")}}{{SeeCompatTable}}
12+
13+
The **`type`** read-only property of the {{domxref("DataCue")}} interface returns a string identifying the type or schema of the data stored in the cue's {{domxref("DataCue.value", "value")}} property. This is typically a reverse-domain notation string (e.g., `"org.id3"`, `"com.apple.itunes"`) that allows applications to interpret the cue's data payload correctly.
14+
15+
When a user agent automatically generates `DataCue` objects for in-band timed metadata (for example, from an HTTP Live Streaming source), it sets this property to indicate the metadata format. When application code creates a `DataCue` using the {{domxref("DataCue.DataCue", "DataCue()")}} constructor, the `type` is set from the optional fourth argument and defaults to an empty string if omitted.
16+
17+
## Value
18+
19+
A string. Common values set by user agents for in-band metadata include:
20+
21+
- `"org.id3"` — ID3 metadata.
22+
- `"org.mp4ra"` — MPEG-4 metadata.
23+
- `"com.apple.quicktime.udta"` — QuickTime User Data.
24+
- `"com.apple.quicktime.mdta"` — QuickTime Metadata.
25+
- `"com.apple.itunes"` — iTunes metadata.
26+
27+
Application-defined cues may use any string, but reverse-domain notation is recommended to avoid collisions.
28+
29+
## Examples
30+
31+
### Reading the type of a DataCue
32+
33+
```html
34+
<video controls src="video.mp4"></video>
35+
```
36+
37+
```js
38+
const video = document.querySelector("video");
39+
const track = video.addTextTrack("metadata", "Events");
40+
track.mode = "hidden";
41+
42+
const cue = new DataCue(
43+
0,
44+
10,
45+
{ latitude: 51.5043, longitude: -0.0762 },
46+
"org.example.geo",
47+
);
48+
track.addCue(cue);
49+
50+
console.log(cue.type);
51+
// "org.example.geo"
52+
```
53+
54+
### Dispatching on type for in-band metadata
55+
56+
When a user agent generates `DataCue` objects from in-band timed metadata, the `type` property can be used to determine how to handle each cue.
57+
58+
```js
59+
track.addEventListener("cuechange", () => {
60+
for (const cue of track.activeCues) {
61+
switch (cue.type) {
62+
case "org.id3":
63+
handleID3Metadata(cue.value);
64+
break;
65+
case "org.mp4ra":
66+
handleMP4Metadata(cue.value);
67+
break;
68+
default:
69+
console.log(`Unknown cue type: ${cue.type}`);
70+
}
71+
}
72+
});
73+
```
74+
75+
## Specifications
76+
77+
{{Specifications}}
78+
79+
## Browser compatibility
80+
81+
{{Compat}}
82+
83+
## See also
84+
85+
- {{domxref("DataCue")}}
86+
- {{domxref("DataCue.value")}}
87+
- {{domxref("DataCue.DataCue", "DataCue()")}} constructor
88+
- {{domxref("TextTrackCue")}}

‎files/en-us/web/api/datacue/value/index.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: "DataCue: value property"
3+
short-title: value
4+
slug: Web/API/DataCue/value
5+
page-type: web-api-instance-property
6+
status:
7+
- experimental
8+
browser-compat: api.DataCue.value
9+
---
10+
11+
{{APIRef("WebVTT")}}{{SeeCompatTable}}
12+
13+
The **`value`** property of the {{domxref("DataCue")}} interface represents the data payload of the cue. Unlike {{domxref("VTTCue")}}, which carries text content, `DataCue` can hold any data type — such as a JavaScript object, a string, or an {{jsxref("ArrayBuffer")}} — making it suitable for timed metadata use cases where structured data needs to be synchronized with media playback.
14+
15+
The property is read-write for application-created cues, allowing the data to be updated after construction. For cues generated automatically by the user agent from in-band timed metadata (e.g., ID3 tags in an HTTP Live Streaming source), the value is set by the user agent and reflects the metadata payload.
16+
17+
The {{domxref("DataCue.type", "type")}} property can be used alongside `value` to identify the format or schema of the data.
18+
19+
## Value
20+
21+
Any type. The value is typically a string, a plain object, or an {{jsxref("ArrayBuffer")}}, depending on the source of the cue and the kind of timed metadata it represents.
22+
23+
## Examples
24+
25+
### Reading the value of a DataCue
26+
27+
```html
28+
<video controls src="video.mp4"></video>
29+
```
30+
31+
```js
32+
const video = document.querySelector("video");
33+
const track = video.addTextTrack("metadata", "Geo Track");
34+
track.mode = "hidden";
35+
36+
const cue = new DataCue(
37+
0,
38+
10,
39+
{ latitude: 51.5043, longitude: -0.0762 },
40+
"org.example.geo",
41+
);
42+
track.addCue(cue);
43+
44+
console.log(cue.value);
45+
// { latitude: 51.5043, longitude: -0.0762 }
46+
```
47+
48+
### Reacting to cue data during playback
49+
50+
This example adds several `DataCue` objects to a metadata track, then reads each cue's `value` as it becomes active during playback.
51+
52+
```html
53+
<video controls src="video.mp4"></video>
54+
```
55+
56+
```js
57+
const video = document.querySelector("video");
58+
const track = video.addTextTrack("metadata", "Events");
59+
track.mode = "hidden";
60+
61+
const cue1 = new DataCue(5, 10, { action: "showBanner", text: "Welcome!" });
62+
const cue2 = new DataCue(15, 20, { action: "highlight", playerId: 7 });
63+
64+
cue1.addEventListener("enter", (e) => {
65+
console.log(e.target.value.action);
66+
// "showBanner"
67+
});
68+
69+
cue2.addEventListener("enter", (e) => {
70+
console.log(e.target.value.action);
71+
// "highlight"
72+
});
73+
74+
track.addCue(cue1);
75+
track.addCue(cue2);
76+
```
77+
78+
### Updating the value of a DataCue
79+
80+
The `value` property is writable, so it can be changed after the cue is created.
81+
82+
```js
83+
const cue = new DataCue(0, 5, "initial data");
84+
cue.value = { updated: true, score: 42 };
85+
console.log(cue.value);
86+
// { updated: true, score: 42 }
87+
```
88+
89+
## Specifications
90+
91+
{{Specifications}}
92+
93+
## Browser compatibility
94+
95+
{{Compat}}
96+
97+
## See also
98+
99+
- {{domxref("DataCue")}}
100+
- {{domxref("DataCue.type")}}
101+
- {{domxref("DataCue.DataCue", "DataCue()")}} constructor
102+
- {{domxref("TextTrackCue")}}

‎files/en-us/web/api/texttrackcue/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ browser-compat: api.TextTrackCue
77

88
{{APIRef("WebVTT")}}
99

10-
The **`TextTrackCue`** interface of the [WebVTT API](/en-US/docs/Web/API/WebVTT_API) is the abstract base class for the various derived cue types, such as {{domxref("VTTCue")}}; you will work with these derived types rather than the base class.
10+
The **`TextTrackCue`** interface of the [WebVTT API](/en-US/docs/Web/API/WebVTT_API) is the abstract base class for the various derived cue types, such as {{domxref("VTTCue")}} and {{domxref("DataCue")}}; you will work with these derived types rather than the base class.
1111

1212
These cues represent strings of text presented for some duration of time during the performance of a {{domxref("TextTrack")}}. The cue includes the start time (the time at which the text will be displayed) and the end time (the time at which it will be removed from the display), as well as other information.
1313

‎files/en-us/web/api/webvtt_api/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ Most important WebVTT features can be accessed using either the file format or W
5353

5454
### Related interfaces
5555

56+
- {{domxref("DataCue")}}
57+
- : Represents a cue for associating arbitrary timed data (rather than text) with a media resource, such as in-band event messages.
5658
- {{domxref("TrackEvent")}}
5759
- : Part of the HTML DOM API, this is the interface for the `addtrack` and `removetrack` events that are fired when a track is added or removed from {{domxref("TextTrackList")}} (or more generally, when a track is added/removed from an HTML media element).
5860

0 commit comments

Comments
 (0)