MediaElementAudioSourceNode — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaElementAudioSourceNode extends AudioNode

Beschreibung

MediaElementAudioSourceNode ist ein AudioNode ohne Eingänge und mit genau einem Ausgang. Damit leitet man den Ton eines HTMLMediaElement (also <audio> oder <video>) in einen AudioContext weiter. Dort lässt er sich mit weiteren Knoten verarbeiten, etwa mit GainNode, BiquadFilterNode oder AnalyserNode. Die Zahl der Ausgangskanäle richtet sich nach der Mediendatei.

Einen solchen Knoten erzeugt man entweder mit audioCtx.createMediaElementSource(element) oder mit dem Konstruktor new MediaElementAudioSourceNode(context, { mediaElement }). Die schreibgeschützte Eigenschaft mediaElement verweist auf das zugehörige Element.

Typische Einsatzfälle sind Audio-Visualisierungen wie Spektrum- oder Wellenformanzeigen, Equalizer, eigene Lautstärkeregler über 100 % hinaus und räumlicher Klang mit PannerNode. Die Wiedergabe steuert man weiterhin über das Medienelement selbst, also mit play(), pause() und currentTime. Der Knoten hat keine eigenen Methoden wie start().

Wichtig: Sobald das Element an einen Knoten gebunden ist, läuft sein Ton nur noch durch den Audiographen. Wenn man den Knoten nicht mit audioCtx.destination verbindet, bleibt das Element stumm.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	AudioContext		Der `AudioContext`, zu dem der Knoten gehört. Ein `OfflineAudioContext` ist hier nicht erlaubt.
$options Pflicht	{ mediaElement: HTMLMediaElement }		Optionsobjekt (nur beim Konstruktor). `mediaElement` ist das `<audio>`- oder `<video>`-Element, das als Quelle dient. Zusätzlich sind die allgemeinen `AudioNodeOptions` möglich (`channelCount`, `channelCountMode`, `channelInterpretation`).

Rückgabewert

Typ

MediaElementAudioSourceNode

Beschreibung

Ein neuer Quellknoten mit 0 Eingängen und 1 Ausgang. Die Eigenschaft mediaElement (schreibgeschützt) verweist auf das zugehörige Medienelement.

Beispiele

Audio-Element über einen GainNode verstärken

const audio = document.querySelector('audio');
const audioCtx = new AudioContext();

// Quelle erzeugen (Fabrikmethode)
const source = audioCtx.createMediaElementSource(audio);
const gain = audioCtx.createGain();
gain.gain.value = 1.5; // 150 % Lautstärke

source.connect(gain).connect(audioCtx.destination);

document.querySelector('#play').addEventListener('click', async () => {
  // AudioContext braucht eine Nutzerinteraktion
  if (audioCtx.state === 'suspended') await audioCtx.resume();
  await audio.play();
  console.log(source.mediaElement === audio);
});

true

Konstruktor-Variante mit Frequenzanalyse für eine Visualisierung

const video = document.querySelector('video');
const audioCtx = new AudioContext();

const source = new MediaElementAudioSourceNode(audioCtx, { mediaElement: video });
const analyser = new AnalyserNode(audioCtx, { fftSize: 256 });

source.connect(analyser);
analyser.connect(audioCtx.destination); // sonst ist das Video stumm

const data = new Uint8Array(analyser.frequencyBinCount);
const draw = () => {
  analyser.getByteFrequencyData(data);
  const avg = data.reduce((a, b) => a + b, 0) / data.length;
  document.title = `Pegel: ${Math.round(avg)}`;
  requestAnimationFrame(draw);
};

video.addEventListener('play', async () => {
  await audioCtx.resume();
  draw();
});

Knoten nur einmal pro Element anlegen

const sources = new WeakMap();

const getSource = (ctx, el) => {
  // Ein zweiter createMediaElementSource-Aufruf würde einen InvalidStateError werfen
  if (!sources.has(el)) {
    sources.set(el, ctx.createMediaElementSource(el));
  }
  return sources.get(el);
};

const ctx = new AudioContext();
const audio = new Audio('musik.mp3');
const a = getSource(ctx, audio);
const b = getSource(ctx, audio);
console.log(a === b);

true

// Wichtig · Fallstricke

Nur eine Quelle pro Element: Ein Medienelement lässt sich nur an einen einzigen MediaElementAudioSourceNode binden. Ein zweiter Aufruf von createMediaElementSource() für dasselbe Element wirft einen InvalidStateError. Den Knoten daher zwischenspeichern.
Stummes Element: Nach dem Binden gibt das Element keinen Ton mehr direkt aus. Der Knoten muss (über Zwischenknoten) mit destination verbunden sein.
CORS: Kommt die Mediendatei von einer fremden Quelle ohne passende CORS-Header, gibt der Knoten nur Stille aus. Das schützt vor dem Auslesen fremder Inhalte. Abhilfe: crossorigin="anonymous" am Element setzen, und der Server muss Access-Control-Allow-Origin senden.
Autoplay-Richtlinie: Ein AudioContext startet oft im Zustand suspended. resume() sollte deshalb in einem Handler für eine Nutzeraktion aufgerufen werden.
Die Lautstärke des Elements (volume, muted) wirkt sich je nach Browser vor oder nach der Übergabe an den Graphen aus. Für eine verlässliche Steuerung besser einen GainNode verwenden.
Die Web Audio API wird in allen modernen Browsern unterstützt. Der Konstruktor ist etwas neuer als die Fabrikmethode createMediaElementSource().

Siehe auch

MediaStreamAudioSourceNode MediaStreamTrackAudioSourceNode AudioScheduledSourceNode AudioBufferSourceNode ConstantSourceNode