Este documento proporciona información de referencia del API del reproductor JavaScript de YouTube.

Contenido

Aspectos generales

El API de JavaScript permite a los usuarios controlar los reproductores de vídeo insertados de YouTube a través de JavaScript. Las llamadas se pueden realizar para reproducir, detener, buscar un determinado momento de un vídeo, ajustar el volumen, silenciar el reproductor y otras muchas funciones útiles.

Requisitos

El usuario final debe tener instalado Flash Player 8 o superior para una correcta visualización. Debido a este requisito, te sugerimos que utilices SWFObject para insertar el objeto SWF y detectar la versión de Flash Player del usuario.

Introducción

Nota: Para probar cualquiera de estas llamadas, deberás ejecutar tu archivo en un servidor web, ya que el reproductor Flash restringe las llamadas entre los archivos locales e Internet.

Para habilitar el API de JavaScript, deberás transmitir el parámetro de URL enablejsapi=1 a la URL del reproductor que deseas controlar. Por ejemplo, imagina que deseas utilizar la siguiente URL para insertar el objeto SWF.

http://www.youtube.com/v/VIDEO_ID&enablejsapi=1

Esto activa los gestionadores del API de JavaScript en el reproductor, y además indica al reproductor que avise a la página HTML contenedora a través de una devolución de llamada cuando el reproductor esté cargado y listo para recibir llamadas de JavaScript. Cuando el reproductor esté listo, se ejecutará la función JavaScript onYouTubePlayerReady.

También puede transmitir un parámetro playerapiid, que identificará el reproductor cuando se ejecute la devolución de llamada a onYouTubePlayerReady. Sea cual sea el valor que se trasmita, playerapiid se transmitirá a onYouTubePlayerReady como primer argumento.

http://www.youtube.com/v/VIDEO_ID&enablejsapi=1&playerapiid=ytplayer

Consulta los ejemplos que aparecen a continuación para obtener más información sobre cómo insertar un objeto SWF de reproductor de YouTube en tu página.

Operaciones

Para ejecutar los métodos de API del reproductor, en primer lugar deberás obtener una referencia al objeto de reproductor que deseas controlar. Para ello, ejecuta getElementById() en la etiqueta object o embed que contiene el objeto SWF del reproductor utilizando SWFObject para insertar el objeto SWF del reproductor.

Funciones

player.playVideo():Void

Reproduce el vídeo actualmente cargado/en cola.

player.pauseVideo():Void

Pausa el vídeo que actualmente en reproducción.

player.stopVideo():Void

Detiene el vídeo actual. También cierra el objeto NetStream y cancela la carga del vídeo. Una vez que se haya ejecutado stopVideo(), un vídeo no se podrá reanudar sin volver a cargar el reproductor o cargar un nuevo vídeo (sólo reproductores sin bordes). Al ejecutar stopVideo(), en primer lugar el reproductor emitirá un evento de finalización (0), seguido de un evento no iniciado (-1).

player.clearVideo():Void

Borra la visualización del vídeo. Resulta útil si deseas borrar el rastro de un vídeo después de ejecutar stopVideo().

player.getVideoBytesLoaded():Number

Devuelve el número de bytes cargados para el vídeo actual.

player.getVideoBytesTotal():Number

Devuelve el tamaño en bytes del vídeo en reproducción/cargado actualmente.

player.getVideoStartBytes():Number

Devuelve el número de bytes desde el que comenzó la carga del archivo de vídeo. Caso de ejemplo: el usuario busca un punto que aún no se ha cargado, y el reproductor realiza una nueva solicitud de reproducción de un segmento del vídeo que aún no se ha cargado.

player.mute():Void

Silencia el reproductor.

player.unMute():Void

Devuelve el sonido al reproductor.

player.isMuted():Boolean

Devuelve el valor true, si el productor está silenciado; false, si no lo está.

player.setVolume(volume):Void

Establece el volumen. Acepta un número entero comprendido entre 0 y 100.

player.getVolume(volume):Void

Devuelve el volumen actual del reproductor, un número entero comprendido entre 0 y 100. Ten en cuenta que getVolume() devolverá el volumen aunque el reproductor esté silenciado.

player.seekTo(seconds, allowSeekAhead):Void

Busca el tiempo especificado del vídeo en segundos. allowSeekAhead determina si el reproductor va a realizar una nueva solicitud al servidor si seconds trasciende los datos de vídeo actualmente cargados. Ten en cuenta que seekTo() intentará buscar el fotograma clave más cercano a los segundos (seconds) especificados. Esto significa que a veces el comienzo de la reproducción puede buscar realmente justo antes o justo después del tiempo solicitado, normalmente no más de ~2 segundos.

player.getPlayerState():Number

Devuelve el estado del reproductor. Los valores posibles son no iniciado (-1), finalizado (0), en reproducción (1), pausado (2), almacenamiento en búfer (3), en cola de vídeos (5).

player.getCurrentTime():Number

Devuelve el tiempo actual en segundos del vídeo actual.

player.getDuration():Number

Devuelve la duración en segundos del vídeo actualmente en reproducción. Ten en cuenta que getDuration() devolverá 0 hasta que se hayan cargado los metadatos del vídeo, lo que normalmente se produce justo después de que comience la reproducción del vídeo.

player.addEventListener(event, listener):Void

Añade una función de escucha para el evento especificado.

player.getVideoUrl():String

Devuelve la URL YouTube.com para el vídeo en reproducción o cargado actualmente.

player.getVideoEmbedCode():String

Devuelve el código insertado para el vídeo en reproducción o cargado actualmente.

Eventos

onStateChange

Se activa siempre que cambie el estado del reproductor. Los valores posibles son no iniciado (-1), finalizado (0), en reproducción (1), pausado (2), almacenamiento en búfer (3), en cola de vídeos (5). Cuando el objeto SWF se carga por primera vez, emitirá un evento (-1) no iniciado. Cuando el vídeo está en cola y listo para reproducirse, emitirá un evento de vídeo en cola (5).

onError

Se activa cuando se produce un error en el reproductor. Actualmente sólo existe un código de error, que es 100 para "No se ha encontrado el vídeo". Esto se produce si se ha eliminado un vídeo (por cualquier motivo) o si el usuario lo ha marcado como privado o no insertable.

Eventos especiales

onYouTubePlayerReady(playerid)

Se ejecuta cuando el reproductor está completamente cargado y el API está listo para recibir llamadas. Si se transmite playerapiid al reproductor a través de argumentos URL, a continuación se transmitirá a esta función. Esta función se debe implementar en la página HTML que contenga el reproductor de YouTube.

Ejemplos

Cómo insertar el reproductor de YouTube mediante el objeto SWFObject

Te recomendamos que utilices SWFObject para insertar cualquier reproductor al que se vaya acceder mediante el API de JavaScript. Esto permite detectar la versión de Flash Player del usuario final (el API de JavaScript requiere Flash Player 8 o superior), y también deshacerse del cuadro "Haga clic para activar este control" cuando utilice Internet Explorer para ver el reproductor. Para habilitar el API en el objeto SWF, deberá transmitir el parámetro enablejsapi=1.

Consulte más adelante un ejemplo de cómo utilizar las secuencias de comandos para insertar un reproductor de YouTube con el API de JavaScript habilitada, y con un objetoplayerapiid de ytplayer.

  <script type="text/javascript" src="swfobject.js"></script>    
  <div id="ytapiplayer">
    You need Flash player 8+ and JavaScript enabled to view this video.
  </div>

  <script type="text/javascript">

    var params = { allowScriptAccess: "always" };
    var atts = { id: "myytplayer" };
    swfobject.embedSWF("http://www.youtube.com/v/VIDEO_ID&enablejsapi=1&playerapiid=ytplayer", 
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

  </script>

El parámetro allowScriptAccess del código es necesario para permitir que el objeto SWF del reproductor ejecute funciones en la página HTML contenedora, ya que el reproductor se encuentra alojado en un dominio distinto al de la página HTML.

El único atributo que se va a transmitir es la id del objeto insertado, en este caso myytplayer. Esta ID es la que utilizaremos para obtener una referencia al reproductor mediante getElementById().

swfobject.embedSWF cargará el reproductor desde YouTube y lo insertará en tu página.

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

• swfUrlStr: es la URL del objeto SWF. Ten en cuenta que hemos añadido los parámetros enablejsapi y playerapiid a la URL de SWF de YouTube normal para habilitar las llamadas del API de JavaScript.
• replaceElemIdStr: es la ID del objeto HTML DIV que sustituirá el contenido insertado. En el ejemplo anterior, es ytapiplayer.
• widthStr: el ancho del reproductor.
• heightStr: la altura del reproductor.
• swfVersionStr: la versión mínima necesaria para que el usuario vea el contenido. En este caso, es necesaria la versión 8 o superior. Si el usuario no tiene la versión 8 o superior, verá la línea predeterminada de texto en el objeto HTML DIV.
• xiSwfUrlStr: (opcional) especifica la URL de tu instalación rápida de SWF. No se ha utilizado en este ejemplo.
• flashVarsObj: (opcional) especifica las FlashVars en los pares nombre:valor. No se ha utilizado en este ejemplo.
• parObj: (opcional) los parámetros del objeto insertado. En este caso, hemos definido allowScriptAccess.
• AttObj: (opcional) los atributos del objeto insertado. En este caso, hemos definido la ID en myytplayer.

Para más información, consulta la documentación de SWFObject.

Cómo obtener la referencia del reproductor

Una vez que el reproductor esté listo, ejecutará onYouTubePlayerReady.

Para obtener la referencia del reproductor, utiliza getElementById(). Cuando tengas el objeto, podrás comenzar a ejecutar llamadas al API.

    function onYouTubePlayerReady(playerId) {
      ytplayer = document.getElementById("myytplayer");
    }

Generación de llamadas

Ahora podrás ejecutar funciones con la referencia del reproductor. Por ejemplo, si deseas reproducir un vídeo una vez que un usuario ha hecho clic en un enlace, deberías introducir lo siguiente:

function play() {
  if (ytplayer) {
    ytplayer.playVideo();
  }
}

<a href="javascript:void(0);" onclick="play();">Play</a>

O simplemente,

 <a href="javascript:ytplayer.playVideo()">Play</a> 

Suscripción a eventos

Para suscribirse a eventos es necesario añadir una función de escucha de eventos a la referencia del reproductor. Por ejemplo, para recibir una notificación cuando el estado del reproductor cambie, añade una función de escucha de eventos a onStateChange e incluye una función de devolución de llamada.

function onYouTubePlayerReady(playerId) {
  ytplayer = document.getElementById("myytplayer");
  ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
}

function onytplayerStateChange(newState) {
   alert("Player's new state: " + newState);
}

Aquí te mostramos un sencillo ejemplo en el que aparecen muchas de las funciones. Observa la superficie para ver lo que se esconde debajo.

Volver al principio