MediaStream API

  • Revision slug: WebRTC/MediaStream_API
  • Revision title: MediaStream API
  • Revision id: 320635
  • Created:
  • Creator: scottrowe
  • 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
audioTracks  MediaStreamTrackList, read-only  Returns the MediaStreamTrackList object representing the audio tracks.
ended Boolean, read-only Returns true if the ended event has fired on the MediaStream object.
label DOMString, read-only A globally unique identifier (GUID) of 36 characters that describes the media stream.
onended EventHandler Handles the ended event when fired on the MediaStream object.
videoTracks  MediaStreamTrackList, read-only Returns the MediaStreamTrackList object representing the video tracks.

Events

Event  Interface  Description 
ended Event All tracks of the MediaStream object have ended; the MediaStream is said to be finished. 

LocalMediaStream

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  Returns true if the track is still associated with its source.
kind DOMString, read-only Returns 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 MediaStream object.
onmute  EventHandler Handles the muted event when fired on the MediaStream object. 
onunmute  EventHandler Handles the unmuted event when fired on the MediaStream 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.
  • ENDED - the track has ended, and the underlying media source will not provide further data.

Events

Event  Interface  Description 
muted Event The MediaStreamTrack object's source is temporarily unable to provide data. 
unmuted  Event The MediaStreamTrack object's source has resumed providing data.
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

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  Returns 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

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 getUserMedia(), 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, &lt;audio&gt; or &lt;video&gt;, 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>audioTracks&nbsp;</td>
      <td>MediaStreamTrackList, read-only&nbsp;</td>
      <td>Returns the MediaStreamTrackList object representing the audio tracks.</td>
    </tr>
    <tr>
      <td>ended</td>
      <td>Boolean, read-only</td>
      <td>Returns true if the ended event has fired on the MediaStream object.</td>
    </tr>
    <tr>
      <td>label</td>
      <td>DOMString, read-only</td>
      <td>A globally unique identifier (GUID) of 36 characters that describes the media stream.</td>
    </tr>
    <tr>
      <td>onended</td>
      <td>EventHandler</td>
      <td>Handles the ended event when fired on the MediaStream object.</td>
    </tr>
    <tr>
      <td>videoTracks&nbsp;</td>
      <td>MediaStreamTrackList, read-only</td>
      <td>Returns the MediaStreamTrackList object representing the video tracks.</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>
  </tbody>
</table>
<h2 id="LocalMediaStream">LocalMediaStream</h2>
<p>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.</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>Returns true if the track is still associated with its source.</td>
    </tr>
    <tr>
      <td>kind</td>
      <td>DOMString, read-only</td>
      <td>Returns <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 MediaStream object.</td>
    </tr>
    <tr>
      <td>onmute&nbsp;</td>
      <td>EventHandler</td>
      <td>Handles the muted event when fired on the MediaStream object.&nbsp;</td>
    </tr>
    <tr>
      <td>onunmute&nbsp;</td>
      <td>EventHandler</td>
      <td>Handles the unmuted event when fired on the MediaStream 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>
          <li>ENDED - the track has ended, and the underlying media source will not provide further data.</li>
        </ul>
      </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>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>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>
<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>Returns 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>
<p>&nbsp;</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>
Revert to this revision