# Câmera no navegador: o que o getUserMedia entrega à captura Guia · UNIFOKAL · 17 de outubro de 2026 · 6 min de leitura · Produto e integração O getUserMedia abre a câmera numa página web, mas só em contexto seguro, com permissão e com restrições que o navegador trata como preferência. Os erros que o padrão define e o que a captura de documento faz além dele. Para fotografar documento e rosto numa página web, sem aplicativo instalado, o caminho é a API getUserMedia, definida pelo padrão Media Capture and Streams do W3C. Ela pede a câmera ao navegador e devolve um fluxo de vídeo. A resposta curta: o getUserMedia só existe em contexto seguro, depende de permissão da pessoa e trata a maior parte das restrições como preferência, não como garantia; ele entrega quadros de vídeo, e todo o resto da captura de documento, do enquadramento à nitidez, é trabalho da sua página. Pedir a câmera traseira com valor solto é um pedido; pedir com `exact` é uma exigência que pode falhar. **Em resumo** - A interface é marcada `[SecureContext]` no padrão: em página sem HTTPS, ela não existe. - Valor solto ou `ideal` é preferência; `exact`, `min` e `max` são exigências que podem gerar `OverconstrainedError`. - O padrão define erros distintos para permissão negada, câmera inexistente, câmera ocupada e restrição impossível. - Ele entrega vídeo; enquadrar, focar e escolher o melhor quadro do documento é trabalho de quem captura. ## O que o padrão diz e em que estágio ele está O Media Capture and Streams é mantido pelo grupo de trabalho de WebRTC do W3C. A versão lida para este texto é o "W3C Candidate Recommendation Draft" de 9 de outubro de 2025, e o próprio documento avisa que ainda não está completo. O método aparece assim na definição de interface: `[SecureContext] undefined getUserMedia(MediaStreamConstraints constraints, ...)`. O atributo `[SecureContext]` significa que, numa página servida sem HTTPS, o método não está disponível, salvo nos contextos que o navegador trata como seguros, como o endereço local de desenvolvimento. ## Restrição é pedido, não ordem A escolha da câmera e da resolução passa pelas restrições. O padrão define que o navegador "MUST attempt to apply, individually, any 'ideal' constraints or a constraint given as a bare value for the property", e satisfaz o maior número que conseguir. O valor solto, como `facingMode: "environment"`, é tratado como ideal: se o aparelho não tiver câmera traseira, o navegador entrega outra. Já `exact`, `min` e `max` são obrigatórios, e quando nenhuma câmera os atende a promessa é rejeitada com `OverconstrainedError`. O valor `environment` está definido no padrão como "The source is facing away from the user (viewing the environment)", e `user` como "The source is facing toward the user (a self-view camera)". Para documento, a traseira; para selfie, a frontal. Na prática, `{ facingMode: "environment" }` pede a traseira e aceita outra; `{ facingMode: { exact: "environment" } }` exige a traseira e falha onde ela não existe. O padrão recomenda o primeiro jeito na maior parte dos casos: os autores de aplicação "are strongly encouraged to use required constraints sparingly", porque cada exigência tira do navegador a margem de escolher a melhor câmera. O exemplo do próprio padrão mostra a combinação: "width: {min: 640, ideal: 1280}, height: {min: 480, ideal: 720}", um piso que precisa ser atendido e um alvo que o navegador tenta alcançar. A resolução que de fato chegou é lida depois, no `getSettings()` da trilha de vídeo, e não deve ser presumida. ## Os erros que o padrão define, e o que fazer com cada um **erros do getUserMedia definidos no Media Capture and Streams e a resposta da página de captura (resposta: leitura da casa)** | Erro | Quando o padrão o lança | O que a página faz | |---|---|---| | `NotAllowedError` | Permissão negada pela pessoa ou pela política da página | Explicar por que a câmera é pedida e como liberar; oferecer outro canal | | `NotFoundError` | Nenhuma câmera disponível no aparelho | Oferecer continuar em outro aparelho, como o celular | | `NotReadableError` | Falha de hardware ou trava do sistema, como outro programa usando a câmera | Pedir para fechar o outro programa e tentar de novo | | `OverconstrainedError` | Restrição obrigatória que nenhuma câmera atende | Repetir o pedido sem `exact`, com a restrição como ideal | O padrão ainda prevê o `AbortError` para falha de acesso por outros motivos. A regra de produto que sai da tabela: cada erro tem uma mensagem própria. Tratar todos como "câmera indisponível" deixa a pessoa sem saber o que fazer. ## A permissão também depende da sua página Antes da pessoa, quem decide é a página. A seção 14 do padrão define a câmera como um recurso controlado por política, com lista padrão de permissão "self", e diz que a política de permissões do documento "determines whether any content in that document is allowed to use getUserMedia". Um cabeçalho `Permissions-Policy` que negue a câmera faz o pedido falhar mesmo com a pessoa disposta a aceitar, e um iframe de outra origem só usa a câmera se a página que o embute delegar o recurso a ele. Em página com widget embutido, a política da página do integrador vale para o widget. Na UNIFOKAL, a [documentação do widget](https://docs.unifokal.com/widget) lista o que a página precisa: ser servida por HTTPS, não negar a câmera no `Permissions-Policy` e ter uma `Content-Security-Policy` que permita o pacote do widget e o detector de rosto. ## O que a captura de documento faz além da API O getUserMedia entrega quadros de vídeo. A foto de documento que serve para leitura e para conferência é outra coisa, e o trabalho para chegar nela fica com quem constrói a captura. A lista é a leitura da casa, a partir do que a leitura de documento precisa: 1. **Enquadrar.** Guiar a pessoa para o documento ocupar o quadro, sem cortar as bordas, porque a borda é o que mostra que o documento está inteiro. 2. **Escolher o quadro.** Avaliar vários quadros e ficar com o mais nítido, em vez de fotografar no clique. 3. **Evitar reflexo.** Documento plastificado reflete luz; pedir para inclinar ou mudar de posição quando o brilho apaga parte do texto. 4. **Comprimir com cuidado.** A imagem final passa por compressão, e compressão demais apaga detalhe de segurança; o efeito está em [compressão JPEG e perícia de documento](https://unifokal.com/blog/compressao-jpeg-e-pericia-de-documento). > **Atenção** > > O padrão observa que `getCapabilities()` "gives likely persistent, cross-origin information about the underlying device" e por isso "adds to the fingerprint surface of the device". Consultar as capacidades da câmera para escolher a melhor é legítimo; guardar essas capacidades como identificador do aparelho é outro tratamento de dado, com outra base legal, como explica [sinais de dispositivo sem SDK](https://unifokal.com/blog/sinais-de-dispositivo-sem-sdk). Na UNIFOKAL, o [OCR do documento](https://unifokal.com/modulos/cpf-ocr) lê a foto que a captura entrega. Quanto melhor a captura, menos a leitura precisa adivinhar. ## Fontes citadas - W3C, Media Capture and Streams, W3C Candidate Recommendation Draft de 9 de outubro de 2025, seções de getUserMedia, restrições, VideoFacingModeEnum, erros e integração com a política de permissões (seção 14), em [w3.org](https://www.w3.org/TR/mediacapture-streams/) - W3C, Media Capture and Streams, rascunho do editor, em [w3c.github.io](https://w3c.github.io/mediacapture-main/)