JavaScript MediaStream addtrack Event

What You’ll Learn

The addtrack event on MediaStream fires when a new MediaStreamTrack is added to the stream. Learn MDN’s addEventListener and onaddtrack patterns, the MediaStreamTrackEvent.track property, pairing with addTrack(), and how this differs from the removetrack event—with five examples and try-it labs.

Introduction

Streams change over time—tracks arrive from WebRTC peers, screen shares start, or you compose streams manually with addTrack(). The addtrack event tells you when a new track joined the stream so you can update UI, attach to a <video> element, or log diagnostics.

MDN: the event is a MediaStreamTrackEvent with a read-only track property. It is not cancelable and does not bubble. Listen with stream.addEventListener("addtrack", handler) or stream.onaddtrack = handler.

Understanding the addtrack Event

An instance event on MediaStream that signals a track was added to the stream’s track set.

• Event name — "addtrack" (lowercase, one word).
• Event type — MediaStreamTrackEvent (inherits Event).
• Key property — event.track: the MediaStreamTrack that was added.
• Cancelable — no (MDN).
• Bubbles — no (MDN).
• Common trigger — addTrack() on the same stream.
• Baseline Widely available on MDN (since September 2017).

📝 Syntax

stream.addEventListener("addtrack", (event) => { })

stream.onaddtrack = (event) => { }

Event object

MediaStreamTrackEvent — use event.track to access the added MediaStreamTrack (read-only).

Typical pattern (MDN idea)

const stream = new MediaStream();

stream.addEventListener("addtrack", (event) => {
  console.log(`New ${event.track.kind} track added`);
});

⚖️ addtrack vs Related Ideas

Examples Gallery

Examples follow MDN MediaStream: addtrack event. Demos use new MediaStream() plus addTrack() to trigger the event predictably.

const stream = new MediaStream();

stream.addEventListener("addtrack", (event) => {
  console.log(`New ${event.track.kind} track added`);
});

// Later: stream.addTrack(someTrack) fires the event

New video track added

const stream = new MediaStream();

stream.onaddtrack = (event) => {
  console.log(`New ${event.track.kind} track added`);
};

New audio track added

const composed = new MediaStream();
const log = [];

composed.addEventListener("addtrack", (event) => {
  log.push(event.track.kind);
});

navigator.mediaDevices
  .getUserMedia({ video: true })
  .then((source) => {
    composed.addTrack(source.getVideoTracks()[0]);
    console.log(log);
  });

["video"]

const composed = new MediaStream();
const kinds = [];

composed.addEventListener("addtrack", (event) => {
  kinds.push(event.track.kind);
});

navigator.mediaDevices
  .getUserMedia({ audio: true, video: true })
  .then((source) => {
    composed.addTrack(source.getAudioTracks()[0]);
    composed.addTrack(source.getVideoTracks()[0]);
    console.log(kinds.join(", "));
  });

audio, video

const composed = new MediaStream();
let addCount = 0;

composed.addEventListener("addtrack", () => {
  addCount += 1;
});

navigator.mediaDevices
  .getUserMedia({ audio: true, video: true })
  .then((source) => {
    source.getTracks().forEach((track) => {
      composed.addTrack(track);
    });
    console.log(addCount, composed.getTracks().length);
  });

2 2

🚀 Common Use Cases

• Update UI when a WebRTC peer adds a new audio or video track.
• Log track additions for debugging composed streams.
• Attach new tracks to a recorder or processor when they arrive.
• Sync stream state with getTracks() after dynamic changes.
• Pair with removetrack for full add/remove lifecycle handling.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since September 2017) — no Deprecated / Experimental / Non-standard banner.
• Not cancelable — you cannot prevent a track from being added via this event.
• Does not bubble — listen on the MediaStream itself.
• Register early — attach the listener before addTrack() to avoid missing events.
• vs addTrack() — the method adds; the event notifies after addition.
• Related learning: removetrack, addTrack(), removeTrack(), active / inactive.

💡 Best Practices