Packet Loss Handling
====================
Opus has two mechanisms for coping with lost packets in real-time streams:
**packet loss concealment (PLC)** via :meth:`~ruopus.OpusDecoder.decode_lost`,
and **in-band forward error correction (FEC)** via
:meth:`~ruopus.OpusDecoder.decode_fec`. Both keep the decoder state consistent
so the stream can recover cleanly after loss.
Packet Loss Concealment
-----------------------
When a packet is lost, call :meth:`~ruopus.OpusDecoder.decode_lost` instead of
:meth:`~ruopus.OpusDecoder.decode_packet`. You must tell the decoder how many
samples to conceal; this should match the expected frame size of the lost
packet.
.. code-block:: python
import ruopus
dec = ruopus.OpusDecoder(2)
for pkt in stream:
if pkt is None:
# Conceal one lost 20 ms frame
concealed = dec.decode_lost(frame_size=960)
else:
pcm = dec.decode_packet(pkt)
CELT-mode concealment extrapolates the last pitch period, producing a short
fade-out. Frames following a SILK or hybrid packet fade to silence (full SILK
PLC is not yet ported). The ``final_range`` of a concealed decode is 0.
In-Band FEC (LBRR)
------------------
When in-band FEC is enabled on the encoder, SILK-mode packets carry a
low-bitrate redundant (LBRR) copy of the *previous* frame's audio alongside
the current frame. If a packet is lost, its content can be recovered from the
*next* received packet using :meth:`~ruopus.OpusDecoder.decode_fec`:
Enable FEC on the Encoder
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
import ruopus
enc = ruopus.OpusEncoder(
1,
bitrate=24_000,
application=ruopus.Application.Voip,
signal=ruopus.Signal.Voice,
inband_fec=True,
packet_loss_perc=10, # hint to the encoder: expect 10% loss
)
``packet_loss_perc`` biases the encoder toward loss-robust coding (more
redundancy, lower raw bitrate efficiency). Values are clamped to 0-100.
Recover a Lost Packet Using FEC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
dec = ruopus.OpusDecoder(1)
FRAME = 960 # 20 ms at 48 kHz
prev_pkt = None
for pkt in stream:
if pkt is None:
if prev_pkt is not None:
# next_pkt not yet available; use concealment as fallback
recovered = dec.decode_lost(FRAME)
# ... wait for next packet
else:
# If the previous slot was empty and we have a successor,
# try FEC recovery first:
if prev_pkt is None and next_pkt is not None:
recovered = dec.decode_fec(next_pkt, frame_size=FRAME)
pcm = dec.decode_packet(pkt)
prev_pkt = pkt
The decoder automatically falls back to plain concealment when the packet
carries no usable FEC data (CELT-only modes, or when the requested frame size
is longer than the LBRR frame).
Realistic Loss Handling Loop
------------------------------
A production loss handler typically buffers packets and decides on decode vs
conceal vs FEC at playback time:
.. code-block:: python
import ruopus
import numpy as np
enc = ruopus.OpusEncoder(
1,
bitrate=16_000,
application=ruopus.Application.Voip,
signal=ruopus.Signal.Voice,
inband_fec=True,
packet_loss_perc=5,
)
dec = ruopus.OpusDecoder(1)
FRAME = 960 # 20 ms
LOSS_RATE = 0.05 # simulate 5% loss
# Simulate transmission
rng = np.random.default_rng(42)
pcm_in = np.random.randn(FRAME * 10, 1).astype(np.float32)
packets = []
for i in range(0, len(pcm_in), FRAME):
pkt = enc.encode_auto(pcm_in[i:i+FRAME])
packets.append(pkt if rng.random() > LOSS_RATE else None)
# Decode with FEC / PLC
output_blocks = []
for i, pkt in enumerate(packets):
if pkt is not None:
output_blocks.append(dec.decode_packet(pkt))
elif i + 1 < len(packets) and packets[i + 1] is not None:
# FEC: use the next received packet to recover this lost one
output_blocks.append(dec.decode_fec(packets[i + 1], FRAME))
else:
# No next packet yet: conceal
output_blocks.append(dec.decode_lost(FRAME))
recovered = np.concatenate(output_blocks, axis=0)
print(f"Recovered {len(recovered) / 48_000:.2f} s of audio")
Tuning for Loss-Prone Networks
-------------------------------
.. list-table::
:header-rows: 1
:widths: 30 70
* - Setting
- Recommendation
* - ``inband_fec=True``
- Enable on the encoder when SILK modes will be used (Voip / Voice).
* - ``packet_loss_perc``
- Set to the *expected* loss rate. Higher values increase redundancy overhead but improve recovery quality.
* - ``application``
- ``Application.Voip`` or ``Application.Audio``; FEC data is only included in SILK/hybrid packets, and ``RestrictedLowDelay`` never uses SILK so FEC has no effect.
* - Frame size
- 20 ms is the most common SILK frame size and gives FEC the most redundancy budget.