<video>: O elemento HTML de incorporação de Vídeo

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

O elemento HTML <video> incorpora um reprodutor de mídia que suporta a reprodução de vídeo no documento. Você também pode usar <video> para conteúdo de áudio, mas o elemento <audio> pode proporcionar uma experiência de usuário mais adequada.

Experimente

O exemplo acima mostra um uso simples do elemento <video>. Semelhante ao elemento <img>, incluímos o caminho da mídia que queremos exibir dentro do atributo src; também podemos incluir outros atributos para especificar informações, como largura e altura do vídeo, se queremos que ele seja reproduzido automaticamente e em loop, se queremos mostrar os controles de vídeo padrão do navegador etc.

O conteúdo dentro das tags de abertura e fechamento <video></video> é exibido como uma alternativa (fallback) em navegadores que não suportam o elemento.

Atributos

Como qualquer elemento HTML, este elemento suporta os atributos globais.

autoplay

Um atributo Booleano; se especificado, o video vai ser executado assim que possível sem precisar de carregar todo o arquivo.

Nota: Sites que reproduzem automaticamente áudio (ou vídeos com uma faixa de áudio) podem proporcionar uma experiência desagradável para os usuários, portanto, devem ser evitados sempre que possível. Se você precisar oferecer a funcionalidade de reprodução automática, é recomendável torná-la opcional (exigindo que o usuário a habilite especificamente). No entanto, isso pode ser útil ao criar elementos de mídia cuja fonte será definida posteriormente, sob controle do usuário. Consulte nosso guia sobre reprodução automática para obter informações adicionais sobre como usar a reprodução automática corretamente.

Para desativar a reprodução automática, autoplay="false" não vai funcionar; o vídeo será reproduzido automaticamente se o atributo estiver presente na tag <video>. Para remover a reprodução automática, o atributo deve ser removido por completo.

A reprodução automática não funciona em alguns navegadores (ex., Chrome 70.0) se o atributo muted estiver presente.

controls

Se esse atributo estiver presente, o navegador oferecerá controles para permitir o usuário controlar a reprodução do vídeo, incluindo volume, navegação (seek), e pausa/continuação da reprodução.

controlslist

O atributo controlslist, quando definido, ajuda o navegador a selecionar que controles mostrar no elemento video sempre que o navegador exibir o seu próprio conjunto de controles (ou seja, quando o atributo controls for especificado).

Os valores permitidos são nodownload, nofullscreen e noremoteplayback.

Use o atributo disablepictureinpicture se você quiser desabilitar o modo Picture-In-Picture (e o controle).

crossorigin

Esse atributo enumerado indica se deve usar CORS para buscar o vídeo relacionado. Recursos habilitados para CORS podem ser reutilizados no elemento <canvas> sem serem contaminados. Os valores permitidos são:

  • anonymous Envia uma solicitação de origem cruzada sem uma credencial. Em outras palavras, ele envia o cabeçalho HTTP Origin: sem um cookie, certificado X.509 ou realizar uma autenticação HTTP Basic. Se o servidor não fornecer credenciais ao site de origem (não definindo o cabeçalho HTTP Access-Control-Allow-Origin:), o recurso será contaminado e seu uso restrito.
  • use-credentials
    • : Envia uma solicitação de origem cruzada com uma credencial. Em outras palavras, envia o cabeçalho HTTP Origin: com um cookie, um certificado, ou realiza autenticação HTTP Basic. Se o servidor não fornecer credenciais ao o site de origem (por meio do cabeçalho HTTP Access-Control-Allow-Credentials:), o recurso será contaminado e seu uso será restrito.

Quando não está presente, o recurso é buscado sem uma solicitação CORS (ou seja, sem enviar o cabeçalho HTTP Origin:), impedindo seu uso não contaminado em elementos <canvas>. Se for inválido, é tratado como se a palavra-chave enumerada anonymous tivesse sido usada. Consulte os atributos de configuração de CORS para obter informações adicionais.

disablepictureinpicture

Impede o navegador de sugerir um menu de contexto Picture-in-Picture ou de solicitar automaticamente o Picture-in-Picture em alguns casos..

disableremoteplayback

Um atributo Booleano usado para desativar a capacidade de reprodução remota em dispositivos conectados usando tecnologias com fio (HDMI, DVI, etc.) e sem fio (Miracast, Chromecast, DLNA, AirPlay, etc.).

No Safari, você pode usar x-webkit-airplay="deny" como alternativa.

height

A altura da área de exibição do vídeo, em pixels de CSS (apenas valores absolutos; sem porcentagens).

loop

Um atributo Booleano; se especificado, ao chegar no fim do vídeo, ele voltará automaticamente para o começo.

muted

Um atributo Booleano que indica a configuração padrão do áudio contido no vídeo. Se definido, o áudio vai começar mudo. Seu valor padrão é falso, significando que o áudio será reproduzido juntamente com o vídeo.

playsinline

Um atributo booleano que indica que o vídeo deve ser reproduzido "em linha" (inline), ou seja, dentro da área de reprodução do elemento. Observe que a ausência deste atributo não implica que o vídeo será sempre reproduzido em tela cheia.

poster

Uma URL indicando uma imagem de prévia do vídeo até o usuário reproduzir ou navegar por ele. Se este atributo não estiver especificado, nada será mostrado até que o primeiro quadro esteja disponível; então o primeiro quadro será exibido como imagem de prévia.

preload

Esse atributo enumerado pretende dar uma sugestão ao navegador sobre o que o autor pensa que proporcionará uma melhor experiência do usuário. Ele pode ter os seguintes valores:

  • none: indica que o usuário não necessitará consultar o vídeo ou que o servidor quer minimizar seu tráfego; em outros termos indica que o vídeo não deve ser pré-carregado.
  • metadata: indica que embora o usuário não necessitará consultar o vídeo, pegar os meta-dados (ex: comprimento) é interessante.
  • auto: indica que o usuário necessita ter prioridade; em outros termos isso indicou que, se necessário, o vídeo inteiro pode ser baixado, mesmo que não seja esperado a execução.
  • a string vazia: é um sinônimo do valor auto.

Se não definido, seu valor padrão será definido pelo navegador (isto é, cada navegador pode escolher seu valor padrão), embora a especificação recomende que seja definido para o metadata.

Nota:

  • O atributo autoplay tem precedência sobre o preload, pois se é necessário executar o vídeo automaticamente, o navegador obviamente o baixará. Definindo ambos autoplay e preload é permitido pela especificação.
  • O navegador não é forçado pela especifição a seguir o valor desse atributo; é apenas uma sugestão.
src

A URL do vídeo a ser incorporado. Isto é opcional; ao invés disso você pode usar o elemento <source> dentro do bloco do vídeo para especificar o vídeo a ser incorporado .

width

A largura da área de exibição do vídeo, em pixels de CSS (apenas valores absolutos; sem porcentagens).

Eventos

Nome do evento Quando é disparado
audioprocess Deprecated O buffer de entrada de um ScriptProcessorNode está pronto para ser processado.
canplay O navegador pode reproduzir a mídia, mas estima que não há dados suficientes carregados para reproduzir a mídia até o final sem ter que parar para carregar mais conteúdo.
canplaythrough O navegador estima que pode reproduzir a mídia até o final sem precisar parar para carregar mais conteúdo.
complete A renderização de um OfflineAudioContext foi concluída.
durationchange O atributo duration foi atualizado.
emptied A mídia ficou vazia; por exemplo, este evento é enviado se a mídia já foi carregada (ou parcialmente carregada), e o método load() é chamado para recarregá-la.
ended A reprodução foi interrompida porque o final da mídia foi alcançado.
error Ocorreu um erro ao buscar os dados da mídia, ou o tipo do recurso não é um formato de mídia suportado.
loadeddata O primeiro quadro da mídia terminou de carregar.
loadedmetadata Os metadados foram carregados.
loadstart Disparado quando o navegador começou a carregar o recurso.
pause A reprodução foi pausada.
play A reprodução começou.
playing A reprodução está pronta para começar depois de ter sido pausada ou atrasada devido à falta de dados.
progress Disparado periodicamente conforme o navegador carrega um recurso.
ratechange A taxa de reprodução foi alterada.
seeked Uma operação de navegação foi concluída.
seeking Uma operação de navegação foi iniciada.
stalled O agente do usuário está tentando buscar dados de mídia, mas os dados não estão sendo recebidos conforme o esperado.
suspend O carregamento dos dados da mídia foi suspenso.
timeupdate O tempo indicado pelo atributo currentTime foi atualizado.
volumechange O volume foi alterado.
waiting A reprodução foi interrompida devido à falta temporária de dados.

Notas de uso

Os navegadores não dão suporte a todos os mesmos formatos de vídeo; você pode fornecer múltiplas fontes dentro de elementos <source> aninhados, e o navegador utilizará a primeira que tiver suporte.

html
<video controls>
  <source src="meuVideo.webm" type="video/webm" />
  <source src="meuVideo.mp4" type="video/mp4" />
  <p>
    O seu navegador não tem suporte a vídeo HTML. Em vez disso, aqui está
    <a href="meuVideo.mp4" download="meuVideo.mp4">o link do vídeo</a>.
  </p>
</video>

Nós oferecemos um guia abrangente e detalhado sobre tipos de arquivos de mídia e o guia sobre os codecs compatíveis com vídeo. Também está disponível um guia sobre os codecs de áudio que podem ser usados com eles.

Outras notas de uso:

  • Se você não especificar o atributo controls, o vídeo não incluirá os controles padrão do navegador; você pode criar seus próprios controles personalizados usando JavaScript e a API HTMLMediaElement. Consulte Criando um player de vídeo compatível com vários navegadores para obter mais detalhes.
  • Para permitir o controle preciso do conteúdo do seu vídeo (e áudio), os elementos HTMLMediaElement disparam muitos eventos diferentes. Além de fornecer controlabilidade, esses eventos permitem que você monitore o progresso tanto do download quanto da reprodução da mídia, bem como o estado e a posição da reprodução.
  • Você pode usar a propriedade object-position para ajustar o posicionamento do vídeo dentro do quadro do elemento e a propriedade object-fit para controlar como o tamanho do vídeo é ajustado para caber dentro do quadro.
  • Para exibir legendas/legendas junto com o seu vídeo, você pode usar JavaScript junto com o elemento <track> e o formato WebVTT. Consulte Adicionando legendas em um vídeo HTML para obter mais informações.
  • Você pode reproduzir arquivos de áudio usando um elemento <video>. Isso pode ser útil, por exemplo, se você precisar executar áudio com uma transcrição WebVTT, já que o elemento <audio> não permite legendas usando WebVTT.
  • Para testar o conteúdo de alternativa (fallback) em navegadores que suportam o elemento, você pode substituir <video> por um elemento que não exista, como <notavideo>.

Uma boa fonte geral de informações sobre o uso de HTML <video> é o tutorial para iniciantes em Conteúdo de vídeo e áudio.

Estilização com CSS

O elemento <video> é um replaced element — seu valor display é inline por padrão, mas sua largura e altura padrão na viewport são definidas pelo vídeo que está sendo incorporado.

Não há considerações especiais para estilizar <video>; uma estratégia comum é atribuir a ele um valor display de block para facilitar o posicionamento, o tamanho etc. e, em seguida, fornecer informações de estilo e layout conforme necessário. Noções básicas de estilo do player de vídeo fornece algumas técnicas de estilo úteis.

Detectando a adição e a remoção de faixas

Você pode detectar quando as faixas são adicionadas e removidas de um elemento <video> usando os eventos addtrack e removetrack. Entretanto, esses eventos não são enviados diretamente para o próprio elemento <video>. Em vez disso, eles são enviados para o objeto da lista de faixas dentro do HTMLMediaElement do elemento <video> que corresponde ao tipo de faixas que foi adicionada ao elemento:

HTMLMediaElement.audioTracks

Um AudioTrackList contendo todas as faixas de áudio do elemento de mídia. Você pode adicionar um listener no evento addtrack deste objeto para ser alertado quando novas faixas de áudio forem adicionadas ao elemento.

HTMLMediaElement.videoTracks

Adicione um listener addtrack a este objeto VideoTrackList para ser informado quando faixas de vídeo forem adicionadas ao elemento.

HTMLMediaElement.textTracks

Adicione um listener de evento addtrack a este TextTrackList para ser notificado quando novas faixas de texto forem adicionadas ao elemento.

Por exemplo, para detectar quando faixas de áudio são adicionadas ou removidas de um elemento <video>, você pode usar um código como este:

js
const elem = document.querySelector("video");

elem.audioTracks.onaddtrack = (event) => {
  trackEditor.addTrack(event.track);
};

elem.audioTracks.onremovetrack = (event) => {
  trackEditor.removeTrack(event.track);
};

Este código monitora as faixas de áudio que foram adicionadas ou removidas do elemento e chama uma função hipotética em um editor de faixas para registrar e remover a faixa da lista de faixas disponíveis do editor.

Você também pode usar addEventListener() para ouvir os eventos addtrack e removetrack.

Suporte do servidor para vídeo

Se o tipo MIME do vídeo não estiver definido corretamente no servidor, o vídeo poderá não ser mostrado ou uma caixa cinza contendo um X (se o JavaScript estiver habilitado) será exibida em seu lugar.

Se você disponibiliza seu vídeos como Ogg Theora, você pode corrigir esse problema para o servidor web Apache adicionando a extensão utilizada por seu arquivos de vídeo (".ogm", ".ogv", e ".ogg" são as mais comuns) para o tipo MIME "video/ogg" através do arquivo "mime.types" localizado em "/etc/apache" ou através da configuração de diretiva "AddType" no httpd.conf.

AddType video/ogg .ogm
AddType video/ogg .ogv
AddType video/ogg .ogg

Se você disponibilizar seu vídeos como WebM, você pode corrigir esse problema para o servidor web Apache adicionando a extensão usada por seu arquivos de vídeo (".webm" é a mais comum) para o tipo MIME "video/webm" através do arquivo "mime.types" localizado em "/etc/apache" ou através da configuração de diretiva "AddType" no httpd.conf.

AddType video/webm .webm

Seu serviço de hospedagem talvez forneça uma interface simples para mudar a configuração dos tipos MIME para as novas tecnologias até que uma atualização global ocorra naturalmente.

Exemplos

Fonte única

Esse exemplo reproduz um vídeo quando ativado, fornecendo ao usuário os controles de vídeo padrão do navegador para controlar a reprodução.

HTML

html
<!-- Exemplo de vídeo simples -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster de peach.blender.org -->
<video
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Desculpe, seu navegador não suporta vídeos incorporados, mas não se preocupe,
  você pode
  <a href="https://archive.org/details/BigBuckBunny_124">baixá-lo</a>
  e assisti-lo com seu player de vídeo favorito!
</video>

Resultado

Até que o vídeo comece a ser reproduzido, a imagem fornecida no atributo poster é exibida em seu lugar. Se o navegador não tiver suporte para reprodução de vídeo, o texto de alternativa (fallback) será exibido.

Múltiplas fontes

Este exemplo se baseia no anterior, oferecendo três fontes diferentes para a mídia; isso permite que o vídeo seja assistido independentemente dos codecs de vídeo suportados pelo navegador.

HTML

html
<!-- Usando multiplas fontes como alternativa para a tag video -->
<!-- 'Elephants Dream' by Orange Open Movie Project Studio, licensed under CC-3.0, hosted by archive.org -->
<!-- Poster hospedado por Wikimedia -->
<video
  width="620"
  controls
  poster="https://upload.wikimedia.org/wikipedia/commons/e/e8/Elephants_Dream_s5_both.jpg">
  <source
    src="https://archive.org/download/ElephantsDream/ed_hd.ogv"
    type="video/ogg" />
  <source
    src="https://archive.org/download/ElephantsDream/ed_hd.avi"
    type="video/avi" />
  <source
    src="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    type="video/mp4" />

  Desculpe, seu navegador não suporta vídeos incorporados, mas não se preocupe,
  você pode fazer o
  <a
    href="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    download="ed_1024_512kb.mp4">
    download do MP4
  </a>
  e assisti-lo com seu player de vídeo favorito!
</video>

Resultado

Primeiro, é tentado o formato Ogg. Se não for possível reproduzi-lo, será tentado o AVI. Por fim, é tentado o MP4. Uma mensagem de fallback é exibida se o vídeo não puder ser reproduzido, mas a mesma não será exibida se todas as fontes falharem.

Alguns tipos de arquivos de mídia permitem que você forneça informações mais específicas usando o parâmetro codecs como parte da string de tipo do arquivo. Um exemplo relativamente simples é video/webm; codecs="vp8, vorbis", que indica que o arquivo é um vídeo WebM usando VP8 para o vídeo e Vorbis para o áudio.

Preocupações com a acessibilidade

Os vídeos devem fornecer legendas e transcrições que descrevam com precisão o seu conteúdo (consulte Adicionando legendas e subtítulos a vídeos em HTML para obter mais informações sobre como implementá-las). As legendas permitem que pessoas com perda auditiva compreendam o conteúdo de áudio de um vídeo enquanto ele está sendo reproduzido, enquanto as transcrições permitem que pessoas que precisam de mais tempo possam revisar o conteúdo de áudio em um ritmo e formato que seja confortável para elas.

Vale ressaltar que, embora seja possível legendar mídia somente de áudio, isso só pode ser feito ao reproduzir áudio em um elemento <video>, uma vez que a região de vídeo do elemento é usada para apresentar as legendas. Este é um dos cenários especiais em que é útil reproduzir áudio em um elemento de vídeo.

Se serviços de legendagem automática forem usados, é importante revisar o conteúdo gerado para garantir que ele represente com precisão o vídeo original.

Além do diálogo falado, legendas e transcrições também devem identificar músicas e efeitos sonoros que transmitam informações importantes. Isso inclui emoção e tom:

14
00:03:14 --> 00:03:18
[Música rock dramática]

15
00:03:19 --> 00:03:21
[sussurrando] O que é aquilo lá longe?

16
00:03:22 --> 00:03:24
É… é um…

16 00:03:25 --> 00:03:32
[Barulho alto]
[Barulho de pratos]

As legendas não devem obstruir o assunto principal do vídeo. Elas podem ser posicionadas usando a configuração align VTT cue.

Sumário técnico

Categorias de conteúdo Conteúdo de fluxo, conteúdo de fraseado, conteúdo incorporado. Se possui o atributo controls: interactive conteúdo interativo e conteúdo palpável.
Conteúdo permitido

Se o elemento possui um atributo src : zero ou mais elementos <track>, seguido de conteúdo transparente que não contém elementos de mídia – ou seja nenhum <audio> ou <video>.

Caso contrário: zero ou mais elementos <source>, seguido de zero ou mais elementos <track>, seguido de conteúdo transparente que não contém elementos de mídia – ou seja, nenhum <audio> ou <video>.

Omissão de tag Nenhuma, ambas as tags de abertura e fechamento são obrigatórias.
Pais permitidos Qualquer elemento que aceite conteúdo embutido.
ARIA role implícito Nenhuma ARIA role correspondente
ARIA roles permitidas application
Interface DOM HTMLVideoElement

Especificações

Specification
HTML Standard
# the-video-element

Compatibilidade com navegadores

BCD tables only load in the browser

Veja também