MediaStreamTrackAudioSourceNode — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaStreamTrackAudioSourceNode extends AudioNode

Beschreibung

MediaStreamTrackAudioSourceNode ist ein Quellknoten der Web Audio API. Er nimmt die Audiodaten einer einzelnen MediaStreamTrack entgegen, z. B. aus navigator.mediaDevices.getUserMedia(), getDisplayMedia() oder einer WebRTC-Verbindung (RTCPeerConnection), und stellt sie im Audio-Graphen bereit. Der Knoten hat keinen Eingang (numberOfInputs = 0) und einen Ausgang. Die Anzahl der Kanäle richtet sich nach der Track.

Der Unterschied zu MediaStreamAudioSourceNode: Dieser nimmt einen ganzen MediaStream und verwendet bei mehreren Audio-Tracks die Track mit der lexikografisch kleinsten ID. Das ist oft nicht die gewünschte. MediaStreamTrackAudioSourceNode ist eindeutig, denn du gibst genau die Track an, die verarbeitet werden soll.

Erzeugt wird der Knoten entweder mit dem Konstruktor new MediaStreamTrackAudioSourceNode(context, { mediaStreamTrack }) oder mit der Fabrikmethode AudioContext.prototype.createMediaStreamTrackSource(track). Typische Anwendungen sind Pegelanzeigen, Spektrumanalyse, Effekte auf einen bestimmten Teilnehmer in Videokonferenzen oder das Mischen mehrerer Mikrofone.

Der Knoten hat außer den von AudioNode geerbten Eigenschaften und Methoden (connect(), disconnect(), context, channelCount …) keine eigenen Mitglieder.

Parameter

Name	Typ	Beschreibung
$context Pflicht	AudioContext	Der `AudioContext`, zu dem der Knoten gehören soll. Ein `OfflineAudioContext` ist nicht erlaubt.
$options Pflicht	object	Optionsobjekt (`MediaStreamTrackAudioSourceOptions`).
$options.mediaStreamTrack Pflicht	MediaStreamTrack	Die Audio-Track, die als Quelle dient. `track.kind` muss `"audio"` sein, sonst wird ein `InvalidStateError` ausgelöst.

Rückgabewert

Typ

MediaStreamTrackAudioSourceNode

Beschreibung

Ein neuer Quellknoten, den du mit connect() an weitere AudioNodes anschließen kannst.

Beispiele

Mikrofon-Track per Konstruktor einbinden und abhören

const startMonitoring = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const [track] = stream.getAudioTracks();

  const ctx = new AudioContext();
  const source = new MediaStreamTrackAudioSourceNode(ctx, {
    mediaStreamTrack: track,
  });

  // Lautstärke reduzieren, damit keine Rückkopplung entsteht
  const gain = new GainNode(ctx, { gain: 0.3 });
  source.connect(gain).connect(ctx.destination);

  console.log(source.numberOfInputs, source.numberOfOutputs);
};

document.querySelector('#start').addEventListener('click', startMonitoring);

0 1

Fabrikmethode mit Fallback für Chromium und Safari

const createTrackSource = (ctx, track) => {
  if (typeof ctx.createMediaStreamTrackSource === 'function') {
    return ctx.createMediaStreamTrackSource(track);
  }
  // Fallback: Stream mit genau dieser einen Track bauen
  return ctx.createMediaStreamSource(new MediaStream([track]));
};

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const ctx = new AudioContext();
const source = createTrackSource(ctx, stream.getAudioTracks()[0]);
console.log(source.constructor.name);

MediaStreamTrackAudioSourceNode (Firefox) bzw. MediaStreamAudioSourceNode (andere Browser)

Pegelanzeige für einen bestimmten WebRTC-Teilnehmer

const ctx = new AudioContext();
const pc = new RTCPeerConnection();

pc.addEventListener('track', ({ track }) => {
  if (track.kind !== 'audio') return;

  const source = new MediaStreamTrackAudioSourceNode(ctx, { mediaStreamTrack: track });
  const analyser = new AnalyserNode(ctx, { fftSize: 256 });
  source.connect(analyser);

  const data = new Uint8Array(analyser.frequencyBinCount);
  const tick = () => {
    analyser.getByteFrequencyData(data);
    const level = data.reduce((sum, v) => sum + v, 0) / data.length;
    console.log(`Pegel: ${level.toFixed(1)}`);
    if (track.readyState === 'live') requestAnimationFrame(tick);
  };
  tick();
});

Pegel: 42.7 (fortlaufend)

// Wichtig · Fallstricke

Browser-Kompatibilität: Konstruktor und createMediaStreamTrackSource() gibt es bislang nur in Firefox (ab 68). In Chromium-Browsern und Safari fehlen sie. Prüfe vorher, ob sie vorhanden sind, und nutze als Ersatz createMediaStreamSource(new MediaStream([track])).
Ist track.kind nicht "audio", wird ein InvalidStateError ausgelöst. Videotracks lassen sich also nicht verwenden.
Der Knoten funktioniert nur mit einem Echtzeit-AudioContext, nicht mit einem OfflineAudioContext.
Autoplay-Richtlinien: Ein AudioContext startet ohne Nutzeraktion oft im Zustand "suspended". Rufe ctx.resume() in einem Klick-Handler auf.
Wird die Track beendet (track.stop()) oder stummgeschaltet (enabled = false), gibt der Knoten Stille aus. Ein Fehler wird dabei nicht ausgelöst.
Wenn du das Mikrofon direkt an ctx.destination anschließt, kann es über die Lautsprecher zu Rückkopplungen kommen. Nutze Kopfhörer oder einen GainNode.
Datenschutz: Mikrofonzugriff braucht einen sicheren Kontext (HTTPS) und die Zustimmung der Nutzerin oder des Nutzers.

Siehe auch

MediaStreamAudioSourceNode MediaElementAudioSourceNode MediaStreamTrackProcessor MediaStreamTrackEvent MediaStreamTrackGenerator