YouTube Player API Reference for iframe Embeds

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 puede enviar la API y explica cómo escribir objetos de escucha de eventos para responder a ellos. 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 admitir la función postMessage de HTML5. La mayoría de los navegadores modernos son compatibles con 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 llamará a esta función cuando la página termine de descargar el código JavaScript para la API del reproductor, lo que te permitirá usar 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.

Introducción

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:

  1. La etiqueta <div> de esta sección identifica la ubicación en la página donde 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> por su id para garantizar que la API coloque el <iframe> en la ubicación correcta. Específicamente, la API de IFrame reemplazará la etiqueta <div> por 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.

  2. 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).

  3. 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 incorporas, y la función luego construye el objeto del reproductor de video.

  4. La función onPlayerReady se ejecutará cuando se active el evento onReady. En este ejemplo, la función indica que la reproducción debe comenzar cuando el reproductor de video está listo.

  5. La API llamará a la función onPlayerStateChange cuando cambie el estado del reproductor, lo que puede indicar que está reproduciendo, pausado, finalizado, etcétera. La función indica que, cuando el estado del reproductor es 1 (reproducción), este debe reproducirse durante seis segundos y, luego, llamar a la función stopVideo para detener el video.

Cómo cargar un reproductor de video

Después de que se cargue el código JavaScript de la API, esta llamará a la función onYouTubeIframeAPIReady, en cuyo momento podrás crear 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:

  1. El primer parámetro especifica el elemento DOM o el id del elemento HTML en el que la API insertará la etiqueta <iframe> que contiene el reproductor.

    La API de IFrame reemplazará el elemento especificado por 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 elemento inline-block.

  2. 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 es 640.
    • height (número): Es la altura del reproductor de video. El valor predeterminado es 390.
    • videoId (cadena): Es 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 personalizarlo.
    • events (objeto): Las propiedades del objeto identifican los eventos que activa la API y las funciones (objetos de escucha de eventos) a las que llamará la API cuando ocurran esos eventos. En el ejemplo, el constructor indica que la función onPlayerReady se ejecutará cuando se active el evento onReady y que la función onPlayerStateChange se ejecutará cuando se active el evento onStateChange.

Como se mencionó en la sección Introducción, 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>, puedes crear la etiqueta <iframe> por tu cuenta. 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>, ni los parámetros videoId y del reproductor, que se especifican en la URL src. Como medida de seguridad adicional, también debes incluir el parámetro origin en la URL, especificando el esquema de URL (http:// o https://) y el dominio completo de tu página host como el valor del parámetro. Si bien origin es opcional, incluirlo te protege contra la inserción de JavaScript malicioso de terceros en tu página y el control de piratería de tu reproductor de YouTube.

Para ver otros ejemplos sobre la construcción de objetos de reproductores de video, consulta Ejemplos.

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 Introducción 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 llamar a estas funciones, también puedes poner en cola o cargar una lista de los videos subidos por 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 no es compatible con la sintaxis de argumentos.

  • 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 archivo FLV hasta que se llama a playVideo() o seekTo().

  • El parámetro videoId obligatorio especifica el ID de video de YouTube que se reproducirá. En la API de YouTube Data, la propiedad id de un recurso video especifica el ID.
  • El parámetro opcional startSeconds acepta un número de punto flotante o entero y especifica el momento a partir del cual debe comenzar a reproducirse el video cuando se llama a playVideo(). Si especificas un valor startSeconds y, luego, llamas a seekTo(), el reproductor se reproduce desde la hora especificada en la llamada a seekTo(). Cuando el video esté listo para reproducirse, el reproductor transmitirá un evento video cued (5).
  • El parámetro opcional endSeconds, que solo se admite en la sintaxis de objetos, acepta un número de punto flotante o entero y especifica la hora en la que se debe detener la reproducción del video cuando se llama a playVideo(). Si especificas un valor endSeconds y, luego, llamas a seekTo(), el valor endSeconds 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 videoId obligatorio especifica el ID de video de YouTube del video que se reproducirá. En la API de YouTube Data, la propiedad id de un recurso video especifica el ID.
  • El parámetro opcional startSeconds acepta un número de punto flotante 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 de punto flotante 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 archivo FLV hasta que se llama a playVideo() o seekTo().

  • El parámetro mediaContentUrl obligatorio especifica una URL del reproductor de YouTube completamente calificada en el formato http://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 momento a partir del cual debe comenzar a reproducirse el video cuando se llama a playVideo(). Si especificas startSeconds y, luego, llamas a seekTo(), el jugador reproduce desde la hora especificada en la llamada a seekTo(). Cuando el video esté listo para reproducirse, el reproductor transmitirá un evento video cued (5).
  • El parámetro opcional endSeconds, que solo se admite en la sintaxis de objetos, acepta un número de punto flotante o entero y especifica la hora en la que se debe detener la reproducción del video cuando se llama a playVideo(). Si especificas un valor endSeconds y, luego, llamas a seekTo(), el valor endSeconds 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 mediaContentUrl obligatorio especifica una URL del reproductor de YouTube completamente calificada en el formato http://www.youtube.com/v/VIDEO_ID?version=3.
  • El parámetro opcional startSeconds acepta un número de punto flotante o entero y especifica la hora a partir de la cual debe comenzar a reproducirse el video. Si se especifica startSeconds (el número puede ser un número de punto flotante), el video comenzará desde el fotograma clave más cercano a la hora especificada.
  • El parámetro opcional endSeconds, que solo se admite en la sintaxis de objetos, acepta un número de punto flotante o entero y especifica la hora en la que se debe detener la reproducción del video.

Funciones de fila de listas

Las funciones cuePlaylist y loadPlaylist te permiten cargar y reproducir una playlist. Si usas sintaxis de objetos para llamar a estas funciones, también puedes poner en cola (o cargar) una lista de los videos subidos por 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
     Agrega la playlist especificada a la fila. Cuando la playlist esté en cola y lista para reproducirse, el reproductor transmitirá un evento video cued (5).

    • El parámetro playlist obligatorio especifica un array de IDs de videos de YouTube. En la API de YouTube Data, la propiedad id del recurso video identifica el ID de ese video.

    • El parámetro opcional index especifica el índice del primer video de la playlist que se reproducirá. El parámetro usa un índice basado en cero, y el valor predeterminado del parámetro es 0, 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 entero o de punto flotante y especifica la hora a partir de la cual debe comenzar a reproducirse el primer video de la playlist cuando se llame a la función playVideo(). Si especificas un valor startSeconds y, luego, llamas a seekTo(), el reproductor se reproduce desde la hora especificada en la llamada a seekTo(). Si agregas una playlist y, luego, llamas a la función playVideoAt(), el reproductor comenzará a reproducirse al principio del video especificado.

  • Sintaxis de objetos

    player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
     Agrega a una fila la lista de videos especificada. La lista puede ser una playlist o el feed de videos subidos de un usuario. La capacidad de poner en cola una lista de resultados de la búsqueda dejó de estar disponible y dejará de ser compatible a partir del 15 de noviembre de 2020.

    Cuando la lista esté en cola y lista para reproducirse, el reproductor transmitirá un evento video cued (5).

loadPlaylist

Controles de reproducción y configuración del reproductor

Reproducción de un video

player.playVideo():Void
Reproduce el video que se está reproduciendo o cargando. El estado final del reproductor después de que se ejecute esta función será playing (1).

Nota: Una reproducción solo se registra en el recuento oficial de vistas 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 jugador después de que se ejecute esta función será paused (2), a menos que el jugador esté en el estado ended (0) cuando se llame a la función, en cuyo caso el estado del jugador 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 reproduce el reproductor, puedes llamar a una de las funciones de cola sin llamar primero a stopVideo.

Importante: A diferencia de la función pauseVideo, que deja al reproductor en el estado paused (2), la función stopVideo podría colocarlo en cualquier estado que no sea de reproducción, incluidos ended (0), paused (2), video cued (5) o unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Salta 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 llama a la función desde otro estado (playing, video cued, etcétera), el reproductor reproducirá el video.

  • El parámetro seconds identifica la hora a la que debe avanzar el jugador.

    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ámetro seconds especifica una hora fuera de los datos de video almacenados actualmente en el búfer.

    Te recomendamos que configures este parámetro en false mientras el usuario arrastra el mouse por una barra de progreso de video y, luego, en true 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 en 360° aparecen distorsionados y no hay ninguna forma compatible de cambiar la perspectiva de visualización, ni siquiera a través de la API, con sensores de orientación o respondiendo a acciones de toque o arrastre 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 de 360° o si se llama a la función desde un dispositivo no compatible, la función muestra un objeto vacío.
  • En dispositivos móviles compatibles, si la propiedad enableOrientationSensor se establece en true, esta función muestra un objeto en el que la propiedad fov contiene el valor correcto y las otras propiedades se establecen en 0.
El objeto contiene las siguientes propiedades:
Propiedades
yaw Es un número en el rango [0, 360) que representa el ángulo horizontal de la vista en grados, lo que refleja la medida en que el usuario gira la vista para que apunte más a la izquierda o a la derecha. La posición neutral, que mira hacia el centro del video en su proyección equirectangular, representa 0°, y este valor aumenta a medida que el usuario 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 el grado en que el usuario ajusta la vista para mirar hacia arriba o hacia abajo. La posición neutral, que mira hacia el centro del video en su proyección equirectangular, 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 de la vista en grados, ya sea en el sentido de las manecillas del reloj o en sentido contrario. La posición neutral, con el eje horizontal en la proyección equirectangular 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 la vista rota en sentido contrario a las manecillas del reloj.

Ten en cuenta que el reproductor incorporado no presenta una interfaz de usuario para ajustar el giro de la vista. El balance puede ajustarse de las siguientes maneras mutuamente excluyentes:
  1. Usa el sensor de orientación en un navegador para dispositivos móviles para proporcionar un giro a la vista. Si el sensor de orientación está habilitado, la función getSphericalProperties siempre muestra 0 como el valor de la propiedad roll.
  2. Si el sensor de orientación está inhabilitado, establece el balanceo en un valor distinto de cero con esta API.
fov Es un número en el rango [30, 120] que representa el campo de visión de la vista en grados, medido a lo largo del borde más largo de la ventana de visualización. El borde más corto se ajusta automáticamente para ser proporcional a la relación de aspecto de la vista.

El valor predeterminado es de 100 grados. Reducir el valor es como acercar el contenido de video, y aumentarlo es como alejarlo. Este valor se puede ajustar con 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 del video para la reproducción de un video en 360°. (Si el video actual no es esférico, el método no realiza ninguna acción, independientemente de la entrada).

La vista del reproductor responde a las llamadas a este método actualizando para reflejar los valores de las propiedades conocidas en el objeto properties. La vista conserva los valores de cualquier otra propiedad conocida que no se incluya en ese objeto.

Además:
  • Si el objeto contiene propiedades desconocidas o inesperadas, el reproductor las ignora.
  • Como se indicó 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 propiedades yaw, pitch y roll para la reproducción de videos panorámicos de 360°. Consulta la propiedad enableOrientationSensor a continuación para obtener más detalles.
El objeto properties que se pasa a la función contiene las siguientes propiedades:
Propiedades
yaw Consulta la definición anterior.
pitch Consulta la definición anterior.
roll Consulta la definición anterior.
fov Consulta la definición anterior.
enableOrientationSensor Nota: Esta propiedad afecta solo la experiencia de visualización de 360° en dispositivos compatibles.Un valor booleano que indica si la incorporación de IFrame debe responder a eventos que indican 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 es true.

Dispositivos móviles compatibles
  • Cuando el valor es true, un reproductor incorporado se basa solo en el movimiento del dispositivo para ajustar las propiedades yaw, pitch y roll para la reproducción de videos en 360°. Sin embargo, la propiedad fov se puede cambiar a través de la API, que, de hecho, es la única forma de cambiar la propiedad fov 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 propiedades yaw, pitch, roll y fov deben configurarse a través de la API.

Dispositivos móviles no compatibles
El valor de la propiedad enableOrientationSensor 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 llama a player.nextVideo() mientras se reproduce el último video de la playlist y esta está configurada para reproducirse de forma continua (loop), el reproductor cargará y reproducirá el primer video de la lista.

  • Si se llama a player.nextVideo() mientras se mira el último video de la playlist y esta no está configurada para reproducirse de forma continua, la reproducción finalizará.

player.previousVideo():Void
Esta función carga y reproduce el video anterior de la playlist.

  • Si se llama a player.previousVideo() mientras se reproduce el primer video de la playlist y esta está configurada para reproducirse de forma continua (loop), el reproductor cargará y reproducirá el último video de la lista.

  • Si se llama a player.previousVideo() mientras se mira el primer video de la playlist y esta no está configurada para reproducirse de forma continua, el reproductor reiniciará el primer video de la playlist desde el principio.

player.playVideoAt(index:Number):Void
Esta función carga y reproduce el video especificado en la playlist.

  • El parámetro index obligatorio especifica el índice del video que quieres reproducir en la playlist. El parámetro usa un índice basado en cero, por lo que un valor de 0 identifica el primer video de la lista. Si reprodujos la playlist de forma aleatoria, esta función reproducirá el video en la posición especificada de la playlist aleatoria.

Modificación del volumen del reproductor

player.mute():Void
Silencia el reproductor.
player.unMute():Void
Activa el sonido del reproductor.
player.isMuted():Boolean
Muestra true si el reproductor está silenciado, false si no lo está.
player.setVolume(volume:Number):Void
Establece el volumen. Acepta un número entero entre 0 y 100.
player.getVolume():Number
Devuelve el volumen actual del reproductor, un número entero entre 0 y 100. Ten en cuenta que getVolume() 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. La velocidad de reproducción predeterminada es 1, lo que indica que el video se reproduce a velocidad normal. Las tasas de reproducción pueden incluir valores como 0.25, 0.5, 1, 1.5 y 2.
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 estableces la velocidad de reproducción de un video con indicaciones, esa velocidad seguirá vigente 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, llamar a funciones para activar o cargar videos o playlists (cueVideoById, loadVideoById, etc.) restablecerá la velocidad de reproducción en 1.

Llamar a esta función no garantiza que la velocidad de reproducción cambie. Sin embargo, si cambia la velocidad de reproducción, se activará el evento onPlaybackRateChange y tu código debería responder al evento en lugar de al hecho de que llamó a la función setPlaybackRate.

El método getAvailablePlaybackRates mostrará las velocidades de reproducción posibles para el video que se está reproduciendo. Sin embargo, si estableces el parámetro suggestedRate en un valor de número entero o de punto flotante no admitido, el reproductor redondeará ese valor hacia abajo al valor admitido más cercano en la dirección de 1.
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, que indica que el video se reproduce a velocidad normal.

La función muestra un array de números ordenados de la velocidad de reproducción más lenta a la más rápida. 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.

Este parámetro de configuración persistirá incluso si cargas o pones en cola una playlist diferente, lo que significa que, si cargas una playlist, llamas a la función setLoop con un valor de true y, luego, cargas una segunda playlist, esta también se reproducirá en bucle.

El parámetro loopPlaylists obligatorio identifica el comportamiento de bucle.

  • Si el valor del parámetro es true, el reproductor de video reproducirá 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.

Este parámetro de configuración no se mantendrá si cargas o pones en cola una playlist diferente, lo que significa que, si cargas una playlist, llamas a la función setShuffle y, luego, cargas una segunda playlist, esta no se reproducirá de forma aleatoria.

El parámetro shufflePlaylist obligatorio indica si YouTube debe reproducir la playlist de forma aleatoria.

  • Si el valor del parámetro es true, YouTube reproducirá la playlist de forma aleatoria. 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 cambiará el orden de la playlist al original.

Estado de la reproducción

player.getVideoLoadedFraction():Float
Devuelve un número entre 0 y 1 que especifica el porcentaje del video que el reproductor muestra como almacenado en búfer. Este método muestra un número más confiable que los métodos getVideoBytesLoaded y getVideoBytesTotal, que ahora están obsoletos.
player.getPlayerState():Number
Devuelve el estado del reproductor. Los valores posibles son los siguientes:
  • -1: No se inició.
  • {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
Devuelve el tiempo transcurrido en segundos desde que comenzó a reproducirse el video.
player.getVideoStartBytes():Number
Quedó 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. (Este método ahora siempre muestra un valor de 0). Ejemplo: el usuario avanza hasta 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 del video que se almacenó en búfer.

Este método muestra un valor entre 0 y 1000 que aproxima la cantidad de video que se cargó. Para calcular la fracción del video que se cargó, divide el valor de getVideoBytesLoaded por el valor de getVideoBytesTotal.
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 que se está cargando o reproduciendo actualmente, o una aproximación del tamaño del video.

Este método siempre muestra un valor de 1000. Para calcular la fracción del video que se cargó, divide el valor de getVideoBytesLoaded por el valor de getVideoBytesTotal.

Recuperación de información de video

player.getDuration():Number
Devuelve 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 suele ocurrir justo después de que comienza a reproducirse.

Si el video que se está reproduciendo es un evento en vivo, la función getDuration() 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
Devuelve la URL de YouTube.com del video que se está cargando o reproduciendo.
player.getVideoEmbedCode():String
Devuelve el código de incorporación del video que se está cargando o reproduciendo actualmente.

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 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 reproducir la playlist de forma aleatoria, el valor que se muestra de la función getPlaylist() 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, que aparece a continuación, se identifican los diferentes eventos que puede activar el jugador. 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 ya 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 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 cuando construyes el objeto YT.Player. 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 eventos onReady y onAutoplayBlocked no especifican una propiedad data.

La siguiente lista define los eventos que activa la API:

onReady
Este evento se activa cada vez que un jugador termina de cargarse y está listo para comenzar a recibir llamadas a la API. Tu aplicación debe implementar esta función si deseas ejecutar automáticamente ciertas operaciones, como reproducir el video o mostrar información sobre él, en cuanto el reproductor esté listo.

En el siguiente ejemplo, se muestra una función de muestra para controlar este evento. El objeto de evento que la API pasa a la función tiene una propiedad target, que identifica al jugador. La función recupera el código de incorporación del video cargado actualmente, comienza a reproducirlo y muestra el código de incorporación en el elemento de página que tiene un valor id de embed-code. 
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
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)

Cuando el reproductor cargue un video por primera vez, transmitirá un evento unstarted (-1). Cuando un video esté listo para reproducirse, el reproductor transmitirá un evento video 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 pueden activar el evento.

El valor de la propiedad data del objeto del evento que la API pasa a la función del objeto de escucha de eventos será 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 debe responder al evento y no debe suponer que la velocidad de reproducción cambiará automáticamente cuando se llame a la función setPlaybackRate(suggestedRate). Del mismo modo, tu código no debe dar por sentado que la velocidad de reproducción de video solo cambiará como resultado de una llamada explícita a setPlaybackRate.

El valor de la propiedad data del objeto de evento que la API pasa a la función del objeto de escucha de eventos será un número que identifica la nueva velocidad de reproducción. El método getAvailablePlaybackRates muestra una lista de las velocidades de reproducción válidas para el video que se está reproduciendo o en la cola.
onError
Este evento se activa si se produce un error en el reproductor. La API pasará un objeto event a la función del objeto de escucha de eventos. La propiedad data de ese 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 error 101 son idénticos. Es solo un error 101 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 establecer opciones de reproductor:
player.getOptions();
 Actualmente, el único módulo para el que puedes configurar opciones es el módulo captions, que controla los subtítulos en el reproductor. Cuando recibe un evento onApiChange, tu aplicación puede usar el siguiente comando para determinar qué opciones se pueden configurar para el módulo captions:
player.getOptions('captions');
 Si sondeas al 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);
 En la siguiente tabla, se enumeran las opciones que admite la API:

Módulo Opción Descripción
subtítulos 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 y 3. El tamaño predeterminado es 0 y el más pequeño es -1. Si estableces esta opción en un número entero inferior a -1, se mostrará el tamaño de subtítulo más pequeño, mientras que si estableces esta opción en un número entero superior a 3, se mostrará el tamaño de subtítulo más grande.
subtítulos 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 en true 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 secuencias de comandos, que se denominan colectivamente "reproducción automática". Esto incluye la reproducción que se intenta con cualquiera de las siguientes APIs de reproductores:

La mayoría de los navegadores tienen políticas que pueden bloquear la reproducción automática en computadoras, dispositivos móviles y otros entornos si se cumplen ciertas condiciones. Las instancias en las que se puede activar esta política incluyen la reproducción sin silenciar sin interacción del usuario o cuando no se configuró una política de permisos para permitir la reproducción automática en un iframe de origen cruzado.

Para obtener todos los detalles, consulta las políticas específicas del navegador (Apple Safari / WebKit, Google Chrome, Mozilla Firefox) y la guía de reproducción automática de Mozilla.

Ejemplos

Cómo crear 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 URL src del reproductor debe establecer el parámetro enablejsapi en 1 o el atributo enablejsapi del elemento <iframe> debe establecerse en true.

    La función onPlayerReady cambia el color del borde alrededor del reproductor a naranja cuando este está listo. Luego, la función onPlayerStateChange cambia el color del borde alrededor del reproductor según su estado actual. Por ejemplo, el color es verde cuando el reproductor está reproduciendo contenido, rojo cuando está pausado, azul cuando está en el búfer, etcétera.

    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 alta

    En este ejemplo se crea un reproductor de video de 1280 píxeles por 720 píxeles. Luego, el objeto de escucha de eventos para el evento onReady llama a la función setVolume para ajustar el volumen al parámetro de configuración 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 establecen parámetros del reproductor para que reproduzca automáticamente el video cuando se cargue y oculte 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
    }
  });
}

Cómo controlar 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 WebView de Android

YouTube amplió la API de Android WebView Media Integrity para permitir que los reproductores multimedia incorporados, incluidos los reproductores de YouTube incorporados en aplicaciones para Android, verifiquen la autenticidad de la app de incorporación. Con este cambio, las apps de incorporación envían automáticamente un ID de app certificado a YouTube. Los datos recopilados a través del 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 del dispositivo. Está encriptada, 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 su app en la API de WebView Media Integrity. La configuración admite una opción de rechazo.

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

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

October 24, 2019

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

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

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

May 16, 2018

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

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

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

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

August 11, 2016

This update contains the following changes:

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

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

June 29, 2016

This update contains the following changes:

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

June 24, 2016

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

January 6, 2016

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

December 18, 2015

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

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

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

July 23, 2013

This update contains the following changes:

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

October 31, 2012

This update contains the following changes:

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

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

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

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

August 22, 2012

This update contains the following changes:

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

August 6, 2012

This update contains the following changes:

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

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

    • Functions

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

    • Events

July 19, 2012

This update contains the following changes:

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

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

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

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

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

July 16, 2012

This update contains the following changes:

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

June 6, 2012

This update contains the following changes:

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

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

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

March 30, 2012

This update contains the following changes:

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

March 26, 2012

This update contains the following changes:

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