Signatur
Beschreibung
Die schreibgeschützte Eigenschaft format gehört zur WebCodecs-API. Sie gibt an, wie die Audio-Samples im Speicher eines AudioData-Objekts liegen, also welchen Datentyp jedes Sample hat und ob die Kanäle verschachtelt (interleaved) oder getrennt (planar) gespeichert sind. Mögliche Werte (Typ AudioSampleFormat):
"u8"/"u8-planar"– 8-Bit-Ganzzahl ohne Vorzeichen"s16"/"s16-planar"– 16-Bit-Ganzzahl mit Vorzeichen"s32"/"s32-planar"– 32-Bit-Ganzzahl mit Vorzeichen"f32"/"f32-planar"– 32-Bit-Gleitkommazahl (Wertebereich −1.0 bis 1.0)
Bei interleaved-Formaten gibt es genau eine Ebene (Plane), in der die Samples aller Kanäle abwechselnd liegen (L R L R …). Bei planaren Formaten gibt es pro Kanal eine eigene Ebene. Das ist wichtig für AudioData.copyTo() und AudioData.allocationSize(): Der Parameter planeIndex darf bei interleaved-Daten nur 0 sein, bei planaren Daten bis numberOfChannels - 1 gehen.
Man braucht format vor allem, um dekodierte Daten aus einem AudioDecoder korrekt zu verarbeiten, den passenden TypedArray-Typ für den Zielpuffer zu wählen oder zu entscheiden, ob beim Kopieren eine Formatumwandlung nötig ist. Der Wert wird beim Erzeugen festgelegt – über den Konstruktor oder durch den Decoder – und ändert sich danach nicht mehr.
Rückgabewert
"u8", "s16", "s32", "f32", "u8-planar", "s16-planar", "s32-planar" oder "f32-planar". Nach close() (oder wenn das Objekt übertragen und damit abgekoppelt wurde) ist der Wert null.Beispiele
Format beim Erzeugen festlegen und auslesen
const numberOfFrames = 480; // 10 ms bei 48 kHz
const numberOfChannels = 2;
// Planar: zuerst alle Samples von Kanal 0, dann alle von Kanal 1
const samples = new Float32Array(numberOfFrames * numberOfChannels);
const audioData = new AudioData({
format: "f32-planar",
sampleRate: 48000,
numberOfFrames,
numberOfChannels,
timestamp: 0,
data: samples
});
console.log(audioData.format);
audioData.close();
console.log(audioData.format); // nach close() abgekoppeltEinen Kanal unabhängig vom Quellformat als Float32 lesen
// Umwandlung nach "f32-planar" muss jeder Browser beim Kopieren unterstützen
const channelToFloat32 = (audioData, channel) => {
const options = { planeIndex: channel, format: "f32-planar" };
const bytes = audioData.allocationSize(options);
const buffer = new Float32Array(bytes / Float32Array.BYTES_PER_ELEMENT);
audioData.copyTo(buffer, options);
return buffer;
};
const pcm = new Int16Array([1000, -1000, 16384, -16384]); // s16, interleaved, 2 Kanäle
const data = new AudioData({
format: "s16",
sampleRate: 44100,
numberOfFrames: 2,
numberOfChannels: 2,
timestamp: 0,
data: pcm
});
console.log(data.format);
console.log(channelToFloat32(data, 0)); // linker Kanal
data.close();Planar oder interleaved? Anzahl der Ebenen und Sample-Größe bestimmen
const BYTES_PER_SAMPLE = { u8: 1, s16: 2, s32: 4, f32: 4 };
const describeFormat = (audioData) => {
const { format, numberOfChannels } = audioData;
if (format === null) throw new Error("AudioData wurde bereits geschlossen");
const planar = format.endsWith("-planar");
const base = format.replace("-planar", "");
return {
format,
planar,
planes: planar ? numberOfChannels : 1,
bytesPerSample: BYTES_PER_SAMPLE[base]
};
};
const data = new AudioData({
format: "s16",
sampleRate: 48000,
numberOfFrames: 128,
numberOfChannels: 2,
timestamp: 0,
data: new Int16Array(256)
});
console.log(describeFormat(data));
data.close();Ausgabeformat eines AudioDecoder prüfen
const decoder = new AudioDecoder({
output: (audioData) => {
// Viele Opus-/AAC-Decoder liefern "f32" oder "f32-planar"
console.log(`Format: ${audioData.format}, Kanäle: ${audioData.numberOfChannels}`);
audioData.close(); // Speicher sofort freigeben
},
error: (e) => console.error("Dekodierfehler:", e)
});
decoder.configure({
codec: "opus",
sampleRate: 48000,
numberOfChannels: 2
});
// Anschließend decoder.decode(new EncodedAudioChunk({...})) aufrufen