HTMLMediaElement.remote — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.remote

Beschreibung

Über HTMLMediaElement.remote erreicht man die Remote Playback API eines <video>- oder <audio>-Elements. Das zurückgegebene RemotePlayback-Objekt steht für die Möglichkeit, das Medium auf einem entfernten Ausgabegerät abzuspielen, zum Beispiel über Chromecast, AirPlay oder einen DLNA-Fernseher.

Typische Anwendungsfälle sind ein eigener „Auf Fernseher abspielen“-Button in einem individuellen Video-Player und die Anzeige des aktuellen Verbindungsstatus. Das Objekt bietet dafür:

state: Verbindungsstatus mit den Werten "disconnected", "connecting" oder "connected".
watchAvailability(callback): benachrichtigt, sobald Remote-Geräte verfügbar werden oder verschwinden.
cancelWatchAvailability(id): beendet diese Überwachung wieder.
prompt(): öffnet die Geräteauswahl des Browsers.
Die Ereignisse connecting, connect und disconnect.

Die Eigenschaft ist schreibgeschützt und liefert für ein Element immer dasselbe Objekt. Es gibt zwar das HTML-Attribut disableremoteplayback bzw. die Eigenschaft disableRemotePlayback, aber auch damit bleibt remote vorhanden. Dann werden nur die Methoden mit einem InvalidStateError abgelehnt.

Rückgabewert

Typ

RemotePlayback

Beschreibung

Das RemotePlayback-Objekt, das zu diesem Media-Element gehört. In Browsern ohne Unterstützung existiert die Eigenschaft nicht, der Wert ist dann undefined.

Beispiele

Unterstützung prüfen und Status auslesen

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

if ('remote' in HTMLMediaElement.prototype) {
  console.log('Remote-Status:', video.remote.state);
} else {
  console.log('Remote Playback API wird nicht unterstützt');
}

Remote-Status: disconnected

Cast-Button nur bei verfügbaren Geräten anzeigen

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

const initRemote = async () => {
  if (!video.remote) {
    castButton.hidden = true;
    return;
  }
  try {
    const watchId = await video.remote.watchAvailability((available) => {
      castButton.hidden = !available;
    });
    // Später aufräumen:
    // await video.remote.cancelWatchAvailability(watchId);
  } catch (err) {
    // NotSupportedError: Überwachung nicht möglich (z. B. Energiesparmodus)
    // Button trotzdem zeigen, prompt() entscheidet dann
    castButton.hidden = false;
  }
};

castButton.addEventListener('click', async () => {
  try {
    await video.remote.prompt(); // muss durch eine Nutzeraktion ausgelöst werden
  } catch (err) {
    console.warn('Keine Verbindung:', err.name);
  }
});

initRemote();

Auf Verbindungsänderungen reagieren

const video = document.querySelector('video');
const status = document.querySelector('#cast-status');
const { remote } = video;

const render = () => {
  const labels = {
    disconnected: 'Lokale Wiedergabe',
    connecting: 'Verbinde …',
    connected: 'Wiedergabe auf externem Gerät'
  };
  status.textContent = labels[remote.state];
};

remote.addEventListener('connecting', render);
remote.addEventListener('connect', render);
remote.addEventListener('disconnect', render);
// Alternativ: remote.onconnect = render;
render();

Lokale Wiedergabe

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die API vor allem unter Android, Safari ab 13.1 über AirPlay. Firefox unterstützt sie nicht. Deshalb vorher immer mit 'remote' in HTMLMediaElement.prototype oder video.remote prüfen, ob sie vorhanden ist.
prompt() funktioniert nur innerhalb einer Nutzeraktion, zum Beispiel eines Klicks. Sonst wird das Promise mit InvalidAccessError abgelehnt.
watchAvailability() kann mit NotSupportedError fehlschlagen, wenn der Browser die Geräteerkennung nicht dauerhaft durchführen kann, etwa um Energie zu sparen. In diesem Fall sollte trotzdem ein Button mit prompt() angeboten werden.
Ist disableRemotePlayback gesetzt, werden alle Methoden mit InvalidStateError abgelehnt.
Medien mit MediaSource (blob:-URLs aus MSE) oder DRM-geschützte Inhalte lassen sich oft nicht remote abspielen.

Siehe auch

HTMLMediaElement.src HTMLMediaElement.muted HTMLMediaElement.preload HTMLMediaElement.ended HTMLMediaElement.error