Schwenken, Neigen und Zoomen der Kamera steuern

Die Schwenk-, Neigungs- und Zoomfunktionen von Kameras können jetzt auch im Web gesteuert werden.

François Beaufort

Bei Videokonferenzlösungen für ganze Räume werden Kameras mit Schwenk-, Neigungs- und Zoomfunktionen (PTZ) eingesetzt, damit die Software die Kamera auf die Meetingteilnehmer richten kann. Ab Chrome 87 sind die Funktionen zum Schwenken, Neigen und Zoomen von Kameras für Websites verfügbar, die Einschränkungen für Medienspuren in MediaDevices.getUserMedia() und MediaStreamTrack.applyConstraints() verwenden.

API verwenden

Feature-Erkennung

Die Featureerkennung für Hardware unterscheidet sich von dem, was Sie wahrscheinlich gewohnt sind. Das Vorhandensein der Einschränkungsnamen "pan", "tilt" und "zoom" in navigator.mediaDevices.getSupportedConstraints() zeigt an, dass der Browser die API zur Steuerung der Schwenk-, Neige- und Zoomfunktionen der Kamera unterstützt, aber nicht, ob die Kamerahardware dies unterstützt. Ab Chrome 87 wird die PTZ-Steuerung der Kamera auf dem Desktop unterstützt, während Android weiterhin nur den Zoom unterstützt.

const supports = navigator.mediaDevices.getSupportedConstraints();
if (supports.pan && supports.tilt && supports.zoom) {
  // Browser supports camera PTZ.
}

PTZ-Zugriff auf die Kamera anfordern

Eine Website darf die Schwenk-, Neige- und Zoomfunktionen der Kamera nur steuern, wenn der Nutzer die entsprechende Berechtigung über eine Aufforderung explizit erteilt hat.

Wenn Sie PTZ-Zugriff auf die Kamera anfordern möchten, rufen Sie navigator.mediaDevices.getUserMedia() mit den PTZ-Einschränkungen auf, wie unten gezeigt. Der Nutzer wird dann aufgefordert, sowohl die Berechtigung für die normale Kamera als auch für die Kamera mit PTZ zu erteilen.

Nutzeraufforderung für PTZ-Kamera.

Das zurückgegebene Promise wird mit einem MediaStream-Objekt aufgelöst, das verwendet wird, um dem Nutzer den Videostream der Kamera anzuzeigen. Wenn die Kamera PTZ nicht unterstützt, wird dem Nutzer eine normale Kameraaufforderung angezeigt.

try {
  // User is prompted to grant both camera and PTZ access in a single call.
  // If camera doesn't support PTZ, it falls back to a regular camera prompt.
  const stream = await navigator.mediaDevices.getUserMedia({
    // Website asks to control camera PTZ as well without altering the
    // current pan, tilt, and zoom settings.
    video: { pan: true, tilt: true, zoom: true }
  });

  // Show camera video stream to user.
  document.querySelector("video").srcObject = stream;
} catch (error) {
  // User denies prompt or matching media is not available.
  console.log(error);
}

Eine zuvor erteilte Berechtigung zum Zugriff auf die Kamera, insbesondere eine ohne PTZ-Zugriff, erhält nicht automatisch PTZ-Zugriff, wenn dieser verfügbar wird. Das gilt auch dann, wenn die Kamera selbst PTZ unterstützt. Die Berechtigung muss noch einmal angefordert werden. Glücklicherweise können Sie die Permissions API verwenden, um den Status der PTZ-Berechtigung abzufragen und zu überwachen.

try {
  const panTiltZoomPermissionStatus = await navigator.permissions.query({
    name: "camera",
    panTiltZoom: true
  });

  if (panTiltZoomPermissionStatus.state == "granted") {
    // User has granted access to the website to control camera PTZ.
  }

  panTiltZoomPermissionStatus.addEventListener("change", () => {
    // User has changed PTZ permission status.
  });
} catch (error) {
  console.log(error);
}

Wenn du wissen möchtest, ob ein Chromium-basierter Browser PTZ für eine Kamera unterstützt, rufe die interne Seite about://media-internals auf und sieh dir auf dem Tab „Video Capture“ die Spalte „Pan-Tilt-Zoom“ an. „pan tilt“ und „zoom“ bedeuten, dass die Kamera die UVC-Steuerelemente „PanTilt (Absolute)“ und „Zoom (Absolute)“ unterstützt. Die UVC-Steuerelemente „Schwenken/Neigen (relativ)“ und „Zoomen (relativ)“ werden in Chromium-basierten Browsern nicht unterstützt.

Interne Seite zum Debuggen der Unterstützung von PTZ-Kameras.

PTZ-Kamera steuern

Sie können die PTZ-Funktionen und -Einstellungen der Kamera mithilfe der Vorschau MediaStreamTrack aus dem zuvor abgerufenen stream-Objekt ändern. MediaStreamTrack.getCapabilities() gibt ein Wörterbuch mit den unterstützten Funktionen und den Bereichen oder zulässigen Werten zurück. Entsprechend gibt MediaStreamTrack.getSettings() die aktuellen Einstellungen zurück.

Die Funktionen und Einstellungen zum Schwenken, Neigen und Zoomen sind nur verfügbar, wenn sie von der Kamera unterstützt werden und der Nutzer der Kamera die PTZ-Berechtigung erteilt hat.

PTZ-Kamera steuern.

Rufe videoTrack.applyConstraints() mit den entsprechenden erweiterten PTZ-Einschränkungen auf, um das Schwenken, Neigen und Zoomen der Kamera wie im Beispiel gezeigt zu steuern. Das zurückgegebene Promise wird aufgelöst, wenn der Vorgang erfolgreich ist. Die Anfrage wird abgelehnt, wenn:

• Die Kamera mit PTZ-Berechtigung ist nicht gewährt.
• Die Kamerahardware unterstützt die PTZ-Einschränkung nicht.
• Die Seite ist für den Nutzer nicht sichtbar. Verwenden Sie die Page Visibility API, um Änderungen der Seitensichtbarkeit zu erkennen.

// Get video track capabilities and settings.
const [videoTrack] = stream.getVideoTracks();
const capabilities = videoTrack.getCapabilities();
const settings = videoTrack.getSettings();

// Let the user control the camera pan motion if the camera supports it
// and PTZ access is granted.
if ("pan" in settings) {
  const input = document.querySelector("input[type=range]");
  input.min = capabilities.pan.min;
  input.max = capabilities.pan.max;
  input.step = capabilities.pan.step;
  input.value = settings.pan;

  input.addEventListener("input", async () => {
    await videoTrack.applyConstraints({ advanced: [{ pan: input.value }] });
  });
}

if ("tilt" in settings) {
  // similar for tilt...
}
if ("zoom" in settings) {
  // similar for zoom...
}

Es ist auch möglich, Schwenken, Neigen und Zoomen der Kamera zu konfigurieren, indem Sie navigator.mediaDevices.getUserMedia() mit einigen idealen Einschränkungswerten für Schwenken, Neigen und Zoomen der Kamera aufrufen. Das ist nützlich, wenn die PTZ-Funktionen der Kamera im Voraus bekannt sind. Beachten Sie, dass obligatorische Einschränkungen (min, max, exact) hier nicht zulässig sind.

const stream = await navigator.mediaDevices.getUserMedia({
  // Website asks to reset known camera pan.
  video: { pan: 0, deviceId: { exact: "myCameraDeviceId" } }
});

Spielplatz

Sie können die API ausprobieren, indem Sie die Demo ausführen.

Tipp: Wenn Sie keine Kamera haben, die PTZ unterstützt, können Sie Chrome mit dem Schalter --use-fake-device-for-media-stream ausführen, um eine solche Kamera auf Ihrem Computer zu simulieren. Viel Spaß!

Sicherheitsaspekte

Die Autoren der Spezifikation haben diese API unter Berücksichtigung der Kernprinzipien wie Nutzerkontrolle, Transparenz und Ergonomie entworfen und implementiert. Die Möglichkeit, diese API zu verwenden, wird hauptsächlich durch dasselbe Berechtigungsmodell wie die Media Capture and Streams API eingeschränkt. Als Reaktion auf eine Nutzeraufforderung darf die Website die Schwenk-, Neige- und Zoomfunktionen der Kamera nur steuern, wenn die Seite für den Nutzer sichtbar ist.

Browser-Kompatibilität

MediaStream API

Browser Support

• 55
• 12
• 15
• 11

Source

Permissions API

Browser Support

• 43
• 79
• 46
• 16

Source

Page Visibility API

Browser Support

• 33
• 12
• 18
• 7

Source

MediaDevices.getUserMedia()

Browser Support

• 53
• 12
• 36
• 11

Source

MediaDevices.getSupportedConstraints()

Browser Support

• 53
• 12
• 44
• 11

Source

MediaStreamTrack.applyConstraints()

Browser Support

• 59
• 12
• 43
• 11

Source

MediaStreamTrack.getCapabilities()

Browser Support

• 59
• 12
• 132
• 11

Source

MediaStreamTrack.getSettings()

Browser Support

• 59
• 12
• 50
• 11

Source

Nützliche Links

• PTZ-Erklärung
• Spezifikationsentwurf
• GitHub-Repository
• ChromeStatus-Eintrag
• Chrome-Tracking-Fehler

Danksagungen

Dieser Artikel wurde von Joe Medley und Thomas Steiner geprüft. Vielen Dank an Rijubrata Bhaumik und Eero Häkkinen von Intel für ihre Arbeit an der Spezifikation und der Implementierung.