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:
player.getOptions();
 No momento, o único módulo para o qual você pode definir opções é o captions, que lida com legendas no player. Ao receber um evento onApiChange, o app pode usar o comando a seguir para determinar quais opções podem ser definidas para o módulo captions:
player.getOptions('captions');
 Ao consultar o player com esse comando, você pode confirmar se as opções que você quer acessar estão realmente acessíveis. Os comandos a seguir extraem e atualizam as opções do módulo:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
 A tabela abaixo lista as opções compatíveis com a API:

Módulo Opção Descrição
legendas 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 é -1. Definir essa opção como um número inteiro abaixo de -1 fará com que o tamanho de legenda mais pequeno seja exibido, enquanto definir essa opção como um número inteiro acima de 3 fará com que o tamanho de legenda mais grande seja exibido.
legendas reload Essa opção recarrega os dados de closed caption para o vídeo que está sendo reproduzido. O valor será null se você recuperar o valor da opção. Defina o valor como true para recarregar os dados de legenda.
onAutoplayBlocked
Esse evento é acionado sempre que o navegador bloqueia a reprodução automática ou os recursos de reprodução de vídeo com script, coletivamente chamados de "reprodução automática". Isso inclui a reprodução tentada com qualquer uma das seguintes APIs do player:

A maioria dos navegadores tem políticas que podem bloquear a reprodução automática em computadores, dispositivos móveis e outros ambientes se determinadas condições forem atendidas. As instâncias em que essa política pode ser acionada incluem a reprodução sem som sem interação do usuário ou quando uma política de permissões para permitir a reprodução automática em um iframe entre origens não foi definida.

Para mais detalhes, consulte as políticas específicas do navegador (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) e o guia de autoplay da Mozilla.

Exemplos

Criação de objetos YT.Player

  • Exemplo 1: usar a API com o <iframe> atual

    Neste exemplo, um elemento <iframe> na página já define o player com que a API será usada. O URL src do player precisa definir o parâmetro enablejsapi como 1 ou o atributo enablejsapi do elemento <iframe> como true.

    A função onPlayerReady muda a cor da borda ao redor do player para laranja quando ele está pronto. A função onPlayerStateChange muda a cor da borda ao redor do player com base no status atual dele. Por exemplo, a cor é verde quando o player está tocando, vermelha quando está pausado, azul quando está em buffer e assim por diante.

    Este exemplo usa o seguinte código:

    <iframe id="existing-iframe-example"
        width="640" height="360"
        src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
        frameborder="0"
        style="border: solid 4px #37474F"
></iframe>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player('existing-iframe-example', {
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
        }
    });
  }
  function onPlayerReady(event) {
    document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00';
  }
  function changeBorderColor(playerStatus) {
    var color;
    if (playerStatus == -1) {
      color = "#37474F"; // unstarted = gray
    } else if (playerStatus == 0) {
      color = "#FFFF00"; // ended = yellow
    } else if (playerStatus == 1) {
      color = "#33691E"; // playing = green
    } else if (playerStatus == 2) {
      color = "#DD2C00"; // paused = red
    } else if (playerStatus == 3) {
      color = "#AA00FF"; // buffering = purple
    } else if (playerStatus == 5) {
      color = "#FF6DOO"; // video cued = orange
    }
    if (color) {
      document.getElementById('existing-iframe-example').style.borderColor = color;
    }
  }
  function onPlayerStateChange(event) {
    changeBorderColor(event.data);
  }
</script>

  • Exemplo 2: reprodução alta

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

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

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

  • Exemplo 3 : neste exemplo, os parâmetros do player são definidos para reproduzir o vídeo automaticamente quando ele for carregado e ocultar os controles do player de vídeo. Ele também adiciona listeners de eventos para vários eventos transmitidos pela API.

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

Como controlar vídeos em 360°

Este exemplo usa o seguinte código:

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

Integração da API Media Integrity da WebView do Android

O YouTube estendeu a API Android WebView Media Integrity para permitir que players de mídia incorporados, incluindo players do YouTube incorporados em aplicativos Android, verifiquem a autenticidade do app de incorporação. Com essa mudança, os apps incorporados enviam automaticamente um ID de app atestado para o YouTube. Os dados coletados pelo uso dessa API são os metadados do app (o nome do pacote, o número da versão e o certificado de assinatura) e um token de atestado do dispositivo gerado pelo Google Play Services.

Os dados são usados para verificar a integridade do aplicativo e do dispositivo. Ele é criptografado, não é compartilhado com terceiros e é excluído após um período de retenção fixo. Os desenvolvedores de apps podem configurar a identidade do app na API Media Integrity do WebView. A configuração aceita uma opção de desativação.

Histórico de revisões

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

  • The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
  • The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
  • The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

  • The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
    • yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
    • pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
    • roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
    • fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
  • The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

  • Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

  • The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

    The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

  • The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

  • The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

July 23, 2013

This update contains the following changes:

  • The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

October 31, 2012

This update contains the following changes:

  • The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

    In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)

  • When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.

  • The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

  • The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

  • The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.

  • The API supports several new functions and one new event that can be used to control the video playback speed:

    • Functions

      • getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
      • getPlaybackRate – Retrieve the playback rate for the cued or playing video.
      • setPlaybackRate – Set the playback rate for the cued or playing video.

    • Events

July 19, 2012

This update contains the following changes:

  • The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.

  • The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.

  • The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

    Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.

  • The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

  • The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

  • We have removed the experimental status from the IFrame Player API.

  • The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

    In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

  • The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size.