JavaScript MediaStream addTrack() Method

What You’ll Learn

The addTrack() method of MediaStream adds a MediaStreamTrack to the stream. Learn the empty-stream pattern with new MediaStream(), building composed streams track by track, MDN’s duplicate-track rule, how active updates, and comparison with the constructor—with five examples and try-it labs.

Introduction

A MediaStream is a collection of tracks—audio, video, or both. You often get a full stream from getUserMedia() or captureStream(). When you need to assemble a stream yourself, start with new MediaStream() and call stream.addTrack(track) for each track you want.

MDN: the track argument is a MediaStreamTrack. If that track is already in the stream, addTrack() does nothing. The method returns undefined.

Understanding MediaStream.addTrack()

An instance method that inserts one MediaStreamTrack into the stream’s track set.

• Parameter — track: a MediaStreamTrack to add.
• Return value — none (undefined).
• Duplicate — if the track is already present, no effect (MDN).
• Pair with — removeTrack() to remove a track.
• Alternative — new MediaStream([trackA, trackB]) in one step.
• Baseline Widely available on MDN (since September 2017).

📝 Syntax

addTrack(track)

Parameters

Return value

None (undefined).

Typical pattern

const composed = new MediaStream();
const source = canvas.captureStream();
const videoTrack = source.getVideoTracks()[0];

composed.addTrack(videoTrack);
console.log(composed.getTracks().length);

⚖️ addTrack() vs Related Ideas

Examples Gallery

Examples follow MDN MediaStream: addTrack(). Labs use canvas.captureStream() so no camera permission is required.

const canvas = document.createElement("canvas");
const source = canvas.captureStream();
const videoTrack = source.getVideoTracks()[0];

const stream = new MediaStream();
stream.addTrack(videoTrack);

console.log(stream.getTracks().length);

1

const a = document.createElement("canvas");
const b = document.createElement("canvas");
const trackA = a.captureStream().getVideoTracks()[0];
const trackB = b.captureStream().getVideoTracks()[0];

const composed = new MediaStream();
composed.addTrack(trackA);
composed.addTrack(trackB);

console.log(composed.getTracks().length);

2

const canvas = document.createElement("canvas");
const track = canvas.captureStream().getVideoTracks()[0];
const stream = new MediaStream();

stream.addTrack(track);
stream.addTrack(track);

console.log(stream.getTracks().length);

1

const canvas = document.createElement("canvas");
const track = canvas.captureStream().getVideoTracks()[0];
const stream = new MediaStream();

console.log("before:", stream.active);
stream.addTrack(track);
console.log("after:", stream.active);

before: false
after: true

const canvas = document.createElement("canvas");
const track = canvas.captureStream().getVideoTracks()[0];

const viaAdd = new MediaStream();
viaAdd.addTrack(track);

const viaCtor = new MediaStream([track]);

console.log(viaAdd.getTracks().length, viaCtor.getTracks().length);
console.log(viaAdd.getTracks()[0] === viaCtor.getTracks()[0]);

1 1
true

🚀 Common Use Cases

• Merge separate audio and video captures into one MediaStream.
• Add a screen-share track to an existing camera stream in WebRTC.
• Build streams dynamically as tracks become available.
• Re-wrap tracks after processing without stopping the source track.
• Test media pipelines with new MediaStream() plus manual tracks.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since September 2017) — no Deprecated / Experimental / Non-standard banner.
• Duplicate tracks — adding the same track again has no effect.
• Shared references — the track object may belong to multiple streams.
• Return value — always undefined; inspect with getTracks().
• Related learning: MediaStream(), removeTrack(), active, getUserMedia().

💡 Best Practices