API de MediaStream

Experimental: Esta es una tecnología experimental
Comprueba la Tabla de compabilidad de navegadores cuidadosamente antes de usarla en producción.

La API de proceso MediaStream, a veces llamada Media Stream API o Stream API, es parte de la norma WebRTC y describe un flujo de datos de audio o video, los métodos para trabajar con ellos, las limitaciones asociadas con este tipo de datos, las respuestas de error y éxito al usar los datos asincrónicamente y los eventos que se disparan durante el proceso.

Conceptos Básicos

La API está basada sobre la manipulación de un objeto MediaStream que representa un flujo de datos de audio o video. Generalmente, un objeto MediaStream es una simple cadena URL que puede ser usada para referirse a datos almacenados en un Archivo DOM o un objeto Blob creado con window.URL.createObjectURL(), como se lo describe enObtener el video.

Un MediaStream está compuesto por más objetos [i]MediaStreamTrack que representan varias pistas de audio o video. Cada MediaStreamTrack puede tener uno o más canales. El canal representa la unidad menor de un flujo de medio, como una señal de audio asociada a un parlante específico, como el izquierdo o el derecho en una pista de audio estéreo.

Los objetos MediaStream poseen una sola entrada y salida[ii]. Un objeto MediaStream creado con getUserMedia() se denomina local y tiene como origen de entrada una de las cámaras o micrófonos del usuario. Un MediaStream no local puede estar representando un elemento de medio como <video> o <audio>, un flujo originado en la red y obtenido a través de la [iii]PeerConnection API o un flujo creado con la API de Audio Web [iv]MediaStreamAudioSourceNode. La salida de un objeto MediaStream está enlazada a un consumidor. El mismo puede ser un elemento de medio como <audio> o <video>, la PeerConnection API de WebRTC o una API de Audio Web [v]MediaStreamAudioDestinationNode.

Referencia

Pista de MediaStream

Una MediaStreamTrack puede ser de dos tipos, de audio o video, y representa el origen del medio, como una cámara.

Atributos

enabled: Boolean

True si la pista sigue asociada a su fuente.

id: DOMString, read-only

Un globally unique identifier (GUID) que describe la pista de medios.

kind: DOMString, read-only

El audio o video para la pista de origen.

label: DOMString, read-only

Una cadena de tipo usuario-asignada que identifica la pista de origen, como en "internal microphone."

onended: EventHandler

Maneja el evento finalizado cuando se lo activa en el objeto MediaStreamTrack.

onmute: EventHandler

Maneja el evento mudo del objeto MediaStreamTrack.

onoverconstrained: EventHandler

Maneja el evento superrestricto cuando se lo activa en el objeto MediaStreamTrack.

onstarted: EventHandler

Maneja el evento iniciado cuando se lo activa en el objeto MediaStreamTrack.

onunmute: EventHandler

Manjea el evento sin enmudecer cuando se lo activa en el objeto MediaStreamTrack.

readyState: unsigned short, read-only

Valores para la pista lista:

  • live - la pista está activa; la salida se puede activar on y off con el atributo habilitado.
  • muted - el origen del medio subyacente de la pista no puede proveer temporalmente datos en tiempo real.
sourceId: DOMString, read-only

La identidad de este origen que es único para esta aplicación y persistente. Se recomienda una GUID pero no es obligatoria.

sourceType: SourceTypeEnum, read-only

Contiene el tipo de información del origen, si es que existe.

Eventos

started: Event

El objeto MediaStreamTrack no es más "new" en el readyState.

muted: Event

El origen del objeto MediaStreamTrack no puede proveer datos temporalmente.

unmuted: Event

El origen del objeto MediaStreamTrack a recomenzado a proveer datos

overconstrained: Event

El origen del objeto MediaStreamTrack no puede ser confugurado para que encaje en las restricciones impuestas por la pista. Esto podría ocurrir con la altura en el caso de un video, entre otras posibilidades.

ended: Event

El origen del objeto MediaStreamTrack no proveerá datos; puede ocurrir por lo siguiente:

  • el usuario a deshabilitado los permisos de la aplicación
  • el dispositivo de origen está desconectado
  • el peer remoto no transmite datos
  • se llamó el método stop()

appendConstraint()

Agrega la restricción al final de la lista. Esto sólo es un método para añadir restricciones optativas.

Parámetros

constraintName DOMString, required.

constraintValue Primitive (DOMString, float, etc.) or MinMaxConstraint, required.

Devuelve

void

Excepciones

None.

applyConstraints()

Aplica una lista de opciones optativas a la pista. Sobrescribe cualquier otra restricción optativa ya existente en la pista.

Parámetros

constraints MediaTrackConstraints, required.

Devuelve

void

Excepciones

None.

constraints()

Devuelte todas las [i]restricciones en la pista, obligatorias y optativas. Si tanto mandatory u optional no tienen restricciones, ese campo será undefined. Si ninguno tiene restricciones, entonces constraints() devolverá null.

Parámetros

None.

Devuelve

MediaTrackConstraints or null

Excepciones

None.

getConstraint()

Trae una restricción específica, por nombre, de la pista. Este método puede devolver una de varias posibilidades:

  • Si su restricción no existe, devuelve null.
  • Si no provee true para parámetro optativo mandatory y su búsqueda resulta en más de una restricción, este método devolverá una lista. Cada ítem de la lista será el nombre de la búsqueda así como su valor o un objeto MinMaxConstraint. La lista se agrupa con la entrada 0º como la más importante y cada entrada posterior es progresivamente menos importante.
  • Si provee True al parámetro mandatory y su búsqueda es miembro del MediaTrackConstraintSet de la pista, este método devuelve su valor primitivo o su MinMaxConstraint, cualquiera que aplique al caso.
Parámetros

constraintName DOMString, required.

mandatory boolean, optional, default false.

Devuelve

Any of the possibilities mentioned above.

Excepciones

None.

--

stop()

Detiene permanentemente la creación de datos para las pistas y remueve las referencias a los orígines.

Parámetros

None.

Devuelve

Void.

Excepciones

None.

Lista de pistas de MediaStream

Un MediaStream tiene dos objetos MediaStreamTrackList, uno para la pista de video y otro para la de audio.

Atributo Tipo Descripción
length unsigned long, read-only El número de pistas en la lista.
onaddtrack EventHandler Maneja el evento addtrack.
onremovetrack EventHandler Maneja el evento removetrack.

Eventos

Evento Interfaz Descripción
addtrack MediaStreamTrackEvent Se agregó una MediaStreamTrack a la lista.
removetrack MediaStreamTrackEvent Se removió una MediaStreamTrack de la lista.

add()

Agrega una MediaStreamTrack a la lista de pistas.

Parámetros

MediaStreamTrack track, required.

Devuelve

Void.

Excepciones

INVALID_STATE_ERR if the stream is finished (all tracks have ended).

item()

Devuelve la MediaStreamTrack al valor de índice (index) especificado.

Parámetros

unsigned long index, required.

Devuelve

MediaStreamTrack

Excepciones

None.

Remove()

Remueve una MediaStreamTrack de la lista de pistas.

Parámetros

MediaStreamTrack track, required.

Devuelve

Void.

Excepciones

INVALID_STATE_ERR if the stream is finished (all tracks have ended).

Especificaciones

Specification
Media Capture and Streams
Media Capture from DOM Elements

Compatibilidad con navegadores

api.MediaStream

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
MediaStream
MediaStream() constructor
active
active event
Non-standard
addTrack
addtrack event
clone
getAudioTracks
getTrackById
getTracks
getVideoTracks
id
inactive event
Non-standard
removeTrack
removetrack event

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Non-standard. Check cross-browser support before using.
See implementation notes.
Requires a vendor prefix or different name for use.
Has more compatibility info.

api.MediaStreamTrack

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
MediaStreamTrack
applyConstraints
aspectRatio constraint
autoGainControl constraint
channelCount constraint
deviceId constraint
displaySurface constraint
echoCancellation constraint
facingMode constraint
frameRate constraint
groupId constraint
height constraint
latency constraint
logicalSurface constraint
noiseSuppression constraint
resizeMode constraint
sampleRate constraint
sampleSize constraint
suppressLocalAudioPlayback constraint
Experimental
volume constraint
DeprecatedNon-standard
width constraint
capturehandlechange event
Experimental
clone
contentHint
enabled
ended event
getCapabilities
getCaptureHandle
Experimental
getConstraints
getSettings
id
kind
label
mute event
muted
readyState
stop
unmute event

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
Deprecated. Not for use in new websites.
See implementation notes.
Requires a vendor prefix or different name for use.
Has more compatibility info.

api.MediaDevices

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
MediaDevices
devicechange event
enumerateDevices
getDisplayMedia()
Audio capture support
controller option
Experimental
monitorTypeSurfaces option
Experimental
preferCurrentTab option
ExperimentalNon-standard
selfBrowserSurface option
Experimental
surfaceSwitching option
Experimental
systemAudio option
Experimental
getSupportedConstraints
getUserMedia
Secure context required
selectAudioOutput
Experimental
setCaptureHandleConfig
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
See implementation notes.
Has more compatibility info.

api.MediaDeviceInfo

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
MediaDeviceInfo
deviceId
groupId
kind
label
toJSON()

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
See implementation notes.

api.InputDeviceInfo

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
InputDeviceInfo
getCapabilities

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support

api.CanvasCaptureMediaStreamTrack

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
CanvasCaptureMediaStreamTrack
canvas
requestFrame

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

Ver también