Signatur
Beschreibung
Die Eigenschaft buffered eines <audio>- oder <video>-Elements zeigt, welche Abschnitte der Medienressource der Browser zum Zeitpunkt des Zugriffs schon geladen hat. Sie liefert ein TimeRanges-Objekt. Jeder Bereich darin hat einen Start- und einen Endzeitpunkt in Sekunden, die man mit start(i) und end(i) abfragt. Mit length erhält man die Anzahl der Bereiche.
Normiert bedeutet: Die Bereiche sind aufsteigend sortiert, überlappen sich nicht und grenzen nicht aneinander. Aneinanderstoßende Abschnitte werden zu einem Bereich zusammengefasst. Mehrere getrennte Bereiche gibt es zum Beispiel, wenn der Nutzer an eine Stelle springt (Seeking) und der Browser dort neu zu laden beginnt.
Statisch bedeutet: Das Objekt ist eine Momentaufnahme und aktualisiert sich nicht selbst. Wer den Ladefortschritt verfolgen will, etwa für einen Fortschrittsbalken im eigenen Player, liest buffered bei jedem progress- oder timeupdate-Event neu aus.
Typische Anwendungen sind Pufferanzeigen in eigenen Player-Oberflächen, die Prüfung, ob eine Sprungmarke schon ohne Nachladen abspielbar ist, und die Diagnose des Streamings, etwa zusammen mit Media Source Extensions.
Rückgabewert
TimeRanges-Objekt mit den gepufferten Bereichen, Angaben in Sekunden. Ist noch nichts gepuffert, ist length gleich 0.Beispiele
Gepufferte Bereiche auflisten
const video = document.querySelector('video');
const logBuffered = () => {
const ranges = video.buffered;
for (let i = 0; i < ranges.length; i++) {
console.log(`Bereich ${i}: ${ranges.start(i).toFixed(1)}s – ${ranges.end(i).toFixed(1)}s`);
}
};
video.addEventListener('progress', logBuffered);Pufferanzeige für einen eigenen Player
const video = document.querySelector('#player');
const bar = document.querySelector('#buffer-bar');
const updateBufferBar = () => {
const { buffered, currentTime, duration } = video;
if (!Number.isFinite(duration) || buffered.length === 0) return;
// Den Bereich suchen, in dem die aktuelle Abspielposition liegt
for (let i = 0; i < buffered.length; i++) {
if (buffered.start(i) <= currentTime && currentTime <= buffered.end(i)) {
const percent = (buffered.end(i) / duration) * 100;
bar.style.width = `${percent}%`;
break;
}
}
};
video.addEventListener('progress', updateBufferBar);
video.addEventListener('timeupdate', updateBufferBar);Prüfen, ob eine Zielzeit schon gepuffert ist
const isBuffered = (media, time) => {
const { buffered } = media;
for (let i = 0; i < buffered.length; i++) {
if (time >= buffered.start(i) && time <= buffered.end(i)) return true;
}
return false;
};
const audio = document.querySelector('audio');
const target = 45;
if (isBuffered(audio, target)) {
audio.currentTime = target; // Sprung ohne Nachladen
} else {
console.log('Position noch nicht geladen – kurze Wartezeit möglich');
audio.currentTime = target;
}// Wichtig · Fallstricke
- Momentaufnahme: Jeder Zugriff liefert ein neues Objekt. Wer eine Referenz speichert, sieht später keine Änderungen. Deshalb bei Bedarf neu auslesen.
start(i)undend(i)werfen einenIndexSizeError(DOMException), wenn der Index außerhalb von0bislength - 1liegt. Vorherlengthprüfen.- Nicht davon ausgehen, dass es nur einen Bereich gibt: Nach Sprüngen im Medium entstehen oft mehrere getrennte Bereiche.
- Bei Live-Streams kann
durationden WertInfinityhaben. Prozentrechnungen deshalb mitNumber.isFinite()absichern. - Browser können bereits geladene Daten wieder verwerfen, etwa bei Speicherknappheit oder bei MSE-Quellen. Bereiche können also auch schrumpfen.
- Bei
preload="none"ist bis zum Abspielstart meist nichts gepuffert. - Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt. Wie oft das
progress-Event feuert, unterscheidet sich je nach Browser.