API de MediaStream

La API de proceso [i]MediaStream, a veces llamadaMedia Stream API o Stream API, es parte de la norma WebRTC [en] 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 en Obtener 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

Eventos

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 optativomandatory 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 proveeTrue 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.

Eventos

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).

Compatibilidad con navegadores

Actualmente, el uso de WebRTC para acceder a la cámara está soportado en Chrome, Opera y Firefox Nightly 18. Habilitar WebRTC en Firefox Nightly requiere que usted establezca una advertencia (flag) en la configuración:

• Escriba "about:config" en la barra de direcciones y diga que sí quiere efectuar los cambios
• Busque la entrada de "media.navigator.enabled" entry y establezca su valos a "true" [sin comillas]

Ver también

• WebRTC - la página de introducción a la API
• getUserMedia()
• Taking webcam photos - un tutorial para usar getUserMedia()