RemotePlayback.prompt() — Methode · JavaScript-Referenz

Signatur

RemotePlayback.prototype.prompt()

Beschreibung

Die Methode prompt() der Schnittstelle RemotePlayback zeigt einen vom Browser gesteuerten Dialog an. Darin wählt der Nutzer ein verfügbares Gerät für die Fernwiedergabe aus, etwa einen Chromecast, ein AirPlay-Gerät oder einen Smart-TV, und erlaubt damit, dass das zugehörige <video>- oder <audio>-Element dort abgespielt wird. Das RemotePlayback-Objekt bekommst du über die Eigenschaft HTMLMediaElement.remote.

Besteht bereits eine Verbindung (remote.state === "connected"), bietet der Dialog in der Regel an, die Verbindung zu trennen oder das Gerät zu wechseln. Du kannst also denselben „Cast“-Button zum Verbinden und zum Trennen verwenden.

Das zurückgegebene Promise wird erfüllt, sobald der Nutzer ein Gerät gewählt hat (bzw. die Verbindung getrennt hat). Zu diesem Zeitpunkt ist die Verbindung aber meist noch nicht fertig aufgebaut. Den tatsächlichen Stand zeigen die Events connecting, connect und disconnect sowie die Eigenschaft state. Bricht der Nutzer ab oder ist keine Fernwiedergabe möglich, wird das Promise mit einer DOMException abgelehnt.

Üblicherweise prüfst du zuerst mit RemotePlayback.watchAvailability(), ob überhaupt Geräte erreichbar sind. Nur dann blendest du den Cast-Button ein und rufst prompt() direkt im Klick-Handler auf.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald der Nutzer ein Gerät ausgewählt (oder eine bestehende Verbindung getrennt) hat. Bei einem Fehler oder Abbruch wird es mit einer DOMException abgelehnt, z. B. NotAllowedError, NotFoundError, NotSupportedError, InvalidStateError, InvalidAccessError oder OperationError.

Beispiele

Cast-Button: Gerätedialog per Klick öffnen

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

castButton.addEventListener('click', async () => {
  try {
    // Muss direkt aus einer Nutzeraktion heraus aufgerufen werden
    await video.remote.prompt();
    console.log('Gerät gewählt, Status:', video.remote.state);
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      console.log('Nutzer hat den Dialog abgebrochen.');
    } else {
      console.error('Fernwiedergabe fehlgeschlagen:', err.name, err.message);
    }
  }
});

Gerät gewählt, Status: connecting

Button nur bei verfügbaren Geräten anzeigen

const video = document.querySelector('#film');
const castButton = document.querySelector('#cast');
castButton.hidden = true;

if ('remote' in HTMLMediaElement.prototype) {
  video.remote
    .watchAvailability((available) => {
      // Wird bei jeder Änderung der Geräteverfügbarkeit aufgerufen
      castButton.hidden = !available;
    })
    .catch(() => {
      // z. B. NotSupportedError auf Desktop-Chrome: Button bleibt verborgen
      castButton.hidden = true;
    });

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

Verbindungsstatus mit Events verfolgen

const video = document.querySelector('#film');
const status = document.querySelector('#status');

const updateStatus = () => {
  const texte = {
    disconnected: 'Lokale Wiedergabe',
    connecting: 'Verbinde mit Gerät …',
    connected: 'Wiedergabe auf externem Gerät'
  };
  status.textContent = texte[video.remote.state];
  console.log(texte[video.remote.state]);
};

video.remote.addEventListener('connecting', updateStatus);
video.remote.addEventListener('connect', updateStatus);
video.remote.addEventListener('disconnect', updateStatus);

document.querySelector('#cast').addEventListener('click', () => {
  video.remote.prompt().catch((err) => console.warn('Abbruch:', err.name));
});

Verbinde mit Gerät … Wiedergabe auf externem Gerät

// Wichtig · Fallstricke

Nutzeraktion erforderlich: prompt() muss innerhalb einer Nutzerinteraktion aufgerufen werden, etwa in einem click-Handler. Andernfalls wird das Promise mit InvalidAccessError bzw. NotAllowedError abgelehnt. Setze vor dem Aufruf kein await auf andere Promises, sonst kann die Nutzeraktivierung verfallen.
Nur ein Dialog gleichzeitig: Ist ein früheres prompt() noch nicht abgeschlossen, wird ein weiterer Aufruf mit OperationError abgelehnt. Deaktiviere den Button am besten, solange der Dialog offen ist.
disableRemotePlayback: Hat das Medienelement das Attribut disableRemotePlayback, lehnt der Browser mit InvalidStateError ab.
Keine Geräte / nicht unterstützt: Ist gerade kein Gerät erreichbar, lehnt der Browser mit NotFoundError ab. Kann die Quelle nicht übertragen werden, etwa manche MediaSource-Streams, gibt es NotSupportedError.
Erfülltes Promise ≠ verbunden: Das Promise wird bereits bei der Auswahl erfüllt. Ob die Verbindung steht, zeigen erst das Event connect bzw. state === "connected".
Browser-Kompatibilität: Unterstützt in Safari (macOS/iOS, AirPlay) sowie in Chrome/Edge für Android. Desktop-Chrome unterstützt die API nur eingeschränkt, Firefox gar nicht. Prüfe deshalb vorher mit 'remote' in HTMLMediaElement.prototype, ob die API vorhanden ist. Safari bietet zusätzlich die ältere, proprietäre Methode webkitShowPlaybackTargetPicker().

Siehe auch

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