MediaStreamTrack

BaselineWidely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

* Some parts of this feature may have varying levels of support.

TheMediaStreamTrack interface of theMedia Capture and Streams API represents a single media track within a stream; typically, these are audio or video tracks, but other track types may exist as well.

Some user agents subclass this interface to provide more precise information or functionality, such asCanvasCaptureMediaStreamTrack.

Instance properties

In addition to the properties listed below,MediaStreamTrack has constrainable properties which can be set usingapplyConstraints() and accessed usinggetConstraints() andgetSettings(). SeeCapabilities, constraints, and settings to learn how to correctly work with constrainable properties. Not doing so correctly will result in your code being unreliable.

MediaStreamTrack.contentHint

A string that may be used by the web application to provide a hint as to what type of content the track contains to guide how it should be treated by API consumers. Allowable values depend on the value of theMediaStreamTrack.kind property.

MediaStreamTrack.enabled

A Boolean whose value oftrue if the track is enabled, that is allowed to render the media source stream; orfalse 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.

Note:You can implement standard "mute" functionality by settingenabled tofalse. Themuted property refers to a condition in which there's no media because of a technical issue.

MediaStreamTrack.idRead only

Returns a string containing a unique identifier (GUID) for the track; it is generated by the browser.

MediaStreamTrack.kindRead only

Returns a string set to"audio" if the track is an audio track and to"video", if it is a video track. It doesn't change if the track is disassociated from its source.

MediaStreamTrack.labelRead only

Returns a string containing a user agent-assigned label that identifies the track source, as in"internal microphone". The string may be left empty and is empty as long as no source has been connected. When the track is disassociated from its source, the label is not changed.

MediaStreamTrack.mutedRead only

Returns a Boolean value indicating whether the track is unable to provide media data due to a technical issue.

Note:You can implement standard "mute" functionality by settingenabled tofalse, and unmute the media by setting it back totrue again.

MediaStreamTrack.readyStateRead only

Returns an enumerated string giving the status of the track. This will be one of the following values:

"live" 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 theenabled attribute.
"ended" which indicates that the input is not giving any more data and will never provide new data.

Instance methods

MediaStreamTrack.applyConstraints(): Lets the application specify the ideal and/or ranges of acceptable values for any number of the available constrainable properties of theMediaStreamTrack.
MediaStreamTrack.clone(): Returns a duplicate of theMediaStreamTrack.
MediaStreamTrack.getCapabilities(): Returns an object detailing the accepted values or value range for each constrainable property of the associatedMediaStreamTrack.
MediaStreamTrack.getConstraints(): Returns aMediaTrackConstraints object containing the currently set constraints for the track; the returned value matches the constraints last set usingapplyConstraints().
MediaStreamTrack.getSettings(): Returns aMediaTrackSettings object containing the current values of each of theMediaStreamTrack's constrainable properties.
MediaStreamTrack.stop(): Stops playing the source associated to the track, both the source and the track are disassociated. The track state is set toended.

Events

Listen to these events usingaddEventListener() or by assigning an event listener to theoneventname property of this interface:

ended: Sent when playback of the track ends (when the valuereadyState changes toended), except when the track is ended by callingMediaStreamTrack.stop.
mute: Sent to theMediaStreamTrack when the value of themuted property is changed totrue, indicating that the track is unable to provide data temporarily (such as when the network is experiencing a service malfunction).
unmute: Sent to the track when data becomes available again, ending themuted state.