Signatur
Beschreibung
Die schreibgeschützte Eigenschaft inBandMetadataTrackDispatchType des Interfaces TextTrack gibt einen String zurück, der das Format eines In-Band-Metadatentracks beschreibt. In-Band-Tracks sind Spuren, die direkt im Mediencontainer stecken, etwa in einem MPEG-2-Transportstream, in WebM oder in einem HLS-Stream. Sie werden also nicht per <track>-Element eingebunden.
Die Eigenschaft ist dafür gedacht, dass ein Skript mehrere eingebettete Metadatentracks unterscheiden kann. So bindet es nur an die Spuren Handler, die es auch auswerten kann, zum Beispiel ID3-Tags für Werbemarker, Kapitel oder „Jetzt läuft“-Informationen. Wie der Wert entsteht, hängt vom Container ab:
- MPEG-2 TS: Der Wert ist der
stream_typezusammen mit den ES-Info-Bytes aus der Program Map Table, als hexadezimaler String kodiert. - WebM: Der Wert ist die
CodecIDder Spur. - HLS in Safari: Zeitgesteuerte ID3-Metadaten erscheinen typischerweise mit dem Dispatch-Typ
"com.apple.streaming".
Ist der Track kein In-Band-Track, hat er nicht die Art kind === "metadata" oder kennt der Browser keinen Dispatch-Typ, liefert die Eigenschaft einen leeren String. Sie hat keine Parameter. Da sie schreibgeschützt ist, kann man sie nur lesen.
Rückgabewert
"". In Browsern ohne Unterstützung ist der Wert undefined.Beispiele
Dispatch-Typen aller Tracks eines Videos auflisten
const video = document.querySelector('video');
video.addEventListener('loadedmetadata', () => {
for (const track of video.textTracks) {
console.log(
`${track.kind} | ${track.label || '(ohne Label)'} | ` +
`Dispatch-Typ: "${track.inBandMetadataTrackDispatchType ?? 'nicht unterstützt'}"`
);
}
});ID3-Metadaten aus einem HLS-Stream in Safari auswerten
const video = document.querySelector('video');
video.src = 'https://example.com/live/stream.m3u8';
video.textTracks.addEventListener('addtrack', ({ track }) => {
// Nur eingebettete Metadatentracks mit bekanntem Format verwenden
if (track.kind !== 'metadata') return;
if (track.inBandMetadataTrackDispatchType !== 'com.apple.streaming') return;
// 'hidden' sorgt dafür, dass Cues ausgewertet, aber nicht angezeigt werden
track.mode = 'hidden';
track.addEventListener('cuechange', () => {
for (const cue of track.activeCues) {
// In Safari enthalten DataCues ein value-Objekt mit dem ID3-Frame
const { key, data } = cue.value ?? {};
console.log('ID3-Frame:', key, data);
}
});
});Funktionsprüfung mit Rückfall auf eine andere Erkennung
const supportsDispatchType = () =>
'TextTrack' in window &&
'inBandMetadataTrackDispatchType' in TextTrack.prototype;
const isKnownMetadataTrack = (track) => {
if (track.kind !== 'metadata') return false;
if (supportsDispatchType()) {
return track.inBandMetadataTrackDispatchType !== '';
}
// Rückfall: Browser kennt die Eigenschaft nicht, also Label/ID prüfen
return /id3|timed/i.test(track.label + track.id);
};
console.log('Unterstützt:', supportsDispatchType());// Wichtig · Fallstricke
- Browser-Kompatibilität: Nur WebKit (Safari auf macOS und iOS) setzt die Eigenschaft tatsächlich um. In Chrome, Edge und Firefox ist sie nicht vorhanden und liefert
undefined. Prüfe deshalb vorher, ob sie existiert, z. B. mit'inBandMetadataTrackDispatchType' in TextTrack.prototype. Für HLS in anderen Browsern liefern Bibliotheken wie hls.js die ID3-Daten über eigene Events. - Bei Tracks, die per
<track>-Element oderaddTextTrack()entstehen, ist der Wert immer ein leerer String. Ein nicht leerer Wert ist also ein Hinweis darauf, dass der Track aus dem Mediencontainer stammt. - In-Band-Tracks tauchen oft erst nach dem Laden der Metadaten oder sogar während der Wiedergabe auf. Höre deshalb auf das
addtrack-Event vonvideo.textTracks, statt die Liste nur einmal gleich am Anfang auszulesen. - Metadatentracks stehen standardmäßig auf
mode = \"disabled\". Setzemodeauf\"hidden\", sonst werden keinecuechange-Events ausgelöst. - Das Format des Werts hängt vom Container ab (Hex-String, CodecID oder herstellerspezifischer Bezeichner). Vergleiche ihn deshalb nur mit Werten, die für den jeweiligen Container bekannt sind.