Wrapper de ActionScript 3.0 para reproductor sin bordes

Un desarrollador externo escribió y envió este artículo. El equipo de herramientas y APIs de YouTube agradece a Matthew Richmond por su tiempo y experiencia.


Matthew Richmond, The Chopping Block, Inc.
Octubre de 2008

Introducción

En este artículo, presentaré y describiré brevemente un wrapper de ActionScript 3.0 confiable para el reproductor de YouTube sin bordes. El wrapper aprovecha la clase ExternalInterface de ActionScript y la API de JavaScript de YouTube.

Las herramientas de YouTube Player y Chromeless Player de Google permitieron a los diseñadores y desarrolladores integrar de forma rápida y sencilla la potencia de YouTube en sus proyectos en línea. Este enfoque es ideal para proyectos pequeños con presupuestos fijos que no permiten alojar videos, así como para proyectos a gran escala para clientes que desean una experiencia personalizada para el usuario final sin distanciarse de su público de YouTube.

Captura de pantalla del wrapper de ActionScript 3.0
Figura 1: Captura de pantalla del wrapper de ActionScript 3.0

La API Flash de YouTube y los reproductores integrados están escritos y funcionan bastante bien con ActionScript 2.0. Sin embargo, si tu proyecto es ActionScript 3.0, la integración continua se vuelve un poco más compleja. Si bien es fácil cargar los reproductores de ActionScript 2.0 en un swf de ActionScript 3.0, no puedes comunicarte directamente ni pasar ninguna llamada funcional al reproductor cargado. Esto se complica aún más porque el archivo swf que proviene de los servidores de YourTube carga un video en sí mismo. Nuestro wrapper debe estar completamente al tanto de ese hecho y reaccionar según corresponda. Afortunadamente, el lenguaje ActionScript contiene dos soluciones alternativas plausibles para volver a conectar estas piezas anidadas pero desconectadas: la clase LocalConnection o la clase ExternalInterface. Esta demostración se enfocará en la última, ya que ExternalInterface funciona sin problemas con la API de JavaScript bien documentada y, por lo tanto, funciona bien con cualquier otro elemento de la página XHTML.

Recursos importantes

Antes de comenzar, aquí tienes una lista de recursos y archivos relacionados disponibles para ti. Muchos de los temas que se analizan en este artículo se detallan con mayor detalle en los vínculos que aparecen a continuación.

Profundizando

Descripción general de la demostración del wrapper

Archivos de clase de ActionScript
Figura 3: Archivo JavaScript
Archivos de clase de ActionScript
Figura 2: Archivos de clase de ActionScript

El wrapper de ActionScript 3.0 consta, básicamente, de dos partes interconectadas: los archivos de clase de ActionScript 3.0 ubicados en src/choppingblock/video/ (Figura 2) y el archivo JavaScript "youTubeLoader.js" ubicado en deploy/_assets/js/ (Figura 3). Tu archivo fuente Flash/Flex creará una instancia de la clase ActionScript YouTubeLoader. Su página XHTML incorpora el archivo Flash y lo registra con las funciones del archivo JavaScript de youTubeLoader. Es fundamental comprender que, a partir de este punto, todo lo que hace YouTubeLoader dentro del archivo Flash se controla a través de las funciones de JavaScript.

Dado que toda la funcionalidad de Flash se controla a través de la API de JavaScript, NO podrás cargar contenido de YouTube en el reproductor “Test Movie” de Flash. Solo funcionará cuando se incorpore en una página XHTML y se conecte correctamente a las funciones de JavaScript de youTubeLoader.

Nota: Para probar cualquiera de estas invocaciones, deberás ejecutar tu archivo en un servidor web o modificar la Configuración de seguridad de Flash Player, ya que el reproductor de Flash restringe las llamadas entre los archivos locales e Internet.

Cómo crear un objeto YouTubeLoader

Antes de que puedas crear una instancia del objeto YouTubeLoader en tu proyecto Flash/Flex, debes asegurarte de que el paquete (carpeta) de los archivos requeridos se encuentre en el mismo directorio que tu proyecto (consulta la Figura 2) o definido con la ruta de clase de tus proyectos. Luego, puedes importar los archivos del paquete:

import choppingblock.video.*;

Esto permite que tu archivo ActionScript acceda al archivo "YouTubeLoader.as" y 'YouTubeLoaderEvent.as' . Ya puedes crear una instancia de la clase YouTubeLoader y los objetos de escucha de eventos necesarios:

import choppingblock.video.*;

public class YouTubeDemo extends Sprite {

  private var _youTubeLoader:YouTubeLoader;	
  
  // ------------------------------------
  // CONSTRUCTOR
  // ------------------------------------
  
  public function YouTubeDemo () {
    
    // create YouTubeLoader object
    _youTubeLoader = new YouTubeLoader();
    
    // add event listener to call youTubePlayerLoadedHandler method on load
    _youTubeLoader.addEventListener(YouTubeLoaderEvent.LOADED, youTubePlayerLoadedHandler);
    
    // create the actual loader 
    _youTubeLoader.create();
    
    // add object to the display stack
    addChild(_youTubeLoader);
  };
  
  // ------------------------------------
  // EVENT METHODS
  // ------------------------------------
  
  /**
  Called via player loaded event, lets you know you are all clear to send player commands.
  */
  private function youTubePlayerLoadedHandler (event:YouTubeLoaderEvent):void{
    //trace("YouTubeDemo: youTubePlayerLoadedHandler");
    
    // you are now clear to start making calls to the YouTubeLoader object
  };
};

Ahora, si el archivo JavaScript está en su lugar y está conectado correctamente, se debería llamar a youTubePlayerLoadedHandler correctamente y ya podemos comenzar a realizar solicitudes.

Cómo incorporar el swf y conectar el JavaScript de youTubeLoader

No podrás cargar contenido de YouTube correctamente hasta que tu archivo SWF esté incorporado en un archivo XHTML y conectado al código JavaScript de youTubeLoader. Recomendamos usar SWFObject para incorporar cualquier reproductor al que se acceda con la API de JavaScript. Esto te permitirá detectar la versión de Flash Player del usuario final (la API de JavaScript requiere Flash Player 8 o superior) y también eliminará el control "Hacer clic para activar este control" cuando use Internet Explorer para ver el reproductor.

Dentro de la parte <head> de tu archivo XHTML, conecta los archivos swfobject y youTubeLoader:

<script type="text/javascript" src="_assets/js/swfobject.js"></script>
<script type="text/javascript" src="_assets/js/youTubeLoader.js"></script>

A continuación, se muestra un ejemplo del uso de SWFObject para incorporar tu swf de ActionScript 3.0 con la API de JavaScript habilitada y, luego, pasar una referencia a tu swf a la API de JavaScript de youTubeLoader.

<script type="text/javascript">

  var flashvars = {};
  var params = {
    menu: "false",
    allowScriptAccess: "always",
    scale: "noscale"
  };
  var attributes = {
    id: "youtubewrapper"
  };

  swfobject.embedSWF("YouTubeIntegrationDemo.swf", "flashcontent", "960", "500", "9.0.0", "_assets/swf/expressInstall.swf", flashvars, params, attributes);
  
  //init the youTubeLoader JavaScript methods
  SWFID = "youtubewrapper"
    
</script>

El parámetro allowScriptAccess del código es necesario para permitir que el SWF del reproductor invoque funciones en la página HTML contenedora, ya que el reproductor sin bordes está alojado en un dominio distinto al de la página XHTML.

El único atributo que pasamos es el ID del objeto incorporado, en este caso, youtubewrapper. Este ID es lo que el archivo youTubeLoader.js usará para obtener una referencia al reproductor utilizando getElementById().

swfobject.embedSWF cargará el reproductor de YouTube y lo incorporará en tu página.

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

  • swfUrlStr: Es la URL del SWF. Ten en cuenta que agregamos los parámetros enablejsapi y playerapiid a la URL normal de SWF de YouTube para habilitar las llamadas a la API de JavaScript.
  • replaceElemIdStr: Es el ID de DIV HTML que se reemplazará por el contenido incorporado. En el ejemplo anterior, es ytapiplayer.
  • widthStr: Es el ancho del reproductor.
  • heightStr: Altura del reproductor.
  • swfVersionStr: Es la versión mínima requerida 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 como mínimo, verá la línea predeterminada de texto en el DIV HTML.
  • xiSwfUrlStr: Especifica la URL de tu SWF de instalación exprés (opcional). No se utiliza en este ejemplo.
  • flashVarsObj: (Opcional) Especifica tus FlashVars en pares nombre:valor. No se utiliza en este ejemplo.
  • parObj: (Opcional) Son los parámetros del objeto incorporado. En este caso, configuramos allowScriptAccess.
  • AttObj: (opcional): Son los atributos del objeto incorporado. En este caso, configuramos el ID como myytplayer.

Consulta la documentación de SWFObject para obtener una explicación más detallada.

SWFID ≡ almacenará una referencia al ID del objeto de incorporación para que la use la API de JavaScript. Debes usar el mismo ID del objeto incorporado que le asignaste al archivo SWF.

SWFID ≡ "youtubewrapper"

En este punto, deberías poder probar correctamente tu proyecto. El objeto YouTubeLoader debería cargar el reproductor sin Chrome y se debería llamar correctamente al controlador de eventos YouTubeLoaderEvent.LOADED. Ya estamos listos para hacer una solicitud de video y para interactuar con el objeto YouTubeLoader.

Cómo interactuar con el jugador

Dado que este enfoque para crear un wrapper de ActionScript 3.0 para el reproductor sin Chrome aprovecha la clase ExternalInterface de ActionScript, ahora podemos usar cualquiera de las operaciones dentro de la API de YouTube JavaScript Player para controlar nuestro reproductor cargado. Si miras en el archivo "youTubeLoader.js" Archivo JavaScript ubicado en deploy/_assets/js/ (Figura 3) descubrirás que contiene la mayoría de las funciones disponibles. Cada función de la operación se verifica primero con la función checkObj para verificar que la variable SWFID se configuró correctamente antes de que se ejecute.

//------------------------------------
// UTILITY METHODS
//------------------------------------

function checkObj () {
  // alert("youTubeLoader.js : checkObj");
  if (SWFID) {
    createObj();
    return true;
  } else{
    alert("YouTubeLoader: In order to call methods within a swf, you must first set the variable \"SWFID\"!");
    return false;
  };
}
  
//------------------------------------
// YOUTUBE METHODS
//------------------------------------

function loadVideoById(id, startSeconds) {
  // alert("youTubeLoader.js : loadVideoById");
  if (checkObj()) {
    obj.loadVideoById(id,startSeconds);
  };
};

function cueNewVideo(id, startSeconds) {
  // alert("youTubeLoader.js : loadVideoById");
  if (checkObj()) {
    obj.cueVideoById(id, startSeconds);
  }
}

function clearVideo() {
  // alert("youTubeLoader.js : clearVideo");
  if (checkObj()) {
    obj.clearVideo();
  }
}

// plus 17 more...

Dado que el objetivo final de nuestro Wrapper ActionScript 3.0 para el reproductor sin bordes es ofrecer una interacción fluida con la API de YouTube desde un proyecto Flash/Flex de ActionScript 3.0, agregamos exactamente los mismos métodos públicos a "YouTubeLoader.as". ubicado en src/choppingblock/video/ (Figura 2). Esto significa que puedes llamar exactamente a las mismas operaciones directamente al objeto YouTubeLoader dentro de Flash/Flex. En el archivo de la clase, encontrarás lo siguiente:

// ------------------------------------
// YOUTUBE METHODS
// ------------------------------------

public function loadVideoById (id:String, startSeconds:Number = 0):void{
  //trace("YouTubeLoader: loadVideoById");
  ExternalInterface.call("loadVideoById", id, startSeconds);
};

public function cueNewVideo (id:String, startSeconds:Number = 0):void{
  //trace("YouTubeLoader: cueNewVideo");
  ExternalInterface.call("cueNewVideo", id, startSeconds);
};

public function clearVideo ():void{
  //trace("YouTubeLoader: clearVideo");
  ExternalInterface.call("clearVideo");
};

// plus 17 more...

Los métodos de ActionScript usan la clase ExternalInterface para simplemente llamar a la función adecuada dentro de la API de JavaScript.

Cómo solicitar un video

Ahora puedes solicitar un video desde tu archivo ActionScript 3.0 llamando a funciones con la referencia del reproductor. Por ejemplo, si quieres reproducir el video cuando un usuario hace clic en un botón, debes agregar un objeto de escucha de eventos MouseEvent.CLICK a tu botón. Para ello, puedes escribir lo siguiente:

// assuming your button was called 'myButton'
myButton.addEventListener(MouseEvent.CLICK, youtubeLoadVideoHandler);

Crear un método de controlador de eventos para controlar la solicitud Para ello, puedes escribir lo siguiente:

private function youtubeLoadVideoHandler (event:MouseEvent):void{
  
  // assuming that '_youTubeLoader' is a reference to your YouTubeLoader object
  _youTubeLoader.loadVideoById( "u1zgFlCw8Aw" );
};

Fuera de tu archivo Flash/Flex, puedes solicitar un video llamando directamente a la función de JavaScript correspondiente. Para ello, puedes escribir lo siguiente:

 <a href="javascript:loadVideoById('u1zgFlCw8Aw')">Play</a>

Emitir llamadas adicionales

Las llamadas adicionales funcionan de la misma manera que la solicitud de video. desde ActionScript 3, puedes simplemente invocar métodos usando la referencia del reproductor. A continuación, encontrarás una lista completa de los métodos disponibles.

Suscripción a eventos

Puedes suscribirte a eventos agregando un objeto de escucha de eventos a la referencia del reproductor. Por ejemplo, para recibir una notificación cuando cambie el estado del reproductor, agrega un objeto de escucha de eventos para YouTubeLoaderEvent.STATE_CHANGE. Para ello, puedes escribir lo siguiente:

// assuming that '_youTubeLoader' is a reference to your YouTubeLoader object
_youTubeLoader.addEventListener(YouTubeLoaderEvent.STATE_CHANGE, youTubePlayerStateChangeHandler);

Además, crea un método de controlador de eventos para controlar la solicitud. Para ello, puedes escribir lo siguiente:


private function youTubePlayerStateChangeHandler (event:YouTubeLoaderEvent):void{
  //trace("YouTubeIntegrationDemo: youTubePlayerStateChangeHandler");
  
  _stateField.text = event.state;
};

Operaciones disponibles

Para llamar a los métodos de la API de YouTubePlayer, primero debes crear una instancia de la clase YouTubePlayer dentro de tu archivo de ActionScript y almacenar una referencia al objeto YouTubePlayer que deseas controlar. Para ello, llama a lo siguiente:

var _youTubeLoader:YouTubeLoader;
_youTubeLoader = new YouTubeLoader();

Métodos públicos

player.loadVideoById(id:String, startSeconds:Number = 0):void
Carga y reproduce videos según el ID especificado.
player.cueNewVideo(id:String, startSeconds:Number = 0):void
Se carga, pero no reproduce automáticamente el video según el ID especificado.
player.clearVideo():void
Borra el video que se está reproduciendo o cargando.
player.setSize(w:Number, h:Number):void
Establece el tamaño de la instancia de YouTubePlayer.
player.play():void
Reproduce el video que se está reproduciendo o cargando.
player.pause():void
Pausa el video que se está reproduciendo o cargando.
player.stop():void
Detiene el video que se está reproduciendo o cargando.
player.seekTo(seconds:Number):void
Busca un tiempo especificado dentro del video cargado o en fila.
player.getPlayerState():String
Devuelve el estado actual del video que se está reproduciendo o cargando.
player.getBytesLoaded():Number
Muestra el valor de los bytes actuales cargados del video cargado o en fila.
player.getBytesTotal():Number
Devuelve el valor de los bytes totales cargados del video que se está reproduciendo o cargando actualmente.
player.getCurrentTime():Number
Devuelve la posición actual en el tiempo del video que se está reproduciendo o cargando.
player.getDuration():Number
Devuelve la duración actual del video que se está reproduciendo o cargando.
player.getStartBytes():Number
Muestra los bytes iniciales del video cargado o en fila.
player.setVolume(newVolume:Number):void
Establece el volumen del video cargado o en fila.
player.getVolume():Number
Muestra el volumen actual del video cargado o en fila.
player.mute():void
Almacena el volumen actual y cambia el volumen del video en cola o cargado actualmente a 0.
player.unmute():void
Devuelve el volumen del video que se está reproduciendo o cargando actualmente al último valor almacenado cuando se silencia.
player.getEmbedCode():String
Muestra el código de incorporación actual de YouTube del video cargado o en fila.
player.getVideoUrl():String
Muestra la URL del video de YouTube actual del video cargado o en fila.

Eventos

YouTubeLoaderEvent.LOADED
Se activa una vez que el reproductor sin Chrome completa la carga de forma correcta y está listo para aceptar llamadas de operaciones.
YouTubeLoaderEvent.STATE_CHANGE
Se activa cada vez que cambia el estado del jugador. La clase YouTubeLoader traduce los números de la API de JavaScript a los valores de cadena relacionados, la clase YouTubeLoaderEvent almacena el evento actual en una variable llamada state. Los valores posibles son sin comenzar, finalizar, reproduciendo, pausado, almacenamiento en búfer, video en cola. Cuando el SWF se cargue por primera vez, transmitirá un evento no iniciado. Cuando el video esté listo para reproducirse, se transmitirá un evento de video en cola.
YouTubeLoaderEvent.IO_ERROR
Se activa cuando se produce un error en el reproductor. Hay dos códigos de error posibles: 100 se transmite cuando no se encuentra el video solicitado. Esto ocurre cuando se quita un video (por cualquier motivo) o se marca como privado. El código 101 se transmite cuando el video solicitado no permite la reproducción en los reproductores incorporados.

Notas sobre la demostración

Para fines de demostración, quisimos incluir los campos del formulario, los botones y la IU de visualización de XHTML debajo del wrapper de ActionScript 3 incorporado. Para tener el archivo swf Y la actualización XHTML al mismo tiempo, tuvimos que incluir dos líneas de código en el archivo "youTubeLoader.js" Archivo JavaScript ubicado en “deploy/_assets/js/” (Figura 3). Es conveniente eliminar las dos líneas siguientes [69, 79] cuando integres este archivo en tu proyecto:

//------------------------------------
// SPECIAL YOUTUBE EVENT METHODS
//------------------------------------

function onYouTubePlayerReady(playerId) {

  if (checkObj()) {	
    obj.addEventListener("onStateChange", "onytplayerStateChange");
  };

  // PLEASE NOTE: For the purpose of this demo:
  // This calls a secondary method located in the index.html file allowing the html display to update.
  // You will most likely not need this, it's gross, remove this when you implement this code.
  secondaryOnYouTubePlayerReady(playerId);
}

function onytplayerStateChange(newState) {
    //alert("Player's new state: " + newState);
  obj.playerStateUpdateHandler(newState);

  // PLEASE NOTE: For the purpose of this demo:
  // This calls a secondary method located in the index.html file allowing the html display to update.
  // You will most likely not need this, it's gross, remove this when you implement this code.
  secondaryOnytplayerStateChange(newState)
}

El archivo de demostración y las bibliotecas ActionScript incluidas son software libre: puedes redistribuirlo o modificarlo según los términos de la Licencia Pública General Reducida de GNU. Estos archivos se distribuyen con la esperanza de que sean útiles, pero sin ninguna garantía.

Conclusión

Este artículo, la demo y los archivos fuente deberían brindarte una descripción general sólida de una solución relativamente simple y confiable para integrar la API de YouTube y los reproductores incorporados en entornos de ActionScript 3 con la biblioteca del wrapper que desarrollamos para nuestros propios proyectos. Dado que comenté gran parte del código, lo ideal es que sea bastante sencillo explorar y reutilizar las bibliotecas. No carece de limitaciones, y siempre hay espacio para mejorar, refactorizar y mejorar. Si tienes alguna opinión al respecto, comunícate conmigo.

Biografía del autor


Matías Carrizo

Matthew Richmond cuenta con 14 años de experiencia en diseño, desarrollo y arquitectura interactivos. Cuando no está en el estudio, se lo puede encontrar enseñando técnicas de ilustración y fotografía digitales, y ActionScript avanzado en la School of Visual Arts. Matías es socio fundador y diseñador de choppingblock.com.