Diese Seite wurde von der Cloud Translation API übersetzt.

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 den Raum werden Kameras mit Schwenk-, Neige- und Zoomfunktionen (PTZ) eingesetzt, damit die Software die Kamera auf die Teilnehmer der Videokonferenz richten kann. Ab Chrome 87 sind die Schwenk-, Neige- und Zoomfunktionen von Kameras für Websites verfügbar, die Medientrack-Einschränkungen in MediaDevices.getUserMedia() und MediaStreamTrack.applyConstraints() verwenden.

API verwenden

Funktionserkennung

Die Funktionsprüfung für Hardware unterscheidet sich wahrscheinlich von dem, was Sie gewohnt sind. Wenn die Namen der Einschränkungen "pan", "tilt" und "zoom" in navigator.mediaDevices.getSupportedConstraints() vorhanden sind, unterstützt der Browser die API zur Steuerung der PTZ-Kamera, aber nicht, ob die Kamerahardware dies unterstützt. Ab Chrome 87 wird die PTZ-Steuerung der Kamera auf dem Computer unterstützt, während unter Android weiterhin nur der Zoom unterstützt wird.

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

PTZ-Zugriff auf Kamera anfordern

Eine Website darf die PTZ-Funktion einer Kamera nur dann steuern, wenn der Nutzer der Kamera über eine Aufforderung ausdrücklich die PTZ-Berechtigung erteilt hat.

Wenn Sie den PTZ-Zugriff auf die Kamera anfordern möchten, rufen Sie navigator.mediaDevices.getUserMedia() mit den PTZ-Einschränkungen auf, wie unten gezeigt. Daraufhin wird der Nutzer aufgefordert, sowohl der normalen Kamera als auch der Kamera mit PTZ-Funktion Berechtigungen zu erteilen.

Screenshot einer PTZ-Aufforderung für eine Kamera in Chrome für macOS — Aufforderung für PTZ-Kamera

Das zurückgegebene Promise wird mit einem MediaStream-Objekt aufgelöst, mit dem der Kameravideostream für den Nutzer angezeigt wird. Wenn die Kamera keine PTZ-Funktion 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 Kameraberechtigung, insbesondere eine ohne PTZ-Zugriff, erhält nicht automatisch PTZ-Zugriff, wenn dieser verfügbar wird. Das gilt auch, wenn die Kamera selbst PTZ unterstützt. Die Berechtigung muss dann noch einmal angefordert werden. Mit der Permissions API können Sie den Status der PTZ-Berechtigung abfragen und ü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 Sie wissen möchten, ob ein Chromium-basierter Browser PTZ für eine Kamera unterstützt, rufen Sie die interne Seite about://media-internals auf und sehen Sie sich die Spalte „Schwenken-Neigen-Zoomen“ auf dem Tab „Videoaufnahme“ an. „Schwenken-Neigen“ und „Zoomen“ bedeuten, dass die Kamera die UVC-Steuerelemente „Schwenken-Neigen (absolut)“ und „Zoomen (absolut)“ unterstützt. Die UVC-Steuerelemente „Schwenken/Neigen (relativ)“ und „Zoomen (relativ)“ werden in Chromium-basierten Browsern nicht unterstützt.

Screenshot der internen Seite in ChromeOS zur Fehlerbehebung bei der PTZ-Kameraunterstützung — Interne Seite zum Debuggen der PTZ-Kameraunterstützung.

PTZ-Kamera steuern

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

Die Funktionen und Einstellungen für 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.

Kamera-PTZ steuern

Rufe videoTrack.applyConstraints() mit den entsprechenden erweiterten PTZ-Einschränkungen auf, um die Kamera zu schwenken, zu neigen und zu zoomen, wie im Beispiel unten gezeigt. Das zurückgegebene Versprechen wird bei Erfolg erfüllt. Andernfalls wird die Anfrage abgelehnt, wenn folgende Bedingungen erfüllt sind:

der Kamera mit PTZ-Berechtigung nicht gewährt.
Die Kamerahardware unterstützt die PTZ-Einschränkung nicht.
die Seite für den Nutzer nicht sichtbar ist. Verwenden Sie die Page Visibility API, um Änderungen an der Sichtbarkeit von Seiten 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...
}

Sie können auch die Schwenk-, Neige- und Zoomfunktionen der Kamera konfigurieren, indem Sie navigator.mediaDevices.getUserMedia() mit einigen Werten für die PTZ-Idealeinschränkungen der Kamera aufrufen. Das ist praktisch, wenn die PTZ-Funktionen der Kamera im Voraus bekannt sind. Erforderliche Einschränkungen (min, max, exact) sind hier nicht zulässig.

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

Spielplatz

Du kannst die API ausprobieren, indem du die Demo auf Glitch ausführst. Sehen Sie sich den Quellcode an.

Sicherheitsaspekte

Die Autoren der Spezifikation haben diese API mit den Kernelementen wie Nutzerkontrolle, Transparenz und Ergonomie entworfen und implementiert. Die Nutzung dieser API ist hauptsächlich durch dasselbe Berechtigungsmodell wie bei der Media Capture and Streams API eingeschränkt. Die Website darf die PTZ-Funktion der Kamera nur dann als Reaktion auf einen Nutzerhinweis steuern, wenn die Seite für den Nutzer sichtbar ist.

Browserkompatibilität

MediaStream API

Unterstützte Browser

Quelle

Berechtigungen-API

Unterstützte Browser

Quelle

Page Visibility API

Unterstützte Browser

Quelle

`MediaDevices.getUserMedia()`

Unterstützte Browser

Quelle

`MediaDevices.getSupportedConstraints()`

Unterstützte Browser

Quelle

`MediaStreamTrack.applyConstraints()`

Unterstützte Browser

Quelle

`MediaStreamTrack.getCapabilities()`

Unterstützte Browser

Quelle

`MediaStreamTrack.getSettings()`

Unterstützte Browser

Quelle

Nützliche Links

Danksagungen

Dieser Artikel wurde von Joe Medley und Thomas Steiner überprüft. Vielen Dank an Rijubrata Bhaumik und Eero Häkkinen von Intel für ihre Arbeit an der Spezifikation und Implementierung. Hero-Image von Christina @ wocintechchat.com auf Unsplash.