Signatur
Beschreibung
Mit configure() legt man fest, wie ein AudioEncoder rohe Audiodaten (AudioData) in komprimierte EncodedAudioChunk-Objekte umwandelt: welcher Codec verwendet wird (z. B. Opus oder AAC), mit welcher Abtastrate und Kanalzahl das Eingangssignal vorliegt und welche Zielbitrate gilt. Ohne vorherigen Aufruf von configure() wirft encode() einen InvalidStateError.
Die Methode arbeitet asynchron über eine Steuerungswarteschlange: Sie kehrt sofort zurück und setzt state auf "configured". Die eigentliche Konfiguration des Codecs geschieht im Hintergrund. Wird die Konfiguration dort nicht unterstützt, meldet der Encoder einen NotSupportedError über den error-Callback des Konstruktors und schließt sich danach (state === "closed").
configure() kann auch mehrmals aufgerufen werden, etwa um die Bitrate zur Laufzeit zu ändern. Chunks, die vorher eingereiht wurden, werden noch mit der alten Konfiguration codiert. Wer sicherstellen will, dass alle ausstehenden Daten ausgegeben wurden, ruft vorher await encoder.flush() auf. Vor dem Konfigurieren sollte man mit der statischen Methode AudioEncoder.isConfigSupported() prüfen, ob die gewünschte Konfiguration unterstützt wird.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $config Pflicht | Object (AudioEncoderConfig) | Konfigurationsobjekt mit den folgenden Eigenschaften. | |
| $config.codec Pflicht | string | Codec-Zeichenkette nach dem WebCodecs Codec Registry, z. B. "opus", "mp4a.40.2" (AAC-LC), "flac", "mp3". |
|
| $config.sampleRate Pflicht | number | Abtastrate des Eingangs in Hz, z. B. 48000. Muss zu den übergebenen AudioData-Objekten passen. |
|
| $config.numberOfChannels Pflicht | number | Anzahl der Audiokanäle, z. B. 1 (Mono) oder 2 (Stereo). |
|
| $config.bitrate | number | Zielbitrate in Bit pro Sekunde, z. B. 128000. |
|
| $config.bitrateMode | "constant" | "variable" | "variable" | Konstante (CBR) oder variable Bitrate (VBR). |
| $config.opus | Object | Opus-spezifische Optionen: format ("opus" | "ogg"), frameDuration (µs, Standard 20000), complexity (0–10), packetlossperc, useinbandfec, usedtx, signal ("auto" | "music" | "voice"), application ("voip" | "audio" | "lowdelay"). |
|
| $config.aac | Object | AAC-spezifische Optionen: format ("aac" = roh mit description in den Metadaten, "adts" = mit ADTS-Headern). |
Rückgabewert
error-Callback gemeldet.Beispiele
Opus-Encoder konfigurieren und Chunks sammeln
const chunks = [];
const encoder = new AudioEncoder({
output: (chunk, metadata) => {
chunks.push(chunk);
if (metadata?.decoderConfig) {
console.log('Decoder-Konfiguration:', metadata.decoderConfig.codec);
}
},
error: (e) => console.error('Encoder-Fehler:', e.message),
});
encoder.configure({
codec: 'opus',
sampleRate: 48000,
numberOfChannels: 2,
bitrate: 128_000,
});
console.log(encoder.state);Unterstützung vorher mit isConfigSupported() prüfen
const config = {
codec: 'mp4a.40.2', // AAC-LC
sampleRate: 44100,
numberOfChannels: 2,
bitrate: 160_000,
aac: { format: 'adts' },
};
const { supported } = await AudioEncoder.isConfigSupported(config);
if (supported) {
const encoder = new AudioEncoder({
output: (chunk) => console.log('Chunk:', chunk.byteLength, 'Bytes'),
error: (e) => console.error(e),
});
encoder.configure(config);
} else {
console.warn('AAC wird in diesem Browser nicht unterstützt.');
}Mikrofon-Audio für Sprachübertragung codieren
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
const { sampleRate, channelCount } = track.getSettings();
const encoder = new AudioEncoder({
output: (chunk) => console.log(`${chunk.type} @ ${chunk.timestamp} µs`),
error: (e) => console.error(e),
});
encoder.configure({
codec: 'opus',
sampleRate: sampleRate ?? 48000,
numberOfChannels: channelCount ?? 1,
bitrate: 32_000,
opus: { application: 'voip', signal: 'voice', usedtx: true, useinbandfec: true },
});
// MediaStreamTrackProcessor: derzeit nur in Chromium-Browsern verfügbar
const processor = new MediaStreamTrackProcessor({ track });
const reader = processor.readable.getReader();
while (true) {
const { value: audioData, done } = await reader.read();
if (done) break;
encoder.encode(audioData);
audioData.close();
}Bitrate zur Laufzeit ändern
const lowerBitrate = async (encoder) => {
// Ausstehende Daten erst mit alter Konfiguration ausgeben
await encoder.flush();
encoder.configure({
codec: 'opus',
sampleRate: 48000,
numberOfChannels: 2,
bitrate: 48_000,
});
console.log('Neue Bitrate aktiv');
};