HTMLMediaElement.src — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.src

Beschreibung

Die Eigenschaft src spiegelt das HTML-Attribut src eines Medienelements (<audio> oder <video>) wider. Beim Lesen erhalten Sie immer eine absolute URL. Relative Angaben werden also relativ zur Basis-URL des Dokuments aufgelöst. Ist kein Attribut gesetzt, ist der Wert ein leerer String.

Beim Setzen wird das Attribut aktualisiert und der Ladealgorithmus des Elements neu gestartet: Die laufende Wiedergabe bricht ab, currentTime wird zurückgesetzt und der Browser beginnt mit dem Laden der neuen Ressource. Deshalb eignet sich src gut, um in Wiedergabelisten, Playern oder Vorschau-Funktionen zwischen Dateien zu wechseln.

Ist ein src-Attribut vorhanden, werden verschachtelte <source>-Elemente ignoriert. Für mehrere Formate als Ausweichlösung sollten Sie src daher weglassen und <source>-Kindelemente verwenden. Welche Ressource der Browser tatsächlich ausgewählt hat, liefert currentSrc.

Für MediaStream-, MediaSource- oder Blob-Objekte gibt es srcObject. Wenn srcObject gesetzt ist, hat es Vorrang vor src.

Parameter

Name	Typ	Default	Beschreibung
$wert	string	""	Nur beim Setzen: URL der Medienressource. Erlaubt sind relative oder absolute URLs, `blob:`- und `data:`-URLs.

Rückgabewert

Typ

string

Beschreibung

Die absolute URL aus dem src-Attribut oder ein leerer String, wenn das Attribut fehlt.

Beispiele

Quelle auslesen (absolute URL)

// HTML: <video id="clip" src="media/intro.mp4"></video>
const video = document.querySelector('#clip');
console.log(video.src);
console.log(video.getAttribute('src'));

https://example.com/media/intro.mp4 media/intro.mp4

Titel in einer Wiedergabeliste wechseln

const player = document.querySelector('audio');
const playlist = ['songs/eins.mp3', 'songs/zwei.mp3', 'songs/drei.mp3'];
let index = 0;

const playTrack = async (i) => {
  player.src = playlist[i]; // startet das Laden neu
  try {
    await player.play();
  } catch (err) {
    console.warn('Wiedergabe blockiert:', err.name);
  }
};

player.addEventListener('ended', () => {
  index = (index + 1) % playlist.length;
  playTrack(index);
});

playTrack(index);

Lokale Datei per Blob-URL abspielen

const input = document.querySelector('input[type=file]');
const video = document.querySelector('video');

input.addEventListener('change', () => {
  const file = input.files[0];
  if (!file) return;
  if (video.src.startsWith('blob:')) URL.revokeObjectURL(video.src);
  video.src = URL.createObjectURL(file);
});

Quelle entfernen und Ressourcen freigeben

const video = document.querySelector('video');
video.pause();
video.removeAttribute('src'); // nicht: video.src = ''
video.load(); // bricht das Laden ab und gibt die Ressource frei
console.log(video.src === '');

true

// Wichtig · Fallstricke

Absolute URL beim Lesen: video.src === 'intro.mp4' ist praktisch immer false. Für den rohen Attributwert verwenden Sie getAttribute('src').
src = '' vermeiden: Ein leerer String wird zur Dokument-URL aufgelöst und kann einen Ladefehler auslösen (error-Ereignis, MEDIA_ERR_SRC_NOT_SUPPORTED). Nutzen Sie stattdessen removeAttribute('src') und danach load().
play() nach dem Wechsel: Wird play() direkt nach dem Setzen aufgerufen, kann das Promise mit AbortError abgelehnt werden, wenn schnell hintereinander erneut gewechselt wird. Wegen Autoplay-Richtlinien kann es auch mit NotAllowedError abgelehnt werden. Fangen Sie das Promise immer ab.
<source> wird ignoriert: Ist src gesetzt, zählen <source>-Kindelemente nicht.
Blob-URLs freigeben: Mit URL.createObjectURL() erzeugte URLs sollten Sie mit URL.revokeObjectURL() wieder freigeben, sonst entstehen Speicherlecks.
CORS: Medien von fremden Ursprüngen lassen sich abspielen. Wenn Sie aber z. B. Pixel per Canvas oder Audiodaten per Web Audio API auslesen wollen, brauchen Sie crossorigin und passende CORS-Header.
Die Eigenschaft funktioniert in allen modernen Browsern. MediaStream-Objekte gehören nicht in src, sondern in srcObject.

Siehe auch

HTMLAreaElement.search HTMLMediaElement.error HTMLMediaElement.loop HTMLMediaElement.ended HTMLMediaElement.muted