Controlla panoramica, inclinazione e zoom della videocamera

Le funzionalità di panoramica, inclinazione e zoom delle videocamere sono finalmente controllabili sul web.

François Beaufort
François Beaufort

Le soluzioni per videoconferenze su scala stanza implementano videocamere con panoramica, inclinazione e zoom (PTZ) per consentire al software di puntare la videocamera verso la riunione. partecipanti. A partire da Chrome 87, le funzionalità di panoramica, inclinazione e zoom attive le videocamere sono disponibili per i siti web che utilizzano vincoli di tracce multimediali MediaDevices.getUserMedia() e MediaStreamTrack.applyConstraints().

Utilizzo dell'API

Rilevamento delle caratteristiche

Il rilevamento delle funzionalità per l'hardware è diverso da quello che probabilmente conosci. La presenza dei nomi dei vincoli "pan", "tilt" e "zoom" in navigator.mediaDevices.getSupportedConstraints() indica che il browser supporta l'API per controllare la PTZ della videocamera, ma non se l'hardware della videocamera la supporta. A partire da Chrome 87, il controllo PTZ della videocamera è supportato su computer desktop, mentre Android supporta ancora solo lo zoom.

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

Richiedi accesso PTZ alla videocamera

Un sito web può controllare la visualizzazione PTZ della videocamera solo se l'utente ha esplicitamente ha concesso alla videocamera l'autorizzazione PTZ tramite un messaggio.

Per richiedere l'accesso PTZ alla videocamera, chiama navigator.mediaDevices.getUserMedia() con i vincoli PTZ come mostrato di seguito. In questo modo, all'utente verrà chiesto di concedere videocamera e videocamera standard con autorizzazioni PTZ.

Screenshot del messaggio dell'utente PTZ di una fotocamera in Chrome per macOS.
Richiesta utente PTZ videocamera.

La promessa restituita verrà risolta con un oggetto MediaStream utilizzato per mostrare stream video della videocamera all'utente. Se la videocamera non supporta la funzione PTZ, l'utente riceverà un normale prompt della fotocamera.

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);
}

Un'autorizzazione di accesso alla videocamera concessa in precedenza, in particolare una senza accesso PTZ, non ottiene automaticamente l'accesso PTZ se diventa disponibile. È vero anche se la videocamera supporta la funzione PTZ. L'autorizzazione deve essere richiesta di nuovo. Fortunatamente, puoi utilizzare l'API Permissions per eseguire query e monitorare stato dell'autorizzazione PTZ.

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);
}

Per sapere se un browser basato su Chromium supporta la funzione PTZ per una videocamera, vai alle pagina about://media-internals interna e guarda la panoramica "Panoramica, inclinazione e zoom" colonna nella sezione "Acquisizione video" tab; "inclinazione panoramica" e "zoom" indicano rispettivamente che la videocamera supporta la finestra "PanTilt (Assoluto)" e "Zoom (assoluto)" Controlli VUV. Il ruolo "PanTilt (relative)" e "Zoom (relativo)" I controlli UVC non sono supportati nei browser basati su Chromium.

Screenshot della pagina interna in ChromeOS per eseguire il debug del supporto delle videocamere PTZ.
Pagina interna per eseguire il debug del supporto delle videocamere PTZ.

Controlla PTZ videocamera

Manipolare le funzionalità e le impostazioni PTZ della videocamera utilizzando l'anteprima MediaStreamTrack dall'oggetto stream ottenuto in precedenza. MediaStreamTrack.getCapabilities() restituisce un dizionario con e gli intervalli o i valori consentiti. Di conseguenza, MediaStreamTrack.getSettings() restituisce le impostazioni attuali.

Le funzionalità e le impostazioni di panoramica, inclinazione e zoom sono disponibili solo se supportate da la videocamera e l'utente ha concesso l'autorizzazione PTZ alla videocamera.

Controllo PTZ della videocamera.

Chiama il numero videoTrack.applyConstraints() con il PTZ avanzato appropriato vincoli per controllare panoramica, inclinazione e zoom della videocamera, come mostrato nell'esempio riportato di seguito. In caso di esito positivo, la promessa restituita verrà risolta. In caso contrario, rifiuterà in uno dei seguenti modi:

  • la videocamera con autorizzazione PTZ non è stata concessa.
  • l'hardware della videocamera non supporta il vincolo PTZ.
  • la pagina non è visibile all'utente. Usare l'API Page Visibility per rilevare modifiche alla visibilità delle pagine.
// 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...
}

È anche possibile configurare panoramica, inclinazione e zoom della videocamera chiamando navigator.mediaDevices.getUserMedia() con un vincolo ideale PTZ della videocamera e i relativi valori. Ciò è utile quando le funzionalità PTZ delle videocamere sono note in anticipo. Nota che i vincoli obbligatori (min, max, exact) non sono consentiti qui.

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

Parco giochi

Puoi giocare con l'API eseguendo la demo su Glitch. Assicurati di dare un'occhiata il codice sorgente.

Considerazioni sulla sicurezza

Gli autori delle specifiche hanno progettato e implementato questa API utilizzando tra cui controllo dell'utente, trasparenza ed ergonomia. Possibilità di utilizzare API è gestita principalmente dallo stesso modello di autorizzazione di Media Capture e API Streams. In risposta a un prompt dell'utente, il sito web può controllare videocamera PTZ solo quando la pagina è visibile all'utente.

Compatibilità del browser

API MediaStream

Supporto dei browser

  • Chrome: 55.
  • Edge: 12.
  • Firefox: 15.
  • Safari: 11.

Origine

API autorizzazioni

Supporto dei browser

  • Chrome: 43.
  • Edge: 79.
  • Firefox: 46.
  • Safari: 16.

Origine

API Page Visibility

Supporto dei browser

  • Chrome: 33.
  • Edge: 12.
  • Firefox: 18.
  • Safari: 7.

Origine

MediaDevices.getUserMedia()

Supporto dei browser

  • Chrome: 53.
  • Edge: 12.
  • Firefox: 36.
  • Safari: 11.

Origine

MediaDevices.getSupportedConstraints()

Supporto dei browser

  • Chrome: 53.
  • Edge: 12.
  • Firefox: 44.
  • Safari: 11.

Origine

MediaStreamTrack.applyConstraints()

Supporto dei browser

  • Chrome: 59.
  • Edge: 12.
  • Firefox: 43.
  • Safari: 11.

Origine

MediaStreamTrack.getCapabilities()

Supporto dei browser

  • Chrome: 59.
  • Edge: 12.
  • Firefox: non supportato.
  • Safari: 11.

Origine

MediaStreamTrack.getSettings()

Supporto dei browser

  • Chrome: 59.
  • Edge: 12.
  • Firefox: 50.
  • Safari: 11.

Origine

Link utili

Ringraziamenti

Questo articolo è stato esaminato da Joe Medley e Thomas Steiner. Grazie a Rijubrata Bhaumik ed Eero Häkkinen di Intel per il loro lavoro sulla specifiche e l'implementazione. Immagine hero di Christina @ wocintechchat.com su Unsplash.