MediaStream API

  • Revision slug: WebRTC/MediaStream_API
  • Revision title: MediaStream API
  • Revision id: 377333
  • Created:
  • Creator: ScottMichaud
  • Is current revision? No
  • Comment

Revision Content

The MediaStream interface of the WebRTC API describes a stream of audio or video data, the methods for working with the MediaStream objects, the constraint members that describe the type of data, the success and error callbacks that communicate the data asynchronously, and the events that fire on the MediaStream objects in process.

Basic concepts

A MediaStream object is typically set as a simple URL string which can be used to reference data stored in a DOM File or Blob object with window.URL.createObjectURL(), as described in Get the video. The MediaStream object is further distinguished as either a MediaStreamTrack or a LocalMediaStream.

A MediaStream consists of zero or more MediaStreamTrack objects, which comprise one or more channels, and which are contained in a MediaStreamTrackList. Each MediaStreamTrack may have one or more channels. The channel represents the smallest unit of a media stream, such as an audio signal.

MediaStream objects have an input and an output. A LocalMediaStream is a MediaStream object generated by getUserMedia(), and which has as its source input the user's camera or microphone. The output describes how the consumer uses the MediaStream object. The consumer is either of the media elements, <audio> or <video>, or the PeerConnection API.

MediaStream

A MediaStream object represents a linear, potentially infinite timeline. It is not preloadable, nor is it seekable. 

Attributes

Attribute Type Description
ended Boolean, read-only True if the ended event has fired on the MediaStream object which would mean the MediaStream has finished. It is otherwise false.
id DOMString, read-only A globally unique identifier (GUID) of 36 characters that describes the media stream.
onaddtrack EventHandler Handles the addtrack MediaStreamTrackEvent fired on the MediaStream object.
onended EventHandler Handles the ended event when fired on the MediaStream object.
onremovetrack EventHandler Handles the removetrack MediaStreamTrackEvent fired on the MediaStream object.

Events

Event  Interface  Description 
ended Event All tracks of the MediaStream object have ended; the MediaStream is said to be finished. 
addtrack MediaStreamTrackEvent A new MediaStreamTrack has been added to the MediaStream object.
removetrack MediaStreamTrackEvent An existing MediaStreamTrack has been removed from the MediaStream object.

LocalMediaStream

This object, LocalMediaStream, has been removed as of 20 March 2013 spec.

This reference section will likely be removed. Its stop() method has been moved to the MediaStreamTrack interface.

The LocalMediaStream object is the MediaStream object returned from the call to getUserMedia(). It has all the attributes and events of the MediaStream object and the stop method.

stop()

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

Parameters
None.
Returns
Void.
Exceptions
None.

MediaStreamTrack

A MediaStreamTrack is one of two kinds, audio or video, and represents the media source, such as a camera.

Attributes

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.

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

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera  Safari (WebKit)
Stream API  21{{ property_prefix("webkit") }}  nightly 18{{ property_prefix("moz") }}  {{ CompatUnknown() }}  12 {{ CompatUnknown() }} 
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Stream API  {{ CompatNo() }}  {{ CompatUnknown() }} {{ CompatUnknown() }}  {{ CompatNo() }}  {{ CompatNo() }} 

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

Revision Source

<p>The MediaStream interface of the WebRTC API describes a stream of audio or video data, the methods for working with the MediaStream objects, the constraint members that describe the type of data, the success and error callbacks that communicate the data asynchronously, and the events that fire on the MediaStream objects in process.</p>
<h2 id="Basic_concepts">Basic concepts</h2>
<p>A MediaStream object is typically set as a simple URL string which can be used to reference data stored in a DOM File or Blob object with <a href="/en-US/docs/DOM/window.URL.createObjectURL" title="/en-US/docs/DOM/window.URL.createObjectURL">window.URL.createObjectURL()</a>, as described in <a href="/en-US/docs/WebRTC/taking_webcam_photos#Get_the_video" title="/en-US/docs/WebRTC/taking_webcam_photos#Get_the_video">Get the video</a>. The MediaStream object is further distinguished as either a MediaStreamTrack or a LocalMediaStream.</p>
<p>A MediaStream consists of zero or more MediaStreamTrack objects, which comprise one or more channels, and which are contained in a MediaStreamTrackList. Each MediaStreamTrack may have one or more <strong>channels</strong>. The channel represents the smallest unit of a media stream, such as an audio signal.</p>
<p>MediaStream objects have an <strong>input</strong> and an <strong>output</strong>. A LocalMediaStream is a MediaStream object generated by <a href="/en-US/docs/WebRTC/navigator.getUserMedia" title="/en-US/docs/WebRTC/navigator.getUserMedia">getUserMedia()</a>, and which has as its source input the user's camera or microphone. The output describes how the <strong>consumer</strong> uses the MediaStream object. The consumer is either of the media elements, <code>&lt;audio&gt;</code> or <code>&lt;video&gt;</code>, or the PeerConnection API.</p>
<h2 id="MediaStream">MediaStream</h2>
<p>A MediaStream object represents a linear, potentially infinite timeline. It is not preloadable, nor is it seekable.&nbsp;</p>
<h3 id="Attributes">Attributes</h3>
<table>
  <thead>
    <tr>
      <th scope="col">Attribute</th>
      <th scope="col">Type</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>ended</td>
      <td>Boolean, read-only</td>
      <td>True if the ended event has fired on the MediaStream object which would mean the MediaStream has finished. It is otherwise false.</td>
    </tr>
    <tr>
      <td>id</td>
      <td>DOMString, read-only</td>
      <td>A globally unique identifier (GUID) of 36 characters that describes the media stream.</td>
    </tr>
    <tr>
      <td>onaddtrack</td>
      <td>EventHandler</td>
      <td>Handles the addtrack MediaStreamTrackEvent fired on the MediaStream object.</td>
    </tr>
    <tr>
      <td>onended</td>
      <td>EventHandler</td>
      <td>Handles the ended event when fired on the MediaStream object.</td>
    </tr>
    <tr>
      <td>onremovetrack</td>
      <td>EventHandler</td>
      <td>Handles the removetrack MediaStreamTrackEvent fired on the MediaStream object.</td>
    </tr>
  </tbody>
</table>
<h3 id="Events">Events</h3>
<table>
  <thead>
    <tr>
      <th scope="col">Event&nbsp;</th>
      <th scope="col">Interface&nbsp;</th>
      <th scope="col">Description&nbsp;</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>ended</td>
      <td>Event</td>
      <td>All tracks of the MediaStream object have ended; the MediaStream is said to be finished.&nbsp;</td>
    </tr>
    <tr>
      <td>addtrack</td>
      <td>MediaStreamTrackEvent</td>
      <td>A new MediaStreamTrack has been added to the MediaStream object.</td>
    </tr>
    <tr>
      <td>removetrack</td>
      <td>MediaStreamTrackEvent</td>
      <td>An existing MediaStreamTrack has been removed from the MediaStream object.</td>
    </tr>
  </tbody>
</table>
<h2 id="LocalMediaStream">LocalMediaStream</h2>
<div class="warning">
  <p>This object, LocalMediaStream, has been removed as of 20 March 2013 spec.</p>
  <p>This reference section will likely be removed. Its <code>stop()</code> method has been moved to the MediaStreamTrack interface.</p>
</div>
<p>The LocalMediaStream object is the MediaStream object returned from the call to <a href="/en-US/docs/WebRTC/navigator.getUserMedia" title="/en-US/docs/WebRTC/navigator.getUserMedia">getUserMedia()</a>. It has all the attributes and events of the MediaStream object and the stop method.</p>
<h3 id="stop()">stop()</h3>
<p>Permanently halts the generation of data for the tracks' sources and removes the references to the sources.</p>
<dl>
  <dt>
    <span id="cke_bm_309C" style="display: none; ">&nbsp;</span>Parameters</dt>
  <dd>
    None.</dd>
  <dt>
    Returns</dt>
  <dd>
    Void.</dd>
  <dt>
    Exceptions</dt>
  <dd>
    None.</dd>
</dl>
<h2 id="MediaStreamTrack">MediaStreamTrack</h2>
<p>A MediaStreamTrack is one of two kinds, audio or video, and represents the media source, such as a camera.</p>
<h3 id="Attributes">Attributes</h3>
<table>
  <thead>
    <tr>
      <th scope="col">Attribute&nbsp;</th>
      <th scope="col">Type</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>enabled</td>
      <td>Boolean&nbsp;</td>
      <td>True if the track is still associated with its source.</td>
    </tr>
    <tr>
      <td>id</td>
      <td>DOMString, read-only</td>
      <td>A globally unique identifier (GUID) which describes the media track.</td>
    </tr>
    <tr>
      <td>kind</td>
      <td>DOMString, read-only</td>
      <td>The&nbsp;<strong>audio</strong>&nbsp;or <strong>video</strong> for the source of the track.</td>
    </tr>
    <tr>
      <td>label</td>
      <td>DOMString, read-only</td>
      <td>A user agent-assigned string that identifies the track source, as in "internal microphone."&nbsp;</td>
    </tr>
    <tr>
      <td>onended</td>
      <td>EventHandler</td>
      <td>Handles the ended event when fired on the MediaStreamTrack object.</td>
    </tr>
    <tr>
      <td>onmute&nbsp;</td>
      <td>EventHandler</td>
      <td>Handles the muted event when fired on the MediaStreamTrack object.&nbsp;</td>
    </tr>
    <tr>
      <td>onoverconstrained</td>
      <td>EventHandler</td>
      <td>Handles the overconstrained event when fired on the MediaStreamTrack object.</td>
    </tr>
    <tr>
      <td>onstarted</td>
      <td>EventHandler</td>
      <td>Handles the started event when fired on the MediaStreamTrack object.</td>
    </tr>
    <tr>
      <td>onunmute&nbsp;</td>
      <td>EventHandler</td>
      <td>Handles the unmuted event when fired on the MediaStreamTrack object.</td>
    </tr>
    <tr>
      <td>readyState</td>
      <td>unsigned short, read-only</td>
      <td>
        <p>The track's ready state; values:</p>
        <ul>
          <li>live - the track is active; the output may be switched on and off with the enabled attribute.</li>
          <li>muted - the track's underlying media source is temporarily unable to provide realtime data.</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>sourceId</td>
      <td>DOMString, read-only</td>
      <td>The identity of this source that is unique to this application and persistent between sessions. A GUID is recommended but not required.</td>
    </tr>
    <tr>
      <td>sourceType</td>
      <td>SourceTypeEnum, read-only</td>
      <td>Contains the type information of the source, if one exists.</td>
    </tr>
  </tbody>
</table>
<h3 id="Events">Events</h3>
<table>
  <thead>
    <tr>
      <th scope="col">Event&nbsp;</th>
      <th scope="col">Interface&nbsp;</th>
      <th scope="col">Description&nbsp;</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>started</td>
      <td>Event</td>
      <td>The MediaStreamTrack object is no longer in the "new" readyState.</td>
    </tr>
    <tr>
      <td>muted</td>
      <td>Event</td>
      <td>The MediaStreamTrack object's source is temporarily unable to provide data.&nbsp;</td>
    </tr>
    <tr>
      <td>unmuted&nbsp;</td>
      <td>Event</td>
      <td>The MediaStreamTrack object's source has resumed providing data.</td>
    </tr>
    <tr>
      <td>overconstrained</td>
      <td>Event</td>
      <td>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.</td>
    </tr>
    <tr>
      <td>ended</td>
      <td>Event</td>
      <td>
        <p>The MediaStreamTrack object's source will not provide data; this may be caused by the following:</p>
        <ul>
          <li>the user has revoked permissions on the application</li>
          <li>the source device has been disconnected</li>
          <li>the remote peer has stopped sending data</li>
          <li>the stop() method was invoked</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>
<h3>appendConstraint()</h3>
<p>Adds the constraint to the end of the list. This is only a method of adding optional constraints.</p>
<dl>
  <dt>
    Parameters</dt>
  <dd>
    constraintName <strong>DOMString</strong>, required.</dd>
  <dd>
    constraintValue <strong>Primitive (DOMString, float, etc.) or MinMaxConstraint</strong>, required.</dd>
</dl>
<h3>stop()</h3>
<p>Permanently halts the generation of data for the tracks' sources and removes the references to the sources.</p>
<dl>
  <dt>
    Parameters</dt>
  <dd>
    None.</dd>
  <dt>
    Returns</dt>
  <dd>
    Void.</dd>
  <dt>
    Exceptions</dt>
  <dd>
    None.</dd>
</dl>
<h2 id="MediaStreamTrackList">MediaStreamTrackList</h2>
<p>A MediaStream has two MediaStreamTrackList objects, one for the video and one for the audio tracks.</p>
<table>
  <thead>
    <tr>
      <th scope="col">Attribute&nbsp;</th>
      <th scope="col">Type</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>length</td>
      <td>unsigned long, read-only&nbsp;</td>
      <td>The number of tracks in the list.&nbsp;</td>
    </tr>
    <tr>
      <td>onaddtrack&nbsp;</td>
      <td>EventHandler</td>
      <td>Handles the addtrack event.</td>
    </tr>
    <tr>
      <td>onremovetrack&nbsp;</td>
      <td>EventHandler</td>
      <td>Handles the removetrack event.</td>
    </tr>
  </tbody>
</table>
<h3 id="Events">Events</h3>
<table>
  <thead>
    <tr>
      <th scope="col">Event&nbsp;</th>
      <th scope="col">Interface&nbsp;</th>
      <th scope="col">Description&nbsp;</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>addtrack&nbsp;</td>
      <td>MediaStreamTrackEvent&nbsp;</td>
      <td>A MediaStreamTrack has been added to the list.&nbsp;</td>
    </tr>
    <tr>
      <td>removetrack&nbsp;</td>
      <td>MediaStreamTrackEvent</td>
      <td>A MediaStreamTrack has been removed from the list.&nbsp;</td>
    </tr>
  </tbody>
</table>
<h3 id="add()">add()</h3>
<p>Adds a MediaStreamTrack to this track list.</p>
<dl>
  <dt>
    Parameters</dt>
  <dd>
    MediaStreamTrack <strong>track</strong>, required.</dd>
  <dt>
    Returns</dt>
  <dd>
    Void.</dd>
  <dt>
    Exceptions</dt>
  <dd>
    INVALID_STATE_ERR if the stream is finished (all tracks have ended).</dd>
</dl>
<h3 id="item().C2.A0">item()<span id="cke_bm_369C" style="display: none; ">&nbsp;</span></h3>
<p>Returns the MediaStreamTrack at the specified index value.</p>
<dl>
  <dt>
    Parameters</dt>
  <dd>
    unsigned long <strong>index</strong>, required.</dd>
  <dt>
    Returns</dt>
  <dd>
    MediaStreamTrack</dd>
  <dt>
    Exceptions</dt>
  <dd>
    None.</dd>
</dl>
<h3 id="Remove()">Remove()</h3>
<p>Removes a MediaStreamTrack from this track list.</p>
<dl>
  <dt>
    Parameters</dt>
  <dd>
    MediaStreamTrack&nbsp;<strong>track</strong>, required.</dd>
  <dt>
    Returns</dt>
  <dd>
    Void.</dd>
  <dt>
    Exceptions</dt>
  <dd>
    INVALID_STATE_ERR if the stream is finished (all tracks have ended).</dd>
</dl>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera&nbsp;</th>
        <th>Safari (WebKit)</th>
      </tr>
      <tr>
        <td>Stream API&nbsp;</td>
        <td>21{{ property_prefix("webkit") }}&nbsp;</td>
        <td>nightly 18{{ property_prefix("moz") }}&nbsp;</td>
        <td>{{ CompatUnknown() }}&nbsp;</td>
        <td>12</td>
        <td>{{ CompatUnknown() }}&nbsp;</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE&nbsp;Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Stream API&nbsp;</td>
        <td>{{ CompatNo() }}&nbsp;</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}&nbsp;</td>
        <td>{{ CompatNo() }}&nbsp;</td>
        <td>{{ CompatNo() }}&nbsp;</td>
      </tr>
    </tbody>
  </table>
</div>
<p><span style="line-height: 1.5em; ">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:</span></p>
<ul style="margin: 0px 0px 1.286em; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; ">
  <li>Type "about:config" in the address bar and say yes that you want to make changes</li>
  <li>Find the "media.navigator.enabled" entry and set it to true</li>
</ul>
<h2 id="See_Also">See Also</h2>
<ul>
  <li><a href="/en-US/docs/WebRTC" title="/en-US/docs/WebRTC">WebRTC</a> - the introductory page to the API</li>
  <li><a href="/en-US/docs/WebRTC/navigator.getUserMedia" title="/en-US/docs/WebRTC/navigator.getUserMedia">getUserMedia()</a></li>
  <li><a href="/en-US/docs/WebRTC/taking_webcam_photos" title="/en-US/docs/WebRTC/taking_webcam_photos">Taking webcam photos</a>&nbsp;- a tutorial on using getUserMedia()</li>
</ul>
Revert to this revision