AudioEncoder: configure()-Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Dieses Feature ist verfügbar in Dedicated Web Workers.

Die configure()-Methode der AudioEncoder-Schnittstelle stellt eine Steuerungsnachricht in die Warteschlange, um den Audio-Encoder für die Codierung von Chunks zu konfigurieren.

Syntax

js
configure(config)

Parameter

config

Ein Wörterbuchobjekt, das die folgenden Mitglieder enthält:

codec

Ein String, der einen gültigen Codec-String enthält. Siehe "codecs"-Parameter für Details zur Konstruktion des Codec-Strings.

sampleRate

Ein Integer, der die Anzahl der Frame-Samples pro Sekunde darstellt.

numberOfChannels

Ein Integer, der die Anzahl der Audiokanäle darstellt.

bitrate Optional

Ein Integer, der die Bitrate darstellt.

bitrateMode Optional

Ein enumerierter Wert, der den Bitratemodus definiert, den der Encoder verwenden soll. Mögliche Werte sind:

"constant"

Erzwingt, dass ein Audio-Encoder die gleiche Bitrate beibehält, unabhängig vom Audiocontent. Dies kann nützlich sein, wenn ein vorhersehbarer Bandbreitenverbrauch bevorzugt wird.

"variable" (Standard)

Erlaubt einem Audio-Encoder, seine Bitrate je nach Inhalt des zu codierenden Audios zu erhöhen oder zu senken, um Bandbreite/Binärgröße zu sparen und dennoch eine Zielqualität beizubehalten. Beispielsweise könnte ein Encoder seine Bitrate senken, wenn Stille codiert wird, und zu einer vollen Bitrate zurückkehren, wenn Sprache codiert wird.

Spezifische Codec-Encoder-Implementierungen können leicht unterschiedliche Terminologien verwenden (zum Beispiel CBR vs VBR für Opus), sollten aber alle dem allgemeinen Konzept von "konstanter" versus "variabler" Bitrate entsprechen.

opus Optional

Spezifiziert Codec-Konfigurationsoptionen, die spezifisch für den Opus-Codec sind. Sein Wert ist ein OpusEncoderConfig-Objekt, dessen mögliche Eigenschaften wie folgt sind:

application Optional

Ein enumerierter Wert, der den beabsichtigten Anwendungstyp des Encoders bestimmt. Mögliche Werte sind:

audio (Standard)

Verarbeitet das Signal originalgetreu zum ursprünglichen Eingangs.

lowdelay

Konfiguriert eine minimale mögliche Kodierungsverzögerung, indem bestimmte Betriebsarten deaktiviert werden, während das Signal verarbeitet wird.

voip

Verarbeitet das Signal zur Verbesserung der Sprachverständlichkeit.

complexity Optional

Eine Zahl, die die rechnerische Komplexität des Encoders definiert, basierend auf den Aspekten, die in Abschnitt RFC6716, 2.1.5. — Komplexität beschrieben sind. Der gültige Bereich reicht von 0 bis 10, wobei 10 die höchste Komplexität darstellt. Wenn kein Wert angegeben wird, ist der Standardwert plattformabhängig, wobei die Spezifikation 5 für mobile Plattformen und 9 für alle anderen Plattformen empfiehlt.

format Optional

Ein enumerierter Wert, der das Format spezifiziert, in dem der Encoder EncodedAudioChunks ausgeben soll. Mögliche Werte sind:

opus (Standard)

Gibt EncodedAudioChunks im Opus-Format aus. In diesem Fall sind keine Metadaten notwendig, um den codierten Audiostream zu decodieren.

ogg

Gibt EncodedAudioChunks im Ogg-Format aus. In diesem Fall sind keine Metadaten notwendig, um den codierten Audiostream zu decodieren. In diesem Fall werden die Metadaten des codierten Audiostreams in der Dekoderkonfiguration bereitgestellt — über die description Eigenschaft des Konfigurationsobjekts, das an AudioDecoder.configure() übergeben wird.

frameDuration Optional

Eine Zahl, die die Rahmendauer in Mikrosekunden der EncodedAudioChunks definiert, die vom Encoder ausgegeben werden. Wenn nicht angegeben, beträgt der Standardwert für frameDuration 20000.

packetlossperc Optional

Eine Zahl, die den erwarteten Paketverlustrate des Encoders definiert. Der gültige Bereich liegt zwischen 0 und 100. Wenn nicht angegeben, beträgt der Standardwert für packetlossperc 0.

signal Optional

Ein enumerierter Wert, der den Standardwert für die Art des zu codierenden Audiosignals festlegt. Mögliche Werte sind:

auto (Standard)

Das Audiosignal ist nicht als eine bestimmte Art spezifiziert.

music

Das Audiosignal ist Musik.

voice

Das Audiosignal ist Stimme oder Sprache.

usedtx Optional

Ein boolescher Wert, der angibt, ob der Encoder Diskontinuierliche Übertragung (DTX) verwendet, die die Bitrate während Stille oder Hintergrundgeräuschen reduziert. Wenn DTX aktiviert ist, wird nur ein Frame alle 400 Millisekunden codiert. Wenn nicht angegeben, lautet der Standardwert für usedtx false.

useinbandfec Optional

Ein boolescher Wert, der angibt, ob der Encoder Opus In-Band Error Correction (FEC) bereitstellt. Dies führt dazu, dass Pakete, die als wahrnehmbar wichtige Sprachinformationen enthalten (wie zum Beispiel Anstiege oder Transienten), mit einer niedrigeren Bitrate re-kodiert und einem nachfolgenden Paket hinzugefügt werden. Wenn nicht angegeben, lautet der Standardwert für useinbandfec false.

Rückgabewert

Keiner (undefined).

Ausnahmen

TypeError

Wird ausgelöst, wenn das bereitgestellte config ungültig ist.

InvalidStateError DOMException

Wird ausgelöst, wenn der state "closed" ist.

NotSupportedError DOMException

Wird ausgelöst, wenn das bereitgestellte config gültig ist, jedoch der User-Agent keinen Codec bereitstellen kann, der dieses Profil dekodieren kann.

Beispiele

Grundlegendes Konfigurationsbeispiel

Das folgende Beispiel erstellt einen neuen AudioEncoder und konfiguriert ihn mit einigen der verfügbaren Optionen.

js
const init = {
  output: handleOutput,
  error: (e) => {
    console.log(e.message);
  },
};

let config = {
  codec: "mp3",
  sampleRate: 44100,
  numberOfChannels: 2,
  bitrate: 128_000, // 128 kbps
  bitrateMode: "constant",
};

let encoder = new AudioEncoder(init);
encoder.configure(config);

Opus-spezifisches Konfigurationsbeispiel

Das folgende Beispiel erstellt einen neuen AudioEncoder und konfiguriert ihn mit Opus-spezifischen Optionen.

js
const init = {
  output: handleOutput,
  error: (e) => {
    console.log(e.message);
  },
};

let opusConfig = {
  application: "voip",
  complexity: 9,
  signal: "voice",
  usedtx: true,
};

let config = {
  codec: "opus",
  sampleRate: 44100,
  numberOfChannels: 2,
  bitrate: 128_000,
  opus: opusConfig,
};

let encoder = new AudioEncoder(init);
encoder.configure(config);

Spezifikationen

Specification
WebCodecs
# dom-audioencoder-configure

Browser-Kompatibilität

BCD tables only load in the browser