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 la API puede enviar y explica cómo escribir objetos de escucha de eventos para responder a esos eventos. También se detallan las diferentes funciones de JavaScript que es posible invocar para controlar el reproductor de video, así como los parámetros del reproductor que se pueden utilizar para personalizar el reproductor.

Requisitos

El navegador del usuario debe ser compatible con la función postMessage de HTML5. La mayoría de los navegadores modernos admiten postMessage.

Los reproductores insertados deben tener una ventana gráfica de al menos 200 px por 200 px. Si el reproductor muestra controles, debe tener el tamaño suficiente para mostrar los controles por completo, sin reducir la ventana gráfica por debajo del tamaño mínimo. Recomendamos que los reproductores de 16:9 tengan al menos 480 píxeles de ancho y 270 píxeles de alto.

Cualquier página web que utilice la API de IFrame también debe implementar la siguiente función de JavaScript:

  • onYouTubeIframeAPIReady: La API invoca esta función cuando la página termina de descargar el código JavaScript para la API del reproductor, que te permite utilizar la API en tu página. Por lo tanto, esta función podrá crear los objetos del reproductor que deseas mostrar cuando se cargue la página.

Primeros pasos

La página HTML de ejemplo que se muestra a continuación crea un reproductor insertado que carga un video, lo reproduce durante seis segundos y luego detiene la reproducción. Los comentarios numerados en el código HTML se explican en la lista posterior al ejemplo.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

La siguiente lista ofrece más detalles sobre el ejemplo anterior:

  1. La etiqueta <div> de esta sección identifica la ubicación dentro de la página donde la API de IFrame posicionará el reproductor de video. El constructor del objeto del reproductor, que se describe en la sección Cómo cargar un reproductor de video, identifica la etiqueta <div> por su id para garantizar que la API coloque <iframe> en la ubicación correcta. Específicamente, la API de IFrame reemplazará la etiqueta <div> con la etiqueta <iframe>.

    Como alternativa, también puedes colocar el elemento <iframe> directamente en la página. En la sección Cómo cargar un reproductor de video se explica cómo hacerlo.

  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, detenido, finalizado, etcétera. La función indica que cuando el estado del reproductor es 1 (en reproducción), el reproductor debe reproducir un video durante seis segundos y luego invocar 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. En ese momento, podrás construir un objeto YT.Player para insertar un reproductor de video en tu página. En el siguiente extracto de HTML, se muestra la función onYouTubeIframeAPIReady del ejemplo anterior:

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '390',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'playsinline': 1
    },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

El constructor para el reproductor de video especifica los siguientes parámetros:

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

    La API de IFrame reemplazará el elemento especificado con el elemento <iframe> que contiene el reproductor. Esto podría afectar el diseño de tu página si el elemento que se reemplaza tiene un estilo de visualización diferente al del elemento <iframe> insertado. De forma predeterminada, un <iframe> se muestra como un 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): el ID de video de YouTube que identifica el video que cargará el reproductor.
    • playerVars (objeto): Las propiedades del objeto identifican los parámetros del reproductor que se pueden utilizar para personalizar el reproductor.
    • events (objeto): Las propiedades del objeto identifican los eventos que la API activa y las funciones (objetos de escucha de eventos) a las que llamará la API cuando se produzcan esos eventos. En el ejemplo, el constructor indica que la funció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 Cómo comenzar, en lugar de escribir un elemento <div> vacío en tu página, que el código JavaScript de la API del reproductor reemplazará por un elemento <iframe>, podrías crear la etiqueta <iframe> tú mismo. En el primer ejemplo de la sección Ejemplos, se muestra cómo hacerlo.

<iframe id="player" type="text/html" width="640" height="390"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

Ten en cuenta que, si escribes la etiqueta <iframe>, cuando construyes el objeto YT.Player, no necesitas especificar valores para width y height, que se especifican como atributos de la etiqueta <iframe>, o los parámetros videoId y reproductor, que se especifican en la URL src. Como medida de seguridad adicional, también debes incluir el parámetro origin en la URL y especificar el esquema de URL (http:// o https://) y el dominio completo de tu página de alojamiento como valor del parámetro. Aunque origin es opcional, incluir protección contra código JavaScript malicioso de terceros que se introduzca en tu página y que usurpe el control de tu reproductor de YouTube.

En la sección Ejemplos, también se muestran otros dos ejemplos de construcción de objetos del reproductor de video.

Operaciones

Para invocar los métodos de la API del reproductor, debes obtener una referencia al objeto del reproductor que deseas controlar. A fin de obtener la referencia, crea un objeto YT.Player como se explica en las secciones Introducción y Cómo cargar un reproductor de video de este documento.

remotas

Funciones de fila

Las funciones de fila permiten cargar y reproducir un video, una lista de reproducción u otra lista de videos. Si usas la sintaxis de objetos que se describe a continuación para invocar estas funciones, también puedes poner en fila o cargar una lista de los videos subidos de un usuario.

La API es compatible con dos sintaxis diferentes para invocar las funciones de fila.

  • La sintaxis de argumentos requiere que los argumentos de funciones se ordenen de acuerdo con un orden prescrito.

  • La sintaxis de objetos permite transferir un objeto como un parámetro único y definir las propiedades del objeto de los argumentos de la función que quieres ajustar. Además, la API puede admitir funciones adicionales que la sintaxis de argumentos no admite.

Por ejemplo, se puede llamar a la función loadVideoById de cualquiera de las siguientes maneras. Ten en cuenta que la sintaxis de objetos admite la propiedad endSeconds, que la sintaxis de argumentos no admite.

  • Sintaxis de argumentos

    loadVideoById("bHQqvYy5KYo", 5, "large")
  • Sintaxis de objetos

    loadVideoById({'videoId': 'bHQqvYy5KYo',
                   'startSeconds': 5,
                   'endSeconds': 60});

Funciones de fila de videos

cueVideoById
  • Sintaxis de argumentos

    player.cueVideoById(videoId:String,
                        startSeconds:Number):Void
  • Sintaxis de objetos

    player.cueVideoById({videoId:String,
                         startSeconds:Number,
                         endSeconds:Number}):Void

Esta función carga la miniatura del video indicado y prepara el reproductor para reproducir el video. El reproductor no solicita el FLV hasta que se llame a playVideo() o seekTo().

  • El parámetro obligatorio videoId especifica el ID de video de YouTube del video que se va a reproducir. En la API de datos de YouTube, la propiedad id de un recurso video especifica el ID.
  • El parámetro opcional startSeconds acepta un número decimal o entero e indica el tiempo desde el que el video debe comenzar a reproducirse cuando se llama a playVideo(). Si especificas un valor startSeconds y, luego, llamas a seekTo(), el reproductor reproducirá desde el momento especificado en la llamada 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 estará vigente.

loadVideoById

  • Sintaxis de argumentos

    player.loadVideoById(videoId:String,
                         startSeconds:Number):Void
  • Sintaxis de objetos

    player.loadVideoById({videoId:String,
                          startSeconds:Number,
                          endSeconds:Number}):Void

Esta función carga y reproduce el video indicado.

  • El parámetro obligatorio videoId especifica el ID de video de YouTube del video que se va a reproducir. En la API de datos de YouTube, la 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 de objetos

    player.cueVideoByUrl({mediaContentUrl:String,
                          startSeconds:Number,
                          endSeconds:Number}):Void

Esta función carga la miniatura del video indicado y prepara el reproductor para reproducir el video. El reproductor no solicita el FLV hasta que se llame a playVideo() 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 decimal o entero e indica el tiempo desde el que el video debe comenzar a reproducirse cuando se llama a playVideo(). Si especificas startSeconds y, luego, llamas a seekTo(), el reproductor reproducirá desde el momento especificado en la llamada 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 estará vigente.

loadVideoByUrl

  • Sintaxis de argumentos

    player.loadVideoByUrl(mediaContentUrl:String,
                          startSeconds:Number):Void
  • Sintaxis de objetos

    player.loadVideoByUrl({mediaContentUrl:String,
                           startSeconds:Number,
                           endSeconds:Number}):Void

Esta función carga y reproduce el video indicado.

  • El parámetro obligatorio mediaContentUrl especifica una URL de reproductor de YouTube completamente calificada en el 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 el video debe comenzar a reproducirse. Si se especifica un valor de 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 lista de reproducción. Si usas sintaxis de objetos para invocar estas funciones, también puedes poner en cola (o cargar) una lista de los videos subidos de un usuario.

Las funciones son diferentes en función de si se las invoca utilizando la sintaxis de argumentos o la sintaxis de objetos. En vista de aquello, ambos métodos para invocarlas se documentan a continuación.

cuePlaylist
  • Sintaxis de argumentos

    player.cuePlaylist(playlist:String|Array,
                       index:Number,
                       startSeconds:Number):Void
    Pone en cola la lista de reproducción especificada. Cuando la lista de reproducción está en fila y lista para reproducirse, el reproductor transmite un evento video cued (5).
    • El parámetro obligatorio playlist especifica un conjunto de ID de video 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 lista de reproducción que se va a reproducir. El parámetro utiliza un índice basado en cero y el valor predeterminado del parámetro es 0, por lo que el comportamiento predeterminado es cargar y reproducir el primer video de la lista de reproducción.

    • El parámetro opcional startSeconds acepta un número decimal o entero e indica el tiempo desde el que debe comenzar a reproducirse el primer video de la lista de reproducción cuando se invoca la función playVideo(). Si especificas un valor startSeconds y, luego, llamas a seekTo(), el reproductor reproducirá desde el momento especificado en la llamada seekTo(). Si pones en fila una lista de reproducción y luego invocas la función playVideoAt(), el reproductor comenzará a reproducir el comienzo del video especificado.

  • Sintaxis de objetos

    player.cuePlaylist({listType:String,
                        list:String,
                        index:Number,
                        startSeconds:Number}):Void
    Pone en cola la lista de videos especificada. La lista puede ser una lista de reproducción o el feed de videos subidos de un usuario. La función para poner en fila una lista de resultados de la búsqueda está obsoleta y ya no se admitirá a partir del 15 de noviembre de 2020.

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

    • La propiedad opcional listType especifica el tipo de feed de resultados que se va a recuperar. Los valores válidos son playlist y user_uploads. A partir del 15 de noviembre de 2020, ya no se admitirá un valor obsoleto, search. El valor predeterminado es playlist.

    • La propiedad obligatoria list contiene una clave que identifica la lista específica de videos que YouTube debe mostrar.

      • Si el valor de la propiedad listType es playlist, la propiedad list especifica el ID de la lista de reproducción 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 lista de reproducción, 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, 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 va 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 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 seekTo(). Si pone en fila una lista y luego llama a la función playVideoAt(), el reproductor comenzará a reproducir el comienzo del video especificado.

loadPlaylist
  • Sintaxis de argumentos

    player.loadPlaylist(playlist:String|Array,
                        index:Number,
                        startSeconds:Number):Void
    Esta función carga la lista de reproducción especificada y la reproduce.
    • El parámetro obligatorio playlist especifica un conjunto de ID de video de YouTube. En la API de datos de YouTube, la propiedad id del recurso video especifica un ID de video.

    • El parámetro opcional index especifica el índice del primer video de la lista de reproducción que se va a reproducir. El parámetro utiliza un índice basado en cero y el valor predeterminado del parámetro es 0, por lo que el comportamiento predeterminado es cargar y reproducir el primer video de la lista de reproducción.

    • El parámetro opcional startSeconds acepta un número decimal o entero e indica el tiempo desde el que debe comenzar a reproducirse el primer video de la lista de reproducción.

  • Sintaxis de objetos

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number}):Void
    Esta función carga la lista especificada y la reproduce. La lista puede ser una lista de reproducción o el feed de videos subidos de un usuario. La capacidad de cargar una lista de resultados de la búsqueda está obsoleta y ya no se admitirá a partir 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, ya no se admitirá un valor obsoleto, search. El valor predeterminado es playlist.

    • La propiedad obligatoria list contiene una clave que identifica la lista específica de videos que YouTube debe mostrar.

      • Si el valor de la propiedad listType es playlist, la propiedad list especifica un ID de lista de reproducción 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 lista de reproducción 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, 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 va 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 lista.

    • La propiedad opcional startSeconds acepta un número de punto flotante o entero y especifica el tiempo desde el que debe comenzar a reproducirse el primer video de la lista.

Controles de reproducción y configuración del reproductor

Reproducción de un video

player.playVideo():Void
Reproduce el video que se encuentra actualmente cargado o en fila. El estado final del reproductor después de que se ejecuta esta función es playing (1).

Nota: Una reproducción solo se contabiliza para el recuento de vistas oficial de un video si se inicia a través de un botón de reproducción nativo en el reproductor.
player.pauseVideo():Void
Pausa el video que se está reproduciendo. El estado final del reproductor después de que se ejecute esta función será paused (2), a menos que el reproductor se encuentre en el 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 tu intención es pausar el video, solo debes llamar a la función pauseVideo. Si quieres cambiar el video que se está reproduciendo en el reproductor, puedes llamar a una de las funciones de fila sin antes llamar a stopVideo.

Importante: A diferencia de la función pauseVideo, que deja al jugador en el estado paused (2), la función stopVideo podría colocar al jugador en cualquier estado que no se esté reproduciendo, incluidos ended (0), paused (2), video cued (5) o unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Avanza a un momento específico del video. Si el reproductor está en pausa cuando se invoca la función, se mantendrá en pausa. Si se invoca la función desde otro estado (playing, video cued, etc.), el reproductor reproducirá el video.
  • El parámetro seconds identifica el momento en que el reproductor debe avanzar.

    El reproductor avanza al fotograma clave más cercano antes de ese tiempo a menos que el reproductor ya haya descargado la parte del video que el usuario está buscando.

  • El parámetro allowSeekAhead determina si el reproductor realizará una nueva solicitud al servidor si el parámetro seconds especifica un tiempo fuera de los datos de video almacenados en búfer actualmente.

    Te recomendamos establecer este parámetro en false mientras el usuario arrastra el mouse por la barra de progreso de un video y, luego, establecerlo 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 video en 360° tiene compatibilidad limitada en dispositivos móviles. En los dispositivos no compatibles, los videos panorámicos de 360° aparecen distorsionados y no se admite cambiar la perspectiva de visualización, incluida la API, el uso de sensores de orientación o la respuesta a acciones de tocar y arrastrar en la pantalla del dispositivo.

player.getSphericalProperties():Object
Recupera las propiedades que describen la perspectiva o vista actual del usuario para la reproducción de un video. Además:
  • Este objeto solo se propaga para los videos panorámicos de 360°, que también se denominan videos esféricos.
  • Si el video actual no es un video panorámico de 360° o si la función se invoca desde un dispositivo no compatible, la función devuelve un objeto vacío.
  • En los dispositivos móviles compatibles, si la propiedad enableOrientationSensor está configurada como 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 en qué medida el usuario gira la vista para mirar más hacia la izquierda o la derecha. La posición neutra, mirando al centro del video en su proyección equirrectangular, representa 0°, y este valor aumenta a medida que el espectador gira a la izquierda.
pitch Es un número en el rango [-90, 90] que representa el ángulo vertical de la vista en grados, lo que refleja en qué medida el usuario ajusta la vista para mirar hacia arriba o hacia abajo. La posición neutra, mirando al centro del video en su proyección equirrectangular, representa 0°, y este valor aumenta a medida que el usuario mira hacia arriba.
roll Es un número en el rango [-180, 180] que representa el ángulo de rotación en el sentido de las manecillas del reloj o en el sentido contrario a las manecillas del reloj de la vista en grados. La posición neutra, con el eje horizontal en la proyección equirrectangular paralelo al eje horizontal de la vista, representa 0°. El valor aumenta a medida que la vista gira en el sentido de las manecillas del reloj y disminuye a medida que la vista se rota en sentido contrario a las manecillas del reloj.

Ten en cuenta que el reproductor incorporado no presenta una interfaz de usuario para ajustar la rueda de la vista. El lanzamiento se puede ajustar de cualquiera de estas formas mutuamente excluyentes:
  1. Usa el sensor de orientación en un navegador para dispositivos móviles a fin de proporcionar giros para la vista. Si el sensor de orientación está habilitado, la función getSphericalProperties siempre muestra 0 como el valor de la propiedad roll.
  2. Si el sensor de orientación está inhabilitado, configura el giro en un valor distinto de cero con esta API.
fov Un número en el rango [30, 120] que representa el campo visual de la vista en grados según la medida a lo largo del borde más largo del viewport. El borde más corto se ajusta automáticamente para que sea proporcional a la relación de aspecto de la vista.

El valor predeterminado es de 100 grados. Disminuir el valor es como acercar el contenido del video y aumentar el valor como alejarlo. Este valor se puede ajustar mediante la API o la rueda del mouse cuando el video se encuentra en el modo de pantalla completa.
player.setSphericalProperties(properties:Object):Void
Establece la orientación del video para la reproducción de un video panorámico de 360°. (Si el video actual no es esférico, el método es un no-op independientemente de la entrada).

La vista del reproductor responde a las llamadas a este método actualizando para reflejar los valores de cualquier propiedad conocida en el 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 ignorará.
  • Como se señaló al comienzo de esta sección, la experiencia de reproducción de videos en 360° no es compatible con todos los dispositivos móviles.
  • De forma predeterminada, en los dispositivos móviles compatibles, esta función establece solo la propiedad fov y no afecta las propiedades yaw, pitch y 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 Consulte la definición más arriba.
pitch Consulte la definición más arriba.
roll Consulte la definición más arriba.
fov Consulte la definición más arriba.
enableOrientationSensor Nota: Esta propiedad afecta la experiencia de visualización de 360° solo en dispositivos compatibles.Un valor booleano que indica si la incorporación IFrame debe responder a eventos que indiquen cambios en la orientación de un dispositivo compatible, como el DeviceOrientationEvent de un navegador para dispositivos móviles. El valor predeterminado del parámetro es true.

Dispositivos móviles compatibles
  • Cuando el valor es true, el reproductor incorporado solo depende del movimiento del dispositivo para ajustar las propiedades yaw, pitch y roll de las reproducciones de video en 360°. Sin embargo, la propiedad fov aún se puede cambiar a través de la API y, de hecho, la API 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 mediante 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 lista de reproducción.
  • Si se invoca player.nextVideo() mientras se reproduce el último video de la lista de reproducción y la lista de reproducción está configurada para reproducir continuamente (loop), el reproductor cargará y reproducirá el primer video de la lista.

  • Si se llama a player.nextVideo() mientras se reproduce el último video de la lista de reproducción y la lista de reproducción no está configurada para reproducir continuamente, la reproducción finalizará.

player.previousVideo():Void
Esta función carga y reproduce el video anterior de la lista de reproducción.
  • Si se invoca player.previousVideo() mientras se reproduce el primer video de la lista de reproducción y la lista de reproducción está configurada para reproducir continuamente (loop), el reproductor cargará y reproducirá el último video de la lista.

  • Si se invoca player.previousVideo() mientras se reproduce el primer video de la lista de reproducción y la lista de reproducción no está configurada para reproducir continuamente, el reproductor reiniciará el primer video de la lista de reproducción desde el principio.

player.playVideoAt(index:Number):Void
Esta función carga y reproduce el video indicado en la lista de reproducción.
  • El parámetro obligatorio index especifica el índice del video que se desea reproducir en la lista de reproducción. El parámetro utiliza un índice basado en cero, por lo que un valor de 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 al reproductor.
player.unMute():Void
Activa el sonido del jugador.
player.isMuted():Boolean
Muestra 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() volverá a mostrar el volumen, incluso si el reproductor está silenciado.

Configuración del tamaño del reproductor

player.setSize(width:Number, height:Number):Object
Establece el tamaño en píxeles del <iframe> que contiene el reproductor.

Ajuste de la velocidad de reproducción

player.getPlaybackRate():Number
Esta función recupera la velocidad de reproducción del video que se está reproduciendo en ese momento. La velocidad de reproducción predeterminada es 1, lo que indica que el video se reproduce a velocidad normal. Las velocidades de reproducción pueden incluir valores 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 configuras la velocidad de reproducción de un video en fila, esa velocidad seguirá vigente cuando se invoque la función playVideo o el usuario inicie la reproducción directamente a través de los controles del reproductor. Además, invocar funciones para poner en fila o cargar videos o listas de reproducción (cueVideoById, loadVideoById, etc.) restablecerá la velocidad de reproducción a 1.

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

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

La función muestra un array de números ordenados de la velocidad de reproducción más baja a la más rápida. Incluso si el reproductor no admite velocidades variables de reproducción, el array siempre debe contener al menos un valor (1).

Configuración de la reproducción de listas de reproducción

player.setLoop(loopPlaylists:Boolean):Void

Esta función indica si el reproductor de video debe reproducir continuamente una lista de reproducción o si debe detener la reproducción al finalizar el último video de la lista de reproducción. El comportamiento predeterminado es que las listas de reproducción no se reproduzcan en bucle.

Esta configuración se mantendrá incluso si cargas o pones en fila una lista de reproducción diferente, lo que significa que si cargas una lista de reproducción, llamas a la función setLoop con un valor de true y, luego, cargas una segunda lista de reproducción, la segunda lista también se repetirá en bucle.

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

  • Si el valor del parámetro es true, el reproductor de video reproducirá listas de reproducción de forma continua. Después de reproducir el último video de una lista de reproducción, el reproductor de video vuelve al principio de la lista de reproducción y la reproduce nuevamente.

  • Si el valor del parámetro es false, las reproducciones se terminan después de que el reproductor de video reproduce el último video de una lista de reproducción.

player.setShuffle(shufflePlaylist:Boolean):Void

Esta función indica si los videos de una lista de reproducción deben mezclarse para que se reproduzcan en un orden distinto del designado por el autor de la lista de reproducción. Si se mezcla una lista de reproducción después de comenzar a reproducirla, la lista se reordena mientras se reproduce el video actual. El siguiente video para reproducir se selecciona según el nuevo orden de la lista.

Esta configuración no se conservará si cargas o pones en fila una lista de reproducción diferente, lo que significa que si cargas una lista de reproducción, llamas a la función setShuffle y, luego, cargas una segunda lista de reproducción, esta no se mezclará.

El parámetro obligatorio shufflePlaylist indica si YouTube debe mezclar la lista de reproducción.

  • Si el valor del parámetro es true, YouTube mezcla el orden de la lista de reproducción. Si se indica a la función que mezcle una lista de reproducción ya mezclada, YouTube mezcla el orden nuevamente.

  • Si el valor del parámetro es false, YouTube restablece el orden original de las listas de reproducción.

Estado de la reproducción

player.getVideoLoadedFraction():Float
Muestra un número entre 0 y 1 que especifica el porcentaje del video que el reproductor muestra en el búfer. Este método muestra un número más confiable que los métodos getVideoBytesLoaded y getVideoBytesTotal obsoletos.
player.getPlayerState():Number
Muestra el estado del reproductor. Estos son los posibles valores:
  • -1 - unstarted
  • {0/} - ended (terminado)
  • 1 - playing (en reproducción)
  • 2 - paused (en pausa)
  • 3 - buffering (almacenando en búfer)
  • 5 - video cued (video en fila)
player.getCurrentTime():Number
Muestra el tiempo transcurrido en segundos desde que se inició la reproducción del video.
player.getVideoStartBytes():Number
Obsoleto a partir del 31 de octubre de 2012. Muestra el número de bytes desde el cual que el archivo de video comenzó a cargar. (Ahora, este método siempre muestra un valor de 0). Situación de ejemplo: El usuario busca un punto que aún no se cargó y el reproductor realiza una nueva solicitud para reproducir un segmento del video que aún no se cargó.
player.getVideoBytesLoaded():Number
Obsoleto a partir del 18 de julio de 2012. En su lugar, usa el método getVideoLoadedFraction para determinar el porcentaje de video almacenado en el búfer.

Este método muestra un valor entre 0 y 1000 que se aproxima a la cantidad de video cargado. Puedes calcular la fracción del video que se cargó dividiendo 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 de video almacenado en el búfer.

Muestra el tamaño en bytes del video en reproducción o carga actualmente, o una aproximación del tamaño del video.

Este método siempre muestra un valor de 1000. Puedes calcular la fracción del video que se cargó dividiendo 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 comienza a reproducirse el video.

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 actualmente cargado o en reproducción.
player.getVideoEmbedCode():String
Muestra el código insertado del video cargado o en reproducción.

Recuperación de información de una lista de reproducción

player.getPlaylist():Array
Esta función muestra un array de los IDs de video de la lista de reproducción tal como están ordenados actualmente. De forma predeterminada, esta función muestra ID de video en el orden designado por el propietario de la lista de reproducción. Sin embargo, si llamaste a la función setShuffle para desordenar el orden de la lista de reproducción, el valor que se muestra de la función getPlaylist() reflejará el orden aleatorio.
player.getPlaylistIndex():Number
Esta función muestra el índice del video de la lista de reproducción que se está reproduciendo en ese momento.
  • Si no mezclaste la lista de reproducción, el valor mostrado identifica la posición en la que el creador de la lista de reproducción puso el video. El valor mostrado utiliza un índice basado en cero, por lo que un valor de 0 identifica el primer video de la lista de reproducción.

  • Si mezclaste la lista de reproducción, el valor mostrado identifica el orden del video en la lista de reproducción mezclada.

Adición o eliminación de un objeto de escucha de eventos

player.addEventListener(event:String, listener:String):Void
Agrega una función de objeto de escucha para el event especificado. En la sección Eventos a continuación se identifican los diferentes eventos que puede activar el reproductor. El detector es una cadena que indica la función que se ejecuta cuando se activa el evento indicado.
player.removeEventListener(event:String, listener:String):Void
Quita una función de objeto de escucha para el event especificado. listener es una cadena que identifica la función que no se ejecutará cuando se active el evento especificado.

Acceso y modificación de los nodos DOM

player.getIframe():Object
Este método muestra el nodo del DOM para el <iframe> incorporado.
player.destroy():Void
Quita el <iframe> que contiene el reproductor.

Eventos

La API ejecuta eventos para notificar a la aplicación de los cambios en el reproductor insertado. Como se señaló en la sección anterior, puedes suscribirte a eventos agregando un objeto de escucha de eventos durante la construcción del objeto YT.Player, y también puedes usar la función addEventListener.

La API transfiere un objeto de evento como el único argumento para cada una de esas funciones. El objeto de evento tiene las siguientes propiedades:

  • El target del evento identifica el reproductor de video que corresponde al evento.
  • La data del evento especifica un valor relevante para el evento. Ten en cuenta que los 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 llamadas a la API. Tu aplicación debe implementar esta función si quieres ejecutar ciertas operaciones automáticamente, como reproducir el video o mostrar información sobre el video, tan pronto como el reproductor esté listo.

En el siguiente ejemplo, se muestra una función de ejemplo para controlar este evento. El objeto de evento que la API pasa a la función tiene una propiedad target, que identifica el reproductor. La función recupera el código de incorporación del video cargado, comienza a reproducirlo y muestra el código de incorporación en el elemento de la página que tiene un 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á 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. Puede indicar un cambio en el entorno de reproducción del usuario. Consulta el Centro de ayuda de YouTube para obtener más información sobre los factores que afectan las condiciones de reproducción o que podrían causar que se active el evento.

El valor de la propiedad data del objeto del evento que la API pasa a la función de objeto de escucha de eventos es una cadena que identifica la nueva calidad de reproducción. Los valores posibles son:

  • small
  • medium
  • large
  • hd720
  • hd1080
  • highres

onPlaybackRateChange
Este evento se activa cada vez que cambia la velocidad de reproducción del video. Por ejemplo, si llamas a la función setPlaybackRate(suggestedRate), este evento se activará si la velocidad de reproducción cambia. Tu aplicación debería responder al evento y no debería suponer que la velocidad de reproducción cambiará automáticamente cuando se llame a la funció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 del evento que la API pasa a la función de objeto de escucha de eventos es un número que identifica la nueva velocidad de reproducción. El método getAvailablePlaybackRates muestra una lista de las velocidades de reproducción válidas del video en fila o en reproducción.
onError
Este evento se activa si se produce un error en el reproductor. La API pasará un objeto event a la función de objeto de escucha de eventos. La 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 establecer opciones es el módulo captions, que controla los subtítulos opcionales 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 se puede acceder a las opciones a las que deseas acceder. Los siguientes comandos recuperan y actualizan las opciones del módulo:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
La siguiente tabla muestra las opciones que admite la API:

Módulo Opción Descripción
captions fontSize Esta opción ajusta el tamaño de la fuente de los subtítulos que se muestran en el reproductor.

Los valores válidos son -1, 0, 1, 2 y 3. El tamaño predeterminado es 0 y el tamaño mínimo es -1. Si estableces esta opción en un número entero inferior a -1, se mostrará el tamaño de subtítulos más pequeño, mientras que si estableces esta opción en un número entero superior a 3, se mostrará el tamaño más grande de subtítulos.
captions reload Esta opción vuelve a cargar los datos de subtítulos del video en reproducción. Si recuperas el valor de la opción, el valor será null. Establece el valor en true para volver a cargar los datos de subtítulos.
onAutoplayBlocked
Este evento se activa cuando el navegador bloquea la reproducción automática o las funciones de reproducción de video con guion, que en su conjunto se denominan "reproducción automática". Esto incluye los intentos de reproducción con cualquiera de las siguientes API del reproductor:

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 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 del navegador (Safari / Webkit de Apple, Google Chrome, Mozilla Firefox) y la guía de reproducción automática de Mozilla.

Ejemplos

Creando objetos YT.Player

  • Ejemplo 1: Usa la API con un <iframe> existente

    En este ejemplo, un elemento <iframe> en la página ya define el reproductor con el que se usará la API. Ten en cuenta que la URL src del reproductor debe establecer el parámetro enablejsapi en 1 o el atributo enablejsapi del elemento <iframe> debe establecerse en true.

    Cuando el reproductor está listo, la función onPlayerReady cambia el color del borde del reproductor a naranja. 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 se pausa, azul cuando se almacena en búfer, etc.

    En este ejemplo, se usa el siguiente código:

    <iframe id="existing-iframe-example"
            width="640" height="360"
            src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
            frameborder="0"
            style="border: solid 4px #37474F"
    ></iframe>
    
    <script type="text/javascript">
      var tag = document.createElement('script');
      tag.id = 'iframe-demo';
      tag.src = 'https://www.youtube.com/iframe_api';
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
    
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('existing-iframe-example', {
            events: {
              'onReady': onPlayerReady,
              'onStateChange': onPlayerStateChange
            }
        });
      }
      function onPlayerReady(event) {
        document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00';
      }
      function changeBorderColor(playerStatus) {
        var color;
        if (playerStatus == -1) {
          color = "#37474F"; // unstarted = gray
        } else if (playerStatus == 0) {
          color = "#FFFF00"; // ended = yellow
        } else if (playerStatus == 1) {
          color = "#33691E"; // playing = green
        } else if (playerStatus == 2) {
          color = "#DD2C00"; // paused = red
        } else if (playerStatus == 3) {
          color = "#AA00FF"; // buffering = purple
        } else if (playerStatus == 5) {
          color = "#FF6DOO"; // video cued = orange
        }
        if (color) {
          document.getElementById('existing-iframe-example').style.borderColor = color;
        }
      }
      function onPlayerStateChange(event) {
        changeBorderColor(event.data);
      }
    </script>
    
  • Ejemplo 2: Reproducción con volumen alto

    En este ejemplo se crea un reproductor de video de 1280 píxeles por 720 píxeles. El objeto de escucha de eventos del evento onReady llama a la función setVolume para ajustar el volumen al máximo.

    function onYouTubeIframeAPIReady() {
      var player;
      player = new YT.Player('player', {
        width: 1280,
        height: 720,
        videoId: 'M7lc1UVf-VE',
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange,
          'onError': onPlayerError
        }
      });
    }
    
    function onPlayerReady(event) {
      event.target.setVolume(100);
      event.target.playVideo();
    }
    
  • Ejemplo 3: en este ejemplo, se configuran los parámetros para reproducir automáticamente el video cuando se carga y para ocultar los controles del reproductor de video. También agrega objetos de escucha para varios eventos que transmite la API.

    function onYouTubeIframeAPIReady() {
      var player;
      player = new YT.Player('player', {
        videoId: 'M7lc1UVf-VE',
        playerVars: { 'autoplay': 1, 'controls': 0 },
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange,
          'onError': onPlayerError
        }
      });
    }

Cómo controlar los videos panorámicos de 360°

En este ejemplo, se usa el siguiente código:

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

Historial de revisión

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 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.