new AudioContext() — Methode · JavaScript-Referenz

Signatur

new AudioContext(options)

Beschreibung

Der Konstruktor new AudioContext() erzeugt den zentralen Einstiegspunkt der Web Audio API. Der Kontext verwaltet einen Graphen aus AudioNode-Knoten (Quellen, Effekte, Analysatoren) und leitet das Ergebnis an context.destination weiter, also an die Lautsprecher bzw. das gewählte Ausgabegerät.

Einsetzen solltest du ihn, wenn du Töne synthetisieren (z. B. mit OscillatorNode), Audiodateien dekodieren und abspielen, Mikrofonsignale verarbeiten oder Audiodaten visualisieren möchtest (AnalyserNode). In der Regel reicht ein einziger Kontext pro Seite – alle Knoten sollten in diesem Kontext erzeugt werden.

Über das optionale options-Objekt kannst du die Latenz (latencyHint), die Abtastrate (sampleRate) und in neueren Browsern das Ausgabegerät (sinkId) festlegen. Wichtig: Wegen der Autoplay-Richtlinien der Browser startet ein Kontext, der ohne Nutzerinteraktion erzeugt wurde, meist im Zustand "suspended" und muss per resume() nach einer Nutzergeste (Klick, Tastendruck) gestartet werden.

Parameter

Name	Typ	Default	Beschreibung
$options	AudioContextOptions	{}	Konfigurationsobjekt mit den unten beschriebenen optionalen Eigenschaften.
$options.latencyHint	"interactive" \| "balanced" \| "playback" \| number	"interactive"	Gewünschte Latenz: `"interactive"` (möglichst gering, z. B. für Spiele/Instrumente), `"balanced"`, `"playback"` (stromsparend, für reine Wiedergabe) oder eine Latenz in Sekunden.
$options.sampleRate	number	Abtastrate des Ausgabegeräts	Abtastrate in Hz (z. B. `44100` oder `48000`). Wird eine nicht unterstützte Rate angegeben, wirft der Konstruktor einen `NotSupportedError`.
$options.sinkId	string \| { type: "none" }	"" (Standardausgabe)	ID des Audio-Ausgabegeräts (aus `navigator.mediaDevices.enumerateDevices()`) oder `{ type: "none" }` für Verarbeitung ohne hörbare Ausgabe. Noch nicht in allen Browsern verfügbar.

Rückgabewert

Typ

AudioContext

Beschreibung

Ein neues AudioContext-Objekt. Sein state ist "running" oder – bei fehlender Nutzerinteraktion – "suspended".

Beispiele

Kontext per Klick starten und Ton erzeugen

const button = document.querySelector('#play');
let ctx;

button.addEventListener('click', async () => {
  // Kontext erst nach Nutzergeste erzeugen (Autoplay-Richtlinie)
  ctx ??= new AudioContext();
  if (ctx.state === 'suspended') await ctx.resume();

  const osc = ctx.createOscillator();
  const gain = ctx.createGain();
  osc.type = 'sine';
  osc.frequency.value = 440; // Kammerton A
  gain.gain.setValueAtTime(0.2, ctx.currentTime);
  gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 1);

  osc.connect(gain).connect(ctx.destination);
  osc.start();
  osc.stop(ctx.currentTime + 1);
  console.log(ctx.state, ctx.sampleRate);
});

running 48000

Optionen: Latenz und Abtastrate festlegen

const ctx = new AudioContext({
  latencyHint: 'playback',
  sampleRate: 44100
});

console.log(ctx.sampleRate);
console.log(typeof ctx.baseLatency);

44100 number

Audiodatei laden, dekodieren und abspielen

const ctx = new AudioContext();

const playSound = async (url) => {
  const response = await fetch(url);
  const arrayBuffer = await response.arrayBuffer();
  const audioBuffer = await ctx.decodeAudioData(arrayBuffer);

  const source = ctx.createBufferSource();
  source.buffer = audioBuffer;
  source.connect(ctx.destination);
  await ctx.resume();
  source.start();
  console.log(`Dauer: ${audioBuffer.duration.toFixed(2)} s`);
};

document.querySelector('#sfx').addEventListener('click', () => playSound('/sounds/klick.mp3'));

Dauer: 0.35 s

Kontext sauber schließen

const ctx = new AudioContext();

const cleanup = async () => {
  await ctx.close(); // gibt Hardware-Ressourcen frei
  console.log(ctx.state);
};

window.addEventListener('pagehide', cleanup);

closed

// Wichtig · Fallstricke

Autoplay-Richtlinie: Chrome, Safari und Firefox starten einen ohne Nutzergeste erzeugten Kontext im Zustand "suspended". Rufe ctx.resume() in einem Klick- oder Tasten-Handler auf, sonst bleibt es still.
Nur ein Kontext: Browser begrenzen die Anzahl gleichzeitiger Kontexte (Chrome früher ca. 6). Erzeuge nicht bei jedem Klick einen neuen Kontext, sondern verwende ihn wieder und schließe nicht mehr benötigte mit close().
Knoten sind kontextgebunden: Ein AudioNode aus einem Kontext kann nicht mit Knoten eines anderen Kontexts verbunden werden (InvalidAccessError).
Kompatibilität: Ältere Safari-Versionen (vor 14.1) kennen nur webkitAudioContext; Fallback: const Ctx = window.AudioContext || window.webkitAudioContext;. Die Option sinkId ist derzeit nur in Chromium-Browsern verfügbar.
Fehler: Eine nicht unterstützte sampleRate führt zu NotSupportedError. Die tatsächliche Latenz kann vom latencyHint abweichen – prüfe baseLatency und outputLatency.
Für Offline-Rendering (z. B. Export in eine Datei, schneller als Echtzeit) verwende stattdessen OfflineAudioContext.

Siehe auch

new EditContext() new AudioBuffer() new AudioData() new AudioDecoder() new AudioEncoder()