new AudioBufferSourceNode() — Methode · JavaScript-Referenz

Signatur

new AudioBufferSourceNode(context, options)

Beschreibung

Der Konstruktor AudioBufferSourceNode() erzeugt eine Audioquelle für die Web Audio API, die Audiodaten aus einem AudioBuffer abspielt. Das ist ideal für kurze, häufig genutzte Klänge wie Soundeffekte in Spielen, UI-Klicks oder Samples in Musik-Apps, weil die Daten bereits dekodiert im Arbeitsspeicher liegen und ohne Verzögerung abgespielt werden.

Anders als bei der älteren Fabrikmethode BaseAudioContext.createBufferSource() kannst du hier alle Einstellungen direkt über das options-Objekt übergeben, zum Beispiel buffer, loop, playbackRate oder detune. Beide Wege liefern das gleiche Ergebnis.

Wichtig: Ein AudioBufferSourceNode ist ein Wegwerf-Objekt. start() darf nur einmal aufgerufen werden. Soll ein Klang mehrfach abgespielt werden, erzeugst du jedes Mal einen neuen Knoten. Das ist gewollt und günstig, denn der eigentliche AudioBuffer kann beliebig oft wiederverwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehören soll.
$options	object	{}	Optionales Konfigurationsobjekt mit folgenden Eigenschaften: `buffer` (`AudioBuffer\|null`, Standard `null`): abzuspielende Audiodaten. `detune` (`number`, Standard `0`): Verstimmung in Cent. `loop` (`boolean`, Standard `false`): Wiedergabe in Schleife. `loopStart` (`number`, Standard `0`): Schleifenbeginn in Sekunden. `loopEnd` (`number`, Standard `0`): Schleifenende in Sekunden (`0` = Pufferende). `playbackRate` (`number`, Standard `1`): Abspielgeschwindigkeit. Außerdem die allgemeinen `AudioNode`-Optionen `channelCount`, `channelCountMode`, `channelInterpretation`.

Rückgabewert

Typ

AudioBufferSourceNode

Beschreibung

Ein neuer, noch nicht gestarteter AudioBufferSourceNode, der mit connect() in den Audio-Graphen eingebunden und mit start() abgespielt wird.

Beispiele

Soundeffekt laden und abspielen

const ctx = new AudioContext();

const loadSound = async (url) => {
  const response = await fetch(url);
  const arrayBuffer = await response.arrayBuffer();
  return ctx.decodeAudioData(arrayBuffer);
};

const playSound = (buffer) => {
  // Für jede Wiedergabe einen neuen Knoten erzeugen
  const source = new AudioBufferSourceNode(ctx, { buffer });
  source.connect(ctx.destination);
  source.start();
  return source;
};

document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume(); // Autoplay-Sperre aufheben
  const clickBuffer = await loadSound('/sounds/click.mp3');
  playSound(clickBuffer);
});

Hintergrundschleife mit Schleifenbereich und Tempo

const ctx = new AudioContext();
const response = await fetch('/audio/loop.wav');
const buffer = await ctx.decodeAudioData(await response.arrayBuffer());

const loop = new AudioBufferSourceNode(ctx, {
  buffer,
  loop: true,
  loopStart: 1.0,   // Schleife ab Sekunde 1
  loopEnd: 3.0,     // bis Sekunde 3
  playbackRate: 1.25
});

loop.connect(ctx.destination);
loop.start(0, 1.0); // direkt bei Sekunde 1 beginnen

// Nach 10 Sekunden anhalten
loop.stop(ctx.currentTime + 10);

Weißes Rauschen synthetisch erzeugen

const ctx = new AudioContext();
const seconds = 2;
const noiseBuffer = new AudioBuffer({
  numberOfChannels: 1,
  length: ctx.sampleRate * seconds,
  sampleRate: ctx.sampleRate
});

const data = noiseBuffer.getChannelData(0);
for (let i = 0; i < data.length; i++) {
  data[i] = Math.random() * 2 - 1;
}

const noise = new AudioBufferSourceNode(ctx, { buffer: noiseBuffer });
const gain = new GainNode(ctx, { gain: 0.2 });
noise.connect(gain).connect(ctx.destination);

noise.addEventListener('ended', () => console.log('Rauschen beendet'));
noise.start();

Rauschen beendet

// Wichtig · Fallstricke

Nur einmal startbar: Ein zweiter Aufruf von start() wirft einen InvalidStateError. Für jede Wiedergabe einen neuen Knoten erzeugen – den AudioBuffer dagegen wiederverwenden.
Autoplay-Richtlinien: Browser starten einen AudioContext oft im Zustand "suspended". Rufe ctx.resume() innerhalb einer Benutzeraktion (z. B. Klick) auf.
Buffer nur einmal setzbar: Wurde buffer einmal auf einen Nicht-null-Wert gesetzt, führt eine erneute Zuweisung zu einem InvalidStateError.
Speicherbedarf: Dekodierte Audiodaten liegen unkomprimiert im Speicher (32-Bit-Float pro Sample und Kanal). Für lange Musikstücke besser MediaElementAudioSourceNode mit einem <audio>-Element verwenden.
Kompatibilität: Die Konstruktor-Syntax wird von allen aktuellen Browsern unterstützt; ältere Safari-Versionen (vor 14.1) kennen nur createBufferSource() und teils nur webkitAudioContext.
Ist loopEnd kleiner oder gleich loopStart bzw. 0, wird der gesamte Puffer als Schleife verwendet.

Siehe auch

new AudioBuffer() new ConstantSourceNode() new AudioWorkletNode() new AudioDecoder() new AudioEncoder()