new MediaStreamAudioSourceNode() — Methode · JavaScript-Referenz

Signatur

new MediaStreamAudioSourceNode(context, options)

Beschreibung

Mit dem Konstruktor MediaStreamAudioSourceNode() binden Sie einen Live-MediaStream in die Web Audio API ein. Typische Quellen sind das Mikrofon (über navigator.mediaDevices.getUserMedia()), ein entfernter WebRTC-Teilnehmer oder ein über captureStream() gewonnener Stream eines Medien- oder Canvas-Elements. Der entstandene Knoten hat keine Eingänge und genau einen Ausgang. Sie können ihn mit Analysatoren, Filtern, Gain-Knoten oder einem MediaStreamAudioDestinationNode verbinden.

Der Konstruktor macht dasselbe wie die Fabrikmethode AudioContext.prototype.createMediaStreamSource(), nimmt die Einstellungen aber als Optionsobjekt entgegen. Das passt gut zu anderen AudioNode-Konstruktoren und macht den Code klarer lesbar.

Wichtig: Es wird nur eine Audiospur genutzt. Laut Spezifikation ist das die Spur, deren id in lexikografischer Sortierung zuerst kommt, also nicht unbedingt die Spur, die zuerst hinzugefügt wurde. Um eine bestimmte Spur gezielt zu verwenden, nehmen Sie MediaStreamTrackAudioSourceNode oder erstellen einen neuen MediaStream, der nur die gewünschte Spur enthält.

Parameter

Name	Typ	Beschreibung
$context Pflicht	AudioContext	Der `AudioContext`, zu dem der Knoten gehört. Ein `OfflineAudioContext` ist hier nicht erlaubt.
$options Pflicht	Object	Optionsobjekt mit der Pflicht-Eigenschaft `mediaStream`.
$options.mediaStream Pflicht	MediaStream	Der Stream, aus dem das Audiosignal kommt. Er muss mindestens eine Audiospur (`MediaStreamTrack` mit `kind === "audio"`) enthalten.

Rückgabewert

Typ

MediaStreamAudioSourceNode

Beschreibung

Ein neuer Quellknoten. Seine Eigenschaft mediaStream zeigt auf den übergebenen Stream.

Beispiele

Mikrofon abhören und Lautstärke regeln

const startMic = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const ctx = new AudioContext();

  const source = new MediaStreamAudioSourceNode(ctx, { mediaStream: stream });
  const gain = new GainNode(ctx, { gain: 0.5 });

  // Achtung: Kopfhörer benutzen, sonst gibt es Rückkopplungen
  source.connect(gain).connect(ctx.destination);
  console.log(source.mediaStream === stream);
};

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

true

Pegelanzeige mit AnalyserNode

const meter = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const ctx = new AudioContext();
  const source = new MediaStreamAudioSourceNode(ctx, { mediaStream: stream });
  const analyser = new AnalyserNode(ctx, { fftSize: 256 });
  source.connect(analyser); // nicht an destination: nur messen, nichts ausgeben

  const data = new Uint8Array(analyser.fftSize);
  const tick = () => {
    analyser.getByteTimeDomainData(data);
    const peak = Math.max(...data.map((v) => Math.abs(v - 128)));
    document.querySelector('#level').style.width = `${(peak / 128) * 100}%`;
    requestAnimationFrame(tick);
  };
  tick();
};

document.querySelector('#meter').addEventListener('click', meter);

Fehlerbehandlung bei Stream ohne Audiospur

const ctx = new AudioContext();
const canvasStream = document.createElement('canvas').captureStream(); // nur Video

try {
  new MediaStreamAudioSourceNode(ctx, { mediaStream: canvasStream });
} catch (err) {
  console.log(err.name);
}

InvalidStateError

Bestimmte Audiospur gezielt auswählen

const useTrack = (ctx, stream, index = 0) => {
  const track = stream.getAudioTracks()[index];
  // Neuer Stream mit genau einer Spur, damit die Auswahl eindeutig ist
  const single = new MediaStream([track]);
  return new MediaStreamAudioSourceNode(ctx, { mediaStream: single });
};

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const node = useTrack(new AudioContext(), stream);
console.log(node.numberOfInputs, node.numberOfOutputs);

0 1

// Wichtig · Fallstricke

InvalidStateError: Diesen Fehler wirft der Konstruktor, wenn der Stream keine Audiospur hat. Prüfen Sie das vorher mit stream.getAudioTracks().length.
Autoplay-Richtlinie: Wird ein AudioContext ohne Nutzerinteraktion erzeugt, startet er oft im Zustand "suspended". Rufen Sie dann in einem Klick-Handler ctx.resume() auf.
Nur eine Spur, nicht unbedingt die erste: Nach der Spezifikation wird die Spur mit der lexikografisch kleinsten id gewählt. Für eine eindeutige Auswahl nutzen Sie MediaStreamTrackAudioSourceNode.
Kein Offline-Kontext: Ein OfflineAudioContext als context führt zu einem TypeError.
Datenschutz und sichere Kontexte: getUserMedia() funktioniert nur über HTTPS bzw. localhost und nur mit Zustimmung der Nutzerin oder des Nutzers. Beenden Sie nach der Nutzung die Spuren mit track.stop(), damit die Aufnahmeanzeige ausgeht.
Cross-Origin: Stammt der Stream aus fremden Medien ohne CORS-Freigabe, gibt der Knoten nur Stille aus.
Kompatibilität: Sehr alte Browser (z. B. Safari vor 14.1) kennen den Konstruktor nicht. Verwenden Sie dort ctx.createMediaStreamSource(stream).
Rückkopplung: Wird das Mikrofonsignal direkt an ctx.destination geleitet, entsteht über Lautsprecher schnell ein Pfeifen.

Siehe auch

new MediaStreamTrackAudioSourceNode() new MediaElementAudioSourceNode() new MediaStreamAudioDestinationNode() new ConstantSourceNode() new MediaStreamEvent()