HTMLMediaElement

Baseline

Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since julio de 2015.

* Some parts of this feature may have varying levels of support.

See full compatibility
Learn more

La interfaz HTMLMediaElement añade a HTMLElement las propiedades y métodos necesarios para admitir las capacidades básicas relacionadas con los medios, comunes tanto al audio como al vídeo.

Los elementos HTMLVideoElement y HTMLAudioElement heredan esta interfaz.

Propiedades de instancia

Esta interfaz también hereda propiedades de sus antecesores HTMLElement, Element, Node y EventTarget.

HTMLMediaElement.audioTracks Read only: Un AudioTrackList que enumera los objetos AudioTrack contenidos en el elemento.
HTMLMediaElement.autoplay: Un valor booleano que refleja el atributo HTML autoplay, que indica si la reproducción debe comenzar automáticamente en cuanto haya suficiente contenido multimedia disponible para hacerlo sin interrupciones.

Nota: Reproducir audio automáticamente cuando el usuario no lo espera ni lo desea es una mala experiencia de usuario y debe evitarse en la mayoría de los casos, aunque existen excepciones. Consulta la guía de reproducción automática para las API de medios y Web Audio para obtener más información. Ten en cuenta que los navegadores pueden ignorar las solicitudes de reproducción automática, así que asegúrate de que tu código no dependa de que la reproducción automática funcione.
HTMLMediaElement.buffered Read only: Devuelve un objeto TimeRanges que indica los intervalos de la fuente multimedia que el navegador ha almacenado en el búfer (si los hay) en el momento en que se accede a la propiedad buffered.
HTMLMediaElement.controls: Un booleano que refleja el atributo HTML controls, que indica si deben mostrarse los elementos de la interfaz de usuario para controlar el recurso.
HTMLMediaElement.controlsList: Devuelve un DOMTokenList que ayuda al agente de usuario a seleccionar qué controles mostrar en el elemento multimedia siempre que dicho agente muestre su propio conjunto de controles. El DOMTokenList acepta uno o más de tres valores posibles: nodownload, nofullscreen y noremoteplayback.
HTMLMediaElement.crossOrigin: Una cadena que indica la configuración de CORS para este elemento multimedia.
HTMLMediaElement.currentSrc Read only: Devuelve una cadena con la URL absoluta del recurso multimedia elegido.
HTMLMediaElement.currentTime: Un valor de punto flotante de doble precisión que indica el tiempo de reproducción actual en segundos; si el contenido multimedia no ha comenzado a reproducirse y no se ha desplazado, este valor es el tiempo de reproducción inicial del contenido. Al establecer este valor, el contenido multimedia se desplaza al nuevo tiempo. El tiempo se especifica en relación con la línea de tiempo del contenido multimedia.
HTMLMediaElement.defaultMuted: Un booleano que refleja el atributo HTML muted, que indica si la salida de audio del elemento multimedia debe silenciarse de forma predeterminada.
HTMLMediaElement.defaultPlaybackRate: Un double que indica la velocidad de reproducción predeterminada del contenido multimedia.
HTMLMediaElement.disableRemotePlayback: Un booleano que establece o devuelve el estado de reproducción remota, e indica si el elemento multimedia puede tener una interfaz de reproducción remota.
HTMLMediaElement.duration Read only: Un valor de punto flotante de doble precisión de solo lectura que indica la duración total del contenido multimedia en segundos. Si no hay datos multimedia disponibles, el valor devuelto es NaN. Si el contenido multimedia tiene una duración indefinida (como una transmisión en vivo, el contenido de una llamada WebRTC o similar), el valor es Infinity.
HTMLMediaElement.ended Read only: Devuelve un booleano que indica si el elemento multimedia ha terminado de reproducirse.
HTMLMediaElement.error Read only: Devuelve un objeto MediaError correspondiente al error más reciente, o null si no se ha producido ningún error.
HTMLMediaElement.loading: Una cadena que indica si el navegador debe cargar el contenido multimedia de inmediato (eager) o cuando sea necesario (lazy). Consulta los atributos HTML <video loading> y <audio loading> para obtener más información.
HTMLMediaElement.loop: Un booleano que refleja el atributo HTML loop, que indica si el elemento multimedia debe comenzar de nuevo cuando llega al final.
HTMLMediaElement.mediaKeys Read only Contexto seguro: Devuelve un objeto MediaKeys, que es un conjunto de claves que el elemento puede usar para descifrar los datos multimedia durante la reproducción. Si no hay ninguna clave disponible, puede ser null.
HTMLMediaElement.muted: Un booleano que determina si el audio está silenciado. true si el audio está silenciado y false en caso contrario.
HTMLMediaElement.networkState Read only: Devuelve un unsigned short (enumeración) que indica el estado actual de la obtención del contenido multimedia a través de la red.
HTMLMediaElement.paused Read only: Devuelve un booleano que indica si el elemento multimedia está en pausa.
HTMLMediaElement.playbackRate: Un double que indica la velocidad a la que se está reproduciendo el contenido multimedia.
HTMLMediaElement.played Read only: Devuelve un objeto TimeRanges que contiene los intervalos de la fuente multimedia que el navegador ha reproducido, si los hay.
HTMLMediaElement.preload: Una cadena que refleja el atributo HTML preload, que indica qué datos deben precargarse, si corresponde. Los valores posibles son: none, metadata y auto.
HTMLMediaElement.preservesPitch: Un valor booleano que determina si se conservará el tono del sonido. Si se establece en false, el tono se ajustará a la velocidad del audio.
HTMLMediaElement.readyState Read only: Devuelve un unsigned short (enumeración) que indica el estado de preparación del contenido multimedia.
HTMLMediaElement.remote Read only: Devuelve una instancia del objeto RemotePlayback asociada al elemento multimedia.
HTMLMediaElement.seekable Read only: Devuelve un objeto TimeRanges que contiene los intervalos de tiempo a los que el usuario puede desplazarse, si los hay.
HTMLMediaElement.seeking Read only: Devuelve un booleano que indica si el contenido multimedia está en proceso de desplazarse a una nueva posición.
HTMLMediaElement.sinkId Read only Contexto seguro: Devuelve una cadena que representa el ID único del dispositivo de audio de salida, o una cadena vacía si se está usando el dispositivo de audio predeterminado del agente de usuario.
HTMLMediaElement.src: Una cadena que refleja el atributo HTML src, que contiene la URL del recurso multimedia que se va a usar.
HTMLMediaElement.srcObject: Un objeto que actúa como fuente del contenido multimedia asociado con el HTMLMediaElement, o null si no se ha asignado.
HTMLMediaElement.textTracks Read only: Devuelve un objeto TextTrackList que contiene la lista de objetos TextTrack incluidos en el elemento.
HTMLMediaElement.videoTracks Read only: Devuelve un objeto VideoTrackList que contiene la lista de objetos VideoTrack incluidos en el elemento.
HTMLMediaElement.volume: Un double que indica el volumen de audio, de 0.0 (silencio) a 1.0 (máximo).

Propiedades obsoletas

Estas propiedades son obsoletas y no deben usarse, aunque un navegador todavía las admita.

HTMLMediaElement.controller: Un objeto MediaController que representa el controlador multimedia asignado al elemento, o null si no hay ninguno asignado.
HTMLMediaElement.mediaGroup: Una cadena que refleja el atributo HTML mediagroup, que indica el nombre del grupo de elementos al que pertenece. Un grupo de elementos multimedia comparte un mismo MediaController.
HTMLMediaElement.mozAudioCaptured Read only: Devuelve un booleano. Relacionado con la captura de flujos de audio.
HTMLMediaElement.mozFragmentEnd: Un double que proporciona acceso al tiempo final del fragmento si el elemento multimedia tiene un URI de fragmento para currentSrc; en caso contrario, es igual a la duración del contenido multimedia.

Métodos de instancia

Esta interfaz también hereda métodos de sus antecesores HTMLElement, Element, Node y EventTarget.

HTMLMediaElement.addTextTrack(): Añade un nuevo objeto TextTrack (como una pista para subtítulos) a un elemento multimedia. Se trata únicamente de una interfaz programática y no afecta al DOM.
HTMLMediaElement.captureStream(): Devuelve un MediaStream y captura un flujo del contenido multimedia.
HTMLMediaElement.canPlayType(): Dada una cadena que especifica un tipo de medio MIME (que puede incluir el parámetro codecs), canPlayType() devuelve la cadena probably si el contenido multimedia debería poder reproducirse, maybe si no hay suficiente información para determinar si se reproducirá o no, o una cadena vacía si el contenido multimedia no se puede reproducir.
HTMLMediaElement.fastSeek(): Busca rápidamente el tiempo especificado con baja precisión.
HTMLMediaElement.getStartDate(): Devuelve un objeto Date que representa la fecha y hora reales correspondientes al inicio del contenido multimedia. En el caso de las transmisiones en vivo, este es el momento en que la emisión comenzó en el servidor, que puede ser anterior al momento en que el usuario empezó a verla.
HTMLMediaElement.load(): Reinicia el contenido multimedia al principio y selecciona la mejor fuente disponible entre las proporcionadas mediante el atributo src o el elemento <source>.
HTMLMediaElement.pause(): Pausa la reproducción del contenido multimedia.
HTMLMediaElement.play(): Inicia la reproducción del contenido multimedia.
HTMLMediaElement.seekToNextFrame(): Se desplaza al siguiente fotograma del contenido multimedia. Este método experimental y no estándar permite controlar manualmente la lectura y el renderizado del contenido multimedia a una velocidad personalizada, o recorrerlo fotograma a fotograma para realizar filtrados u otras operaciones.
HTMLMediaElement.setMediaKeys() Contexto seguro: Devuelve una Promise. Establece las claves MediaKeys que se usarán para descifrar el contenido multimedia durante la reproducción.
HTMLMediaElement.setSinkId() Contexto seguro: Establece el ID del dispositivo de audio que se usará para la salida y devuelve una Promise. Esto solo funciona cuando la aplicación está autorizada a usar el dispositivo especificado.

Métodos obsoletos

Estos métodos son obsoletos y no deben usarse, aunque un navegador todavía los admita.

HTMLMediaElement.mozCaptureStream(): El equivalente con prefijo de Firefox de HTMLMediaElement.captureStream(). Consulta su compatibilidad con navegadores para más información.
HTMLMediaElement.mozCaptureStreamUntilEnded(): Un método no estándar y obsoleto para capturar el flujo hasta su finalización.
HTMLMediaElement.mozGetMetadata(): Devuelve un Object que contiene propiedades que representan los metadatos del recurso multimedia en reproducción, en forma de pares {clave: valor}. Cada vez que se llama al método, se devuelve una copia independiente de los datos. Este método debe llamarse después de que se dispare el evento loadedmetadata.

Eventos

Hereda eventos de su padre, HTMLElement.

Escucha estos eventos mediante addEventListener(), o asignando un detector de eventos a la propiedad oneventname de esta interfaz.

abort: Se dispara cuando el recurso no se cargó por completo, pero no como resultado de un error.
canplay: Se dispara cuando el agente de usuario puede reproducir el contenido multimedia, pero calcula que no se han cargado suficientes datos para reproducirlo hasta el final sin tener que detenerse para seguir almacenando contenido en el búfer.
canplaythrough: Se dispara cuando el agente de usuario puede reproducir el contenido multimedia y calcula que se han cargado suficientes datos para reproducirlo hasta el final sin tener que detenerse para seguir almacenando contenido en el búfer.
durationchange: Se dispara cuando se ha actualizado la propiedad de duración.
emptied: Se dispara cuando el contenido multimedia queda vacío; por ejemplo, cuando ya se había cargado (o cargado parcialmente) y se llama al método HTMLMediaElement.load() para volver a cargarlo.
encrypted: Se dispara cuando se encuentran datos de inicialización en el contenido multimedia que indican que está cifrado.
ended: Se dispara cuando la reproducción se detiene al llegar al final del contenido multimedia (<audio> o <video>), o porque ya no hay más datos disponibles.
error: Se dispara cuando el recurso no se pudo cargar debido a un error.
loadeddata: Se dispara cuando termina de cargarse el primer fotograma del contenido multimedia.
loadedmetadata: Se dispara cuando se han cargado los metadatos.
loadstart: Se dispara cuando el navegador comienza a cargar un recurso.
pause: Se dispara cuando se procesa una solicitud para pausar la reproducción y la actividad entra en su estado de pausa, lo que ocurre normalmente cuando se llama al método HTMLMediaElement.pause() del elemento multimedia.
play: Se dispara cuando la propiedad paused cambia de true a false, como resultado del método HTMLMediaElement.play() o del atributo autoplay.
playing: Se dispara cuando la reproducción está lista para comenzar tras haber estado pausada o retrasada por falta de datos.
progress: Se dispara periódicamente mientras el navegador carga un recurso.
ratechange: Se dispara cuando cambia la velocidad de reproducción.
seeked: Se dispara cuando finaliza una operación de desplazamiento.
seeking: Se dispara cuando comienza una operación de desplazamiento.
stalled: Se dispara cuando el agente de usuario intenta obtener datos multimedia, pero estos no llegan de forma inesperada.
suspend: Se dispara cuando se suspende la carga de los datos multimedia.
timeupdate: Se dispara cuando se actualiza el tiempo indicado por la propiedad currentTime.
volumechange: Se dispara cuando ha cambiado el volumen.
waiting: Se dispara cuando la reproducción se detiene debido a una falta temporal de datos.
waitingforkey: Se dispara cuando la reproducción se bloquea inicialmente a la espera de una clave.