mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:42:27 +00:00
* craft-audio: native MP3 (Layer III) decoder (feature `mp3-decode`) A clean-room Layer III decoder written from ISO/IEC 11172-3 and 13818-3: MPEG-1, MPEG-2 and MPEG-2.5 (8-48 kHz), CBR and VBR, mono, stereo, dual channel and joint stereo (mid/side and intensity), long, short and mixed blocks, and the bit reservoir. It shares the encoder's Huffman and scalefactor band tables and the MP1/MP2 synthesis filter. `decode`, `Decoder` and `TrackDecoder` now read raw .mp3 files and MP3 in MP4 and Matroska natively instead of through symphonia. A Xing / Info / VBRI frame is not a packet, and the LAME tag's encoder delay and padding are applied, so a file decodes to its exact presented length. The seek pre-roll covers how far back the bit reservoir can reach, so a seek is bit-exact. symphonia stays the fallback for free-format MP3. The encoder moves to mp3/encoder.rs so that each half builds without the other. * craft-audio: MP3 review and CI fixes - Huffman: big values stop at the granule's part2_3_length. A damaged granule no longer reads the next granule's bits, as ffmpeg does. - Joint stereo runs on the lines in coded order, before short blocks are reordered, as ffmpeg and libmad do. Where the two channels' block layouts differ, against the specification, each channel is then reordered by its own layout. - Seek pre-roll: sized from the smallest frame the stream can hold (the lowest bit rate for its version, rate, mode and CRC), not the last frame, so a seek into a VBR stream's small frames still has the reservoir. The decoder learns the stream's format from its first frame. - Mixed-block oracle test: edit only granules whose scalefactors take no bits, so the edited streams stay valid, and not before a pure short block. ffmpeg's short-block IMDCT drops overlap that a mixed block's long subbands carry, where the specification adds it. Use 16 kHz instead of 12 kHz. - Routing oracle: ffmpeg before 9 decodes the 1105 samples of the MP3 Matroska CodecDelay. * craft-audio: MPEG audio packets of several frames keep their length An MP4 or Matroska packet may hold several MP1/MP2/MP3 frames. TrackDecoder now counts the frames each packet holds from their headers: - frames_per_packet is None once a packet in the lookahead or a decoded packet has held several frames, so an MP4 track's length is no longer capped at one frame per sample and the container's timing decides. - Concealment is the length of the frames a damaged packet holds. For MP3 a packet lost whole is as long as the last packet, and one frame before any is decoded. Also corrects the Huffman doc comment: a big-value pair that starts before the granule's end is kept whole, as ffmpeg does. * craft-audio: MPEG audio concealment after partial packets and before the first - A packet whose later frame fails decodes only in part: like AC-3, it no longer replaces the length of the last whole packet that concealment uses. - MP1/MP2: a packet lost before any has decoded, or right after a seek, is one frame (384 or 1152 samples) of silence rather than none, as MP3's already is. --------- Co-authored-by: alehel <git@ornumhelgaker.no>
633 lines
27 KiB
Rust
633 lines
27 KiB
Rust
//! Format detection, probing and decoding. The native path (craft-media's demuxers, the WAV and
|
||
//! AIFF readers, and [`TrackDecoder`]) comes first; symphonia decodes the rest.
|
||
//!
|
||
//! `native.rs` opens a file natively or returns `None`, and `symph.rs` is the fallback, so a new
|
||
//! native decoder takes its formats over without an API change. Removing symphonia means deleting
|
||
//! `symph.rs` and its size checks, the `symphonia` feature and the workspace's
|
||
//! `symphonia-bundle-flac` profile override.
|
||
|
||
mod aiff;
|
||
#[cfg(feature = "symphonia")]
|
||
mod caf;
|
||
#[cfg(feature = "symphonia")]
|
||
mod flac;
|
||
#[cfg(feature = "symphonia")]
|
||
mod mp4;
|
||
mod native;
|
||
mod raw;
|
||
mod source;
|
||
#[cfg(feature = "symphonia")]
|
||
mod symph;
|
||
mod wav;
|
||
|
||
use crate::{AudioBuffer, AudioError, AudioInfo, ChannelLayout, CodecId, Container, Result};
|
||
use native::Native;
|
||
pub use raw::{RawPcm, aiff_pcm, wav_pcm};
|
||
pub use source::SharedSource;
|
||
use source::Src;
|
||
use std::sync::Arc;
|
||
#[cfg(feature = "symphonia")]
|
||
use symph::Symph;
|
||
|
||
/// The decode limit [`decode`] applies unless [`DecodeOptions::max_samples`] says otherwise:
|
||
/// 2^30 samples, 4 GiB of `f32`.
|
||
pub const DEFAULT_MAX_SAMPLES: u64 = crate::pcm::MAX_DECODE_SAMPLES;
|
||
|
||
/// Size of an ID3v2 tag at the start of `b`, if there is one. The 10-byte footer flag (`0x10`)
|
||
/// exists only in ID3v2.4; in v2.2/v2.3 that bit is reserved and must not extend the skip.
|
||
pub(crate) fn id3v2_len(b: &[u8]) -> Option<usize> {
|
||
if b.get(..3)? != b"ID3" {
|
||
return None;
|
||
}
|
||
let version = *b.get(3)?;
|
||
let flags = *b.get(5)?;
|
||
let size = b.get(6..10)?.iter().fold(0usize, |acc, &x| (acc << 7) | usize::from(x & 0x7F));
|
||
let footer = version == 4 && flags & 0x10 != 0;
|
||
Some(10 + size + if footer { 10 } else { 0 })
|
||
}
|
||
|
||
fn detect_by_magic(b: &[u8], depth: u32) -> Option<Container> {
|
||
let head = |n: usize| b.get(..n);
|
||
if wav::is_wav(b) {
|
||
return Some(Container::Wav);
|
||
}
|
||
if aiff::is_aiff(b) {
|
||
return Some(Container::Aiff);
|
||
}
|
||
match head(4)? {
|
||
b"fLaC" => return Some(Container::Flac),
|
||
b"OggS" => return Some(Container::Ogg),
|
||
b"caff" => return Some(Container::Caf),
|
||
// Matroska and WebM differ only in the EBML header's DocType, within its first bytes.
|
||
[0x1A, 0x45, 0xDF, 0xA3] => {
|
||
let header = b.get(..64.min(b.len())).unwrap_or_default();
|
||
return Some(if header.windows(4).any(|w| w == b"webm") { Container::WebM } else { Container::Matroska });
|
||
}
|
||
_ => {}
|
||
}
|
||
if b.get(4..8) == Some(b"ftyp") {
|
||
return Some(if b.get(8..12) == Some(b"qt ") { Container::QuickTime } else { Container::Mp4 });
|
||
}
|
||
if let Some(len) = id3v2_len(b) {
|
||
if depth == 0
|
||
&& let Some(f) = b.get(len..).and_then(|rest| detect_by_magic(rest, 1))
|
||
{
|
||
return Some(f);
|
||
}
|
||
return Some(Container::MpegAudio);
|
||
}
|
||
let (b0, b1) = (*b.first()?, *b.get(1)?);
|
||
if b0 == 0x0B && b1 == 0x77 {
|
||
return Some(Container::Ac3);
|
||
}
|
||
if b0 == 0xFF && b1 & 0xE0 == 0xE0 {
|
||
let layer = (b1 >> 1) & 0x3;
|
||
if b1 & 0xF0 == 0xF0 && layer == 0 {
|
||
return Some(Container::Adts);
|
||
}
|
||
if layer != 0 {
|
||
return Some(Container::MpegAudio);
|
||
}
|
||
}
|
||
None
|
||
}
|
||
|
||
/// The file extensions of the formats [`decode`] reads, lower case and without the dot: what a
|
||
/// file picker or a browser filters by. Each is a hint [`detect_container`] knows; a file's
|
||
/// contents still decide what it is. Without the `symphonia` feature the formats only symphonia
|
||
/// decodes (FLAC, CAF) are left out.
|
||
#[cfg(feature = "symphonia")]
|
||
pub const DECODE_EXTENSIONS: &[&str] = &[
|
||
"wav", "wave", "bwf", "rf64", "aif", "aiff", "aifc", "flac", "mp3", "mp2", "mp1", "mpa", "ogg", "oga", "opus", "m4a", "m4b", "mp4", "mov", "aac",
|
||
"adts", "ac3", "eac3", "ec3", "caf", "mkv", "mka", "webm",
|
||
];
|
||
/// The file extensions of the formats [`decode`] reads, lower case and without the dot: what a
|
||
/// file picker or a browser filters by. Each is a hint [`detect_container`] knows; a file's
|
||
/// contents still decide what it is. Without the `symphonia` feature the formats only symphonia
|
||
/// decodes (FLAC, CAF) are left out.
|
||
#[cfg(not(feature = "symphonia"))]
|
||
pub const DECODE_EXTENSIONS: &[&str] = &[
|
||
"wav", "wave", "bwf", "rf64", "aif", "aiff", "aifc", "mp3", "mp2", "mp1", "mpa", "ogg", "oga", "opus", "m4a", "m4b", "mp4", "mov", "aac", "adts",
|
||
"ac3", "eac3", "ec3", "mkv", "mka", "webm",
|
||
];
|
||
|
||
fn detect_by_ext(ext: &str) -> Option<Container> {
|
||
Some(match ext.trim_start_matches('.').to_ascii_lowercase().as_str() {
|
||
"wav" | "wave" | "bwf" | "rf64" => Container::Wav,
|
||
"aif" | "aiff" | "aifc" => Container::Aiff,
|
||
"flac" => Container::Flac,
|
||
"mp3" | "mp2" | "mp1" | "mpa" => Container::MpegAudio,
|
||
"ogg" | "oga" | "opus" => Container::Ogg,
|
||
"aac" | "adts" => Container::Adts,
|
||
"m4a" | "m4b" | "mp4" => Container::Mp4,
|
||
"mov" => Container::QuickTime,
|
||
"mkv" | "mka" => Container::Matroska,
|
||
"webm" => Container::WebM,
|
||
"ac3" | "eac3" | "ec3" => Container::Ac3,
|
||
"caf" => Container::Caf,
|
||
_ => return None,
|
||
})
|
||
}
|
||
|
||
/// The container of a file, by its magic bytes, falling back to the extension hint (`"wav"`,
|
||
/// `".flac"`); `None` when neither says.
|
||
///
|
||
/// ```
|
||
/// use craft_audio::{Container, detect_container};
|
||
///
|
||
/// assert_eq!(detect_container(b"fLaC\0\0\0\x22", None), Some(Container::Flac));
|
||
/// assert_eq!(detect_container(&[0; 16], Some("wav")), Some(Container::Wav));
|
||
/// assert_eq!(detect_container(&[0; 16], None), None);
|
||
/// ```
|
||
pub fn detect_container(bytes: &[u8], ext_hint: Option<&str>) -> Option<Container> {
|
||
detect_by_magic(bytes, 0).or_else(|| ext_hint.and_then(detect_by_ext))
|
||
}
|
||
|
||
/// Options for [`Decoder`], [`decode_with`] and [`probe_with`].
|
||
///
|
||
/// `#[non_exhaustive]`: start from `DecodeOptions::default()` and use the `with_*` methods.
|
||
#[non_exhaustive]
|
||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
|
||
pub struct DecodeOptions {
|
||
/// Which audio track to decode, counted among the file's audio tracks as [`tracks`] lists
|
||
/// them; `None` is the first.
|
||
pub track: Option<usize>,
|
||
/// The most samples (frames × channels) [`decode_with`] returns; a longer file is
|
||
/// [`AudioError::TooLarge`]. The default, [`DEFAULT_MAX_SAMPLES`], is 2^30 samples: 4 GiB of
|
||
/// `f32`, about 3 hours of 48 kHz stereo. It is a ceiling for trusted input, not a budget:
|
||
/// a small compressed file (silent FLAC, say) can decode to all of it, and [`decode_with`]
|
||
/// holds the whole result in memory. A caller that decodes files it does not control sets
|
||
/// this to what it can hold, or reads blocks with [`Decoder`], which keeps nothing and has no
|
||
/// limit.
|
||
pub max_samples: u64,
|
||
}
|
||
|
||
impl Default for DecodeOptions {
|
||
fn default() -> Self {
|
||
DecodeOptions { track: None, max_samples: DEFAULT_MAX_SAMPLES }
|
||
}
|
||
}
|
||
|
||
impl DecodeOptions {
|
||
/// Decode the audio track at index `track` (see [`DecodeOptions::track`]).
|
||
pub fn with_track(mut self, track: usize) -> DecodeOptions {
|
||
self.track = Some(track);
|
||
self
|
||
}
|
||
|
||
/// Set [`DecodeOptions::max_samples`].
|
||
pub fn with_max_samples(mut self, max_samples: u64) -> DecodeOptions {
|
||
self.max_samples = max_samples;
|
||
self
|
||
}
|
||
}
|
||
|
||
/// One audio track of a file, as [`tracks`] lists it.
|
||
#[non_exhaustive]
|
||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
|
||
pub struct TrackInfo {
|
||
/// The value for [`DecodeOptions::track`].
|
||
pub index: usize,
|
||
/// The codec the container names (an AAC track that turns out to be HE-AAC is `Aac` here). A
|
||
/// raw ADTS stream names none, so this is what decoding finds.
|
||
pub codec: CodecId,
|
||
/// The sample rate the container declares, if it does; for raw ADTS, the decoded rate.
|
||
pub sample_rate: Option<u32>,
|
||
/// The channel count the container declares, if it does.
|
||
pub channels: Option<u16>,
|
||
}
|
||
|
||
/// The decoder behind a [`Decoder`].
|
||
enum Inner<'a> {
|
||
Native(Box<Native<'a>>),
|
||
#[cfg(feature = "symphonia")]
|
||
Symph(Box<Symph>),
|
||
}
|
||
|
||
/// A file's audio, decoded block by block: the streaming counterpart of [`decode`], with seeking
|
||
/// and track choice.
|
||
///
|
||
/// Native formats (WAV, AIFF, AAC, Opus, AC-3/E-AC-3, MP1/MP2 and PCM in MP4/MOV, Matroska/WebM and
|
||
/// Ogg, and raw ADTS, AC-3 and MPEG audio streams) read their sample data from the source packet by
|
||
/// packet. The container's packet index is held in memory (tens of bytes per packet), and opening
|
||
/// an Ogg or Matroska file or a raw
|
||
/// stream reads through the whole file to build it; WAV and AIFF need no index. Formats symphonia
|
||
/// decodes (MP3, FLAC, ALAC, Vorbis, CAF, ADPCM, A-law, µ-law) read the whole source into memory
|
||
/// first; their decoded audio still streams.
|
||
///
|
||
/// ```no_run
|
||
/// # fn demo() -> craft_audio::Result<()> {
|
||
/// use craft_audio::{DecodeOptions, Decoder};
|
||
///
|
||
/// let file = std::fs::File::open("long-recording.m4a")?;
|
||
/// let mut dec = Decoder::open(file, Some("m4a"), &DecodeOptions::default())?;
|
||
/// println!("{} {} Hz {}", dec.info().codec.name(), dec.info().sample_rate, dec.info().layout);
|
||
/// dec.seek(48_000 * 60)?; // one minute in
|
||
/// while let Some(block) = dec.next_block()? {
|
||
/// // block.channels: planar f32, WAV channel order
|
||
/// }
|
||
/// # Ok(()) }
|
||
/// ```
|
||
pub struct Decoder<'a> {
|
||
inner: Inner<'a>,
|
||
}
|
||
|
||
impl std::fmt::Debug for Decoder<'_> {
|
||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||
f.debug_struct("Decoder").field("info", self.info()).field("length_known", &self.length_known()).finish_non_exhaustive()
|
||
}
|
||
}
|
||
|
||
impl Decoder<'static> {
|
||
/// Open a file read from `source`: a `std::fs::File`, a shared buffer, a
|
||
/// [`crate::ReadSeekSource`] around any `Read + Seek`, or any [`crate::ByteSource`] that is
|
||
/// [`SharedSource`] (`Send + Sync`, except on single-threaded WebAssembly). `ext_hint` is the
|
||
/// file's extension, used only when its bytes do not say what it is.
|
||
pub fn open(source: impl SharedSource, ext_hint: Option<&str>, opts: &DecodeOptions) -> Result<Decoder<'static>> {
|
||
Decoder::from_src(Src::Shared(Arc::new(source)), ext_hint, opts)
|
||
}
|
||
}
|
||
|
||
impl<'a> Decoder<'a> {
|
||
/// Open a file held in memory.
|
||
pub fn from_bytes(bytes: &'a [u8], ext_hint: Option<&str>, opts: &DecodeOptions) -> Result<Decoder<'a>> {
|
||
Decoder::from_src(Src::Slice(bytes), ext_hint, opts)
|
||
}
|
||
|
||
fn from_src(src: Src<'a>, ext_hint: Option<&str>, opts: &DecodeOptions) -> Result<Decoder<'a>> {
|
||
let head = src.head_checked()?;
|
||
let container = detect_container(&head, ext_hint);
|
||
if let Some(n) = Native::open(&src, container, opts.track) {
|
||
return Ok(Decoder { inner: Inner::Native(Box::new(n?)) });
|
||
}
|
||
Decoder::fallback(src, container, opts)
|
||
}
|
||
|
||
/// A file the native path does not read: symphonia's.
|
||
#[cfg(feature = "symphonia")]
|
||
fn fallback(src: Src<'a>, container: Option<Container>, opts: &DecodeOptions) -> Result<Decoder<'a>> {
|
||
let mut s = Symph::open(src.whole()?, container, opts.track).map_err(|e| damaged_or(&src, container, e))?;
|
||
// A WAV with a codec symphonia reads (ADPCM, A-law, ...) keeps its BWF metadata.
|
||
if container == Some(Container::Wav)
|
||
&& let Ok(wav::WavParse::Foreign { bwf }) = wav::parse(&src)
|
||
{
|
||
s.set_bwf(bwf);
|
||
}
|
||
Ok(Decoder { inner: Inner::Symph(Box::new(s)) })
|
||
}
|
||
|
||
/// A file the native path does not read, without symphonia.
|
||
#[cfg(not(feature = "symphonia"))]
|
||
fn fallback(src: Src<'a>, _container: Option<Container>, _opts: &DecodeOptions) -> Result<Decoder<'a>> {
|
||
Err(not_built(&src))
|
||
}
|
||
|
||
/// What the file holds. `frames` is 0 until decoded when the container does not say how long
|
||
/// the track is ([`Decoder::length_known`]).
|
||
pub fn info(&self) -> &AudioInfo {
|
||
match &self.inner {
|
||
Inner::Native(n) => n.info(),
|
||
#[cfg(feature = "symphonia")]
|
||
Inner::Symph(s) => s.info(),
|
||
}
|
||
}
|
||
|
||
/// Whether [`AudioInfo::frames`] came from the file rather than being unknown (an MP3 without
|
||
/// a Xing frame, PCM in Matroska).
|
||
pub fn length_known(&self) -> bool {
|
||
match &self.inner {
|
||
Inner::Native(n) => n.frames_known(),
|
||
#[cfg(feature = "symphonia")]
|
||
Inner::Symph(s) => s.frames_known(),
|
||
}
|
||
}
|
||
|
||
/// What [`probe`] reports, for a decoder opened on any source: the info from the headers, or,
|
||
/// when they give no length, the info after decoding the rest of the track to count it.
|
||
///
|
||
/// ```no_run
|
||
/// # fn demo() -> craft_audio::Result<()> {
|
||
/// use craft_audio::{DecodeOptions, Decoder};
|
||
///
|
||
/// let info = Decoder::open(std::fs::File::open("take.mp3")?, Some("mp3"), &DecodeOptions::default())?.probe()?;
|
||
/// println!("{:.1} s", info.duration_secs());
|
||
/// # Ok(()) }
|
||
/// ```
|
||
pub fn probe(mut self) -> Result<AudioInfo> {
|
||
if self.length_known() {
|
||
return Ok(self.info().clone());
|
||
}
|
||
let (mut frames, mut channels) = (0u64, None);
|
||
while let Some(b) = self.next_block()? {
|
||
frames = frames.saturating_add(b.frames() as u64);
|
||
channels.get_or_insert(b.channels.len());
|
||
}
|
||
let mut info = self.info().clone();
|
||
info.frames = frames;
|
||
fit_channels(&mut info, channels);
|
||
Ok(info)
|
||
}
|
||
|
||
/// The next block of decoded audio (planar `f32`, WAV channel order when the layout is
|
||
/// ordered), or `None` at the end. Blocks follow the codec's packets, so their length varies.
|
||
/// A damaged packet is concealed and counted in [`AudioInfo::damaged`]; a source that fails a read gives
|
||
/// [`AudioError::Io`] and that packet is skipped, so call [`Decoder::seek`] to retry it.
|
||
pub fn next_block(&mut self) -> Result<Option<AudioBuffer>> {
|
||
match &mut self.inner {
|
||
Inner::Native(n) => n.next_block(),
|
||
#[cfg(feature = "symphonia")]
|
||
Inner::Symph(s) => s.next_block(),
|
||
}
|
||
}
|
||
|
||
/// Continue decoding from frame `frame` (samples per channel from the start); the next block
|
||
/// starts exactly there. Returns the frame decoding resumes at.
|
||
pub fn seek(&mut self, frame: u64) -> Result<u64> {
|
||
match &mut self.inner {
|
||
Inner::Native(n) => n.seek(frame),
|
||
#[cfg(feature = "symphonia")]
|
||
Inner::Symph(s) => s.seek(frame),
|
||
}
|
||
}
|
||
}
|
||
|
||
/// Read a file's container, codec, sample rate, channel layout, length and BWF metadata from its
|
||
/// headers. When the headers give no length (an MP3 without a Xing frame, PCM in Matroska), the
|
||
/// file is decoded to count it. For a file on disk, use [`Decoder::probe`].
|
||
///
|
||
/// ```
|
||
/// # #[cfg(feature = "pcm-encode")] {
|
||
/// use craft_audio::{AudioBuffer, ChannelLayout, CodecId, Container, EncodeOptions, encode, probe};
|
||
///
|
||
/// let wav = encode(&AudioBuffer::new(48_000, 2, 4800), &EncodeOptions::default()).unwrap();
|
||
/// let info = probe(&wav, Some("wav")).unwrap();
|
||
/// assert_eq!((info.container, info.codec, info.layout), (Container::Wav, CodecId::Pcm, ChannelLayout::STEREO));
|
||
/// assert_eq!((info.sample_rate, info.frames), (48_000, 4800));
|
||
/// # }
|
||
/// ```
|
||
pub fn probe(bytes: &[u8], ext_hint: Option<&str>) -> Result<AudioInfo> {
|
||
probe_with(bytes, ext_hint, &DecodeOptions::default())
|
||
}
|
||
|
||
/// [`probe`] for the track `opts` names.
|
||
///
|
||
/// ```
|
||
/// # #[cfg(feature = "pcm-encode")] {
|
||
/// use craft_audio::{AudioBuffer, EncodeOptions, encode};
|
||
/// let wav = encode(&AudioBuffer::new(48_000, 2, 4800), &EncodeOptions::default()).unwrap();
|
||
/// use craft_audio::{DecodeOptions, probe_with};
|
||
///
|
||
/// let info = probe_with(&wav, Some("wav"), &DecodeOptions::default().with_track(0)).unwrap();
|
||
/// assert_eq!((info.channels, info.frames), (2, 4800));
|
||
/// assert!(probe_with(&wav, Some("wav"), &DecodeOptions::default().with_track(1)).is_err());
|
||
/// # }
|
||
/// ```
|
||
pub fn probe_with(bytes: &[u8], ext_hint: Option<&str>, opts: &DecodeOptions) -> Result<AudioInfo> {
|
||
Decoder::from_bytes(bytes, ext_hint, opts)?.probe()
|
||
}
|
||
|
||
/// Decode the first audio track of a file to planar `f32`, trimmed to its presentation length, in
|
||
/// WAV channel order when [`AudioInfo::layout`] is ordered. Use [`Decoder`] to stream a long
|
||
/// file instead, and [`decode_with`] for another track or size limit.
|
||
///
|
||
/// ```
|
||
/// # #[cfg(all(feature = "flac-encode", feature = "symphonia"))] {
|
||
/// use craft_audio::{AudioBuffer, EncodeFormat, EncodeOptions, decode, encode};
|
||
///
|
||
/// let tone: Vec<f32> = (0..4800).map(|i| (i as f32 * 0.05).sin() * 0.5).collect();
|
||
/// let flac = encode(&AudioBuffer { sample_rate: 48_000, channels: vec![tone] }, &EncodeOptions::new(EncodeFormat::Flac)).unwrap();
|
||
/// let (info, buf) = decode(&flac, None).unwrap();
|
||
/// assert_eq!((info.channels, buf.frames()), (1, 4800));
|
||
/// # }
|
||
/// ```
|
||
pub fn decode(bytes: &[u8], ext_hint: Option<&str>) -> Result<(AudioInfo, AudioBuffer)> {
|
||
decode_with(bytes, ext_hint, &DecodeOptions::default())
|
||
}
|
||
|
||
/// [`decode`] with options: another track, or another size limit. [`decode`] and `decode_with`
|
||
/// keep every decoded sample, so for untrusted files pass a limit
|
||
/// ([`DecodeOptions::with_max_samples`]) that the host can hold, or stream with [`Decoder`].
|
||
///
|
||
/// ```
|
||
/// # #[cfg(feature = "pcm-encode")] {
|
||
/// use craft_audio::{AudioBuffer, EncodeOptions, encode};
|
||
/// let wav = encode(&AudioBuffer::new(48_000, 2, 4800), &EncodeOptions::default()).unwrap();
|
||
/// use craft_audio::{AudioError, DecodeOptions, decode_with};
|
||
///
|
||
/// let (_, buf) = decode_with(&wav, None, &DecodeOptions::default()).unwrap();
|
||
/// assert_eq!(buf.frames(), 4800);
|
||
/// // 2 × 4800 samples are over a limit of 1000.
|
||
/// let small = DecodeOptions::default().with_max_samples(1000);
|
||
/// assert!(matches!(decode_with(&wav, None, &small), Err(AudioError::TooLarge(_))));
|
||
/// # }
|
||
/// ```
|
||
pub fn decode_with(bytes: &[u8], ext_hint: Option<&str>, opts: &DecodeOptions) -> Result<(AudioInfo, AudioBuffer)> {
|
||
let mut d = Decoder::from_bytes(bytes, ext_hint, opts)?;
|
||
let declared = d.info().frames.saturating_mul(u64::from(d.info().channels.max(1)));
|
||
if d.length_known() && declared > opts.max_samples {
|
||
return Err(AudioError::TooLarge(format!("{declared} samples exceeds the decode limit")));
|
||
}
|
||
let mut planar: Vec<Vec<f32>> = Vec::new();
|
||
let (mut frames, mut damaged) = (0u64, 0u64);
|
||
while let Some(block) = d.next_block()? {
|
||
if planar.is_empty() {
|
||
planar = vec![Vec::new(); block.channels.len()];
|
||
}
|
||
// A block with another channel count cannot join the buffer: it is concealed like a
|
||
// damaged packet, so the audio after it keeps its timing.
|
||
let block = if block.channels.len() == planar.len() {
|
||
block
|
||
} else {
|
||
damaged += 1;
|
||
AudioBuffer { sample_rate: block.sample_rate, channels: vec![vec![0.0; block.frames()]; planar.len()] }
|
||
};
|
||
frames = frames.saturating_add(block.frames() as u64);
|
||
if frames.saturating_mul(planar.len() as u64) > opts.max_samples {
|
||
return Err(AudioError::TooLarge("decoded audio exceeds the decode limit".into()));
|
||
}
|
||
for (dst, src) in planar.iter_mut().zip(block.channels) {
|
||
dst.try_reserve(src.len()).map_err(|_| AudioError::TooLarge("cannot allocate decoded audio".into()))?;
|
||
dst.extend(src);
|
||
}
|
||
}
|
||
let mut info = d.info().clone();
|
||
info.damaged += damaged;
|
||
let channels = (!planar.is_empty()).then_some(planar.len());
|
||
fit_channels(&mut info, channels);
|
||
if planar.is_empty() {
|
||
planar = vec![Vec::new(); usize::from(info.channels)];
|
||
}
|
||
info.frames = planar.iter().map(Vec::len).min().unwrap_or(0) as u64;
|
||
let sample_rate = info.sample_rate;
|
||
Ok((info, AudioBuffer { sample_rate, channels: planar }))
|
||
}
|
||
|
||
/// The decoded channel count is authoritative: a layout that names another count is dropped.
|
||
fn fit_channels(info: &mut AudioInfo, decoded: Option<usize>) {
|
||
if let Some(ch) = decoded
|
||
&& ch != usize::from(info.channels)
|
||
{
|
||
info.channels = u16::try_from(ch).unwrap_or(u16::MAX);
|
||
info.layout = ChannelLayout::unordered(crate::layout::count(ch));
|
||
}
|
||
}
|
||
|
||
/// The audio tracks of a file, in the order [`DecodeOptions::track`] counts them.
|
||
///
|
||
/// ```
|
||
/// # #[cfg(feature = "pcm-encode")] {
|
||
/// use craft_audio::{AudioBuffer, EncodeOptions, encode};
|
||
/// let wav = encode(&AudioBuffer::new(48_000, 2, 4800), &EncodeOptions::default()).unwrap();
|
||
/// use craft_audio::{CodecId, tracks};
|
||
///
|
||
/// let list = tracks(&wav, None).unwrap();
|
||
/// assert_eq!((list.len(), list[0].codec, list[0].channels), (1, CodecId::Pcm, Some(2)));
|
||
/// # }
|
||
/// ```
|
||
pub fn tracks(bytes: &[u8], ext_hint: Option<&str>) -> Result<Vec<TrackInfo>> {
|
||
tracks_in(&Src::Slice(bytes), ext_hint)
|
||
}
|
||
|
||
/// [`tracks`] for a file read from a source.
|
||
///
|
||
/// ```no_run
|
||
/// # fn demo() -> craft_audio::Result<()> {
|
||
/// for t in craft_audio::tracks_of(std::fs::File::open("interview.mkv")?, Some("mkv"))? {
|
||
/// println!("track {}: {}", t.index, t.codec.name());
|
||
/// }
|
||
/// # Ok(()) }
|
||
/// ```
|
||
pub fn tracks_of(source: impl SharedSource, ext_hint: Option<&str>) -> Result<Vec<TrackInfo>> {
|
||
tracks_in(&Src::Shared(Arc::new(source)), ext_hint)
|
||
}
|
||
|
||
fn tracks_in(src: &Src<'_>, ext_hint: Option<&str>) -> Result<Vec<TrackInfo>> {
|
||
let container = detect_container(&src.head_checked()?, ext_hint);
|
||
let list = |v: Vec<(CodecId, Option<u32>, Option<u16>)>| -> Vec<TrackInfo> {
|
||
v.into_iter().enumerate().map(|(index, (codec, sample_rate, channels))| TrackInfo { index, codec, sample_rate, channels }).collect()
|
||
};
|
||
if let Some(params) = native::tracks(src, container) {
|
||
let params = params?;
|
||
return Ok(list(params.into_iter().map(|p| (p.codec, p.sample_rate, p.channels)).collect()));
|
||
}
|
||
match Native::open(src, container, None) {
|
||
// Single-track formats: WAV, AIFF, raw streams.
|
||
Some(n) => {
|
||
let n = n?;
|
||
let i = n.info();
|
||
Ok(list(vec![(i.codec, (i.sample_rate > 0).then_some(i.sample_rate), (i.channels > 0).then_some(i.channels))]))
|
||
}
|
||
#[cfg(feature = "symphonia")]
|
||
None => Ok(list(
|
||
symph::tracks(src.whole()?, container)
|
||
.map_err(|e| damaged_or(src, container, e))?
|
||
.into_iter()
|
||
.map(|(c, r, n)| (c, (r > 0).then_some(r), (n > 0).then_some(n)))
|
||
.collect(),
|
||
)),
|
||
#[cfg(not(feature = "symphonia"))]
|
||
None => Err(not_built(src)),
|
||
}
|
||
}
|
||
|
||
/// symphonia's error for a file it cannot read, or the native demuxer's finding when symphonia
|
||
/// calls unsupported a file the native path found damaged: a damaged file is malformed whichever
|
||
/// path last tried it.
|
||
#[cfg(feature = "symphonia")]
|
||
fn damaged_or(src: &Src<'_>, container: Option<Container>, e: AudioError) -> AudioError {
|
||
if matches!(e, AudioError::Unsupported(_))
|
||
&& let Some(m) = native::damage(src, container)
|
||
{
|
||
return AudioError::Malformed(m);
|
||
}
|
||
e
|
||
}
|
||
|
||
/// The error for a file the native path does not read, in a build without symphonia: the build
|
||
/// is blamed only when the bytes name a format.
|
||
#[cfg(not(feature = "symphonia"))]
|
||
fn not_built(src: &Src<'_>) -> AudioError {
|
||
let head = match src.head_checked() {
|
||
Ok(head) => head,
|
||
Err(e) => return e,
|
||
};
|
||
match detect_container(&head, None) {
|
||
Some(c) => AudioError::Unsupported(format!("{} needs a decoder this build leaves out (the `decode` feature adds symphonia)", c.name())),
|
||
None => AudioError::Unsupported("not a recognized audio format".into()),
|
||
}
|
||
}
|
||
|
||
#[cfg(all(test, not(feature = "symphonia")))]
|
||
mod native_only_tests {
|
||
use super::*;
|
||
|
||
/// Without symphonia, a format with no native decoder is unsupported, not malformed.
|
||
#[test]
|
||
fn formats_left_to_symphonia_are_unsupported() {
|
||
let flac_header = [&b"fLaC"[..], &[0x80, 0, 0, 34], &[0; 34]].concat();
|
||
assert!(matches!(decode(&flac_header, None), Err(AudioError::Unsupported(m)) if m.contains("FLAC")));
|
||
assert!(matches!(probe(&flac_header, None), Err(AudioError::Unsupported(_))));
|
||
// A track list says the same instead of listing nothing.
|
||
assert!(matches!(tracks(&flac_header, None), Err(AudioError::Unsupported(m)) if m.contains("FLAC")));
|
||
// Bytes that name no format are not blamed on the build.
|
||
assert!(matches!(tracks(&[7u8; 64], None), Err(AudioError::Unsupported(m)) if m.contains("not a recognized")));
|
||
}
|
||
|
||
/// A source that cannot be read is an I/O error, not an unrecognized format.
|
||
#[test]
|
||
fn a_failed_header_read_is_an_io_error() {
|
||
struct Failing;
|
||
impl craft_media::ByteSource for Failing {
|
||
fn len(&self) -> u64 {
|
||
1000
|
||
}
|
||
fn read_at(&self, _: u64, _: &mut [u8]) -> std::io::Result<()> {
|
||
Err(std::io::Error::other("disk gone"))
|
||
}
|
||
}
|
||
assert!(matches!(tracks_of(Failing, None), Err(AudioError::Io(_))));
|
||
assert!(matches!(Decoder::open(Failing, None, &DecodeOptions::default()), Err(AudioError::Io(_))));
|
||
}
|
||
|
||
/// A damaged file in a container the native path reads is malformed, not left to a decoder
|
||
/// this build lacks.
|
||
#[test]
|
||
fn a_damaged_mp4_is_malformed() {
|
||
// an `ftyp` box and nothing after it: no `moov`
|
||
let mp4 = [&16u32.to_be_bytes()[..], b"ftypisom", &[0, 0, 2, 0]].concat();
|
||
assert!(matches!(decode(&mp4, None), Err(AudioError::Malformed(_))));
|
||
assert!(matches!(tracks(&mp4, None), Err(AudioError::Malformed(_))));
|
||
}
|
||
|
||
/// A source that fails past its first 64 KiB fails inside the demuxer: still an I/O error.
|
||
#[test]
|
||
fn a_failed_read_inside_the_demuxer_is_an_io_error() {
|
||
use craft_media::matroska::{LacingMode, MkvWriter, MuxOptions, TrackKind, TrackSpec};
|
||
struct FailsLate(Vec<u8>);
|
||
impl craft_media::ByteSource for FailsLate {
|
||
fn len(&self) -> u64 {
|
||
self.0.len() as u64
|
||
}
|
||
fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> {
|
||
if offset + buf.len() as u64 > 64 * 1024 {
|
||
return Err(std::io::Error::other("disk gone"));
|
||
}
|
||
self.0.read_at(offset, buf)
|
||
}
|
||
}
|
||
// a Matroska PCM file of about 400 KB, whose cues and later clusters lie past 64 KiB
|
||
let mut spec = TrackSpec::new(TrackKind::Audio, "A_PCM/FLOAT/IEEE");
|
||
spec.audio = Some((48_000.0, 1, Some(32)));
|
||
let opts = MuxOptions { lacing: LacingMode::None, ..MuxOptions::default() };
|
||
let mut w = MkvWriter::new(std::io::Cursor::new(Vec::new()), vec![spec], opts).unwrap();
|
||
for k in 0..100i64 {
|
||
w.write_frame(0, k * 20_000_000, true, &[0; 960 * 4], Some(20_000_000)).unwrap();
|
||
}
|
||
let file = w.finish().unwrap().into_inner();
|
||
assert!(matches!(tracks_of(FailsLate(file.clone()), None), Err(AudioError::Io(_))));
|
||
assert!(matches!(Decoder::open(FailsLate(file), None, &DecodeOptions::default()), Err(AudioError::Io(_))));
|
||
}
|
||
}
|