Phase 3a of the DRED integration — the foundation for codec-layer loss
recovery. Adds three new safe wrappers to crates/wzp-codec/src/dred_ffi.rs
over the raw opusic-sys FFI, plus the reconstruction method on the existing
DecoderHandle. No call-site integration yet — that lands in Phase 3b (desktop)
and Phase 3c (Android).
New types:
- `DredDecoderHandle`: owns *mut OpusDREDDecoder from opus_dred_decoder_create.
Used for parsing DRED side-channel data out of arriving Opus packets.
This is a SEPARATE libopus object from OpusDecoder — it has its own
internal state. Freed via opus_dred_decoder_destroy on Drop.
- `DredState`: owns *mut OpusDRED from opus_dred_alloc (a fixed ~10.6 KB
buffer per libopus 1.5). Holds parsed DRED data between the parse and
reconstruct steps. Reusable — parse_into overwrites contents. Tracks
samples_available as a cached u32 so callers don't thread the value
separately. Freed via opus_dred_free on Drop.
New methods:
- `DredDecoderHandle::parse_into(&mut self, state: &mut DredState, packet)`
wraps opus_dred_parse with max_dred_samples=48000 (1s max), sampling_rate
=48000, defer_processing=0. Returns the positive sample offset of the
first decodable DRED sample, 0 if no DRED is present, or an error.
Populates state.samples_available so subsequent reconstruct calls know
the valid offset range.
- `DecoderHandle::reconstruct_from_dred(&mut self, state, offset_samples,
output)` wraps opus_decoder_dred_decode. Reconstructs audio at a specific
sample position (positive, measured backward from the DRED anchor packet)
into a caller-provided output buffer. Validates that 0 < offset_samples
<= state.samples_available() before calling the FFI to catch range bugs.
Tests (+7, wzp-codec total: 68 passing):
- dred_decoder_handle_creates_and_drops
- dred_state_creates_and_drops
- dred_state_reset_zeroes_counter
- dred_parse_and_reconstruct_roundtrip — end-to-end validation. Encodes
60 frames of a 300 Hz sine wave through a DRED-enabled Opus 24k encoder,
parses DRED state out of each arriving packet, asserts that at least one
packet carries non-zero samples_available (DRED warm-up completes within
the first second), then reconstructs 20 ms of audio from inside the
window and asserts non-zero total energy. This is the hard signal that
the full libopus 1.5 DRED FFI chain is correctly wired on our side.
- reconstruct_with_out_of_range_offset_errors — offset > samples_available
is rejected at the Rust layer before the FFI call.
- reconstruct_with_zero_offset_errors — offset <= 0 rejected.
- dred_parse_empty_packet_returns_zero — graceful handling of empty input.
Architectural note (divergence from PRD's literal wording):
The PRD said "jitter buffer takes a Box<dyn DredReconstructor>". After
checking Cargo.toml for wzp-transport, it does NOT depend on wzp-codec —
only wzp-proto. Adding a DRED state ring inside the jitter buffer would
require a new cross-crate dependency and couple the codec-agnostic jitter
buffer to libopus internals. Instead, Phase 3b will put the DRED state
ring and reconstruction dispatch in CallDecoder (one layer up from the
jitter buffer), intercepting the existing PlayoutResult::Missing signal
and attempting reconstruction before falling through to classical PLC.
The jitter buffer itself stays unchanged. Same lookahead/backfill
semantics, cleaner layering. PRD's intent preserved, implementation
refined.
Verification:
- cargo check --workspace: zero errors
- cargo test -p wzp-codec --lib: 68 passing (61 Phase 2 baseline + 7 new)
- The roundtrip test is the acceptance gate — it proves that
opus_dred_decoder_create, opus_dred_alloc, opus_dred_parse, and
opus_decoder_dred_decode all work correctly through our wrappers on
real libopus 1.5.2 output.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
c27b39d553