Controlla panoramica, inclinazione e zoom della videocamera

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

Le soluzioni di videoconferenza su scala locale implementano le videocamere con funzionalità di panoramica, inclinazione e zoom (PTZ) in modo che il software possa puntare la videocamera verso i partecipanti alla riunione. A partire da Chrome 87, le funzionalità di panoramica, inclinazione e zoom delle videocamere sono disponibili per i siti web che utilizzano vincoli relativi alla traccia multimediale in MediaDevices.getUserMedia() e MediaStreamTrack.applyConstraints().

Utilizzo dell'API

Rilevamento delle funzionalità

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 della PTZ della fotocamera è supportato sui computer, 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 il PTZ della videocamera solo se l'utente ha concesso esplicitamente l'autorizzazione alla videocamera con PTZ tramite un prompt.

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

La promessa restituita si risolverà con un oggetto MediaStream utilizzato per mostrare il video stream della videocamera all'utente. Se la videocamera non supporta la modalità PTZ, l'utente riceverà una normale richiesta.

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 persona senza accesso PTZ, non consente di ottenere automaticamente l'accesso a quest'ultima se diventa disponibile. anche quando la videocamera stessa supporta la tecnologia PTZ. L'autorizzazione deve essere richiesta di nuovo. Fortunatamente, puoi utilizzare l'API Permissions per eseguire query e monitorare lo 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 modalità PTZ per una videocamera, vai alla pagina about://media-internals interna e controlla la colonna "Panoramica-inclinazione-Zoom" nella scheda "Acquisizione video". "Panoramica" e "zoom" indicano rispettivamente che la videocamera supporta i controlli Panoramica panoramica (assoluta)" e "Zoom (assoluto)" UVC. I controlli UVC "Panoramica (relativa)" e "Zoom (relativo)" non sono supportati nei browser basati su Chromium.

Controlla PTZ della videocamera

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

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

Richiama videoTrack.applyConstraints() con i vincoli avanzati PTZ appropriati per controllare la panoramica, l'inclinazione e lo zoom della videocamera, come mostrato nell'esempio di seguito. La promessa restituita verrà risolta in caso di esito positivo. In caso contrario, la risposta verrà rifiutata se:

• la videocamera con autorizzazione PTZ non è stata concessa.
• l'hardware della videocamera non supporta il vincolo PTZ.
• la pagina non è visibile all'utente. Utilizza l'API Page Visibilità per rilevare le modifiche di 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 alcuni valori di vincolo di PTZ ideali della videocamera. Questo è particolarmente utile quando le funzionalità PTZ della fotocamera sono già note. Tieni presente che i vincoli obbligatori (min, max, esatti) 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 controllare il codice sorgente.

Considerazioni sulla sicurezza

Gli autori delle specifiche hanno progettato e implementato questa API utilizzando le funzionalità principali, tra cui controllo dell'utente, trasparenza ed ergonomia. La possibilità di utilizzare questa API è controllata principalmente dallo stesso modello di autorizzazione dell'API Media Capture e Streams. In risposta a una richiesta dell'utente, il sito web può controllare la PTZ della videocamera solo quando la pagina è visibile all'utente.

Compatibilità del browser

API MediaStream

API Permissions

API Page Visibilità

MediaDevices.getUserMedia()

MediaDevices.getSupportedConstraints()

MediaStreamTrack.applyConstraints()

MediaStreamTrack.getCapabilities()

MediaStreamTrack.getSettings()

Link utili

• Spiegazione PTZ
• Bozza della specifica
• Repository GitHub
• Voce ChromeStatus
• Bug di monitoraggio di Chrome

Ringraziamenti

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