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; 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:

  1. 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 su id 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.

  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 estás incorporando. Luego, la función 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 el reproductor está reproduciendo contenido, que está detenido, que ya finalizó, etcétera. La función indica que cuando el estado del reproductor es 1 (reproduciendo), este debe reproducir 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, 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:

  1. 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 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): Indica 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): 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ón onPlayerReady 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 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() o seekTo().

  • 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 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 tiempo desde el que debe comenzar a reproducirse el video cuando se llama a playVideo(). Si especificas un valor startSeconds y, luego, llamas a seekTo(), el reproductor reproducirá desde el momento especificado en la llamada a seekTo(). Cuando el video está en fila y listo para reproducirse, el reproductor transmite un evento video 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 a playVideo(). Si especificas un valor endSeconds y, luego, llamas a seekTo(), el valor endSeconds 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 propiedad id de un recurso video 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() o seekTo().

  • El parámetro obligatorio mediaContentUrl especifica una URL de 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 tiempo desde el que debe comenzar a reproducirse el video cuando se llama a playVideo(). Si especificas startSeconds y, luego, llamas a seekTo(), el reproductor reproducirá desde el momento especificado en la llamada a seekTo(). Cuando el video está en fila y listo para reproducirse, el reproductor transmite un evento video 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 a playVideo(). Si especificas un valor endSeconds y, luego, llamas a seekTo(), el valor endSeconds 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 formato http://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 especifica startSeconds (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 evento video cued (5).
    • El parámetro obligatorio playlist especifica un array de IDs de videos de YouTube. En la API de datos de YouTube, 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 a reproducir. El parámetro utiliza 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 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ón playVideo(). Si especificas un valor startSeconds y, luego, llamas a seekTo(), el reproductor reproducirá desde el momento especificado en la llamada a seekTo(). Si se pone en fila una playlist y luego se invoca la función playVideoAt(), 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 del 15 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 son playlist y user_uploads. A partir del 15 de noviembre de 2020, se dejará de admitir un valor obsoleto, search. El valor predeterminado es playlist.

    • 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 es playlist, la propiedad list especifica el ID de la playlist o un array de IDs de video. En la API de datos de YouTube, la propiedad id del recurso playlist identifica el ID de una playlist, y la propiedad id del recurso video especifica un ID de video.
      • Si el valor de la propiedad listType es user_uploads, la propiedad list identifica al usuario cuyos videos subidos se mostrarán.
      • Si el valor de la propiedad listType es search, entonces la propiedad list especifica la búsqueda. Nota: Esta función está obsoleta y dejará de ser compatible a partir del 15 de noviembre de 2020.

    • 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 es 0, 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ón playVideo(). Si especificas un valor startSeconds y, luego, llamas a seekTo(), el reproductor reproducirá desde el momento especificado en la llamada a seekTo(). Si se pone en fila una lista y luego se invoca la función playVideoAt(), 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 propiedad id del recurso video 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 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 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 del 15 de noviembre de 2020.
    • La propiedad opcional listType especifica el tipo de feed de resultados que se va a recuperar. Los valores válidos son playlist y user_uploads. A partir del 15 de noviembre de 2020, se dejará de admitir un valor obsoleto, search. El valor predeterminado es playlist.

    • 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 es playlist, la propiedad list especifica el ID de la playlist o un array de IDs de video. En la API de datos de YouTube, la propiedad id del recurso playlist especifica el ID de una playlist, mientras que la propiedad id del recurso video especifica un ID de video.
      • Si el valor de la propiedad listType es user_uploads, la propiedad list identifica al usuario cuyos videos subidos se mostrarán.
      • Si el valor de la propiedad listType es search, entonces la propiedad list especifica la búsqueda. Nota: Esta función está obsoleta y dejará de ser compatible a partir del 15 de noviembre de 2020.

    • 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 es 0, 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 estado ended (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 a stopVideo.

Importante: A diferencia de la función pauseVideo, que deja al reproductor en el estado paused (2), la función stopVideo puede colocar el reproductor en cualquier estado de no reproducción, como ended (0), paused (2), video cued (5) o unstarted (-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ámetro seconds 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 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 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 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 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:
  1. 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 muestra 0 como el valor de la propiedad roll.
  2. 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 objeto properties. 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 propiedades yaw, pitch ni roll para las reproducciones de video en 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 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 es true.

Dispositivos móviles compatibles
  • Cuando el valor es true, un reproductor incorporado solo depende del movimiento del dispositivo para ajustar las propiedades yaw, pitch y roll para las reproducciones de video en 360°. Sin embargo, la propiedad fov aún se puede modificar mediante la API, que es, de hecho, 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 en 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 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 valor 0 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 y 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
Muestra el volumen actual del reproductor, un número entero entre 0 y 100. Ten en cuenta que getVolume() 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 como 0.25, 0.5, 1, 1.5 y 2.
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 a 1.

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 evento onPlaybackRateChange y tu código debería responder al evento en lugar del hecho de haber llamado a la función setPlaybackRate.

El método getAvailablePlaybackRates devolverá las velocidades de reproducción posibles para el video que se está reproduciendo. Sin embargo, si estableces el parámetro suggestedRate en un valor entero o flotante no admitido, el reproductor redondeará ese valor hacia abajo hasta el valor admitido más cercano a 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, 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 de true 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 y 1 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étodos getVideoBytesLoaded y getVideoBytesTotal 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 entre 0 y 1000 que se aproxima a la cantidad de video cargado. Para calcular la fracción del video que se cargó, puedes dividir 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 actualmente cargado o en reproducción 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ó, puedes dividir el valor de getVideoBytesLoaded por el valor de getVideoBytesTotal.

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ó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
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ó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 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 eventos onReady y onAutoplayBlocked no especifican una propiedad data.

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 propiedad target, 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 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 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)

Cuando el reproductor carga un video por primera vez, transmite un evento unstarted (-1). Cuando un video está en fila y listo para reproducirse, el reproductor transmite 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. 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 propiedad data 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ón setPlaybackRate(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 a setPlaybackRate.

El valor de la propiedad data 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étodo getAvailablePlaybackRates 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 propiedad data 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 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 configurar opciones del reproductor:
player.getOptions();
Actualmente, el único módulo para el que puedes configurar opciones es captions, que controla los subtítulos en el reproductor. Cuando se 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 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 y 3. El tamaño predeterminado es 0 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 a 3 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 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 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:

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. Los casos en los que se puede activar esta política incluyen la reproducción con sonido sin interacción del usuario o cuando no se estableció una política de permisos para permitir la reproducción automática en un iframe de origen cruzado.

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.

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 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 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ón setVolume 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 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.