HTMLTrackElement.src — Eigenschaft · JavaScript-Referenz

Signatur

HTMLTrackElement.src

Beschreibung

Die Eigenschaft src des HTMLTrackElement-Interfaces spiegelt das HTML-Attribut src eines <track>-Elements wider. Sie enthält die URL der Textspur-Daten, in der Praxis fast immer eine WebVTT-Datei (.vtt) mit Untertiteln, Beschreibungen, Kapiteln oder Metadaten für ein <video>- oder <audio>-Element.

Beim Lesen gibt die Eigenschaft immer eine absolute, aufgelöste URL zurück, auch wenn im Attribut nur ein relativer Pfad steht. Den unveränderten Attributwert erhältst du mit getAttribute('src'). Ist kein Attribut gesetzt, ist der Rückgabewert ein leerer String.

Wenn du src per Skript setzt, lädt der Browser die neue Datei, allerdings nur, wenn die Spur aktiv ist (track.mode ist "showing" oder "hidden"). Das ist praktisch, um z. B. Untertitel dynamisch nachzuladen oder Sprachen umzuschalten, ohne das Element neu anzulegen. Ob das Laden geklappt hat, erkennst du an den Events load und error am <track>-Element sowie an readyState.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: absolute oder relative URL der Textspur-Datei. Relative URLs werden gegen die Basis-URL des Dokuments aufgelöst.

Rückgabewert

Typ

string

Beschreibung

Die vollständig aufgelöste URL aus dem src-Attribut oder ein leerer String, wenn das Attribut fehlt.

Beispiele

URL einer Untertitelspur auslesen

// HTML: <video id="film" src="film.mp4"><track id="de" kind="subtitles" srclang="de" src="untertitel/de.vtt"></video>
const track = document.getElementById('de');

console.log(track.src);                 // aufgelöste, absolute URL
console.log(track.getAttribute('src')); // Rohwert aus dem HTML

https://example.com/untertitel/de.vtt untertitel/de.vtt

Untertitelsprache dynamisch wechseln

const video = document.querySelector('video');
const track = video.querySelector('track');

const setSubtitleLanguage = (lang) => {
  track.srclang = lang;
  track.label = lang === 'de' ? 'Deutsch' : 'English';
  track.src = `/untertitel/${lang}.vtt`;
  // Spur aktivieren, damit sie geladen und angezeigt wird
  track.track.mode = 'showing';
};

track.addEventListener('load', () => console.log('Geladen:', track.src));
track.addEventListener('error', () => console.error('Fehler beim Laden:', track.src));

setSubtitleLanguage('en');

Geladen: https://example.com/untertitel/en.vtt

Track mit Blob-URL aus generiertem WebVTT erzeugen

const vtt = `WEBVTT

00:00:01.000 --> 00:00:04.000
Hallo und willkommen!`;

const blobUrl = URL.createObjectURL(new Blob([vtt], { type: 'text/vtt' }));

const video = document.querySelector('video');
const track = document.createElement('track');
track.kind = 'captions';
track.srclang = 'de';
track.label = 'Deutsch (generiert)';
track.src = blobUrl;
track.default = true;
video.append(track);

track.addEventListener('load', () => {
  console.log('Cues:', track.track.cues.length);
  URL.revokeObjectURL(blobUrl);
});

Cues: 1

// Wichtig · Fallstricke

CORS: Textspuren von einem anderen Origin werden nur geladen, wenn das übergeordnete <video>/<audio> ein crossorigin-Attribut hat und der Server passende Access-Control-Allow-Origin-Header schickt. Sonst wird das Event error ausgelöst.
Lazy Loading: Ist track.track.mode auf "disabled" gesetzt (Standard bei nicht-default-Spuren), lädt der Browser die Datei nicht. Setze mode auf "showing" oder "hidden".
Format: Browser unterstützen nur WebVTT. SRT-Dateien musst du vorher umwandeln. Der Server sollte den MIME-Typ text/vtt senden.
Der gelesene Wert ist immer absolut. Für einen Vergleich mit dem Rohwert nimm getAttribute('src').
Seiten mit file:// blockieren das Laden in vielen Browsern (z. B. Chrome). Teste deshalb über einen lokalen Webserver.
Die Eigenschaft wird von allen modernen Browsern unterstützt.

Siehe auch

HTMLTrackElement.track HTMLTrackElement.kind HTMLTrackElement.srclang HTMLTrackElement.label HTMLTrackElement.default