Os recursos de panorâmica, inclinação e zoom nas câmeras finalmente podem ser controlados na Web.
As soluções de videoconferência em escala de sala implantam câmeras com recursos de panorâmica, inclinação e zoom (PTZ, na sigla em inglês) para que o software possa apontar a câmera para os participantes da reunião. A partir do Chrome 87, os recursos de panorâmica, inclinação e zoom em
câmeras estão disponíveis para sites que usam restrições de faixa de mídia em
MediaDevices.getUserMedia() e MediaStreamTrack.applyConstraints().
Como usar a API
Detecção de recursos
A detecção de recursos para hardware é diferente do que você provavelmente está acostumado.
A presença dos nomes de restrição "pan", "tilt" e "zoom" em
navigator.mediaDevices.getSupportedConstraints() informa que o navegador
é compatível com a API para controlar o PTZ da câmera, mas não se o hardware da câmera
é compatível. A partir do Chrome 87, o controle de PTZ da câmera é compatível com
computadores, enquanto o Android ainda oferece suporte apenas ao zoom.
const supports = navigator.mediaDevices.getSupportedConstraints();
if (supports.pan && supports.tilt && supports.zoom) {
// Browser supports camera PTZ.
}
Solicitar acesso à PTZ da câmera
Um site só pode controlar o PTZ da câmera se o usuário tiver concedido explicitamente a permissão de PTZ à câmera por meio de uma solicitação.
Para solicitar acesso à PTZ da câmera, chame navigator.mediaDevices.getUserMedia() com
as restrições de PTZ, conforme mostrado abaixo. Isso vai solicitar que o usuário conceda as permissões
de câmera normal e de câmera com PTZ.
A promessa retornada é resolvida com um objeto
MediaStream
usado para mostrar o stream de vídeo da câmera ao usuário. Se a câmera não for compatível com
PTZ, o usuário vai receber um comando de câmera normal.
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);
}
Uma permissão da câmera concedida anteriormente, especificamente uma sem acesso PTZ, não recebe acesso PTZ automaticamente se ele ficar disponível. Isso é verdade mesmo quando a câmera é compatível com PTZ. A permissão precisa ser solicitada novamente. Felizmente, é possível usar a API Permissions para consultar e monitorar o status da permissão de 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);
}
Para saber se um navegador baseado no Chromium é compatível com PTZ para uma câmera, acesse a
página interna about://media-internals e confira a coluna "Pan-Tilt-Zoom"
na guia "Video Capture". "pan tilt" e "zoom" significam que a câmera
é compatível com os controles UVC
"PanTilt (Absolute)" e "Zoom (Absolute)".
Os controles UVC "PanTilt (Relative)" e "Zoom (Relative)" não são compatíveis com
navegadores baseados no Chromium.
Controlar PTZ da câmera
Manipule os recursos e as configurações de PTZ da câmera usando o MediaStreamTrack de pré-lançamento do objeto stream recebido anteriormente.
MediaStreamTrack.getCapabilities() retorna um dicionário com os recursos
compatíveis e os intervalos ou valores permitidos. Da mesma forma,
MediaStreamTrack.getSettings() retorna as configurações atuais.
Os recursos e as configurações de panorâmica, inclinação e zoom só estarão disponíveis se forem compatíveis com a câmera e se o usuário tiver concedido permissão de PTZ à câmera.
Chame videoTrack.applyConstraints() com as restrições avançadas de PTZ adequadas para controlar a panorâmica, a inclinação e o zoom da câmera, conforme mostrado no exemplo.
A promessa retornada será resolvida se for bem-sucedida. Ele rejeita se:
- A câmera com permissão de PTZ não foi concedida.
- O hardware da câmera não é compatível com a restrição de PTZ.
- A página não fica visível para o usuário. Use a API Page Visibility para detectar mudanças na visibilidade da página.
// 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...
}
Também é possível configurar a panorâmica, a inclinação e o zoom da câmera chamando
navigator.mediaDevices.getUserMedia() com alguns valores de restrição ideais de PTZ
da câmera. Isso é útil quando os recursos de PTZ da câmera são conhecidos com antecedência. As restrições obrigatórias (mínimo, máximo, exato) não são permitidas aqui.
const stream = await navigator.mediaDevices.getUserMedia({
// Website asks to reset known camera pan.
video: { pan: 0, deviceId: { exact: "myCameraDeviceId" } }
});
Playground
Para testar a API, execute a demonstração.
Considerações sobre segurança
Os autores da especificação projetaram e implementaram essa API usando o núcleo, incluindo controle do usuário, transparência e ergonomia. A capacidade de usar essa API é controlada principalmente pelo mesmo modelo de permissão da API Media Capture and Streams. Em resposta a um comando do usuário, o site pode controlar o PTZ da câmera somente quando a página estiver visível para o usuário.
Compatibilidade com navegadores
API MediaStream
API Permissions
API Page Visibility
MediaDevices.getUserMedia()
MediaDevices.getSupportedConstraints()
MediaStreamTrack.applyConstraints()
MediaStreamTrack.getCapabilities()
MediaStreamTrack.getSettings()
Links úteis
- Explicação sobre PTZ
- Rascunho da especificação
- Repositório do GitHub
- Entrada do ChromeStatus
- Bug de rastreamento do Chrome
Agradecimentos
Este artigo foi revisado por Joe Medley e Thomas Steiner. Agradecemos a Rijubrata Bhaumik e Eero Häkkinen, da Intel, pelo trabalho na especificação e na implementação.