RemotePlayback.watchAvailability() — Methode · JavaScript-Referenz

Signatur

RemotePlayback.prototype.watchAvailability(callback)

Beschreibung

Mit watchAvailability() registrierst du einen Callback beim RemotePlayback-Objekt eines Medienelements (video.remote bzw. audio.remote). Der Browser ruft den Callback mit einem booleschen Wert auf: true heißt, mindestens ein passendes Remote-Wiedergabegerät ist erreichbar, false heißt, es gibt keins. Der erste Aufruf kommt kurz nach der Registrierung mit dem aktuellen Stand, danach wird der Callback bei jeder Änderung erneut aufgerufen.

Typischerweise nutzt du die Methode, um einen „Auf Fernseher streamen“-Button nur dann anzuzeigen, wenn wirklich ein Gerät da ist. Den eigentlichen Verbindungsdialog öffnest du danach mit RemotePlayback.prompt().

Das zurückgegebene Promise wird mit einer numerischen callbackId erfüllt. Mit dieser ID beendest du die Überwachung gezielt über cancelWatchAvailability(callbackId). Ohne Argument beendet cancelWatchAvailability() alle Überwachungen für dieses Element.

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	(available: boolean) => void		Wird bei jeder Änderung der Geräteverfügbarkeit aufgerufen und direkt nach der Registrierung einmal mit dem aktuellen Stand. `available` ist `true`, wenn mindestens ein kompatibles Remote-Gerät gefunden wurde.

Rückgabewert

Typ

Promise<number>

Beschreibung

Ein Promise, das mit einer ganzzahligen callbackId erfüllt wird. Es wird mit einer DOMException abgelehnt, und zwar mit InvalidStateError, wenn am Element disableRemotePlayback gesetzt ist, oder mit NotSupportedError, wenn der Browser die Verfügbarkeit nicht dauerhaft überwachen kann (z. B. um Energie zu sparen).

Beispiele

Cast-Button abhängig von der Verfügbarkeit anzeigen

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

const updateButton = (available) => {
  castButton.hidden = !available;
  console.log('Remote-Gerät verfügbar:', available);
};

if ('remote' in HTMLMediaElement.prototype) {
  try {
    const id = await video.remote.watchAvailability(updateButton);
    console.log('Überwachung aktiv, ID:', id);
  } catch (err) {
    // NotSupportedError: Button trotzdem zeigen, prompt() entscheidet dann
    castButton.hidden = false;
    console.warn(err.name, err.message);
  }

  castButton.addEventListener('click', () => {
    video.remote.prompt().catch((e) => console.warn('Abgebrochen:', e.name));
  });
}

Überwachung aktiv, ID: 1 Remote-Gerät verfügbar: true

Überwachung gezielt beenden

const video = document.querySelector('video');
let watchId = null;

const startWatching = async () => {
  watchId = await video.remote.watchAvailability((available) => {
    console.log(available ? 'Gerät gefunden' : 'Kein Gerät');
  });
};

const stopWatching = async () => {
  if (watchId !== null) {
    await video.remote.cancelWatchAvailability(watchId);
    console.log('Überwachung beendet');
    watchId = null;
  }
};

await startWatching();
// z. B. beim Verlassen der Ansicht aufräumen
window.addEventListener('pagehide', stopWatching);

Gerät gefunden

Fehlerfall: disableRemotePlayback gesetzt

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

try {
  await video.remote.watchAvailability(() => {});
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser (Chrome, Edge, Opera) und Safari (AirPlay) unterstützen die Remote Playback API. Firefox unterstützt sie standardmäßig nicht. Prüfe deshalb vorher mit 'remote' in HTMLMediaElement.prototype, ob die API da ist.
NotSupportedError ist kein Grund zum Aufgeben: Manche Plattformen (etwa Chrome auf Android unter bestimmten Bedingungen) lehnen die dauerhafte Überwachung ab, um Energie zu sparen. prompt() funktioniert dort oft trotzdem. Blende den Button in diesem Fall also ruhig ein.
Die Verfügbarkeit hängt auch von der Medienquelle ab. Bei manchen Quellen (z. B. über Media Source Extensions oder mit DRM) meldet der Browser womöglich false, obwohl Geräte im Netz sind.
Rechne nicht damit, dass der Callback synchron aufgerufen wird. Der erste Aufruf kommt asynchron.
Beende nicht mehr benötigte Überwachungen mit cancelWatchAvailability(), denn die Gerätesuche kostet Akku und Netzwerkressourcen.
Den Verbindungsstatus (connecting, connected, disconnected) liefert nicht dieser Callback, sondern die Eigenschaft RemotePlayback.state bzw. die gleichnamigen Events.

Siehe auch

RemotePlayback RemotePlayback.cancelWatchAvailability() RemotePlayback.prompt() RemotePlayback.state HTMLMediaElement.remote HTMLMediaElement.disableRemotePlayback