RemotePlayback — Schnittstelle · JavaScript-Referenz

Signatur

interface RemotePlayback extends EventTarget

Beschreibung

Das Interface RemotePlayback gehört zur Remote Playback API. Mit ihm lässt sich ein <video>- oder <audio>-Element auf einem externen Gerät abspielen, etwa über Chromecast, AirPlay oder einen DLNA-fähigen Fernseher. Man erzeugt es nicht selbst: Jedes HTMLMediaElement stellt seine Instanz über die Eigenschaft element.remote bereit.

Die wichtigsten Bestandteile:

state (nur lesbar): "disconnected", "connecting" oder "connected".
watchAvailability(callback): beobachtet, ob Geräte verfügbar sind, und liefert ein Promise<number> mit einer Callback-ID.
cancelWatchAvailability(id): beendet eine bestimmte Beobachtung. Ohne ID werden alle Beobachtungen beendet.
prompt(): öffnet den Geräteauswahldialog des Browsers. Das geht nur nach einer Nutzeraktion wie einem Klick.
Events connecting, connect und disconnect: Du registrierst sie per addEventListener oder über die Eigenschaften onconnecting, onconnect und ondisconnect.

Typischer Einsatz ist ein eigener „Cast“-Button in einem selbstgebauten Videoplayer. Der Button wird nur angezeigt, wenn tatsächlich ein Gerät verfügbar ist, und zeigt den aktuellen Verbindungsstatus an. Die Wiedergabe selbst steuerst du wie gewohnt über das Medienelement, also mit play(), pause() und currentTime. Der Browser leitet diese Befehle an das entfernte Gerät weiter.

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	(available: boolean) => void		Parameter von `watchAvailability()`. Wird sofort und danach bei jeder Änderung aufgerufen, mit `true`, wenn mindestens ein kompatibles Gerät verfügbar ist.
$id	number		Parameter von `cancelWatchAvailability()`. Die von `watchAvailability()` gelieferte Callback-ID. Ohne ID werden alle Beobachtungen dieses Elements beendet.

Rückgabewert

Typ

RemotePlayback

Beschreibung

Die Instanz erhältst du über HTMLMediaElement.remote. Rückgabewerte der Methoden: watchAvailability() → Promise<number> (Callback-ID), cancelWatchAvailability() und prompt() → Promise<void>.

Beispiele

Instanz holen und Status auslesen

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

if ('remote' in HTMLMediaElement.prototype) {
  const remote = video.remote; // RemotePlayback-Instanz
  console.log(remote instanceof RemotePlayback, remote.state);
} else {
  console.log('Remote Playback API wird nicht unterstützt');
}

true "disconnected"

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

const video = document.querySelector('#player');
const castBtn = document.querySelector('#cast');
let watchId;

const updateButton = (available) => {
  castBtn.hidden = !available;
};

try {
  watchId = await video.remote.watchAvailability(updateButton);
  console.log('Beobachtung gestartet, ID:', watchId);
} catch (err) {
  // z. B. NotSupportedError: Dauerbeobachtung auf dieser Plattform nicht möglich
  console.warn(err.name);
  castBtn.hidden = false; // Button trotzdem zeigen, prompt() entscheidet dann
}

// Später, z. B. beim Entfernen des Players:
const stopWatching = () => video.remote.cancelWatchAvailability(watchId);

Beobachtung gestartet, ID: 1

Geräteauswahl öffnen und Verbindung verfolgen

const video = document.querySelector('#player');
const castBtn = document.querySelector('#cast');
const { remote } = video;

remote.addEventListener('connecting', () => castBtn.textContent = 'Verbinde …');
remote.addEventListener('connect', () => castBtn.textContent = 'Wird übertragen');
remote.ondisconnect = () => castBtn.textContent = 'Übertragen';

castBtn.addEventListener('click', async () => {
  try {
    await remote.prompt(); // nur mit Nutzeraktion erlaubt
  } catch (err) {
    // NotFoundError: kein Gerät, NotAllowedError: abgebrochen/keine Nutzeraktion
    console.log('Fernwiedergabe fehlgeschlagen:', err.name);
  }
});

Fernwiedergabe fehlgeschlagen: NotAllowedError

Eingebauten Cast-Button abschalten

const video = document.querySelector('video');
// Entspricht dem HTML-Attribut disableremoteplayback
video.disableRemotePlayback = true;

video.remote.prompt().catch((err) => console.log(err.name));

InvalidStateError

// Wichtig · Fallstricke

Browserunterstützung: Chrome unterstützt die API auf Android und seit Version 121 auch auf dem Desktop, Safari ab Version 13.1 (dort über AirPlay). Firefox unterstützt sie nicht. Prüfe deshalb vorher mit 'remote' in HTMLMediaElement.prototype, ob die API vorhanden ist.
watchAvailability() kann mit NotSupportedError abgelehnt werden. Das passiert, wenn die Plattform keine dauerhafte Beobachtung erlaubt (etwa aus Energiespargründen) oder wenn disableRemotePlayback gesetzt ist. Zeige den Button in diesem Fall trotzdem an und überlass die Entscheidung prompt().
prompt() braucht eine Nutzeraktion (transient activation), sonst wird es mit NotAllowedError abgelehnt. Weitere Fehler: NotFoundError (kein Gerät gefunden) und InvalidStateError (Fernwiedergabe deaktiviert). OperationError tritt auf, wenn gerade schon ein Auswahldialog offen ist.
Viele Cast-Geräte können keine blob:- oder MSE-Quellen abspielen. Nutze deshalb eine normale, öffentlich erreichbare URL im src und beachte CORS für Untertitel.
Rufe beim Aufräumen cancelWatchAvailability() auf. Aktive Beobachtungen verbrauchen Energie, weil der Browser weiter nach Geräten im Netzwerk sucht.

Siehe auch

HTMLMediaElement HTMLMediaElement.remote HTMLMediaElement.disableRemotePlayback RemotePlayback.prompt() RemotePlayback.watchAvailability() Presentation