AudioData.numberOfChannels — Eigenschaft · JavaScript-Referenz

Signatur

get AudioData.prototype.numberOfChannels

Beschreibung

Die schreibgeschützte Eigenschaft numberOfChannels gehört zum Interface AudioData der WebCodecs API. Sie liefert eine ganze Zahl ohne Vorzeichen, die angibt, wie viele Kanäle die Audio-Samples im Objekt enthalten. Den Wert legt man beim Konstruktor-Aufruf new AudioData({ numberOfChannels, … }) fest. Wenn das Objekt von einem AudioDecoder stammt, setzt der Decoder den Wert.

Man braucht die Eigenschaft vor allem, um die Audiodaten kanalweise zu verarbeiten. Bei planaren Formaten (z. B. "f32-planar") liegt jeder Kanal in einer eigenen Ebene. numberOfChannels ist dann gleich der Anzahl der Ebenen, die man über den Parameter planeIndex von copyTo() und allocationSize() ansprechen kann. Bei verschachtelten Formaten (z. B. "f32" oder "s16") gibt es dagegen nur eine Ebene. Dort liegen die Samples der einzelnen Kanäle abwechselnd hintereinander, und numberOfChannels bestimmt den Abstand zwischen zwei Samples desselben Kanals.

Zusammen mit numberOfFrames, sampleRate und format beschreibt numberOfChannels den Aufbau des Puffers vollständig. Die Gesamtzahl der Samples ist numberOfFrames × numberOfChannels.

Rückgabewert

Typ

number

Beschreibung

Anzahl der Kanäle als ganze Zahl ohne Vorzeichen (unsigned long). Nach dem Aufruf von close() ist der Wert 0.

Beispiele

Stereo-AudioData erzeugen und Kanalanzahl auslesen

const sampleRate = 48000;
const numberOfFrames = 480; // 10 ms
const numberOfChannels = 2;

// Planar: erst alle Samples des linken Kanals, dann die des rechten
const data = new Float32Array(numberOfFrames * numberOfChannels);
for (let i = 0; i < numberOfFrames; i++) {
  const sample = Math.sin(2 * Math.PI * 440 * i / sampleRate);
  data[i] = sample;                        // links
  data[numberOfFrames + i] = sample * 0.5; // rechts, leiser
}

const audioData = new AudioData({
  format: 'f32-planar',
  sampleRate,
  numberOfFrames,
  numberOfChannels,
  timestamp: 0,
  data
});

console.log(audioData.numberOfChannels);
console.log(audioData.duration); // Mikrosekunden
audioData.close();

2 10000

Pegelspitzen pro Kanal in der Ausgabe eines AudioDecoders messen

// Kopiert jeden Kanal in ein eigenes Float32Array
const splitChannels = (audioData) => {
  const channels = [];
  for (let ch = 0; ch < audioData.numberOfChannels; ch++) {
    const options = { planeIndex: ch, format: 'f32-planar' };
    const bytes = audioData.allocationSize(options);
    const buffer = new Float32Array(bytes / Float32Array.BYTES_PER_ELEMENT);
    audioData.copyTo(buffer, options);
    channels.push(buffer);
  }
  return channels;
};

const decoder = new AudioDecoder({
  output: (audioData) => {
    const peaks = splitChannels(audioData).map((samples) =>
      samples.reduce((max, s) => Math.max(max, Math.abs(s)), 0)
    );
    console.log(`${audioData.numberOfChannels} Kanäle, Spitzen:`, peaks);
    audioData.close(); // Speicher sofort freigeben
  },
  error: (err) => console.error('Decoder-Fehler:', err)
});

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

2 Kanäle, Spitzen: [0.98, 0.49] (Beispielwerte)

Verhalten nach close()

const audioData = new AudioData({
  format: 's16',
  sampleRate: 44100,
  numberOfFrames: 1024,
  numberOfChannels: 1,
  timestamp: 0,
  data: new Int16Array(1024)
});

console.log(audioData.numberOfChannels);
audioData.close();
console.log(audioData.numberOfChannels);

1 0

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie audioData.numberOfChannels = 4 wird ignoriert. Im strikten Modus wirft sie einen TypeError. Um die Kanalanzahl zu ändern, legt man ein neues AudioData-Objekt an.
Nach close() ist der Wert 0. Schleifen über die Kanäle laufen dann nicht mehr, und copyTo() wirft einen InvalidStateError.
Planar oder verschachtelt: Nur bei planaren Formaten ist numberOfChannels gleich der Anzahl der Ebenen. Bei verschachtelten Formaten ist nur planeIndex: 0 gültig, sonst folgt ein RangeError. Wenn man in copyTo() format: 'f32-planar' angibt, kann man jeden Kanal einzeln kopieren, egal in welchem Format die Daten vorliegen.
Konstruktor-Prüfung: Ist numberOfChannels 0 oder passt die Größe von data nicht zu numberOfFrames × numberOfChannels, wirft new AudioData() einen TypeError.
Kompatibilität: Die WebCodecs API steht nur in sicheren Kontexten (HTTPS) zur Verfügung, im Fenster und in Workern. Chromium-Browser unterstützen sie seit Version 94, Firefox seit 130. In Safari ist die Audio-Unterstützung erst in neueren Versionen vorhanden. Deshalb vorher mit 'AudioData' in globalThis prüfen.
Speicher: AudioData-Objekte belegen oft Speicher außerhalb des JavaScript-Heaps. Deshalb nach der Verarbeitung immer close() aufrufen.

Siehe auch

AudioData.numberOfFrames AudioData.sampleRate AudioData.duration AudioData.timestamp AudioData.format MediaTrackSettings.channelCount Window.speechSynthesis