La API del reproductor IFrame permite insertar un reproductor de video de YouTube en un sitio web y controlar el reproductor con JavaScript.
Mediante el uso de las funciones JavaScript de la API puedes poner videos en cola para su reproducción, reproducir, pausar o detener los videos, ajustar el volumen del reproductor o recuperar la información sobre el video en reproducción. También puedes agregar objetos de escucha de eventos que se ejecutarán en respuesta a ciertos eventos del reproductor, como un cambio de estado del reproductor.
En esta guía, se explica cómo usar la API de IFrame. Identifica los diferentes tipos de eventos que la API puede enviar y explica cómo escribir objetos de escucha de eventos para responder a esos eventos. También se detallan las diferentes funciones de JavaScript que es posible invocar para controlar el reproductor de video, así como los parámetros del reproductor que se pueden utilizar para personalizar el reproductor.
Requisitos
El navegador del usuario debe ser compatible con la función postMessage
de HTML5. La mayoría de los navegadores modernos admiten postMessage
.
Los reproductores insertados deben tener una ventana gráfica de al menos 200 px por 200 px. Si el reproductor muestra controles, debe tener el tamaño suficiente para mostrar los controles por completo, sin reducir la ventana gráfica por debajo del tamaño mínimo. Recomendamos que los reproductores de 16:9 tengan al menos 480 píxeles de ancho y 270 píxeles de alto.
Cualquier página web que utilice la API de IFrame también debe implementar la siguiente función de JavaScript:
-
onYouTubeIframeAPIReady
: La API invoca esta función cuando la página termina de descargar el código JavaScript para la API del reproductor, que te permite utilizar la API en tu página. Por lo tanto, esta función podrá crear los objetos del reproductor que deseas mostrar cuando se cargue la página.
Primeros pasos
La página HTML de ejemplo que se muestra a continuación crea un reproductor insertado que carga un video, lo reproduce durante seis segundos y luego detiene la reproducción. Los comentarios numerados en el código HTML se explican en la lista posterior al ejemplo.
<!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>
La siguiente lista ofrece más detalles sobre el ejemplo anterior:
-
La etiqueta
<div>
de esta sección identifica la ubicación dentro de la página donde la API de IFrame posicionará el reproductor de video. El constructor del objeto del reproductor, que se describe en la sección Cómo cargar un reproductor de video, identifica la etiqueta<div>
por suid
para garantizar que la API coloque<iframe>
en la ubicación correcta. Específicamente, la API de IFrame reemplazará la etiqueta<div>
con la etiqueta<iframe>
.Como alternativa, también puedes colocar el elemento
<iframe>
directamente en la página. En la sección Cómo cargar un reproductor de video se explica cómo hacerlo. -
El código de esta sección carga el código JavaScript de la API del reproductor IFrame. En el ejemplo se utiliza la modificación de DOM para descargar el código de la API con el fin de comprobar que el código se recupera de forma asíncrona. (El atributo
async
de la etiqueta<script>
, que también habilita las descargas asíncronas, aún no es compatible con todos los navegadores modernos, como se explica en esta respuesta de Stack Overflow). -
La función
onYouTubeIframeAPIReady
se ejecutará en cuanto se descargue el código de la API del reproductor. Esta parte del código define una variable global,player
, que hace referencia al reproductor de video que estás incorporando. Luego, la función construye el objeto del reproductor de video. -
La función
onPlayerReady
se ejecutará cuando se active el eventoonReady
. En este ejemplo, la función indica que la reproducción debe comenzar cuando el reproductor de video está listo. -
La API llamará a la función
onPlayerStateChange
cuando cambie el estado del reproductor, lo que puede indicar que el reproductor está reproduciendo, detenido, finalizado, etcétera. La función indica que cuando el estado del reproductor es1
(en reproducción), el reproductor debe reproducir un video durante seis segundos y luego invocar la funciónstopVideo
para detener el video.
Cómo cargar un reproductor de video
Después de que se cargue el código JavaScript de la API, la API llamará a la función onYouTubeIframeAPIReady
. En ese momento, podrás construir un objeto YT.Player
para insertar un reproductor de video en tu página. En el siguiente extracto de HTML, se muestra la función onYouTubeIframeAPIReady
del ejemplo anterior:
var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '390', width: '640', videoId: 'M7lc1UVf-VE', playerVars: { 'playsinline': 1 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); }
El constructor para el reproductor de video especifica los siguientes parámetros:
-
El primer parámetro especifica el elemento DOM o el
id
del elemento HTML donde la API insertará la etiqueta<iframe>
que contiene el reproductor.La API de IFrame reemplazará el elemento especificado con el elemento
<iframe>
que contiene el reproductor. Esto podría afectar el diseño de tu página si el elemento que se reemplaza tiene un estilo de visualización diferente al del elemento<iframe>
insertado. De forma predeterminada, un<iframe>
se muestra como un elementoinline-block
. - El segundo parámetro es un objeto que especifica las opciones del reproductor. El objeto contiene las siguientes propiedades:
width
(número): Es el ancho del reproductor de video. El valor predeterminado es640
.height
(número): Es la altura del reproductor de video. El valor predeterminado es390
.videoId
(cadena): el ID de video de YouTube que identifica el video que cargará el reproductor.playerVars
(objeto): Las propiedades del objeto identifican los parámetros del reproductor que se pueden utilizar para personalizar el reproductor.events
(objeto): Las propiedades del objeto identifican los eventos que la API activa y las funciones (objetos de escucha de eventos) a las que llamará la API cuando se produzcan esos eventos. En el ejemplo, el constructor indica que la funciónonPlayerReady
se ejecutará cuando se active el eventoonReady
y que la funciónonPlayerStateChange
se ejecutará cuando se active el eventoonStateChange
.
Como se mencionó en la sección Cómo comenzar, en lugar de escribir un elemento <div>
vacío en tu página, que el código JavaScript de la API del reproductor reemplazará por un elemento <iframe>
, podrías crear la etiqueta <iframe>
tú mismo. En el primer ejemplo de la sección Ejemplos, se muestra cómo hacerlo.
<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>
Ten en cuenta que, si escribes la etiqueta <iframe>
, cuando construyes el objeto YT.Player
, no necesitas especificar valores para width
y height
, que se especifican como atributos de la etiqueta <iframe>
, o los parámetros videoId
y reproductor, que se especifican en la URL src
. Como medida de seguridad adicional, también debes incluir el parámetro origin
en la URL y especificar el esquema de URL (http://
o https://
) y el dominio completo de tu página de alojamiento como valor del parámetro. Aunque origin
es opcional, incluir protección contra código JavaScript malicioso de terceros que se introduzca en tu página y que usurpe el control de tu reproductor de YouTube.
En la sección Ejemplos, también se muestran otros dos ejemplos de construcción de objetos del reproductor de video.
Operaciones
Para invocar los métodos de la API del reproductor, debes obtener una referencia al objeto del reproductor que deseas controlar. A fin de obtener la referencia, crea un objeto YT.Player
como se explica en las secciones Introducción y Cómo cargar un reproductor de video de este documento.
remotas
Funciones de fila
Las funciones de fila permiten cargar y reproducir un video, una lista de reproducción u otra lista de videos. Si usas la sintaxis de objetos que se describe a continuación para invocar estas funciones, también puedes poner en fila o cargar una lista de los videos subidos de un usuario.
La API es compatible con dos sintaxis diferentes para invocar las funciones de fila.
-
La sintaxis de argumentos requiere que los argumentos de funciones se ordenen de acuerdo con un orden prescrito.
-
La sintaxis de objetos permite transferir un objeto como un parámetro único y definir las propiedades del objeto de los argumentos de la función que quieres ajustar. Además, la API puede admitir funciones adicionales que la sintaxis de argumentos no admite.
Por ejemplo, se puede llamar a la función loadVideoById
de cualquiera de las siguientes maneras. Ten en cuenta que la sintaxis de objetos admite la propiedad endSeconds
, que la sintaxis de argumentos no admite.
-
Sintaxis de argumentos
loadVideoById("bHQqvYy5KYo", 5, "large")
-
Sintaxis de objetos
loadVideoById({'videoId': 'bHQqvYy5KYo', 'startSeconds': 5, 'endSeconds': 60});
Funciones de fila de videos
cueVideoById
-
-
Sintaxis de argumentos
player.cueVideoById(videoId:String, startSeconds:Number):Void
-
Sintaxis de objetos
player.cueVideoById({videoId:String, startSeconds:Number, endSeconds:Number}):Void
Esta función carga la miniatura del video indicado y prepara el reproductor para reproducir el video. El reproductor no solicita el FLV hasta que se llame a
playVideo()
oseekTo()
.- El parámetro obligatorio
videoId
especifica el ID de video de YouTube del video que se va a reproducir. En la API de datos de YouTube, la propiedadid
de un recursovideo
especifica el ID. - El parámetro opcional
startSeconds
acepta un número decimal o entero e indica el tiempo desde el que el video debe comenzar a reproducirse cuando se llama aplayVideo()
. Si especificas un valorstartSeconds
y, luego, llamas aseekTo()
, el reproductor reproducirá desde el momento especificado en la llamadaseekTo()
. Cuando el video está en fila y listo para reproducirse, el reproductor transmite un eventovideo cued
(5
). - El parámetro opcional
endSeconds
, que solo se admite en la sintaxis de objetos, acepta un número decimal o entero e indica el momento en que el video debe dejar de reproducirse cuando se llama aplayVideo()
. Si especificas un valorendSeconds
y, luego, llamas aseekTo()
, el valorendSeconds
ya no estará vigente.
-
loadVideoById
-
-
Sintaxis de argumentos
player.loadVideoById(videoId:String, startSeconds:Number):Void
-
Sintaxis de objetos
player.loadVideoById({videoId:String, startSeconds:Number, endSeconds:Number}):Void
Esta función carga y reproduce el video indicado.
- El parámetro obligatorio
videoId
especifica el ID de video de YouTube del video que se va a reproducir. En la API de datos de YouTube, la propiedadid
de un recursovideo
especifica el ID. - El parámetro opcional
startSeconds
acepta un número decimal o entero. Si se indica, el video empieza a reproducirse desde el fotograma clave más cercano al momento indicado. - El parámetro opcional
endSeconds
acepta un número decimal o entero. Si se indica, el video deja de reproducirse desde el momento indicado.
-
cueVideoByUrl
-
-
Sintaxis de argumentos
player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
-
Sintaxis de objetos
player.cueVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number}):Void
Esta función carga la miniatura del video indicado y prepara el reproductor para reproducir el video. El reproductor no solicita el FLV hasta que se llame a
playVideo()
oseekTo()
.- El parámetro obligatorio
mediaContentUrl
especifica una URL de reproductor de YouTube completamente calificada en el formatohttp://www.youtube.com/v/VIDEO_ID?version=3
. - El parámetro opcional
startSeconds
acepta un número decimal o entero e indica el tiempo desde el que el video debe comenzar a reproducirse cuando se llama aplayVideo()
. Si especificasstartSeconds
y, luego, llamas aseekTo()
, el reproductor reproducirá desde el momento especificado en la llamadaseekTo()
. Cuando el video está en fila y listo para reproducirse, el reproductor transmite un eventovideo cued
(5). - El parámetro opcional
endSeconds
, que solo se admite en la sintaxis de objetos, acepta un número decimal o entero e indica el momento en que el video debe dejar de reproducirse cuando se llama aplayVideo()
. Si especificas un valorendSeconds
y, luego, llamas aseekTo()
, el valorendSeconds
ya no estará vigente.
-
loadVideoByUrl
-
-
Sintaxis de argumentos
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
-
Sintaxis de objetos
player.loadVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number}):Void
Esta función carga y reproduce el video indicado.
- El parámetro obligatorio
mediaContentUrl
especifica una URL de reproductor de YouTube completamente calificada en el formatohttp://www.youtube.com/v/VIDEO_ID?version=3
. - El parámetro opcional
startSeconds
acepta un número decimal o entero e indica el tiempo desde el que el video debe comenzar a reproducirse. Si se especifica un valor destartSeconds
(el número puede ser un número de punto flotante), el video comenzará desde el fotograma clave más cercano al tiempo especificado. - El parámetro opcional
endSeconds
, que solo se admite en la sintaxis de objetos, acepta un número decimal o entero e indica el momento en que el video debe dejar de reproducirse.
-
Funciones de fila de listas
Las funciones cuePlaylist
y loadPlaylist
te permiten cargar y reproducir una lista de reproducción. Si usas sintaxis de objetos para invocar estas funciones, también puedes poner en cola (o cargar) una lista de los videos subidos de un usuario.
Las funciones son diferentes en función de si se las invoca utilizando la sintaxis de argumentos o la sintaxis de objetos. En vista de aquello, ambos métodos para invocarlas se documentan a continuación.
cuePlaylist
-
-
Sintaxis de argumentos
player.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
Pone en cola la lista de reproducción especificada. Cuando la lista de reproducción está en fila y lista para reproducirse, el reproductor transmite un eventovideo cued
(5
).-
El parámetro obligatorio
playlist
especifica un conjunto de ID de video de YouTube. En la API de datos de YouTube, la propiedadid
del recursovideo
identifica el ID de ese video. -
El parámetro opcional
index
especifica el índice del primer video de la lista de reproducción que se va a reproducir. El parámetro utiliza un índice basado en cero y el valor predeterminado del parámetro es0
, por lo que el comportamiento predeterminado es cargar y reproducir el primer video de la lista de reproducción. -
El parámetro opcional
startSeconds
acepta un número decimal o entero e indica el tiempo desde el que debe comenzar a reproducirse el primer video de la lista de reproducción cuando se invoca la funciónplayVideo()
. Si especificas un valorstartSeconds
y, luego, llamas aseekTo()
, el reproductor reproducirá desde el momento especificado en la llamadaseekTo()
. Si pones en fila una lista de reproducción y luego invocas la funciónplayVideoAt()
, el reproductor comenzará a reproducir el comienzo del video especificado.
-
-
Sintaxis de objetos
player.cuePlaylist({listType:String, list:String, index:Number, startSeconds:Number}):Void
Pone en cola la lista de videos especificada. La lista puede ser una lista de reproducción o el feed de videos subidos de un usuario. La función para poner en fila una lista de resultados de la búsqueda está obsoleta y ya no se admitirá a partir del15 de noviembre de 2020 .Cuando la lista está en fila y lista para reproducirse, el reproductor transmite un evento
video cued
(5
).-
La propiedad opcional
listType
especifica el tipo de feed de resultados que se va a recuperar. Los valores válidos sonplaylist
yuser_uploads
. A partir del15 de noviembre de 2020 , ya no se admitirá un valor obsoleto,search
. El valor predeterminado esplaylist
. -
La propiedad obligatoria
list
contiene una clave que identifica la lista específica de videos que YouTube debe mostrar.- Si el valor de la propiedad
listType
esplaylist
, la propiedadlist
especifica el ID de la lista de reproducción o un array de IDs de video. En la API de datos de YouTube, la propiedadid
del recursoplaylist
identifica el ID de una lista de reproducción, y la propiedadid
del recursovideo
especifica un ID de video. - Si el valor de la propiedad
listType
esuser_uploads
, la propiedadlist
identifica al usuario cuyos videos subidos se mostrarán. - Si el valor de la propiedad
listType
essearch
, la propiedadlist
especifica la búsqueda. Nota: Esta función está obsoleta y dejará de ser compatible a partir del15 de noviembre de 2020 .
- Si el valor de la propiedad
-
La propiedad opcional
index
especifica el índice del primer video de la lista que se va a reproducir. El parámetro utiliza un índice basado en cero y el valor predeterminado del parámetro es0
, por lo que el comportamiento predeterminado es cargar y reproducir el primer video de la lista. -
La propiedad opcional
startSeconds
acepta un número de punto flotante o entero y especifica el tiempo desde el que debe comenzar a reproducirse el primer video de la lista cuando se llama a la funciónplayVideo()
. Si especificas un valorstartSeconds
y, luego, llamas aseekTo()
, el reproductor reproducirá desde el momento especificado en la llamadaseekTo()
. Si pone en fila una lista y luego llama a la funciónplayVideoAt()
, el reproductor comenzará a reproducir el comienzo del video especificado.
-
-
loadPlaylist
-
-
Sintaxis de argumentos
player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
Esta función carga la lista de reproducción especificada y la reproduce.-
El parámetro obligatorio
playlist
especifica un conjunto de ID de video de YouTube. En la API de datos de YouTube, la propiedadid
del recursovideo
especifica un ID de video. -
El parámetro opcional
index
especifica el índice del primer video de la lista de reproducción que se va a reproducir. El parámetro utiliza un índice basado en cero y el valor predeterminado del parámetro es0
, por lo que el comportamiento predeterminado es cargar y reproducir el primer video de la lista de reproducción. -
El parámetro opcional
startSeconds
acepta un número decimal o entero e indica el tiempo desde el que debe comenzar a reproducirse el primer video de la lista de reproducción.
-
-
Sintaxis de objetos
player.loadPlaylist({list:String, listType:String, index:Number, startSeconds:Number}):Void
Esta función carga la lista especificada y la reproduce. La lista puede ser una lista de reproducción o el feed de videos subidos de un usuario. La capacidad de cargar una lista de resultados de la búsqueda está obsoleta y ya no se admitirá a partir del15 de noviembre de 2020 .-
La propiedad opcional
listType
especifica el tipo de feed de resultados que se va a recuperar. Los valores válidos sonplaylist
yuser_uploads
. A partir del15 de noviembre de 2020 , ya no se admitirá un valor obsoleto,search
. El valor predeterminado esplaylist
. -
La propiedad obligatoria
list
contiene una clave que identifica la lista específica de videos que YouTube debe mostrar.- Si el valor de la propiedad
listType
esplaylist
, la propiedadlist
especifica un ID de lista de reproducción o un array de IDs de video. En la API de datos de YouTube, la propiedadid
del recursoplaylist
especifica el ID de una lista de reproducción y la propiedadid
del recursovideo
especifica un ID de video. - Si el valor de la propiedad
listType
esuser_uploads
, la propiedadlist
identifica al usuario cuyos videos subidos se mostrarán. - Si el valor de la propiedad
listType
essearch
, la propiedadlist
especifica la búsqueda. Nota: Esta función está obsoleta y dejará de ser compatible a partir del15 de noviembre de 2020 .
- Si el valor de la propiedad
-
La propiedad opcional
index
especifica el índice del primer video de la lista que se va a reproducir. El parámetro utiliza un índice basado en cero y el valor predeterminado del parámetro es0
, por lo que el comportamiento predeterminado es cargar y reproducir el primer video de la lista. -
La propiedad opcional
startSeconds
acepta un número de punto flotante o entero y especifica el tiempo desde el que debe comenzar a reproducirse el primer video de la lista.
-
-
Controles de reproducción y configuración del reproductor
Reproducción de un video
player.playVideo():Void
- Reproduce el video que se encuentra actualmente cargado o en fila. El estado final del reproductor después de que se ejecuta esta función es
playing
(1).
Nota: Una reproducción solo se contabiliza para el recuento de vistas oficial de un video si se inicia a través de un botón de reproducción nativo en el reproductor.
player.pauseVideo():Void
- Pausa el video que se está reproduciendo. El estado final del reproductor después de que se ejecute esta función será
paused
(2
), a menos que el reproductor se encuentre en el estadoended
(0
) cuando se llame a la función, en cuyo caso el estado del reproductor no cambiará.
player.stopVideo():Void
- Detiene y cancela la carga del video actual. Esta función debe reservarse para situaciones excepcionales cuando se sabe que el usuario no va a mirar videos adicionales en el reproductor. Si tu intención es pausar el video, solo debes llamar a la función
pauseVideo
. Si quieres cambiar el video que se está reproduciendo en el reproductor, puedes llamar a una de las funciones de fila sin antes llamar astopVideo
.
Importante: A diferencia de la funciónpauseVideo
, que deja al jugador en el estadopaused
(2
), la funciónstopVideo
podría colocar al jugador en cualquier estado que no se esté reproduciendo, incluidosended
(0
),paused
(2
),video cued
(5
) ounstarted
(-1
).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
- Avanza a un momento específico del video. Si el reproductor está en pausa cuando se invoca la función, se mantendrá en pausa. Si se invoca la función desde otro estado (
playing
,video cued
, etc.), el reproductor reproducirá el video.-
El parámetro
seconds
identifica el momento en que el reproductor debe avanzar.El reproductor avanza al fotograma clave más cercano antes de ese tiempo a menos que el reproductor ya haya descargado la parte del video que el usuario está buscando.
-
El parámetro
allowSeekAhead
determina si el reproductor realizará una nueva solicitud al servidor si el parámetroseconds
especifica un tiempo fuera de los datos de video almacenados en búfer actualmente.Te recomendamos establecer este parámetro en
false
mientras el usuario arrastra el mouse por la barra de progreso de un video y, luego, establecerlo entrue
cuando el usuario suelta el mouse. Este método permite al usuario desplazarse por distintos puntos del video que no se han almacenado en el búfer sin solicitar nuevas secuencias de video. Cuando el usuario suelta el botón del mouse, el reproductor avanza hasta el punto deseado en el video y solicita una nueva secuencia de video si es necesario.
-
Cómo controlar la reproducción de videos en 360°
Nota: La experiencia de reproducción de video en 360° tiene compatibilidad limitada en dispositivos móviles. En los dispositivos no compatibles, los videos panorámicos de 360° aparecen distorsionados y no se admite cambiar la perspectiva de visualización, incluida la API, el uso de sensores de orientación o la respuesta a acciones de tocar y arrastrar en la pantalla del dispositivo.
player.getSphericalProperties():Object
- Recupera las propiedades que describen la perspectiva o vista actual del usuario para la reproducción de un video. Además:
- Este objeto solo se propaga para los videos panorámicos de 360°, que también se denominan videos esféricos.
- Si el video actual no es un video panorámico de 360° o si la función se invoca desde un dispositivo no compatible, la función devuelve un objeto vacío.
- En los dispositivos móviles compatibles, si la propiedad
enableOrientationSensor
está configurada comotrue
, esta función muestra un objeto en el que la propiedadfov
contiene el valor correcto y las otras propiedades se establecen en0
.
Propiedades yaw
Es un número en el rango [0, 360) que representa el ángulo horizontal de la vista en grados, lo que refleja en qué medida el usuario gira la vista para mirar más hacia la izquierda o la derecha. La posición neutra, mirando al centro del video en su proyección equirrectangular, representa 0°, y este valor aumenta a medida que el espectador gira a la izquierda. pitch
Es un número en el rango [-90, 90] que representa el ángulo vertical de la vista en grados, lo que refleja en qué medida el usuario ajusta la vista para mirar hacia arriba o hacia abajo. La posición neutra, mirando al centro del video en su proyección equirrectangular, representa 0°, y este valor aumenta a medida que el usuario mira hacia arriba. roll
Es un número en el rango [-180, 180] que representa el ángulo de rotación en el sentido de las manecillas del reloj o en el sentido contrario a las manecillas del reloj de la vista en grados. La posición neutra, con el eje horizontal en la proyección equirrectangular paralelo al eje horizontal de la vista, representa 0°. El valor aumenta a medida que la vista gira en el sentido de las manecillas del reloj y disminuye a medida que la vista se rota en sentido contrario a las manecillas del reloj.
Ten en cuenta que el reproductor incorporado no presenta una interfaz de usuario para ajustar la rueda de la vista. El lanzamiento se puede ajustar de cualquiera de estas formas mutuamente excluyentes:- Usa el sensor de orientación en un navegador para dispositivos móviles a fin de proporcionar giros para la vista. Si el sensor de orientación está habilitado, la función
getSphericalProperties
siempre muestra0
como el valor de la propiedadroll
. - Si el sensor de orientación está inhabilitado, configura el giro en un valor distinto de cero con esta API.
fov
Un número en el rango [30, 120] que representa el campo visual de la vista en grados según la medida a lo largo del borde más largo del viewport. El borde más corto se ajusta automáticamente para que sea proporcional a la relación de aspecto de la vista.
El valor predeterminado es de 100 grados. Disminuir el valor es como acercar el contenido del video y aumentar el valor como alejarlo. Este valor se puede ajustar mediante la API o la rueda del mouse cuando el video se encuentra en el modo de pantalla completa.
player.setSphericalProperties(properties:Object):Void
- Establece la orientación del video para la reproducción de un video panorámico de 360°. (Si el video actual no es esférico, el método es un no-op independientemente de la entrada).
La vista del reproductor responde a las llamadas a este método actualizando para reflejar los valores de cualquier propiedad conocida en el objetoproperties
. La vista conserva los valores de cualquier otra propiedad conocida que no esté incluida en ese objeto.
Además:- Si el objeto contiene propiedades desconocidas o inesperadas, el reproductor las ignorará.
- Como se señaló al comienzo de esta sección, la experiencia de reproducción de videos en 360° no es compatible con todos los dispositivos móviles.
- De forma predeterminada, en los dispositivos móviles compatibles, esta función establece solo la propiedad
fov
y no afecta las propiedadesyaw
,pitch
yroll
para las reproducciones de video en 360°. Consulta la propiedadenableOrientationSensor
a continuación para obtener más detalles.
properties
que se pasa a la función contiene las siguientes propiedades:Propiedades yaw
Consulte la definición más arriba. pitch
Consulte la definición más arriba. roll
Consulte la definición más arriba. fov
Consulte la definición más arriba. enableOrientationSensor
Nota: Esta propiedad afecta la experiencia de visualización de 360° solo en dispositivos compatibles.Un valor booleano que indica si la incorporación IFrame debe responder a eventos que indiquen cambios en la orientación de un dispositivo compatible, como el DeviceOrientationEvent
de un navegador para dispositivos móviles. El valor predeterminado del parámetro estrue
.
Dispositivos móviles compatibles- Cuando el valor es
true
, el reproductor incorporado solo depende del movimiento del dispositivo para ajustar las propiedadesyaw
,pitch
yroll
de las reproducciones de video en 360°. Sin embargo, la propiedadfov
aún se puede cambiar a través de la API y, de hecho, la API es la única forma de cambiar la propiedadfov
en un dispositivo móvil. Este es el comportamiento predeterminado. - Cuando el valor es
false
, el movimiento del dispositivo no afecta la experiencia de visualización de 360°, y las propiedadesyaw
,pitch
,roll
yfov
deben configurarse mediante la API.
Dispositivos móviles no compatibles
El valor de la propiedadenableOrientationSensor
no tiene ningún efecto en la experiencia de reproducción.
Reproducción de un video en una lista de reproducción
player.nextVideo():Void
- Esta función carga y reproduce el siguiente video de la lista de reproducción.
-
Si se invoca
player.nextVideo()
mientras se reproduce el último video de la lista de reproducción y la lista de reproducción está configurada para reproducir continuamente (loop
), el reproductor cargará y reproducirá el primer video de la lista. -
Si se llama a
player.nextVideo()
mientras se reproduce el último video de la lista de reproducción y la lista de reproducción no está configurada para reproducir continuamente, la reproducción finalizará.
-
player.previousVideo():Void
- Esta función carga y reproduce el video anterior de la lista de reproducción.
-
Si se invoca
player.previousVideo()
mientras se reproduce el primer video de la lista de reproducción y la lista de reproducción está configurada para reproducir continuamente (loop
), el reproductor cargará y reproducirá el último video de la lista. -
Si se invoca
player.previousVideo()
mientras se reproduce el primer video de la lista de reproducción y la lista de reproducción no está configurada para reproducir continuamente, el reproductor reiniciará el primer video de la lista de reproducción desde el principio.
-
player.playVideoAt(index:Number):Void
- Esta función carga y reproduce el video indicado en la lista de reproducción.
-
El parámetro obligatorio
index
especifica el índice del video que se desea reproducir en la lista de reproducción. El parámetro utiliza un índice basado en cero, por lo que un valor de0
identifica el primer video de la lista. Si se selecciona la reproducción aleatoria de la lista de reproducción, esta función reproduce el video en la posición indicada en la lista de reproducción reproducida aleatoriamente.
-
Modificación del volumen del reproductor
player.mute():Void
- Silencia al reproductor.
player.unMute():Void
- Activa el sonido del jugador.
player.isMuted():Boolean
- Muestra
true
si el reproductor está silenciado, yfalse
si no lo está.
player.setVolume(volume:Number):Void
- Establece el volumen. Acepta un número entero entre
0
y100
.
player.getVolume():Number
- Muestra el volumen actual del reproductor, un número entero entre
0
y100
. Ten en cuenta quegetVolume()
volverá a mostrar el volumen, incluso si el reproductor está silenciado.
Configuración del tamaño del reproductor
player.setSize(width:Number, height:Number):Object
- Establece el tamaño en píxeles del
<iframe>
que contiene el reproductor.
Ajuste de la velocidad de reproducción
player.getPlaybackRate():Number
- Esta función recupera la velocidad de reproducción del video que se está reproduciendo en ese momento. La velocidad de reproducción predeterminada es
1
, lo que indica que el video se reproduce a velocidad normal. Las velocidades de reproducción pueden incluir valores como0.25
,0.5
,1
,1.5
y2
.
player.setPlaybackRate(suggestedRate:Number):Void
- Esta función establece la velocidad de reproducción sugerida para el video actual. Si la velocidad de reproducción cambia, solo afecta al video actualmente en fila o en reproducción. Si configuras la velocidad de reproducción de un video en fila, esa velocidad seguirá vigente cuando se invoque la función
playVideo
o el usuario inicie la reproducción directamente a través de los controles del reproductor. Además, invocar funciones para poner en fila o cargar videos o listas de reproducción (cueVideoById
,loadVideoById
, etc.) restablecerá la velocidad de reproducción a1
.
Llamar a esta función no garantiza que la velocidad de reproducción cambie realmente. Sin embargo, si la velocidad de reproducción cambia, se activa el eventoonPlaybackRateChange
, y tu código debe responder al evento en lugar del hecho de que llamó a la funciónsetPlaybackRate
.
El métodogetAvailablePlaybackRates
mostrará las velocidades de reproducción posibles del video que se está reproduciendo en ese momento. Sin embargo, si estableces el parámetrosuggestedRate
en un valor entero o flotante no admitido, el reproductor redondea ese valor hacia abajo hasta el valor admitido más cercano en la dirección de1
.
player.getAvailablePlaybackRates():Array
- Esta función muestra el conjunto de velocidades de reproducción en las que está disponible el video actual. El valor predeterminado es
1
, lo que indica que el video se está reproduciendo a velocidad normal.
La función muestra un array de números ordenados de la velocidad de reproducción más baja a la más rápida. Incluso si el reproductor no admite velocidades variables de reproducción, el array siempre debe contener al menos un valor (1
).
Configuración de la reproducción de listas de reproducción
player.setLoop(loopPlaylists:Boolean):Void
-
Esta función indica si el reproductor de video debe reproducir continuamente una lista de reproducción o si debe detener la reproducción al finalizar el último video de la lista de reproducción. El comportamiento predeterminado es que las listas de reproducción no se reproduzcan en bucle.
Esta configuración se mantendrá incluso si cargas o pones en fila una lista de reproducción diferente, lo que significa que si cargas una lista de reproducción, llamas a la función
setLoop
con un valor detrue
y, luego, cargas una segunda lista de reproducción, la segunda lista también se repetirá en bucle.El parámetro obligatorio
loopPlaylists
identifica el comportamiento de bucle.-
Si el valor del parámetro es
true
, el reproductor de video reproducirá listas de reproducción de forma continua. Después de reproducir el último video de una lista de reproducción, el reproductor de video vuelve al principio de la lista de reproducción y la reproduce nuevamente. -
Si el valor del parámetro es
false
, las reproducciones se terminan después de que el reproductor de video reproduce el último video de una lista de reproducción.
-
player.setShuffle(shufflePlaylist:Boolean):Void
-
Esta función indica si los videos de una lista de reproducción deben mezclarse para que se reproduzcan en un orden distinto del designado por el autor de la lista de reproducción. Si se mezcla una lista de reproducción después de comenzar a reproducirla, la lista se reordena mientras se reproduce el video actual. El siguiente video para reproducir se selecciona según el nuevo orden de la lista.
Esta configuración no se conservará si cargas o pones en fila una lista de reproducción diferente, lo que significa que si cargas una lista de reproducción, llamas a la función
setShuffle
y, luego, cargas una segunda lista de reproducción, esta no se mezclará.El parámetro obligatorio
shufflePlaylist
indica si YouTube debe mezclar la lista de reproducción.-
Si el valor del parámetro es
true
, YouTube mezcla el orden de la lista de reproducción. Si se indica a la función que mezcle una lista de reproducción ya mezclada, YouTube mezcla el orden nuevamente. -
Si el valor del parámetro es
false
, YouTube restablece el orden original de las listas de reproducción.
-
Estado de la reproducción
player.getVideoLoadedFraction():Float
- Muestra un número entre
0
y1
que especifica el porcentaje del video que el reproductor muestra en el búfer. Este método muestra un número más confiable que los métodosgetVideoBytesLoaded
ygetVideoBytesTotal
obsoletos.
player.getPlayerState():Number
- Muestra el estado del reproductor. Estos son los posibles valores:
-1
- unstarted- {
0
/} - ended (terminado) 1
- playing (en reproducción)2
- paused (en pausa)3
- buffering (almacenando en búfer)5
- video cued (video en fila)
player.getCurrentTime():Number
- Muestra el tiempo transcurrido en segundos desde que se inició la reproducción del video.
player.getVideoStartBytes():Number
- Obsoleto a partir del 31 de octubre de 2012. Muestra el número de bytes desde el cual que el archivo de video comenzó a cargar. (Ahora, este método siempre muestra un valor de
0
). Situación de ejemplo: El usuario busca un punto que aún no se cargó y el reproductor realiza una nueva solicitud para reproducir un segmento del video que aún no se cargó.
player.getVideoBytesLoaded():Number
-
Obsoleto a partir del 18 de julio de 2012. En su lugar, usa el método
getVideoLoadedFraction
para determinar el porcentaje de video almacenado en el búfer.
Este método muestra un valor entre0
y1000
que se aproxima a la cantidad de video cargado. Puedes calcular la fracción del video que se cargó dividiendo el valor degetVideoBytesLoaded
por el valor degetVideoBytesTotal
.
player.getVideoBytesTotal():Number
-
Obsoleto a partir del 18 de julio de 2012. En su lugar, usa el método
getVideoLoadedFraction
para determinar el porcentaje de video almacenado en el búfer.
Muestra el tamaño en bytes del video en reproducción o carga actualmente, o una aproximación del tamaño del video.
Este método siempre muestra un valor de1000
. Puedes calcular la fracción del video que se cargó dividiendo el valor degetVideoBytesLoaded
por el valor degetVideoBytesTotal
.
Recuperación de información de video
player.getDuration():Number
- Muestra la duración en segundos del video que se está reproduciendo actualmente. Ten en cuenta que
getDuration()
mostrará0
hasta que se carguen los metadatos del video, lo que generalmente ocurre justo después de que comienza a reproducirse el video.
Si el video que se está reproduciendo es un evento en vivo, la funcióngetDuration()
mostrará el tiempo transcurrido desde que comenzó la transmisión de video en vivo. Específicamente, esta es la cantidad de tiempo que el video se transmite sin ser reiniciado o interrumpido. Además, esta duración por lo general es más larga que el tiempo real del evento debido a que la transmisión puede comenzar antes de la hora de inicio del evento.
player.getVideoUrl():String
- Muestra la URL de YouTube.com del video actualmente cargado o en reproducción.
player.getVideoEmbedCode():String
- Muestra el código insertado del video cargado o en reproducción.
Recuperación de información de una lista de reproducción
player.getPlaylist():Array
- Esta función muestra un array de los IDs de video de la lista de reproducción tal como están ordenados actualmente. De forma predeterminada, esta función muestra ID de video en el orden designado por el propietario de la lista de reproducción. Sin embargo, si llamaste a la función
setShuffle
para desordenar el orden de la lista de reproducción, el valor que se muestra de la funcióngetPlaylist()
reflejará el orden aleatorio.
player.getPlaylistIndex():Number
- Esta función muestra el índice del video de la lista de reproducción que se está reproduciendo en ese momento.
-
Si no mezclaste la lista de reproducción, el valor mostrado identifica la posición en la que el creador de la lista de reproducción puso el video. El valor mostrado utiliza un índice basado en cero, por lo que un valor de
0
identifica el primer video de la lista de reproducción. -
Si mezclaste la lista de reproducción, el valor mostrado identifica el orden del video en la lista de reproducción mezclada.
-
Adición o eliminación de un objeto de escucha de eventos
player.addEventListener(event:String, listener:String):Void
- Agrega una función de objeto de escucha para el
event
especificado. En la sección Eventos a continuación se identifican los diferentes eventos que puede activar el reproductor. El detector es una cadena que indica la función que se ejecuta cuando se activa el evento indicado.
player.removeEventListener(event:String, listener:String):Void
- Quita una función de objeto de escucha para el
event
especificado.listener
es una cadena que identifica la función que no se ejecutará cuando se active el evento especificado.
Acceso y modificación de los nodos DOM
player.getIframe():Object
- Este método muestra el nodo del DOM para el
<iframe>
incorporado.
player.destroy():Void
- Quita el
<iframe>
que contiene el reproductor.
Eventos
La API ejecuta eventos para notificar a la aplicación de los cambios en el reproductor insertado. Como se señaló en la sección anterior, puedes suscribirte a eventos agregando un objeto de escucha de eventos durante la construcción del objeto YT.Player
, y también puedes usar la función addEventListener
.
La API transfiere un objeto de evento como el único argumento para cada una de esas funciones. El objeto de evento tiene las siguientes propiedades:
- El
target
del evento identifica el reproductor de video que corresponde al evento. - La
data
del evento especifica un valor relevante para el evento. Ten en cuenta que los eventosonReady
yonAutoplayBlocked
no especifican una propiedaddata
.
La siguiente lista define los eventos que activa la API:
onReady
- Este evento se activa cuando finaliza la carga de un reproductor y está listo para comenzar a recibir llamadas a la API. Tu aplicación debe implementar esta función si quieres ejecutar ciertas operaciones automáticamente, como reproducir el video o mostrar información sobre el video, tan pronto como el reproductor esté listo.
En el siguiente ejemplo, se muestra una función de ejemplo para controlar este evento. El objeto de evento que la API pasa a la función tiene una propiedadtarget
, que identifica el reproductor. La función recupera el código de incorporación del video cargado, comienza a reproducirlo y muestra el código de incorporación en el elemento de la página que tiene un 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
- Este evento se activa cada vez que cambia el estado del reproductor.
La propiedad
data
del objeto de evento que la API pasa a tu función de objeto de escucha de eventos especificará un número entero que corresponde al nuevo estado del reproductor. Los valores posibles son:-1
(sin iniciar)0
(ended, finalizado)1
(playing, en reproducción)2
(en pausa)3
(almacenando en búfer)5
(video cued, video en cola)
unstarted
(-1
). Cuando un video está en fila y listo para reproducirse, el reproductor transmite un eventovideo cued
(5
). Puedes especificar los valores en tu código o usar una de las siguientes variables separadas por nombre:YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED
onPlaybackQualityChange
- Este evento se activa cada vez que cambia la calidad de reproducción del video. Puede indicar un cambio en el entorno de reproducción del usuario. Consulta el Centro de ayuda de YouTube para obtener más información sobre los factores que afectan las condiciones de reproducción o que podrían causar que se active el evento.
El valor de la propiedaddata
del objeto del evento que la API pasa a la función de objeto de escucha de eventos es una cadena que identifica la nueva calidad de reproducción. Los valores posibles son:small
medium
large
hd720
hd1080
highres
onPlaybackRateChange
- Este evento se activa cada vez que cambia la velocidad de reproducción del video. Por ejemplo, si llamas a la función
setPlaybackRate(suggestedRate)
, este evento se activará si la velocidad de reproducción cambia. Tu aplicación debería responder al evento y no debería suponer que la velocidad de reproducción cambiará automáticamente cuando se llame a la funciónsetPlaybackRate(suggestedRate)
. Del mismo modo, tu código no debe suponer que la velocidad de reproducción de video solo cambiará como resultado de una llamada explícita asetPlaybackRate
.
El valor de la propiedaddata
del objeto del evento que la API pasa a la función de objeto de escucha de eventos es un número que identifica la nueva velocidad de reproducción. El métodogetAvailablePlaybackRates
muestra una lista de las velocidades de reproducción válidas del video en fila o en reproducción.
onError
- Este evento se activa si se produce un error en el reproductor.
La API pasará un objeto
event
a la función de objeto de escucha de eventos. La propiedaddata
del objeto especificará un número entero que identifica el tipo de error que se produjo. Los valores posibles son:2
: la solicitud contiene un valor de parámetro no válido. Por ejemplo, este error se produce cuando se especifica un ID de video que no contiene 11 caracteres, o que contiene caracteres no válidos, como signos de exclamación o asteriscos.5
: el contenido solicitado no se puede reproducir en un reproductor HTML5
, o se produjo otro error relacionado con el reproductor HTML5.100
: no se encontró el video solicitado. Esto sucede si se eliminó un video (por cualquier motivo) o si se marcó como privado.101
: el propietario del video solicitado no permite su reproducción en reproductores insertados.150
: este error y el error101
son idénticos. Es solo un error101
disfrazado.
onApiChange
- Este evento se activa para indicar que el reproductor cargó (o descargó) un módulo con métodos de API expuestos. Tu aplicación puede intentar escuchar este evento y sondear el reproductor para determinar las opciones expuestas del módulo cargado recientemente. A continuación, tu aplicación puede recuperar o actualizar la configuración actual de esas opciones.
El siguiente comando recupera un array de nombres de módulos para los que puedes configurar opciones del reproductor:
player.getOptions();
Actualmente, el único módulo para el que puedes establecer opciones es el módulocaptions
, que controla los subtítulos opcionales en el reproductor. Cuando se recibe un eventoonApiChange
, tu aplicación puede usar el siguiente comando para determinar qué opciones se pueden configurar para el módulocaptions
:
player.getOptions('captions');
Si sondeas el reproductor con este comando, puedes confirmar que se puede acceder a las opciones a las que deseas acceder. Los siguientes comandos recuperan y actualizan las opciones del módulo:
Retrieving an option: player.getOption(module, option); Setting an option player.setOption(module, option, value);
La siguiente tabla muestra las opciones que admite la API:
Módulo Opción Descripción captions fontSize Esta opción ajusta el tamaño de la fuente de los subtítulos que se muestran en el reproductor.
Los valores válidos son-1
,0
,1
,2
y3
. El tamaño predeterminado es0
y el tamaño mínimo es-1
. Si estableces esta opción en un número entero inferior a-1
, se mostrará el tamaño de subtítulos más pequeño, mientras que si estableces esta opción en un número entero superior a3
, se mostrará el tamaño más grande de subtítulos.captions reload Esta opción vuelve a cargar los datos de subtítulos del video en reproducción. Si recuperas el valor de la opción, el valor será null
. Establece el valor entrue
para volver a cargar los datos de subtítulos.
onAutoplayBlocked
- Este evento se activa cuando el navegador bloquea la reproducción automática o las funciones de reproducción de video con guion, que en su conjunto se denominan "reproducción automática". Esto incluye los intentos de reproducción con cualquiera de las siguientes API del reproductor:
- Parámetro
autoplay
- Función
loadPlaylist
- Función
loadVideoById
- Función
loadVideoByUrl
- Función
playVideo
Para obtener más información, consulta las políticas específicas del navegador (Safari / Webkit de Apple, Google Chrome, Mozilla Firefox) y la guía de reproducción automática de Mozilla. - Parámetro
Ejemplos
Creando objetos YT.Player
-
Ejemplo 1: Usa la API con un <iframe> existente
En este ejemplo, un elemento
<iframe>
en la página ya define el reproductor con el que se usará la API. Ten en cuenta que la URLsrc
del reproductor debe establecer el parámetroenablejsapi
en1
o el atributoenablejsapi
del elemento<iframe>
debe establecerse entrue
.Cuando el reproductor está listo, la función
onPlayerReady
cambia el color del borde del reproductor a naranja. Luego, la funciónonPlayerStateChange
cambia el color del borde alrededor del reproductor según el estado actual del reproductor. Por ejemplo, el color es verde cuando el reproductor está reproduciendo, rojo cuando se pausa, azul cuando se almacena en búfer, etc.En este ejemplo, se usa el siguiente 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>
-
Ejemplo 2: Reproducción con volumen alto
En este ejemplo se crea un reproductor de video de 1280 píxeles por 720 píxeles. El objeto de escucha de eventos del evento
onReady
llama a la funciónsetVolume
para ajustar el volumen al máximo.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(); }
-
Ejemplo 3: en este ejemplo, se configuran los parámetros para reproducir automáticamente el video cuando se carga y para ocultar los controles del reproductor de video. También agrega objetos de escucha para varios eventos que transmite la 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 } }); }
Cómo controlar los videos panorámicos de 360°
En este ejemplo, se usa el siguiente 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>
Historial de revisión
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 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
, andgetAvailableQualityLevels
functions are no longer supported. In particular, calls tosetPlaybackQuality
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 thesuggestedQuality
argument. Similarly, if you call those functions using object syntax, thesuggestedQuality
field is no longer supported. IfsuggestedQuality
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 toDeviceOrientationEvents
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 thecaptions
module and not thecc
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:
-
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.