Vídeos do YouTube em HTML
Aprenda a incorporar vídeos do YouTube com o elemento <iframe>: URL de incorporação, dimensionamento responsivo, atributo allow, autoplay, loop e modo de privacidade.
Hospedar e servir vídeos por conta própria é trabalhoso: você precisa codificar em vários formatos para que todos os navegadores possam reproduzi-los, armazenar arquivos grandes e pagar pela largura de banda. A abordagem mais simples é deixar o YouTube fazer tudo isso e incorporar seu player na sua página com um elemento <iframe>. O navegador carrega o player do YouTube dentro do frame, então algumas linhas de HTML oferecem streaming adaptativo, legendas e tela cheia gratuitamente.
Esta página explica como construir a URL de incorporação, tornar o player responsivo, configurar permissões com o atributo allow e passar parâmetros de reprodução como autoplay, loop e controles.
Encontrando o ID do Vídeo e a URL de Incorporação
O erro mais comum é colocar a URL de assistir no src. O endereço que você vê no navegador ao assistir um vídeo no YouTube é uma URL de assistir e não pode ser incorporado diretamente:
https://www.youtube.com/watch?v=i8n1gSw_o_8A parte após v= é o ID do vídeo (i8n1gSw_o_8 acima). Para incorporação, você precisa da URL de incorporação, que usa o caminho /embed/ seguido desse ID:
https://www.youtube.com/embed/i8n1gSw_o_8Para encontrar o ID: abra o vídeo no YouTube, copie o valor do parâmetro de consulta v da barra de endereços (ou use a opção Compartilhar → Incorporar, que fornece a URL /embed/ completa e a marcação <iframe>). Links de compartilhamento encurtados como https://youtu.be/i8n1gSw_o_8 também expõem o ID como o último segmento do caminho.
Reproduzindo um Vídeo do YouTube em HTML
Para incorporar um vídeo, aponte o src do iframe para a URL de incorporação e defina suas dimensões:
- Anote o ID do vídeo (veja acima).
- Adicione um elemento
<iframe>à sua página. - Defina o atributo
srccomo a URL de incorporação:https://www.youtube.com/embed/VIDEO_ID. - Defina
widtheheight(ou dimensione com CSS — veja Incorporações Responsivas). - Adicione um atributo
titledescrevendo o vídeo para acessibilidade. - Acrescente parâmetros de URL para personalizar a reprodução (por exemplo,
?rel=0para limitar os vídeos recomendados após a reprodução ao mesmo canal).
Exemplo de reprodução de um vídeo do YouTube em HTML com o elemento <iframe>:
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<iframe width="560" height="315" title="YouTube video player" src="https://www.youtube.com/embed/i8n1gSw_o_8" allow="autoplay; fullscreen"></iframe>
</body>
</html>Modo de Privacidade Aprimorada (youtube-nocookie.com)
Uma incorporação padrão do YouTube pode definir cookies de rastreamento assim que a página é carregada — antes mesmo de o visitante pressionar play. Sob o GDPR e regulamentações similares, isso pode exigir consentimento explícito. O YouTube oferece um modo de privacidade aprimorada que adia o armazenamento de cookies de identificação pessoal até que o visitante realmente comece a assistir. Para usá-lo, substitua o host por youtube-nocookie.com:
<iframe width="560" height="315" title="YouTube video player"
src="https://www.youtube-nocookie.com/embed/i8n1gSw_o_8"
allow="autoplay; fullscreen"></iframe>Todo o restante — o caminho /embed/, o ID do vídeo e todos os parâmetros de URL — funciona exatamente da mesma forma. Note que isso reduz, mas não elimina completamente, os dados que o player pode enviar, portanto revise sua política de consentimento se você tiver requisitos rigorosos.
O Atributo allow
Os navegadores controlam recursos avançados por meio da Permissions Policy. Para que um iframe do YouTube use autoplay, tela cheia e outras capacidades, a página principal deve concedê-las por meio do atributo allow do iframe. O atributo recebe uma lista separada por ponto e vírgula de tokens de permissão. O conjunto que o diálogo Compartilhar → Incorporar do próprio YouTube gera é:
<iframe width="560" height="315" title="YouTube video player"
src="https://www.youtube.com/embed/i8n1gSw_o_8"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowfullscreen></iframe>Tokens comuns e o que eles habilitam:
| Token | Finalidade |
|---|---|
accelerometer | Permite ao player ler o movimento do dispositivo (usado por alguns vídeos 360°/VR). |
autoplay | Permite que o vídeo comece a ser reproduzido sem um gesto do usuário. |
clipboard-write | Permite ao player copiar texto (por exemplo, links de compartilhamento) para a área de transferência. |
encrypted-media | Habilita a reprodução protegida por DRM via Encrypted Media Extensions. |
gyroscope | Permite ao player ler a orientação do dispositivo (vídeos 360°/VR). |
picture-in-picture | Permite que o vídeo apareça em uma janela flutuante. |
web-share | Permite ao player abrir o diálogo de compartilhamento nativo. |
O atributo separado allowfullscreen permite o botão de tela cheia. Você pode omitir tokens que não precisa; omitir autoplay, por exemplo, simplesmente significa que o autoplay será bloqueado.
Incorporações Responsivas do YouTube
Um iframe com width/height fixos não se adaptará a telas pequenas e pode transbordar de seu contêiner. Duas técnicas confiáveis fazem o player escalar para seu elemento pai mantendo as proporções de vídeo 16:9.
Com a propriedade CSS aspect-ratio (navegadores modernos)
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
<style>
.video {
width: 100%;
max-width: 720px;
}
.video iframe {
width: 100%;
height: auto;
aspect-ratio: 16 / 9;
border: 0;
}
</style>
</head>
<body>
<div class="video">
<iframe title="YouTube video player"
src="https://www.youtube.com/embed/i8n1gSw_o_8"
allow="autoplay; fullscreen"></iframe>
</div>
</body>
</html>Com o hack do padding-bottom (ampla compatibilidade)
Para navegadores mais antigos que não possuem aspect-ratio, envolva o iframe em um contêiner cuja altura é criada por padding-bottom: 56.25% (ou seja, 9 ÷ 16, a proporção 16:9), então estique o iframe para preenchê-lo absolutamente:
<style>
.video-wrap {
position: relative;
width: 100%;
padding-bottom: 56.25%; /* 16:9 aspect ratio */
height: 0;
}
.video-wrap iframe {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
border: 0;
}
</style>
<div class="video-wrap">
<iframe title="YouTube video player"
src="https://www.youtube.com/embed/i8n1gSw_o_8"
allow="autoplay; fullscreen"></iframe>
</div>Personalizando a Reprodução com Parâmetros de URL
Você configura o player acrescentando parâmetros de consulta à URL de incorporação. O primeiro parâmetro é introduzido com ?, e cada parâmetro adicional é unido com &:
https://www.youtube.com/embed/VIDEO_ID?autoplay=1&mute=1&controls=0A maioria dos parâmetros aceita um valor de 0 (desligado) ou 1 (ligado). As seções abaixo cobrem os que você usará com mais frequência.
Autoplay do YouTube
Para iniciar o vídeo automaticamente quando o player carrega, adicione autoplay=1 (o padrão, autoplay=0, aguarda o usuário pressionar play).
Importante: os navegadores bloqueiam o autoplay com som. Um vídeo com autoplay também deve estar sem som, então combine autoplay=1 com mute=1 — caso contrário, o vídeo não iniciará. O iframe também deve ter a permissão autoplay concedida em seu atributo allow.
Exemplo de autoplay do YouTube:
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<iframe width="560" height="315" title="YouTube video player" src="https://www.youtube.com/embed/i8n1gSw_o_8?autoplay=1&mute=1" allow="autoplay; fullscreen"></iframe>
</body>
</html>Controles do YouTube
O parâmetro controls alterna a barra de controles do player (play/pause, volume, tela cheia, entre outros). Use controls=0 para ocultá-la e controls=1 (o padrão) para exibi-la.
Exemplo de controles do YouTube:
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<iframe width="560" height="315" title="YouTube video player" src="https://www.youtube.com/embed/i8n1gSw_o_8?controls=0" allow="autoplay; fullscreen"></iframe>
</body>
</html>Loop do YouTube
Use loop=1 para fazer o vídeo repetir infinitamente (o padrão, loop=0, reproduz apenas uma vez). Há uma ressalva: para um único vídeo, o loop só funciona se você também passar playlist com o mesmo ID do vídeo. O YouTube trata um loop como "voltar ao início da playlist", então sem essa entrada na playlist o vídeo para após uma reprodução. O exemplo abaixo define ambos:
Exemplo de loop do YouTube:
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<iframe width="560" height="315" title="YouTube video player" src="https://www.youtube.com/embed/i8n1gSw_o_8?playlist=i8n1gSw_o_8&loop=1" allow="autoplay; fullscreen"></iframe>
</body>
</html>Legado: as tags <embed> e <object>
Você ainda pode encontrar tutoriais antigos que incorporam o YouTube com os elementos <embed> ou <object>. Não use esses elementos para o YouTube — o método moderno e suportado é o <iframe> mostrado acima. Os exemplos abaixo são mantidos apenas para que você possa reconhecer o padrão legado:
<!-- Legacy / not recommended -->
<embed width="560" height="315" src="https://www.youtube.com/embed/i8n1gSw_o_8" />
<object width="560" height="315" data="https://www.youtube.com/embed/i8n1gSw_o_8"></object>Tópicos Relacionados
- Tag HTML
<iframe>— o elemento usado em toda incorporação do YouTube. - Tag HTML
<video>— para servir seus próprios arquivos de vídeo em vez de incorporar o YouTube. - Áudio e Vídeo em HTML5 — o panorama geral de mídia nativa em HTML.