Revision 1116107 of MediaStreamTrack

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

<p>The <strong><code>MediaStreamTrack</code></strong><strong> </strong>interface represents&nbsp;a media source in the User Agent, like video or audio tracks.</p>

<h2>Capabilities and constraints</h2>

<p>The twin concepts of constraints and capabilies let the browser and Web site or app exchange information about what properties the browser's implementation of a track supports and what values it will accept for each one. An API provides a list of <strong>capabilities</strong>, lets the script determine which constrainable properties are supported by the browser. Once the script knows whether the property or properties it wishes to use are supported, it can then check the <strong>constraints</strong> of the API and its implementation, so that the script can adjust its inputs into the API, its code path, or even report problems to the user if necessary. Finally, it can then configure the API as desired by specifying the values or ranges of values it wishes to use for any of the constrainable properties about which it has a preference.</p>

<p>Before using any of the constrainable properties on the <code>MediaStreamTrack</code> interface, you begin by calling {{domxref("MediaDevices.getSupportedConstraints", "navigator.mediaDevices.getSupportedConstraints()")}} to get a list of the constrainable properties which the browser recognizes at all. Only properties included in the returned list should be used. You can use a pattern like this:</p>

<pre class="brush: js">
let supported = navigator.mediaDevices.getSupportedConstraints();

let constraints = {
  width: 640,
  height: 480
};

if (supported["frameRate"]) {
  constraints.frameRate = { min: 30 };
}</pre>

<p>In this example, the supported constraints are fetched, and then the <code>frameRate</code> constraint is only requested when the browser supports it.</p>

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

<dl>
 <dt>{{domxref("MediaStreamTrack.enabled")}}</dt>
 <dd>Is 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.getConstraints", "MediaStreamTrack.getConstraints()")}}</dt>
 <dd>Returns a {{domxref('MediaTrackConstraints')}}&nbsp;object containing the full set of constraints&nbsp;for the properties of the current&nbsp;<code>MediaStreamTrack</code>.</dd>
 <dt>{{domxref("MediaStreamTrack.applyConstraints()")}}</dt>
 <dd>Lets the application select the range of values it wants for the capabilities of a <code>MediaStreamTrack</code>.</dd>
 <dt>{{domxref("MediaStreamTrack.getSettings", "MediaStreamTrack.getSettings()")}}</dt>
 <dd>Returns a {{domxref("MediaTrackSettings")}} object containing&nbsp;the state of the constrainable properties for the current <code>MediaStreamTrack</code>.</dd>
 <dt>{{domxref("MediaStreamTrack.getCapabilities()")}}</dt>
 <dd>Returns the a list of constrainable properties for&nbsp;the source that the current <code>MediaStreamTrack</code> represents.</dd>
 <dt>{{domxref("MediaStreamTrack.clone()")}}</dt>
 <dd>Returns a duplicate of the <code>MediaStreamTrack</code>.</dd>
 <dt>{{domxref("MediaStreamTrack.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>{{CompatVersionUnknown}}</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, enabled, muted</code>, <code>onmute</code>, <code>onunmute</code>, <code>readyState</code>, <code>onended</code>, <code>getSources(), clone()</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>remote</code></td>
   <td>{{CompatChrome(48.0)}}</td>
   <td>{{CompatUnknown}}</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>{{CompatUnknown}}</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>{{CompatVersionUnknown}}</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>{{CompatGeckoDesktop(34)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>kind, id, label, enabled, muted</code>, <code>onmute</code>, <code>onunmute</code>, <code>readyState</code>, <code>onended</code>,&nbsp;<code>getSources(), clone()</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>remote</code></td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(48.0)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</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>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(52.0)}}</td>
  </tr>
 </tbody>
</table>
</div>

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

<ul>
 <li><a href="/en-US/docs/WebRTC/MediaStream_API" title="/en-US/docs/WebRTC/MediaStream_API">Using the MediaStream API</a></li>
</ul>