AudioBuffer — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioBuffer

Beschreibung

Ein AudioBuffer enthält unkomprimierte Audiodaten als lineare PCM-Samples im Format 32-Bit-Gleitkomma (Wertebereich nominal -1.0 bis 1.0), getrennt nach Kanälen. Er entsteht entweder durch Dekodieren einer Audiodatei mit BaseAudioContext.decodeAudioData(), durch BaseAudioContext.createBuffer(), direkt über den Konstruktor new AudioBuffer(options) oder als Ergebnis von OfflineAudioContext.startRendering().

Abgespielt wird ein Buffer über einen AudioBufferSourceNode (Eigenschaft buffer). Ein und derselbe AudioBuffer lässt sich beliebig oft wiederverwenden und auch mehreren Quellknoten gleichzeitig zuweisen – ideal für Soundeffekte in Spielen, Samples in Musik-Apps oder kurze UI-Sounds.

Wichtige Eigenschaften (alle schreibgeschützt):

sampleRate – Abtastrate in Hz (number)
length – Anzahl der Sample-Frames pro Kanal
duration – Dauer in Sekunden (length / sampleRate)
numberOfChannels – Anzahl der Kanäle

Wichtige Methoden: getChannelData(channel) liefert ein Float32Array mit direktem Zugriff auf die Samples eines Kanals, copyFromChannel(destination, channel, startInChannel) und copyToChannel(source, channel, startInChannel) kopieren Daten gezielt zwischen Buffer und eigenen Arrays.

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	Object		Konstruktor-Optionen für `new AudioBuffer(options)`.
$options.length Pflicht	number		Anzahl der Sample-Frames pro Kanal (muss > 0 sein).
$options.sampleRate Pflicht	number		Abtastrate in Hz; Browser unterstützen mindestens 8000–96000 Hz.
$options.numberOfChannels	number	1	Anzahl der Kanäle (mindestens 32 werden unterstützt).

Rückgabewert

Typ

AudioBuffer

Beschreibung

Ein neuer, mit Stille (Nullen) gefüllter AudioBuffer.

Beispiele

Audiodatei laden, dekodieren und abspielen

const ctx = new AudioContext();

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

const play = (buffer) => {
  const source = ctx.createBufferSource();
  source.buffer = buffer;
  source.connect(ctx.destination);
  source.start();
};

document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume(); // Autoplay-Richtlinie: nur nach Nutzeraktion
  const buffer = await loadSound('/sounds/klick.mp3');
  console.log(`${buffer.numberOfChannels} Kanäle, ${buffer.duration.toFixed(2)} s`);
  play(buffer);
});

2 Kanäle, 0.35 s

Weißes Rauschen per Konstruktor erzeugen

const ctx = new AudioContext();

const noise = new AudioBuffer({
  numberOfChannels: 2,
  length: ctx.sampleRate * 2, // 2 Sekunden
  sampleRate: ctx.sampleRate
});

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

const src = new AudioBufferSourceNode(ctx, { buffer: noise });
src.connect(ctx.destination);
src.start();
console.log(noise.duration);

2

Spitzenpegel ermitteln und Kanal umkehren (copyFromChannel/copyToChannel)

const getPeak = (buffer) => {
  let peak = 0;
  for (let ch = 0; ch < buffer.numberOfChannels; ch++) {
    for (const s of buffer.getChannelData(ch)) {
      peak = Math.max(peak, Math.abs(s));
    }
  }
  return peak;
};

const reverseChannel = (buffer, channel = 0) => {
  const tmp = new Float32Array(buffer.length);
  buffer.copyFromChannel(tmp, channel);
  tmp.reverse();
  buffer.copyToChannel(tmp, channel);
};

const buf = new AudioBuffer({ length: 4, sampleRate: 44100 });
buf.copyToChannel(new Float32Array([0.1, -0.8, 0.5, 0.2]), 0);
reverseChannel(buf);
console.log(getPeak(buf).toFixed(1), Array.from(buf.getChannelData(0), (v) => v.toFixed(1)));

0.8 [ '0.2', '0.5', '-0.8', '0.1' ]

// Wichtig · Fallstricke

Speicherbedarf: Daten liegen unkomprimiert vor – 1 Minute Stereo bei 48 kHz belegt ca. 23 MB (60 × 48000 × 2 × 4 Byte). Für lange Musikstücke besser <audio> mit MediaElementAudioSourceNode verwenden.
Resampling: decodeAudioData() rechnet die Datei auf die sampleRate des Kontexts um – buffer.sampleRate entspricht daher nicht zwingend der Originaldatei.
getChannelData() gibt eine Live-Ansicht zurück; Änderungen während der Wiedergabe werden unter Umständen nicht übernommen, da der Browser die Daten beim Start intern übernehmen darf. Für zuverlässige Änderungen copyToChannel() vor start() nutzen.
Ein AudioBufferSourceNode kann nur einmal gestartet werden – der Buffer selbst ist aber wiederverwendbar; für jede Wiedergabe einen neuen Quellknoten anlegen.
Ungültige Kanalindizes lösen einen IndexSizeError aus, ungültige Optionen im Konstruktor einen NotSupportedError.
Kompatibilität: Der Konstruktor new AudioBuffer() fehlt in sehr alten Browsern (z. B. Safari < 14.1); dort ctx.createBuffer(channels, length, sampleRate) verwenden. Die ältere Callback-Variante von decodeAudioData() ist zugunsten der Promise-Variante überholt.

Siehe auch

AudioDecoder AudioEncoder AudioNode GPUBuffer SourceBuffer