new MediaElementAudioSourceNode() — Methode · JavaScript-Referenz

Signatur

new MediaElementAudioSourceNode(context, options)

Beschreibung

Der Konstruktor MediaElementAudioSourceNode() erzeugt einen Quellknoten, der ein bestehendes HTMLMediaElement (also <audio> oder <video>) mit einem AudioContext verbindet. Der Ton des Elements wird dann nicht mehr direkt ausgegeben, sondern durch den Audio-Graphen geleitet. Dort kannst du ihn mit Filtern, Verstärkung (GainNode), Panning oder Analyse (AnalyserNode) bearbeiten.

Der Konstruktor macht dasselbe wie die ältere Fabrikmethode AudioContext.createMediaElementSource(), nimmt die Optionen aber als Objekt entgegen und passt damit zu den übrigen Knoten-Konstruktoren der Web Audio API. Der Knoten hat keine Eingänge und genau einen Ausgang. Die Anzahl der Kanäle richtet sich nach dem Medium des Elements.

Typische Einsatzfälle sind Audio-Visualisierungen (Spektrum, Wellenform), Equalizer für Musik- oder Podcast-Player, Lautstärkeanhebung über 100 % hinaus oder räumlicher Klang bei Videos. Wiedergabe, Pausieren und Spulen steuerst du weiter über das Medienelement selbst (play(), pause(), currentTime).

Wichtig: Der Knoten muss mit einem Ziel verbunden sein (z. B. context.destination), sonst ist nichts zu hören. Sobald ein Element an einen Quellknoten gebunden ist, läuft seine Ausgabe nur noch über den Graphen.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	AudioContext		Der `AudioContext`, zu dem der Knoten gehört. Ein `OfflineAudioContext` ist nicht erlaubt.
$options Pflicht	MediaElementAudioSourceOptions		Objekt mit der Pflicht-Eigenschaft `mediaElement` (`HTMLMediaElement`): das `<audio>`- oder `<video>`-Element, dessen Ton in den Graphen eingespeist wird.

Rückgabewert

Typ

MediaElementAudioSourceNode

Beschreibung

Eine neue Instanz von MediaElementAudioSourceNode. Über die Eigenschaft mediaElement kommst du wieder an das verbundene Element.

Beispiele

Audio-Element über einen GainNode lauter machen

const audio = document.querySelector('#player');
const ctx = new AudioContext();

const source = new MediaElementAudioSourceNode(ctx, { mediaElement: audio });
const gain = new GainNode(ctx, { gain: 1.8 }); // 180 % Lautstärke

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

document.querySelector('#play').addEventListener('click', async () => {
  // Autoplay-Richtlinie: Kontext erst nach Nutzeraktion fortsetzen
  if (ctx.state === 'suspended') await ctx.resume();
  await audio.play();
});

Spektrum-Analyse für eine Visualisierung

const audio = new Audio('musik.mp3');
audio.crossOrigin = 'anonymous';

const ctx = new AudioContext();
const source = new MediaElementAudioSourceNode(ctx, { mediaElement: audio });
const analyser = new AnalyserNode(ctx, { fftSize: 256 });

source.connect(analyser);
analyser.connect(ctx.destination);

const data = new Uint8Array(analyser.frequencyBinCount);

const draw = () => {
  analyser.getByteFrequencyData(data);
  const avg = data.reduce((a, b) => a + b, 0) / data.length;
  console.log('Mittlerer Pegel:', avg.toFixed(1));
  requestAnimationFrame(draw);
};

document.body.addEventListener('click', async () => {
  await ctx.resume();
  await audio.play();
  draw();
}, { once: true });

Mittlerer Pegel: 87.4 Mittlerer Pegel: 91.2 ...

Einfacher Tiefen-Equalizer für ein Video

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

const source = new MediaElementAudioSourceNode(ctx, { mediaElement: video });
const bass = new BiquadFilterNode(ctx, {
  type: 'lowshelf',
  frequency: 200,
  gain: 8 // +8 dB Bass
});

source.connect(bass).connect(ctx.destination);

console.log(source.mediaElement === video);
video.addEventListener('play', () => ctx.resume());

true

// Wichtig · Fallstricke

Nur einmal pro Element: Ein Medienelement lässt sich nur an einen Quellknoten binden. Ein zweiter Aufruf mit demselben Element wirft einen InvalidStateError. Speichere den Knoten also und verwende ihn wieder, zum Beispiel in React-Komponenten, die mehrfach gerendert werden.
Keine Ausgabe ohne connect(): Nach dem Binden hört man das Element nur noch, wenn der Knoten (direkt oder über andere Knoten) mit ctx.destination verbunden ist.
CORS: Stammt das Medium von einer fremden Herkunft und fehlen crossOrigin=\"anonymous\" oder passende CORS-Header, gibt der Knoten nur Stille aus. Analyser liefern dann nur Nullen.
Autoplay-Richtlinien: Ein AudioContext startet oft im Zustand suspended. Rufe ctx.resume() in einem Handler für eine Nutzeraktion auf.
OfflineAudioContext wird nicht unterstützt, dafür gibt es einen TypeError/NotSupportedError.
Kompatibilität: Der Konstruktor funktioniert in allen aktuellen Browsern. Sehr alte Browser (Safari vor 14.1) kennen nur createMediaElementSource(), das du als Rückfallebene nutzen kannst.

Siehe auch

new MediaStreamAudioSourceNode() new MediaStreamTrackAudioSourceNode() new AudioBufferSourceNode() new ConstantSourceNode() new ManagedMediaSource()