Etiqueta de vídeo HTML: o guia completo com exemplos

Principais conclusões

• Use <video> com uma fonte MP4 (H.264/AAC); acrescente primeiro WebM se quiser ficheiros mais pequenos.

• Adicione controls, um poster e preload="metadata" — reprodução automática apenas sem som e inline.

• Reserve espaço com aspect-ratio e use object-fit para se adaptar a qualquer layout.

• Adicione legendas com <track> para acessibilidade.

• Para YouTube ou Vimeo, use os respetivos leitores em iframe; para muitos vídeos, use uma galeria.

Exemplo básico

<video controls width="640" poster="poster.jpg">
  <source src="movie.webm" type="video/webm">
  <source src="movie.mp4" type="video/mp4">
  O seu navegador não suporta vídeo HTML5.
</video>

Atributos

Vídeo responsivo

video{width:100%;height:auto;aspect-ratio:16/9}

Legendas

<video controls>
  <source src="movie.mp4" type="video/mp4">
  <track kind="captions" src="captions.vtt" srclang="en" label="English" default>
</video>

Incorporar o YouTube não é a etiqueta video

Os vídeos do YouTube e do Vimeo não podem ser reproduzidos com <video>; use os respetivos leitores em iframe — veja o nosso gerador de código de incorporação do YouTube.

A via sem código

Precisa de uma galeria de vídeos do YouTube, Vimeo e alojados em vez de um só leitor? Use um widget.

Experimente a Elfsight Video Gallery

Formatos e compatibilidade com navegadores

Controlar o vídeo com JavaScript

const v = document.querySelector("video");
v.play();            // returns a Promise
v.pause();
v.currentTime = 30;  // seek to 0:30
v.muted = true;
v.addEventListener("ended", () => console.log("done"));
v.addEventListener("timeupdate", () => console.log(v.currentTime));

Trate a Promise devolvida por play() — é rejeitada quando o navegador bloqueia a reprodução.

Carregamento diferido e desempenho

• preload="none" ou "metadata" mantém a página inicial leve.

• Uma imagem poster aparece de imediato.

• Use loading="lazy" em iframes; para <video>, defina o src quando entrar na área visível.

• Reserve espaço com aspect-ratio para evitar mudanças de layout.

Lista de verificação de acessibilidade

• Adicione legendas com <track kind="captions">.

• Mantenha controls, a menos que forneça os seus próprios controlos acessíveis.

• Nunca reproduza automaticamente com som.

• Forneça uma transcrição para os vídeos importantes.

Problemas comuns

1. 1.

   O vídeo não é reproduzido no iPhone

   Adicione playsinline e muted para a reprodução automática; verifique se o codec é H.264.

2. 2.

   Ecrã preto antes de reproduzir

   Adicione uma imagem de poster.

3. 3.

   Tamanho errado no telemóvel

   Use width:100%; height:auto; aspect-ratio.

4. 4.

   Um ficheiro grande carrega devagar

   Comprima-o ou transmita-o a partir de uma plataforma de vídeo.

Como o navegador escolhe uma fonte

O navegador lê os elementos <source> de cima para baixo e reproduz o primeiro que suportar. É por isso que se lista primeiro o formato mais pequeno e moderno (WebM) e, em segundo lugar, o que tem suporte universal (MP4). O atributo type permite ao navegador saltar ficheiros que não consegue reproduzir sem os descarregar — inclua-o sempre. O texto colocado dentro de <video> depois das fontes só é mostrado pelos navegadores que não suportam vídeo.

<video controls preload="metadata" poster="poster.jpg">
  <source src="clip.webm" type='video/webm; codecs="vp9, opus"'>
  <source src="clip.mp4"  type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
  <a href="clip.mp4">Transferir o vídeo</a>
</video>

Ajustar o vídeo a qualquer layout

Use CSS para controlar como o vídeo preenche a sua caixa. object-fit: cover preenche a área e corta as margens — ideal para secções de destaque. object-fit: contain mostra o fotograma inteiro com barras. Combine-o com aspect-ratio para reservar espaço antes de o ficheiro carregar e evitar mudanças de layout.

.video-box{aspect-ratio:16/9;width:100%}
.video-box video{width:100%;height:100%;object-fit:cover}

/* vertical clips */
.video-vertical{aspect-ratio:9/16;max-width:360px}

Imagem na imagem e ecrã inteiro

Os navegadores modernos permitem mover um vídeo para uma janela flutuante ou para ecrã inteiro a partir de JavaScript — ambos precisam de um gesto do utilizador, como um clique.

const v = document.querySelector("video");

pipButton.onclick = async () => {
  if (document.pictureInPictureElement) await document.exitPictureInPicture();
  else await v.requestPictureInPicture();
};

fullButton.onclick = () => v.requestFullscreen();

Adicione disablepictureinpicture ao elemento se não quiser o botão de PiP do próprio navegador.

Acompanhar a interação com o vídeo

O elemento de vídeo dispara eventos que pode enviar para a sua ferramenta de análise. Acompanhe inícios, conclusões e marcos de progresso — não cada timeupdate, que dispara várias vezes por segundo.

const v = document.querySelector("video");
const sent = new Set();
const track = (name) => window.gtag && gtag("event", name, { video_title: v.dataset.title });

v.addEventListener("play", () => track("video_start"), { once: true });
v.addEventListener("ended", () => track("video_complete"));
v.addEventListener("timeupdate", () => {
  const p = Math.floor((v.currentTime / v.duration) * 4) * 25; // 25, 50, 75
  if (p && p < 100 && !sent.has(p)) { sent.add(p); track("video_progress_" + p); }
});

Etiqueta video, iframe ou galeria?

A etiqueta video é a ferramenta certa para os seus próprios ficheiros curtos: ciclos de produto, fundos de destaque, pequenas explicações alojadas numa CDN. Para vídeos no YouTube ou no Vimeo, use os respetivos leitores em iframe — tratam da transmissão, da mudança de qualidade e das legendas. Quando precisa de muitos vídeos, de feeds que se atualizam sozinhos ou de uma mistura de plataformas, um widget de galeria poupa-lhe construir à mão playlists, pop-ups e layouts.