Signatur
Beschreibung
Die schreibgeschützte Eigenschaft width eines PictureInPictureWindow-Objekts gibt die aktuelle Breite des schwebenden Bild-im-Bild-Fensters (Picture-in-Picture, kurz PiP) als ganze Zahl in CSS-Pixeln zurück. Das Objekt bekommt man als Auflösungswert des Promise von HTMLVideoElement.requestPictureInPicture() oder über die Eigenschaft pictureInPictureWindow des Events enterpictureinpicture.
Praktisch ist die Eigenschaft vor allem dann, wenn die Qualität des Videos an die tatsächliche Fenstergröße angepasst werden soll. Beispiel: Bei adaptivem Streaming (HLS/DASH) reicht für ein kleines PiP-Fenster eine niedrigere Auflösung, was Bandbreite spart. Zusammen mit height und dem Event resize lässt sich jede Größenänderung durch den Nutzer verfolgen.
Die Breite kann man nur lesen. Wie groß das Fenster ist, bestimmen Browser und Nutzer. Sobald das Fenster geschlossen wird (Event leavepictureinpicture), liefern width und height den Wert 0.
Rückgabewert
0.Beispiele
Breite direkt nach dem Öffnen auslesen
const video = document.querySelector('video');
const button = document.querySelector('#pip-button');
button.addEventListener('click', async () => {
try {
// Muss durch eine Nutzeraktion ausgelöst werden
const pipWindow = await video.requestPictureInPicture();
console.log(`PiP-Fenster: ${pipWindow.width} × ${pipWindow.height} px`);
} catch (err) {
console.error('Bild-im-Bild fehlgeschlagen:', err.message);
}
});Videoqualität an die Fenstergröße anpassen
const video = document.querySelector('video');
// Wählt eine passende Qualitätsstufe anhand der Breite
const pickQuality = (width) => {
if (width <= 320) return '240p';
if (width <= 640) return '480p';
return '720p';
};
const onResize = (event) => {
const { width } = event.target;
console.log(`Neue Breite: ${width}px → Qualität ${pickQuality(width)}`);
};
video.addEventListener('enterpictureinpicture', (event) => {
const pipWindow = event.pictureInPictureWindow;
console.log('Startqualität:', pickQuality(pipWindow.width));
pipWindow.addEventListener('resize', onResize);
// Beim Verlassen den Listener wieder entfernen
video.addEventListener('leavepictureinpicture', () => {
pipWindow.removeEventListener('resize', onResize);
console.log('Breite nach dem Schließen:', pipWindow.width);
}, { once: true });
});Vorher prüfen, ob die API verfügbar ist
const video = document.querySelector('video');
const supportsPiP = 'pictureInPictureEnabled' in document
&& document.pictureInPictureEnabled
&& !video.disablePictureInPicture;
if (!supportsPiP) {
console.log('Bild-im-Bild wird nicht unterstützt.');
} else if (document.pictureInPictureElement) {
// Es ist bereits ein PiP-Fenster offen
console.log('Es ist bereits ein PiP-Fenster aktiv.');
}// Wichtig · Fallstricke
- Nur lesbar: Wird
widthein Wert zugewiesen, hat das keine Wirkung. Die Fenstergröße lässt sich per Skript nicht ändern. - Wert 0 nach dem Schließen: Eine gespeicherte Referenz auf das
PictureInPictureWindowliefert nachleavepictureinpicturedie Breite0. Den Wert also nicht zwischenspeichern, sondern bei Bedarf neu auslesen. - Häufige Resize-Events: Beim Ziehen am Fensterrand wird
resizesehr oft ausgelöst. Aufwendige Vorgänge wie ein Qualitätswechsel sollten deshalb gedrosselt oder verzögert werden (Throttling/Debouncing). - Browser-Unterstützung: Unterstützt in Chromium-Browsern (Chrome, Edge, Opera) und in Safari. Firefox bietet zwar eine eigene Bild-im-Bild-Funktion in der Oberfläche an, aber keine API dafür. Vorher mit
document.pictureInPictureEnabledprüfen. Die API funktioniert nur in einem sicheren Kontext (HTTPS), und das Öffnen erfordert eine Nutzeraktion. - Nicht zu verwechseln mit der Document Picture-in-Picture API (
documentPictureInPicture). Diese liefert ein vollständigesWindow-Objekt mitinnerWidth.