Signatur
Beschreibung
Die Eigenschaft played gibt ein TimeRanges-Objekt zurück. Es enthält die Abschnitte der Medienressource, die der Browser seit dem Laden tatsächlich wiedergegeben hat. Jeder Bereich hat eine Start- und eine Endzeit in Sekunden. Diese Zeiten fragst du über start(i) und end(i) ab, die Anzahl der Bereiche über length.
Springt der Nutzer im Medium umher (Seeking), entstehen mehrere getrennte Bereiche. Überlappende oder direkt aneinandergrenzende Abschnitte fasst der Browser automatisch zu einem Bereich zusammen. Deshalb eignet sich played gut für Nutzungsstatistiken: Du kannst messen, wie viel Prozent eines Videos wirklich angesehen wurden, oder prüfen, ob ein Pflichtvideo (z. B. in einer E-Learning-Anwendung) vollständig angeschaut wurde.
Im Unterschied dazu zeigt buffered, welche Teile geladen sind, und seekable, zu welchen Stellen gesprungen werden kann. played betrachtet nur die tatsächliche Wiedergabe.
Rückgabewert
TimeRanges-Objekt mit den Eigenschaften length sowie den Methoden start(index) und end(index). Die Werte sind Sekunden (number). Wurde noch nichts abgespielt, ist length gleich 0.Beispiele
Abgespielte Bereiche auflisten
const video = document.querySelector('video');
video.addEventListener('pause', () => {
const { played } = video;
for (let i = 0; i < played.length; i++) {
console.log(`Bereich ${i}: ${played.start(i).toFixed(1)}s – ${played.end(i).toFixed(1)}s`);
}
});Prozentsatz des angesehenen Videos berechnen
const video = document.querySelector('#lernvideo');
const gesehenProzent = (media) => {
const { played, duration } = media;
if (!Number.isFinite(duration) || duration === 0) return 0;
let summe = 0;
for (let i = 0; i < played.length; i++) {
summe += played.end(i) - played.start(i);
}
return Math.round((summe / duration) * 100);
};
video.addEventListener('ended', () => {
console.log(`Angesehen: ${gesehenProzent(video)} %`);
});Prüfen, ob ein Pflichtvideo komplett angesehen wurde
const video = document.querySelector('video');
const weiterButton = document.querySelector('#weiter');
weiterButton.disabled = true;
const komplettGesehen = ({ played, duration }, toleranz = 1) =>
played.length === 1 &&
played.start(0) <= toleranz &&
played.end(0) >= duration - toleranz;
video.addEventListener('timeupdate', () => {
if (komplettGesehen(video)) {
weiterButton.disabled = false;
console.log('Video vollständig angesehen – weiter freigeschaltet.');
}
});// Wichtig · Fallstricke
- Momentaufnahme:
playedgibt bei jedem Zugriff ein neues Objekt zurück. Es aktualisiert sich nicht selbst. Lies die Eigenschaft deshalb erneut, z. B. imtimeupdate- oderpause-Handler. - Zurücksetzen: Wird eine neue Quelle geladen (
srcändern,load()aufrufen), leert der Browser die Liste wieder. - Indexfehler:
start(i)undend(i)werfen einenIndexSizeError(DOMException), wenniaußerhalb von0 … length - 1liegt. - Keine Wiederholungszählung: Wird ein Abschnitt mehrfach abgespielt, erscheint er trotzdem nur einmal. Die tatsächliche Sehdauer kannst du daraus also nicht ablesen.
- Livestreams: Hier ist
durationoftInfinity. Prozentangaben sind dann nicht sinnvoll. - Manipulierbar: Werte, die im Client ermittelt werden (z. B. „Video angesehen“), lassen sich leicht fälschen. Für sicherheitsrelevante Nachweise brauchst du eine Prüfung auf dem Server.
- Die Eigenschaft funktioniert in allen modernen Browsern und seit Längerem auch in mobilen Browsern.