opus_codec_registration.src.html

<pre class='metadata'>
Title: Opus WebCodecs Registration
Repository: w3c/webcodecs
Status: NOTE-ED
Shortname: webcodecs-opus-codec-registration
Level: none
Group: mediawg
ED: https://w3c.github.io/webcodecs/opus_codec_registration.html
TR: https://www.w3.org/TR/webcodecs-opus-codec-registration/
Editor: Paul Adenot, w3cid 62410, Mozilla https://www.mozilla.org/
Editor: Eugene Zemtsov, w3cid 139375, Google LLC https://www.google.com/
Former Editor: Bernard Aboba, w3cid 65611, Microsoft Corporation https://www.microsoft.com/
Former Editor: Chris Cunningham, w3cid 114832, Google LLC https://www.google.com/

Abstract: This registration is entered into the [[webcodecs-codec-registry]].
    It describes, for Opus, the (1) fully qualified [[WEBCODECS#config-codec-string|codec strings]], (2) the
    codec-specific {{EncodedAudioChunk}} {{EncodedAudioChunk/[[internal data]]}}
    bytes, (3) the {{AudioDecoderConfig/description|AudioDecoderConfig.description}}
    bytes, (4) the values of {{EncodedAudioChunk}} {{EncodedAudioChunk/[[type]]}},
    and (5) the codec-specific extensions to {{AudioEncoderConfig}}

    The registration is not intended to include any information on whether a
    codec format is encumbered by intellectual property claims. Implementers and
    authors are advised to seek appropriate legal counsel in this matter if they
    intend to implement or use a specific codec format. Implementers of
    WebCodecs are not required to support the Opus codec.

    This registration is non-normative.

Markup Shorthands:css no, markdown yes, dfn yes
!Participate: <a href="https://github.com/w3c/webcodecs">Git Repository.</a>
!Participate: <a href="https://github.com/w3c/webcodecs/issues/new">File an issue.</a>
!Version History: <a href="https://github.com/w3c/webcodecs/commits">https://github.com/w3c/webcodecs/commits</a>
</pre>


<pre class='biblio'>
{
  "OPUS": {
    "href": "https://datatracker.ietf.org/doc/html/rfc6716",
    "title": "RFC 6716: Definition of the Opus Audio Codec",
    "publisher": "IETF",
    "date": "September 2012"
  },
  "OPUS-IN-OGG": {
    "href": "https://datatracker.ietf.org/doc/html/rfc7845",
    "title": "RFC 7845: Ogg Encapsulation for the Opus Audio Codec",
    "publisher": "IETF",
    "date": "April 2016"
  }
}
</pre>

Fully qualified codec strings {#fully-qualified-codec-strings}
==============================================================

The [[WEBCODECS#config-codec-string|codec string]] is `"opus"`.

EncodedAudioChunk data {#encodedaudiochunk-data}
================================================

An {{EncodedAudioChunk}} containing Opus can be in two different formats.

If the bitstream is in {{OpusBitstreamFormat/opus}} format,
{{EncodedAudioChunk}} have to be Opus packets, as described in [section
3](https://datatracker.ietf.org/doc/html/rfc6716#section-3) of [[OPUS]]

If the bitstream is in {{OpusBitstreamFormat/ogg}} format,
{{EncodedAudioChunk}} have to be audio data packets, as described in [section
3](https://datatracker.ietf.org/doc/html/rfc7845#section-3) of [[OPUS-IN-OGG]].

AudioDecoderConfig description {#audiodecoderconfig-description}
================================================================

{{AudioDecoderConfig/description}} can be optionally set to an Identification
Header, described in section 5.1 of [[OPUS-IN-OGG]].

If a {{AudioDecoderConfig/description}} has been set, the bitstream is assumed
to be in {{OpusBitstreamFormat/ogg}} format.

If a {{AudioDecoderConfig/description}} has not been set, the bitstream is
assumed to be in {{OpusBitstreamFormat/opus}} format.

EncodedAudioChunk type {#encodedaudiochunk-type}
================================================

The {{EncodedAudioChunk/[[type]]}} for an {{EncodedAudioChunk}} containing
Opus is always "{{EncodedAudioChunkType/key}}".

NOTE: Once the initialization has succeeded, any packet can be decoded at any
time without error, but this might not result in the expected audio output.

Priming Samples {#priming-samples}
==================================

The `Pre-skip` field in the Identification Header (see section 5.1 of [[OPUS-IN-OGG]]), if present in {{AudioDecoderConfig/description}}, specifies the initial value for {{AudioDecoder}}'s {{AudioDecoder/[[priming samples to discard]]}} internal slot. If {{AudioDecoderConfig/description}} is not present, {{AudioDecoder/[[priming samples to discard]]}} is initialized to `0`. Decoded {{EncodedAudioChunk}}s do not convey additional discard information.

AudioEncoderConfig extensions {#audioencoderconfig-extensions}
=============================================================

<pre class='idl'>
<xmp>
partial dictionary AudioEncoderConfig {
  OpusEncoderConfig opus;
};
</xmp>
</pre>

<dl>
  <dt><dfn dict-member for=AudioEncoderConfig>opus</dfn></dt>
  <dd>
    Contains codec specific configuration options for the Opus codec.
  </dd>
</dl>


OpusEncoderConfig {#opus-encoder-config}
--------------------------------------

<pre class='idl'>
<xmp>
dictionary OpusEncoderConfig {
  OpusBitstreamFormat format = "opus";
  OpusSignal signal = "auto";
  OpusApplication application = "audio";
  [EnforceRange] unsigned long long frameDuration = 20000;
  [EnforceRange] unsigned long complexity;
  [EnforceRange] unsigned long packetlossperc = 0;
  boolean useinbandfec = false;
  boolean usedtx = false;
};
</xmp>
</pre>

To check if an {{OpusEncoderConfig}} is valid, run these steps:
1. If {{OpusEncoderConfig/frameDuration}} is not a valid frame duration,
    which is described section 2.1.4 of [[RFC6716]], return `false`.
1. If {{OpusEncoderConfig/complexity}} is specified and not within the range of
    `0` and `10` inclusively, return `false`.
1. If {{OpusEncoderConfig/packetlossperc}} is specified and not within the range of
    `0` and `100` inclusively, return `false`.
2. Return `true`.

<dl>
  <dt><dfn dict-member for=OpusEncoderConfig>format</dfn></dt>
  <dd>
    Configures the format of output {{EncodedAudioChunk}}s. See
    {{OpusBitstreamFormat}}.
  </dd>
  <dt><dfn dict-member for=OpusEncoderConfig>signal</dfn></dt>
  <dd>
    Specificies the type of audio signal being encoded. See {{OpusSignal}}.
  </dd>
  <dt><dfn dict-member for=OpusEncoderConfig>application</dfn></dt>
  <dd>
    Specificies the encoder's intended application. See {{OpusApplication}}.
  </dd>
  <dt><dfn dict-member for=OpusEncoderConfig>frameDuration</dfn></dt>
  <dd>
    Configures the frame duration, in microseconds, of output {{EncodedAudioChunk}}s.
  </dd>
  <dt><dfn dict-member for=OpusEncoderConfig>complexity</dfn></dt>
  <dd>
    Configures the encoder's computational complexity, as described in section 2.1.9.
    of [[RFC6716]]. The valid range is `0` to `10`, with `10` representing the highest
    complexity. If no value is specificied, the default value is platform-specific:
    User Agents <em class="rfc2119">SHOULD</em> set a default of `5` for mobile
    platforms, and a default of `9` for all other platforms.
  </dd>
  <dt><dfn dict-member for=OpusEncoderConfig>packetlossperc</dfn></dt>
  <dd>
    Configures the encoder's expected packet loss percentage. The valid range is
    `0` to `100`.

    NOTE: The packet loss percentage might be updated over the course of an
    encoding, and it is recommended for User Agents to support these reconfigurations.
  </dd>
  <dt><dfn dict-member for=OpusEncoderConfig>useinbandfec</dfn></dt>
  <dd>
    Specifies whether the encoder provides Opus in-band Forward Error Correction
    (FEC), as described by section 2.1.7. of [[RFC6716]].
  </dd>
  <dt><dfn dict-member for=OpusEncoderConfig>usedtx</dfn></dt>
  <dd>
    Specifies if the encoder uses Discontinuous Transmission (DTX), as described
    by section 2.1.9. of [[RFC6716]].
  </dd>
</dl>

OpusBitstreamFormat {#opus-bitstream-format}
------------------------------------------
<pre class='idl'>
<xmp>
enum OpusBitstreamFormat {
  "opus",
  "ogg",
};
</xmp>
</pre>

The {{OpusBitstreamFormat}} determines if extra-data are necessary to decode the
encoded audio stream.

<dl>
  <dt><dfn enum-value for=OpusBitstreamFormat>opus</dfn></dt>
  <dd>
    No metadata are necessary to decode the encoded audio stream.
  </dd>
  <dt><dfn enum-value for=OpusBitstreamFormat>ogg</dfn></dt>
  <dd>
    The metadata of the encoded audio stream are provided at configuration via
    {{AudioDecoderConfig/description|AudioDecoderConfig.description}}.
  </dd>
</dl>

OpusSignal {#opus-signal}
------------------------------------------
<pre class='idl'>
<xmp>
enum OpusSignal {
  "auto",
  "music",
  "voice",
};
</xmp>
</pre>

The {{OpusSignal}} indicates the default value for the type of signal being encoded.

<dl>
  <dt><dfn enum-value for=OpusSignal>auto</dfn></dt>
  <dd>
    The audio signal is not specified to be of a particular type.
  </dd>
  <dt><dfn enum-value for=OpusSignal>music</dfn></dt>
  <dd>
    The audio signal is music.
  </dd>
  <dt><dfn enum-value for=OpusSignal>voice</dfn></dt>
  <dd>
    The audio signal is voice or speech.
  </dd>
</dl>

OpusApplication {#opus-application}
------------------------------------------
<pre class='idl'>
<xmp>
enum OpusApplication {
  "voip",
  "audio",
  "lowdelay",
};
</xmp>
</pre>

The {{OpusApplication}} indicates the default value for the encoder's intended
application.

<dl>
  <dt><dfn enum-value for=OpusApplication>voip</dfn></dt>
  <dd>
    Process signal for improved speech intelligibility.
  </dd>
  <dt><dfn enum-value for=OpusApplication>audio</dfn></dt>
  <dd>
    Favor faithfulness to the original input.
  </dd>
  <dt><dfn enum-value for=OpusApplication>lowdelay</dfn></dt>
  <dd>
    Configure the minimum possible coding delay by disabling certain modes of
    operation.
  </dd>
</dl>

Privacy Considerations {#privacy-considerations}
==========================================================================

Please refer to the section [[WEBCODECS#privacy-considerations|Privacy
Considerations]] in [[WEBCODECS]].

Security Considerations {#security-considerations}
==========================================================================

Please refer to the section [[WEBCODECS#security-considerations|Security
Considerations]] in [[WEBCODECS]].