From 18f529112e1dcf09a873f3ebf9818c00f1600b97 Mon Sep 17 00:00:00 2001 From: blenux Date: Fri, 13 Nov 2026 15:51:20 +1100 Subject: [PATCH 01/22] raster-codecs: expose DDS header info and bounded mip imports Keep import clients on the shared decoder after the extraction from PhotoCraft. Charge the entire mip chain before each allocation, check cancellation between levels, and accept mip counts without the optional writer flag. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- crates/raster-codecs/src/dds.rs | 77 ++++++++++++++++++++++++++++--- crates/raster-codecs/tests/dds.rs | 76 ++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+), 6 deletions(-) diff --git a/crates/raster-codecs/src/dds.rs b/crates/raster-codecs/src/dds.rs index 1249cb5b7..0f848e38c 100644 --- a/crates/raster-codecs/src/dds.rs +++ b/crates/raster-codecs/src/dds.rs @@ -91,6 +91,7 @@ impl Field { } } +#[derive(Clone, Copy)] enum Encoding { /// Uncompressed: bytes per pixel, then red (or luminance), green, blue and alpha. Masks { @@ -202,7 +203,25 @@ fn dx10_encoding(b: &[u8]) -> Result { } } -pub fn decode(b: &[u8], limits: &Limits) -> Result { +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct DdsInfo { + pub width: u32, + pub height: u32, + pub levels: u32, + pub alpha: bool, + pub compression: Option, +} + +struct Parsed<'a> { + encoding: Encoding, + data: &'a [u8], + width: u32, + height: u32, + levels: u32, + pitch: Option, +} + +fn parse(b: &[u8]) -> Result, CodecError> { if !b.starts_with(b"DDS ") { return Err(bad("missing the `DDS ` signature")); } @@ -218,17 +237,63 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result { } let dx10 = le32(b, 80)? & DDPF_FOURCC != 0 && &le32(b, 84)?.to_le_bytes() == b"DX10"; let (encoding, start) = if dx10 { (dx10_encoding(b)?, HEADER + DX10_HEADER) } else { (legacy_encoding(b)?, HEADER) }; - let layout = encoding.layout(); - limits.check(width, height, layout, SampleType::U8)?; + let declared = le32(b, 28)?.max(1); + let levels = declared.min(mip_levels(width, height)); // The same header field is a total level size for BC, but a row stride when DDSD_PITCH is set. let pitch = if flags & DDSD_PITCH != 0 { Some(le32(b, 20)?) } else { None }; + Ok(Parsed { encoding, data: b.get(start..).unwrap_or_default(), width, height, levels, pitch }) +} + +pub fn info(b: &[u8]) -> Result { + let p = parse(b)?; + let compression = match p.encoding { + Encoding::Masks { .. } => DdsCompression::None, + Encoding::Bc1 => DdsCompression::Bc1, + Encoding::Bc2 => DdsCompression::Bc2, + Encoding::Bc3 => DdsCompression::Bc3, + }; + let alpha = match p.encoding { + Encoding::Masks { fields, .. } => fields[3].is_some(), + _ => true, + }; + Ok(DdsInfo { width: p.width, height: p.height, levels: p.levels, alpha, compression: Some(compression) }) +} + +pub fn decode(b: &[u8], limits: &Limits) -> Result { + let p = parse(b)?; + level_image(p.encoding, p.data, p.width, p.height, p.pitch, limits).map(|(img, _)| img) +} + +pub fn decode_levels(b: &[u8], limits: &Limits, cancel: &dyn Fn() -> bool) -> Result, CodecError> { + let p = parse(b)?; + let (mut data, mut width, mut height, mut remaining) = (p.data, p.width, p.height, limits.max_alloc); + let mut levels = Vec::with_capacity(p.levels as usize); + for i in 0..p.levels { + if cancel() { + return Err(bad("DDS import cancelled")); + } + let level_limits = Limits { max_alloc: remaining, ..*limits }; + let (img, size) = level_image(p.encoding, data, width, height, if i == 0 { p.pitch } else { None }, &level_limits)?; + remaining = + remaining.checked_sub(img.data().len() as u64).ok_or_else(|| CodecError::LimitExceeded("DDS mip chain exceeds max_alloc".into()))?; + levels.push(img); + data = data.get(size..).ok_or_else(|| bad("truncated mip data"))?; + width = (width / 2).max(1); + height = (height / 2).max(1); + } + Ok(levels) +} + +fn level_image(encoding: Encoding, data: &[u8], width: u32, height: u32, pitch: Option, limits: &Limits) -> Result<(Image, usize), CodecError> { + let layout = encoding.layout(); + limits.check(width, height, layout, SampleType::U8)?; let (row_pitch, size) = encoding.level_layout(width, height, pitch)?; - let data = b.get(start..).and_then(|d| d.get(..size)).ok_or_else(|| bad(format!("truncated pixel data: {size} bytes needed")))?; + let data = data.get(..size).ok_or_else(|| bad(format!("truncated pixel data: {size} bytes needed")))?; let (w, h) = (width as usize, height as usize); let channels = layout.channels(); let row_size = w.checked_mul(channels).ok_or_else(|| bad("pixel size overflow"))?; let total = row_size.checked_mul(h).ok_or_else(|| bad("pixel size overflow"))?; - let mut pixels = vec![0u8; total]; + let mut pixels = crate::alloc_zeroed::(total)?; match encoding { Encoding::Masks { bytes, gray, fields } => { for (src_row, dst_row) in data.chunks_exact(row_pitch).zip(pixels.chunks_exact_mut(row_size)) { @@ -263,7 +328,7 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result { } } } - Image::from_u8(width, height, layout, pixels) + Ok((Image::from_u8(width, height, layout, pixels)?, size)) } /// A BC1 colour block. BC2 and BC3 colour blocks always have four colours; only BC1's diff --git a/crates/raster-codecs/tests/dds.rs b/crates/raster-codecs/tests/dds.rs index afb9066aa..60fe1366d 100644 --- a/crates/raster-codecs/tests/dds.rs +++ b/crates/raster-codecs/tests/dds.rs @@ -410,3 +410,79 @@ fn rejects_bogus_sizes_and_pixel_formats() { no_format.extend([0; 4]); assert!(matches!(decode(&no_format), Err(CodecError::Unsupported { .. }))); } + +fn mip_chain() -> Vec { + let mut b = compressed(4, 4, b"DXT1"); + b[8..12].copy_from_slice(&(0x1007u32 | 0x2_0000).to_le_bytes()); + b[28..32].copy_from_slice(&3u32.to_le_bytes()); + for c in [RED, GREEN, BLUE] { + b.extend(bc1_block(c, c, [0; 4])); + } + b +} + +#[test] +fn import_info_and_all_mips_use_the_shared_decoder() { + let b = mip_chain(); + let info = dds::info(&b[..128]).unwrap(); + assert_eq!((info.width, info.height, info.levels, info.alpha), (4, 4, 3, true)); + assert_eq!(info.compression, Some(dds::DdsCompression::Bc1)); + let levels = dds::decode_levels(&b, &Limits::default(), &|| false).unwrap(); + assert_eq!(levels.iter().map(Image::dimensions).collect::>(), [(4, 4), (2, 2), (1, 1)]); + for (img, color) in levels.iter().zip([[255, 0, 0, 255], [0, 255, 0, 255], [0, 0, 255, 255]]) { + assert!(img.data().as_chunks::<4>().0.iter().all(|p| *p == color)); + } + assert_eq!(decode(&b).unwrap().data(), levels[0].data()); +} + +#[test] +fn mip_chain_charges_the_combined_allocation() { + for (budget, accepted) in [(63, false), (64, false), (80, false), (83, false), (84, true)] { + let result = dds::decode_levels(&mip_chain(), &Limits { max_alloc: budget, ..Default::default() }, &|| false); + if accepted { + assert_eq!(result.unwrap().len(), 3); + } else { + assert!(matches!(result, Err(CodecError::LimitExceeded(_)))); + } + } +} + +#[test] +fn cancellation_is_checked_after_a_level_was_decoded() { + let calls = std::cell::Cell::new(0); + let result = dds::decode_levels(&mip_chain(), &Limits::default(), &|| { + let n = calls.get(); + calls.set(n + 1); + n == 1 + }); + assert!(matches!(result, Err(CodecError::Malformed { message, .. }) if message.contains("cancelled"))); + assert_eq!(calls.get(), 2); +} + +#[test] +fn mip_import_rejects_truncation_and_bounds_declared_count() { + let mut b = mip_chain(); + for n in 0..b.len() { + assert!(dds::decode_levels(&b[..n], &Limits::default(), &|| false).is_err(), "length {n}"); + } + b[28..32].copy_from_slice(&u32::MAX.to_le_bytes()); + assert_eq!(dds::decode_levels(&b, &Limits::default(), &|| false).unwrap().len(), 3); + b[8..12].copy_from_slice(&0x1007u32.to_le_bytes()); + assert_eq!(dds::info(&b).unwrap().levels, 3); + assert_eq!(dds::decode_levels(&b, &Limits::default(), &|| false).unwrap().len(), 3); + b[28..32].copy_from_slice(&0u32.to_le_bytes()); + assert_eq!(dds::info(&b).unwrap().levels, 1); + assert_eq!(dds::decode_levels(&b, &Limits::default(), &|| false).unwrap().len(), 1); +} + +#[test] +fn lower_mips_do_not_inherit_top_level_pitch() { + let mut b = header(2, 2, DDPF_LUMINANCE, &[0; 4], 8, [0xff, 0, 0, 0]); + set_pitch(&mut b, 4); + b[8..12].copy_from_slice(&(0x1007u32 | DDSD_PITCH | 0x2_0000).to_le_bytes()); + b[28..32].copy_from_slice(&2u32.to_le_bytes()); + b.extend([1, 2, 99, 99, 3, 4, 99, 99, 5]); + let levels = dds::decode_levels(&b, &Limits::default(), &|| false).unwrap(); + assert_eq!(levels[0].data(), [1, 2, 3, 4]); + assert_eq!(levels[1].data(), [5]); +} From 332c5abd8d8fbc1f07c919e249c76a01efb5b3ee Mon Sep 17 00:00:00 2001 From: blenux Date: Fri, 13 Nov 2026 19:50:43 +1100 Subject: [PATCH 02/22] raster-codecs: reject incomplete DDS metadata headers Keep complete header-only probes valid while rejecting truncated legacy and DX10 headers before returning metadata. Cover every truncated prefix and preserve missing-pixel-data errors in both decoding paths. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- crates/raster-codecs/src/dds.rs | 3 ++- crates/raster-codecs/tests/dds.rs | 25 +++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/crates/raster-codecs/src/dds.rs b/crates/raster-codecs/src/dds.rs index 0f848e38c..b9a716688 100644 --- a/crates/raster-codecs/src/dds.rs +++ b/crates/raster-codecs/src/dds.rs @@ -241,7 +241,8 @@ fn parse(b: &[u8]) -> Result, CodecError> { let levels = declared.min(mip_levels(width, height)); // The same header field is a total level size for BC, but a row stride when DDSD_PITCH is set. let pitch = if flags & DDSD_PITCH != 0 { Some(le32(b, 20)?) } else { None }; - Ok(Parsed { encoding, data: b.get(start..).unwrap_or_default(), width, height, levels, pitch }) + let data = b.get(start..).ok_or_else(|| bad("truncated header"))?; + Ok(Parsed { encoding, data, width, height, levels, pitch }) } pub fn info(b: &[u8]) -> Result { diff --git a/crates/raster-codecs/tests/dds.rs b/crates/raster-codecs/tests/dds.rs index 60fe1366d..c0a06b6de 100644 --- a/crates/raster-codecs/tests/dds.rs +++ b/crates/raster-codecs/tests/dds.rs @@ -421,6 +421,31 @@ fn mip_chain() -> Vec { b } +#[test] +fn import_info_rejects_truncated_legacy_headers() { + let b = compressed(4, 4, b"DXT1"); + for n in 0..b.len() { + assert!(matches!(dds::info(&b[..n]), Err(CodecError::Malformed { .. })), "accepted {n} of {} header bytes", b.len()); + } +} + +#[test] +fn import_info_rejects_truncated_dx10_headers() { + let b = dx10(4, 4, 71, 3, 0, 1); + for n in 0..b.len() { + assert!(matches!(dds::info(&b[..n]), Err(CodecError::Malformed { .. })), "accepted {n} of {} header bytes", b.len()); + } +} + +#[test] +fn import_info_accepts_complete_headers_without_pixel_data() { + for b in [compressed(4, 4, b"DXT1"), dx10(4, 4, 71, 3, 0, 1)] { + assert_eq!(dds::info(&b).unwrap(), dds::DdsInfo { width: 4, height: 4, levels: 1, alpha: true, compression: Some(dds::DdsCompression::Bc1) }); + assert!(matches!(decode(&b), Err(CodecError::Malformed { .. }))); + assert!(matches!(dds::decode_levels(&b, &Limits::default(), &|| false), Err(CodecError::Malformed { .. }))); + } +} + #[test] fn import_info_and_all_mips_use_the_shared_decoder() { let b = mip_chain(); From 6ac5f83bb23e46518c3aaea33b4d3c3995d41abe Mon Sep 17 00:00:00 2001 From: alehel Date: Sun, 15 Nov 2026 00:44:35 +0100 Subject: [PATCH 03/22] feat(media,video,audio): add Sierra VMD demuxer and decoders Sierra VMD (Video and Music Data) is the video format of Sierra and Coktel Vision games of the 1990s. Written clean-room from the public format description at https://wiki.multimedia.cx/index.php/VMD, with ffmpeg as a black-box oracle. - craft-media: `vmd` feature, a demuxer for the 816-byte header and the table of contents; `Container::Vmd`, `CodecId::VmdVideo` and `CodecId::VmdAudio`. - craft-video: `vmd` feature, a decoder for 8-bit paletted pictures (rendering methods 1 to 3, LZ packing, palette changes). - craft-audio: `vmd-decode` feature, a decoder for 8-bit PCM and 16-bit DPCM sound, mono and stereo. - craft-media-testkit: a VMD fixture writer, since ffmpeg reads VMD but cannot write it. Tests compare the decoders with ffmpeg on generated files, and on real files when CRAFT_MEDIA_VMD_SAMPLES names a directory of them. 16-bit, 24-bit and Indeo 3 pictures, IMA ADPCM sound and the later header revisions are not decoded. --- README.md | 2 +- crates/audio/Cargo.toml | 8 + crates/audio/README.md | 1 + crates/audio/src/lib.rs | 15 +- crates/audio/src/vmd.rs | 178 +++++++++++++ crates/audio/tests/vmd.rs | 265 ++++++++++++++++++++ crates/media-testkit/src/lib.rs | 2 + crates/media-testkit/src/vmd.rs | 343 +++++++++++++++++++++++++ crates/media/Cargo.toml | 6 + crates/media/README.md | 56 ++++- crates/media/src/id.rs | 12 + crates/media/src/lib.rs | 5 +- crates/media/src/vmd/mod.rs | 405 ++++++++++++++++++++++++++++++ crates/media/src/vmd/tests.rs | 161 ++++++++++++ crates/media/tests/oracle_vmd.rs | 68 +++++ crates/video/Cargo.toml | 12 +- crates/video/README.md | 1 + crates/video/src/lib.rs | 4 + crates/video/src/vmd/mod.rs | 382 ++++++++++++++++++++++++++++ crates/video/tests/vmd/main.rs | 415 +++++++++++++++++++++++++++++++ 20 files changed, 2329 insertions(+), 12 deletions(-) create mode 100644 crates/audio/src/vmd.rs create mode 100644 crates/audio/tests/vmd.rs create mode 100644 crates/media-testkit/src/vmd.rs create mode 100644 crates/media/src/vmd/mod.rs create mode 100644 crates/media/src/vmd/tests.rs create mode 100644 crates/media/tests/oracle_vmd.rs create mode 100644 crates/video/src/vmd/mod.rs create mode 100644 crates/video/tests/vmd/main.rs diff --git a/README.md b/README.md index c6e95bd4f..2f72adfe8 100644 --- a/README.md +++ b/README.md @@ -254,7 +254,7 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit - [`craft-math`](crates/math/README.md): equations as one tree (the Office Math object model) with its syntaxes, read and written: OMML, presentation MathML, LaTeX math and the UnicodeMath linear format. - [`craft-media`](crates/media/README.md): bit-level I/O (`bitstream`), clean-room MP4/MOV (`isobmff`), Matroska/WebM (`matroska`) and MXF (`mxf`) demuxers and muxers, Ogg (`ogg`), AVI (`avi`) and - MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and + MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, a Sierra VMD (`vmd`) demuxer, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and video codecs will go in a separate crate. - [`craft-lottie`](crates/lottie/README.md): Lottie (Bodymovin) JSON: the document model of lottie-spec 1.0 (animation, assets, layers by type, shape items, masks, effects, text, markers) diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index d132f23da..55698d192 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -49,6 +49,8 @@ ac3-encode = ["craft-media/bitstream"] eac3-encode = ["craft-media/bitstream"] # MPEG-1/2 Layer III (MP3) encoder (`mp3`). mp3-encode = ["craft-media/bitstream"] +# Sierra VMD sound decoder (`vmd::Decoder`): 8-bit PCM and 16-bit DPCM. +vmd-decode = [] # Multi-resolution waveform overviews (`peaks`). peaks = [] # Encode AAC channels in parallel (with `aac-encode`). @@ -67,6 +69,8 @@ symphonia = { version = "0.6.1", optional = true, default-features = false, feat [dev-dependencies] craft-media-testkit = { workspace = true } +# The VMD demuxer, for the VMD sound decoder's tests. +craft-media = { workspace = true, features = ["vmd"] } proptest = { workspace = true } serde_json = { workspace = true } @@ -74,6 +78,10 @@ serde_json = { workspace = true } name = "audio" required-features = ["decode", "lossless-encode", "peaks"] +[[test]] +name = "vmd" +required-features = ["vmd-decode"] + [[test]] name = "codecs" required-features = ["decode", "encode"] diff --git a/crates/audio/README.md b/crates/audio/README.md index 5a5df4f2f..59256822a 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -42,6 +42,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou | `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` | | `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` | | `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` | +| `vmd-decode` | `vmd::Decoder`: Sierra VMD sound (8-bit PCM and 16-bit DPCM), frame by frame from `craft_media::vmd` | none | | `peaks` | `peaks::Peaks` | none | | `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` | | `serde` | `Serialize`/`Deserialize` on the shared types | `serde` | diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 1c6c73dcf..cd250bd21 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -27,7 +27,8 @@ //! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`, //! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and //! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] -//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder). +//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder), [`vmd`] +//! (`vmd-decode`: Sierra VMD sound). //! //! The shared types below build with no features. @@ -53,6 +54,8 @@ pub mod peaks; mod read; #[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))] mod track; +#[cfg(feature = "vmd-decode")] +pub mod vmd; #[cfg(any(feature = "decode-native", feature = "pcm-encode"))] mod wav; #[cfg(any( @@ -224,6 +227,16 @@ impl From for AudioError { } } +#[cfg(feature = "vmd-decode")] +impl From for AudioError { + fn from(e: vmd::Error) -> Self { + match e { + vmd::Error::Unsupported(_) => AudioError::Unsupported(e.to_string()), + _ => AudioError::Malformed(e.to_string()), + } + } +} + #[cfg(feature = "opus-encode")] impl From for AudioError { fn from(e: opus::encoder::Error) -> Self { diff --git a/crates/audio/src/vmd.rs b/crates/audio/src/vmd.rs new file mode 100644 index 000000000..6c2a0b829 --- /dev/null +++ b/crates/audio/src/vmd.rs @@ -0,0 +1,178 @@ +//! Sierra VMD sound decoder (feature `vmd-decode`): the 8-bit PCM and 16-bit DPCM sound of VMD +//! (Video and Music Data) files, as in Sierra's and Coktel Vision's 1990s games. +//! +//! Clean-room, from the public format description at +//! ("Description of the Sierra Video and Music Data (VMD) Format", Mike Melanson and Vladimir +//! Gneushev). The description gives the coding but not the size of a block; the sizes here are +//! what ffmpeg was seen to expect of files made by this crate's tests: +//! +//! | Sound | Bytes in a block of `n` samples a channel | +//! |---|---| +//! | 8-bit | `n` for each channel, interleaved | +//! | 16-bit | 2 for each channel's first sample, then one code for each further sample, interleaved | +//! +//! The header's frame length is `n`, except in old-style stereo (audio flag 0x8000), where it +//! counts both channels. Old-style 16-bit stereo blocks begin with their first samples like the +//! others, which is what ffmpeg reads; the description says they carry the last block's samples +//! over instead. No such file was at hand to settle it. +//! +//! A [`Decoder`] is made from the 816-byte file header. [`Decoder::decode`] takes a sound +//! frame's flags (from its record in the file's table of contents; `craft_media::vmd` reads it) +//! and its data, and returns interleaved `i16` samples: one block of sound or silence, or, for a +//! frame with a silence mask, several. 8-bit samples are widened to 16 bits. Blocks do not depend +//! on each other, so decoding can start at any frame. +//! +//! Not decoded: IMA ADPCM sound (audio flag 0x10) and the external codecs of later Coktel Vision +//! files ([`Error::Unsupported`]). +//! +//! Input is treated as hostile: a frame yields at most 32 blocks (the width of the silence +//! mask) of at most 65 535 samples a channel, and a block is decoded only if all of it is there. No `unsafe`, no panics. + +#![warn(missing_docs)] + +/// Bytes of the VMD file header a [`Decoder`] is made from. +pub const HEADER_LEN: usize = 816; + +/// Errors from decoding VMD sound. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The header or a frame is not valid. + #[error("invalid VMD sound: {0}")] + Invalid(&'static str), + /// Valid, but not something this decoder handles. + #[error("unsupported VMD sound: {0}")] + Unsupported(&'static str), +} + +/// The steps of the 16-bit coding: a code's low seven bits pick one, its top bit the sign. +const STEPS: [u16; 128] = [ + 0, 8, 16, 32, 48, 64, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240, 256, 272, 288, 304, 320, 336, 352, 368, 384, 400, 416, 432, 448, 464, + 480, 496, 512, 520, 528, 536, 544, 552, 560, 568, 576, 584, 592, 600, 608, 616, 624, 632, 640, 648, 656, 664, 672, 680, 688, 696, 704, 712, 720, + 728, 736, 744, 752, 760, 768, 776, 784, 792, 800, 808, 816, 824, 832, 840, 848, 856, 864, 872, 880, 888, 896, 904, 912, 920, 928, 936, 944, 952, + 960, 968, 976, 984, 992, 1000, 1008, 1016, 1024, 1088, 1152, 1216, 1280, 1344, 1408, 1472, 1536, 1600, 1664, 1728, 1792, 1856, 1920, 1984, 2048, + 2304, 2560, 2816, 3072, 3328, 3584, 3840, 4096, 5120, 6144, 7168, 8192, 12288, 16384, +]; + +/// A VMD sound decoder. +#[derive(Clone, Debug)] +pub struct Decoder { + sample_rate: u32, + channels: usize, + sixteen_bit: bool, + /// Samples of one block, all channels counted. + block_samples: usize, +} + +impl Decoder { + /// A decoder for the file whose header is `header` (its first 816 bytes; more are ignored). + pub fn new(header: &[u8]) -> Result { + let h = header.get(..HEADER_LEN).ok_or(Error::Invalid("the header is shorter than 816 bytes"))?; + let u16_at = |at: usize| u16::from_le_bytes([h[at], h[at + 1]]); + if usize::from(u16_at(0)) != HEADER_LEN - 2 { + return Err(Error::Invalid("not a VMD header")); + } + if u16_at(16) & 0x1000 == 0 { + return Err(Error::Invalid("the file has no sound")); + } + let flags = u16_at(810); + if flags & 0x10 != 0 { + return Err(Error::Unsupported("IMA ADPCM sound")); + } + let length = u16_at(806) as i16; + let frame_length = usize::from(length.unsigned_abs()); + // old-style stereo counts both channels, new-style one + let (channels, block_samples) = match flags { + f if f & 0x8000 != 0 => (2, frame_length & !1), + f if f & 0x200 != 0 => (2, frame_length * 2), + _ => (1, frame_length), + }; + Ok(Decoder { sample_rate: u32::from(u16_at(804)), channels, sixteen_bit: length < 0, block_samples }) + } + + /// Samples a second. + pub fn sample_rate(&self) -> u32 { + self.sample_rate + } + + /// 1 or 2. + pub fn channels(&self) -> usize { + self.channels + } + + /// Bits a sample in the file: 8 (PCM) or 16 (DPCM). The decoder returns `i16` for both. + pub fn bits(&self) -> u8 { + if self.sixteen_bit { 16 } else { 8 } + } + + /// Samples of one block for each channel. + pub fn block_samples(&self) -> usize { + self.block_samples / self.channels + } + + /// Bytes of one block of sound in a frame. + pub fn block_bytes(&self) -> usize { + if self.sixteen_bit { (self.block_samples + self.channels).min(self.block_samples * 2) } else { self.block_samples } + } + + /// Decode one sound frame: `flags` is the frame's flag byte from its record, `data` the + /// frame data. Returns interleaved samples, [`Decoder::block_samples`] for each channel and + /// block. + /// + /// - flags 1: one block of sound; + /// - flags 2: a 32-bit mask, then blocks of sound: the sound a player loads ahead at the + /// start of a file. From bit 0 up, a set bit is a block of silence and a clear bit the next + /// block of data, while there is one. ffmpeg plays the silent blocks first instead; + /// the order here is the description's; + /// - flags 3: one block of silence. + /// + /// An empty frame gives no samples. A block cut short is an error. + pub fn decode(&self, flags: u8, data: &[u8]) -> Result, Error> { + let mut out = Vec::new(); + match flags { + 3 => out.resize(self.block_samples, 0), + _ if data.is_empty() => {} + 1 => self.block(data, &mut out)?, + 2 => { + let (mask, mut data) = data.split_first_chunk::<4>().ok_or(Error::Invalid("the silence mask is cut short"))?; + let mask = u32::from_le_bytes(*mask); + // bit by bit: a set bit is a silent block, a clear one takes the next block of data + // while there is one. The header's buffer count is not needed: game files hold + // one block fewer than it says. + for i in 0..32 { + if mask >> i & 1 == 1 { + out.resize(out.len() + self.block_samples, 0); + } else if !data.is_empty() && data.len() >= self.block_bytes() { + self.block(data, &mut out)?; + data = &data[self.block_bytes()..]; + } + } + } + _ => return Err(Error::Unsupported("unknown sound frame flags")), + } + Ok(out) + } + + /// Decode the block at the start of `data` onto `out`. + fn block(&self, data: &[u8], out: &mut Vec) -> Result<(), Error> { + let data = data.get(..self.block_bytes()).ok_or(Error::Invalid("a block of sound is cut short"))?; + if !self.sixteen_bit { + out.extend(data.iter().map(|&b| (i16::from(b) - 0x80) << 8)); + return Ok(()); + } + // each channel's first sample as it is, then a signed step for each further sample + let mut last = [0i32; 2]; + let Some((first, codes)) = data.split_at_checked(self.channels * 2) else { return Ok(()) }; + for (ch, s) in first.as_chunks::<2>().0.iter().enumerate() { + last[ch] = i32::from(i16::from_le_bytes(*s)); + out.push(last[ch] as i16); + } + for (i, &code) in codes.iter().enumerate() { + let ch = i % self.channels; + let step = i32::from(STEPS[usize::from(code & 0x7F)]); + last[ch] = (if code & 0x80 != 0 { last[ch] - step } else { last[ch] + step }).clamp(-32768, 32767); + out.push(last[ch] as i16); + } + Ok(()) + } +} diff --git a/crates/audio/tests/vmd.rs b/crates/audio/tests/vmd.rs new file mode 100644 index 000000000..d7004a888 --- /dev/null +++ b/crates/audio/tests/vmd.rs @@ -0,0 +1,265 @@ +//! VMD sound decoder tests. ffmpeg reads VMD but cannot write it, so the files come from the +//! test kit's VMD writer. The decoder must return the samples that were packed, and the same +//! samples as ffmpeg (skipped without ffmpeg). + +use std::process::Command; + +use craft_audio::vmd::{Decoder, Error}; +use craft_media::vmd::{FrameKind, open}; +use craft_media_testkit::hostile::Rng; +use craft_media_testkit::vmd::{Audio, Frame, Spec, build, dpcm_pack}; + +/// (frame length field, audio flags, channels, 16-bit): every layout the decoder handles. +const FORMATS: [(i16, u16, usize, bool); 6] = + [(50, 0, 1, false), (50, 0x200, 2, false), (50, 0x8000, 2, false), (-50, 0, 1, true), (-50, 0x200, 2, true), (-50, 0x8000, 2, true)]; + +fn spec(frame_length: i16, flags: u16) -> Spec { + let mut spec = Spec::new(4, 4); + spec.audio = Some(Audio { sample_rate: 22050, frame_length, buffers: 5, flags }); + spec +} + +fn decoder(frame_length: i16, flags: u16) -> Decoder { + Decoder::new(&build(&spec(frame_length, flags), &[])).unwrap() +} + +/// One block of random sound: its bytes in the file and the samples it decodes to. +fn block(rng: &mut Rng, d: &Decoder) -> (Vec, Vec) { + let n = d.block_samples() * d.channels(); + if d.bits() == 8 { + let bytes: Vec = (0..n).map(|_| rng.next_u64() as u8).collect(); + let samples = bytes.iter().map(|&b| (i16::from(b) - 0x80) << 8).collect(); + return (bytes, samples); + } + // a random walk, so that the steps are of every size + let mut last = [0i32; 2]; + let samples: Vec = (0..n) + .map(|i| { + let bits = 1 + rng.below(15); + let step = rng.below(1 << bits) as i32 - (1 << (bits - 1)); + let s = &mut last[i % d.channels()]; + *s = (*s + step).clamp(-32768, 32767); + *s as i16 + }) + .collect(); + dpcm_pack(&samples, d.channels()) +} + +/// A file of sound frames (with a small picture each, as ffmpeg expects video) and the samples +/// expected of it. The first frame is a mask frame: one silent block, then four of sound. +fn movie(seed: u64, frame_length: i16, flags: u16) -> (Vec, Vec) { + let spec = spec(frame_length, flags); + let d = decoder(frame_length, flags); + let mut rng = Rng(seed | 1); + let mut picture = vec![2u8]; + picture.extend([9; 16]); + let silence = vec![0i16; d.block_samples() * d.channels()]; + let mut want = Vec::new(); + let mut blocks = Vec::new(); + for n in 0..12 { + let sound = match n { + 0 => { + let mut data = 1u32.to_le_bytes().to_vec(); + want.extend_from_slice(&silence); + for _ in 0..4 { + let (bytes, samples) = block(&mut rng, &d); + data.extend_from_slice(&bytes); + want.extend_from_slice(&samples); + } + Frame::audio(2, data) + } + _ if rng.below(4) == 0 => { + want.extend_from_slice(&silence); + Frame::audio(3, vec![]) + } + _ => { + let (bytes, samples) = block(&mut rng, &d); + want.extend_from_slice(&samples); + Frame::audio(1, bytes) + } + }; + blocks.push(vec![sound, Frame::video([0, 0, 3, 3], false, picture.clone())]); + } + (build(&spec, &blocks), want) +} + +fn decode_all(bytes: &[u8]) -> Vec { + let file = open(bytes).unwrap(); + let d = Decoder::new(file.header_bytes()).unwrap(); + let mut out = Vec::new(); + for (i, frame) in file.frames.iter().enumerate() { + if let FrameKind::Audio { flags } = frame.kind { + out.extend(d.decode(flags, &file.read_frame(bytes, i).unwrap()).unwrap()); + } + } + out +} + +#[test] +fn decodes_the_samples_that_were_packed() { + for (i, (frame_length, flags, channels, sixteen)) in FORMATS.into_iter().enumerate() { + let d = decoder(frame_length, flags); + assert_eq!((d.channels(), d.bits(), d.sample_rate()), (channels, if sixteen { 16 } else { 8 }, 22050), "format {i}"); + // old-style stereo counts both channels in the frame length + assert_eq!(d.block_samples(), if flags & 0x8000 != 0 { 25 } else { 50 }, "format {i}"); + let (bytes, want) = movie(i as u64 + 1, frame_length, flags); + assert_eq!(want.len(), 16 * d.block_samples() * channels); + assert!(decode_all(&bytes) == want, "format {i}"); + } +} + +#[test] +fn matches_ffmpeg() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg_or_skip("vmd sound oracle") else { return }; + let dir = craft_media_testkit::private_dir("vmd-sound"); + for (i, (frame_length, flags, ..)) in FORMATS.into_iter().enumerate() { + let (bytes, _) = movie(i as u64 + 1, frame_length, flags); + let path = dir.join(format!("sound{i}.vmd")); + std::fs::write(&path, &bytes).unwrap(); + let out = Command::new(&ffmpeg).args(["-v", "error", "-i"]).arg(&path).args(["-vn", "-f", "s16le", "-"]).output().unwrap(); + assert!(out.status.success() && out.stderr.is_empty(), "format {i}: ffmpeg: {}", String::from_utf8_lossy(&out.stderr)); + let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + assert!(theirs == decode_all(&bytes), "format {i} differs from ffmpeg"); + } + std::fs::remove_dir_all(&dir).unwrap(); +} + +#[test] +fn sixteen_bit_steps() { + // values ffmpeg gave for this block: the first sample, then signed steps from the table + let mut data = 1000i16.to_le_bytes().to_vec(); + data.extend([1, 1, 1, 0x81, 0x81, 2, 3, 0x7F, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]); + let d = decoder(-20, 0); + assert_eq!(d.block_bytes(), 21); + assert_eq!( + d.decode(1, &data).unwrap(), + [1000, 1008, 1016, 1024, 1016, 1008, 1024, 1056, 17440, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1064] + ); + // stereo: the channels take turns + let mut data = [1000i16.to_le_bytes(), (-1000i16).to_le_bytes()].concat(); + data.extend([1, 0x82].repeat(3)); + let d = decoder(-4, 0x200); + assert_eq!(d.decode(1, &data).unwrap(), [1000, -1000, 1008, -1016, 1016, -1032, 1024, -1048]); + // steps past 16 bits stop at the ends + let mut data = 30000i16.to_le_bytes().to_vec(); + data.extend([0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]); + assert_eq!(decoder(-7, 0).decode(1, &data).unwrap(), [30000, 32767, 16383, -1, -16385, -32768, -32768]); +} + +#[test] +fn eight_bit_and_silence() { + let d = decoder(4, 0); + assert_eq!(d.decode(1, &[0x80, 0x00, 0xFF, 0x70]).unwrap(), [0, -32768, 0x7F00, -0x1000]); + assert_eq!(d.decode(3, &[]).unwrap(), [0; 4]); + assert_eq!(d.decode(1, &[]).unwrap(), [0i16; 0]); + assert_eq!(decoder(4, 0x200).decode(3, &[]).unwrap(), [0; 8]); + assert_eq!(decoder(-4, 0x8000).decode(3, &[]).unwrap(), [0; 4]); +} + +#[test] +fn silence_mask_runs_bit_by_bit() { + let d = decoder(2, 0); + let frame = |mask: u32, data: &[u8]| d.decode(2, &[&mask.to_le_bytes()[..], data].concat()); + let (a, b) = ([0x90, 0x91], [0xA0, 0xA1]); + let (sa, sb) = ([0x1000, 0x1100], [0x2000, 0x2100]); + assert_eq!(frame(0, &[a, b].concat()).unwrap(), [sa, sb].concat()); + // silent, sound, silent, sound + assert_eq!(frame(0b0101, &[a, b].concat()).unwrap(), [[0, 0], sa, [0, 0], sb].concat()); + // game files set a bit for every block when all are silent + assert_eq!(frame(0b0111, &[]).unwrap(), [0; 6]); + // a trailing part of a block is left out + assert_eq!(frame(0, &[0x90, 0x91, 0xA0]).unwrap(), sa); + assert_eq!(d.decode(2, &[0, 0, 0]), Err(Error::Invalid("the silence mask is cut short"))); +} + +#[test] +fn bad_input_is_an_error() { + let d = decoder(-20, 0); + assert_eq!(d.decode(1, &[0; 20]), Err(Error::Invalid("a block of sound is cut short"))); + assert_eq!(d.decode(4, &[0; 21]), Err(Error::Unsupported("unknown sound frame flags"))); + + let good = build(&spec(20, 0), &[]); + let with = |patch: &dyn Fn(&mut Vec)| { + let mut h = good.clone(); + patch(&mut h); + Decoder::new(&h).err() + }; + assert_eq!(with(&|_| {}), None); + assert_eq!(with(&|h| h.truncate(815)), Some(Error::Invalid("the header is shorter than 816 bytes"))); + assert_eq!(with(&|h| h[0] = 0), Some(Error::Invalid("not a VMD header"))); + assert_eq!(with(&|h| h[17] = 0), Some(Error::Invalid("the file has no sound"))); + assert_eq!(with(&|h| h[810] = 0x10), Some(Error::Unsupported("IMA ADPCM sound"))); + // a frame length of nothing decodes to nothing + let mut empty = good.clone(); + empty[806..808].fill(0); + let d = Decoder::new(&empty).unwrap(); + assert_eq!(d.decode(1, &[1, 2, 3]).unwrap(), [0i16; 0]); + assert_eq!(d.decode(2, &[0, 0, 0, 0, 1, 2]).unwrap(), [0i16; 0]); +} + +#[test] +fn hostile_input_never_panics() { + for (i, (frame_length, flags, ..)) in FORMATS.into_iter().enumerate() { + let (bytes, _) = movie(i as u64 + 1, frame_length, flags); + craft_media_testkit::hostile::hammer(&format!("vmd sound format {i}"), &bytes, 10_000, |d| { + let Ok(file) = open(d) else { return }; + let Ok(decoder) = Decoder::new(file.header_bytes()) else { return }; + for (i, frame) in file.frames.iter().enumerate() { + let FrameKind::Audio { flags } = frame.kind else { continue }; + if let Ok(data) = file.read_frame(d, i) { + let _ = decoder.decode(flags, &data); + } + } + }); + } +} + +/// Real files, for whoever has some: the sound of every `.vmd` in the directory +/// `CRAFT_MEDIA_VMD_SAMPLES` names must decode to the samples ffmpeg gets. Game files are not +/// redistributable, so none are in the repository and the test is skipped without the variable. +#[test] +fn real_files_match_ffmpeg() { + let Some(dir) = std::env::var_os("CRAFT_MEDIA_VMD_SAMPLES").filter(|d| !d.is_empty()) else { + craft_media_testkit::skip_test("vmd samples", "CRAFT_MEDIA_VMD_SAMPLES is not set"); + return; + }; + let Some(ffmpeg) = craft_media_testkit::ffmpeg_or_skip("vmd sound samples") else { return }; + let mut paths: Vec<_> = std::fs::read_dir(&dir) + .unwrap() + .filter_map(|e| Some(e.ok()?.path())) + .filter(|p| p.extension().is_some_and(|e| e.eq_ignore_ascii_case("vmd"))) + .collect(); + paths.sort(); + assert!(!paths.is_empty(), "no .vmd files in CRAFT_MEDIA_VMD_SAMPLES"); + let (mut files, mut samples) = (0, 0); + for path in &paths { + let name = path.display(); + let source = std::fs::File::open(path).unwrap(); + let file = open(&source).unwrap(); + if file.audio_params().is_none() { + continue; + } + let d = Decoder::new(file.header_bytes()).unwrap(); + let mut ours = Vec::new(); + for (i, frame) in file.frames.iter().enumerate() { + let FrameKind::Audio { flags } = frame.kind else { continue }; + let mut data = file.read_frame(&source, i).unwrap(); + if flags == 2 && data.len() >= 4 { + // ffmpeg plays a mask frame's silent blocks before its sound; put ours in that + // order to compare + let silent = u32::from_le_bytes([data[0], data[1], data[2], data[3]]).count_ones() as usize; + ours.resize(ours.len() + silent * d.block_samples() * d.channels(), 0); + data[..4].fill(0); + } + ours.extend(d.decode(flags, &data).unwrap_or_else(|e| panic!("{name}: frame {i}: {e}"))); + } + let out = Command::new(&ffmpeg).args(["-v", "quiet", "-i"]).arg(path).args(["-vn", "-f", "s16le", "-"]).output().unwrap(); + let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + if let Some(at) = (0..ours.len().max(theirs.len())).find(|&i| ours.get(i) != theirs.get(i)) { + panic!("{name}: sample {at} differs from ffmpeg ({} samples here, {} there)", ours.len(), theirs.len()); + } + files += 1; + samples += ours.len(); + } + println!("{files} files, {samples} samples match ffmpeg"); +} diff --git a/crates/media-testkit/src/lib.rs b/crates/media-testkit/src/lib.rs index 6d3a75525..8894014dd 100644 --- a/crates/media-testkit/src/lib.rs +++ b/crates/media-testkit/src/lib.rs @@ -13,11 +13,13 @@ //! //! [`hostile::hammer`] runs a parser over truncations and mutations of a valid input and fails on //! a panic or a slow run; `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations. +//! [`vmd`] writes Sierra VMD fixtures, which ffmpeg can read but not write. //! //! Failing loudly is what a test helper is for: a wrong `CRAFT_MEDIA_*` setting or an unwritable //! fixture directory panics, which fails the test that asked. pub mod hostile; +pub mod vmd; use std::path::{Path, PathBuf}; use std::process::Command; diff --git a/crates/media-testkit/src/vmd.rs b/crates/media-testkit/src/vmd.rs new file mode 100644 index 000000000..c7068f19c --- /dev/null +++ b/crates/media-testkit/src/vmd.rs @@ -0,0 +1,343 @@ +//! Sierra VMD fixture writer. ffmpeg reads VMD but cannot write it, so the VMD tests build their +//! files here and use ffmpeg only to decode them. Written from the public format description +//! (); the packers favour coverage of every coding +//! mode over compression. + +use crate::hostile::Rng; + +/// Bytes of the file header. +pub const HEADER_LEN: usize = 816; + +/// The audio fields of the header. +#[derive(Clone, Copy, Debug)] +pub struct Audio { + /// Samples per second. + pub sample_rate: u16, + /// The frame length field as stored: negative for 16-bit sound. + pub frame_length: i16, + /// Number of sound buffers. + pub buffers: u16, + /// Audio flags (0x8000 old stereo, 0x200 new stereo). + pub flags: u16, +} + +/// What the header says. +#[derive(Clone, Debug)] +pub struct Spec { + /// Picture width in pixels. + pub width: u16, + /// Picture height in pixels. + pub height: u16, + /// Left coordinate of the picture. + pub left: u16, + /// Top coordinate of the picture. + pub top: u16, + /// 256 R-G-B triplets of 6-bit components. + pub palette: [u8; 768], + /// Size of the unpack buffer for LZ-packed frames. + pub unpack: u32, + /// Video codec version (header bytes 4-5). + pub codec_version: u16, + /// The sound, if the file has any. + pub audio: Option