Revision 1111995 of MediaStream

<p>{{APIRef("Media Capture and Streams")}}</p>

<p><span class="seoSummary">The <strong><code>MediaStream</code></strong><strong> </strong>interface represents a stream of media content. A stream consists of several <em>tracks </em>such as&nbsp;video or audio tracks.</span></p>

<p>Some user agents subclass this interface to provide more precise information or functionality, like in {{domxref("CanvasCaptureMediaStream")}}.</p>

<h2 id="Properties">Properties</h2>

<p><em>This interface inherits properties from its parent, </em><em>{{domxref("EventTarget")}}.</em></p>

<dl>
</dl>

<dl>
 <dt>{{domxref("MediaStream.active")}} {{readonlyinline}}</dt>
 <dd>A Boolean value that returns <code>true</code> if the <code>MediaStream</code> is active, or <code>false</code> otherwise.</dd>
 <dt>{{domxref("MediaStream.ended")}} {{readonlyInline}}&nbsp;{{obsolete_inline()}}</dt>
 <dd>A Boolean value set to&nbsp;<code style="font-size: 14px;">true</code>&nbsp;if the {{event("ended (MediaStream)", "ended")}} event has been fired on the object, meaning that the stream has been completely read, or&nbsp;<code style="font-size: 14px;">false</code>&nbsp;if the end of the stream has not been reached. This has been removed from the specification; you should instead check the value of {{domxref("MediaStreamTrack.readyState")}} to see if it's <code>"ended"</code>. For the track or tracks you want to check up on</dd>
</dl>

<dl>
 <dt>{{domxref("MediaStream.id")}} {{readonlyInline}}</dt>
 <dd>A {{domxref("DOMString")}} containing 36 characters denoting a universally unique identifier (UUID) for the object.</dd>
</dl>

<h3 id="Event_handlers">Event handlers</h3>

<dl>
 <dt>{{domxref("MediaStream.onaddtrack")}}</dt>
 <dd>An {{domxref("EventHandler")}} containing the action to perform when an {{event("addtrack")}} event is fired when a new {{domxref("MediaStreamTrack")}} object is added.</dd>
 <dt>{{domxref("MediaStream.onremovetrack")}}</dt>
 <dd>An {{domxref("EventHandler")}} containing the action to perform when an {{event("removetrack")}} event is fired when a&nbsp; {{domxref("MediaStreamTrack")}} object is removed from it.</dd>
</dl>

<h2>Constructor</h2>

<dl>
 <dt>{{domxref("MediaStream.MediaStream", "MediaStream()")}}</dt>
 <dd>Creates and returns a new MediaStream object. You can create an empty stream, a stream which is based upon an existing stream, or a stream that contains a specified list of tracks (specified as an array of {{domxref("MediaStreamTrack")}} objects).</dd>
</dl>

<h2 id="Methods">Methods</h2>

<p><em>This interface inherits methods from its parent, </em><em>{{domxref("EventTarget")}}.</em></p>

<dl>
 <dt>{{domxref("MediaStream.addTrack()")}}</dt>
 <dd>Stores a copy of the {{domxref("MediaStreamTrack")}} given as argument. If the track has already been added to the <code>MediaStream</code> object, nothing happens; if the track is in the <code>finished</code> state - that is, has already reached its end - the exception <code>INVALID_STATE_RAISE</code> is raised.</dd>
</dl>

<dl>
 <dt>{{domxref("MediaStream.clone()")}}</dt>
 <dd>Returns a clone of the <code>MediaStream</code> object. The clone will, however, have a unique value for {{domxref("MediaStream.id", "id")}}.</dd>
</dl>

<dl>
 <dt><span style="line-height:1.572">{{domxref("MediaStream.getAudioTracks()")}}</span></dt>
 <dd><span style="line-height:1.572">Returns a list of the {{domxref("MediaStreamTrack")}} objects stored in the </span><code style="font-size: 14px;">MediaStream</code><span style="line-height:1.572"> object that have their </span><code style="font-size: 14px;">kind</code><span style="line-height:1.572"> attribute set to </span><code style="font-size: 14px;">"audio"</code><span style="line-height:1.572">. The order is not defined, and may not only vary from one browser to another, but also from one call&nbsp;to another.</span></dd>
</dl>

<dl>
 <dt>{{domxref("MediaStream.getTrackById()")}}</dt>
 <dd>Returns the track whose ID corresponds to the one given in parameters,&nbsp;<code style="font-size: 14px;">trackid</code>. If no parameter is given, or if no track with that ID does exist, it returns&nbsp;<code style="font-size: 14px;">null</code>. If several tracks have the same ID, it returns the first one.</dd>
 <dt>{{domxref("MediaStream.getTracks()")}}</dt>
 <dd>Returns a list of all {{domxref("MediaStreamTrack")}} objects stored in the <code>MediaStream</code> object, regardless of the value of the <code>kind</code> attribute. The order is not defined, and may not only vary from one browser to another, but also from one call to another.</dd>
</dl>

<dl>
 <dt>{{domxref("MediaStream.getVideoTracks()")}}</dt>
 <dd>Returns a list of the {{domxref("MediaStreamTrack")}} objects stored in the <code>MediaStream</code> object that have their <code>kind</code> attribute set to <code>"video"</code>. The order is not defined, and may not only vary from one browser to another, but also from one call&nbsp;to another.</dd>
</dl>

<dl>
 <dt>{{domxref("MediaStream.removeTrack()")}}</dt>
 <dd>Removes the {{domxref("MediaStreamTrack")}} given as argument. If the track is not part of the&nbsp;<code style="font-size: 14px;">MediaStream</code>&nbsp;object, nothing happens; if the track is in the&nbsp;<code style="font-size: 14px;">finished</code>&nbsp;state - that is, it has already reached its end - the exception&nbsp;<code style="font-size: 14px;">INVALID_STATE_RAISE</code>&nbsp;is raised.</dd>
</dl>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('Media Capture', '#mediastream', 'MediaStream')}}</td>
   <td>{{Spec2('Media Capture')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<div>{{CompatibilityTable}}</div>

<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</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>getAudioTracks()</code> and <code>getVideoTracks()</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop("23.0")}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>id</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop("41.0")}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>label</code> and <code>stop() </code>{{deprecated_inline()}}</td>
   <td>{{CompatNo}} [1]</td>
   <td>&nbsp;</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>ended</code>&nbsp;{{deprecated_inline()}}</td>
   <td>{{CompatNo}} [2]</td>
   <td>&nbsp;</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>onaddtrack</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop(50)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Android Webview</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>getAudioTracks()</code> and <code>getVideoTracks()</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile("23.0")}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>id</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile("41.0")}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>label</code> and <code>stop()</code> {{deprecated_inline()}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}} [1]</td>
   <td>&nbsp;</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}} [1]</td>
  </tr>
  <tr>
   <td><code>ended</code>&nbsp;{{deprecated_inline()}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}} [2]</td>
   <td>&nbsp;</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}} [2]</td>
  </tr>
  <tr>
   <td><code>onaddtrack</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile(50)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] Deprecated in Chrome 45, removed in Chrome 47.</p>

<p>[2] Deprecated in Chrome 52.</p>

<h2 id="See_also">See also</h2>

<ul>
 <li>Using the MediaStream API</li>
 <li><a href="/en-US/docs/Web/API/WebRTC_API">WebRTC API</a></li>
 <li><a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a></li>
 <li>{{domxref("MediaTrack")}}</li>
</ul>