PictureInPictureWindow.height — Eigenschaft · JavaScript-Referenz

Signatur

PictureInPictureWindow.height

Beschreibung

Die schreibgeschützte Eigenschaft height der Schnittstelle PictureInPictureWindow liefert die aktuelle Höhe des Bild-in-Bild-Fensters (Picture-in-Picture, PiP) in CSS-Pixeln. Ein PictureInPictureWindow-Objekt bekommst du, sobald das Promise von HTMLVideoElement.requestPictureInPicture() erfüllt ist, oder über die Eigenschaft pictureInPictureWindow des Ereignisses enterpictureinpicture.

Nützlich ist die Eigenschaft vor allem dann, wenn du die Videoqualität an die tatsächliche Fenstergröße anpassen willst. Beim adaptiven Streaming (HLS/DASH) kannst du zum Beispiel für ein kleines PiP-Fenster eine niedrigere Auflösung laden und so Bandbreite sparen. Zusammen mit width ergibt sich das Seitenverhältnis des Fensters.

Zieht der Nutzer das Fenster größer oder kleiner, ändert sich der Wert. Über jede Größenänderung informiert das Ereignis resize am PictureInPictureWindow-Objekt. Wird das Fenster geschlossen, liefert height laut Spezifikation 0.

Rückgabewert

Typ

number

Beschreibung

Ganzzahlige Höhe des PiP-Fensters in CSS-Pixeln. 0, wenn das Fenster geschlossen ist.

Beispiele

Größe nach dem Öffnen des PiP-Fensters auslesen

const video = document.querySelector('video');
const button = document.querySelector('#pip-button');

button.addEventListener('click', async () => {
  try {
    // Muss als Reaktion auf eine Nutzeraktion aufgerufen werden
    const pipWindow = await video.requestPictureInPicture();
    console.log(`PiP-Fenster: ${pipWindow.width} × ${pipWindow.height} px`);
  } catch (err) {
    console.error('Bild-in-Bild nicht möglich:', err.message);
  }
});

PiP-Fenster: 400 × 225 px

Auf Größenänderungen reagieren und Qualität anpassen

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

const chooseQuality = (height) => {
  if (height <= 240) return '240p';
  if (height <= 480) return '480p';
  return '720p';
};

video.addEventListener('enterpictureinpicture', (event) => {
  const pipWindow = event.pictureInPictureWindow;
  console.log('Startqualität:', chooseQuality(pipWindow.height));

  const onResize = () => {
    console.log(`Neue Höhe: ${pipWindow.height} px → ${chooseQuality(pipWindow.height)}`);
  };
  pipWindow.addEventListener('resize', onResize);

  // Listener beim Verlassen des PiP-Modus wieder entfernen
  video.addEventListener('leavepictureinpicture', () => {
    pipWindow.removeEventListener('resize', onResize);
  }, { once: true });
});

Startqualität: 240p Neue Höhe: 360 px → 480p

Funktionserkennung vor dem Zugriff

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

const getPipHeight = () => {
  if (!('pictureInPictureEnabled' in document) || !document.pictureInPictureEnabled) {
    return null; // API nicht verfügbar oder deaktiviert
  }
  // Nur wenn genau dieses Video gerade im PiP-Modus ist
  return document.pictureInPictureElement === video ? null : null;
};

console.log(document.pictureInPictureEnabled ? 'PiP verfügbar' : 'PiP nicht verfügbar');

PiP verfügbar

// Wichtig · Fallstricke

Schreibgeschützt: Wenn du height zuweist, passiert nichts. Die Fenstergröße lässt sich per Skript nicht ändern, das bestimmen Nutzer und Betriebssystem.
Nach dem Schließen: Sobald der PiP-Modus beendet ist (leavepictureinpicture), gibt die Eigenschaft 0 zurück. Lies den Wert deshalb nicht nachträglich über eine alte Referenz aus.
Browser-Unterstützung: Die Picture-in-Picture-API mit PictureInPictureWindow gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox bietet zwar eine eigene PiP-Funktion in der Oberfläche, stellt aber keine JavaScript-API bereit. Safari nutzt stattdessen die herstellereigene webkitSetPresentationMode(). Prüfe die Unterstützung daher immer vorher, z. B. mit document.pictureInPictureEnabled.
Performance: Das Ereignis resize kann beim Ziehen am Fensterrand sehr oft feuern. Aufwendige Reaktionen wie ein Qualitätswechsel im Stream solltest du mit Debouncing drosseln.
Nicht verwechseln mit der Document Picture-in-Picture API (documentPictureInPicture): Dort ist das PiP-Fenster ein echtes Window-Objekt, und du fragst die Höhe über innerHeight ab.

Siehe auch

PerformanceScriptTiming.windowAttribution PictureInPictureWindow.width HTMLInputElement.height PointerEvent.height DOMRectReadOnly.height