AnalyserNode.getByteTimeDomainData() — Methode · JavaScript-Referenz

Signatur

AnalyserNode.prototype.getByteTimeDomainData(array)

Beschreibung

getByteTimeDomainData() liefert eine Momentaufnahme des Audiosignals im Zeitbereich, also die rohe Wellenform, wie sie ein Oszilloskop zeigt. Jeder Abtastwert wird von der Gleitkomma-Amplitude (−1 bis 1) auf einen vorzeichenlosen Byte-Wert von 0 bis 255 abgebildet. Stille entspricht dem Wert 128.

Die Methode schreibt direkt in das übergebene Uint8Array und legt kein neues Array an. So kann man denselben Puffer in jedem Animationsframe wiederverwenden, ohne neuen Speicher zu belegen. Wie viele Werte geschrieben werden, hängt von fftSize ab: Es sind höchstens fftSize Samples. Ist das Array kürzer, werden überzählige Werte verworfen. Ist es länger, bleiben die restlichen Einträge unverändert.

Typische Einsatzgebiete sind Oszilloskop-Anzeigen, einfache Pegelanzeigen (VU-Meter) und das Erkennen von Stille oder Übersteuerung. Wenn du eine höhere Genauigkeit brauchst, nimm getFloatTimeDomainData() mit einem Float32Array. Für Spektrum- bzw. Frequenzdaten gibt es getByteFrequencyData().

Parameter

Name	Typ	Default	Beschreibung
$array Pflicht	Uint8Array		Ziel-Array, in das die Zeitbereichsdaten kopiert werden. Es sollte in der Regel die Länge `analyser.fftSize` haben. Andere Typen (z. B. ein normales `Array`) lösen einen `TypeError` aus.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Das Ergebnis steht danach im übergebenen Array.

Beispiele

Wellenform eines Oszillators auslesen

const ctx = new AudioContext();
const osc = ctx.createOscillator();
const analyser = ctx.createAnalyser();
analyser.fftSize = 2048;

osc.connect(analyser).connect(ctx.destination);
osc.start();

const data = new Uint8Array(analyser.fftSize);

setTimeout(() => {
  analyser.getByteTimeDomainData(data);
  console.log(data.length, data.slice(0, 8));
}, 500);

2048 Uint8Array(8) [128, 140, 152, ...] // Werte schwanken um 128

Oszilloskop auf einem Canvas zeichnen

const canvas = document.querySelector('#scope');
const g = canvas.getContext('2d');

const start = async () => {
  const ctx = new AudioContext();
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const source = ctx.createMediaStreamSource(stream);
  const analyser = ctx.createAnalyser();
  analyser.fftSize = 1024;
  source.connect(analyser);

  const buffer = new Uint8Array(analyser.fftSize);

  const draw = () => {
    requestAnimationFrame(draw);
    analyser.getByteTimeDomainData(buffer);

    g.fillStyle = '#111';
    g.fillRect(0, 0, canvas.width, canvas.height);
    g.strokeStyle = '#0f0';
    g.beginPath();

    const step = canvas.width / buffer.length;
    buffer.forEach((v, i) => {
      const y = (v / 255) * canvas.height;
      i === 0 ? g.moveTo(0, y) : g.lineTo(i * step, y);
    });
    g.stroke();
  };
  draw();
};

document.querySelector('#start').addEventListener('click', start);

Pegel (RMS) berechnen und Stille erkennen

const getLevel = (analyser, buffer) => {
  analyser.getByteTimeDomainData(buffer);
  let sum = 0;
  for (const v of buffer) {
    const x = (v - 128) / 128; // auf -1..1 normieren
    sum += x * x;
  }
  return Math.sqrt(sum / buffer.length);
};

// Verwendung mit vorhandenem analyser:
// const buf = new Uint8Array(analyser.fftSize);
// const rms = getLevel(analyser, buf);
// if (rms < 0.01) console.log('Stille');

Stille // wenn kein Signal anliegt

// Wichtig · Fallstricke

Puffergröße: Nimm als Länge analyser.fftSize. frequencyBinCount ist nur halb so groß und gehört zu den Frequenzmethoden. Mit einem Array dieser Länge bekommst du nur die halbe Wellenform.
Nullpunkt ist 128: Die Werte sind vorzeichenlos. Für Berechnungen musst du zuerst 128 abziehen. Durch die 8-Bit-Auflösung sind leise Signale nur grob abgebildet. In dem Fall ist getFloatTimeDomainData() die bessere Wahl.
Audio-Kontext entsperren: Browser starten einen AudioContext meist im Zustand suspended, solange es keine Benutzerinteraktion gab. Bis dahin besteht das Array komplett aus 128. Rufe ctx.resume() in einem Klick-Handler auf.
Leistung: Lege den Puffer einmal an und verwende ihn in jedem Frame wieder. Ein neues Array in requestAnimationFrame belastet die Garbage Collection unnötig.
smoothingTimeConstant gilt nur für Frequenzdaten, nicht für die Zeitbereichsdaten.
Die Methode wird von allen modernen Browsern unterstützt. Ältere Safari-Versionen brauchten webkitAudioContext.

Siehe auch

AnalyserNode AnalyserNode.getFloatTimeDomainData() AnalyserNode.getByteFrequencyData() AnalyserNode.fftSize AudioContext Uint8Array