AudioContext.createMediaElementSource() — Methode · JavaScript-Referenz

Signatur

AudioContext.prototype.createMediaElementSource(mediaElement)

Beschreibung

Mit createMediaElementSource() bindest du ein vorhandenes HTMLMediaElement (<audio> oder <video>) als Quelle in einen AudioContext ein. Der Rückgabewert ist ein MediaElementAudioSourceNode, den du mit weiteren Knoten verbindest, z. B. mit GainNode, BiquadFilterNode oder AnalyserNode.

Die Methode eignet sich besonders, wenn das Medienelement weiter die Wiedergabe steuern soll (Play/Pause, Spulen, Streaming, Pufferung durch den Browser) und du trotzdem den Ton bearbeiten oder analysieren willst, etwa für Equalizer, Visualisierungen oder Lautstärkeregelung über 1,0 hinaus.

Wichtig: Sobald das Element an den Kontext gebunden ist, geht sein Ton ausschließlich durch den Audiograph. Wenn du den Knoten nicht (direkt oder indirekt) mit audioContext.destination verbindest, bleibt es stumm. Wiedergabesteuerung und Zeitposition laufen weiter über das Medienelement.

Parameter

Name	Typ	Default	Beschreibung
$mediaElement Pflicht	HTMLMediaElement		Das `<audio>`- oder `<video>`-Element, dessen Ton in den Audiograph geleitet werden soll.

Rückgabewert

Typ

MediaElementAudioSourceNode

Beschreibung

Ein neuer Quellknoten ohne Eingang und mit einem Ausgang, der den Ton des Medienelements liefert.

Beispiele

Lautstärke eines Audio-Elements per GainNode verstärken

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

const source = ctx.createMediaElementSource(audio);
const gain = ctx.createGain();
gain.gain.value = 2; // doppelte Lautstärke

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

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

Frequenzanalyse für eine Visualisierung

const video = document.querySelector('video');
const ctx = new AudioContext();
const source = ctx.createMediaElementSource(video);
const analyser = ctx.createAnalyser();
analyser.fftSize = 256;

source.connect(analyser);
analyser.connect(ctx.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.querySelector('#level').style.width = `${avg}%`;
  requestAnimationFrame(draw);
};

video.addEventListener('play', () => {
  ctx.resume();
  draw();
}, { once: true });

Quellknoten nur einmal pro Element erzeugen

const sources = new WeakMap();
const ctx = new AudioContext();

const getSource = (el) => {
  if (!sources.has(el)) {
    sources.set(el, ctx.createMediaElementSource(el));
  }
  return sources.get(el);
};

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

true

// Wichtig · Fallstricke

Nur einmal pro Element: Ein Medienelement kann nur mit einem einzigen MediaElementAudioSourceNode verbunden werden. Rufst du die Methode ein zweites Mal für dasselbe Element auf, wird eine InvalidStateError-DOMException geworfen. Speichere den Knoten also zwischen, z. B. in einer WeakMap.
Stummschaltung: Ohne Verbindung zu ctx.destination ist das Element nicht mehr zu hören.
CORS: Kommen die Medien von einer fremden Herkunft ohne passende CORS-Header, liefert der Knoten nur Stille (die Ausgabe wird aus Sicherheitsgründen genullt). Setze crossorigin="anonymous" am Element und sorge serverseitig für Access-Control-Allow-Origin.
Autoplay-Richtlinien: Ein AudioContext startet oft im Zustand suspended. Rufe ctx.resume() in einem Handler für eine Benutzeraktion auf.
Die Lautstärke des Elements (element.volume, muted) wirkt weiterhin vor dem Audiograph.
Die Methode gibt es nur an AudioContext, nicht an OfflineAudioContext. Alternativ kannst du den Konstruktor new MediaElementAudioSourceNode(ctx, { mediaElement }) verwenden.

Siehe auch

AudioContext.createMediaStreamSource() AudioContext.createMediaStreamTrackSource() AudioContext.createMediaStreamDestination() AudioContext.getOutputTimestamp() AudioContext.resume()