API MediaStream

Cette fonction est expérimentale
Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

L'API Processing MediaStream, souvent appelée Media Stream API ou Stream API, est la partie de WebRTC décrivant un flux de données audio ou vidéo, les méthodes pour les manipuler, les contraintes associées au type de données, les erreurs et succès des callbacks avec les données asynchrones, et les évènements déclenchés durant le processus.

Concepts de base

L'API est basée sur la manipulation de l'objet MediaStream représentant un flux de données audio ou vidéo. Typiquement, un MediaStream est une simple chaine URL qui peut être utilisée pour référencer une donnée stockée dans un File DOM, ou un objet Blob crée avec window.URL.createObjectURL(), tel que décrit dans cette vidéo.

Un MediaStream consiste en zéro ou plus objets MediaStreamTrack, représentant différentes pistes audio ou vidéos. Chaque MediaStreamTrack peut avoir un ou plusieurs canal. Le canal représente la pus petite unité d'un flux média, tel un signal audio d'un haut-parleur, séparé en gauche et droite sur une piste audio en stéréo.

Les objets MediaStream ont une seule entrée et une seule sortie. Un objet MediaStream généré par getUserMedia() est dit local, et sa source d'entrée provient de l'une des camara ou microphone de l'utilisateur. Un objet MediaStream non local peut représenter un média tel que  <video> ou <audio>, un flux provenant du réseau et obtenu via l'API WebRTC PeerConnection, ou un flux crée en utilisant l'API Web Audio MediaStreamAudioSourceNode. La sortie d'un objet MediaStream est liée à un consommateur. Elle peut-être un élément média tel que <audio> ou <video>, l'API WebRTC PeerConnection ou l'API Web Audio MediaStreamAudioDestinationNode.

Reference

 

MediaStreamTrack

Un objet MediaStreamTrack peut-être de deux types différents, audio ou vidéo, et représente une source (ex: une caméra).

Attributs

Attribute  Type Description
enabled Boolean  True if the track is still associated with its source.
id DOMString, read-only A globally unique identifier (GUID) which describes the media track.
kind DOMString, read-only The audio or video for the source of the track.
label DOMString, read-only A user agent-assigned string that identifies the track source, as in "internal microphone." 
onended EventHandler Handles the ended event when fired on the MediaStreamTrack object.
onmute  EventHandler Handles the muted event when fired on the MediaStreamTrack object. 
onoverconstrained EventHandler Handles the overconstrained event when fired on the MediaStreamTrack object.
onstarted EventHandler Handles the started event when fired on the MediaStreamTrack object.
onunmute  EventHandler Handles the unmuted event when fired on the MediaStreamTrack object.
readyState unsigned short, read-only

The track's ready state; values:

  • live - the track is active; the output may be switched on and off with the enabled attribute.
  • muted - the track's underlying media source is temporarily unable to provide realtime data.
sourceId DOMString, read-only The identity of this source that is unique to this application and persistent between sessions. A GUID is recommended but not required.
sourceType SourceTypeEnum, read-only Contains the type information of the source, if one exists.

Events

Event  Interface  Description 
started Event The MediaStreamTrack object is no longer in the "new" readyState.
muted Event The MediaStreamTrack object's source is temporarily unable to provide data. 
unmuted  Event The MediaStreamTrack object's source has resumed providing data.
overconstrained Event The MediaStreamTrack object's source cannot be configured to fit the constraints imposed by the track. This could be height in the case of video, among several others.
ended Event

The MediaStreamTrack object's source will not provide data; this may be caused by the following:

  • the user has revoked permissions on the application
  • the source device has been disconnected
  • the remote peer has stopped sending data
  • the stop() method was invoked

appendConstraint()

Adds the constraint to the end of the list. This is only a method of adding optional constraints.

Parameters
constraintName DOMString, required.
constraintValue Primitive (DOMString, float, etc.) or MinMaxConstraint, required.
Returns
void
Exceptions
None.

applyConstraints()

Applies the list of optional constraints to the track. This overwrites any existing optional constraints on the track.

Parameters
constraints MediaTrackConstraints, required.
Returns
void
Exceptions
None.

constraints()

Returns all constraints on the track, mandatory and optional. If either mandatory or optional have no constraints, that field will be undefined. If neither have constraints, then constraints() will return null.

Parameters
None.
Returns
MediaTrackConstraints or null
Exceptions
None.

getConstraint()

Fetches a specific constraint, by name, from the track. This method can return one of many possibilities:

  • If your constraint does not exist, null is returned.
  • If you do not provide true to this method's optional mandatory parameter, and your query matches one or more constraints, this method will return a list. Each item in the list will be the query name and either its value or a MinMaxConstraint object. The list is sorted: the 0th entry is most important, and each entry thereafter is progressively less important.
  • If your provide true to the mandatory parameter, and your query is a member of the MediaTrackConstraintSet for the track, this method returns either its primitive value or its MinMaxConstraint, whichever applies.
Parameters
constraintName DOMString, required.
mandatory boolean, optional, default false.
Returns
Any of the possibilities mentioned above.
Exceptions
None.

--

stop()

Permanently halts the generation of data for the tracks' sources and removes the references to the sources.

Parameters
None.
Returns
Void.
Exceptions
None.

MediaStreamTrackList

A MediaStream has two MediaStreamTrackList objects, one for the video and one for the audio tracks.

Attribute  Type Description
length unsigned long, read-only  The number of tracks in the list. 
onaddtrack  EventHandler Handles the addtrack event.
onremovetrack  EventHandler Handles the removetrack event.

Events

Event  Interface  Description 
addtrack  MediaStreamTrackEvent  A MediaStreamTrack has been added to the list. 
removetrack  MediaStreamTrackEvent A MediaStreamTrack has been removed from the list. 

add()

Adds a MediaStreamTrack to this track list.

Parameters
MediaStreamTrack track, required.
Returns
Void.
Exceptions
INVALID_STATE_ERR if the stream is finished (all tracks have ended).

item()

Returns the MediaStreamTrack at the specified index value.

Parameters
unsigned long index, required.
Returns
MediaStreamTrack
Exceptions
None.

Remove()

Removes a MediaStreamTrack from this track list.

Parameters
MediaStreamTrack track, required.
Returns
Void.
Exceptions
INVALID_STATE_ERR if the stream is finished (all tracks have ended).

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera  Safari (WebKit)
Stream API  21webkit  nightly 18moz  ?  12 ? 
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Stream API  Pas de support  ? ?  Pas de support  Pas de support 

Currently using WebRTC for accessing the camera is supported in Chrome, Opera and Firefox Nightly 18. Enabling WebRTC in Firefox Nightly requires you to set a flag in the configuration:

  • Type "about:config" in the address bar and say yes that you want to make changes
  • Find the "media.navigator.enabled" entry and set it to true

See Also

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : JonathanMM, AbrahamT
 Dernière mise à jour par : JonathanMM,