Apresentação do elemento HTML <usermedia>

Mari Viana

Minh Le

Publicado em: 29 de junho de 2026

Após o lançamento do <geolocation> elemento no Chrome 144, o próximo controle funcional no conjunto de elementos de capacidade é o elemento HTML <usermedia>. Disponível no Chrome 151, esse elemento marca a próxima fase da transição de solicitações de permissão genéricas para controles direcionados e funcionais para acessar streams de câmera e microfone. Ao abandonar os prompts acionados por script em favor de uma experiência declarativa e ativada pelo usuário, <usermedia> reduz o código boilerplate, melhora a segurança e oferece um caminho de recuperação contínuo para usuários que negaram o acesso anteriormente, resolvendo o problema de permissão de longa data.

Do gerenciamento de permissões ao controle de capacidade

O elemento <usermedia> é o próximo controle especializado a ser lançado no conjunto de elementos de capacidade, após a introdução bem-sucedida do <geolocation>. Essa transição da proposta original e genérica <permission> , que faz parte da iniciativa PEPC, permite que o navegador processe as complexidades e comportamentos exclusivos de diferentes recursos de hardware de maneira mais eficaz. Embora a proposta inicial tenha se concentrado principalmente no gerenciamento de estados de permissão, como permitir versus negar, os elementos de capacidade funcionam como mediadores de dados.

O elemento <geolocation> fornece um objeto de local ao seu site, e <usermedia> gerencia todo o fluxo de acesso à câmera e ao microfone. Ele captura a intenção do usuário, gerencia o prompt do navegador e entrega o objeto MediaStream ao aplicativo. Essa mudança elimina a necessidade de chamadas getUserMedia() separadas, simplifica a implementação e garante que o navegador tenha um sinal confiável da intenção do usuário.

Validação do conceito

Os dados reais do teste de origem inicial demonstraram que os controles de permissão no contexto e iniciados pelo usuário melhoram significativamente as taxas de sucesso do usuário.

• A Cisco observou que os usuários que inicialmente negaram permissões tinham apenas 10% de probabilidade de conceder permissões usando prompts legados, mas essa taxa aumentou para mais de 65% com o novo elemento.
• O Zoom relatou uma diminuição de 46,9% nos erros de captura de câmera ou microfone, como bloqueadores no nível do sistema, usando o elemento para orientar os usuários na recuperação.
• O Google Meet observou uma diminuição de 17% no feedback de "microfone não funcionando" e um aumento de 131% na recuperação de permissão bem-sucedida para usuários que inicialmente negaram o acesso.

Por que usar o <usermedia> elemento?

Com base nos padrões estabelecidos por <geolocation>, o <usermedia> elemento aborda os principais desafios de solicitar recursos avançados. As solicitações de mídia dependem de chamadas JavaScript imperativas que geralmente acionam prompts fora do contexto. Se você bloquear seu site por engano, reverter essa decisão exigirá navegar pelas configurações do navegador, um "buraco de permissão" que geralmente leva a recursos abandonados.

O elemento <usermedia> resolve esses problemas fornecendo o seguinte:

• Intenção e tempo claros:como o prompt só aparece depois de um toque físico em um elemento controlado pelo navegador, ele fornece um sinal confiável de intenção. Isso permite que o navegador ignore blocos silenciosos automatizados que geralmente fazem com que as solicitações acionadas por script típicas falhem.
• Recuperação simplificada:se o acesso foi negado anteriormente, tocar no elemento aciona um fluxo de recuperação especializado que permite reativar a câmera ou o microfone instantaneamente na página, sem navegar pelas configurações do navegador complexas.
• Acesso direto ao stream:como mediador de dados, o elemento expõe o stream de mídia diretamente. Isso reduz o código boilerplate necessário para gerenciar callbacks e estados de erro no aplicativo.

Implementação

A integração do elemento exige muito menos código clichê do que a API JavaScript legada. Seguindo o padrão declarativo estabelecido pelo <geolocation> elemento, você pode adicionar a <usermedia> tag ao HTML e configurar os requisitos de hardware com o setConstraints() método.

<usermedia id="media-ctrl">
  <button>Enable camera and microphone</button>
</usermedia>

const el = document.getElementById('media-ctrl');

// Specify hardware preferences before user interaction:
el.setConstraints({
    video: { width: 1280, height: 720 },
    audio: { echoCancellation: true }
});

// Handle successful stream acquisition:
el.addEventListener('stream', () => {
  videoPreview.srcObject = el.stream;
});

// Handle stream acquisition failure:
el.addEventListener('error', () => {
  console.error(`Access failed: ${el.error?.name}`);
});

// Handle prompt cancellation or dismissal:
el.addEventListener('cancel', () => {
  console.log('Permission prompt was dismissed by the user.');
});

Principais atributos e propriedades

• stream: uma propriedade somente leitura que fornece o objeto MediaStream quando o usuário concede acesso.
• setConstraints(): um método que permite que os desenvolvedores atualizem as preferências de hardware, como deviceId ou resolução, antes da interação do usuário.
• error: uma propriedade somente leitura que retorna uma DOMException (por exemplo, um NotAllowedError) se a solicitação falhar ou for dispensada.
• onstream: um manipulador de eventos que é acionado imediatamente quando as faixas de mídia são adquiridas.
• onerror: um manipulador de eventos que é acionado quando uma tentativa de aquisição de stream falha.
• oncancel: um manipulador de eventos que é acionado quando o usuário cancela ou dispensa o prompt de permissão durante a aquisição.

Restrições de estilo

Para garantir a confiança do usuário e evitar padrões de design enganosos, o <usermedia> elemento aplica as mesmas restrições de estilo estritas que outros elementos de capacidade:

• Legibilidade:o navegador verifica as cores do texto e do plano de fundo para garantir contraste suficiente (pelo menos 3:1) para que a solicitação seja sempre legível. Defina o canal alfa (opacity) como 1 para evitar que o elemento seja enganosamente transparente.
• Dimensionamento e espaçamento:o navegador aplica limites mínimos e máximos para width, height e font-size. Ele desativa margens negativas ou deslocamentos de contorno para evitar que o elemento seja visualmente obscurecido.
• Integridade visual:o navegador limita os efeitos de distorção. Por exemplo, transform oferece suporte apenas a traduções 2D e escalonamento proporcional.
• Pseudoclasses CSS:o elemento oferece suporte a estilos baseados em estado, como :granted (que é ativado quando a permissão está ativa e o stream é adquirido), bem como estados de interação padrão, como :hover e :active.

Estratégia de migração e aprimoramento progressivo

Seguindo o padrão de design estabelecido pelo <geolocation>, o <usermedia> elemento é criado para ser reduzido normalmente. Os navegadores que não oferecem suporte ao elemento o tratarão como um HTMLUnknownElement e renderizarão os filhos dele. Isso permite que você ofereça uma experiência de fallback para todos os usuários.

Padrão de fallback personalizado

Detecte programaticamente o suporte ao elemento <usermedia> em JavaScript:

if ('HTMLUserMediaElement' in window) {
  // Use modern <usermedia> element logic
} else {
  // Fallback to legacy getUserMedia() API
}

Use essa lógica de detecção para adicionar um botão padrão dentro do <usermedia> elemento para acionar a API getUserMedia() legada:

<usermedia id="stream-handler">
    <button id="fallback-stream-handler">
        Enable Camera and Mic
    </button>
</usermedia>

// Function for handling video/audio streams:
function handleStream (event) {
  /* ... */
}

if ('HTMLUserMediaElement' in window) {
  // In this case, we have <usermedia> element support:
  const streamHandler = document.getElementById('stream-handler');

  streamHandler.addEventListener('stream', event => {
    handleStream(event);
  });
} else {
  // <usermedia> element support is missing, so fall back instead:
  const fallbackStreamHandler = document.getElementById('fallback-stream-handler');

  fallbackStreamHandler.addEventListener('click', event => {
    navigator.mediaDevices.getUserMedia({video: true, audio: true}).then(handleStream);
  });
}

Migração para participantes do teste de origem

Para desenvolvedores que integraram o elemento experimental e genérico <permission> durante o teste de origem, a transição para <usermedia> foi projetada para ser mínima.

1. Atualização de tag: substitua <permission type="camera microphone"> por <usermedia> para garantir que todos os seletores direcionados aos elementos <permission> anteriores sejam atualizados para usar o elemento <usermedia> em vez disso.
2. Detecção de recursos:atualize as verificações de HTMLPermissionElement para HTMLUserMediaElement

O roteiro à frente

Embora o elemento <usermedia> processe solicitações combinadas de áudio e vídeo, o roteiro para futuros elementos de capacidade inclui:

• <camera>: concentra-se especificamente em cenários somente de vídeo.
• <microphone>: concentra-se especificamente em cenários somente de áudio.

Saiba como esses elementos específicos de capacidade ajudam os desenvolvedores a criar experiências de mídia mais intuitivas e confiáveis. Para mais informações, consulte o guia técnico de elementos de capacidade.

Links relacionados

• Elementos de capacidade: explicador do elemento <usermedia>
• Especificação
• Apresentação do elemento HTML <geolocation>