HTMLSourceElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLSourceElement extends HTMLElement

Beschreibung

Das Interface HTMLSourceElement steht für ein <source>-Element im DOM. Es erbt alle Eigenschaften und Methoden von HTMLElement und ergänzt sie um Eigenschaften, mit denen sich mehrere alternative Quellen für <video>, <audio> und <picture> beschreiben lassen. Der Browser wählt daraus die erste passende Quelle aus.

Die wichtigsten Eigenschaften:

src – URL der Mediendatei (nur in <video>/<audio> relevant; wird als absolute URL zurückgegeben).
type – MIME-Typ inkl. optionalem codecs-Parameter, z. B. video/webm; codecs="vp9". Nicht unterstützte Typen überspringt der Browser, ohne die Datei zu laden.
srcset und sizes – Kandidatenliste von Bildern bzw. Layoutbreiten (nur innerhalb von <picture>).
media – Media Query, die bestimmt, ob die Quelle in Frage kommt (vor allem in <picture>).
width und height – intrinsische Abmessungen der Bildquelle in <picture>, um Layoutverschiebungen zu vermeiden.

Man nutzt das Interface, wenn Medienquellen dynamisch erzeugt oder ausgetauscht werden sollen – etwa für adaptive Formate (WebM/MP4, AVIF/WebP/JPEG), Art Direction nach Bildschirmgröße oder das Umschalten von Qualitätsstufen. Wichtig: Nachdem sich die <source>-Kinder eines Medienelements geändert haben, muss man bei <video>/<audio> load() aufrufen, damit der Browser die Quellauswahl neu ausführt.

Rückgabewert

Typ

HTMLSourceElement

Beschreibung

Instanzen erhält man über document.createElement('source') oder Abfragen wie querySelector('source'). Es gibt keinen eigenen Konstruktor.

Beispiele

Video mit mehreren Formaten dynamisch aufbauen

const video = document.createElement('video');
video.controls = true;

const quellen = [
  { src: '/media/intro.webm', type: 'video/webm; codecs="vp9, opus"' },
  { src: '/media/intro.mp4', type: 'video/mp4' }
];

for (const { src, type } of quellen) {
  const source = document.createElement('source');
  source.src = src;
  source.type = type;
  video.append(source);
}

document.body.append(video);

// Nach dem Laden: welche Quelle wurde gewählt?
video.addEventListener('loadedmetadata', () => {
  console.log('Gewählt:', video.currentSrc);
});

Gewählt: https://example.com/media/intro.webm

Quelle zur Laufzeit austauschen (Qualitätsstufe)

const video = document.querySelector('#player');
const source = video.querySelector('source');

const setzeQualitaet = (stufe) => {
  const zeit = video.currentTime;
  source.src = `/media/film-${stufe}.mp4`;
  video.load(); // Quellauswahl neu anstoßen – sonst passiert nichts
  video.currentTime = zeit;
  video.play();
};

setzeQualitaet('720p');
console.log(source.src);

https://example.com/media/film-720p.mp4

Responsive Bild mit <picture> und Media Query

const picture = document.createElement('picture');

const avif = document.createElement('source');
avif.type = 'image/avif';
avif.srcset = '/img/hero-800.avif 800w, /img/hero-1600.avif 1600w';
avif.sizes = '(max-width: 600px) 100vw, 50vw';
avif.width = 1600;
avif.height = 900;

const mobil = document.createElement('source');
mobil.media = '(max-width: 600px)';
mobil.srcset = '/img/hero-mobil.jpg';

const img = document.createElement('img');
img.src = '/img/hero-1600.jpg';
img.alt = 'Startbild';

picture.append(avif, mobil, img); // <img> muss das letzte Kind sein
document.body.append(picture);

img.addEventListener('load', () => console.log(img.currentSrc));

https://example.com/img/hero-1600.avif

Formatunterstützung vorab prüfen

const video = document.createElement('video');
const sources = [...document.querySelectorAll('#player source')];

for (const s of sources) {
  console.log(s.type, '→', video.canPlayType(s.type) || 'nein');
}

video/webm; codecs="vp9" → probably video/mp4 → maybe

// Wichtig · Fallstricke

Kein automatisches Neuladen: Ein Ändern von src oder type eines bestehenden <source> in <video>/<audio> hat keine Wirkung, bis media.load() aufgerufen wird. In <picture> dagegen wertet der Browser Änderungen an srcset/media automatisch neu aus.
Kontextabhängige Attribute: srcset, sizes, width und height gelten nur in <picture>; src wird dort ignoriert. Bei Medienelementen ist dagegen src maßgeblich.
Fehlerereignisse: Kann eine Quelle nicht geladen werden, feuert das error-Event am <source>-Element, nicht am <video>. Wer Ladefehler abfangen will, sollte am letzten <source> lauschen.
Getter liefern absolute URLs: source.src gibt die aufgelöste URL zurück; für den Rohwert getAttribute('src') verwenden. Die tatsächlich gewählte Quelle steht in currentSrc des Eltern- bzw. <img>-Elements.
Präziser type: Ein korrekter MIME-Typ mit Codecs spart Netzwerkanfragen, da der Browser ungeeignete Quellen ohne Download überspringt.
Kompatibilität: src, type, media, srcset und sizes werden von allen modernen Browsern unterstützt. width/height sind neuer (Chrome 90, Firefox 108, Safari 15). media auf <source> in <video> wurde lange ignoriert und erst 2023 wieder in Chrome/Firefox eingeführt – nicht blind darauf verlassen.

Siehe auch

HTMLFormElement HTMLPreElement HTMLQuoteElement HTMLSelectElement HTMLStyleElement