API para configuración, consulta y notificaciones de Player

Este artículo provee una referencia de todas las funciones disponibles para el Player de la plataforma para poder integrar el mismo dentro de una página web y poder configurar el contenido a reproducir, consultar su estado y suscribir a las notificaciones emitidas.

---

Setup

Las siguientes funciones permiten crear un nuevo reproductor y consultar de qué forma fue creado el mismo.

setup (opciones)

Inicializa un nuevo Player. El parámetro opciones es necesario y debe ser pasado como Object. Dicho objeto debe contener una propiedad archivo indicando el objetivo de reproducción, de lo contrario el reproductor no podrá iniciar correctamente. Otros parámetros disponibles pueden ser incluidos.

remove ( )

Removerá el reproductor de la página, asegurando que el mismo sea detenido y que todos los recursos utilizados sean liberados.

onReady (callback)

Este evento será disparado cuando el reproductor haya completado su inicialización y esté disponible para comenzar a reproducir contenido.

onSetupError (callback)

Este evento será disparado en caso de error de inicialización. Los parámetros que devolverá son:

• fallback (Boolean): true cuando ocurre un “download fallback”.
• messsage (String): El mensaje de error describiendo por qué no pudo iniciar el reproductor.

---

Buffer

Las siguientes funciones actualizan el estado de carga del archivo actualmente seleccionado. Esto solo aplica a tipos de media progresivos (MP4/FLV/WebM y AAC/MP3/Vorbis). Contenido de tipo streaming no dispone de esta propiedad.

onBufferChange (callback)

Este evento será disparado cuando se cargue contenido adicional al buffer del archivo a reproducir. El siguiente parámetro será enviado:

• buffer (Number): porcentaje entre 0 y 100 indicando la porción cargada en buffer del archivo en curso.

---

Playback

Las siguientes funciones permiten consultar y modificar el estado de reproducción actual.

getState ( )

• IDLE: indica que la reproducción no ha comenzado o está detenida, debido a una llamada a stop() o a un error. Se visualizará el ícono de play o de error.
• BUFFERING: el usuario presionó play, pero no hay suficiente contenido para iniciar la reproducción. Se visualizará el ícono de buffering.
• PLAYING: el contenido está siendo reproducido. No se verá ningún ícono.
• PAUSED: la reproducción está pausada. Se visualizará el ícono play.

play (state)

Cambia el estado del reproductor. En caso que state sea true, el reproductor iniciará la reproducción, en caso que state sea false el reproductor pausará la reproducción y si el parámetro es omitido el reproductor conmutará el estado de reproducción en función del actual.

pause (state)

Cambia el estado del reproductor. En caso que state sea true, el reproductor pausará la reproducción, en caso que state sea false el reproductor iniciará la reproducción y si el parámetro es omitido el reproductor conmutará el estado de reproducción en función del actual.

stop ( )

Detiene el reproductor, retornandolo al estado IDLE y remueve el archivo de media cargado.

onPlay (callback)

Este evento será disparado cuando el reproductor cambie a un estado PLAYING.

• oldstate (String): El estado anterior del reproductor. Puede ser BUFFERING o PAUSED.

onPause (callback)

Este evento será disparado cuando el reproductor cambie a un estado PAUSED.

• oldstate (String): El estado anterior del reproductor. Puede ser BUFFERING o PAUSED.

onBuffer (callback)

Este evento será disparado cuando el reproductor cambie a un estado BUFFERING.

• oldstate (String): El estado anterior del reproductor. Puede ser IDLE, PLAYING o PAUSED.

onIdle (callback)

Este evento será disparado cuando el reproductor cambie a un estado IDLE.

• oldstate (String): El estado anterior del reproductor. Puede ser BUFFERING, PLAYING o PAUSED.

onComplete (callback)

Este evento será disparado cuando el reproductor complete la reproducción. No devuelve propiedades.

onError (callback)

Este evento será disparado en caso de error. El reproductor será detenido y llevado a un estado IDLE.

• message (String): El mensaje describiendo el error.

---

Seek

Las siguientes funciones pueden ser utilizadas para consultar o modificar la posición de reproducción actual.

getPosition ( )

Devuelve la posición de reproducción actual en segundos, como número.

getDuration ( )

Devuelve la duración completa del archivo reproducido en curso en segundos, como número. Un valor de (-1) indica que el contenido es una transmisión en vivo y por lo tanto no tiene posición, duración ni capacidad de búsqueda.

seek (position)

Cambia la posición de reproducción actual para el archivo reproducido en curso. El parámetro position es necesario y debe ser provisto como integer, en segundos.

onSeek (callback)

Este evento será disparado luego de que una operación de seek haya sido solicitada, ya sea desde la barra de control o desde la API.

• position (Number): La posición del reproductor antes de efectuar la búsqueda (en segundos).
• offset (Number): La posición especificada por el llamado de búsqueda, en segundos. Nótese que la posición final de búsqueda puede diferir de la solicitada, por ejemplo debido a que Flash progresivo solo puede buscar entre keyframes o HLS solo puede buscar entre límites de fragmentos.

onTime (callback)

Este evento será disparado cuando la posición de reproducción se modifique, siempre que el reproductor esté reproduciendo. Esto puede ocurrir con una frecuencia de hasta 10 veces por segundo.

• duration (Number): Duración del archivo actual, en segundos.
• position (Number): Posición de reproducción, en segundos.

Nótese que búsquedas para descargas progresivas en Flash solo van a funcionar para porciones ya descargadas. Cuando se realiza una búsqueda fuera de esa sección la búsqueda se hará al último fragmento descargado. Este problema no se presenta en HTML5, por lo que sólo debería ser relevante para IE8.

---

Volumen

Las siguientes funciones permiten consultar y modificar el volumen del reproductor así como también el estado de suspensión de sonido (mute).

getMute ( )

Devuelve el estado actual de la configuración de suspensión de sonido. True si el sonido está suspendido.

getVolume ( )

Devuelve el valor de volumen en porcentaje como número entre 0 y 100.

setMute (state)

Cambia el estado de suspensión de sonido. Si state vale true el sonido será suspendido, si vale false será activado y si no está especificado se conmutará respecto al valor anterior.

setVolume ( )

Configura el valor de volumen en porcentaje como número entre 0 y 100.

onMute (callback)

Este evento será disparado cuando se haya modificado el estado de suspensión de sonido

• mute (Boolean): indica el nuevo estado de suspensión de sonido.

onVolume (callback)

Este evento será disparado cuando se haya modificado el valor de volumen

• volume (Number): indica el nuevo valor de volumen en porcentaje entre 0 y 100.

Resize

Las siguientes funciones permiten notificar sobre cambios en el tamaño del reproductor

onFullScreen (callback)

Este evento será disparado cuando el reproductor conmute de o hacia pantalla completa.

• fullscreen (Boolean): nuevo estado del reproductor; true para pantalla completa, false de lo contrario.

onResize (callback)

Este evento será disparado cuando cambien las dimensiones dentro la página. No será disparado en caso de cambios de o hacia pantalla completa.

• width (Number): indica el nuevo ancho del reproductor.
• height (Number): indica el nuevo alto del reproductor.

---

Quality

Las siguientes funciones permiten notificar sobre cambios de calidad del contenido a reproducir si el mismo dispone de múltiples opciones.

onQualityLevels (callback)

Este evento será disparado cuando se actualice la lista de opciones de calidad disponibles. Ocurrirá por ejemplo luego de que inicie la reproducción de un archivo.

• levels (Array): arreglo de niveles de calidad disponibles.

onQualityChange (callback)

Este evento será disparado cuando cambie el nivel de calidad activa. Ocurrirá por ejemplo cuando el usuario seleccione un nivel distinto desde la barra de control.

• currentQuality (Number): indica un índice dentro del arreglo de niveles de calidad.

---

Fin de la documentación

En este post se da una rápida explicación respecto del uso e integración de los contenidos de Magma (Fluvio) a través de la interface JavaScript.

Ejemplo

A continuación se ejemplifica con un simple código la mínima forma de integrar una transmisión en vivo.

<html>
<head>
  ...
  <script src="https://statics.fluvio.tv/integration/js/pdk.js"></script>
  ...
</head>
<body>
  ...
  <div id="myElement"></div>
  ...
  <script>
  player = LayerPlayer("myElement");
  player.setup({
     asset: "live-12344",
     assetType: 'live',
     width: "500px",
     height: "400px",
     autoplay: "true"
  });
  </script>
</body>
</html>

Para poder utilizar el player debe incluirse la siguiente linea en el encabezado del archivo HTML:

<script src="https://statics.fluvio.tv/integration/js/pdk.js"></script>

Este código se mantiene constantemente actualizado medida que se incorporan nuevas funciones ala plataforma.

El siguiente paso es configurar el player, para ello primero se crea una instancia del player:

player = LayerPlayer("myElement");

El esta asociado a un contenedor, que en este caso posee el ID ‘myElement’. Una vez instanciado debe inicializarse.

player.setup({
   asset: "c7live01-20034",
   assetType: 'live',
   width: "500px",
   height: "400px",
   autoplay: "true"
});

Inmediatamente se puede comenzar a utilizar la interfaz, cada llamado a función se encolará hasta el momento en el que el player termine de inicializarse.

En cualquier momento el player puede ser accedido utilizando la función LayerPlayer, usando como parámetro el ID del elemento contenedor. Ejemplo:

LayerPlayer("myElement").seek(0.3);

Multiples player

Los players pueden accederse a través de la función LayersPlayer. Pude utilizarse como parametros:

El ID del elemento contenedor:

LayerPlayer("pip").pause();
LayerPlayer("main").pause();

el indice del player segun el orden de creación:

LayerPlayer(0).pause();
LayerPlayer(1).pause();

Uso

El acceso tanto a los esteos como a los estados se realiza por medio e métodos o funciones. Pueden diferenciarse los siguientes casos:

1 · Acceso a estados

var volume = player.getVolume();

2 · Seteos

player.setVolume(45);

3 · Eventos

player.onVolume(function(event){
   ...
});

FTP WatchFolder

Una forma conveniente de vincular, los contenidos VOD ingestados a través del FTP WatchFolder es utilizar el PATH dentro de la carpeta.

El parámetro que se envía al método setup, debe contener los siguientes campos:

{
  ...
   asset: {
     raId: 0034,
     ftpTag: 'uploads/contenidos/video.mp4'
  },
  assetType: 'vod'
  ...
}

• assetType: debe fijarse en ‘vod’ para indicar al player que se trata de un contenido bajo demanda.
• asset debe ser un objeto con las siguientes propiedades.

Referencia rápida

En la siguiente tabla se listan los Métodos, propiedades y eventos:

 

Tipos	Get	Set	Eventos
Setup	–	setup remove	onReady onSetupError
Playlist	getPlaylist getPlaylistIndex getPlaylistItem	load playlistItem	onPlaylist onPlaylistItem onPlaylistComplete
Buffer	–	–	onBufferChange
Playback	getState	play pause stop	onPlay onPause onBuffer onIdle onComplete onError
Seek	getPosition getDuration	seek	onSeek onTime
Volume	getMute getVolume	setMute setVolume	onMute onVolume
Resize	–	–	onFullscreen onResize
Quality	–	–	onQualityLevels onQualityChange
Captions	–	–	–
Controls	–	–	–
Advertising	–	–	–
Metadata	–	–	–