YouTube Player API Reference for iframe Embeds

A API do player IFrame permite incorporar um player de vídeo do YouTube em seu website e controlar o player usando o JavaScript. Ao contrário das APIs de players em Flash e em JavaScript, que envolvem a incorporação de um objeto Flash em sua página da Web, as mensagens da API do IFrame postam conteúdo em uma tag <iframe> em sua página. Essa abordagem proporciona mais flexibilidade do que as APIs disponíveis anteriormente, pois ela permite que o YouTube forneça um player HTML5, em vez de um player Flash, para dispositivos móveis que não são compatíveis com Flash.

Usando as funções JavaScript da API, você pode enfileirar vídeos para reprodução; reproduzir, pausar ou interromper esses vídeos; ajustar o volume do player; ou ter informações sobre o vídeo que está sendo reproduzido. Você também pode adicionar listeners de eventos que serão executados em resposta a determinados eventos do player, como uma mudança de estado do player ou uma mudança de qualidade de reprodução do vídeo.

Esse guia explica como usar a API do IFrame. Ele identifica os diferentes tipos de eventos que a API pode enviar e explica como gravar listeners de eventos para responder a esses eventos. Além disso, detalha as diferentes funções JavaScript que você pode chamar para controlar o player de vídeo, além dos parâmetros do player que você pode usar para personalizar ainda mais o player.

Requisitos

O usuário final precisar estar usando um navegador que ofereça suporte ao recurso HTML5 postMessage. A maioria dos navegadores modernos oferece suporte ao postMessage, embora o Internet Explorer 7 não o faça.

É necessário que os players incorporados tenham uma Janela de visualização de pelo menos 200 px por 200 px. Se o player mostra controles, ele tem que ser grande o suficiente para exibir completamente os controles sem encolher a Janela visualização abaixo do tamanho mínimo. Recomendamos que players de 16:9 tenham pelo menos 480 pixels de largura e 270 pixels de altura.

Qualquer página da Web que use a API do IFrame também precisará implementar a seguinte função JavaScript:

onYouTubeIframeAPIReady – A API chamará essa função quando a página tiver terminado de baixar o JavaScript para a API do player, que permite que você use a API em sua página. Dessa forma, essa função cria os objetos do player que você deseja exibir quando a página for carregada.

Primeiros passos

O exemplo de página HTML abaixo cria um player incorporado que carregará um vídeo, irá reproduzi-lo por seis segundos e, em seguida, interromperá a reprodução. Os comentários numerados no HTML são explicados na lista abaixo do exemplo.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '360',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

A lista a seguir fornece mais detalhes sobre o exemplo acima:

Nessa seção, a tag <div> identifica o local na página em que a API do IFrame colocará o player de vídeo. O construtor do objeto do player, descrito na seção Carregar um player de vídeo, identifica a tag <div> pelo id para que a API possa coloca o <iframe> no local apropriado. Especificamente, a API do IFrame substituirá a tag <div> pela tag <iframe>.

Como alternativa, você também pode colocar o elemento <iframe> diretamente na página. A seção Carregar um player de vídeo contém informações sobre como executar este procedimento.
O código dessa seção carrega o código JavaScript da API do player IFrame. O exemplo usa a modificação DOM para baixar o código API para garantir que ele seja recuperado de forma assíncrona. O atributo <script> da tag async, que também permite downloads assíncronos, ainda não é compatível com todos os navegadores modernos, como discutido nesta resposta do Stack Overflow.
A função onYouTubeIframeAPIReady será executada assim que o código API do player for baixado. Essa parte do código define uma variável global, player, que se refere ao player de vídeo que está sendo incorporado, e a função constrói o objeto do player de vídeo.
A função onPlayerReady será executada quando o evento onReady for disparado. Nesse exemplo, a função indica que, quando o player de vídeo estiver pronto, ele começará a ser reproduzido.
A API chamará a função onPlayerStateChange quando o estado do player mudar, o que pode indicar que o player está sendo reproduzido, foi pausado, terminou de reproduz e assim por diante. A função indica que, quando o estado do player for 1 (em reprodução), o player deve ser reproduzido por seis segundos e, em seguida, chamar a função stopVideo para interromper o vídeo.

Carregar um player de vídeo

Depois de o código JavaScript da API ser carregado, a API chamará a função onYouTubeIframeAPIReady. Nesse ponto, você pode criar um objeto YT.Player para inserir um player de vídeo em sua página. O excerto HTML abaixo mostra a função onYouTubeIframeAPIReady do exemplo acima:

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '360',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

O construtor do player de vídeo especifica os seguintes parâmetros:

O primeiro parâmetro especifica o elemento DOM ou o id do elemento HTML em que a API inserirá a tag <iframe> que contém o player.

A API do IFrame substituirá o elemento especificado pelo elemento <iframe> que contém o player. Isso pode afetar o layout de sua página se o elemento que estiver sendo substituído tiver um estilo de exibição diferente do elemento <iframe> inserido. Por padrão, um <iframe> é exibido como um elemento inline-block.
O segundo parâmetro é um objeto que especifica as opções do player. O objeto contém as seguintes propriedades:
- width (número) – A largura do player de vídeo. O valor padrão é 640.
- height (número) – A altura do player de vídeo. O valor padrão é 360.
- videoId (string) – O ID do vídeo do YouTube que identifica o vídeo que o player carregará.
- playerVars (objeto) – As propriedades do objeto identificam os parâmetros do player que podem ser usados para personalizar o player.
- events (objeto) – As propriedades do objeto identificam os eventos que a API dispara e as funções (listeners de eventos) que ela chamará quando esses eventos ocorrerem. No exemplo, o construtor indica que a função onPlayerReady será executada quando o evento onReady for disparado e que a função onPlayerStateChange será executada quando o evento onStateChange for disparado.

Conforme mencionado na seção Primeiros passos, em vez de escrever um elemento <div> vazio em sua página, que o código JavaScript da API substituirá por um elemento <iframe>, você pode criar a própria tag <iframe>.

<iframe id="player" type="text/html" width="640" height="360"
  src="?url=http%3A%2F%2Fwww.youtube.com%2Fembed%2FM7lc1UVf-VE%3Fenablejsapi%3D1%26amp%3Borigin%3Dhttp%3A%2F%2Fexample.com"
  frameborder="0"></iframe>

Se você gravar a tag <iframe>, quando criar o objeto YT.Player, não precisará especificar os valores para width e height, que são especificados como atributos da tag <iframe>, ou parâmetros videoId e do player, que são especificados no URL src. Como medida de segurança extra, você também precisa incluir o parâmetro origin no URL, especificando o esquema de URL (http:// ou https://) e o domínio completo de sua página de hospedagem como o valor do parâmetro. Embora origin seja opcional, sua inclusão protege contra a injeção de JavaScript malicioso de terceiros em sua página e controla a invasão de seu player do YouTube.

Na seção Exemplos, há mais alguns exemplos para a criação de objetos do player de vídeo.

Operações

Para chamar os métodos da API do player, primeiro, tenha uma referência do objeto do player que deseja controlar. É possível conseguir essa referência criando um objeto YT.Player, como discutido nas seções Primeiros passos e Carregar um player de vídeo deste documento.

Funções

Funções de enfileiramento

As funções de enfileiramento permitem carregar e reproduzir um vídeo, uma playlist ou outra lista de vídeos. Se você estiver usando a sintaxe do objeto descrita abaixo para chamar essas funções, poderá também enfileirar ou carregar uma lista de resultados de pesquisa ou uma lista de vídeos enviados do usuário.

A API é compatível com duas sintaxes diferentes para chamar as funções de enfileiramento.

A sintaxe do argumento requer argumentos de função a serem listados em uma ordem prescrita.
A sintaxe do objeto permite passar um objeto como um parâmetro único e definir suas propriedades para os argumentos de função que você deseja definir. Além disso, a API pode ser compatível com outras funcionalidades que a sintaxe do argumento não suporta.

Por exemplo, a função loadVideoById pode ser chamada de uma das formas a seguir. A sintaxe do objeto é compatível com a propriedade endSeconds, que a sintaxe do argumento não suporta.

Sintaxe do argumento

loadVideoById("bHQqvYy5KYo", 5, "large")

Sintaxe do objeto

loadVideoById({'videoId': 'bHQqvYy5KYo',
               'startSeconds': 5,
               'endSeconds': 60,
               'suggestedQuality': 'large'});

Funções de enfileiramento de vídeos

cueVideoById

Sintaxe do argumento

player.cueVideoById(videoId:String,
                    startSeconds:Number,
                    suggestedQuality:String):Void

Sintaxe do objeto

player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number,
                     suggestedQuality:String}):Void

Esta função carrega a miniatura do vídeo especificado e prepara o player para reproduzir o vídeo. O player não solicita o FLV enquanto playVideo() ou seekTo() não é chamado.

O parâmetro obrigatório videoId especifica o ID do vídeo do YouTube a ser reproduzido. Nos feeds do vídeo da API de dados do YouTube, a tag <yt:videoid> especifica o ID.
O parâmetro opcional startSeconds aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser iniciada quando playVideo() é chamado. Se você especificar um valor startSeconds e chamar seekTo(), o player iniciará a reprodução no ponto especificado na chamada seekTo(). Quando o vídeo estiver indicado e pronto para ser reproduzido, o player transmitirá um evento video cued (5).
O parâmetro opcional endSeconds (compatível apenas com a sintaxe do objeto) aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser interrompida quando playVideo() é chamado. Se você especificar um valor endSeconds e chamar seekTo(), o valor endSeconds não estará mais disponível.
O parâmetro opcional suggestedQuality especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da função setPlaybackQuality para saber mais sobre a qualidade de reprodução.

loadVideoById

Argument syntax

player.loadVideoById(videoId:String,
                     startSeconds:Number,
                     suggestedQuality:String):Void

Object syntax

player.loadVideoById({videoId:String,
                      startSeconds:Number,
                      endSeconds:Number,
                      suggestedQuality:String}):Void

Esta função carrega e reproduz o vídeo especificado.

O parâmetro obrigatório videoId especifica o ID do vídeo do YouTube a ser reproduzido. Nos feeds do vídeo da API de dados do YouTube, a tag <yt:videoid> especifica o ID.
O parâmetro opcional startSeconds aceita um número flutuante/inteiro. Se ele for especificado, o vídeo será iniciado no frame principal mais próximo ao ponto especificado.
O parâmetro opcional endSeconds aceita um número decimal / inteiro. Se for especificado, o vídeo vai interromper a reprodução no ponto especificado.
O parâmetro opcional suggestedQuality especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da função setPlaybackQuality para saber mais sobre a qualidade de reprodução.

cueVideoByUrl

Argument syntax

player.cueVideoByUrl(mediaContentUrl:String,
                     startSeconds:Number,
                     suggestedQuality:String):Void

Object syntax

player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number,
                      suggestedQuality:String}):Void

Esta função carrega a miniatura do vídeo especificado e prepara o player para reproduzir o vídeo. O player não solicita o FLV enquanto playVideo() ou seekTo() não é chamado.

O parâmetro obrigatório mediaContentUrl especifica um URL do player do YouTube totalmente qualificado no formato http://www.youtube.com/v/VIDEO_ID?version=3. Nos feeds de vídeo da API de dados do YouTube, o atributo url da tag <media:content>, contém um URL de player totalmente qualificado quando o valor do atributo format da tag é 5.
O parâmetro opcional startSeconds aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser iniciada quando playVideo() é chamado. Se você especificar startSeconds e chamar seekTo(), o player iniciará a reprodução no ponto especificado na chamada seekTo(). Quando o vídeo estiver indicado e pronto para ser reproduzido, o player transmitirá um video cued evento (5).
O parâmetro opcional endSeconds (compatível apenas com a sintaxe do objeto) aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser interrompida quando playVideo() é chamado. Se você especificar um valor endSeconds e chamar seekTo(), o valor endSeconds não estará mais disponível.
O parâmetro opcional suggestedQuality especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da função setPlaybackQuality para saber mais sobre a qualidade de reprodução.

loadVideoByUrl

Argument syntax

player.loadVideoByUrl(mediaContentUrl:String,
                      startSeconds:Number,
                      suggestedQuality:String):Void

Object syntax

player.loadVideoByUrl({mediaContentUrl:String,
                       startSeconds:Number,
                       endSeconds:Number,
                       suggestedQuality:String}):Void

Esta função carrega e reproduz o vídeo especificado.

O parâmetro obrigatório mediaContentUrl especifica um URL do player do YouTube totalmente qualificado no formato http://www.youtube.com/v/VIDEO_ID?version=3. Nos feeds de vídeo da API de dados do YouTube, o atributo url da tag <media:content> contém um URL de player totalmente qualificado quando o valor do atributo format da tag é 5.
O parâmetro opcional startSeconds aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser iniciada. Se startSeconds (o número pode ser decimal) for especificado, o vídeo será iniciado a partir do frame principal mais próximo ao ponto especificado.
O parâmetro opcional endSeconds (compatível apenas com a sintaxe do objeto) aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser interrompida.
O parâmetro opcional suggestedQuality especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da função setPlaybackQuality para saber mais sobre a qualidade de reprodução.

Funções de enfileiramento para listas

As funções cuePlaylist e loadPlaylist permitem carregar e reproduzir uma playlist ou uma lista de vídeos. Se você estiver usando a sintaxe de objeto para chamar essas funções, você também pode enfileirar ou carregar uma lista de resultados da pesquisa ou uma lista de vídeos enviados por um usuário.

Como as funções operam de maneira diferente, dependendo se elas são chamadas usando a sintaxe do argumento ou a sintaxe do objeto, os dois métodos de chamada são documentados abaixo.

cuePlaylist

Argument syntax
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number,
                   suggestedQuality:String):Void
```
Enfileira a playlist especificada. Quando a playlist estiver indicada e pronta para ser reproduzida, o player transmitirá um evento video cued (5).
- O parâmetro obrigatório playlist especifica uma matriz de IDs do vídeo do YouTube. Nos feeds da API de dados do YouTube, a tag <yt:videoid> especifica um ID do vídeo.
- O parâmetro opcional index especifica o índice do primeiro vídeo da lista que será reproduzido. O parâmetro usa um índice com base em zero e o valor do parâmetro padrão é 0, portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da playlist.
- O parâmetro opcional startSeconds aceita um número flutuante/inteiro e especifica o ponto em que o primeiro vídeo da playlist deve ser reproduzido quando a função playVideo() for chamada. Se você especificar um valor startSeconds e chamar seekTo(), o player iniciará a reprodução no ponto especificado na chamada seekTo(). Se você indicar uma playlist e chamar a função playVideoAt(), a reprodução do player iniciará no começo do vídeo especificado.
- O parâmetro opcional suggestedQuality especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da função setPlaybackQuality para saber mais sobre a qualidade de reprodução.
Sintaxe do objeto
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String}):Void
```
Enfileira a lista de vídeos especificada. Ela pode ser uma playlist, um feed de resultados de pesquisa ou o feed de vídeos enviados de um usuário. Quando a lista estiver indicada e pronta para ser reproduzida, o player transmitirá um evento video cued (5).
- A propriedade opcional listType especifica o tipo de feed de resultados que você está recuperando. Os valores válidos são playlist, search e user_uploads. O valor padrão é playlist.
- A propriedade obrigatória list contém uma chave que identifica a lista particular de vídeos que o YouTube deve retornar.
  - Se o valor de propriedade listType for playlist, a propriedade list especificará o ID de playlist de reprodução ou uma matriz de IDs de vídeo. Nos feeds de API de dados do YouTube, a tag <yt:playlistid> especifica um ID de playlist e a tag <yt:videoid> especifica um ID de vídeo.
  - Se o valor de propriedade listType for search, a propriedade list especificará a consulta de pesquisa.
  - Se o valor de propriedade listType for user_uploads, a propriedade list identificará o usuário cujos vídeos enviados serão retornados.
- A propriedade opcional index especifica o índice do primeiro vídeo da lista que será reproduzida. O parâmetro usa um índice com base em zero e o valor do parâmetro padrão é 0, portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da lista.
- A propriedade opcional startSeconds aceita um número flutuante/inteiro e especifica o ponto em que o primeiro vídeo da playlist deve começar a ser reproduzido quando a função playVideo() for chamada. Se você especificar um valor startSeconds e chamar seekTo(), o player iniciará a reprodução no ponto especificado na chamada seekTo(). Se você indicar uma playlist e chamar a função playVideoAt(), a reprodução do player iniciará no começo do vídeo especificado.
- A propriedade opcional suggestedQuality especifica a qualidade de reprodução sugerida para os vídeos da lista. Veja a definição da função setPlaybackQuality para saber mais sobre a qualidade de reprodução.

loadPlaylist

Argument syntax
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String):Void
```
Esta função carrega a playlist especificada e a reproduz.
- O parâmetro obrigatório playlist especifica uma matriz de IDs do vídeo do YouTube. Nos feeds da API de dados do YouTube, a tag <yt:videoid> especifica um ID do vídeo.
- O parâmetro opcional index especifica o índice do primeiro vídeo da lista que será reproduzido. O parâmetro usa um índice com base em zero e o valor do parâmetro padrão é 0, portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da playlist.
- O parâmetro startSeconds opcional aceita um número flutuante/inteiro e especifica o ponto em que o primeiro vídeo da playlist deve começar a ser reproduzido.
- O parâmetro opcional suggestedQuality especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da função setPlaybackQuality para saber mais sobre a qualidade de reprodução.
Object syntax
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number,
                     suggestedQuality:String}):Void
```
Esta função carrega a lista especificada e a reproduz. Ela pode ser uma playlist, um feed de resultados de pesquisa ou o feed de vídeos enviados de um usuário.
- A propriedade opcional listType especifica o tipo de feed de resultados que você está recuperando. Os valores válidos são playlist, search e user_uploads. O valor padrão é playlist.
- A propriedade obrigatória list contém uma chave que identifica a lista particular de vídeos que o YouTube deve retornar.
  - Se o valor de propriedade listType for playlist, a propriedade list especificará o ID da playlist de reprodução ou uma matriz de IDs de vídeo. Nos feeds de API de dados do YouTube, a tag <yt:playlistid> especifica um ID de playlist e a tag <yt:videoid> especifica um ID de vídeo.
  - Se o valor de propriedade listType for search, a propriedade list especificará a consulta de pesquisa.
  - Se o valor de propriedade listType for user_uploads, a propriedade list identificará o usuário cujos vídeos enviados serão retornados.
- A propriedade opcional index especifica o índice do primeiro vídeo da lista que será reproduzida. O parâmetro usa um índice com base em zero e o valor do parâmetro padrão é 0, portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da lista.
- A propriedade opcional startSeconds aceita um número flutuante/inteiro e especifica o ponto em que o primeiro vídeo da lista deve começar a ser reproduzido.
- A propriedade opcional suggestedQuality especifica a qualidade de reprodução sugerida para os vídeos da lista. Veja a definição da função setPlaybackQuality para saber mais sobre a qualidade de reprodução.

Controles da reprodução e configurações do player

Reproduzir um vídeo

player.playVideo():Void: Reproduz o vídeo atualmente indicado/carregado. O estado final do player após esta função ser executada será playing (1).

Observação: a reprodução só é considerada na contagem de visualização oficial do vídeo se ela for iniciada por um botão nativo de reprodução no player.

player.pauseVideo():Void: Pausa o vídeo que está sendo reproduzido. Após a execução dessa função, o estado final do player será paused (2), a não ser que o player esteja no estado ended (0) quando a função é chamada e, neste caso, o estado do player não será alterado.

player.stopVideo():Void: Interrompe e cancela o carregamento do vídeo atual. Esta função deve ser reservada para situações raras em que você sabe que o usuário não assistirá a vídeo adicional no player. Se sua intenção for pausar o vídeo, basta chamar a função pauseVideo. Se você quer alterar o vídeo que o player está reproduzindo, você pode chamar uma das funções de enfileiramento sem chamar stopVideo primeiro.

Importante: ao contrário da função pauseVideo, que deixa o player no estado paused (2), a função stopVideo pode colocar o player em um estado de não reprodução, inclusive ended (0), paused (2), video cued (5) ou unstarted (-1).

player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void

Procura um ponto especificado no vídeo. Se o player estiver em pausa quando a função for chamada, ele permanecerá em pausa. Se a função for chamada a partir de outro estado (playing, video cued, etc), o player reproduzirá o vídeo.

O parâmetro seconds identifica o ponto a partir do qual o player deve continuar.

O player continuará a partir do frame principal mais próximo antes desse ponto, a menos que ele já tenha baixado a parte do vídeo que o usuário está buscando. Nesse caso, o player continuará a partir do frame principal mais próximo antes ou depois do ponto especificado, conforme ditado pelo método seek() do objeto NetStream do player Flash. Consulte a documentação do Adobe para mais informações.
O parâmetro allowSeekAhead determina se o player fará uma nova solicitação ao servidor se o parâmetro seconds especificar um ponto fora dos dados do vídeo atualmente armazenado em buffer.

Recomendamos que você defina esse parâmetro como false enquanto o usuário arrasta o mouse ao longo da barra de progresso de um vídeo e configure-o como true quando o usuário soltar o mouse. Essa abordagem permite que um usuário role para diferentes pontos de um vídeo sem solicitar novos fluxos de vídeo rolando por pontos sem buffer. Quando o usuário libera o botão do mouse, o player avança para o ponto desejado no vídeo e solicita um novo fluxo de vídeo, se necessário.

player.clearVideo():Void: Limpa a exibição do vídeo. Esta função é útil se você deseja limpar o restante do vídeo depois de chamar stopVideo(). Seu uso foi suspenso na API do player ActionScript 3.0.

Reproduzir um vídeo em uma playlist

player.nextVideo():Void

Esta função carrega e reproduz o próximo vídeo da playlist.

Se player.nextVideo() é chamado quando o último vídeo da playlist estiver sendo assistido e a playlist estiver configurada para reproduzir continuamente loop, o player carregará e reproduzirá o primeiro vídeo da lista.
Se player.nextVideo() é chamado quando o último vídeo da playlist estiver sendo assistido e a lista não estiver configurada para reproduzir continuamente, a reprodução será encerrada.

player.previousVideo():Void

Esta função carrega e reproduz o vídeo anterior da playlist.

Se player.previousVideo() é chamado quando o primeiro vídeo da playlist estiver sendo assistido e a playlist estiver configurada para reproduzir continuamente loop, o player carregará e reproduzirá o último vídeo da lista.
Se player.previousVideo() é chamado quando o primeiro vídeo da playlist estiver sendo assistido e a lista não estiver configurada para reproduzir continuamente, o player reiniciará o primeiro vídeo desde o início.

player.playVideoAt(index:Number):Void

Esta função carrega e reproduz o próximo vídeo da playlist.

O parâmetro obrigatório index especifica o índice do vídeo que você deseja reproduzir na playlist. O parâmetro usa um índice com base em zero, portanto, o valor 0 identifica o primeiro vídeo da lista. Se você tornar a playlist aleatória, esta função reproduzirá o vídeo na posição especificada na lista aleatória.

Alterar o volume do player

player.mute():Void: Desativa o som do player.

player.unMute():Void: Ativa o som do player.

player.isMuted():Boolean: Retorna true se o player estiver no mudo. Em caso negativo, retorna false.

player.setVolume(volume:Number):Void: Define o volume. Aceita um número inteiro entre 0 e 100.

player.getVolume():Number: Retorna o volume atual do player, um número inteiro entre 0 e 100. getVolume() retornará o volume mesmo se o player estiver no mudo.

Definir o tamanho do player

player.setSize(width:Number, height:Number):Object: Define o tamanho em pixels do <iframe> que contém o player.

Definir a taxa de reprodução

player.getPlaybackRate():Number: Esta função recupera a taxa de reprodução do vídeo em reprodução. A taxa de reprodução padrão é 1, o que indica que o vídeo está sendo reproduzido em velocidade normal. As taxas de reprodução incluem valores como 0.25, 0.5, 1, 1.5 e 2.

player.setPlaybackRate(suggestedRate:Number):Void: Esta função define a taxa de reprodução sugerida para o vídeo atual. Se a taxa de reprodução for alterada, essa alteração será aplicada somente ao vídeo que já estiver indicado ou sendo reproduzido. Se você definir a taxa de reprodução de um vídeo indicado, essa taxa ainda estará em vigor quando a função playVideo for chamada ou quando o usuário iniciar a reprodução diretamente nos controles do player. Além disso, as funções de chamada para indicar ou carregar vídeos ou playlists (cueVideoById, loadVideoById etc) redefinirão a taxa de reprodução para 1.

Chamar essa função não garante que a qualidade da reprodução será realmente alterada. No entanto, se a taxa de reprodução for realmente alterada, o evento onPlaybackRateChange será disparado e seu código responderá ao evento, em vez de chamar a função setPlaybackRate.

O método getAvailablePlaybackRates retornará as possíveis taxas de reprodução do vídeo sendo reproduzido. No entanto, se você definir o parâmetro suggestedRate para um número inteiro não compatível ou para um valor decimal, o player arredondará esse valor para o valor inferior compatível mais próximo de 1.

player.getAvailablePlaybackRates():Array: Esta função retorna o conjunto de taxas de reprodução em que o vídeo atual está disponível. O valor padrão é 1, o que indica que o vídeo está sendo reproduzido em velocidade normal.

A função retorna uma matriz de números ordenados da velocidade de reprodução mais lenta para a mais rápida. Mesmo que o player não seja compatível com as velocidades de reprodução variáveis, é necessário que a matriz sempre contenha pelo menos um valor (1).

Definir o comportamento da reprodução de listas

player.setLoop(loopPlaylists:Boolean):Void

Esta função indica se o player de vídeo deve reproduzir uma lista continuamente ou se deve interromper a reprodução após a conclusão do último vídeo da lista. O comportamento padrão é que as playlists não sejam reproduzidas em loop.

Essa configuração persistirá mesmo se você carregar ou indicar uma playlist diferente. Se você carregar uma playlist, chame a função setLoop com um valor true e carregue uma segunda lista, que também será reproduzida em loop.

O parâmetro obrigatório loopPlaylists identifica o comportamento em loop.

Se o valor do parâmetro for true, o player de vídeo reproduzirá as listas de . Depois de reproduzir o último vídeo, o player voltará para o início da lista e reproduzirá novamente.
Se o valor do parâmetro for false, as reproduções serão concluídas depois que o player reproduzir o último vídeo de uma lista.

player.setShuffle(shufflePlaylist:Boolean):Void

Esta função indica se os vídeos de uma lista devem ser misturados para que sejam reproduzidos em uma ordem diferente da designada pelo criador da lista. Se você misturar uma playlist depois de ela já ter começado a ser reproduzida, ela será reordenada enquanto o vídeo for reproduzido. O próximo vídeo a ser reproduzido será selecionados com base na lista reordenada.

Esta configuração não persistirá se você carregar ou indicar uma playlist diferente. Se você carregar uma playlist, chame a função setShuffle e carregue uma segunda lista, que não será misturada.

O parâmetro obrigatório shufflePlaylist indica se o YouTube deve reproduzir a playlist aleatoriamente.

Se o valor do parâmetro for true, o YouTube misturará a ordem da playlist. Se você instruir a função para misturar uma lista de reprodução que já estiver em ordem aleatória, o YouTube misturará a ordem novamente.
Se o valor do parâmetro for false, o YouTube mudará a playlist para sua ordem original.

Status da reprodução

player.getVideoLoadedFraction():Float: Retorna um número entre 0 e 1, que especifica a porcentagem do vídeo que o player mostra como armazenado em buffer. Este método retorna um número mais confiável do que os métodos getVideoBytesLoaded e getVideoBytesTotal, com uso suspenso.

player.getPlayerState():Number

Retorna o estado do player. Os valores possíveis são:

-1 – não iniciado
0 – encerrado
1 – em reprodução
2 – em pausa
3 – armazenando em buffer
5 – vídeo indicado

player.getCurrentTime():Number: Retorna o tempo decorrido em segundos desde que o início da reprodução do vídeo.

player.getVideoStartBytes():Number: Uso suspenso em 31 de outubro de 2012. Retorna o número de bytes a partir do qual o arquivo do vídeo começou a ser carregado. Agora, este método sempre retorna um valor 0. Exemplo: o usuário avança até um ponto que ainda não foi carregado e o player faz uma nova solicitação para reproduzir um segmento do vídeo que ainda não foi carregado.

player.getVideoBytesLoaded():Number: Uso suspenso em 18 de julho de 2012. Usar o método getVideoLoadedFraction para determinar a porcentagem de vídeo que foi armazenada em buffer.

Este método retorna um valor entre 0 e 1000 que se aproxima da quantidade do vídeo que foi carregada. Era possível calcular a fração do vídeo carregado ao dividir o valor de getVideoBytesLoaded pelo valor de getVideoBytesTotal.

player.getVideoBytesTotal():Number: Uso suspenso em 18 de julho de 2012. Usar o método getVideoLoadedFraction para determinar a porcentagem de vídeo que foi armazenada em buffer.

Retorna o tamanho em bytes do vídeo sendo carregado/reproduzido no momento ou uma aproximação do tamanho.

Este método sempre retorna o valor 1000. Era possível calcular a fração do vídeo carregado ao dividir o valor de getVideoBytesLoaded pelo valor de getVideoBytesTotal.

Qualidade da reprodução

player.getPlaybackQuality():String: Esta função recupera a qualidade real do vídeo atual. Possíveis valores retornados: highres, hd1080, hd720, large, medium e small. Ela também retornará undefined se não houver vídeo atual.

player.setPlaybackQuality(suggestedQuality:String):Void

Esta função define a qualidade de vídeo sugerida para o vídeo atual. A função faz com que o vídeo seja atualizado, em sua posição atual, com a nova qualidade. Se a qualidade de reprodução for alterada, ela só mudará para o vídeo reproduzido. Chamar essa função não garante que a qualidade da reprodução será realmente alterada. No entanto, se a qualidade de reprodução for alterada, o evento onPlaybackQualityChange será disparado e seu código responderá ao evento, em vez de chamar a função setPlaybackQuality.

O valor do parâmetro suggestedQuality pode ser small, medium, large, hd720,hd1080, highres ou default. Recomendamos que você configure o valor do parâmetro como default, que instrui o YouTube a selecionar a qualidade de reprodução mais adequada, o que variará para diferentes usuários, vídeos, sistemas e outras condições de reprodução.

Quando você sugerir uma qualidade de reprodução para um vídeo, a qualidade sugerida terá efeito apenas no vídeo em questão. É necessário selecionar uma qualidade de reprodução que corresponda ao tamanho de seu player de vídeo. Por exemplo, se a página exibir um player de vídeo de 1.280 px por 720 px, um vídeo de qualidade hd720, na verdade, parecerá melhor do que um de qualidade hd1080. Recomendamos chamar a função getAvailableQualityLevels() para determinar quais níveis de qualidade estão disponíveis para um vídeo.

A lista abaixo mostra os níveis qualidade de reprodução que correspondem a diferentes tamanhos de player padrão. Recomendamos que você configure a altura de seu player de vídeo para um dos valores listados abaixo e que dimensione seu player para usar a proporção 16:9. Conforme dito acima, mesmo se você escolher um tamanho padrão do player, também recomendamos que você configure o valor do parâmetro suggestedQuality como default para permitir que o YouTube selecione a qualidade de reprodução mais adequada.

Nível de qualidade small: a altura do player é 240 px e suas dimensões são no mínimo 320 px por 240 px para a proporção 4:3.
Nível de qualidade medium: a altura player é 360 px e suas dimensões são 640 px por 360 px (para a proporção 16:9) ou 480 px por 360 px (para a proporção 4:3).
Nível de qualidade large: a altura do layer é 480 px e suas dimensões são 853 px por 480 px (para proporção 16:9) ou 640 px por 480 px (para a proporção 4:3).
Nível de qualidade hd720: a altura do player é 720 px e suas dimensões são 1.280 px por 720 px (para a proporção 16:9) ou 960 px por 720 px (para a proporção 4:3).
Nível de qualidade hd1080: altura do player é 1.080 px e suas dimensões são 1.920 px por 1.080 px (para a proporção 16:9) ou 1.440 px por 1.080 px (para a proporção 4:3).
Nível de qualidade highres: a altura do player é maior que 1.080 px, o que significa que sua proporção é maior que 1.920 px por 1.080 px.
Nível de qualidade default: o YouTube seleciona a qualidade de reprodução adequada. Esta configuração reverte de maneira efetiva o nível de qualidade para o estado padrão e anula todos os esforços anteriores para configurar a qualidade de reprodução usando as funções cueVideoById, loadVideoById ou setPlaybackQuality.

Se você chamar a função setPlaybackQuality com um nível suggestedQuality indisponível para o vídeo, então a qualidade será definida para o próximo nível mais baixo que estiver disponível. Por exemplo, se você solicitar um nível de qualidade large e ele não estiver disponível, a qualidade de reprodução será configurada para medium (contanto que ele esteja disponível).

Além disso, a definição de suggestedQuality como um valor que não é um nível de qualidade reconhecido é o mesmo que definir suggestedQuality como default .

player.getAvailableQualityLevels():Array: Esta função retorna o conjunto de formatos de qualidade no qual o vídeo atual está disponível. É possível usar essa função para determinar se há uma qualidade superior à que o usuário está exibindo o vídeo, e o player pode exibir um botão ou outro elemento que permita ao usuário ajustar a qualidade.

A função retorna uma matriz de strings ordenadas da qualidade mais alta para a mais baixa. Possíveis valores dos elementos da matriz: highres, hd1080, hd720, large, medium e small. Essa função retorna uma matriz vazia se não houver um vídeo sendo reproduzido.

Seu cliente não alternará automaticamente para a qualidade mais alta (ou mais baixa) ou para um nome de formato desconhecido. O YouTube pode expandir a lista de níveis de qualidade para incluir formatos que talvez não sejam adequados ao contexto de seu player. Da mesma forma, o YouTube pode remover opções de qualidade que prejudiquem a experiência do usuário. Ao assegurar que seu cliente alterne somente para formatos disponíveis e conhecidos, você pode garantir que o desempenho do cliente não será afetado pela introdução de novos níveis de qualidade e pela remoção de níveis de qualidade que não sejam adequados ao contexto do player.

Recuperar informações do vídeo

player.getDuration():Number: Retorna a duração em segundos do vídeo que está sendo reproduzido. Observe que getDuration() retornará 0 até que os metadados do vídeo sejam carregados, o que normalmente ocorre logo após o início da reprodução do vídeo.

Se o vídeo que estiver sendo reproduzido for um evento ao vivo, a função getDuration() retornará o tempo decorrido desde o início do stream do vídeo ao vivo. Especificamente, essa é a quantidade de tempo que o vídeo foi transmitido sem ser redefinido ou interrompido. Esta duração é geralmente maior do que a tempo real do evento, uma vez que o streaming pode começar antes da hora de início do evento.

player.getVideoUrl():String: Retorna o URL YouTube.com para o vídeo carregado/em reprodução no momento.

player.getVideoEmbedCode():String: Retorna o código incorporado para o vídeo carregado/em reprodução no momento.

Recuperar informações da playlist

player.getPlaylist():Array: Esta função retorna uma matriz de IDs de vídeo na playlist em sua ordem atual. Por padrão, ela retornará IDs de vídeo na ordem designada pelo proprietário da playlist. No entanto, se você chamou a função setShuffle para reproduzir a playlist aleatoriamente, o valor de retorno da função getPlaylist() refletirá a ordem de reprodução aleatória.

player.getPlaylistIndex():Number

Esta função retorna o índice do vídeo da playlist em reprodução no momento.

Se você não reproduziu a playlist aleatoriamente, o valor de retorno identificará a posição em que o criador de conteúdo da playlist colocou o vídeo. O valor de retorno usa um índice com base em zero, portanto, o valor 0 identifica o primeiro vídeo da playlist.
Se você misturou a playlist, o valor de retorno identificará a ordem do vídeo dentro da lista aleatória.

Adicionar ou remover uma escuta de evento

player.addEventListener(event:String, listener:String):Void: Adiciona uma função de listener para o event especificado. A seção Eventos abaixo identifica os diferentes eventos que o player pode disparar. O listener é uma string que especifica a função que será executada quando o evento especificado for disparado.

player.removeEventListener(event:String, listener:String):Void: Remove uma função de escuta para o event especificado. A listener é uma string que identifica a função que será executada quando o evento especificado for disparado.

Acessar e modificar nós DOM

player.getIframe():Object: Este método retorna o nó DOM para o <iframe> integrado.

player.destroy():Void: Remove o <iframe> que contém o player.

Eventos

A API dispara eventos para notificar seu aplicativo sobre mudanças no player integrado. Conforme mencionado na seção anterior, você pode se inscrever em eventos ao adicionar um listener de eventos criar o objeto YT.Player. Também é possível usar a função addEventListener.

A API passará um objeto de evento como único argumento para cada uma dessas funções. O objeto de evento tem as seguintes propriedades:

O evento target identifica o player de vídeo que corresponde ao evento.
A propriedade data do evento especifica um valor relevante para o evento. O evento onReady não especifica uma propriedade data.

A lista a seguir define os eventos que a API dispara:

onReady

Esse evento é disparado sempre que um player terminar de carregar e estiver pronto para começar a receber chamadas de API. Seu aplicativo deve implementar essa função se você quiser executar algumas operações automaticamente, como a reprodução do vídeo ou a exibição de informações sobre o vídeo, assim que o player estiver pronto.

O exemplo abaixo mostra um exemplo de função para lidar com esse evento. O objeto de evento que a API passa para a função tem uma propriedade target, que identifica o player. A função recupera o código de incorporação para o vídeo carregado no momento, começa a reproduzir o vídeo e exibe o código de incorporação no elemento de página que tiver um valor id de embed-code.

function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}

onStateChange

Esse evento é disparado sempre que o estado do player for alterado. A propriedade data do objeto de evento que a API passa para sua função de listener de eventos especificará um número inteiro que corresponde ao novo estado do player. Os valores possíveis são:

-1 (não iniciado)
0 (encerrado)
1 (em reprodução)
2 (em pausa)
3 (armazenando em buffer)
5 (vídeo indicado).

Quando o player carrega um vídeo pela primeira vez, ele transmite um evento não iniciado unstarted (-1). Quando o vídeo estiver indicado e pronto para ser reproduzido, o player transmitirá um evento de vídeo indicado video cued (5). Em seu código, você pode especificar valores de números inteiros ou pode usar uma das seguintes variáveis namespaced:

YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED

onPlaybackQualityChange

Esse evento é disparado sempre que a qualidade de reprodução do vídeo for alterada. Por exemplo, se você chamar a função setPlaybackQuality(suggestedQuality), esse evento será disparado se a qualidade de reprodução for realmente alterada. Seu aplicativo responderá ao evento e não pode assumir que a qualidade será automaticamente alterada quando a função setPlaybackQuality(suggestedQuality) é chamada. Da mesma forma, seu código não deve supor que a qualidade de reprodução será alterada somente como resultado de uma chamada explícita a setPlaybackQuality ou a qualquer outra função que permita definir uma qualidade de reprodução sugerida.

O valor de propriedade data do objeto de evento que a API passa para a função de listener de eventos será uma string que identifica a nova qualidade de reprodução. Os valores possíveis são:

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: Esse evento é disparado sempre que a taxa de reprodução do vídeo for alterada. Por exemplo, se você chamar a função setPlaybackRate(suggestedRate), esse evento será disparado se a taxa de reprodução for realmente alterada. Seu aplicativo responderá ao evento e não pode assumir que a taxa de reprodução será automaticamente alterada quando a função setPlaybackRate(suggestedRate) é chamada. Da mesma forma, seu código não pode assumir que a taxa de reprodução de vídeo será alterada somente como resultado de uma chamada explícita a setPlaybackRate.

O valor de propriedade data do objeto de evento que a API passa para a função de listener de eventos será um número que identifica a nova taxa de reprodução. O método getAvailablePlaybackRates retorna uma lista das taxas de reprodução válidas para o vídeo indicado ou em reprodução no momento.

onError

Esse evento será disparado se ocorrer um erro no player. A API passará um objeto event para a função de listener de evento. A propriedade data desse objeto especificará um número inteiro que identifica o tipo de erro ocorrido. Os valores possíveis são:

2 – A solicitação contém um valor de parâmetro inválido. Por exemplo, este erro ocorre se você especificar um ID de vídeo que não tem 11 caracteres, ou se o ID de vídeo contém caracteres inválidos, como pontos de exclamação ou asteriscos.
5 – O conteúdo solicitado não pode ser reproduzido em um player HTML5, ou ocorreu outro erro relacionado ao player HTML5.
100 – O vídeo solicitado não foi encontrado. Esse erro ocorrerá quando um vídeo tiver sido removido (por qualquer motivo) ou marcado como privado.
101 - O proprietário do vídeo solicitado não permite que ele seja reproduzido em players incorporados.
150 – Esse erro é o mesmo que o 101. É apenas um erro 101 disfarçado.

onApiChange

Esse evento é disparado para indicar que o player carregou (ou descarregou) um módulo com métodos de API expostos. Seu aplicativo pode ouvir esse evento e, em seguida, sondar o player para determinar quais opções estão expostas para o módulo recém-carregado. Seu aplicativo pode, então, recuperar ou atualizar as configurações existentes para essas opções.

O comando a seguir recupera uma matriz de nomes de módulos para a qual você pode definir as opções de player:

player.getOptions();

Atualmente, o único módulo para o qual você pode definir opções é o cc, que lida com closed caption no player. Ao receber um evento onApiChange, seu aplicativo pode usar o seguinte comando para determinar quais opções podem ser definidas para o módulo cc:

player.getOptions('cc');

Ao sondar o player com esse comando, é possível confirmar se as opções que você deseja acessar estão, de fato, acessíveis. Os seguintes comandos recuperam e atualizam as opções de módulo:

Recuperar uma opção:
player.getOption(module, option);

configurar uma opção
player.setOption(module, option, value);

A tabela abaixo lista as opções compatíveis com a API:

Módulo	Opção	Descrição
cc	fontSize	Essa opção ajusta o tamanho da fonte das legendas exibidas no player. Os valores válidos são `-1`, `0`, `1`, `2` e `3`. O tamanho padrão é `0` e o menor tamanho é `-1`. A definição dessa opção como um número inteiro menor que `-1` fará com que o menor tamanho de legenda seja exibido, enquanto que a definição dessa opção como um número inteiro maior que `3` fará com que o maior tamanho de legenda seja exibido.
cc	reload	Essa opção recarrega os dados de closed caption para o vídeo que estiver sendo reproduzido. O valor será `null` se você recuperar o valor da opção. Defina o valor para `true` para recarregar os dados de closed caption.

Considerações de dispositivos móveis

Reprodução automática e reprodução com script

Em determinados navegadores móveis (como Chrome e Safari), o elemento HTML5 <video> só permite que a reprodução ocorra se ela for iniciada por uma interação do usuário (como tocar no player). Veja um trecho da documentação da Apple:

"Aviso: para impedir downloads não solicitados por redes celulares à custa do usuário, a mídia incorporada não pode ser reproduzida automaticamente no Safari no iOS. O usuário sempre inicia a reprodução."

Devido a esta restrição, funções e parâmetros, como autoplay, playVideo() e loadVideoById(), não funcionarão em todos os ambientes de dispositivos móveis.

Exemplos

Criar objetos YT.Player

Exemplo 1: reprodução com volume alto

Este exemplo cria um player de vídeo de 1.280 px por 720 px. O listener do evento onReady chama a função setVolume para ajustar o volume na configuração mais alta.

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

Exemplo 2: este exemplo define os parâmetros do player para reproduzir o vídeo automaticamente quando ele carregar e para ocultar os controles do player de vídeo. Ele também adiciona listeners de eventos a todos os eventos que a API transmite.

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

Histórico de revisão

Esta seção lista as alterações na API do player IFrame do YouTube e as atualizações da documentação. Inscreva-se neste changelog..