Docs executáveis de HTML: Tag video

Q: Como colocar um vídeo no HTML?

Use . O atributo controls mostra o botão de play, a linha do tempo e o volume do navegador. Sem ele, o vídeo mostra o primeiro quadro (ou o poster) e o usuário não consegue iniciá-lo.

Q: Por que o autoplay não funciona no meu vídeo?

Os navegadores bloqueiam o autoplay com som. Adicione muted ao lado de autoplay, e playsinline para que o iPhone o reproduza na página em vez de em tela cheia: .

Q: Como colocar uma miniatura num vídeo?

Use o atributo poster com a URL de uma imagem: . A imagem aparece até o vídeo começar a tocar.

Q: Como colocar legendas num vídeo HTML?

Adicione um dentro do vídeo. O arquivo usa o formato WebVTT, e o navegador mostra um botão de legendas nos controles.

Q: Como deixar um vídeo responsivo?

Defina width: 100% e height: auto no CSS (ou max-width: 100%). O vídeo acompanha o contêiner e mantém a proporção.

Como colocar um vídeo

Aponte o elemento <video> para um arquivo de vídeo e adicione controls para que o usuário possa reproduzi-lo:

<video src="movie.mp4" controls width="640"></video>

controls mostra o player do próprio navegador: play e pause, uma linha do tempo, volume e tela cheia. Sem ele, o vídeo fica parado. Esta prévia não consegue carregar arquivos de vídeo, então os exemplos desta página alimentam o elemento com uma pequena animação de canvas desenhada por um script; os atributos funcionam exatamente como com um arquivo:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Video</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <video id="player" controls muted width="320" height="180"></video>
  <p>Press play.</p>
  <script>
    // Stand-in for a video file: an animation drawn on a canvas
    const canvas = document.createElement('canvas');
    canvas.width = 320; canvas.height = 180;
    const ctx = canvas.getContext('2d');
    let x = 0;
    (function draw() {
      ctx.fillStyle = '#111827'; ctx.fillRect(0, 0, 320, 180);
      ctx.fillStyle = '#f59e0b'; ctx.beginPath();
      ctx.arc(30 + (x % 260), 90, 24, 0, Math.PI * 2); ctx.fill();
      x += 2; requestAnimationFrame(draw);
    })();
    document.getElementById('player').srcObject = canvas.captureStream(30);
  </script>
</body>
</html>

Como a origem é um stream ao vivo e não um arquivo, aqui não dá para arrastar a linha do tempo e não existe duração fixa. Com um .mp4 de verdade, o mesmo player ganha uma barra de busca completa.

Atributos do vídeo

Atributo	O que faz
`controls`	Mostra os controles do player do navegador
`autoplay`	Começa a tocar assim que puder (na prática, só com `muted`)
`muted`	Começa sem som
`loop`	Recomeça do início quando termina
`playsinline`	Toca na página no iPhone em vez de mudar para tela cheia
`poster="thumb.jpg"`	Imagem mostrada antes de o vídeo tocar
`preload`	`none`, `metadata` (só tamanho e duração) ou `auto` (o navegador decide quanto baixar)
`width`, `height`	Tamanho em pixels; definir os dois reserva o espaço antes de o vídeo carregar

Autoplay, muted e loop

Os navegadores bloqueiam vídeos que começam sozinhos com som. Um vídeo mudo pode tocar automaticamente, e é assim que funcionam vídeos de fundo e clipes curtos em loop:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Autoplay</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    .hero { position: relative; width: 320px; height: 180px; border-radius: 10px; overflow: hidden; }
    .hero video { width: 100%; height: 100%; object-fit: cover; }
    .hero h1 { position: absolute; inset: auto 0 0 0; margin: 0; padding: 10px; color: #fff; font-size: 20px; background: rgba(0, 0, 0, 0.45); }
  </style>
</head>
<body>
  <div class="hero">
    <video id="bg" autoplay muted loop playsinline></video>
    <h1>Background video</h1>
  </div>
  <p id="state"></p>
  <script>
    const canvas = document.createElement('canvas');
    canvas.width = 320; canvas.height = 180;
    const ctx = canvas.getContext('2d');
    let t = 0;
    (function draw() {
      ctx.fillStyle = 'hsl(' + (t % 360) + ', 70%, 45%)';
      ctx.fillRect(0, 0, 320, 180);
      t += 1; requestAnimationFrame(draw);
    })();
    const video = document.getElementById('bg');
    video.srcObject = canvas.captureStream(30);
    video.addEventListener('playing', () => {
      document.getElementById('state').textContent = 'Playing without a click, because it is muted.';
    });
  </script>
</body>
</html>

Os quatro atributos funcionam em conjunto: autoplay para começar, muted para o navegador permitir, loop para um clipe e playsinline para o iPhone não abrir em tela cheia. Vídeo com som que toca sozinho não só é bloqueado, como também é um problema para quem usa leitor de tela, que tem a fala abafada. Se um clipe toca por mais de cinco segundos, dê às pessoas um jeito de pausá-lo.

Imagem de poster e preload

poster mostra uma imagem antes de o vídeo tocar, como uma miniatura. Aqui o vídeo não tem nenhuma origem, então o poster é tudo o que se vê:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Poster</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <video controls width="320" height="180" preload="none"
    poster="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='320' height='180'%3E%3Crect width='320' height='180' fill='%232563eb'/%3E%3Ctext x='160' y='98' font-family='Arial' font-size='22' fill='white' text-anchor='middle'%3EEpisode 1: Intro%3C/text%3E%3C/svg%3E">
  </video>
</body>
</html>

Com preload="none" o navegador não baixa nada até o usuário apertar play, e o poster evita que o espaço pareça vazio. Use preload="metadata" quando quiser a duração visível antes de tocar. Sem poster, a maioria dos navegadores mostra o primeiro quadro depois de carregá-lo.

Formatos e alternativas com source

Em vez de src, você pode listar vários arquivos com elementos <source>. O navegador toca o primeiro que ele suporta:

<video controls width="640" poster="thumb.jpg">
  <source src="movie.webm" type="video/webm">
  <source src="movie.mp4" type="video/mp4">
  <track kind="captions" src="captions.vtt" srclang="en" label="English">
  <p>Your browser cannot play this video. <a href="movie.mp4">Download it</a>.</p>
</video>

MP4 com vídeo H.264 roda em todos os navegadores atuais, então é a escolha segura quando você tem só um arquivo. O atributo type permite que o navegador pule os formatos que não consegue tocar sem baixá-los. O texto no final só aparece em navegadores que não suportam <video>.

Legendas com track

<track kind="captions"> carrega um arquivo WebVTT, um arquivo de texto simples com linhas marcadas por tempo. O navegador adiciona um botão de legendas aos controles e desenha o texto sobre o vídeo:

WEBVTT

00:00:00.000 --> 00:00:03.000
Welcome to the course.

00:00:03.000 --> 00:00:06.500
Today we build our first web page.

Legendas ajudam pessoas surdas ou com perda auditiva, quem assiste sem som e quem acompanha um vídeo numa segunda língua. Adicione default a uma track para mostrá-la sem precisar de clique. Um arquivo de legendas de outro domínio precisa de cabeçalhos CORS e de crossorigin no vídeo.

Estilizar e controlar com JavaScript

Um vídeo é um elemento substituído, como uma imagem: width: 100% com height: auto o deixa responsivo, e object-fit decide como ele preenche uma caixa de outro formato. O JavaScript tem play(), pause(), currentTime, volume e eventos como play, pause e ended:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Custom controls</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    video { width: 100%; max-width: 360px; height: auto; border-radius: 10px; display: block; }
    button { font: inherit; margin-top: 8px; padding: 6px 14px; }
  </style>
</head>
<body>
  <video id="v" muted width="320" height="180"></video>
  <button id="toggle">Play</button>
  <span id="status">Paused</span>
  <script>
    const canvas = document.createElement('canvas');
    canvas.width = 320; canvas.height = 180;
    const ctx = canvas.getContext('2d');
    let a = 0;
    (function draw() {
      ctx.fillStyle = '#e5e7eb'; ctx.fillRect(0, 0, 320, 180);
      ctx.fillStyle = '#16a34a'; ctx.beginPath();
      ctx.arc(160 + Math.cos(a) * 60, 90 + Math.sin(a) * 60, 16, 0, Math.PI * 2); ctx.fill();
      a += 0.05; requestAnimationFrame(draw);
    })();
    const video = document.getElementById('v');
    const button = document.getElementById('toggle');
    const status = document.getElementById('status');
    video.srcObject = canvas.captureStream(30);
    button.onclick = () => (video.paused ? video.play() : video.pause());
    video.addEventListener('play', () => { button.textContent = 'Pause'; status.textContent = 'Playing'; });
    video.addEventListener('pause', () => { button.textContent = 'Play'; status.textContent = 'Paused'; });
  </script>
</body>
</html>

play() retorna uma promise que é rejeitada quando o navegador bloqueia a reprodução (por exemplo, autoplay com som), então o código de produção deve tratá-la com catch. Criar os seus próprios controles é opcional; os controls nativos funcionam pelo teclado e são traduzidos, e botões personalizados precisam reproduzir tudo isso. Para vídeos hospedados no YouTube ou no Vimeo, você incorpora o player deles com um iframe.

Erros comuns

Autoplay sem muted. O navegador bloqueia. Adicione muted e playsinline.
Esquecer controls. A não ser que você crie os seus, o usuário não tem como iniciar o vídeo.
Sem width e height. A página pula quando o vídeo carrega. Defina os dois e depois escale com CSS.
Arquivos enormes. Comprima os vídeos para a web e use preload="none" ou "metadata" em vídeos mais abaixo na página.
Sem legendas em vídeos com fala. Adicione um <track kind="captions">.

Perguntas frequentes

Como colocar um vídeo no HTML?

Use <video src="movie.mp4" controls width="640"></video>. O atributo controls mostra o botão de play, a linha do tempo e o volume do navegador. Sem ele, o vídeo mostra o primeiro quadro (ou o poster) e o usuário não consegue iniciá-lo.

Por que o autoplay não funciona no meu vídeo?

Os navegadores bloqueiam o autoplay com som. Adicione muted ao lado de autoplay, e playsinline para que o iPhone o reproduza na página em vez de em tela cheia: <video autoplay muted loop playsinline>.

Qual formato de vídeo usar na web?

MP4 com vídeo H.264 roda em todos os navegadores atuais, então é o padrão seguro. Você pode listar primeiro um arquivo WebM menor com <source> e deixar o navegador escolher o primeiro formato que ele suporta.

Como colocar uma miniatura num vídeo?

Use o atributo poster com a URL de uma imagem: <video poster="thumb.jpg" controls>. A imagem aparece até o vídeo começar a tocar.

Como colocar legendas num vídeo HTML?

Adicione um <track kind="captions" src="captions.vtt" srclang="en" label="English"> dentro do vídeo. O arquivo usa o formato WebVTT, e o navegador mostra um botão de legendas nos controles.

Como deixar um vídeo responsivo?

Defina width: 100% e height: auto no CSS (ou max-width: 100%). O vídeo acompanha o contêiner e mantém a proporção.

Conceitos relacionados