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
addtrack
(event)AudioStreamTrack
BlobEvent
ended (MediaStream)
(event)ended (MediaStreamTrack)
(event)MediaStream
MediaStreamConstraints
MediaStreamTrack
MediaStreamTrackEvent
MediaStreamTrackList
MediaTrackConstraints
muted
(event)NavigatorUserMedia
NavigatorUserMediaError
overconstrained
(event)removetrack
(event)started
(event)unmuted
(event)URL
VideoStreamTrack
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:
|
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:
|
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 optionalmandatory
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 aMinMaxConstraint
object. The list is sorted: the 0th entry is most important, and each entry thereafter is progressively less important. - If your provide
true
to themandatory
parameter, and your query is a member of theMediaTrackConstraintSet
for the track, this method returns either its primitive value or itsMinMaxConstraint
, 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
- WebRTC - the introductory page to the API
- getUserMedia()
- Taking webcam photos - a tutorial on using getUserMedia()