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.

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. Também é possível adicionar listeners de eventos que serão executados em resposta a determinados eventos do player, como uma mudança de estado.

Este guia explica como usar a API IFrame. Ela identifica os diferentes tipos de eventos que a API pode enviar e explica como escrever 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 navegador do usuário precisa oferecer suporte ao recurso postMessage do HTML5. A maioria dos navegadores modernos oferece suporte a postMessage.

É 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.

Também será necessário implementar a seguinte função JavaScript em todas as páginas da Web que usarem API do IFrame:

  • onYouTubeIframeAPIReady: a API vai chamar essa função quando a página terminar de fazer o download do JavaScript da API do player, o que permite usar a API na 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: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          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:

  1. A tag <div> nesta seção identifica o local na página em que a API IFrame vai colocar o player de vídeo. O construtor do objeto player, descrito na seção Carregando um player de vídeo, identifica a tag <div> pelo id para garantir que a API coloque o <iframe> no local adequado. Especificamente, a API IFrame vai substituir a tag <div> pela tag <iframe>.

    Como alternativa, você também pode colocar o elemento <iframe> diretamente na página. A seção Como carregar um player de vídeo explica como fazer isso.

  2. 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 async da tag <script>, que também permite downloads assíncronos, ainda não é compatível com todos os navegadores modernos, conforme discutido nesta resposta do Stack Overflow.

  3. A função onYouTubeIframeAPIReady será executada assim que o código da API do player for transferido por download. Essa parte do código define uma variável global, player, que se refere ao player de vídeo que você está incorporando, e a função constrói o objeto do player de vídeo.

  4. A função onPlayerReady será executada quando o evento onReady for acionado. Nesse exemplo, a função indica que, quando o player de vídeo estiver pronto, ele começará a ser reproduzido.

  5. A API vai chamar a função onPlayerStateChange quando o estado do player mudar, o que pode indicar que ele está sendo reproduzido, pausado, concluído e assim por diante. A função indica que, quando o estado do player é 1 (reprodução), ele 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 que o código JavaScript da API for carregado, ela vai chamar a função onYouTubeIframeAPIReady. Nesse ponto, você poderá criar um objeto YT.Player para inserir um player de vídeo na página. O trecho de HTML abaixo mostra a função onYouTubeIframeAPIReady do exemplo acima:

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

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

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

    A API IFrame vai substituir o elemento especificado pelo elemento <iframe> que contém o player. Isso pode afetar o layout da página se o elemento substituído tiver um estilo de exibição diferente do elemento <iframe> inserido. Por padrão, um <iframe> é exibido como um elemento inline-block.

  2. 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 é 390.
    • videoId (string): o ID do vídeo do YouTube que identifica o vídeo que será carregado pelo player.
    • 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 a API vai chamar quando esses eventos ocorrerem. No exemplo, o construtor indica que a função onPlayerReady será executada quando o evento onReady for acionado e que a função onPlayerStateChange será executada quando o evento onStateChange for acionado.

Como mencionado na seção Introdução, em vez de escrever um elemento <div> vazio na página, que o código JavaScript da API do player vai substituir por um elemento <iframe>, você pode criar a tag <iframe>. O primeiro exemplo na seção Exemplos mostra como fazer isso.

<iframe id="player" type="text/html" width="640" height="390"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

Se você escrever a tag <iframe>, não vai precisar especificar valores para width e height, que são especificados como atributos da tag <iframe>, ou para videoId e parâmetros do player, que são especificados no URL src.YT.Player Como medida de segurança extra, também é necessário incluir o parâmetro origin no URL, especificando o esquema de URL (http:// ou https://) e o domínio completo da página de destino como o valor do parâmetro. Embora origin seja opcional, incluí-lo protege contra a injeção de JavaScript de terceiros maliciosos na sua página e o controle do player do YouTube.

Para outros exemplos de construção de objetos de player de vídeo, consulte Exemplos.

Operações

Para chamar os métodos da API do player, primeiro, tenha uma referência do objeto do player que deseja controlar. Para conseguir a referência, crie um objeto YT.Player, conforme discutido nas seções Introdução e Carregando um player de vídeo deste documento.

Funções

Funções de enfileiramento

Com as funções de enfileiramento, é possível carregar e reproduzir um vídeo, uma playlist ou uma outra lista de vídeos. Se você estiver usando a sintaxe de objeto descrita abaixo para chamar essas funções, também poderá colocar em fila ou carregar uma lista de vídeos enviados por um 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 seguintes maneiras. A sintaxe do objeto é compatível com a propriedade endSeconds, que a sintaxe do argumento não é.

  • Sintaxe de argumentos

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

  • Sintaxe de objetos

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

Funções de enfileiramento de vídeos

cueVideoById

  • Sintaxe de argumentos

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

  • Sintaxe de objetos

    player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number}):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 até que playVideo() ou seekTo() seja chamado.

  • O parâmetro videoId obrigatório especifica o ID do vídeo do YouTube que será reproduzido. Na API Data do YouTube, a propriedade id de um recurso video especifica o ID.
  • O parâmetro startSeconds opcional aceita um número inteiro/float e especifica o tempo em que o vídeo vai começar a ser reproduzido quando playVideo() for chamado. Se você especificar um valor startSeconds e chamar seekTo(), o player vai ser reproduzido a partir do tempo especificado na chamada seekTo(). Quando o vídeo estiver pronto para ser reproduzido, o player vai transmitir um evento video cued (5).
  • O parâmetro endSeconds opcional, que só tem suporte na sintaxe de objetos, aceita um número/float e especifica o momento em que o vídeo deve parar de ser reproduzido quando playVideo() é chamado. Se você especificar um valor endSeconds e chamar seekTo(), o valor endSeconds não vai mais estar em vigor.

loadVideoById

  • Sintaxe de argumentos

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

  • Sintaxe de objetos

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

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

  • O parâmetro videoId obrigatório especifica o ID do vídeo do YouTube que será reproduzido. Na API Data do YouTube, a propriedade id de um recurso video especifica o ID.
  • O parâmetro startSeconds opcional 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 endSeconds opcional aceita um número flutuante/inteiro. Se for especificado, o vídeo vai interromper a reprodução no ponto especificado.

cueVideoByUrl

  • Sintaxe de argumentos

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

  • Sintaxe de objetos

    player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number}):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 até que playVideo() ou seekTo() seja chamado.

  • O parâmetro mediaContentUrl obrigatório especifica um URL do player do YouTube totalmente qualificado no formato http://www.youtube.com/v/VIDEO_ID?version=3.
  • O parâmetro startSeconds opcional aceita um número inteiro/float e especifica o tempo em que o vídeo vai começar a ser reproduzido quando playVideo() for chamado. Se você especificar startSeconds e chamar seekTo(), o player vai ser reproduzido a partir do tempo especificado na chamada seekTo(). Quando o vídeo estiver pronto para ser reproduzido, o player vai transmitir um evento video cued (5).
  • O parâmetro endSeconds opcional, que só tem suporte na sintaxe de objetos, aceita um número/float e especifica o momento em que o vídeo deve parar de ser reproduzido quando playVideo() é chamado. Se você especificar um valor endSeconds e chamar seekTo(), o valor endSeconds não vai mais estar em vigor.

loadVideoByUrl

  • Sintaxe de argumentos

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

  • Sintaxe de objetos

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

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

  • O parâmetro mediaContentUrl obrigatório especifica um URL do player do YouTube totalmente qualificado no formato http://www.youtube.com/v/VIDEO_ID?version=3.
  • O parâmetro startSeconds opcional aceita um número inteiro/float e especifica o momento em que o vídeo deve começar a ser reproduzido. Se startSeconds (o número pode ser um número com ponto flutuante) for especificado, o vídeo vai começar no keyframe mais próximo do tempo especificado.
  • O parâmetro endSeconds opcional, que só tem suporte na sintaxe de objetos, aceita um número inteiro/float e especifica o momento em que o vídeo deve parar de ser reproduzido.

Funções de enfileiramento para listas

As funções cuePlaylist e loadPlaylist permitem carregar e reproduzir uma playlist. Se você estiver usando a sintaxe de objeto para chamar essas funções, também poderá colocar em fila (ou carregar) 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

  • Sintaxe de argumentos

    player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
     Coloca a playlist especificada na fila. Quando a playlist estiver em fila e pronta para ser reproduzida, o player vai transmitir um evento video cued (5).

    • O parâmetro playlist obrigatório especifica uma matriz de IDs de vídeos do YouTube. Na API Data do YouTube, a propriedade id do recurso video identifica o ID do vídeo.

    • O parâmetro index opcional especifica o índice do primeiro vídeo da playlist que será reproduzido. O parâmetro usa um índice baseado em zero, e o valor padrão do parâmetro é 0. Portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da playlist.

    • O parâmetro startSeconds opcional aceita um número inteiro/float e especifica o tempo a partir do qual o primeiro vídeo da playlist vai começar a ser reproduzido quando a função playVideo() for chamada. Se você especificar um valor startSeconds e chamar seekTo(), o player vai ser reproduzido a partir do tempo especificado na chamada seekTo(). Se você colocar uma playlist em fila e chamar a função playVideoAt(), o player vai começar a reproduzir o vídeo especificado.

  • Sintaxe de objetos

    player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
     Coloca a lista de vídeos especificada na fila. A lista pode ser uma playlist ou o feed de vídeos enviados por um usuário. A capacidade de enfileirar uma lista de resultados de pesquisa foi descontinuada e não será mais compatível a partir de 15 de novembro de 2020.

    Quando a lista estiver em fila e pronta para ser reproduzida, o player vai transmitir um evento video cued (5).

    • A propriedade listType opcional especifica o tipo de feed de resultados que você está recuperando. Os valores válidos são playlist e user_uploads. Um valor descontinuado, search, não terá mais suporte a partir de 15 de novembro de 2020. O valor padrão é playlist.

    • A propriedade list obrigatória contém uma chave que identifica a lista específica de vídeos que o YouTube deve retornar.

      • Se o valor da propriedade listType for playlist, a propriedade list vai especificar o ID da playlist ou uma matriz de IDs de vídeo. Na API Data do YouTube, a propriedade id do recurso playlist identifica o ID de uma playlist, e a propriedade id do recurso video especifica um ID de vídeo.
      • Se o valor da propriedade listType for user_uploads, a propriedade list vai identificar o usuário cujos vídeos enviados serão retornados.
      • Se o valor da propriedade listType for search, a propriedade list vai especificar a consulta de pesquisa. Observação:essa funcionalidade foi descontinuada e não será mais compatível a partir de 15 de novembro de 2020.

    • A propriedade opcional index especifica o índice do primeiro vídeo da lista que será reproduzido. O parâmetro usa um índice baseado em zero, e o valor padrão do parâmetro é 0. Portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da lista.

    • A propriedade startSeconds opcional aceita um número inteiro ou de ponto flutuante e especifica o tempo a partir do qual o primeiro vídeo da lista vai começar a ser reproduzido quando a função playVideo() for chamada. Se você especificar um valor startSeconds e chamar seekTo(), o player vai ser reproduzido a partir do tempo especificado na chamada seekTo(). Se você colocar uma lista em fila e chamar a função playVideoAt(), o player vai começar a ser reproduzido no início do vídeo especificado.

loadPlaylist

  • Sintaxe de argumentos

    player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
     Essa função carrega e reproduz a playlist especificada.

    • O parâmetro playlist obrigatório especifica uma matriz de IDs de vídeos do YouTube. Na API Data do YouTube, a propriedade id do recurso video especifica um ID de vídeo.

    • O parâmetro index opcional especifica o índice do primeiro vídeo da playlist que será reproduzido. O parâmetro usa um índice baseado em zero, e o valor padrão do parâmetro é 0. Portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da playlist.

    • O parâmetro startSeconds opcional aceita um número inteiro/com ponto flutuante e especifica o momento em que o primeiro vídeo da playlist vai começar a ser reproduzido.

  • Sintaxe de objetos

    player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
     Essa função carrega e reproduz a lista especificada. A lista pode ser uma playlist ou o feed de vídeos enviados por um usuário. A capacidade de carregar uma lista de resultados de pesquisa foi descontinuada e não terá mais suporte a partir de 15 de novembro de 2020.

    • A propriedade listType opcional especifica o tipo de feed de resultados que você está recuperando. Os valores válidos são playlist e user_uploads. Um valor descontinuado, search, não terá mais suporte a partir de 15 de novembro de 2020. O valor padrão é playlist.

    • A propriedade list obrigatória contém uma chave que identifica a lista específica de vídeos que o YouTube deve retornar.

      • Se o valor da propriedade listType for playlist, a propriedade list vai especificar um ID de playlist ou uma matriz de IDs de vídeo. Na API Data do YouTube, a propriedade id do recurso playlist especifica o ID de uma playlist, e a propriedade id do recurso video especifica o ID de um vídeo.
      • Se o valor da propriedade listType for user_uploads, a propriedade list vai identificar o usuário cujos vídeos enviados serão retornados.
      • Se o valor da propriedade listType for search, a propriedade list vai especificar a consulta de pesquisa. Observação:essa funcionalidade foi descontinuada e não será mais compatível a partir de 15 de novembro de 2020.

    • A propriedade opcional index especifica o índice do primeiro vídeo da lista que será reproduzido. O parâmetro usa um índice baseado em zero, e o valor padrão do parâmetro é 0. Portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da lista.

    • A propriedade opcional startSeconds aceita um número inteiro/float e especifica o tempo em que o primeiro vídeo da lista vai começar a ser reproduzido.

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

Reproduzir um vídeo

player.playVideo():Void
Reproduz o vídeo carregado/selecionado. O estado final do player após a execução dessa função será playing (1).

Observação:uma reprodução só conta para a contagem oficial de visualizações de um vídeo se for iniciada por um botão de reprodução nativo no player.
player.pauseVideo():Void
Pausa o vídeo que está sendo reproduzido. O estado final do player após a execução dessa função será paused (2), a menos que o player esteja no estado ended (0) quando a função for chamada. Nesse caso, o estado do player não vai mudar.
player.stopVideo():Void
Pára 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 a intenção é pausar o vídeo, chame a função pauseVideo. Se você quiser mudar o vídeo que está sendo reproduzido, chame 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 qualquer estado de não reprodução, incluindo ended (0), paused (2), video cued (5) ou unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Procura uma marcação de tempo específica 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 de outro estado (playing, video cued etc.), o player vai reproduzir o vídeo.

  • O parâmetro seconds identifica o tempo para o qual o jogador precisa avançar.

    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.

  • O parâmetro allowSeekAhead determina se o player vai fazer uma nova solicitação para o servidor se o parâmetro seconds especificar um tempo fora dos dados de vídeo armazenados em buffer.

    Recomendamos que você defina esse parâmetro como false enquanto o usuário arrasta o mouse pela barra de progresso de um vídeo e, em seguida, defina 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 stream de vídeo, se necessário.

Como controlar a reprodução de vídeos em 360°

Observação:a experiência de reprodução de vídeo em 360° tem suporte limitado em dispositivos móveis. Em dispositivos sem suporte, os vídeos em 360° aparecem distorcidos, e não há como mudar a perspectiva de visualização, nem pela API, nem usando sensores de orientação ou respondendo a ações de toque/arrasto na tela do dispositivo.

player.getSphericalProperties():Object
Recupera propriedades que descrevem a perspectiva ou visualização atual do espectador para uma reprodução de vídeo. Além disso:
  • Esse objeto só é preenchido para vídeos de 360°, também chamados de vídeos esféricos.
  • Se o vídeo atual não for em 360° ou se a função for chamada de um dispositivo sem suporte, ela vai retornar um objeto vazio.
  • Em dispositivos móveis compatíveis, se a propriedade enableOrientationSensor estiver definida como true, essa função vai retornar um objeto em que a propriedade fov contém o valor correto e as outras propriedades são definidas como 0.
O objeto contém as seguintes propriedades:
Propriedades
yaw Um número no intervalo [0, 360] que representa o ângulo horizontal da visualização em graus, o que reflete o quanto o usuário gira a visualização para a esquerda ou para a direita. A posição neutra, voltada para o centro do vídeo na projeção equiretangular, representa 0°, e esse valor aumenta à medida que o espectador vira para a esquerda.
pitch Um número no intervalo [-90, 90] que representa o ângulo vertical da visualização em graus, o que reflete o quanto o usuário ajusta a visualização para olhar para cima ou para baixo. A posição neutra, voltada para o centro do vídeo na projeção equiretangular, representa 0°, e esse valor aumenta à medida que o espectador olha para cima.
roll Um número no intervalo [-180, 180] que representa o ângulo de rotação no sentido horário ou anti-horário da visualização em graus. A posição neutra, com o eixo horizontal na projeção equiretangular paralela ao eixo horizontal da visualização, representa 0°. O valor aumenta à medida que a visualização gira no sentido horário e diminui à medida que a visualização gira no sentido anti-horário.

O player incorporado não apresenta uma interface do usuário para ajustar a rolagem da visualização. O rolo pode ser ajustado de duas maneiras mutuamente exclusivas:
  1. Use o sensor de orientação em um navegador para dispositivos móveis para fornecer rolagem para a visualização. Se o sensor de orientação estiver ativado, a função getSphericalProperties sempre retornará 0 como o valor da propriedade roll.
  2. Se o sensor de orientação estiver desativado, defina o ângulo de inclinação como um valor diferente de zero usando essa API.
fov Um número no intervalo [30, 120] que representa o campo de visão da visualização em graus, medido ao longo da borda mais longa da janela de visualização. A borda menor é ajustada automaticamente para ser proporcional à proporção da visualização.

O valor padrão é 100 graus. Diminuir o valor é como aumentar o conteúdo do vídeo, e aumentar o valor é como diminuir. Esse valor pode ser ajustado usando a API ou a roda do mouse quando o vídeo está no modo de tela cheia.
player.setSphericalProperties(properties:Object):Void
Define a orientação do vídeo para a reprodução de um vídeo em 360°. Se o vídeo atual não for esférico, o método não vai fazer nada, independente da entrada.

A visualização do player responde às chamadas para esse método atualizando para refletir os valores de todas as propriedades conhecidas no objeto properties. A visualização mantém os valores de todas as outras propriedades conhecidas que não estão incluídas nesse objeto.

Além disso:
  • Se o objeto tiver propriedades desconhecidas e/ou inesperadas, o player vai ignorá-las.
  • Como mencionado no início desta seção, a experiência de reprodução de vídeos em 360° não é compatível com todos os dispositivos móveis.
  • Por padrão, em dispositivos móveis compatíveis, essa função define apenas a propriedade fov e não afeta as propriedades yaw, pitch e roll para reprodução de vídeos em 360°. Confira a propriedade enableOrientationSensor abaixo para mais detalhes.
O objeto properties transmitido para a função contém as seguintes propriedades:
Propriedades
yaw Consulte a definição acima.
pitch Consulte a definição acima.
roll Consulte a definição acima.
fov Consulte a definição acima.
enableOrientationSensor Observação:essa propriedade afeta a experiência de visualização em 360° apenas em dispositivos compatíveis.Um valor booleano que indica se a incorporação do IFrame precisa responder a eventos que sinalizam mudanças na orientação de um dispositivo compatível, como o DeviceOrientationEvent de um navegador para dispositivos móveis. O valor padrão do parâmetro é true.

Dispositivos móveis compatíveis
  • Quando o valor é true, um player incorporado depende somente do movimento do dispositivo para ajustar as propriedades yaw, pitch e roll na reprodução de vídeos em 360°. No entanto, a propriedade fov ainda pode ser alterada pela API, que é, na verdade, a única maneira de mudar a propriedade fov em um dispositivo móvel. Esse é o comportamento padrão.
  • Quando o valor é false, o movimento do dispositivo não afeta a experiência de visualização em 360°, e as propriedades yaw, pitch, roll e fov precisam ser definidas pela API.

Dispositivos móveis sem suporte
O valor da propriedade enableOrientationSensor não tem efeito na experiência de reprodução.

Reproduzir um vídeo em uma playlist

player.nextVideo():Void
Essa função carrega e reproduz o próximo vídeo da playlist.

  • Se player.nextVideo() for chamado enquanto o último vídeo da playlist estiver sendo assistido e a playlist estiver configurada para reprodução contínua (loop), o player vai carregar e reproduzir o primeiro vídeo da lista.

  • Se player.nextVideo() for chamado enquanto o último vídeo da playlist estiver sendo assistido e a playlist não estiver configurada para reprodução contínua, a reprodução será encerrada.

player.previousVideo():Void
Essa função carrega e exibe o vídeo anterior na playlist.

  • Se player.previousVideo() for chamado enquanto o primeiro vídeo da playlist estiver sendo assistido e a playlist estiver configurada para reprodução contínua (loop), o player vai carregar e reproduzir o último vídeo da lista.

  • Se player.previousVideo() for chamado enquanto o primeiro vídeo da playlist estiver sendo assistido e a playlist não estiver configurada para reprodução contínua, o player vai reiniciar o primeiro vídeo da playlist do início.

player.playVideoAt(index:Number):Void
Essa função carrega e exibe o vídeo especificado na playlist.

  • O parâmetro index obrigatório especifica o índice do vídeo que você quer reproduzir na playlist. O parâmetro usa um índice com base em zero. Portanto, um valor de 0 identifica o primeiro vídeo da lista. Se você embaralhou a playlist, essa função vai tocar o vídeo na posição especificada na playlist em ordem 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 sem som, false se não.
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() vai retornar o volume mesmo se o player estiver com o som desativado.

Definir o tamanho do player

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

Definir a velocidade do vídeo

player.getPlaybackRate():Number
Esta função recupera a velocidade do vídeo em reprodução. A velocidade do vídeo padrão é 1, o que indica que o vídeo está sendo reproduzido em velocidade normal. As taxas de reprodução podem incluir valores como 0.25, 0.5, 1, 1.5 e 2.
player.setPlaybackRate(suggestedRate:Number):Void
Esta função define a velocidade do vídeo sugerida para o vídeo atual. Se a velocidade do vídeo for alterada, essa alteração será aplicada somente ao vídeo que já estiver indicado ou sendo reproduzido. Se você definir a velocidade 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 velocidade do vídeo para 1.

Chamar essa função não garante que a velocidade de reprodução vai mudar. No entanto, se a velocidade do vídeo for realmente alterada, o evento onPlaybackRateChange será disparado e seu código vai responder ao evento, em vez de chamar a função setPlaybackRate.

O método getAvailablePlaybackRates retorna as velocidades de reprodução possíveis para o vídeo em reprodução. No entanto, se você definir o parâmetro suggestedRate como um valor de ponto flutuante ou inteiro sem suporte, o player vai arredondar esse valor para o valor compatível mais próximo na direção de 1.
player.getAvailablePlaybackRates():Array
Essa função retorna o conjunto de velocidades 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 ofereça suporte a velocidades de reprodução variáveis, a matriz sempre precisa conter 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 vai persistir mesmo se você carregar ou indicar uma playlist diferente. Isso significa que, se você carregar uma playlist, chamar a função setLoop com um valor de true e carregar uma segunda playlist, a segunda playlist também vai ser reproduzida em loop.

O parâmetro loopPlaylists obrigatório identifica o comportamento de looping.

  • Se o valor do parâmetro for true, o player de vídeo vai reproduzir playlists continuamente. 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 exibições vão terminar depois que o player de vídeo exibir o último vídeo de uma playlist.

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.

Essa configuração não vai persistir se você carregar ou colocar uma playlist diferente em fila. Isso significa que, se você carregar uma playlist, chamar a função setShuffle e carregar uma segunda playlist, a segunda playlist não será embaralhada.

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

  • Se o valor do parâmetro for true, o YouTube vai embaralhar 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 vai mudar a ordem da playlist para a 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 bufferizado. Esse método retorna um número mais confiável do que os métodos getVideoBytesLoaded e getVideoBytesTotal, que agora estão obsoletos.
player.getPlayerState():Number
Retorna o estado do jogador. 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 vídeo começou a ser reproduzido.
player.getVideoStartBytes():Number
Descontinuado 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. Esse método agora sempre retorna um valor de 0. Cenário de exemplo: o usuário avança para 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
Descontinuado em 18 de julho de 2012. Em vez disso, use o método getVideoLoadedFraction para determinar a porcentagem do vídeo que foi armazenada em buffer.

Esse método retorna um valor entre 0 e 1000 que aproxima a quantidade de vídeo que foi carregada. Você pode calcular a fração do vídeo que foi carregado dividindo o valor de getVideoBytesLoaded pelo valor de getVideoBytesTotal.
player.getVideoBytesTotal():Number
Descontinuado em 18 de julho de 2012. Em vez disso, use o método getVideoLoadedFraction para determinar a porcentagem do vídeo que foi armazenada em buffer.

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

Esse método sempre retorna um valor de 1000. Você pode calcular a fração do vídeo que foi carregado dividindo o valor de getVideoBytesLoaded pelo valor de getVideoBytesTotal.

Recuperar informações do vídeo

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

Se o vídeo em reprodução for um evento ao vivo, a função getDuration() vai retornar o tempo decorrido desde o início da transmissão de 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 do YouTube.com para o vídeo carregado/reproduzido no momento.
player.getVideoEmbedCode():String
Retorna o código de incorporação do vídeo carregado/reproduzido no momento.

Recuperar informações da playlist

player.getPlaylist():Array
Essa função retorna uma matriz dos IDs de vídeo na playlist conforme o pedido atual. Por padrão, ela retornará IDs de vídeo na ordem designada pelo proprietário da playlist. No entanto, se você tiver chamado a função setShuffle para embaralhar a ordem da playlist, o valor de retorno da função getPlaylist() vai refletir a ordem embaralhada.
player.getPlaylistIndex():Number
Essa função retorna o índice do vídeo da playlist que está sendo reproduzido.

  • 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 um listener 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 jogador pode acionar. 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 listener para o event especificado. O listener é uma string que identifica a função que não será mais executada quando o evento especificado for acionado.

Acessar e modificar nós DOM

player.getIframe():Object
Esse método retorna o nó DOM para o <iframe> incorporado.
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. Como observado na seção anterior, é possível assinar eventos adicionando um listener de eventos ao criar o objeto YT.Player e também 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 target do evento identifica o player de vídeo correspondente.
  • O data do evento especifica um valor relevante para o evento. Os eventos onReady e onAutoplayBlocked não especificam uma propriedade data.

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

onReady
Esse evento é acionado sempre que um jogador termina de carregar e está pronto para começar a receber chamadas de API. O aplicativo precisa implementar essa função se você quiser executar automaticamente determinadas operações, como reproduzir o vídeo ou mostrar informações sobre ele, assim que o player estiver pronto.

O exemplo abaixo mostra uma função de exemplo para processar esse evento. O objeto de evento que a API transmite para a função tem uma propriedade target, que identifica o player. A função recupera o código de incorporação do vídeo carregado, começa a reproduzir o vídeo e exibe o código de incorporação no elemento da página que tem 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 é acionado sempre que o estado do player muda. A propriedade data do objeto de evento que a API transmite para a função de listener de eventos especifica 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 (pausada)
  • 3 (armazenando em buffer)
  • 5 (vídeo indicado).

Quando o player carrega um vídeo pela primeira vez, ele transmite um evento unstarted (-1). Quando um vídeo é preparado para ser reproduzido, o player transmite um evento 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 muda. Isso pode indicar uma mudança no ambiente de reprodução do espectador. Consulte a Central de Ajuda do YouTube para mais informações sobre fatores que afetam as condições de reprodução ou que podem causar o evento.

O valor da propriedade data do objeto de evento que a API transmite para a função de listener do evento 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 é acionado sempre que a velocidade de reprodução do vídeo muda. Por exemplo, se você chamar a função setPlaybackRate(suggestedRate), esse evento será disparado se a velocidade de reprodução for realmente alterada. Seu aplicativo vai responder ao evento e não pode assumir que a velocidade do vídeo será automaticamente alterada quando a função setPlaybackRate(suggestedRate) for chamada. Da mesma forma, seu código não pode assumir que a velocidade do vídeo será alterada somente como resultado de uma chamada explícita a setPlaybackRate.

O valor da propriedade data do objeto de evento que a API passa para a função de listener do evento será um número que identifica a nova velocidade do vídeo. O método getAvailablePlaybackRates retorna uma lista das velocidades de reprodução válidas para o vídeo indicado ou em reprodução.
onError
Esse evento é acionado se ocorrer um erro no player. A API vai transmitir um objeto event para a função do listener de eventos. A propriedade data desse objeto vai 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 player5 HTML ou outro erro relacionado ao player do HTML5 ocorreu.
  • 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 é acionado 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 os quais você pode definir opções de player: