AudioEncoder: configure() method

Syntax

configure(config)

Parameters

config

A dictionary object containing the following members:

codec

A string containing a valid codec string. See "codecs" parameter for details on codec string construction.

sampleRate

An integer representing the number of frame samples per second.

numberOfChannels

An integer representing the number of audio channels.

bitrate Optional

An integer representing the bitrate.

bitrateMode Optional

An enumerated value that defines the bitrate mode the encoder should use. Possible values are:

"constant"

Forces an audio encoder to maintain the same bitrate, regardless of the audio content. This can be useful when a predictable bandwidth consumption is preferable.

"variable" (default)

Allows an audio encoder to increase or lower its bitrate according to the content of the audio it is encoding, in order to preserve bandwidth/binary-size, while still maintaining a target quality. For example, an encoder might lower its bitrate when encoding silence, and revert to a full bitrate when encoding speech.

Specific codec encoder implementations may use slightly different terminology (for example, CBR vs VBR for Opus), but they should all map to the general concept of "constant" versus "variable" bitrate.

opus Optional

Specifies codec configuration options specific to the Opus codec. Its value is an OpusEncoderConfig object, the possible properties of which are as follows:

application Optional

An enumerated value that specifies the encoder's intended application type. Possible values are:

audio (default)

Process the signal faithfully to the original input.

lowdelay

When processing the signal, configure the minimum possible encoding delay by disabling certain modes of operation.

voip

Process signal for improved speech intelligibility.

complexity Optional

A number that defines the encoder's computational complexity, based on the aspects described in section RFC6716, 2.1.5. — Complexity. The valid range is 0 to 10, with 10 representing the highest complexity. If no value is specified, the default value is platform-specific, with the specification recommending 5 for mobile platforms, and 9 for all other platforms.

format Optional

An enumerated value that specifies the format in which the encoder should output EncodedAudioChunks. Possible values are:

opus (default)

Output EncodedAudioChunks in Opus format. In this case, no metadata are necessary to decode the encoded audio stream.

ogg

Output EncodedAudioChunks in Ogg format. In this case, no metadata are necessary to decode the encoded audio stream. In this case, the metadata of the encoded audio stream are provided in the decoder configuration — via the description property of the config object passed into AudioDecoder.configure().

frameDuration Optional

A number that defines the frame duration, in microseconds, of EncodedAudioChunks outputted by the encoder. If not specified, frameDuration defaults to 20000.

packetlossperc Optional

A number that defines the encoder's expected packet loss percentage. The valid range is 0 to 100. If not specified, packetlossperc defaults to 0.

signal Optional

An enumerated value that specifies the default value for the type of audio signal being encoded. Possible values are:

auto (default)

The audio signal is not specified to be of a particular type.

music

The audio signal is music.

voice

The audio signal is voice or speech.

usedtx Optional

A boolean value that specifies whether the encoder uses Discontinuous Transmission (DTX), which reduces the bitrate during silence or background noise. When DTX is enabled, only one frame is encoded every 400 milliseconds. If not specified, usedtx defaults to false.

useinbandfec Optional

A boolean value that specifies whether the encoder provides Opus in-band Forward Error Correction (FEC). This results in packets that are determined to contain perceptually important speech information — such as onsets or transients — to be re-encoded at a lower bitrate and added to a subsequent packet. If not specified, useinbandfec defaults to false.

Return value

None (undefined).

Exceptions

TypeError

Thrown if the provided config is invalid.

InvalidStateError DOMException

Thrown if the state is "closed".

NotSupportedError DOMException

Thrown if the provided config is valid but the user agent cannot provide a codec that can decode this profile.

Examples

Basic configuration example

The following example creates a new AudioEncoder and configures it with some of the available options.

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-specific configuration example

The following example creates a new AudioEncoder and configures it with Opus-specific options.

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);

Specifications

Browser compatibility