Files
craft-libs/crates/audio/src/read/source.rs
T
Aleksander HelgakerandClaude Opus 5.5 38740b43a9 craft-audio: core types, WAV/AIFF read and write, peaks, symphonia (#441)
* craft-audio: core types, WAV/AIFF read and write, peaks, symphonia

The new crate without any codec module: what every later codec plugs
into.

- Shared types: `AudioBuffer`, `AudioInfo`, `ChannelLayout`/`Speaker`,
  `AudioError`, `EncodeOptions` (built with `new` and `with_*`),
  `EncodeFormat`, `BitDepth`, `BwfInfo`, `SampleFormat`.
- WAV/BWF/RF64 and AIFF/AIFF-C reading and writing from SoundCraft's
  `soundcraft-audio-io`, kept over EffectCraft's and FilmCraft's
  smaller writers (only it has BWF, dither, any speaker mask and
  streaming without a known length). `encode` and `FileEncoder` behind
  `pcm-encode`; `lossless-encode` and `encode` turn it on.
- `decode`, `probe`, `tracks` and the streaming, seekable `Decoder`
  (feature `decode-native`). The native path reads WAV, AIFF, and PCM in
  MP4/MOV and Matroska through craft-media's demuxers, packet by packet,
  with edit lists and `CodecDelay`/`DiscardPadding` applied.
  `TrackDecoder` decodes PCM; each codec PR adds its codec to it.
- symphonia 0.6 (MPL-2.0, used unmodified) behind the `symphonia`
  feature, part of `decode`: the fallback for every format with no
  native decoder yet. Its size fields are checked before it reads, and
  its panics are caught where they unwind.
- `peaks`: the min/max/RMS pyramid for waveform drawing.

Workspace: craft-media is a workspace dependency without default
features, so an encode-only craft-audio does not build the MP4
demuxer, and `symphonia-bundle-flac` builds without overflow checks in
dev profiles (its 32-bit LPC restore wraps on valid input).

CI: `audio.yml`, with clippy per feature, rustdoc, WASM, MSRV, and the
tests with ffmpeg oracles.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* craft-audio: review fixes (CodeRabbit on #441)

- Reading: AIFF that declares frames without an SSND chunk is Malformed; a Matroska PCM track's
  length counts from its first frame; seek targets saturate; an empty FLAC has one track; a
  failed header read is an Io error; deinterleave allocates fallibly; concealed silence is capped
  like a decoded packet, and symphonia's uses the damaged packet's own duration when known.
- Peaks sum squares in f64, so loud float samples give a finite RMS.
- Writing: .aifc maps to AIFF; BWF text is cut at a character boundary; a WAV byte rate past
  32 bits is an error; the FileEncoder docs say nothing may follow the sink's position.
- README: the Limits list says which codecs go through symphonia and which MP4 edit lists apply.
- Tests for each, alias and dither coverage, and a FLAC case in the routing oracle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* craft-audio: review fixes, second round (CodeRabbit on #441)

- Every header read is checked: `Native::open`, `native::tracks` and the no-symphonia error read
  it with `head_checked`. craft-media demuxer errors that are I/O failures (not a file ending
  early) are returned as `AudioError::Io` instead of sending the file to the other path.
- A Matroska track's presented length runs from its first frame plus `CodecDelay` (unclamped,
  in timestamp ticks with the delay rounded to one) to its end.
- symphonia's concealment allocates fallibly, and a damaged first packet is concealed when the
  demuxer gives its duration. `deinterleave` reserves its channel list fallibly too.
- `TrackDecoder::conceal` documents its cap at the decode limit.
- Tests: an I/O failure past the first 64 KiB, codec delay with the first block at -20, 0 and
  50 ms (checked with `probe`), a seek back after an overshoot, and the loud-sample RMS value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* craft-audio: TrackDecoder::conceal returns a Result

Concealment allocates fallibly and fails with TooLarge when the silence would pass the 2^30-sample
decode limit, instead of returning less than the packet's length. The native path, the README,
the packets example and the doc example pass the error on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* craft-audio: review fixes, third round (CodeRabbit on #441)

- Concealed silence is held to the decode limit inside pcm::silence, so symphonia's path checks
  frames × channels too, and symphonia's decoded audio is copied into fallibly allocated planes.
- TrackDecoder::reset forgets the last packet's length.
- Without symphonia, a damaged MP4, Matroska or Ogg file (truncated, invalid, no moov) is
  Malformed instead of Unsupported; a feature the demuxer does not read still names the build.
- Tests: an MP4 with no moov in a native-only build, conceal after a reset and past the limit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* craft-audio: review fixes, fourth round (CodeRabbit on #441)

- A file the native demuxers find damaged is Malformed with symphonia too, when symphonia calls
  it unsupported; before, an ftyp-only MP4 was Unsupported in symphonia builds.
- symphonia's decoded blocks are held to the 2^30-sample decode limit before allocating.
- Symph::seek forgets the last packet's length, so a lost packet after a seek is not concealed
  with the length of one before it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* craft-audio: review fixes, fifth round (CodeRabbit on #441)

- The damaged-file test covers Matroska as well as MP4, and fails when either branch of
  native::damage is removed.
- native::damage leaves out Ogg: ogg::open reports no damage (it skips damaged pages and calls a
  file with none it can read not Ogg), and symphonia reports damaged Ogg as malformed itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* craft-audio: run the ffmpeg oracle tests on ubuntu-26.04

ubuntu-latest's apt ships ffmpeg 6.1.1, which writes MP2 and E-AC-3 in
Matroska with ends a few milliseconds early, so the routing tests on the
later codec PRs cannot pass on it. ubuntu-26.04 ships ffmpeg 8.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 10:25:57 +01:00

136 lines
5.2 KiB
Rust

//! What the decoders read from: borrowed bytes or a shared [`ByteSource`], with small typed reads.
use crate::{AudioError, Result};
use craft_media::ByteSource;
#[cfg(feature = "symphonia")]
use std::borrow::Cow;
use std::io;
use std::sync::Arc;
/// A source a [`crate::Decoder`] can own: a [`ByteSource`] that is `Send + Sync + 'static`, so
/// the decoder can move between threads. On single-threaded WebAssembly (no `atomics`), where
/// sources such as a JS `Blob` reader are not `Send`, any `ByteSource + 'static` is one.
/// Implemented for every type that qualifies.
#[cfg(not(all(target_arch = "wasm32", not(target_feature = "atomics"))))]
pub trait SharedSource: ByteSource + Send + Sync + 'static {}
#[cfg(not(all(target_arch = "wasm32", not(target_feature = "atomics"))))]
impl<T: ByteSource + Send + Sync + 'static> SharedSource for T {}
/// A source a [`crate::Decoder`] can own: a [`ByteSource`] that is `Send + Sync + 'static`, so
/// the decoder can move between threads. On single-threaded WebAssembly (no `atomics`), where
/// sources such as a JS `Blob` reader are not `Send`, any `ByteSource + 'static` is one.
/// Implemented for every type that qualifies.
#[cfg(all(target_arch = "wasm32", not(target_feature = "atomics")))]
pub trait SharedSource: ByteSource + 'static {}
#[cfg(all(target_arch = "wasm32", not(target_feature = "atomics")))]
impl<T: ByteSource + 'static> SharedSource for T {}
/// The bytes a decoder reads: a borrowed buffer, or a source shared with the caller (a file, a
/// network-backed buffer).
#[derive(Clone)]
pub(crate) enum Src<'a> {
Slice(&'a [u8]),
Shared(Arc<dyn SharedSource>),
}
impl ByteSource for Src<'_> {
fn len(&self) -> u64 {
match self {
Src::Slice(b) => <[u8]>::len(b) as u64,
Src::Shared(s) => s.len(),
}
}
fn read_at(&self, offset: u64, buf: &mut [u8]) -> io::Result<()> {
match self {
Src::Slice(b) => b.read_at(offset, buf),
Src::Shared(s) => s.read_at(offset, buf),
}
}
}
impl Src<'_> {
/// The source's length in bytes.
pub(crate) fn size(&self) -> u64 {
ByteSource::len(self)
}
/// `n` bytes at `pos`, or `None` when they are not all there.
pub(crate) fn bytes(&self, pos: u64, n: usize) -> Option<Vec<u8>> {
if let Src::Slice(b) = self {
let start = usize::try_from(pos).ok()?;
return b.get(start..start.checked_add(n)?).map(<[u8]>::to_vec);
}
let mut v = vec![0; n];
self.read_at(pos, &mut v).ok()?;
Some(v)
}
/// `n` bytes at `pos` for decoding: missing bytes are [`AudioError::Malformed`], any other
/// failure of the source is [`AudioError::Io`].
pub(crate) fn read(&self, pos: u64, n: usize) -> Result<Vec<u8>> {
let mut v = vec![0; n];
self.read_at(pos, &mut v).map_err(io_error)?;
Ok(v)
}
/// Up to `n` bytes at `pos` for decoding, fewer near the end of the source; errors as
/// [`Src::read`].
pub(crate) fn read_upto(&self, pos: u64, n: usize) -> Result<Vec<u8>> {
let n = n.min(usize::try_from(self.size().saturating_sub(pos)).unwrap_or(usize::MAX));
self.read(pos, n)
}
/// Up to `n` bytes at `pos`: fewer near the end of the source.
pub(crate) fn bytes_upto(&self, pos: u64, n: usize) -> Vec<u8> {
let n = n.min(usize::try_from(self.size().saturating_sub(pos)).unwrap_or(usize::MAX));
self.bytes(pos, n).unwrap_or_default()
}
fn array<const N: usize>(&self, pos: u64) -> Option<[u8; N]> {
let mut a = [0; N];
self.read_at(pos, &mut a).ok()?;
Some(a)
}
pub(crate) fn tag(&self, pos: u64) -> Option<[u8; 4]> {
self.array(pos)
}
pub(crate) fn le_u32(&self, pos: u64) -> Option<u32> {
self.array(pos).map(u32::from_le_bytes)
}
pub(crate) fn be_u32(&self, pos: u64) -> Option<u32> {
self.array(pos).map(u32::from_be_bytes)
}
/// The first bytes of the source, enough to detect its format; a source that fails to read
/// them is [`AudioError::Io`], so the failure is not taken for an unknown format.
pub(crate) fn head_checked(&self) -> Result<Vec<u8>> {
self.read_upto(0, 64 * 1024)
}
/// The whole source in memory: borrowed for a buffer, read once for a shared source.
#[cfg(feature = "symphonia")]
pub(crate) fn whole(&self) -> Result<Cow<'_, [u8]>> {
match self {
Src::Slice(b) => Ok(Cow::Borrowed(b)),
Src::Shared(s) => {
let n = usize::try_from(s.len()).map_err(|_| AudioError::TooLarge("the source does not fit in memory".into()))?;
let mut v = Vec::new();
v.try_reserve_exact(n).map_err(|_| AudioError::TooLarge("the source does not fit in memory".into()))?;
v.resize(n, 0);
s.read_at(0, &mut v).map_err(io_error)?;
Ok(Cow::Owned(v))
}
}
}
}
/// A read failure as an [`AudioError`]: bytes past the end are a truncated or lying file
/// ([`AudioError::Malformed`]); anything else is the source failing ([`AudioError::Io`]).
pub(crate) fn io_error(e: io::Error) -> AudioError {
if e.kind() == io::ErrorKind::UnexpectedEof { AudioError::Malformed(e.to_string()) } else { AudioError::Io(e) }
}