HTMLMediaElement.controller — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.controller

Beschreibung

Die Eigenschaft HTMLMediaElement.controller verweist auf ein MediaController-Objekt, das dem Audio- oder Videoelement zugeordnet ist. Ein MediaController sollte mehrere Medienelemente gemeinsam steuern. Wiedergabe, Pause, Zeitposition, Lautstärke und Wiedergabegeschwindigkeit sollten dann für alle Elemente gleich sein. Ein typischer Anwendungsfall ist ein Video mit einer getrennten Gebärdensprach-Spur oder einer zusätzlichen Audiodeskription.

Ist dem Element kein Controller zugeordnet, ist der Wert null. Einen Controller konnte man auf zwei Wegen zuordnen: indem man der Eigenschaft ein new MediaController() zuwies, oder indirekt über das Attribut mediagroup bzw. die Eigenschaft mediaGroup. Alle Elemente mit demselben Gruppennamen im selben Dokument bekamen automatisch einen gemeinsamen Controller.

Wichtig: MediaController, controller und mediaGroup wurden aus dem HTML-Standard entfernt. Früher unterstützten nur WebKit-basierte Browser (Safari) und eine Zeit lang Chrome diese Funktionen. Inzwischen haben alle Browser sie wieder entfernt. Firefox hat sie nie eingebaut. In neuem Code solltest du die Eigenschaft nicht verwenden. Synchronisiere mehrere Medien stattdessen selbst, zum Beispiel über currentTime, play()/pause() und die Ereignisse timeupdate, seeking und ratechange. Für Audio eignet sich auch die Web Audio API.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	MediaController \| null	null	Früher: ein `MediaController`-Objekt, das dem Element zugeordnet werden sollte, oder `null`, um die Zuordnung zu lösen. Das Setzen hat außerdem das Attribut `mediagroup` entfernt.

Rückgabewert

Typ

MediaController | null | undefined

Beschreibung

In alten Implementierungen der zugeordnete MediaController oder null. In allen aktuellen Browsern gibt es die Eigenschaft nicht mehr, sie liefert daher undefined.

Beispiele

Prüfen, ob der Browser die Eigenschaft unterstützt

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

const hatController = 'controller' in video && typeof window.MediaController === 'function';

console.log(hatController
  ? 'MediaController wird unterstützt'
  : 'MediaController wird nicht unterstützt – eigene Synchronisation verwenden');

MediaController wird nicht unterstützt – eigene Synchronisation verwenden

Historische Nutzung: zwei Videos gemeinsam steuern (nur alte Browser)

const hauptVideo = document.querySelector('#haupt');
const gebaerdenVideo = document.querySelector('#gebaerde');

if (typeof window.MediaController === 'function') {
  const ctrl = new MediaController();
  hauptVideo.controller = ctrl;
  gebaerdenVideo.controller = ctrl;

  // Wiedergabe und Lautstärke gelten für beide Elemente
  ctrl.volume = 0.8;
  ctrl.play();
  console.log(hauptVideo.controller === gebaerdenVideo.controller);
} else {
  console.warn('MediaController nicht verfügbar');
}

MediaController nicht verfügbar (in aktuellen Browsern)

Moderner Ersatz: eigene Synchronisation zweier Medienelemente

const syncMedia = (master, slave, toleranz = 0.1) => {
  master.addEventListener('play', () => slave.play());
  master.addEventListener('pause', () => slave.pause());
  master.addEventListener('ratechange', () => {
    slave.playbackRate = master.playbackRate;
  });
  master.addEventListener('seeking', () => {
    slave.currentTime = master.currentTime;
  });
  master.addEventListener('timeupdate', () => {
    // Zeitabweichung korrigieren
    if (Math.abs(slave.currentTime - master.currentTime) > toleranz) {
      slave.currentTime = master.currentTime;
    }
  });
};

const haupt = document.querySelector('#haupt');
const beschreibung = document.querySelector('#audiodeskription');
syncMedia(haupt, beschreibung);
console.log('Synchronisation aktiv');

Synchronisation aktiv

// Wichtig · Fallstricke

Veraltet und entfernt: controller, mediaGroup und das Interface MediaController gehören nicht mehr zum HTML-Standard. Kein aktueller Browser unterstützt sie. Chrome und Safari haben ihre früheren Umsetzungen entfernt, Firefox hatte nie eine.
In aktuellen Browsern liefert video.controller den Wert undefined und nicht null. Prüfe die Unterstützung deshalb mit typeof window.MediaController === 'function', nicht mit einem Vergleich auf null.
Verwechsle die Eigenschaft nicht mit HTMLMediaElement.controls. controls ist ein Boolean und schaltet die eingebauten Bedienelemente des Browsers ein oder aus.
Wenn du Medien selbst synchronisierst, entstehen durch timeupdate (etwa 4 Hz) und Pufferung kleine Zeitabweichungen. Für eine genauere Synchronisation kannst du requestVideoFrameCallback() verwenden, wo es verfügbar ist. Für Audio ist die Web Audio API besser geeignet.

Siehe auch

HTMLMediaElement.controls HTMLMediaElement.controlsList HTMLMediaElement.autoplay HTMLMediaElement.error HTMLMediaElement.currentSrc