JavaScript MediaStream Constructor

What You’ll Learn

The MediaStream() constructor returns a newly created MediaStream—a collection of MediaStreamTrack objects. Learn the three MDN forms (new MediaStream(), new MediaStream(stream), new MediaStream(tracks)), how shared tracks work, and when to use the constructor vs getUserMedia()—with five examples and try-it labs.

Introduction

Most beginners meet MediaStream through navigator.mediaDevices.getUserMedia(), which returns a live camera or microphone stream. The browser can also build streams in JavaScript with new MediaStream()—handy when you compose tracks manually, clone an existing stream, or start with an empty container and add tracks later.

MDN: if you pass parameters, those tracks are added to the new stream. Otherwise the stream has no tracks. When you pass another MediaStream, its tracks are shared—they are not removed from the original stream.

Understanding the MediaStream() Constructor

A Web API constructor that returns a new MediaStream object—either empty or containing the tracks you provide.

• No arguments — empty stream, zero tracks.
• stream — optional; copies track references from another MediaStream (shared).
• tracks — optional array of MediaStreamTrack objects to add.
• Return value — a newly created MediaStream (with its own id).
• Not the same as — getUserMedia(), which requests hardware and user permission.
• Baseline Widely available on MDN (since September 2017).

📝 Syntax

new MediaStream()
new MediaStream(stream)
new MediaStream(tracks)

Parameters

Return value

A newly-created MediaStream object.

Empty stream

const empty = new MediaStream();
console.log(empty.getTracks().length); // 0

From track array

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

From another stream

const original = canvas.captureStream();
const clone = new MediaStream(original);
// original still has its tracks — they are shared

⚖️ MediaStream() vs Related Ideas

Examples Gallery

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

const stream = new MediaStream();

console.log(stream instanceof MediaStream);
console.log(stream.getTracks().length);
console.log(stream.active);

true
0
false

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

const stream = new MediaStream([videoTrack]);

console.log(stream.getTracks().length);
console.log(stream.getVideoTracks()[0] === videoTrack);

1
true

const canvas = document.createElement("canvas");
const original = canvas.captureStream();
const clone = new MediaStream(original);

console.log(original.getTracks().length);
console.log(clone.getTracks().length);
console.log(original.id === clone.id);

1
1
false

const canvas = document.createElement("canvas");
const a = canvas.captureStream();
const b = new MediaStream(a);

a.getTracks()[0].stop();

console.log(a.active);
console.log(b.active);

false
false

const supported = typeof MediaStream === "function";

if (supported) {
  const stream = new MediaStream();
  console.log("ok", stream.getTracks().length);
} else {
  console.log("MediaStream not available");
}

ok 0

🚀 Common Use Cases

• Start with new MediaStream() and add tracks with addTrack() later.
• Compose custom streams from selected audio and video tracks.
• Clone track references for WebRTC or recording pipelines.
• Unit-test media code without opening real cameras.
• Split one capture into multiple stream objects for different consumers.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since September 2017) — no Deprecated / Experimental / Non-standard banner.
• Shared tracks — new MediaStream(other) does not move tracks off the source stream.
• Empty stream — active is false until a live track is added.
• vs getUserMedia — constructor does not request permission or open hardware by itself.
• Related learning: MediaStream.active, MediaStream.id, getUserMedia(), addTrack().

💡 Best Practices