Codec Modes
===========
Opus contains two independent audio codecs that it combines to cover every use
case from 6 kbps narrowband phone calls to 512 kbps transparent music archival.
Understanding the three modes (SILK-only, CELT-only, and hybrid) helps you
pick the right encoder settings.
The Three Modes
---------------
SILK-Only
~~~~~~~~~
SILK is a wideband speech codec (LP-based, similar in heritage to iSAC).
It operates at internal rates of 8, 12, or 16 kHz and is optimised for speech
at low-to-medium bitrates.
- **Best for**: speech, voice calls, VoIP at 6-32 kbps
- **Frame sizes**: 10, 20, 40, or 60 ms
- **Bandwidth**: narrowband (NB), medium-band (MB), or wideband (WB)
.. code-block:: python
enc = ruopus.OpusEncoder(
1,
bitrate=16_000,
application=ruopus.Application.Voip,
signal=ruopus.Signal.Voice,
)
packet = enc.encode_silk(frame) # force SILK-only for this frame
CELT-Only
~~~~~~~~~
CELT is an MDCT-based codec (similar in heritage to Vorbis). It operates at
the full 48 kHz sample rate and excels at music, wideband audio, and
low-latency applications.
- **Best for**: music, game audio, low-delay voice at 32+ kbps
- **Frame sizes**: 2.5, 5, 10, or 20 ms
- **Bandwidth**: narrowband through fullband
.. code-block:: python
enc = ruopus.OpusEncoder(
2,
bitrate=96_000,
application=ruopus.Application.Audio,
signal=ruopus.Signal.Music,
)
packet = enc.encode(frame) # encode() always uses CELT
Hybrid
~~~~~~
Hybrid coding uses SILK for the low band (below 8 kHz) and CELT for the high
band above it. This gives SILK's speech quality at low bitrates while
preserving fullband presence.
- **Best for**: super-wideband or fullband speech at 16-32 kbps
- **Frame sizes**: 10 or 20 ms
- **Bandwidth**: super-wideband (SWB) or fullband (FB)
.. code-block:: python
packet = enc.encode_hybrid(frame) # force hybrid for this frame
Automatic Mode Selection
------------------------
:meth:`~ruopus.OpusEncoder.encode_auto` is the right choice for most
applications. The encoder runs a signal classifier on every frame and selects
SILK, hybrid, or CELT based on:
- The :attr:`~ruopus.OpusEncoder.signal` hint (``Auto``, ``Voice``, ``Music``)
- The :attr:`~ruopus.OpusEncoder.application` profile
- The target bitrate and forced/maximum bandwidth
- Cross-frame hysteresis (to avoid rapid mode flipping)
.. code-block:: python
enc = ruopus.OpusEncoder(2, bitrate=32_000)
# Auto mode: classifier picks SILK/hybrid/CELT per frame
packet = enc.encode_auto(frame)
Checking the Mode of a Decoded Packet
--------------------------------------
After encoding, inspect the TOC byte to confirm which mode was used:
.. code-block:: python
pkt = ruopus.Packet(packet)
print(pkt.toc.mode) # Mode.SilkOnly / Mode.Hybrid / Mode.CeltOnly
print(pkt.toc.bandwidth) # Bandwidth.FullBand, etc.
print(pkt.toc.frame_size) # FrameSize.Ms20, etc.
See :doc:`packet_inspection` for the full packet introspection API.
Application Profiles
--------------------
The :class:`~ruopus.Application` enum nudges the automatic classifier:
.. list-table::
:header-rows: 1
:widths: 20 80
* - Value
- Effect
* - ``Application.Audio``
- Balanced default. Suitable for music and general audio.
* - ``Application.Voip``
- Biases toward SILK / hybrid; adds noise suppression tuned for speech.
* - ``Application.RestrictedLowDelay``
- Forces CELT-only on every frame. Lowest latency (encoder lookahead = 2.5 ms). Never uses SILK.
Signal Hints
------------
The :class:`~ruopus.Signal` enum biases the speech/music classifier:
.. list-table::
:header-rows: 1
:widths: 15 85
* - Value
- Effect
* - ``Signal.Auto``
- Run the built-in classifier (default).
* - ``Signal.Voice``
- Treat the source as speech; push toward SILK / hybrid modes.
* - ``Signal.Music``
- Treat the source as music; push toward CELT.
Bandwidth Control
-----------------
:class:`~ruopus.Bandwidth` controls the coded audio bandwidth:
.. list-table::
:header-rows: 1
:widths: 25 20 20 35
* - Enum value
- Audio BW
- Sample rate
- Notes
* - ``Bandwidth.NarrowBand``
- 4 kHz
- 8 kHz
- SILK-only
* - ``Bandwidth.MediumBand``
- 6 kHz
- 12 kHz
- SILK-only
* - ``Bandwidth.WideBand``
- 8 kHz
- 16 kHz
- SILK or hybrid
* - ``Bandwidth.SuperWideBand``
- 12 kHz
- 24 kHz
- Hybrid or CELT
* - ``Bandwidth.FullBand``
- 20 kHz
- 48 kHz
- CELT or hybrid
Set :attr:`~ruopus.OpusEncoder.max_bandwidth` to cap automatic selection, or
:attr:`~ruopus.OpusEncoder.bandwidth` to pin it. Call
:meth:`~ruopus.OpusEncoder.set_auto_bandwidth` to restore automatic selection.