Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท Media Capture and Streams

MediaStream and Tracks

Understand MediaStream and MediaStreamTrack: ids, kinds, readyState, enabled versus muted versus stopped, cloning, adding and removing tracks, and track events.

Two objects sit between capture and the network: the MediaStreamTrack (one source of audio or video) and the MediaStream (a named group of tracks). Most WebRTC bugs about "why is there no sound" or "why won't it turn off" come from confusing the many ways a track can be switched off. This lesson makes those differences crisp.

All examples use synthetic sources (a canvas for video, Web Audio for sound), so they run in the sandboxed preview exactly like a real camera would.

Tracks and streams

A track has one kind ("audio" or "video"), a unique id, a label (the device name) and a readyState. A stream is a container: it has an id, can hold any number of tracks and reports whether it is active (at least one track is live).

JavaScript
stream.getTracks();         // all tracks
stream.getAudioTracks();    // only audio
stream.getVideoTracks();    // only video
stream.getTrackById(id);
stream.addTrack(track);
stream.removeTrack(track);

Streams exist mainly to say "these tracks belong together and should be synchronised" (lip-sync between a person's voice and picture). You can put the same track into several streams, and a track belongs to the stream only as a reference; removing it from the stream does not stop it.

flowchart LR
  CAM["Camera"] --> VT["video track"]
  MIC["Microphone"] --> AT["audio track"]
  VT --> S1["MediaStream A (preview)"]
  AT --> S1
  VT --> S2["MediaStream B (sent to peer)"]

One track can be a member of several streams; stopping the track affects all of them.

Three ways a track can be "off"

Property or call Who controls it Effect Reversible?
track.enabled = false You Video shows black frames, audio sends silence. The device stays open (light on). Yes: set it back to true
track.muted (read-only) The browser or source The source is not delivering data right now (device unplugged, network, the OS muted it). Fires mute / unmute. By the source
track.stop() You Releases the device; readyState becomes "ended". No: capture again

For a mute button, set enabled = false on the audio track: it is instant, free and reversible. For a camera off button that must switch the light off, call stop() and capture again later (or use replaceTrack(null) to stop sending but keep the track).

enabled, muted and stop

That last line is a classic trap: calling track.stop() yourself does not dispatch ended. The event is for the outside world ending the track, such as a screen share being stopped from the browser's own "Stop sharing" bar. If you need to update your UI after your own stop(), do it in the same function.

Track events

Event Meaning
mute The source stopped providing data (not your doing)
unmute Data is flowing again
ended The source is gone for good (device removed, share stopped)

For remote tracks (received over a peer connection) muted is true until the first packets arrive, and you will often see mute and unmute fire when the network stalls.

Cloning

track.clone() creates a second track with the same source and settings but an independent life cycle: you can disable or stop one without affecting the other. stream.clone() clones every track.

Independent clones

Why clone? A typical case is showing the camera in a small preview with filters while sending a different constraint-adjusted copy, or giving two peer connections independent control over one camera. Each clone must be stopped for the hardware to be released.

Building streams by hand

You can assemble a stream from tracks that came from different places, which is how you send "screen video plus microphone audio" in a single stream:

JavaScript
const screen = await navigator.mediaDevices.getDisplayMedia({ video: true });
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
const combined = new MediaStream([...screen.getVideoTracks(), ...mic.getAudioTracks()]);

new MediaStream() accepts an array of tracks, another stream (which copies its tracks) or nothing. Adding a track to a stream that is attached to a <video> updates the element automatically.

Inspecting a stream you received

When a remote peer's media arrives, the track event gives you the track and the streams it belongs to. Typical code:

JavaScript
pc.ontrack = (event) => {
  const [remoteStream] = event.streams;       // the stream the sender associated it with
  videoElement.srcObject = remoteStream;
};

event.streams can be empty if the sender called addTrack(track) without a stream; then build one yourself with new MediaStream([event.track]). We do this in sending video over a connection.

Common mistakes

  • Using enabled = false for "camera off": the light stays on and users do not trust it.
  • Waiting for ended after stop(): it will never fire.
  • Stopping only the stream's video track and leaving the audio running; call getTracks().forEach(stop).
  • Reading stream.active to decide whether the call is live: it only reflects local tracks.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which setting silences a microphone instantly and reversibly while keeping the device open?

    enabled = false sends silence (or black video) without releasing the device. muted is read-only and set by the source.
  2. 2. What does track.muted === true tell you?

    muted is controlled by the source or browser, for example when a device is unplugged or the network stalls for remote tracks.
  3. 3. When does a track's ended event fire?

    stop() does not dispatch ended. The event signals the source ending (device removed, share stopped from the browser UI).
  4. 4. What does track.clone() give you?

    A clone has its own id, enabled flag and stop state, but uses the same underlying source.

Summary

  • A MediaStreamTrack is one source; a MediaStream groups tracks that belong together.
  • enabled is yours (reversible), muted is the source's (read-only), stop() releases the device (irreversible) and does not fire ended.
  • clone() creates independent copies; stop every clone to release hardware.
  • Build custom streams with new MediaStream([tracks]).

Next: Capturing from Canvas and Web Audio