Revision 1116603 of MediaStreamTrack

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

<p>The <strong><code>MediaStreamTrack</code></strong><strong> </strong>interface represents&nbsp;a single media track within a stream; typically, these are audio or video tracks, but other track types may exist as well.</p>

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

<p>In addition to the properties listed below, <code>MediaStreamTrack</code> has constrainable properties which can be set using {{domxref("MediaStreamTrack.applyConstraints", "applyConstraints()")}} and accessed using {{domxref("MediaStreamTrack.getConstraints", "getConstraints()")}} and {{domxref("MediaStreamTrack.getSettings", "getSettings()")}}. See {{SectionOnPage("/en-US/docs/Web/API/Media_Streams_API", "Capabilities and constraints")}} to learn how to correctly work with constrainable properties. Not doing so correctly will result in your code being unreliable.</p>

<dl>
 <dt>{{domxref("MediaStreamTrack.enabled")}}</dt>
 <dd>A Boolean value with a value of <code>true</code> if the track is enabled, that is allowed to render the media source stream; or <code>false</code> if it is disabled, that is not rendering the media source stream but silence and blackness. If the track has been disconnected, this value can be changed but has no more effect.</dd>
 <dt>{{domxref("MediaStreamTrack.id")}} {{readonlyInline}}</dt>
 <dd>Returns a {{domxref("DOMString")}} containing a unique identifier (GUID) for the track; it is generated by the browser.</dd>
 <dt>{{domxref("MediaStreamTrack.kind")}} {{readonlyInline}}</dt>
 <dd>Returns a {{domxref("DOMString")}} set to <code>"audio"</code> if the track is an audio track and to <code>"video"</code>, if it is a video track. It doesn't change if the track is deassociated from its source.</dd>
 <dt>{{domxref("MediaStreamTrack.label")}} {{readonlyInline}}</dt>
 <dd>Returns a {{domxref("DOMString")}} containing a user agent-assigned label that identifies the track source, as in <code>"internal microphone"</code>. The string may be left empty and is empty as long as no source has been connected. When the track is deassociated from its source, the label is not changed.</dd>
 <dt>{{domxref("MediaStreamTrack.muted")}} {{readonlyInline}}</dt>
 <dd>Returns a Boolean value indicating whether the track is muted.</dd>
 <dt>{{domxref("MediaStreamTrack.readonly")}} {{readonlyInline}}</dt>
 <dd>Returns a Boolean value with a value of <code>true</code> if the track is readonly (such a video file source or a camera that settings can't be modified),<code>false</code> otherwise.</dd>
 <dt>{{domxref("MediaStreamTrack.readyState")}} {{readonlyInline}}</dt>
 <dd>Returns an enumerated value giving the status of the track. This will be one of the following values:
 <ul>
  <li><code>"live"</code> which indicates that an input is connected and does its best-effort in providing real-time data. In that case, the output of data can be switched on or off using the <code>MediaStreamTrack.enabled</code> attribute.</li>
  <li><code>"ended"</code> which indicates that the input is not giving any more data and will never provide new data.</li>
 </ul>
 </dd>
 <dt>{{domxref("MediaStreamTrack.remote")}} {{readonlyInline}}</dt>
 <dd>Returns a Boolean with a value of <code>true</code> if the track is sourced by a {{domxref("RTCPeerConnection")}}, <code>false</code> otherwise.</dd>
</dl>

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

<dl>
 <dt>{{domxref("MediaStreamTrack.onstarted")}}</dt>
 <dd>Is a {{domxref("EventHandler")}} containing the action to perform when an {{event("started")}} event is fired on the object, that is when a new {{domxref("MediaStreamTrack")}} object is added.</dd>
 <dt>{{domxref("MediaStreamTrack.onmute")}}</dt>
 <dd>Is a {{domxref("EventHandler")}} containing the action to perform when an {{event("mute")}} event is fired on the object, that is when the streaming is terminating.</dd>
 <dt>{{domxref("MediaStreamTrack.onunmute")}}</dt>
 <dd>Is a {{domxref("EventHandler")}} containing the action to perform when an {{event("unmute")}} event is fired on the object, that is when a&nbsp; {{domxref("MediaStreamTrack")}} object is removed from it.</dd>
 <dt>{{domxref("MediaStreamTrack.onoverconstrained")}}</dt>
 <dd>Is a {{domxref("EventHandler")}} containing the action to perform when an {{event("overconstrained")}} event is fired on the object, that is when a&nbsp; {{domxref("MediaStreamTrack")}} object is removed from it.</dd>
 <dt>{{domxref("MediaStreamTrack.onended")}}</dt>
 <dd>Is a {{domxref("EventHandler")}} containing the action to perform when an {{event("ended_(MediaStream)", "ended")}} event is fired on the object, that is when a&nbsp; {{domxref("MediaStreamTrack")}} object is removed from it.</dd>
</dl>

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

<dl>
 <dt>{{domxref("MediaStreamTrack.applyConstraints", "applyConstraints()")}}</dt>
 <dd>Lets the application specify the ideal and/or ranges of acceptable values for any number of the available constrainable properties of the <code>MediaStreamTrack</code>.</dd>
 <dt>{{domxref("MediaStreamTrack.clone", "clone()")}}</dt>
 <dd>Returns a duplicate of the <code>MediaStreamTrack</code>.</dd>
 <dt>{{domxref("MediaStreamTrack.getCapabilities", "getCapabilities()")}}</dt>
 <dd>Returns the a list of constrainable properties available for the <code>MediaStreamTrack</code>.</dd>
 <dt>{{domxref("MediaStreamTrack.getConstraints", "getConstraints()")}}</dt>
 <dd>Returns a {{domxref('MediaTrackConstraints')}}&nbsp;object containing the currently set constraints for the track; the returned value matches the constraints last set using {{domxref("MediaStreamTrack.applyConstraints", "applyConstraints()")}}.</dd>
 <dt>{{domxref("MediaStreamTrack.getSettings", "getSettings()")}}</dt>
 <dd>Returns a {{domxref("MediaTrackSettings")}} object containing&nbsp;the current values of each of the <code>MediaStreamTrack</code>'s constrainable properties.</dd>
 <dt>{{domxref("MediaStreamTrack.stop", "stop()")}}</dt>
 <dd>Stops playing the source associated to the track, both the source and the track are deassociated. The track state is set to <code>ended</code>.</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', '#mediastreamtrack', 'MediaStreamTrack')}}</td>
   <td>{{Spec2('Media Capture')}}</td>
   <td>Initial definition</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>{{CompatGeckoDesktop(22)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>stop()</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop(34)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>kind, id, label</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop(22)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>clone()</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop(48)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>onended, readyState</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop(50)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>enabled</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop(23)}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>muted</code>, <code>onmute</code>, <code>onunmute</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>remote</code></td>
   <td>{{CompatChrome(48.0)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>getConstraints()</code>, <code>getSettings()</code></td>
   <td>{{CompatChrome(53.0)}}</td>
   <td>{{CompatGeckoDesktop(50)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>onoverconstrained</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>getSources()</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</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>{{CompatGeckoMobile(22)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>stop()</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile(34)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>kind, id, label</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop(22)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>clone()</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile(48)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>onended, readyState</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile(50)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>enabled</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile(23)}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>muted</code>, <code>onmute</code>, <code>onunmute</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>remote</code></td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(48.0)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(48.0)}}</td>
  </tr>
  <tr>
   <td><code>getConstraints()</code>, <code>getSettings()</code></td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(53.0)}}</td>
   <td>{{CompatGeckoDesktop(50)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(52.0)}}</td>
  </tr>
  <tr>
   <td><code>onoverconstrained</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>getSources()</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

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

<ul>
 <li>Media Capture and Streams API</li>
 <li>{{domxref("MediaStream")}}</li>
 <li>{{domxref("AudioStreamTrack")}} and {{domxref("VideoStreamTrack")}}</li>
 <li><a href="/en-US/docs/WebRTC/MediaStream_API" title="/en-US/docs/WebRTC/MediaStream_API">Using the MediaStream API</a></li>
</ul>