AudioData.allocationSize() — Methode · JavaScript-Referenz

Signatur

AudioData.prototype.allocationSize(options)

Beschreibung

allocationSize() berechnet, wie groß ein Zielpuffer (ArrayBuffer, TypedArray oder DataView) mindestens sein muss, damit AudioData.copyTo() mit denselben Optionen die Audio-Samples hineinkopieren kann. Die Methode wird fast immer direkt vor copyTo() aufgerufen, damit man den Puffer passend anlegen kann.

Das Ergebnis hängt vom Sample-Format ab. Bei interleaved-Formaten (u8, s16, s32, f32) gibt es nur eine Ebene (planeIndex: 0), in der alle Kanäle abwechselnd hintereinander liegen. Die Größe ist dann Frames × Kanäle × Bytes pro Sample. Bei planaren Formaten (u8-planar, s16-planar, s32-planar, f32-planar) hat jeder Kanal eine eigene Ebene. Die Größe ist dann Frames × Bytes pro Sample.

Mit frameOffset und frameCount lässt sich ein Ausschnitt wählen, zum Beispiel wenn man nur einen Teil der Samples braucht. Mit format kann man die Größe für ein anderes Zielformat berechnen, etwa wenn copyTo() beim Kopieren nach f32-planar umwandeln soll.

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	Object		Objekt mit Kopier-Optionen. Dieselben Optionen sollten auch an `copyTo()` übergeben werden.
$options.planeIndex Pflicht	number		Index der Ebene, deren Größe berechnet wird. Bei interleaved-Formaten nur `0`, bei planaren Formaten `0` bis `numberOfChannels - 1`.
$options.frameOffset	number	0	Ab welchem Frame gezählt wird.
$options.frameCount	number	numberOfFrames - frameOffset	Anzahl der zu berücksichtigenden Frames. Ohne Angabe: alle Frames ab `frameOffset`.
$options.format	"u8"\|"s16"\|"s32"\|"f32"\|"u8-planar"\|"s16-planar"\|"s32-planar"\|"f32-planar"	AudioData.format	Zielformat, für das die Größe berechnet wird. Ohne Angabe gilt das Format des Objekts.

Rückgabewert

Typ

number

Beschreibung

Benötigte Puffergröße in Bytes (ganze Zahl).

Beispiele

Puffergröße für einen planaren Stereo-Kanal

const frames = 1024;
const audio = new AudioData({
  format: 'f32-planar',
  sampleRate: 48000,
  numberOfFrames: frames,
  numberOfChannels: 2,
  timestamp: 0,
  data: new Float32Array(frames * 2) // L-Kanal, danach R-Kanal
});

// Größe der Ebene des linken Kanals
const size = audio.allocationSize({ planeIndex: 0 });
console.log(size); // 1024 Frames × 4 Bytes

const left = new Float32Array(size / Float32Array.BYTES_PER_ELEMENT);
audio.copyTo(left, { planeIndex: 0 });
audio.close();

4096

Interleaved-Format: alle Kanäle in einer Ebene

const audio = new AudioData({
  format: 's16',
  sampleRate: 48000,
  numberOfFrames: 480, // 10 ms
  numberOfChannels: 2,
  timestamp: 0,
  data: new Int16Array(480 * 2)
});

// 480 Frames × 2 Kanäle × 2 Bytes
console.log(audio.allocationSize({ planeIndex: 0 }));

// Nur die ersten 100 Frames
console.log(audio.allocationSize({ planeIndex: 0, frameOffset: 0, frameCount: 100 }));
audio.close();

1920 400

Decoder-Ausgabe kanalweise in Float32 umwandeln

const decoder = new AudioDecoder({
  output: (audioData) => {
    const channels = [];
    for (let ch = 0; ch < audioData.numberOfChannels; ch++) {
      const opts = { planeIndex: ch, format: 'f32-planar' };
      const bytes = audioData.allocationSize(opts);
      const buffer = new Float32Array(bytes / 4);
      audioData.copyTo(buffer, opts);
      channels.push(buffer);
    }
    console.log(`${channels.length} Kanäle, je ${channels[0].length} Samples`);
    audioData.close(); // Speicher sofort freigeben
  },
  error: (e) => console.error(e)
});

decoder.configure({ codec: 'opus', sampleRate: 48000, numberOfChannels: 2 });

2 Kanäle, je 960 Samples

// Wichtig · Fallstricke

Der Rückgabewert ist in Bytes, nicht in Elementen. Für einen Float32Array teilt man durch 4, für einen Int16Array durch 2 (BYTES_PER_ELEMENT).
Wirft einen RangeError, wenn planeIndex nicht existiert (z. B. 1 bei einem interleaved-Format) oder wenn frameOffset/frameCount über numberOfFrames hinausgehen.
Wirft einen InvalidStateError, wenn close() schon aufgerufen wurde.
Umwandlung per format: Laut Spezifikation muss nur die Umwandlung nach f32-planar funktionieren. Andere Zielformate können in copyTo() einen NotSupportedError auslösen, auch wenn allocationSize() einen Wert liefert.
Kompatibilität: Teil der WebCodecs-API. Nur in sicheren Kontexten (HTTPS) verfügbar, im Fenster und in Workern. Unterstützt in Chromium-Browsern ab Version 94 und in Firefox ab 130. In Safari fehlt AudioData ganz oder teilweise – vorher mit 'AudioData' in globalThis prüfen.

Siehe auch

AudioData AudioData.copyTo() AudioData.close() AudioData.format AudioDecoder VideoFrame.allocationSize() Sanitizer.allowAttribute()