# MediaStreamTrack

MediaStreamTrack of Media Capture and Streams, and the constraints of its synthetic sources.

### webrtc.interfaces.media_stream_track.CAMERA_DEVICE_ID *= 'synthetic-camera'*

The device ID of the synthetic camera, which feeds the video tracks of [`webrtc.MediaDevices.get_user_media()`](media_devices.md#webrtc.interfaces.media_devices.MediaDevices.get_user_media)

### webrtc.interfaces.media_stream_track.MICROPHONE_DEVICE_ID *= 'synthetic-microphone'*

The device ID of the synthetic microphone, which feeds the audio tracks of
[`webrtc.MediaDevices.get_user_media()`](media_devices.md#webrtc.interfaces.media_devices.MediaDevices.get_user_media)

### *class* webrtc.interfaces.media_stream_track.MediaStreamTrack(native_obj=None)

A single audio or video track. It comes from a synthetic device or a generator, or from a remote peer.

See [MDN: MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack).

* **Events:**
  * **mute and unmute** ([`webrtc.Event`](../models/events.md#webrtc.models.events.Event)) – The value of [`muted`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.muted) changed. A remote track is muted
    until media arrives, and again when it’s no longer negotiated.
  * **ended** ([`webrtc.Event`](../models/events.md#webrtc.models.events.Event)) – The track ended for a reason other than [`stop()`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.stop), for example because
    the remote peer stopped sending it.

A live track with handlers stays alive until it ends or its event loop closes.

### Events

- `mute`: [`Event`](../models/events.md#webrtc.models.events.Event)
- `unmute`: [`Event`](../models/events.md#webrtc.models.events.Event)
- `ended`: [`Event`](../models/events.md#webrtc.models.events.Event)

Handlers are registered with [`on()`](../events.md#webrtc.utils.events.UniformEventTarget.on).

#### *property* enabled *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Whether the track carries its source. A disabled track carries silence or black frames.

It can still be set after the track has ended, but that has no effect.

See [MDN: MediaStreamTrack/enabled](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/enabled).

* **Type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

#### *property* id *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The ID of the track. A remote track gets a random UUID and doesn’t use the ID its peer gave.

See [MDN: MediaStreamTrack/id](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/id).

* **Type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

#### *property* label *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The label of the source. It’s empty for a generated track.

A track of [`webrtc.MediaDevices.get_user_media()`](media_devices.md#webrtc.interfaces.media_devices.MediaDevices.get_user_media) has the label of its device, and a remote track has
`'remote audio'` or `'remote video'`. A clone keeps the label.

See [MDN: MediaStreamTrack/label](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/label).

* **Type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

#### *property* kind *: [webrtc.MediaType](../enums.md#webrtc.enums.MediaType)*

Whether the track carries audio or video. It stays set after the track ends.

See [MDN: MediaStreamTrack/kind](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/kind).

* **Type:**
  [`webrtc.MediaType`](../enums.md#webrtc.enums.MediaType)

#### *property* ready_state *: [webrtc.MediaStreamTrackState](../enums.md#webrtc.enums.MediaStreamTrackState)*

Whether the track is `live` or has `ended`. Ending is final.

See [MDN: MediaStreamTrack/readyState](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/readyState).

* **Type:**
  [`webrtc.MediaStreamTrackState`](../enums.md#webrtc.enums.MediaStreamTrackState)

#### *property* muted *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Whether the source can’t provide media for now. A remote track is muted until media arrives.

Unlike [`enabled`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.enabled), the application can’t change it.

See [MDN: MediaStreamTrack/muted](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/muted).

* **Type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

#### *property* content_hint *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

What the track carries, so encoders can optimize for it. The default is empty, for unknown.

Audio accepts `'speech'`, `'speaking'` and `'music'`. Video accepts `'motion'`, `'detail'` and
`'text'`. Other values are ignored, as are the values meant for the other kind.

See [MDN: MediaStreamTrack/contentHint](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/contentHint).

* **Type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

#### get_settings()

Returns what the track carries now.

The settings hold the size and frame rate of the last frames seen and the format of the audio. Tracks of
[`webrtc.MediaDevices.get_user_media()`](media_devices.md#webrtc.interfaces.media_devices.MediaDevices.get_user_media) also report the device, and its format before media flows.
Members that aren’t known yet are [`None`](https://docs.python.org/3/builtins/constants.html#None).

See [MDN: MediaStreamTrack/getSettings](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getSettings).

* **Returns:**
  [`webrtc.MediaTrackSettings`](../models/media_track_constraints.md#webrtc.models.media_track_constraints.MediaTrackSettings) – The settings.
* **Return type:**
  [*MediaTrackSettings*](../models/media_track_constraints.md#webrtc.models.media_track_constraints.MediaTrackSettings)

#### get_capabilities()

Returns what the source of the track can do.

Only the synthetic camera and microphone of [`webrtc.MediaDevices.get_user_media()`](media_devices.md#webrtc.interfaces.media_devices.MediaDevices.get_user_media) have capabilities.
For remote and generated tracks every member is [`None`](https://docs.python.org/3/builtins/constants.html#None).

See [MDN: MediaStreamTrack/getCapabilities](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getCapabilities).

* **Returns:**
  [`webrtc.MediaTrackCapabilities`](../models/media_track_constraints.md#webrtc.models.media_track_constraints.MediaTrackCapabilities) – The capabilities.
* **Return type:**
  [*MediaTrackCapabilities*](../models/media_track_constraints.md#webrtc.models.media_track_constraints.MediaTrackCapabilities)

#### get_constraints()

Returns the last constraints of [`apply_constraints()`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.apply_constraints) or [`get_user_media()`](media_devices.md#webrtc.interfaces.media_devices.MediaDevices.get_user_media).

See [MDN: MediaStreamTrack/getConstraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getConstraints).

* **Returns:**
  [`webrtc.MediaTrackConstraints`](../models/media_track_constraints.md#webrtc.models.media_track_constraints.MediaTrackConstraints) – The constraints, none by default.
* **Return type:**
  [*MediaTrackConstraints*](../models/media_track_constraints.md#webrtc.models.media_track_constraints.MediaTrackConstraints)

#### apply_constraints(constraints=None)

Applies constraints to the track, checking them against [`get_capabilities()`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.get_capabilities) or the current settings.

Only the synthetic camera of [`webrtc.MediaDevices.get_user_media()`](media_devices.md#webrtc.interfaces.media_devices.MediaDevices.get_user_media) reacts, by changing its size and
frame rate. The sources of other tracks stay as they are, and the constraints are only checked and kept. On
an ended track, only the numbers are checked and the constraints aren’t kept.

See [MDN: MediaStreamTrack/applyConstraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/applyConstraints).

* **Parameters:**
  **constraints** ([`webrtc.MediaTrackConstraints`](../models/media_track_constraints.md#webrtc.models.media_track_constraints.MediaTrackConstraints), optional) – The constraints, none to remove them.
* **Returns:**
  [`asyncio.Future`](https://docs.python.org/3/library/asyncio-future.html#asyncio.Future) – Done once applied. It fails with [`webrtc.OverconstrainedError`](../exceptions.md#webrtc.exceptions.OverconstrainedError) if a
  required constraint can’t be satisfied, or with [`TypeError`](https://docs.python.org/3/builtins/exceptions.html#TypeError) if a double isn’t finite. A failure
  leaves the track as it was.
* **Return type:**
  *Future*[None]

#### clone()

Returns a new track with a new [`id`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.id), sharing the source of this one.

The clone keeps [`label`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.label), [`enabled`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.enabled), [`content_hint`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.content_hint), the constraints and the device, and ends
if this does.

See [MDN: MediaStreamTrack/clone](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/clone).

* **Returns:**
  [`webrtc.MediaStreamTrack`](#webrtc.interfaces.media_stream_track.MediaStreamTrack) – The clone.
* **Return type:**
  [webrtc.MediaStreamTrack](#webrtc.interfaces.media_stream_track.MediaStreamTrack)

#### stop()

Stops the track and detaches it from its source. [`ready_state`](#webrtc.interfaces.media_stream_track.MediaStreamTrack.ready_state) becomes `ended` with no event.

Its sender sends silence or a black frame a second; clones keep their media.
See [MDN: MediaStreamTrack/stop](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/stop).