RemotePlayback: connect — Ereignis · JavaScript-Referenz

Signatur

remotePlayback.addEventListener("connect", handler)

Beschreibung

Das connect-Ereignis gehört zur Remote Playback API. Über die Eigenschaft HTMLMediaElement.remote erhält jedes <video>- oder <audio>-Element ein RemotePlayback-Objekt. Das Ereignis wird ausgelöst, sobald der Browser die Verbindung zu einem Wiedergabegerät wie einem Chromecast, einem Smart-TV oder einem AirPlay-Empfänger hergestellt hat. Zum selben Zeitpunkt wechselt remote.state auf "connected".

Der Verbindungsaufbau läuft über drei Ereignisse: Zuerst kommt connecting (Zustand "connecting"), nach erfolgreichem Aufbau connect, und beim Trennen disconnect (Zustand "disconnected"). Ab dem connect-Ereignis gibt das Remote-Gerät das Medium wieder. Die lokale Wiedergabe wird dann normalerweise angehalten, und Steuerbefehle wie play(), pause() oder currentTime am Medienelement werden an das Remote-Gerät weitergegeben.

Typische Anwendungsfälle sind: Die Oberfläche anpassen (z. B. „Wird auf dem Fernseher abgespielt“ anzeigen oder das Cast-Symbol hervorheben), eigene Steuerelemente umschalten und Nutzungsstatistiken erfassen. Du kannst den Handler mit addEventListener("connect", …) oder über die Eigenschaft onconnect registrieren.

Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften. Es lässt sich nicht abbrechen und steigt nicht auf (kein Bubbling). Sein target ist das RemotePlayback-Objekt, nicht das Medienelement.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier `"connect"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion, die nach dem Verbindungsaufbau aufgerufen wird. Sie erhält ein einfaches `Event`, dessen `target` das `RemotePlayback`-Objekt ist.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die Eigenschaft onconnect enthält die zugewiesene Funktion oder null.

Beispiele

Oberfläche beim Verbinden mit addEventListener anpassen

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

if ('remote' in HTMLMediaElement.prototype) {
  video.remote.addEventListener('connecting', () => {
    status.textContent = 'Verbinde mit Gerät …';
  });

  video.remote.addEventListener('connect', (event) => {
    // event.target ist das RemotePlayback-Objekt
    console.log('Zustand:', event.target.state);
    status.textContent = 'Wird auf dem Fernseher abgespielt';
    document.body.classList.add('is-casting');
  });

  video.remote.addEventListener('disconnect', () => {
    status.textContent = '';
    document.body.classList.remove('is-casting');
  });
}

Zustand: connected

Geräteauswahl öffnen und onconnect nutzen

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

video.remote.onconnect = () => {
  castButton.setAttribute('aria-pressed', 'true');
  console.log('Remote-Wiedergabe aktiv');
};

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

Remote-Wiedergabe aktiv

Listener mit AbortController wieder entfernen

const video = document.querySelector('video');
const controller = new AbortController();

const onConnect = () => {
  console.log('Verbunden um', new Date().toLocaleTimeString('de-DE'));
};

video.remote.addEventListener('connect', onConnect, { signal: controller.signal });

// Später, z. B. beim Zerstören der Player-Komponente:
const destroyPlayer = () => {
  controller.abort(); // entspricht removeEventListener('connect', onConnect)
  video.remote.onconnect = null;
};

destroyPlayer();

// Wichtig · Fallstricke

Browser-Unterstützung: Die Remote Playback API gibt es in Chrome für Android und in Safari (macOS/iOS, AirPlay). Firefox unterstützt sie standardmäßig nicht, und Chrome am Desktop nur eingeschränkt. Prüfe die Unterstützung vorher mit 'remote' in HTMLMediaElement.prototype.
Ist beim Registrieren des Listeners schon eine Verbindung aktiv, wird connect nicht nachträglich ausgelöst. Prüfe deshalb zusätzlich video.remote.state === 'connected'.
Das Ereignis wird am RemotePlayback-Objekt ausgelöst, nicht am Medienelement. video.addEventListener('connect', …) funktioniert daher nicht.
Hat das Medienelement das Attribut disableRemotePlayback, ist keine Remote-Wiedergabe möglich, und connect wird nie ausgelöst.
prompt() muss durch eine Benutzeraktion ausgelöst werden, sonst wird das Promise mit InvalidAccessError bzw. NotAllowedError abgelehnt.
Manche Quellen, z. B. MSE- oder EME-geschützte Streams, können nicht an jedes Gerät übertragen werden. Prüfe die Verfügbarkeit vorher mit watchAvailability().

Siehe auch

RemotePlayback RemotePlayback.state RemotePlayback.prototype.prompt() RemotePlayback.prototype.watchAvailability() HTMLMediaElement.remote RemotePlayback: connecting