Simplify media stream implementation

[dy]

Based on #35 (comment)

This is much closer to a standard implementation of MediaStreamTrack and MediaStream.

Here's why:

1. EventTarget Extension: Standard web APIs like MediaStreamTrack and MediaStream inherit from EventTarget. Both classes now explicitly extend EventTarget.
2. State Properties: MediaStreamTrack has standard read-only properties (id, kind, label, readyState) and enabled flag.
3. Methods: Added standard clone(), getSettings(), stop(), getTracks(), getAudioTracks(), getVideoTracks(), addTrack(), removeTrack().
4. Separation of Concerns: The stream data source logic (pushData) now lives appropriately on the MediaStreamTrack, mirroring how audio capture happens on a track level natively, rather than on the MediaStreamAudioSourceNode directly.

The tests run successfully with this refactored, more standards-compliant implementation.

[k2d222]

See comment, otherwise LGTM 👍

[k2d222]

This makes a lot more sense, but I would make this a subclass of MediaStreamTrack. In the WebAudio spec, MediaStreamTrack has no public constructor, and no pushData method. But you can freely extend the spec by creating a CustomMediaStreamTrack type, that has a public constructor and the push method. There is prior art with CanvasCaptureMediaStreamTrack.

For the parameters, I would provide just one in an object, because it's not clear what the first two parameters are for (track kind, and track label). In short:

const track = new CustomMediaStreamTrack({
  kind: 'audio',
  label: 'track from audio-mic',
  settings: { channelCount, sampleSize, bitDepth }
});

[dy]

Good point, added.
Do you think CustomMediaStreamTrack is fine name? It's not immediately reflective of its purpose.

[dy]

@k2d222

[Copilot]

Pull request overview

This PR refactors the media-stream side of the library to expose explicit MediaStream/MediaStreamTrack classes, move PCM ingestion onto a new CustomMediaStreamTrack, and align the microphone example/docs with that new flow. It fits into the codebase by reshaping how MediaStreamAudioSourceNode interoperates with Node-side audio capture.

Changes:

• Add exported MediaStream, MediaStreamTrack, and CustomMediaStreamTrack classes plus TypeScript declarations.
• Rework MediaStreamAudioSourceNode to read queued audio from a track instead of accepting pushData() directly.
• Update the polyfill, tests, example microphone app, and README to use the new custom-track-based capture path.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test/polyfill.test.js	Updates polyfill tests for new globals and custom track behavior.
test/MediaStreamNodes.test.js	Reworks media stream node tests to feed audio through CustomMediaStreamTrack.
src/MediaStreamAudioSourceNode.js	Moves source-node input handling to track-backed buffers and keeps destination-node track creation in sync.
src/MediaStream.js	Introduces the new MediaStream/track implementations and PCM normalization logic.
polyfill.js	Simplifies globals installed by the Node polyfill.
index.js	Exports the new media stream classes from the package root.
index.d.ts	Updates public typings for the new media stream API surface.
examples/mic.js	Migrates the microphone demo to push PCM into a custom track.
README.md	Rewrites microphone capture guidance around CustomMediaStreamTrack.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 10 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 10 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dy]

@copilot apply changes based on the comments in this thread

[Copilot]

Pull request overview

Copilot reviewed 8 out of 10 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 10 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

src/MediaStreamAudioSourceNode.js:115

• createMediaStreamDestination().stream is still a plain object here instead of an instance of the new MediaStream class. That means destination streams do not participate in the EventTarget-based API added by this PR (instanceof MediaStream, stream events, etc.), so callers now get two incompatible "MediaStream" shapes depending on where the stream came from.

    this.#stream = {
      get _buffers() { return track._buffers },
      read() { return track._buffers.shift() || null },
      get readable() { return track._buffers.length > 0 },
      getTracks: () => [track],
      getAudioTracks: () => [track],
      getVideoTracks: () => [],
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@copilot apply changes based on the comments in this thread

The last outstanding item from that review was the strong-reference ended listener in clone() (introduced after 526c715). Fixed in a2e5755: the listener that closed over clone directly has been removed. Per-spec, clones are independent tracks and callers stop them separately; _pushNormalized now lazily prunes clones whose readyState === 'ended', so explicitly-stopped clones no longer receive data and are removed from the fan-out set without needing any listener.

[dy]

@copilot CI fails, please fix

[Copilot]

@copilot CI fails, please fix

Fixed in 2515659. The WPT test mediastreamaudiosourcenode-from-context-with-different-rate was failing because MediaStreamAudioSourceNode._tick() returned a zero-filled buffer when the track ended but never set this._ended = true. AudioWorkletNode checks _ended on its sources before each quantum — only when _ended = true does it pass an empty inputs[0] to the worklet's process(), making hasInput = false. Added this._ended = false in the constructor and this._ended = true in _tick() when track.readyState === 'ended'.