A API do player IFrame permite incorporar um player de vídeo do YouTube em seu website e controlar o player usando o JavaScript. Ao contrário das APIs de players em Flash e em JavaScript, que envolvem a incorporação de um objeto Flash em sua página da Web, as mensagens da API do IFrame postam conteúdo em uma tag <iframe>
em sua página. Essa abordagem proporciona mais flexibilidade do que as APIs disponíveis anteriormente, pois ela permite que o YouTube forneça um player HTML5, em vez de um player Flash, para dispositivos móveis que não são compatíveis com Flash.
Usando as funções JavaScript da API, você pode enfileirar vídeos para reprodução; reproduzir, pausar ou interromper esses vídeos; ajustar o volume do player; ou ter informações sobre o vídeo que está sendo reproduzido. Você também pode adicionar listeners de eventos que serão executados em resposta a determinados eventos do player, como uma mudança de estado do player ou uma mudança de qualidade de reprodução do vídeo.
Esse guia explica como usar a API do IFrame. Ele identifica os diferentes tipos de eventos que a API pode enviar e explica como gravar listeners de eventos para responder a esses eventos. Além disso, detalha as diferentes funções JavaScript que você pode chamar para controlar o player de vídeo, além dos parâmetros do player que você pode usar para personalizar ainda mais o player.
Requisitos
O usuário final precisar estar usando um navegador que ofereça suporte ao recurso HTML5 postMessage
. A maioria dos navegadores modernos oferece suporte ao postMessage
, embora o Internet Explorer 7 não o faça.
É necessário que os players incorporados tenham uma Janela de visualização de pelo menos 200 px por 200 px. Se o player mostra controles, ele tem que ser grande o suficiente para exibir completamente os controles sem encolher a Janela visualização abaixo do tamanho mínimo. Recomendamos que players de 16:9 tenham pelo menos 480 pixels de largura e 270 pixels de altura.
Qualquer página da Web que use a API do IFrame também precisará implementar a seguinte função JavaScript:
-
onYouTubeIframeAPIReady
– A API chamará essa função quando a página tiver terminado de baixar o JavaScript para a API do player, que permite que você use a API em sua página. Dessa forma, essa função cria os objetos do player que você deseja exibir quando a página for carregada.
Primeiros passos
O exemplo de página HTML abaixo cria um player incorporado que carregará um vídeo, irá reproduzi-lo por seis segundos e, em seguida, interromperá a reprodução. Os comentários numerados no HTML são explicados na lista abaixo do exemplo.
<!DOCTYPE html> <html> <body> <!-- 1. The <iframe> (and video player) will replace this <div> tag. --> <div id="player"></div> <script> // 2. This code loads the IFrame Player API code asynchronously. var tag = document.createElement('script'); tag.src = "https://www.youtube.com/iframe_api"; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); // 3. This function creates an <iframe> (and YouTube player) // after the API code downloads. var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '360', width: '640', videoId: 'M7lc1UVf-VE', events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); } // 4. The API will call this function when the video player is ready. function onPlayerReady(event) { event.target.playVideo(); } // 5. The API calls this function when the player's state changes. // The function indicates that when playing a video (state=1), // the player should play for six seconds and then stop. var done = false; function onPlayerStateChange(event) { if (event.data == YT.PlayerState.PLAYING && !done) { setTimeout(stopVideo, 6000); done = true; } } function stopVideo() { player.stopVideo(); } </script> </body> </html>
A lista a seguir fornece mais detalhes sobre o exemplo acima:
-
Nessa seção, a tag
<div>
identifica o local na página em que a API do IFrame colocará o player de vídeo. O construtor do objeto do player, descrito na seção Carregar um player de vídeo, identifica a tag<div>
peloid
para que a API possa coloca o<iframe>
no local apropriado. Especificamente, a API do IFrame substituirá a tag<div>
pela tag<iframe>
.Como alternativa, você também pode colocar o elemento
<iframe>
diretamente na página. A seção Carregar um player de vídeo contém informações sobre como executar este procedimento. -
O código dessa seção carrega o código JavaScript da API do player IFrame. O exemplo usa a modificação DOM para baixar o código API para garantir que ele seja recuperado de forma assíncrona. O atributo
<script>
da tagasync
, que também permite downloads assíncronos, ainda não é compatível com todos os navegadores modernos, como discutido nesta resposta do Stack Overflow. -
A função
onYouTubeIframeAPIReady
será executada assim que o código API do player for baixado. Essa parte do código define uma variável global,player
, que se refere ao player de vídeo que está sendo incorporado, e a função constrói o objeto do player de vídeo. -
A função
onPlayerReady
será executada quando o eventoonReady
for disparado. Nesse exemplo, a função indica que, quando o player de vídeo estiver pronto, ele começará a ser reproduzido. -
A API chamará a função
onPlayerStateChange
quando o estado do player mudar, o que pode indicar que o player está sendo reproduzido, foi pausado, terminou de reproduz e assim por diante. A função indica que, quando o estado do player for1
(em reprodução), o player deve ser reproduzido por seis segundos e, em seguida, chamar a funçãostopVideo
para interromper o vídeo.
Carregar um player de vídeo
Depois de o código JavaScript da API ser carregado, a API chamará a função onYouTubeIframeAPIReady
. Nesse ponto, você pode criar um objeto YT.Player
para inserir um player de vídeo em sua página. O excerto HTML abaixo mostra a função onYouTubeIframeAPIReady
do exemplo acima:
var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '360', width: '640', videoId: 'M7lc1UVf-VE', events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); }
O construtor do player de vídeo especifica os seguintes parâmetros:
-
O primeiro parâmetro especifica o elemento DOM ou o
id
do elemento HTML em que a API inserirá a tag<iframe>
que contém o player.A API do IFrame substituirá o elemento especificado pelo elemento
<iframe>
que contém o player. Isso pode afetar o layout de sua página se o elemento que estiver sendo substituído tiver um estilo de exibição diferente do elemento<iframe>
inserido. Por padrão, um<iframe>
é exibido como um elementoinline-block
. - O segundo parâmetro é um objeto que especifica as opções do player. O objeto contém as seguintes propriedades:
width
(número) – A largura do player de vídeo. O valor padrão é640
.height
(número) – A altura do player de vídeo. O valor padrão é360
.videoId
(string) – O ID do vídeo do YouTube que identifica o vídeo que o player carregará.playerVars
(objeto) – As propriedades do objeto identificam os parâmetros do player que podem ser usados para personalizar o player.events
(objeto) – As propriedades do objeto identificam os eventos que a API dispara e as funções (listeners de eventos) que ela chamará quando esses eventos ocorrerem. No exemplo, o construtor indica que a funçãoonPlayerReady
será executada quando o eventoonReady
for disparado e que a funçãoonPlayerStateChange
será executada quando o eventoonStateChange
for disparado.
Conforme mencionado na seção Primeiros passos, em vez de escrever um elemento <div>
vazio em sua página, que o código JavaScript da API substituirá por um elemento <iframe>
, você pode criar a própria tag <iframe>
.
<iframe id="player" type="text/html" width="640" height="360" src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com" frameborder="0"></iframe>
Se você gravar a tag <iframe>
, quando criar o objeto YT.Player
, não precisará especificar os valores para width
e height
, que são especificados como atributos da tag <iframe>
, ou parâmetros videoId
e do player, que são especificados no URL src
. Como medida de segurança extra, você também precisa incluir o parâmetro origin
no URL, especificando o esquema de URL (http://
ou https://
) e o domínio completo de sua página de hospedagem como o valor do parâmetro. Embora origin
seja opcional, sua inclusão protege contra a injeção de JavaScript malicioso de terceiros em sua página e controla a invasão de seu player do YouTube.
Na seção Exemplos, há mais alguns exemplos para a criação de objetos do player de vídeo.
Operações
Para chamar os métodos da API do player, primeiro, tenha uma referência do objeto do player que deseja controlar. É possível conseguir essa referência criando um objeto YT.Player
, como discutido nas seções Primeiros passos e Carregar um player de vídeo deste documento.
Funções
Funções de enfileiramento
As funções de enfileiramento permitem carregar e reproduzir um vídeo, uma playlist ou outra lista de vídeos. Se você estiver usando a sintaxe do objeto descrita abaixo para chamar essas funções, poderá também enfileirar ou carregar uma lista de resultados de pesquisa ou uma lista de vídeos enviados do usuário.
A API é compatível com duas sintaxes diferentes para chamar as funções de enfileiramento.
-
A sintaxe do argumento requer argumentos de função a serem listados em uma ordem prescrita.
-
A sintaxe do objeto permite passar um objeto como um parâmetro único e definir suas propriedades para os argumentos de função que você deseja definir. Além disso, a API pode ser compatível com outras funcionalidades que a sintaxe do argumento não suporta.
Por exemplo, a função loadVideoById
pode ser chamada de uma das formas a seguir. A sintaxe do objeto é compatível com a propriedade endSeconds
, que a sintaxe do argumento não suporta.
-
Sintaxe do argumento
loadVideoById("bHQqvYy5KYo", 5, "large")
-
Sintaxe do objeto
loadVideoById({'videoId': 'bHQqvYy5KYo', 'startSeconds': 5, 'endSeconds': 60, 'suggestedQuality': 'large'});
Funções de enfileiramento de vídeos
cueVideoById
-
-
Sintaxe do argumento
player.cueVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void
-
Sintaxe do objeto
player.cueVideoById({videoId:String, startSeconds:Number, endSeconds:Number, suggestedQuality:String}):Void
Esta função carrega a miniatura do vídeo especificado e prepara o player para reproduzir o vídeo. O player não solicita o FLV enquanto
playVideo()
ouseekTo()
não é chamado.- O parâmetro obrigatório
videoId
especifica o ID do vídeo do YouTube a ser reproduzido. Nos feeds do vídeo da API de dados do YouTube, a tag<yt:videoid>
especifica o ID. - O parâmetro opcional
startSeconds
aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser iniciada quandoplayVideo()
é chamado. Se você especificar um valorstartSeconds
e chamarseekTo()
, o player iniciará a reprodução no ponto especificado na chamadaseekTo()
. Quando o vídeo estiver indicado e pronto para ser reproduzido, o player transmitirá um eventovideo cued
(5
). - O parâmetro opcional
endSeconds
(compatível apenas com a sintaxe do objeto) aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser interrompida quandoplayVideo()
é chamado. Se você especificar um valorendSeconds
e chamarseekTo()
, o valorendSeconds
não estará mais disponível. - O parâmetro opcional
suggestedQuality
especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da funçãosetPlaybackQuality
para saber mais sobre a qualidade de reprodução.
-
loadVideoById
-
-
Argument syntax
player.loadVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void
-
Object syntax
player.loadVideoById({videoId:String, startSeconds:Number, endSeconds:Number, suggestedQuality:String}):Void
Esta função carrega e reproduz o vídeo especificado.
- O parâmetro obrigatório
videoId
especifica o ID do vídeo do YouTube a ser reproduzido. Nos feeds do vídeo da API de dados do YouTube, a tag<yt:videoid>
especifica o ID. - O parâmetro opcional
startSeconds
aceita um número flutuante/inteiro. Se ele for especificado, o vídeo será iniciado no frame principal mais próximo ao ponto especificado. - O parâmetro opcional
endSeconds
aceita um número decimal / inteiro. Se for especificado, o vídeo vai interromper a reprodução no ponto especificado. - O parâmetro opcional
suggestedQuality
especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da funçãosetPlaybackQuality
para saber mais sobre a qualidade de reprodução.
-
cueVideoByUrl
-
-
Argument syntax
player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number, suggestedQuality:String):Void
-
Object syntax
player.cueVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number, suggestedQuality:String}):Void
Esta função carrega a miniatura do vídeo especificado e prepara o player para reproduzir o vídeo. O player não solicita o FLV enquanto
playVideo()
ouseekTo()
não é chamado.- O parâmetro obrigatório
mediaContentUrl
especifica um URL do player do YouTube totalmente qualificado no formatohttp://www.youtube.com/v/VIDEO_ID?version=3
. Nos feeds de vídeo da API de dados do YouTube, o atributourl
da tag<media:content>
, contém um URL de player totalmente qualificado quando o valor do atributoformat
da tag é5
. - O parâmetro opcional
startSeconds
aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser iniciada quandoplayVideo()
é chamado. Se você especificarstartSeconds
e chamarseekTo()
, o player iniciará a reprodução no ponto especificado na chamadaseekTo()
. Quando o vídeo estiver indicado e pronto para ser reproduzido, o player transmitirá umvideo cued
evento (5). - O parâmetro opcional
endSeconds
(compatível apenas com a sintaxe do objeto) aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser interrompida quandoplayVideo()
é chamado. Se você especificar um valorendSeconds
e chamarseekTo()
, o valorendSeconds
não estará mais disponível. - O parâmetro opcional
suggestedQuality
especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da funçãosetPlaybackQuality
para saber mais sobre a qualidade de reprodução.
-
loadVideoByUrl
-
-
Argument syntax
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number, suggestedQuality:String):Void
-
Object syntax
player.loadVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number, suggestedQuality:String}):Void
Esta função carrega e reproduz o vídeo especificado.
- O parâmetro obrigatório
mediaContentUrl
especifica um URL do player do YouTube totalmente qualificado no formatohttp://www.youtube.com/v/VIDEO_ID?version=3
. Nos feeds de vídeo da API de dados do YouTube, o atributourl
da tag<media:content>
contém um URL de player totalmente qualificado quando o valor do atributoformat
da tag é5
. - O parâmetro opcional
startSeconds
aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser iniciada. SestartSeconds
(o número pode ser decimal) for especificado, o vídeo será iniciado a partir do frame principal mais próximo ao ponto especificado. - O parâmetro opcional
endSeconds
(compatível apenas com a sintaxe do objeto) aceita um número flutuante/inteiro e especifica o ponto em que a reprodução do vídeo deve ser interrompida. - O parâmetro opcional
suggestedQuality
especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da funçãosetPlaybackQuality
para saber mais sobre a qualidade de reprodução.
-
Funções de enfileiramento para listas
As funções cuePlaylist
e loadPlaylist
permitem carregar e reproduzir uma playlist ou uma lista de vídeos. Se você estiver usando a sintaxe de objeto para chamar essas funções, você também pode enfileirar ou carregar uma lista de resultados da pesquisa ou uma lista de vídeos enviados por um usuário.
Como as funções operam de maneira diferente, dependendo se elas são chamadas usando a sintaxe do argumento ou a sintaxe do objeto, os dois métodos de chamada são documentados abaixo.
cuePlaylist
-
-
Argument syntax
player.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number, suggestedQuality:String):Void
Enfileira a playlist especificada. Quando a playlist estiver indicada e pronta para ser reproduzida, o player transmitirá um eventovideo cued
(5
).-
O parâmetro obrigatório
playlist
especifica uma matriz de IDs do vídeo do YouTube. Nos feeds da API de dados do YouTube, a tag<yt:videoid>
especifica um ID do vídeo. -
O parâmetro opcional
index
especifica o índice do primeiro vídeo da lista que será reproduzido. O parâmetro usa um índice com base em zero e o valor do parâmetro padrão é0
, portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da playlist. -
O parâmetro opcional
startSeconds
aceita um número flutuante/inteiro e especifica o ponto em que o primeiro vídeo da playlist deve ser reproduzido quando a funçãoplayVideo()
for chamada. Se você especificar um valorstartSeconds
e chamarseekTo()
, o player iniciará a reprodução no ponto especificado na chamadaseekTo()
. Se você indicar uma playlist e chamar a funçãoplayVideoAt()
, a reprodução do player iniciará no começo do vídeo especificado. -
O parâmetro opcional
suggestedQuality
especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da funçãosetPlaybackQuality
para saber mais sobre a qualidade de reprodução.
-
-
Sintaxe do objeto
player.cuePlaylist({listType:String, list:String, index:Number, startSeconds:Number, suggestedQuality:String}):Void
Enfileira a lista de vídeos especificada. Ela pode ser uma playlist, um feed de resultados de pesquisa ou o feed de vídeos enviados de um usuário. Quando a lista estiver indicada e pronta para ser reproduzida, o player transmitirá um eventovideo cued
(5
).-
A propriedade opcional
listType
especifica o tipo de feed de resultados que você está recuperando. Os valores válidos sãoplaylist
,search
euser_uploads
. O valor padrão éplaylist
. -
A propriedade obrigatória
list
contém uma chave que identifica a lista particular de vídeos que o YouTube deve retornar.- Se o valor de propriedade
listType
forplaylist
, a propriedadelist
especificará o ID de playlist de reprodução ou uma matriz de IDs de vídeo. Nos feeds de API de dados do YouTube, a tag<yt:playlistid>
especifica um ID de playlist e a tag<yt:videoid>
especifica um ID de vídeo. - Se o valor de propriedade
listType
forsearch
, a propriedadelist
especificará a consulta de pesquisa. - Se o valor de propriedade
listType
foruser_uploads
, a propriedadelist
identificará o usuário cujos vídeos enviados serão retornados.
- Se o valor de propriedade
-
A propriedade opcional
index
especifica o índice do primeiro vídeo da lista que será reproduzida. O parâmetro usa um índice com base em zero e o valor do parâmetro padrão é0
, portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da lista. -
A propriedade opcional
startSeconds
aceita um número flutuante/inteiro e especifica o ponto em que o primeiro vídeo da playlist deve começar a ser reproduzido quando a funçãoplayVideo()
for chamada. Se você especificar um valorstartSeconds
e chamarseekTo()
, o player iniciará a reprodução no ponto especificado na chamadaseekTo()
. Se você indicar uma playlist e chamar a funçãoplayVideoAt()
, a reprodução do player iniciará no começo do vídeo especificado. -
A propriedade opcional
suggestedQuality
especifica a qualidade de reprodução sugerida para os vídeos da lista. Veja a definição da funçãosetPlaybackQuality
para saber mais sobre a qualidade de reprodução.
-
-
loadPlaylist
-
-
Argument syntax
player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number, suggestedQuality:String):Void
Esta função carrega a playlist especificada e a reproduz.-
O parâmetro obrigatório
playlist
especifica uma matriz de IDs do vídeo do YouTube. Nos feeds da API de dados do YouTube, a tag<yt:videoid>
especifica um ID do vídeo. -
O parâmetro opcional
index
especifica o índice do primeiro vídeo da lista que será reproduzido. O parâmetro usa um índice com base em zero e o valor do parâmetro padrão é0
, portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da playlist. -
O parâmetro
startSeconds
opcional aceita um número flutuante/inteiro e especifica o ponto em que o primeiro vídeo da playlist deve começar a ser reproduzido. -
O parâmetro opcional
suggestedQuality
especifica a qualidade sugerida de reprodução para o vídeo. Veja a definição da funçãosetPlaybackQuality
para saber mais sobre a qualidade de reprodução.
-
-
Object syntax
player.loadPlaylist({list:String, listType:String, index:Number, startSeconds:Number, suggestedQuality:String}):Void
Esta função carrega a lista especificada e a reproduz. Ela pode ser uma playlist, um feed de resultados de pesquisa ou o feed de vídeos enviados de um usuário.-
A propriedade opcional
listType
especifica o tipo de feed de resultados que você está recuperando. Os valores válidos sãoplaylist
,search
euser_uploads
. O valor padrão éplaylist
. -
A propriedade obrigatória
list
contém uma chave que identifica a lista particular de vídeos que o YouTube deve retornar.- Se o valor de propriedade
listType
forplaylist
, a propriedadelist
especificará o ID da playlist de reprodução ou uma matriz de IDs de vídeo. Nos feeds de API de dados do YouTube, a tag<yt:playlistid>
especifica um ID de playlist e a tag<yt:videoid>
especifica um ID de vídeo. - Se o valor de propriedade
listType
forsearch
, a propriedadelist
especificará a consulta de pesquisa. - Se o valor de propriedade
listType
foruser_uploads
, a propriedadelist
identificará o usuário cujos vídeos enviados serão retornados.
- Se o valor de propriedade
-
A propriedade opcional
index
especifica o índice do primeiro vídeo da lista que será reproduzida. O parâmetro usa um índice com base em zero e o valor do parâmetro padrão é0
, portanto, o comportamento padrão é carregar e reproduzir o primeiro vídeo da lista. -
A propriedade opcional
startSeconds
aceita um número flutuante/inteiro e especifica o ponto em que o primeiro vídeo da lista deve começar a ser reproduzido. -
A propriedade opcional
suggestedQuality
especifica a qualidade de reprodução sugerida para os vídeos da lista. Veja a definição da funçãosetPlaybackQuality
para saber mais sobre a qualidade de reprodução.
-
-
Controles da reprodução e configurações do player
Reproduzir um vídeo
player.playVideo():Void
- Reproduz o vídeo atualmente indicado/carregado. O estado final do player após esta função ser executada será
playing
(1).
Observação: a reprodução só é considerada na contagem de visualização oficial do vídeo se ela for iniciada por um botão nativo de reprodução no player.
player.pauseVideo():Void
- Pausa o vídeo que está sendo reproduzido. Após a execução dessa função, o estado final do player será
paused
(2
), a não ser que o player esteja no estadoended
(0
) quando a função é chamada e, neste caso, o estado do player não será alterado.
player.stopVideo():Void
- Interrompe e cancela o carregamento do vídeo atual. Esta função deve ser reservada para situações raras em que você sabe que o usuário não assistirá a vídeo adicional no player. Se sua intenção for pausar o vídeo, basta chamar a função
pauseVideo
. Se você quer alterar o vídeo que o player está reproduzindo, você pode chamar uma das funções de enfileiramento sem chamarstopVideo
primeiro.
Importante: ao contrário da funçãopauseVideo
, que deixa o player no estadopaused
(2
), a funçãostopVideo
pode colocar o player em um estado de não reprodução, inclusiveended
(0
),paused
(2
),video cued
(5
) ouunstarted
(-1
).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
- Procura um ponto especificado no vídeo. Se o player estiver em pausa quando a função for chamada, ele permanecerá em pausa. Se a função for chamada a partir de outro estado (
playing
,video cued
, etc), o player reproduzirá o vídeo.-
O parâmetro
seconds
identifica o ponto a partir do qual o player deve continuar.O player continuará a partir do frame principal mais próximo antes desse ponto, a menos que ele já tenha baixado a parte do vídeo que o usuário está buscando. Nesse caso, o player continuará a partir do frame principal mais próximo antes ou depois do ponto especificado, conforme ditado pelo método
seek()
do objetoNetStream
do player Flash. Consulte a documentação do Adobe para mais informações. -
O parâmetro
allowSeekAhead
determina se o player fará uma nova solicitação ao servidor se o parâmetroseconds
especificar um ponto fora dos dados do vídeo atualmente armazenado em buffer.Recomendamos que você defina esse parâmetro como
false
enquanto o usuário arrasta o mouse ao longo da barra de progresso de um vídeo e configure-o comotrue
quando o usuário soltar o mouse. Essa abordagem permite que um usuário role para diferentes pontos de um vídeo sem solicitar novos fluxos de vídeo rolando por pontos sem buffer. Quando o usuário libera o botão do mouse, o player avança para o ponto desejado no vídeo e solicita um novo fluxo de vídeo, se necessário.
-
player.clearVideo():Void
- Limpa a exibição do vídeo. Esta função é útil se você deseja limpar o restante do vídeo depois de chamar
stopVideo()
. Seu uso foi suspenso na API do player ActionScript 3.0.
Reproduzir um vídeo em uma playlist
player.nextVideo():Void
- Esta função carrega e reproduz o próximo vídeo da playlist.
-
Se
player.nextVideo()
é chamado quando o último vídeo da playlist estiver sendo assistido e a playlist estiver configurada para reproduzir continuamenteloop
, o player carregará e reproduzirá o primeiro vídeo da lista. -
Se
player.nextVideo()
é chamado quando o último vídeo da playlist estiver sendo assistido e a lista não estiver configurada para reproduzir continuamente, a reprodução será encerrada.
-
player.previousVideo():Void
- Esta função carrega e reproduz o vídeo anterior da playlist.
-
Se
player.previousVideo()
é chamado quando o primeiro vídeo da playlist estiver sendo assistido e a playlist estiver configurada para reproduzir continuamenteloop
, o player carregará e reproduzirá o último vídeo da lista. -
Se
player.previousVideo()
é chamado quando o primeiro vídeo da playlist estiver sendo assistido e a lista não estiver configurada para reproduzir continuamente, o player reiniciará o primeiro vídeo desde o início.
-
player.playVideoAt(index:Number):Void
- Esta função carrega e reproduz o próximo vídeo da playlist.
-
O parâmetro obrigatório
index
especifica o índice do vídeo que você deseja reproduzir na playlist. O parâmetro usa um índice com base em zero, portanto, o valor0
identifica o primeiro vídeo da lista. Se você tornar a playlist aleatória, esta função reproduzirá o vídeo na posição especificada na lista aleatória.
-
Alterar o volume do player
player.mute():Void
- Desativa o som do player.
player.unMute():Void
- Ativa o som do player.
player.isMuted():Boolean
- Retorna
true
se o player estiver no mudo. Em caso negativo, retornafalse
.
player.setVolume(volume:Number):Void
- Define o volume. Aceita um número inteiro entre
0
e100
.
player.getVolume():Number
- Retorna o volume atual do player, um número inteiro entre
0
e100
.getVolume()
retornará o volume mesmo se o player estiver no mudo.
Definir o tamanho do player
player.setSize(width:Number, height:Number):Object
- Define o tamanho em pixels do
<iframe>
que contém o player.
Definir a taxa de reprodução
player.getPlaybackRate():Number
- Esta função recupera a taxa de reprodução do vídeo em reprodução. A taxa de reprodução padrão é
1
, o que indica que o vídeo está sendo reproduzido em velocidade normal. As taxas de reprodução incluem valores como0.25
,0.5
,1
,1.5
e2
.
player.setPlaybackRate(suggestedRate:Number):Void
- Esta função define a taxa de reprodução sugerida para o vídeo atual. Se a taxa de reprodução for alterada, essa alteração será aplicada somente ao vídeo que já estiver indicado ou sendo reproduzido. Se você definir a taxa de reprodução de um vídeo indicado, essa taxa ainda estará em vigor quando a função
playVideo
for chamada ou quando o usuário iniciar a reprodução diretamente nos controles do player. Além disso, as funções de chamada para indicar ou carregar vídeos ou playlists (cueVideoById
,loadVideoById
etc) redefinirão a taxa de reprodução para1
.
Chamar essa função não garante que a qualidade da reprodução será realmente alterada. No entanto, se a taxa de reprodução for realmente alterada, o eventoonPlaybackRateChange
será disparado e seu código responderá ao evento, em vez de chamar a funçãosetPlaybackRate
.
O métodogetAvailablePlaybackRates
retornará as possíveis taxas de reprodução do vídeo sendo reproduzido. No entanto, se você definir o parâmetrosuggestedRate
para um número inteiro não compatível ou para um valor decimal, o player arredondará esse valor para o valor inferior compatível mais próximo de1
.
player.getAvailablePlaybackRates():Array
- Esta função retorna o conjunto de taxas de reprodução em que o vídeo atual está disponível. O valor padrão é
1
, o que indica que o vídeo está sendo reproduzido em velocidade normal.
A função retorna uma matriz de números ordenados da velocidade de reprodução mais lenta para a mais rápida. Mesmo que o player não seja compatível com as velocidades de reprodução variáveis, é necessário que a matriz sempre contenha pelo menos um valor (1
).
Definir o comportamento da reprodução de listas
player.setLoop(loopPlaylists:Boolean):Void
-
Esta função indica se o player de vídeo deve reproduzir uma lista continuamente ou se deve interromper a reprodução após a conclusão do último vídeo da lista. O comportamento padrão é que as playlists não sejam reproduzidas em loop.
Essa configuração persistirá mesmo se você carregar ou indicar uma playlist diferente. Se você carregar uma playlist, chame a função
setLoop
com um valortrue
e carregue uma segunda lista, que também será reproduzida em loop.O parâmetro obrigatório
loopPlaylists
identifica o comportamento em loop.-
Se o valor do parâmetro for
true
, o player de vídeo reproduzirá as listas de . Depois de reproduzir o último vídeo, o player voltará para o início da lista e reproduzirá novamente. -
Se o valor do parâmetro for
false
, as reproduções serão concluídas depois que o player reproduzir o último vídeo de uma lista.
-
player.setShuffle(shufflePlaylist:Boolean):Void
-
Esta função indica se os vídeos de uma lista devem ser misturados para que sejam reproduzidos em uma ordem diferente da designada pelo criador da lista. Se você misturar uma playlist depois de ela já ter começado a ser reproduzida, ela será reordenada enquanto o vídeo for reproduzido. O próximo vídeo a ser reproduzido será selecionados com base na lista reordenada.
Esta configuração não persistirá se você carregar ou indicar uma playlist diferente. Se você carregar uma playlist, chame a função
setShuffle
e carregue uma segunda lista, que não será misturada.O parâmetro obrigatório
shufflePlaylist
indica se o YouTube deve reproduzir a playlist aleatoriamente.-
Se o valor do parâmetro for
true
, o YouTube misturará a ordem da playlist. Se você instruir a função para misturar uma lista de reprodução que já estiver em ordem aleatória, o YouTube misturará a ordem novamente. -
Se o valor do parâmetro for
false
, o YouTube mudará a playlist para sua ordem original.
-
Status da reprodução
player.getVideoLoadedFraction():Float
- Retorna um número entre
0
e1
, que especifica a porcentagem do vídeo que o player mostra como armazenado em buffer. Este método retorna um número mais confiável do que os métodosgetVideoBytesLoaded
egetVideoBytesTotal
, com uso suspenso.
player.getPlayerState():Number
- Retorna o estado do player. Os valores possíveis são:
-1
– não iniciado0
– encerrado1
– em reprodução2
– em pausa3
– armazenando em buffer5
– vídeo indicado
player.getCurrentTime():Number
- Retorna o tempo decorrido em segundos desde que o início da reprodução do vídeo.
player.getVideoStartBytes():Number
- Uso suspenso em 31 de outubro de 2012. Retorna o número de bytes a partir do qual o arquivo do vídeo começou a ser carregado. Agora, este método sempre retorna um valor
0
. Exemplo: o usuário avança até um ponto que ainda não foi carregado e o player faz uma nova solicitação para reproduzir um segmento do vídeo que ainda não foi carregado.
player.getVideoBytesLoaded():Number
-
Uso suspenso em 18 de julho de 2012. Usar o método
getVideoLoadedFraction
para determinar a porcentagem de vídeo que foi armazenada em buffer.
Este método retorna um valor entre0
e1000
que se aproxima da quantidade do vídeo que foi carregada. Era possível calcular a fração do vídeo carregado ao dividir o valor degetVideoBytesLoaded
pelo valor degetVideoBytesTotal
.
player.getVideoBytesTotal():Number
-
Uso suspenso em 18 de julho de 2012. Usar o método
getVideoLoadedFraction
para determinar a porcentagem de vídeo que foi armazenada em buffer.
Retorna o tamanho em bytes do vídeo sendo carregado/reproduzido no momento ou uma aproximação do tamanho.
Este método sempre retorna o valor1000
. Era possível calcular a fração do vídeo carregado ao dividir o valor degetVideoBytesLoaded
pelo valor degetVideoBytesTotal
.
Qualidade da reprodução
player.getPlaybackQuality():String
- Esta função recupera a qualidade real do vídeo atual. Possíveis valores retornados:
highres
,hd1080
,hd720
,large
,medium
esmall
. Ela também retornaráundefined
se não houver vídeo atual.
player.setPlaybackQuality(suggestedQuality:String):Void
- Esta função define a qualidade de vídeo sugerida para o vídeo atual. A função faz com que o vídeo seja atualizado, em sua posição atual, com a nova qualidade. Se a qualidade de reprodução for alterada, ela só mudará para o vídeo reproduzido. Chamar essa função não garante que a qualidade da reprodução será realmente alterada. No entanto, se a qualidade de reprodução for alterada, o evento
onPlaybackQualityChange
será disparado e seu código responderá ao evento, em vez de chamar a funçãosetPlaybackQuality
.
O valor do parâmetrosuggestedQuality
pode sersmall
,medium
,large
,hd720
,hd1080
,highres
oudefault
. Recomendamos que você configure o valor do parâmetro comodefault
, que instrui o YouTube a selecionar a qualidade de reprodução mais adequada, o que variará para diferentes usuários, vídeos, sistemas e outras condições de reprodução.
Quando você sugerir uma qualidade de reprodução para um vídeo, a qualidade sugerida terá efeito apenas no vídeo em questão. É necessário selecionar uma qualidade de reprodução que corresponda ao tamanho de seu player de vídeo. Por exemplo, se a página exibir um player de vídeo de 1.280 px por 720 px, um vídeo de qualidadehd720
, na verdade, parecerá melhor do que um de qualidadehd1080
. Recomendamos chamar a funçãogetAvailableQualityLevels()
para determinar quais níveis de qualidade estão disponíveis para um vídeo.
A lista abaixo mostra os níveis qualidade de reprodução que correspondem a diferentes tamanhos de player padrão. Recomendamos que você configure a altura de seu player de vídeo para um dos valores listados abaixo e que dimensione seu player para usar a proporção 16:9. Conforme dito acima, mesmo se você escolher um tamanho padrão do player, também recomendamos que você configure o valor do parâmetrosuggestedQuality
comodefault
para permitir que o YouTube selecione a qualidade de reprodução mais adequada.- Nível de qualidade
small
: a altura do player é 240 px e suas dimensões são no mínimo 320 px por 240 px para a proporção 4:3. - Nível de qualidade
medium
: a altura player é 360 px e suas dimensões são 640 px por 360 px (para a proporção 16:9) ou 480 px por 360 px (para a proporção 4:3). - Nível de qualidade
large
: a altura do layer é 480 px e suas dimensões são 853 px por 480 px (para proporção 16:9) ou 640 px por 480 px (para a proporção 4:3). - Nível de qualidade
hd720
: a altura do player é 720 px e suas dimensões são 1.280 px por 720 px (para a proporção 16:9) ou 960 px por 720 px (para a proporção 4:3). - Nível de qualidade
hd1080
: altura do player é 1.080 px e suas dimensões são 1.920 px por 1.080 px (para a proporção 16:9) ou 1.440 px por 1.080 px (para a proporção 4:3). - Nível de qualidade
highres
: a altura do player é maior que 1.080 px, o que significa que sua proporção é maior que 1.920 px por 1.080 px. - Nível de qualidade
default
: o YouTube seleciona a qualidade de reprodução adequada. Esta configuração reverte de maneira efetiva o nível de qualidade para o estado padrão e anula todos os esforços anteriores para configurar a qualidade de reprodução usando as funçõescueVideoById
,loadVideoById
ousetPlaybackQuality
.
setPlaybackQuality
com um nívelsuggestedQuality
indisponível para o vídeo, então a qualidade será definida para o próximo nível mais baixo que estiver disponível. Por exemplo, se você solicitar um nível de qualidadelarge
e ele não estiver disponível, a qualidade de reprodução será configurada paramedium
(contanto que ele esteja disponível).
Além disso, a definição desuggestedQuality
como um valor que não é um nível de qualidade reconhecido é o mesmo que definirsuggestedQuality
comodefault
. - Nível de qualidade
player.getAvailableQualityLevels():Array
- Esta função retorna o conjunto de formatos de qualidade no qual o vídeo atual está disponível. É possível usar essa função para determinar se há uma qualidade superior à que o usuário está exibindo o vídeo, e o player pode exibir um botão ou outro elemento que permita ao usuário ajustar a qualidade.
A função retorna uma matriz de strings ordenadas da qualidade mais alta para a mais baixa. Possíveis valores dos elementos da matriz:highres
,hd1080
,hd720
,large
,medium
esmall
. Essa função retorna uma matriz vazia se não houver um vídeo sendo reproduzido.
Seu cliente não alternará automaticamente para a qualidade mais alta (ou mais baixa) ou para um nome de formato desconhecido. O YouTube pode expandir a lista de níveis de qualidade para incluir formatos que talvez não sejam adequados ao contexto de seu player. Da mesma forma, o YouTube pode remover opções de qualidade que prejudiquem a experiência do usuário. Ao assegurar que seu cliente alterne somente para formatos disponíveis e conhecidos, você pode garantir que o desempenho do cliente não será afetado pela introdução de novos níveis de qualidade e pela remoção de níveis de qualidade que não sejam adequados ao contexto do player.
Recuperar informações do vídeo
player.getDuration():Number
- Retorna a duração em segundos do vídeo que está sendo reproduzido. Observe que
getDuration()
retornará0
até que os metadados do vídeo sejam carregados, o que normalmente ocorre logo após o início da reprodução do vídeo.
Se o vídeo que estiver sendo reproduzido for um evento ao vivo, a funçãogetDuration()
retornará o tempo decorrido desde o início do stream do vídeo ao vivo. Especificamente, essa é a quantidade de tempo que o vídeo foi transmitido sem ser redefinido ou interrompido. Esta duração é geralmente maior do que a tempo real do evento, uma vez que o streaming pode começar antes da hora de início do evento.
player.getVideoUrl():String
- Retorna o URL YouTube.com para o vídeo carregado/em reprodução no momento.
player.getVideoEmbedCode():String
- Retorna o código incorporado para o vídeo carregado/em reprodução no momento.
Recuperar informações da playlist
player.getPlaylist():Array
- Esta função retorna uma matriz de IDs de vídeo na playlist em sua ordem atual. Por padrão, ela retornará IDs de vídeo na ordem designada pelo proprietário da playlist. No entanto, se você chamou a função
setShuffle
para reproduzir a playlist aleatoriamente, o valor de retorno da funçãogetPlaylist()
refletirá a ordem de reprodução aleatória.
player.getPlaylistIndex():Number
- Esta função retorna o índice do vídeo da playlist em reprodução no momento.
-
Se você não reproduziu a playlist aleatoriamente, o valor de retorno identificará a posição em que o criador de conteúdo da playlist colocou o vídeo. O valor de retorno usa um índice com base em zero, portanto, o valor
0
identifica o primeiro vídeo da playlist. -
Se você misturou a playlist, o valor de retorno identificará a ordem do vídeo dentro da lista aleatória.
-
Adicionar ou remover uma escuta de evento
player.addEventListener(event:String, listener:String):Void
- Adiciona uma função de listener para o
event
especificado. A seção Eventos abaixo identifica os diferentes eventos que o player pode disparar. O listener é uma string que especifica a função que será executada quando o evento especificado for disparado.
player.removeEventListener(event:String, listener:String):Void
- Remove uma função de escuta para o
event
especificado. Alistener
é uma string que identifica a função que será executada quando o evento especificado for disparado.
Acessar e modificar nós DOM
player.getIframe():Object
- Este método retorna o nó DOM para o
<iframe>
integrado.
player.destroy():Void
- Remove o
<iframe>
que contém o player.
Eventos
A API dispara eventos para notificar seu aplicativo sobre mudanças no player integrado. Conforme mencionado na seção anterior, você pode se inscrever em eventos ao adicionar um listener de eventos criar o objeto YT.Player
. Também é possível usar a função addEventListener
.
A API passará um objeto de evento como único argumento para cada uma dessas funções. O objeto de evento tem as seguintes propriedades:
- O evento
target
identifica o player de vídeo que corresponde ao evento. - A propriedade
data
do evento especifica um valor relevante para o evento. O eventoonReady
não especifica uma propriedadedata
.
A lista a seguir define os eventos que a API dispara:
onReady
- Esse evento é disparado sempre que um player terminar de carregar e estiver pronto para começar a receber chamadas de API. Seu aplicativo deve implementar essa função se você quiser executar algumas operações automaticamente, como a reprodução do vídeo ou a exibição de informações sobre o vídeo, assim que o player estiver pronto.
O exemplo abaixo mostra um exemplo de função para lidar com esse evento. O objeto de evento que a API passa para a função tem uma propriedadetarget
, que identifica o player. A função recupera o código de incorporação para o vídeo carregado no momento, começa a reproduzir o vídeo e exibe o código de incorporação no elemento de página que tiver um valorid
deembed-code
.function onPlayerReady(event) { var embedCode = event.target.getVideoEmbedCode(); event.target.playVideo(); if (document.getElementById('embed-code')) { document.getElementById('embed-code').innerHTML = embedCode; } }
onStateChange
- Esse evento é disparado sempre que o estado do player for alterado.
A propriedade
data
do objeto de evento que a API passa para sua função de listener de eventos especificará um número inteiro que corresponde ao novo estado do player. Os valores possíveis são:-1
(não iniciado)0
(encerrado)1
(em reprodução)2
(em pausa)3
(armazenando em buffer)5
(vídeo indicado).
unstarted
(-1
). Quando o vídeo estiver indicado e pronto para ser reproduzido, o player transmitirá um evento de vídeo indicadovideo cued
(5
). Em seu código, você pode especificar valores de números inteiros ou pode usar uma das seguintes variáveis namespaced:YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED
onPlaybackQualityChange
- Esse evento é disparado sempre que a qualidade de reprodução do vídeo for alterada. Por exemplo, se você chamar a função
setPlaybackQuality(suggestedQuality)
, esse evento será disparado se a qualidade de reprodução for realmente alterada. Seu aplicativo responderá ao evento e não pode assumir que a qualidade será automaticamente alterada quando a funçãosetPlaybackQuality(suggestedQuality)
é chamada. Da mesma forma, seu código não deve supor que a qualidade de reprodução será alterada somente como resultado de uma chamada explícita asetPlaybackQuality
ou a qualquer outra função que permita definir uma qualidade de reprodução sugerida.
O valor de propriedadedata
do objeto de evento que a API passa para a função de listener de eventos será uma string que identifica a nova qualidade de reprodução. Os valores possíveis são:small
medium
large
hd720
hd1080
highres
onPlaybackRateChange
- Esse evento é disparado sempre que a taxa de reprodução do vídeo for alterada. Por exemplo, se você chamar a função
setPlaybackRate(suggestedRate)
, esse evento será disparado se a taxa de reprodução for realmente alterada. Seu aplicativo responderá ao evento e não pode assumir que a taxa de reprodução será automaticamente alterada quando a funçãosetPlaybackRate(suggestedRate)
é chamada. Da mesma forma, seu código não pode assumir que a taxa de reprodução de vídeo será alterada somente como resultado de uma chamada explícita asetPlaybackRate
.
O valor de propriedadedata
do objeto de evento que a API passa para a função de listener de eventos será um número que identifica a nova taxa de reprodução. O métodogetAvailablePlaybackRates
retorna uma lista das taxas de reprodução válidas para o vídeo indicado ou em reprodução no momento.
onError
- Esse evento será disparado se ocorrer um erro no player.
A API passará um objeto
event
para a função de listener de evento. A propriedadedata
desse objeto especificará um número inteiro que identifica o tipo de erro ocorrido. Os valores possíveis são:2
– A solicitação contém um valor de parâmetro inválido. Por exemplo, este erro ocorre se você especificar um ID de vídeo que não tem 11 caracteres, ou se o ID de vídeo contém caracteres inválidos, como pontos de exclamação ou asteriscos.5
– O conteúdo solicitado não pode ser reproduzido em um player HTML5, ou ocorreu outro erro relacionado ao player HTML5.100
– O vídeo solicitado não foi encontrado. Esse erro ocorrerá quando um vídeo tiver sido removido (por qualquer motivo) ou marcado como privado.101
- O proprietário do vídeo solicitado não permite que ele seja reproduzido em players incorporados.150
– Esse erro é o mesmo que o101
. É apenas um erro101
disfarçado.
onApiChange
- Esse evento é disparado para indicar que o player carregou (ou descarregou) um módulo com métodos de API expostos. Seu aplicativo pode ouvir esse evento e, em seguida, sondar o player para determinar quais opções estão expostas para o módulo recém-carregado. Seu aplicativo pode, então, recuperar ou atualizar as configurações existentes para essas opções.
O comando a seguir recupera uma matriz de nomes de módulos para a qual você pode definir as opções de player:
player.getOptions();
Atualmente, o único módulo para o qual você pode definir opções é occ
, que lida com closed caption no player. Ao receber um eventoonApiChange
, seu aplicativo pode usar o seguinte comando para determinar quais opções podem ser definidas para o módulocc
:
player.getOptions('cc');
Ao sondar o player com esse comando, é possível confirmar se as opções que você deseja acessar estão, de fato, acessíveis. Os seguintes comandos recuperam e atualizam as opções de módulo:
Recuperar uma opção: player.getOption(module, option); configurar uma opção player.setOption(module, option, value);
A tabela abaixo lista as opções compatíveis com a API:
Módulo Opção Descrição cc fontSize Essa opção ajusta o tamanho da fonte das legendas exibidas no player.
Os valores válidos são-1
,0
,1
,2
e3
. O tamanho padrão é0
e o menor tamanho é-1
. A definição dessa opção como um número inteiro menor que-1
fará com que o menor tamanho de legenda seja exibido, enquanto que a definição dessa opção como um número inteiro maior que3
fará com que o maior tamanho de legenda seja exibido.cc reload Essa opção recarrega os dados de closed caption para o vídeo que estiver sendo reproduzido. O valor será null
se você recuperar o valor da opção. Defina o valor paratrue
para recarregar os dados de closed caption.
Considerações de dispositivos móveis
Reprodução automática e reprodução com script
Em determinados navegadores móveis (como Chrome e Safari), o elemento HTML5 <video>
só permite que a reprodução ocorra se ela for iniciada por uma interação do usuário (como tocar no player). Veja um trecho da documentação da Apple:
"Aviso: para impedir downloads não solicitados por redes celulares à custa do usuário, a mídia incorporada não pode ser reproduzida automaticamente no Safari no iOS. O usuário sempre inicia a reprodução."
Devido a esta restrição, funções e parâmetros, como autoplay
, playVideo()
e loadVideoById()
, não funcionarão em todos os ambientes de dispositivos móveis.
Exemplos
Criar objetos YT.Player
-
Exemplo 1: reprodução com volume alto
Este exemplo cria um player de vídeo de 1.280 px por 720 px. O listener do evento
onReady
chama a funçãosetVolume
para ajustar o volume na configuração mais alta.function onYouTubeIframeAPIReady() { var player; player = new YT.Player('player', { width: 1280, height: 720, videoId: 'M7lc1UVf-VE', events: { 'onReady': onPlayerReady, 'onPlaybackQualityChange': onPlayerPlaybackQualityChange, 'onStateChange': onPlayerStateChange, 'onError': onPlayerError } }); } function onPlayerReady(event) { event.target.setVolume(100); event.target.playVideo(); }
-
Exemplo 2: este exemplo define os parâmetros do player para reproduzir o vídeo automaticamente quando ele carregar e para ocultar os controles do player de vídeo. Ele também adiciona listeners de eventos a todos os eventos que a API transmite.
function onYouTubeIframeAPIReady() { var player; player = new YT.Player('player', { videoId: 'M7lc1UVf-VE', playerVars: { 'autoplay': 1, 'controls': 0 }, events: { 'onReady': onPlayerReady, 'onPlaybackQualityChange': onPlayerPlaybackQualityChange, 'onStateChange': onPlayerStateChange, 'onError': onPlayerError } }); }
Histórico de revisão
Esta seção lista as alterações na API do player IFrame do YouTube e as atualizações da documentação. Inscreva-se neste changelog..
April 28, 2014
This update contains the following changes:
-
The new removeEventListener function lets you remove a listener for a specified event.
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 whenplayVideo()
is called. -
The
getVideoStartBytes
method has been deprecated. The method now always returns a value of0
.
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 theonYouTubeIframeAPIReady
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
onPlaybackRateChange
– This event fires when the video's playback rate changes.
-
July 19, 2012
This update contains the following changes:
-
The new
getVideoLoadedFraction
method replaces the now-deprecatedgetVideoBytesLoaded
andgetVideoBytesTotal
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 of5
, 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 namedonYouTubePlayerAPIReady
. 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 anonYouTubePlayerAPIReady
function, both functions will be called, and theonYouTubeIframeAPIReady
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()
anddestroy()
methods. ThesetSize()
method sets the size in pixels of the<iframe>
that contains the player and thedestroy()
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 aninline-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.