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; por ejemplo, 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 invocará esta función cuando la página termine de descargar el JavaScript para la API del reproductor, lo que te permitirá 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 en la que la API de IFrame colocará 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>
con suid
para garantizar que la API coloque el objeto<iframe>
en la ubicación correcta. Específicamente, la API de IFrame reemplaza 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 contenido, que está detenido, que ya finalizó, etcétera. La función indica que cuando el estado del reproductor es1
(reproduciendo), este debe reproducir durante seis segundos y luego llamar a 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
. A partir de 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 inserta la etiqueta<iframe>
que contiene el reproductor.La API de IFrame reemplaza 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 reemplazará 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): Indica 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): Indica 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 usar 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) que la API llamará cuando se produzcan. En el ejemplo, el constructor indica que se ejecutará la funciónonPlayerReady
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á con un elemento <iframe>
, puedes 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 construyas el objeto YT.Player
, no necesitarás 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 host como valor del parámetro. Si bien origin
es opcional, incluye protección contra la inserción de JavaScript malicioso de terceros en tu página y la usurpación del control de tu reproductor de YouTube.
En la sección Ejemplos, también se muestran otros ejemplos de cómo construir 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. Para obtener la referencia, crea un objeto YT.Player
como se explica en las secciones Cómo comenzar y Cómo cargar un reproductor de video de este documento.
Funciones
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 del objeto
loadVideoById({'videoId': 'bHQqvYy5KYo', 'startSeconds': 5, 'endSeconds': 60});
Funciones de fila de videos
cueVideoById
-
-
Sintaxis de argumentos
player.cueVideoById(videoId:String, startSeconds:Number):Void
-
Sintaxis del objeto
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 llama a
playVideo()
oseekTo()
.- El parámetro obligatorio
videoId
especifica el ID de video de YouTube del video que se 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 de punto flotante o entero y especifica el tiempo desde el que debe comenzar a reproducirse el video cuando se llama aplayVideo()
. Si especificas un valorstartSeconds
y, luego, llamas aseekTo()
, el reproductor reproducirá desde el momento especificado en la llamada aseekTo()
. 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 tendrá efecto.
-
loadVideoById
-
-
Sintaxis de argumentos
player.loadVideoById(videoId:String, startSeconds:Number):Void
-
Sintaxis del objeto
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 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 del objeto
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 llama 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 de punto flotante o entero y especifica el tiempo desde el que debe comenzar a reproducirse el video cuando se llama aplayVideo()
. Si especificasstartSeconds
y, luego, llamas aseekTo()
, el reproductor reproducirá desde el momento especificado en la llamada aseekTo()
. 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 tendrá efecto.
-
loadVideoByUrl
-
-
Sintaxis de argumentos
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
-
Sintaxis del objeto
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 debe comenzar la reproducción del video. Si se especificastartSeconds
(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 playlist. Si usas la sintaxis de objetos para invocar estas funciones, también puedes poner en fila (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 playlist especificada. Cuando la playlist está en cola y lista para reproducirse, el reproductor transmitirá un eventovideo cued
(5
).-
El parámetro obligatorio
playlist
especifica un array de IDs de videos 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 playlist 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 playlist. -
El parámetro opcional
startSeconds
acepta un número decimal o entero e indica el momento a partir del cual debe empezar a reproducirse el primer video de la playlist cuando se invoca la funciónplayVideo()
. Si especificas un valorstartSeconds
y, luego, llamas aseekTo()
, el reproductor reproducirá desde el momento especificado en la llamada aseekTo()
. Si se pone en fila una playlist y luego se invoca la funciónplayVideoAt()
, el reproductor comenzará a reproducir el principio del video especificado.
-
-
Sintaxis del objeto
player.cuePlaylist({listType:String, list:String, index:Number, startSeconds:Number}):Void
Pone en fila la lista de videos especificada. La lista puede ser una playlist o un 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 dejará de ser compatible a partir del15 de noviembre de 2020 .Cuando la lista esté en fila y lista para reproducirse, el reproductor transmitirá 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 , se dejará de admitir un valor obsoleto,search
. El valor predeterminado esplaylist
. -
La propiedad obligatoria
list
contiene una clave que identifica la lista de videos específicos que YouTube debe mostrar.- Si el valor de la propiedad
listType
esplaylist
, la propiedadlist
especifica el ID de la playlist o un array de IDs de video. En la API de datos de YouTube, la propiedadid
del recursoplaylist
identifica el ID de una playlist, 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
, entonces 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 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 llamada aseekTo()
. Si se pone en fila una lista y luego se invoca la funciónplayVideoAt()
, el reproductor comenzará a reproducir el principio del video especificado.
-
-
loadPlaylist
-
-
Sintaxis de argumentos
player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
Esta función carga la playlist especificada y la reproduce.-
El parámetro obligatorio
playlist
especifica un array de IDs de videos 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 playlist 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 playlist. -
El parámetro opcional
startSeconds
acepta un número decimal o entero e indica el momento a partir del cual debe empezar a reproducirse el primer video de la playlist.
-
-
Sintaxis del objeto
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 playlist o un feed de videos subidos de un usuario. La función para cargar una lista de resultados de la búsqueda está obsoleta y dejará de ser compatible 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 , se dejará de admitir un valor obsoleto,search
. El valor predeterminado esplaylist
. -
La propiedad obligatoria
list
contiene una clave que identifica la lista de videos específicos que YouTube debe mostrar.- Si el valor de la propiedad
listType
esplaylist
, la propiedadlist
especifica el ID de la playlist o un array de IDs de video. En la API de datos de YouTube, la propiedadid
del recursoplaylist
especifica el ID de una playlist, mientras que 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
, entonces 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 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 decimal o entero e indica el momento a partir del cual debería comenzar la reproducción del 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 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 considera en 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 ejecuta esta función será
paused
(2
), a menos que el reproductor esté 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 quieres 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 llamar primero astopVideo
.
Importante: A diferencia de la funciónpauseVideo
, que deja al reproductor en el estadopaused
(2
), la funciónstopVideo
puede colocar el reproductor en cualquier estado de no reproducción, comoended
(0
),paused
(2
),video cued
(5
) ounstarted
(-1
).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
- Busca un momento específico del video. Si el reproductor está en pausa cuando se invoca la función, se mantendrá en pausa. Si la función se invoca desde otro estado (
playing
,video cued
, etc.), el reproductor reproducirá el video.-
El parámetro
seconds
identifica la hora a la 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 solicitud nueva al servidor si el parámetroseconds
especifica un momento que no pertenezca a los datos de video almacenados en búfer actualmente.Te recomendamos establecer este parámetro en
false
mientras el usuario arrastra el mouse a lo largo de 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 videos en 360° tiene compatibilidad limitada en dispositivos móviles. En los dispositivos no compatibles, los videos panorámicos en 360° aparecen distorsionados y no hay ninguna forma admitida para cambiar la perspectiva de visualización; por ejemplo, a través de la API, el uso de sensores de orientación o la respuesta a acciones de tocar o 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 en 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 muestra un objeto vacío.
- En los dispositivos móviles compatibles, si la propiedad
enableOrientationSensor
se establece entrue
, esta función muestra un objeto en el que la propiedadfov
contiene el valor correcto y las otras propiedades se establecen en0
.
Propiedades yaw
Un número en el rango [0, 360) que representa el ángulo horizontal de la vista en grados, que refleja hasta qué punto el usuario gira la vista para mirar más a la izquierda o derecha. La posición neutral, orientada al centro del video en su proyección equirrectangular, representa 0°, y este valor aumenta a medida que el usuario gire hacia la izquierda. pitch
Es un número en el rango [-90, 90] que representa el ángulo vertical de la vista en grados, que refleja el grado en que el usuario ajusta la vista para mirar hacia arriba o abajo. La posición neutra, orientada al centro del video en su proyección equirrectangular, representa 0°, y este valor aumenta a medida que el usuario mira hacia arriba. roll
Un número en el rango [-180, 180] que representa el ángulo de rotación de la vista en grados en el sentido de las manecillas del reloj o en sentido contrario. La posición neutral, en la que el eje horizontal en la proyección equirrectangular es paralelo al eje horizontal de la vista, representa 0°. El valor aumenta a medida que la vista rota en el sentido de las manecillas del reloj y disminuye a medida que rota en sentido contrario.
Ten en cuenta que el reproductor incorporado no presenta una interfaz de usuario para ajustar el desplazamiento de la vista. El lanzamiento se puede ajustar de cualquiera de estas formas excluyentes:- Usa el sensor de orientación en un navegador para dispositivos móviles para proporcionar un giro de 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 lanzamiento 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 lo medido 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 usando la API o con la rueda del mouse cuando el video está en modo de pantalla completa.
player.setSphericalProperties(properties:Object):Void
- Establece la orientación de video para la reproducción de un video en 360°. (Si el video actual no es esférico, el método es no-op más allá de la entrada).
La vista del reproductor responde a las llamadas a este método y se actualiza para reflejar los valores de cualquier propiedad conocida del 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 ignora.
- Como se mencionó 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 solo establece la propiedad
fov
y no afecta las propiedadesyaw
,pitch
niroll
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
Consulta la definición más arriba. pitch
Consulta la definición más arriba. roll
Consulta la definición más arriba. fov
Consulta la definición más arriba. enableOrientationSensor
Nota: Esta propiedad afecta la experiencia de visualización de 360° solo en dispositivos compatibles.Es 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
, un reproductor incorporado solo depende del movimiento del dispositivo para ajustar las propiedadesyaw
,pitch
yroll
para las reproducciones de video en 360°. Sin embargo, la propiedadfov
aún se puede modificar mediante la API, que es, de hecho, 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 en 360°, y las propiedadesyaw
,pitch
,roll
yfov
deben configurarse a través de 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 playlist.
-
Si se invoca
player.nextVideo()
mientras se reproduce el último video de la playlist y la playlist está configurada para reproducir continuamente (loop
), el reproductor cargará y reproducirá el primer video de la lista. -
Si se invoca
player.nextVideo()
mientras se reproduce el último video de la playlist y la playlist no está configurada para reproducir continuamente, la reproducción finalizará.
-
player.previousVideo():Void
- Esta función carga y reproduce el video anterior de la playlist.
-
Si se invoca
player.previousVideo()
mientras se reproduce el primer video de la playlist y la lista 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 playlist y esta no está configurada para reproducir continuamente, el reproductor reinicia el primer video de la playlist desde el principio.
-
player.playVideoAt(index:Number):Void
- Esta función carga y reproduce el video indicado en la playlist.
-
El parámetro obligatorio
index
especifica el índice del video que se desea reproducir en la playlist. El parámetro utiliza un índice basado en cero, por lo que el valor0
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 el reproductor.
player.unMute():Void
- Activa el sonido del reproductor.
player.isMuted():Boolean
- Devuelve
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()
devolverá 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. La velocidad de reproducción predeterminada es
1
, lo que indica que el video se está reproduciendo 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 define 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á en vigencia cuando se llame a la función
playVideo
o cuando el usuario inicie la reproducción directamente a través de los controles del reproductor. Además, si invocas funciones para poner en fila o cargar videos o playlists (cueVideoById
,loadVideoById
, etc.), se restablecerá la velocidad de reproducción a1
.
Llamar a esta función no garantiza que la velocidad de reproducción cambie. Sin embargo, si la velocidad de reproducción cambia, se activará el eventoonPlaybackRateChange
y tu código debería responder al evento en lugar del hecho de haber llamado a la funciónsetPlaybackRate
.
El métodogetAvailablePlaybackRates
devolverá las velocidades de reproducción posibles para el video que se está reproduciendo. Sin embargo, si estableces el parámetrosuggestedRate
en un valor entero o flotante no admitido, el reproductor redondeará ese valor hacia abajo hasta el valor admitido más cercano a1
.
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 menor a mayor velocidad de reproducción. Incluso si el reproductor no admite velocidades de reproducción variables, 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 mantiene incluso si cargas o pones en fila una playlist diferente, lo que significa que si cargas una playlist, llamas a la función
setLoop
con un valor detrue
y luego cargas una segunda playlist, la segunda playlist también se repetirá indefinidamente.El parámetro
loopPlaylists
obligatorio identifica el comportamiento de bucle.-
Si el valor del parámetro es
true
, el reproductor de video reproduce playlists 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 finalizarán después de que el reproductor de video reproduzca el último video de una playlist.
-
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 mantiene si se carga o se pone en fila una playlist diferente, lo que significa que si se carga una playlist, se invoca la función
setShuffle
y luego se carga una segunda playlist, esta no se mezclará.El parámetro obligatorio
shufflePlaylist
indica si YouTube debe mezclar la playlist.-
Si el valor del parámetro es
true
, YouTube mezcla el orden de la playlist. 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 de reproducción original.
-
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 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. Los valores posibles son los siguientes:
-1
- sin comenzar- {
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 solicitud nueva 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 del video que se almacenó en búfer.
Este método muestra un valor entre0
y1000
que se aproxima a la cantidad de video cargado. Para calcular la fracción del video que se cargó, puedes dividir 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 del video que se almacenó en búfer.
Muestra el tamaño en bytes del video actualmente cargado o en reproducción o una aproximación del tamaño del video.
Este método siempre muestra un valor de1000
. Para calcular la fracción del video que se cargó, puedes dividir 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 el video comienza a reproducirse.
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 cargado o en reproducción actualmente.
player.getVideoEmbedCode():String
- Muestra el código de incorporación del video actualmente 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 playlist según su orden actual. 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 mezclar el orden de la playlist, 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 playlist que se está reproduciendo actualmente.
-
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 indicó en la sección anterior, puedes suscribirte a eventos agregando un objeto de escucha de eventos cuando construyas el 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. - El
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 invocaciones a la API. Tu aplicación debería implementar esta función si quieres ejecutar automáticamente ciertas operaciones, como reproducir el video o mostrar información sobre este, 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 inserción del video cargado actualmente, comienza a reproducirlo y muestra el código de inserción en el elemento de 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 corresponda 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. Esto 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 pueden provocar que el evento se active.
El valor de la propiedaddata
del objeto de 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 realmente 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 de 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 cola o en reproducción actual.
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 configurar opciones escaptions
, que controla los subtítulos 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 las opciones a las que deseas acceder sean accesibles. 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);
En la siguiente tabla, se muestran las opciones que admite la API:
Módulo Opción Descripción captions fontSize Con esta opción, se 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ás pequeño es-1
. Establecer esta opción en un número entero inferior a-1
permitirá mostrar el tamaño más pequeño de subtítulos, mientras que establecerla en un número entero superior a3
permitirá 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. El valor será null
si recuperas el valor de la opción. Establece el valor entrue
para volver a cargar los datos de subtítulos.
onAutoplayBlocked
- Este evento se activa cada vez que el navegador bloquea la reproducción automática o las funciones de reproducción de video con secuencia de comandos, que en conjunto se denominan "reproducción automática". Esto incluye los intentos de reproducción con cualquiera de las siguientes APIs 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 de cada navegador (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) y la guía de reproducción automática de Mozilla. - Parámetro
Ejemplos
Creando YT.Player
de objetos
-
Ejemplo 1: Usa la API con un <iframe> existente
En este ejemplo, un elemento
<iframe>
de 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
.La función
onPlayerReady
cambia el color del borde alrededor del reproductor a naranja cuando este está listo. 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 está en 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 valor más alto.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 de eventos 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 } }); }
Control de videos en 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>
Integración de la API de Media Integrity de Android WebView
YouTube amplió la API de Media Integrity de Android WebView para habilitar reproductores multimedia incorporados, incluidas las incorporaciones del reproductor de YouTube en aplicaciones para Android, para verificar la autenticidad de incorporación. Con este cambio, las apps que se incorporan envían automáticamente un ID de la app certificado a YouTube. Los datos que se recopilan con el uso de esta API son los metadatos de la app (el nombre del paquete, el número de versión y el certificado de firma) y un token de certificación del dispositivo generado por los Servicios de Google Play.
Los datos se usan para verificar la integridad de la aplicación y el dispositivo. Se encripta, no se comparte con terceros y se borra después de un período de retención fijo. Los desarrolladores de apps pueden configurar la identidad de sus apps en la API de Media Integrity de WebView. La configuración admite una opción de inhabilitación.
Historial de revisión
June 24, 2024
The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.
November 20, 2023
The new onAutoplayBlocked
event API is now available.
This event notifies your application if the browser blocks autoplay or scripted playback.
Verification of autoplay success or failure is an
established paradigm
for HTMLMediaElements, and the onAutoplayBlocked
event now provides similar
functionality for the IFrame Player API.
April 27, 2021
The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars
object to customize the player.
October 13, 2020
Note: This is a deprecation announcement for the embedded player
functionality that lets you configure the player to load search results. This announcement affects
the IFrame Player API's queueing functions for lists,
cuePlaylist
and
loadPlaylist
.
This change will become effective on or after 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.