7a14c3db49
* #2798: contain Symphonia audio decoder panics Guard decoder creation, packet conversion and standalone imports. Keep panicked decoders disabled across reset and reject partial imports while preserving ordinary corrupt-packet recovery. Add synthetic regression and hostile-header tests plus crate documentation. Refs #2798; H.264/HEVC worker containment remains separate. Co-authored-by: Codex <noreply@openai.com> * #2798: document panic strategy limits of audio guards Clarify that decoder panics become CodecError::Decode only with panic=unwind. Document the default wasm32 abort behavior and retain the process-abort and allocation-failure caveats. Co-authored-by: Codex <noreply@openai.com> * codecs README: drop the PR's local test log Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Codex <noreply@openai.com> Co-authored-by: Brandon Thomas <echelon@gmail.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2.6 KiB
filmcraft-codecs
The L2 container and codec hub connects media sources to FilmCraft's software and registered
hardware decoders. It provides container openers, GOP-aware video seeking, packet audio decoding
and standalone audio imports. See the crate-level API documentation in src/lib.rs and
docs/architecture.md for the source and decoder interfaces.
Symphonia audio failure handling (#2798)
Symphonia remains an unmodified MPL-2.0 dependency. Its decoder construction, packet decoding,
sample conversion and reset calls are guarded against unwinding. On targets built with
panic = "unwind", a panic becomes a CodecError::Decode asking the caller to reopen the media.
A packet decoder that panicked is quarantined: later decode calls fail, and reset never calls
into its potentially damaged state.
Because PacketDecoder::reset has no error return, a panic during reset is logged and reported
by the next decode. A newly constructed decoder can be used to retry.
Standalone imports guard the whole attempt, including format probing, packet reading and decoder construction. A decoder panic aborts the import even if earlier packets decoded; partially decoded samples are not returned as a successful source. Ordinary returned errors retain the existing behavior: packet decoding returns an error without quarantining the decoder, and standalone imports skip corrupt packets. This change does not change that pre-existing damaged-file policy or harden the separate H.264/HEVC worker paths in #2798.
The default wasm32-unknown-unknown target uses panic = "abort", so decoder panics cannot be
caught or converted to CodecError::Decode there. The guard handles Rust unwinding; it cannot
recover from a process abort or an allocation failure that aborts. It does not replace input
validation or repair bugs inside a dependency.
Tests
src/audio_panic_tests.rs wraps a real PCM decoder through Symphonia's public Decoder API
with per-instance synthetic decode/reset failures. No dependency implementation is copied.
The tests check errors after a successful packet, no reuse after panic (including reset),
fresh-decoder recovery, ordinary-error recovery, constructor failure, and rejection of partial
standalone imports. WAV truncations and header mutations run under catch_unwind; all fixtures
are generated in memory. Existing MP3, AIFF, FLAC and Vorbis tests cover the normal
audio paths with FFmpeg used only as an external fixture generator/oracle.
cargo test -p filmcraft-codecs --lib audio::panic_tests
FILMCRAFT_REQUIRE_ORACLES=1 cargo test -p filmcraft-codecs
cargo xtask ci