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: Chris Cunningham, w3cid 114832, Google Inc. https://www.google.com/
Editor: Paul Adenot, w3cid 62410, Mozilla https://www.mozilla.org/
Editor: Bernard Aboba, w3cid 65611, Microsoft Corporation https://www.microsoft.com/

Abstract: This registration is entered into the [[webcodecs-codec-registry]].
    It describes, for Opus, the (1) fully qualified codec strings, (2) the
    codec-specific {{EncodedAudioChunk}} [=EncodedAudioChunk/[[internal data]]=]
    bytes, (3) the {{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='anchors'>
spec: WEBCODECS; urlPrefix: https://w3c.github.io/webcodecs/#
    type: attribute
        text: AudioDecoderConfig.description; url: dom-audiodecoderconfig-description
    type: dfn
        for: EncodedAudioChunkType; text: key; url: dom-encodedaudiochunktype-key
        for: EncodedAudioChunk; text: [[internal data]]; url: dom-encodedaudiochunk-internal-data-slot
        for: EncodedAudioChunk; text: [[type]]; url: dom-encodedaudiochunk-type-slot
    type: method
        for: AudioDecoder; text: AudioDecoder.decode; url: dom-audiodecoder-decode
    type: interface
        text: EncodedAudioChunk; url: encodedaudiochunk
    type: dictionary
        text: AudioDecoderConfig; url: dictdef-audiodecoderconfig
        text: AudioEncoderConfig; url: dictdef-audioencoderconfig
</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 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 optionally set to an Identification
Header, described in section 5.1 of [[OPUS-IN-OGG]].

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

If an {{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.

AudiEncoderConfig 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";
};
</xmp>
</pre>

<dl>
  <dt><dfn dict-member for=OpusEncoderConfig>format</dfn></dt>
  <dd>
    Configures the format of output {{EncodedAudioChunk}}s. See
    {{OpusBitstreamFormat}}.
  </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}}.
  </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]].