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