Merge shared main and cover XFA DOM traversal and accessors

This commit is contained in:
Dylan M. Taylor committed 2026-11-17 11:51:04 -05:00
commit f788975eb9
42 files changed
+4787 -37

No files matched your search

+8
View File
@@ -119,9 +119,14 @@ The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper
`crates/palette` extracts the GPL text parser from AniCraft `crates/doc/src/swatch.rs` at `d875a7feb250e6ab06aa28a37fb78a0699e88330` (MIT OR Apache-2.0), introduced by Tanish Manku in `a64130a9da9bdde545463b852d95d6a6774b1dfd` (AniCraft #270). The import preserves Tanish as primary author. Neutral RGB/name adaptation separates application display-name sanitization and the `Untitled` policy; validation tests and integration are subsequent Dylan M. Taylor changes.
## TAR/CPIO compatibility updates
The old GNU sparse-extension traversal, GNU CRC-symlink compatibility and PAX-size precedence fixes and their regression tests in `crates/tar` are ported from RRFZ's Craft Anything PRs #1973 (`8ea2ec66a1bc80f0420f3695baac877a0cb9b9a5`), #1984 (`b226a475f7dce9710e3af7a069386fe7a9720df7`) and #2007 (`d29465c20b0d570ea4973be512a0cb4e212bb60f`). Source is MIT OR Apache-2.0; RRFZ remains the primary Git author of each port. The PAX update adapts to the shared parser's existing `PaxOverrides` structure without changing the source policy.
## Aligned stored ZIP entries
The USDZ alignment requirement and compatibility fixture for `Writer::add_stored_aligned` come from TextureCraft `crates/formats/src/mesh_export/usd.rs`, introduced by bflatastic in `bdbb52c9` and maintained through `9eb20086` (MIT OR Apache-2.0). The shared API and alignment validation are subsequent Dylan M. Taylor work. Scene/material mapping remains in TextureCraft.
The raw gradient wire ordering in `craft-lottie::Gradient::flat_values` follows
AniCraft's Lottie exporter by Tanish Manku (`63b39355`, `b9258b7b`), MIT OR Apache-2.0.
Sanitization, animation fitting and numeric output policy remain caller-owned.
@@ -136,3 +141,6 @@ Sanitization, animation fitting and numeric output policy remain caller-owned.
## XFA XML DOM
`crates/xfa/src/xml.rs` is extracted from PDFCraft at `271e479c53723b1b294c866d5cb2f27604601b29`, originally by Dylan M. Taylor (`eead4541`, `7d44e654`), MIT OR Apache-2.0. Only visibility and module boundaries change; PDF/layout/form policy remains in the app.
## HTTP Archive reader
`crates/har` preserves Craft Anything `crates/formats/src/har.rs` from `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the typed reader in `f64ae3bf3c8863a982af1304e06de20653803968`; BFlat added UTF-8 BOM compatibility in `cb0bb9d8fa4536ba44ef2c86f5ed759b879cc2d3`. Both source snapshots retain primary author attribution. Shared wiring, explicit byte admission and its tests are subsequent Dylan M. Taylor changes. Redaction and analysis remain app-owned.
Generated
+9
View File
@@ -2129,6 +2129,14 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-har"
version = "0.1.0"
dependencies = [
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-heif"
version = "0.1.0"
@@ -2903,6 +2911,7 @@ name = "craft-raster-codecs"
version = "0.1.0"
dependencies = [
"base64 0.23.1",
"craft-dds",
"craft-image-codecs",
"image",
"thiserror 2.0.21",
+1
View File
@@ -12,6 +12,7 @@ repository = "https://github.com/storytold/craft-libs"
[workspace.dependencies]
craft-xfa = { path = "crates/xfa" }
craft-har = { path = "crates/har" }
craft-jsonc = { path = "crates/jsonc" }
craft-palette = { path = "crates/palette" }
craft-score = { path = "crates/score" }
+1 -1
View File
@@ -274,7 +274,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)
+14
View File
@@ -41,6 +41,8 @@ aac-decode = ["craft-media/bitstream"]
# The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`.
aac-encode = ["craft-media/bitstream", "craft-media/isobmff"]
opus-decode = []
# ADPCM (`adpcm`): IMA WAV, Microsoft, Yamaha and Flash (SWF) decoders and encoders.
adpcm = ["craft-media/bitstream"]
# QOA (Quite OK Audio) files: decoder and encoder in the `qoa` module, each on its own.
qoa = ["qoa-decode", "qoa-encode"]
qoa-decode = []
@@ -69,6 +71,8 @@ mp3-encode = ["craft-media/bitstream"]
mpa-encode = ["mpa-decode", "mp3-encode"]
# Bluetooth Low Complexity Subband Coding (SBC) audio codec (`sbc`).
sbc = []
# 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`).
@@ -88,6 +92,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 }
@@ -95,6 +101,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"]
@@ -103,6 +113,10 @@ required-features = ["decode", "encode"]
name = "mp2_encoder_oracle"
required-features = ["mpa-encode"]
[[test]]
name = "adpcm_oracle"
required-features = ["adpcm"]
[[test]]
name = "flac_decode"
required-features = ["flac-decode", "flac-encode"]
+2
View File
@@ -45,7 +45,9 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` |
| `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` |
| `mpa-encode` | `mpa::encoder::Encoder` (Layer II / MP2 frames) | `mpa-decode`, `mp3-encode` |
| `adpcm` | `adpcm::{ima, ms, yamaha, swf}`: decoders and encoders for IMA WAV, Microsoft, Yamaha and Flash ADPCM | craft-media `bitstream` |
| `gsm-decode`, `gsm-encode` (`gsm`) | `gsm::Decoder`, `gsm::Encoder`, `gsm::decode`, `gsm::encode`: GSM 06.10 full-rate speech, bit-exact, raw `.gsm` and WAV (GSM 6.10) packings | none |
| `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` |
+247
View File
@@ -0,0 +1,247 @@
//! IMA ADPCM in WAV blocks (format tag 0x0011).
//!
//! A block is, per channel, a 4-byte header (the first sample as `i16` and the step index as `u8`,
//! then a zero byte), then groups of 4 bytes per channel in channel order, each holding eight
//! 4-bit codes, low nibble first. A block of `block_align` bytes holds
//! `(block_align - 4 * channels) * 2 / channels + 1` samples per channel. A code is a sign bit and
//! three magnitude bits: the decoder adds `step/8` plus `step`, `step/2` and `step/4` for each set
//! magnitude bit from the top, then moves the step index by `[-1, -1, -1, -1, 2, 4, 6, 8]`.
use super::{Error, Result, clip16, step_at};
const INDEX_ADJUST: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8];
/// The state of one channel's decoder.
#[derive(Clone, Copy)]
struct State {
predictor: i32,
index: i32,
}
impl State {
/// The sample after code `nibble`.
fn step(&mut self, nibble: u8) -> i16 {
let step = step_at(self.index);
let mut diff = step >> 3;
if nibble & 1 != 0 {
diff += step >> 2;
}
if nibble & 2 != 0 {
diff += step >> 1;
}
if nibble & 4 != 0 {
diff += step;
}
if nibble & 8 != 0 {
diff = -diff;
}
self.predictor = clip16(self.predictor + diff);
self.index = (self.index + INDEX_ADJUST.get(usize::from(nibble & 7)).copied().unwrap_or(0)).clamp(0, 88);
self.predictor as i16
}
/// The code that brings the predictor closest to `sample`, applied to the state.
fn encode(&mut self, sample: i16) -> u8 {
let step = step_at(self.index);
let mut diff = i32::from(sample) - self.predictor;
let mut code = 0u8;
if diff < 0 {
code = 8;
diff = -diff;
}
let mut s = step;
for bit in [4u8, 2, 1] {
if diff >= s {
code |= bit;
diff -= s;
}
s >>= 1;
}
self.step(code);
code
}
}
/// Samples per channel in a block of `block_align` bytes; `None` when the layout is impossible
/// (a block must hold the headers and whole groups of eight samples, and there are 1 to 8
/// channels).
pub fn samples_per_block(block_align: usize, channels: usize) -> Option<usize> {
if !(1..=8).contains(&channels) {
return None;
}
let header = 4 * channels;
let body = block_align.checked_sub(header)?;
if body == 0 || !body.is_multiple_of(4 * channels) {
return None;
}
let per = (body / channels).checked_mul(2)?.checked_add(1)?;
// Callers size interleaved buffers from this value; the full count must fit too.
per.checked_mul(channels)?;
Some(per)
}
/// Decode one block, appending its samples interleaved by channel to `out`.
pub fn decode_block(block: &[u8], channels: usize, out: &mut Vec<i16>) -> Result<()> {
let per = samples_per_block(block.len(), channels).ok_or(Error::Malformed("block size does not fit the channel count"))?;
let mut states = Vec::with_capacity(channels);
for ch in 0..channels {
let h = block.get(4 * ch..4 * ch + 4).ok_or(Error::Malformed("truncated block header"))?;
let index = i32::from(h[2]);
if index > 88 {
return Err(Error::Malformed("step index above 88"));
}
states.push(State { predictor: i32::from(i16::from_le_bytes([h[0], h[1]])), index });
}
let start = out.len();
out.resize(start + per * channels, 0);
let samples = out.get_mut(start..).ok_or(Error::Malformed("output"))?;
for (ch, s) in states.iter().enumerate() {
if let Some(o) = samples.get_mut(ch) {
*o = s.predictor as i16;
}
}
let body = block.get(4 * channels..).ok_or(Error::Malformed("truncated block"))?;
for (g, group) in body.chunks_exact(4 * channels).enumerate() {
for (ch, bytes) in group.as_chunks::<4>().0.iter().enumerate() {
let Some(state) = states.get_mut(ch) else { continue };
for (k, b) in bytes.iter().enumerate() {
for (half, nibble) in [b & 0xF, b >> 4].into_iter().enumerate() {
let t = 1 + g * 8 + k * 2 + half;
if let Some(o) = samples.get_mut(t * channels + ch) {
*o = state.step(nibble);
}
}
}
}
}
Ok(())
}
/// Decode a stream of blocks of `block_align` bytes. A final partial block is decoded as far as it
/// holds whole groups.
pub fn decode(data: &[u8], channels: usize, block_align: usize) -> Result<Vec<i16>> {
samples_per_block(block_align, channels).ok_or(Error::Malformed("block size does not fit the channel count"))?;
let mut out = Vec::new();
for block in data.chunks(block_align) {
if block.len() == block_align {
decode_block(block, channels, &mut out)?;
} else {
let (header, group) = (4 * channels, 4 * channels);
let whole = block.len().saturating_sub(header) / group * group;
if whole > 0 {
decode_block(block.get(..header + whole).unwrap_or(block), channels, &mut out)?;
}
}
}
Ok(out)
}
/// The starting step index for a channel whose first samples are `x`: the index whose first
/// codes follow `x` most closely.
fn start_index(first: i16, x: &[i16]) -> i32 {
let mut best = (i64::MAX, 0);
for index in 0..=88 {
let mut st = State { predictor: i32::from(first), index };
let mut err = 0i64;
for &s in x.iter().take(16) {
let code = st.encode(s);
let _ = code;
err += (i64::from(s) - i64::from(st.predictor)).pow(2);
}
if err < best.0 {
best = (err, index);
}
}
best.1
}
/// Encode one block from exactly `samples_per_block * channels` interleaved samples.
pub fn encode_block(samples: &[i16], channels: usize, block_align: usize) -> Result<Vec<u8>> {
let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?;
if samples.len() != per * channels {
return Err(Error::InvalidInput("a block needs exactly samples_per_block samples per channel"));
}
let mut block = vec![0u8; block_align];
let mut states = Vec::with_capacity(channels);
for ch in 0..channels {
let col: Vec<i16> = samples.iter().skip(ch).step_by(channels).copied().collect();
let first = col.first().copied().unwrap_or(0);
let st = State { predictor: i32::from(first), index: start_index(first, col.get(1..).unwrap_or(&[])) };
if let Some(h) = block.get_mut(4 * ch..4 * ch + 4) {
h[..2].copy_from_slice(&first.to_le_bytes());
h[2] = st.index as u8;
}
states.push(st);
}
let groups = (block_align - 4 * channels) / (4 * channels);
for g in 0..groups {
for ch in 0..channels {
let Some(state) = states.get_mut(ch) else { continue };
for k in 0..4 {
let mut byte = 0u8;
for half in 0..2 {
let t = 1 + g * 8 + k * 2 + half;
let nibble = state.encode(samples.get(t * channels + ch).copied().unwrap_or(0));
byte |= nibble << (4 * half);
}
if let Some(b) = block.get_mut(4 * channels + g * 4 * channels + ch * 4 + k) {
*b = byte;
}
}
}
}
Ok(block)
}
/// Encode interleaved samples as blocks of `block_align` bytes. The last block is padded with
/// copies of the last sample, so a decoder returns up to one block more than was given.
pub fn encode(samples: &[i16], channels: usize, block_align: usize) -> Result<Vec<u8>> {
let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?;
if !samples.len().is_multiple_of(channels) {
return Err(Error::InvalidInput("the sample count is not a multiple of the channel count"));
}
let mut out = Vec::new();
for chunk in samples.chunks(per * channels) {
if chunk.len() == per * channels {
out.extend(encode_block(chunk, channels, block_align)?);
} else {
let mut padded = chunk.to_vec();
let last: Vec<i16> = chunk.get(chunk.len().saturating_sub(channels)..).unwrap_or(&[]).to_vec();
while padded.len() < per * channels {
padded.extend(last.iter().copied().chain(std::iter::repeat(0)).take(channels));
}
out.extend(encode_block(&padded, channels, block_align)?);
}
}
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn layout() {
assert_eq!(samples_per_block(256, 1), Some(505));
assert_eq!(samples_per_block(512, 2), Some(505));
assert_eq!(samples_per_block(4, 1), None);
assert_eq!(samples_per_block(100, 0), None);
assert_eq!(samples_per_block(258, 2), None);
}
#[test]
fn unrepresentable_interleaved_layout_is_rejected() {
let align = usize::MAX - 7;
assert_eq!(samples_per_block(align, 2), None);
assert!(encode(&[], 2, align).is_err());
assert!(encode_block(&[], 2, align).is_err());
}
#[test]
fn silence_stays_silent() {
let block = encode_block(&vec![0; 505], 1, 256).unwrap();
let mut out = Vec::new();
decode_block(&block, 1, &mut out).unwrap();
assert!(out.iter().all(|&s| s == 0));
}
}
+56
View File
@@ -0,0 +1,56 @@
//! ADPCM: a decoder and an encoder for four families, each on whole blocks or streams of `i16`
//! samples interleaved by channel (feature `adpcm`).
//!
//! - [`ima`]: IMA / DVI ADPCM in WAV blocks (format tag 0x0011): 4 bits per sample, a 4-byte header
//! per channel and groups of eight samples per channel.
//! - [`ms`]: Microsoft ADPCM in WAV blocks (format tag 0x0002): 4 bits per sample, adaptive
//! two-tap prediction with the seven standard coefficient pairs.
//! - [`yamaha`]: Yamaha ADPCM (the YM2608 / AICA family): a raw stream of 4-bit codes.
//! - [`swf`]: the ADPCM of Flash (SWF) audio: 2 to 5 bits per sample, in blocks of 4096 samples.
//!
//! Written from the public descriptions of the algorithms: the IMA Digital Audio Focus and
//! Technical Working Groups' *Recommended Practices for Enhancing Digital Audio Compatibility*
//! (IMA ADPCM), Microsoft's *Multimedia Standards Update* (the WAVE format tags and the block
//! layout of Microsoft ADPCM), the SWF file format specification (the ADPCM section) and the
//! Yamaha ADPCM-B description. ffmpeg is only run as a black-box oracle in the tests.
//!
//! Decoders return errors, never panic, on damaged blocks. Encoders are greedy: they choose each
//! code to bring the decoder's output closest to the sample.
pub mod ima;
pub mod ms;
pub mod swf;
pub mod yamaha;
/// What went wrong decoding or encoding ADPCM.
#[non_exhaustive]
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum Error {
/// The data is damaged, truncated or does not fit the stated block layout.
#[error("malformed ADPCM: {0}")]
Malformed(&'static str),
/// The settings or samples given to an encoder cannot be written.
#[error("ADPCM cannot encode: {0}")]
InvalidInput(&'static str),
}
/// Result with this module's [`Error`].
pub type Result<T> = std::result::Result<T, Error>;
/// IMA ADPCM step sizes (the 89-entry table of the IMA recommended practices).
pub(crate) const STEP_TABLE: [i32; 89] = [
7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66, 73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190,
209, 230, 253, 279, 307, 337, 371, 408, 449, 494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272, 2499,
2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493, 10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350,
22385, 24623, 27086, 29794, 32767,
];
/// Clamp to the 16-bit sample range.
pub(crate) fn clip16(v: i32) -> i32 {
v.clamp(i32::from(i16::MIN), i32::from(i16::MAX))
}
/// The step size at `index` (clamped to the table).
pub(crate) fn step_at(index: i32) -> i32 {
STEP_TABLE.get(index.clamp(0, 88) as usize).copied().unwrap_or(7)
}
+244
View File
@@ -0,0 +1,244 @@
//! Microsoft ADPCM in WAV blocks (format tag 0x0002).
//!
//! A block starts, for all channels in turn, with one predictor index (a byte, 0 to 6), then one
//! initial step (`delta`, `i16`), then each channel's second-last sample (`sample1`, `i16`) and
//! last sample (`sample2`, `i16`) before the block; the block's first two samples per channel are
//! `sample2` then `sample1`. The rest is 4-bit two's-complement codes, the first channel in the
//! high nibble. A block of `block_align` bytes holds `(block_align - 7 * channels) * 2 / channels
//! + 2` samples per channel. Each sample is predicted as `(sample1 * c1 + sample2 * c2) / 256` (rounding toward zero)
//! from the block's coefficient pair, plus `code * delta`; then `delta` becomes
//! `max(16, delta * a / 256)`, where `a` is the table entry for the code (`ADAPT`).
use super::{Error, Result, clip16};
/// The seven coefficient pairs `(c1, c2)` every Microsoft ADPCM stream uses.
pub const COEFFICIENTS: [(i32, i32); 7] = [(256, 0), (512, -256), (0, 0), (192, 64), (240, 0), (460, -208), (392, -232)];
/// How the step moves with the code's unsigned value (the index is the 4-bit pattern).
/// The largest step. The reference keeps it in 16 bits and no real stream gets near this bound; it
/// keeps every product in range however long a damaged block runs.
const MAX_DELTA: i32 = 1 << 24;
const ADAPT: [i32; 16] = [230, 230, 230, 230, 307, 409, 512, 614, 768, 614, 512, 409, 307, 230, 230, 230];
#[derive(Clone, Copy)]
struct State {
c1: i32,
c2: i32,
delta: i32,
s1: i32,
s2: i32,
}
impl State {
fn step(&mut self, nibble: u8) -> i16 {
let signed = i32::from(nibble) - if nibble & 8 != 0 { 16 } else { 0 };
let predicted = (self.s1 * self.c1 + self.s2 * self.c2) / 256;
let sample = clip16(predicted + signed * self.delta);
self.s2 = self.s1;
self.s1 = sample;
let adapt = i64::from(ADAPT.get(usize::from(nibble)).copied().unwrap_or(256));
let new_delta = (adapt * i64::from(self.delta)) >> 8;
self.delta = (new_delta.min(i64::from(MAX_DELTA)) as i32).max(16);
sample as i16
}
/// The code that brings the output closest to `sample`, applied to the state.
fn encode(&mut self, sample: i16) -> u8 {
let predicted = (self.s1 * self.c1 + self.s2 * self.c2) / 256;
let err = i32::from(sample) - predicted;
// round to the nearest multiple of delta
let q = if err >= 0 { (err + self.delta / 2) / self.delta } else { -((-err + self.delta / 2) / self.delta) };
let code = (q.clamp(-8, 7) & 0xF) as u8;
self.step(code);
code
}
}
/// Samples per channel in a block of `block_align` bytes; `None` for an impossible layout (1 or 2
/// channels, and room for the header and at least one code byte).
pub fn samples_per_block(block_align: usize, channels: usize) -> Option<usize> {
if !(1..=2).contains(&channels) {
return None;
}
let body = block_align.checked_sub(7 * channels).filter(|&b| b > 0)?;
// codes pair up across channels
let per = (body.checked_mul(2)? / channels).checked_add(2)?;
// Include the header samples and all channels before callers size their buffers.
per.checked_mul(channels)?;
Some(per)
}
/// Decode one block, appending its samples interleaved by channel to `out`.
pub fn decode_block(block: &[u8], channels: usize, out: &mut Vec<i16>) -> Result<()> {
let per = samples_per_block(block.len(), channels).ok_or(Error::Malformed("block size does not fit the channel count"))?;
let header = block.get(..7 * channels).ok_or(Error::Malformed("truncated block header"))?;
let mut states = Vec::with_capacity(channels);
let word = |i: usize| i32::from(i16::from_le_bytes([header.get(i).copied().unwrap_or(0), header.get(i + 1).copied().unwrap_or(0)]));
for ch in 0..channels {
let pred = usize::from(header.get(ch).copied().unwrap_or(0));
let &(c1, c2) = COEFFICIENTS.get(pred).ok_or(Error::Malformed("predictor index above 6"))?;
states.push(State { c1, c2, delta: word(channels + 2 * ch), s1: word(3 * channels + 2 * ch), s2: word(5 * channels + 2 * ch) });
}
let start = out.len();
out.resize(start + per * channels, 0);
let samples = out.get_mut(start..).ok_or(Error::Malformed("output"))?;
for (ch, s) in states.iter().enumerate() {
if let Some(a) = samples.get_mut(ch) {
*a = s.s2 as i16;
}
if let Some(b) = samples.get_mut(channels + ch) {
*b = s.s1 as i16;
}
}
let codes = block.get(7 * channels..).ok_or(Error::Malformed("truncated block"))?;
let mut t = 2 * channels;
for byte in codes {
for nibble in [byte >> 4, byte & 0xF] {
let ch = t % channels;
if let (Some(o), Some(state)) = (samples.get_mut(t), states.get_mut(ch)) {
*o = state.step(nibble);
}
t += 1;
}
}
Ok(())
}
/// Decode a stream of blocks of `block_align` bytes. A final partial block is decoded in full if
/// it holds a header and a code byte.
pub fn decode(data: &[u8], channels: usize, block_align: usize) -> Result<Vec<i16>> {
samples_per_block(block_align, channels).ok_or(Error::Malformed("block size does not fit the channel count"))?;
let mut out = Vec::new();
for block in data.chunks(block_align) {
if block.len() == block_align || samples_per_block(block.len(), channels).is_some() {
decode_block(block, channels, &mut out)?;
}
}
Ok(out)
}
/// The squared error of encoding `col` (one channel) from state `st`.
fn trial(mut st: State, col: &[i16]) -> i64 {
let mut err = 0i64;
for &s in col {
st.encode(s);
err += (i64::from(s) - i64::from(st.s1)).pow(2);
}
err
}
/// Encode one block from exactly `samples_per_block * channels` interleaved samples. Each channel
/// gets the coefficient pair and initial step that code it with the least error.
pub fn encode_block(samples: &[i16], channels: usize, block_align: usize) -> Result<Vec<u8>> {
let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?;
if samples.len() != per * channels {
return Err(Error::InvalidInput("a block needs exactly samples_per_block samples per channel"));
}
let mut block = vec![0u8; block_align];
let mut states = Vec::with_capacity(channels);
for ch in 0..channels {
let col: Vec<i16> = samples.iter().skip(ch).step_by(channels).copied().collect();
let (x0, x1) = (col.first().copied().unwrap_or(0), col.get(1).copied().unwrap_or(0));
let rest = col.get(2..).unwrap_or(&[]);
let mut best: Option<(i64, usize, i32)> = None;
for (p, &(c1, c2)) in COEFFICIENTS.iter().enumerate() {
for delta in [16, 64, 256, 1024] {
let st = State { c1, c2, delta, s1: i32::from(x1), s2: i32::from(x0) };
let e = trial(st, rest);
if best.is_none_or(|(b, _, _)| e < b) {
best = Some((e, p, delta));
}
}
}
let (_, p, delta) = best.unwrap_or((0, 0, 16));
let &(c1, c2) = COEFFICIENTS.get(p).unwrap_or(&(256, 0));
states.push(State { c1, c2, delta, s1: i32::from(x1), s2: i32::from(x0) });
let (d, a, b) = (delta as i16, x1, x0);
let put = |block: &mut Vec<u8>, at: usize, v: i16| {
if let Some(w) = block.get_mut(at..at + 2) {
w.copy_from_slice(&v.to_le_bytes());
}
};
if let Some(h) = block.get_mut(ch) {
*h = p as u8;
}
put(&mut block, channels + 2 * ch, d);
put(&mut block, 3 * channels + 2 * ch, a);
put(&mut block, 5 * channels + 2 * ch, b);
}
let mut t = 2 * channels;
for byte in block.iter_mut().skip(7 * channels) {
let mut b = 0u8;
for half in 0..2 {
let ch = t % channels;
let nibble = match states.get_mut(ch) {
Some(st) => st.encode(samples.get(t).copied().unwrap_or(0)),
None => 0,
};
b |= nibble << (4 * (1 - half));
t += 1;
}
*byte = b;
}
Ok(block)
}
/// Encode interleaved samples as blocks of `block_align` bytes. The last block is padded with
/// copies of the last frame, so a decoder returns up to one block more than was given.
pub fn encode(samples: &[i16], channels: usize, block_align: usize) -> Result<Vec<u8>> {
let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?;
if !samples.len().is_multiple_of(channels) {
return Err(Error::InvalidInput("the sample count is not a multiple of the channel count"));
}
let mut out = Vec::new();
for chunk in samples.chunks(per * channels) {
let mut padded = chunk.to_vec();
let last: Vec<i16> = chunk.get(chunk.len().saturating_sub(channels)..).unwrap_or(&[]).to_vec();
while padded.len() < per * channels {
padded.extend(last.iter().copied().chain(std::iter::repeat(0)).take(channels));
}
out.extend(encode_block(&padded, channels, block_align)?);
}
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn layout() {
assert_eq!(samples_per_block(256, 1), Some(500));
assert_eq!(samples_per_block(512, 2), Some(500));
assert_eq!(samples_per_block(7, 1), None);
assert_eq!(samples_per_block(100, 3), None);
}
#[test]
fn unrepresentable_layouts_are_rejected() {
for (align, channels) in [(usize::MAX / 2 + 7, 1), (usize::MAX / 2 + 14, 2)] {
assert_eq!(samples_per_block(align, channels), None);
assert!(encode(&[], channels, align).is_err());
assert!(encode_block(&[], channels, align).is_err());
}
}
#[test]
fn a_long_run_of_large_codes_cannot_overflow() {
// a step that starts at its largest 16-bit value and grows with every large code
let mut block = vec![0x77u8; 7 + 2000];
block[..7].copy_from_slice(&[0, 255, 127, 0, 0, 0, 0]);
for b in block.iter_mut().skip(7) {
*b = 0x88;
}
let mut out = Vec::new();
decode_block(&block, 1, &mut out).unwrap();
assert_eq!(out.len(), 2000 * 2 + 2);
}
#[test]
fn bad_predictor_index_is_an_error() {
let mut block = vec![0u8; 64];
block[0] = 7;
assert!(decode_block(&block, 1, &mut Vec::new()).is_err());
}
}
+168
View File
@@ -0,0 +1,168 @@
//! The ADPCM of Flash (SWF) audio, 2 to 5 bits per sample.
//!
//! The stream starts with two bits, the code size minus 2. It continues in blocks of 4096 samples
//! per channel: each block starts, for every channel, with the first sample (16 bits, signed) and
//! the step index (6 bits, 0 to 88), then 4095 codes per channel, interleaved by sample. All fields
//! are packed most significant bit first. A code is a sign bit and `bits - 1` magnitude bits; the
//! decoder adds `step >> (bits - 1)` plus `step >> k` for each magnitude bit set `k` places below
//! the top one, negated when the sign is set, and moves the step index by the adjustment table of
//! the code size (negative for small magnitudes, positive for large ones). The last block may
//! be shorter.
use super::{Error, Result, clip16, step_at};
use craft_media::bitstream::{BitReader, BitWriter};
/// Samples per channel in a full block.
pub const BLOCK_SAMPLES: usize = 4096;
/// The index adjustment for each magnitude, per code size.
fn adjust(bits: u32) -> &'static [i32] {
match bits {
2 => &[-1, 2],
3 => &[-1, -1, 2, 4],
4 => &[-1, -1, -1, -1, 2, 4, 6, 8],
_ => &[-1, -1, -1, -1, -1, -1, -1, -1, 1, 2, 4, 6, 8, 10, 13, 16],
}
}
#[derive(Clone, Copy)]
struct State {
predictor: i32,
index: i32,
}
impl State {
fn apply(&mut self, code: u32, bits: u32) -> i16 {
let step = step_at(self.index);
let mag = code & ((1 << (bits - 1)) - 1);
let mut diff = step >> (bits - 1);
for k in 0..bits - 1 {
if mag & (1 << (bits - 2 - k)) != 0 {
diff += step >> k;
}
}
if code & (1 << (bits - 1)) != 0 {
diff = -diff;
}
self.predictor = clip16(self.predictor + diff);
self.index = (self.index + adjust(bits).get(mag as usize).copied().unwrap_or(0)).clamp(0, 88);
self.predictor as i16
}
fn encode(&mut self, sample: i16, bits: u32) -> u32 {
let step = step_at(self.index);
let mut diff = i32::from(sample) - self.predictor;
let mut code = 0u32;
if diff < 0 {
code = 1 << (bits - 1);
diff = -diff;
}
let mut s = step;
for k in 0..bits - 1 {
if diff >= s {
code |= 1 << (bits - 2 - k);
diff -= s;
}
s >>= 1;
}
self.apply(code, bits);
code
}
}
/// Decode a stream. `channels` is 1 or 2; the code size comes from the stream's first two bits.
/// The result holds every sample up to the end of the data (a last block cut short decodes as
/// far as it goes).
pub fn decode(data: &[u8], channels: usize) -> Result<Vec<i16>> {
if !(1..=2).contains(&channels) {
return Err(Error::Malformed("Flash ADPCM has one or two channels"));
}
let mut r = BitReader::new(data);
let bits = r.read_bits(2).map_err(|_| Error::Malformed("empty stream"))? + 2;
let mut out = Vec::new();
let header_bits = channels * 22;
while r.bits_left() >= header_bits {
let mut states = Vec::with_capacity(channels);
for _ in 0..channels {
let sample = r.read_bits(16).map_err(|_| Error::Malformed("truncated block"))? as u16 as i16;
let index = r.read_bits(6).map_err(|_| Error::Malformed("truncated block"))? as i32;
if index > 88 {
return Err(Error::Malformed("step index above 88"));
}
out.push(sample);
states.push(State { predictor: i32::from(sample), index });
}
'block: for _ in 1..BLOCK_SAMPLES {
if r.bits_left() < channels * (bits as usize) {
break 'block;
}
for st in states.iter_mut() {
match r.read_bits(bits) {
Ok(code) => out.push(st.apply(code, bits)),
Err(_) => break 'block,
}
}
}
}
Ok(out)
}
/// Encode interleaved samples with `bits` (2 to 5) bits per sample. Blocks hold 4096 samples per
/// channel; the stream ends at a byte boundary.
pub fn encode(samples: &[i16], channels: usize, bits: u32) -> Result<Vec<u8>> {
if !(1..=2).contains(&channels) {
return Err(Error::InvalidInput("Flash ADPCM has one or two channels"));
}
if !(2..=5).contains(&bits) {
return Err(Error::InvalidInput("Flash ADPCM codes have 2 to 5 bits"));
}
if !samples.len().is_multiple_of(channels) {
return Err(Error::InvalidInput("the sample count is not a multiple of the channel count"));
}
let mut w = BitWriter::new();
w.write_bits(bits - 2, 2);
for block in samples.chunks(BLOCK_SAMPLES * channels) {
let mut states = Vec::with_capacity(channels);
for ch in 0..channels {
let col: Vec<i16> = block.iter().skip(ch).step_by(channels).copied().collect();
let first = col.first().copied().unwrap_or(0);
// the index whose first codes follow the signal most closely
let mut best = (i64::MAX, 0);
for index in 0..=63 {
let mut st = State { predictor: i32::from(first), index };
let mut err = 0i64;
for &s in col.iter().skip(1).take(16) {
st.encode(s, bits);
err += (i64::from(s) - i64::from(st.predictor)).pow(2);
}
if err < best.0 {
best = (err, index);
}
}
w.write_bits(u32::from(first as u16), 16);
w.write_bits(best.1 as u32, 6);
states.push(State { predictor: i32::from(first), index: best.1 });
}
for frame in block.chunks(channels).skip(1) {
for (st, &s) in states.iter_mut().zip(frame) {
w.write_bits(st.encode(s, bits), bits);
}
}
}
w.align_zero();
Ok(w.finish())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn settings_are_checked() {
assert!(encode(&[0], 3, 4).is_err());
assert!(encode(&[0], 1, 1).is_err());
assert!(encode(&[0], 1, 6).is_err());
assert!(decode(&[], 1).is_err());
assert!(decode(&[0], 0).is_err());
}
}
+113
View File
@@ -0,0 +1,113 @@
//! Yamaha ADPCM (the ADPCM-B of the YM2608 and the AICA): a raw stream of 4-bit codes, no header.
//!
//! Each channel starts at predictor 0 and step 127. A code is a sign bit and three magnitude bits;
//! the sample moves by `step * [1, 3, 5, 7, 9, 11, 13, 15][magnitude] / 8` (negative when the sign
//! is set) and the step is multiplied by `[230, 230, 230, 230, 307, 409, 512, 614][magnitude] / 256`,
//! kept within 127 and 24576. One channel: the low nibble of a byte is the first sample. Two
//! channels: the low nibble is the left channel and the high nibble the right one of the same
//! frame.
use super::{Error, Result, clip16};
const SCALE: [i32; 8] = [230, 230, 230, 230, 307, 409, 512, 614];
#[derive(Clone, Copy)]
struct State {
predictor: i32,
step: i32,
}
impl State {
fn new() -> State {
State { predictor: 0, step: 127 }
}
fn apply(&mut self, nibble: u8) -> i16 {
let m = usize::from(nibble & 7);
let diff = self.step * (2 * m as i32 + 1) / 8;
self.predictor = clip16(self.predictor + if nibble & 8 != 0 { -diff } else { diff });
self.step = ((self.step * SCALE.get(m).copied().unwrap_or(256)) >> 8).clamp(127, 24_576);
self.predictor as i16
}
fn encode(&mut self, sample: i16) -> u8 {
let err = i32::from(sample) - self.predictor;
let m = (err.abs() * 8 / self.step / 2).clamp(0, 7);
// the magnitude whose reconstruction (2m + 1) * step / 8 is nearest
let mut best = (i32::MAX, 0u8);
for cand in [m - 1, m, m + 1] {
let c = cand.clamp(0, 7);
let recon = self.step * (2 * c + 1) / 8;
let e = (err.abs() - recon).abs();
if e < best.0 {
best = (e, c as u8);
}
}
let nibble = best.1 | if err < 0 { 8 } else { 0 };
self.apply(nibble);
nibble
}
}
/// Decode a stream of `channels` (1 or 2) interleaved channels.
pub fn decode(data: &[u8], channels: usize) -> Result<Vec<i16>> {
if !(1..=2).contains(&channels) {
return Err(Error::Malformed("Yamaha ADPCM has one or two channels"));
}
let mut states = vec![State::new(); channels];
let mut out = Vec::with_capacity(data.len() * 2);
let mut t = 0usize;
for byte in data {
for nibble in [byte & 0xF, byte >> 4] {
if let Some(st) = states.get_mut(t % channels) {
out.push(st.apply(nibble));
}
t += 1;
}
}
Ok(out)
}
/// Encode interleaved samples. With two channels the frame count must be whole bytes, which it
/// always is; with one channel an odd count is padded with a copy of the last sample.
pub fn encode(samples: &[i16], channels: usize) -> Result<Vec<u8>> {
if !(1..=2).contains(&channels) {
return Err(Error::InvalidInput("Yamaha ADPCM has one or two channels"));
}
if !samples.len().is_multiple_of(channels) {
return Err(Error::InvalidInput("the sample count is not a multiple of the channel count"));
}
let mut states = vec![State::new(); channels];
let mut out = Vec::with_capacity(samples.len().div_ceil(2));
let mut t = 0usize;
let mut padded = samples.to_vec();
if padded.len() % 2 == 1 {
padded.push(padded.last().copied().unwrap_or(0));
}
for pair in padded.chunks(2) {
let mut byte = 0u8;
for (half, &s) in pair.iter().enumerate() {
let code = match states.get_mut(t % channels) {
Some(st) => st.encode(s),
None => 0,
};
byte |= code << (4 * half);
t += 1;
}
out.push(byte);
}
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn channel_count_is_checked() {
assert!(decode(&[0], 0).is_err());
assert!(decode(&[0], 3).is_err());
assert!(encode(&[0], 3).is_err());
assert!(encode(&[0, 0, 0], 2).is_err());
}
}
+18 -2
View File
@@ -30,8 +30,10 @@
//! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and
//! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`; `mpa-encode`: the Layer II encoder), [`mp3`]
//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-decode`: the frame and file decoder;
//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files),
//! [`gsm`] (`gsm-decode`, `gsm-encode`: GSM 06.10 full-rate speech).
//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files), [`adpcm`]
//! (`adpcm`: IMA WAV, Microsoft, Yamaha and Flash ADPCM),
//! [`gsm`] (`gsm-decode`, `gsm-encode`: GSM 06.10 full-rate speech), [`vmd`] (`vmd-decode`:
//! Sierra VMD sound).
//!
//! The shared types below build with no features.
@@ -39,6 +41,8 @@
pub mod aac;
#[cfg(any(feature = "ac3-decode", feature = "ac3-encode", feature = "eac3-encode"))]
pub mod ac3;
#[cfg(feature = "adpcm")]
pub mod adpcm;
#[cfg(any(feature = "alac-decode", feature = "alac-encode"))]
pub mod alac;
mod buffer;
@@ -65,6 +69,8 @@ mod read;
pub mod sbc;
#[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(feature = "vorbis-encode")]
pub mod vorbis;
#[cfg(any(feature = "decode-native", feature = "pcm-encode"))]
@@ -269,6 +275,16 @@ impl From<alac::Error> for AudioError {
}
}
#[cfg(feature = "vmd-decode")]
impl From<vmd::Error> 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<opus::encoder::Error> for AudioError {
fn from(e: opus::encoder::Error) -> Self {
+192
View File
@@ -0,0 +1,192 @@
//! 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 <https://wiki.multimedia.cx/index.php/VMD>
//! ("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 (the first sound frame of a file), 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 block is at most 65 535 samples a channel and is decoded only
//! if all of it is there; a frame with a silence mask yields at most 32 blocks (the width of
//! the mask), any other frame as many whole blocks as its data holds. 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_total: 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<Decoder, Error> {
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 || u16_at(804) == 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_total) = 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_total })
}
/// 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_total / self.channels
}
/// Bytes of one block of sound in a frame.
pub fn block_bytes(&self) -> usize {
if self.sixteen_bit { (self.block_total + self.channels).min(self.block_total * 2) } else { self.block_total }
}
/// 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 (every whole block, if the frame holds more);
/// - 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. With flags 1, a first block cut short is an error. A part
/// of a block after the last whole one is left out, with flags 1 and 2.
///
/// The sound of a file is its sound frames decoded in file order and played end to end from
/// the first picture on: see `craft_media::vmd` for how that lines up with the pictures.
pub fn decode(&self, flags: u8, data: &[u8]) -> Result<Vec<i16>, Error> {
let mut out = Vec::new();
match flags {
3 => out.resize(self.block_total, 0),
1 | 2 if data.is_empty() => {}
1 => {
// one block; a frame that holds more whole blocks plays them all, as in ffmpeg
self.block(data, &mut out)?;
let size = self.block_bytes();
if size > 0 {
for more in data[size..].chunks_exact(size) {
self.block(more, &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_total, 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<i16>) -> 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(())
}
}
+516
View File
@@ -0,0 +1,516 @@
//! ADPCM (feature `adpcm`): every family decodes what ffmpeg's encoder writes to ffmpeg's own
//! samples, and ffmpeg decodes what our encoder writes to our own decoder's samples (oracle;
//! skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`); plus the
//! round trip through our own encoder and decoder, and damaged input.
use craft_audio::adpcm::{ima, ms, swf, yamaha};
use std::path::Path;
use std::process::Command;
const RATE: u32 = 22_050;
/// Interleaved test audio: tones, a sweep, noise bursts, silence and a full-scale square.
fn signal(channels: usize, frames: usize) -> Vec<i16> {
let mut seed = 0x2545_F491u32;
let mut out = Vec::with_capacity(frames * channels);
for i in 0..frames {
for c in 0..channels {
seed ^= seed << 13;
seed ^= seed >> 17;
seed ^= seed << 5;
let t = i as f64;
let v = match (i / 1500) % 5 {
0 => (t * (0.03 + 0.011 * c as f64)).sin() * 9000.0,
1 => (t * 0.002 * (1.0 + t / 3000.0)).sin() * 14000.0,
2 => f64::from(seed % 12000) - 6000.0,
3 => 0.0,
_ => {
if (i / 40) % 2 == 0 {
20000.0
} else {
-20000.0
}
}
};
out.push(v as i16);
}
}
out
}
fn snr(a: &[i16], b: &[i16]) -> f64 {
let (mut s, mut n) = (0f64, 0f64);
for (x, y) in a.iter().zip(b) {
s += f64::from(*x).powi(2);
n += (f64::from(*x) - f64::from(*y)).powi(2);
}
10.0 * (s / n.max(1.0)).log10()
}
fn max_diff(a: &[i16], b: &[i16]) -> i32 {
a.iter().zip(b).map(|(x, y)| (i32::from(*x) - i32::from(*y)).abs()).max().unwrap_or(0)
}
#[test]
fn encode_then_decode_is_close_to_the_input() {
for channels in [1usize, 2] {
let x = signal(channels, 20_000);
// (name, decoded, minimum SNR dB, a few dB under what each reaches): the signal has noise bursts
// and full-scale square waves, which codes this small follow loosely
let cases: Vec<(&str, Vec<i16>, f64)> = vec![
("ima", ima::decode(&ima::encode(&x, channels, 512).unwrap(), channels, 512).unwrap(), 5.0),
("ms", ms::decode(&ms::encode(&x, channels, 512).unwrap(), channels, 512).unwrap(), 18.0),
("yamaha", yamaha::decode(&yamaha::encode(&x, channels).unwrap(), channels).unwrap(), 5.0),
("swf2", swf::decode(&swf::encode(&x, channels, 2).unwrap(), channels).unwrap(), 1.0),
("swf3", swf::decode(&swf::encode(&x, channels, 3).unwrap(), channels).unwrap(), 3.0),
("swf4", swf::decode(&swf::encode(&x, channels, 4).unwrap(), channels).unwrap(), 5.0),
("swf5", swf::decode(&swf::encode(&x, channels, 5).unwrap(), channels).unwrap(), 7.0),
];
for (name, y, min) in cases {
assert!(y.len() >= x.len(), "{name}: {} samples for {}", y.len(), x.len());
let s = snr(&x, &y[..x.len()]);
println!("{name} {channels}ch: SNR {s:.1} dB");
assert!(s >= min, "{name} {channels}ch: SNR {s:.1} dB under {min}");
}
}
}
#[test]
fn damaged_input_is_an_error_or_decodes_never_panics() {
let x = signal(2, 4000);
let streams: Vec<(&str, Vec<u8>)> = vec![
("ima", ima::encode(&x, 2, 256).unwrap()),
("ms", ms::encode(&x, 2, 256).unwrap()),
("yamaha", yamaha::encode(&x, 2).unwrap()),
("swf", swf::encode(&x, 2, 4).unwrap()),
];
let mut seed = 99u32;
for (name, s) in &streams {
for cut in (0..s.len()).step_by(7) {
let part = &s[..cut];
let _ = match *name {
"ima" => ima::decode(part, 2, 256).map(drop),
"ms" => ms::decode(part, 2, 256).map(drop),
"yamaha" => yamaha::decode(part, 2).map(drop),
_ => swf::decode(part, 2).map(drop),
};
}
for _ in 0..300 {
let mut d = s.clone();
seed ^= seed << 13;
seed ^= seed >> 17;
seed ^= seed << 5;
let at = seed as usize % d.len();
d[at] ^= (seed >> 8) as u8 | 1;
let _ = match *name {
"ima" => ima::decode(&d, 2, 256).map(drop),
"ms" => ms::decode(&d, 2, 256).map(drop),
"yamaha" => yamaha::decode(&d, 2).map(drop),
_ => swf::decode(&d, 2).map(drop),
};
}
}
// the impossible layouts
assert!(ima::decode(&[0; 10], 2, 10).is_err());
assert!(ima::decode(&[0; 8], 9, 8).is_err());
assert!(ms::decode(&[0; 8], 3, 8).is_err());
assert!(ima::encode(&[0; 3], 2, 256).is_err());
assert!(ima::encode_block(&[0; 3], 1, 256).is_err());
assert!(ms::encode_block(&[0; 3], 1, 256).is_err());
// a block whose step index or predictor is out of range
let mut bad = ima::encode_block(&vec![0; 505], 1, 256).unwrap();
bad[2] = 200;
assert!(ima::decode_block(&bad, 1, &mut Vec::new()).is_err());
let mut bad = swf::encode(&[0; 10], 1, 4).unwrap();
bad[2] = 0xFF;
let _ = swf::decode(&bad, 1);
}
#[test]
fn huge_layouts_and_big_jumps_are_handled() {
// block sizes whose sample counts do not fit in a usize
assert_eq!(ima::samples_per_block(usize::MAX - 3, 1), None);
assert_eq!(ms::samples_per_block(usize::MAX, 1), None);
assert!(ima::encode(&[], 1, usize::MAX - 3).is_err());
assert!(ms::encode(&[], 1, usize::MAX).is_err());
// a Flash stream's header holds the step index in six bits: a jump from silence to full scale
// still decodes to what the encoder's own state says
for bits in [2u32, 3, 4, 5] {
let x = [0i16, 32767, -32768, 0, 0];
let y = swf::decode(&swf::encode(&x, 1, bits).unwrap(), 1).unwrap();
// the stream has no length: up to seven padding bits can read as one more code
assert!((x.len()..=x.len() + 3).contains(&y.len()), "{bits} bits: {} samples", y.len());
assert!(y[1] > 0 && y[2] < y[1], "{bits} bits: {y:?}");
}
// padding bits at the end of a stream are not a code: no incomplete stereo frame
for bits in [2u32, 3, 4, 5] {
let y = swf::decode(&swf::encode(&[0, 0, 5, -5, 9, 9], 2, bits).unwrap(), 2).unwrap();
assert_eq!(y.len() % 2, 0, "{bits} bits: {y:?}");
assert!((6..=8).contains(&y.len()), "{bits} bits: {} samples", y.len());
}
}
#[test]
fn partial_final_blocks_are_handled() {
let x = signal(1, 1000);
// IMA: 256-byte blocks hold 505 samples; 1000 samples is two blocks, the second padded
let enc = ima::encode(&x, 1, 256).unwrap();
assert_eq!(enc.len(), 2 * 256);
assert_eq!(ima::decode(&enc, 1, 256).unwrap().len(), 1010);
// a stream cut inside the last block decodes as far as it goes
let cut = ima::decode(&enc[..256 + 4 + 40], 1, 256).unwrap();
assert_eq!(cut.len(), 505 + 1 + 80);
let enc = ms::encode(&x, 1, 256).unwrap();
assert_eq!(ms::decode(&enc, 1, 256).unwrap().len(), 1000);
assert!(ima::encode(&[], 1, 256).unwrap().is_empty());
assert!(ms::encode(&[], 1, 256).unwrap().is_empty());
assert!(yamaha::encode(&[], 1).unwrap().is_empty());
assert_eq!(yamaha::decode(&yamaha::encode(&[5, 6, 7], 1).unwrap(), 1).unwrap().len(), 4);
}
// ---- the other rounding some ffmpeg versions use for IMA and Flash ADPCM
//
// The IMA recommended practices build the step difference from `step >> 3` and the shifted steps
// of the magnitude bits that are set; some decoders (including older ffmpeg releases) compute
// `((2 * magnitude + 1) * step) >> (bits - 1)` instead, which rounds differently by a few units
// and so drifts apart through the predictor. A stream decodes to ours or to this one.
fn alt_diff(mag: i32, step: i32, bits: u32) -> i32 {
((2 * mag + 1) * step) >> (bits - 1)
}
const INDEX_4: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8];
const INDEX_5: [i32; 16] = [-1, -1, -1, -1, -1, -1, -1, -1, 1, 2, 4, 6, 8, 10, 13, 16];
const STEPS: [i32; 89] = [
7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66, 73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190,
209, 230, 253, 279, 307, 337, 371, 408, 449, 494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272, 2499,
2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493, 10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350,
22385, 24623, 27086, 29794, 32767,
];
fn index_table(bits: u32) -> &'static [i32] {
match bits {
2 => &[-1, 2],
3 => &[-1, -1, 2, 4],
4 => &INDEX_4,
_ => &INDEX_5,
}
}
/// `ima::decode` with the other rounding.
fn alt_ima_decode(data: &[u8], channels: usize, block_align: usize) -> Vec<i16> {
let per = ima::samples_per_block(block_align, channels).expect("layout");
let mut out = Vec::new();
for block in data.chunks_exact(block_align) {
let mut pred = vec![0i32; channels];
let mut idx = vec![0i32; channels];
let base = out.len();
out.resize(base + per * channels, 0);
for ch in 0..channels {
pred[ch] = i32::from(i16::from_le_bytes([block[4 * ch], block[4 * ch + 1]]));
idx[ch] = i32::from(block[4 * ch + 2]);
out[base + ch] = pred[ch] as i16;
}
for (g, group) in block[4 * channels..].chunks_exact(4 * channels).enumerate() {
for (ch, bytes) in group.as_chunks::<4>().0.iter().enumerate() {
for (k, b) in bytes.iter().enumerate() {
for (half, nib) in [b & 0xF, b >> 4].into_iter().enumerate() {
let step = STEPS[idx[ch] as usize];
let d = alt_diff(i32::from(nib & 7), step, 4);
pred[ch] = (pred[ch] + if nib & 8 != 0 { -d } else { d }).clamp(-32768, 32767);
idx[ch] = (idx[ch] + INDEX_4[usize::from(nib & 7)]).clamp(0, 88);
out[base + (1 + g * 8 + k * 2 + half) * channels + ch] = pred[ch] as i16;
}
}
}
}
}
out
}
/// `swf::decode` with the other rounding (one stream).
fn alt_swf_decode(data: &[u8], channels: usize) -> Vec<i16> {
let mut bitpos = 0usize;
let mut get = |n: usize| -> Option<u32> {
let mut v = 0u32;
for _ in 0..n {
let byte = *data.get(bitpos / 8)?;
v = (v << 1) | u32::from((byte >> (7 - bitpos % 8)) & 1);
bitpos += 1;
}
Some(v)
};
let bits = get(2).expect("header") + 2;
let mut out = Vec::new();
loop {
let mut pred = Vec::new();
let mut idx = Vec::new();
for _ in 0..channels {
let (Some(p), Some(i)) = (get(16), get(6)) else { return out };
out.push(p as u16 as i16);
pred.push(i32::from(p as u16 as i16));
idx.push(i as i32);
}
for _ in 1..4096 {
for ch in 0..channels {
let Some(code) = get(bits as usize) else { return out };
let mag = (code & ((1 << (bits - 1)) - 1)) as i32;
let d = alt_diff(mag, STEPS[idx[ch] as usize], bits);
pred[ch] = (pred[ch] + if code >> (bits - 1) != 0 { -d } else { d }).clamp(-32768, 32767);
idx[ch] = (idx[ch] + index_table(bits)[mag as usize]).clamp(0, 88);
out.push(pred[ch] as i16);
}
}
}
}
/// Assert `theirs` is `ours` or `alt` over their common length (and say which).
fn same_as_either(what: &str, ours: &[i16], alt: &[i16], theirs: &[i16]) {
let n = ours.len().min(theirs.len());
let (a, b) = (max_diff(&ours[..n], &theirs[..n]), max_diff(&alt[..n.min(alt.len())], &theirs[..n.min(alt.len())]));
println!("{what}: largest difference from ours {a}, from the other rounding {b}");
assert!(a == 0 || b == 0, "{what}: ffmpeg's decode is neither ours ({a}) nor the other rounding ({b})");
}
/// A name, the WAV file around our stream, our decode of it and the other rounding's.
type Stream = (&'static str, Vec<u8>, Vec<i16>, Vec<i16>);
// ---- ffmpeg as the reference
fn ffmpeg(ff: &Path, args: &[&str]) {
let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg");
assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr));
}
fn s(p: &Path) -> String {
p.to_str().expect("path").to_string()
}
fn write_pcm(path: &Path, x: &[i16]) {
std::fs::write(path, x.iter().flat_map(|v| v.to_le_bytes()).collect::<Vec<u8>>()).expect("write");
}
fn read_pcm(path: &Path) -> Vec<i16> {
std::fs::read(path).expect("read").as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect()
}
/// The `fmt ` chunk's fields and the `data` chunk of a WAV file.
fn wav_parts(bytes: &[u8]) -> (u16, usize, usize, Vec<u8>) {
let mut at = 12;
let (mut tag, mut channels, mut align) = (0, 0, 0);
while at + 8 <= bytes.len() {
let id = &bytes[at..at + 4];
let len = u32::from_le_bytes([bytes[at + 4], bytes[at + 5], bytes[at + 6], bytes[at + 7]]) as usize;
let body = &bytes[at + 8..(at + 8 + len).min(bytes.len())];
if id == b"fmt " {
tag = u16::from_le_bytes([body[0], body[1]]);
channels = usize::from(u16::from_le_bytes([body[2], body[3]]));
align = usize::from(u16::from_le_bytes([body[12], body[13]]));
} else if id == b"data" {
return (tag, channels, align, body.to_vec());
}
at += 8 + len + (len & 1);
}
panic!("no data chunk");
}
/// A WAV file around `data`.
fn wav(tag: u16, channels: usize, align: usize, bits: u16, extra: &[u8], data: &[u8]) -> Vec<u8> {
let mut fmt = Vec::new();
fmt.extend(tag.to_le_bytes());
fmt.extend((channels as u16).to_le_bytes());
fmt.extend(RATE.to_le_bytes());
fmt.extend((RATE * align as u32 / 500).to_le_bytes());
fmt.extend((align as u16).to_le_bytes());
fmt.extend(bits.to_le_bytes());
if !extra.is_empty() || tag == 0x11 || tag == 2 {
fmt.extend((extra.len() as u16).to_le_bytes());
fmt.extend(extra);
}
let mut out = b"RIFF".to_vec();
out.extend((4 + 8 + fmt.len() as u32 + 8 + data.len() as u32).to_le_bytes());
out.extend(b"WAVEfmt ");
out.extend((fmt.len() as u32).to_le_bytes());
out.extend(fmt);
out.extend(b"data");
out.extend((data.len() as u32).to_le_bytes());
out.extend(data);
out
}
#[test]
fn we_decode_what_ffmpeg_encodes_to_the_samples_ffmpeg_decodes() {
let Some(ff) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("adpcm");
for channels in [1usize, 2] {
let x = signal(channels, 30_000);
let pcm = dir.join(format!("in{channels}.pcm"));
write_pcm(&pcm, &x);
let input = ["-f", "s16le", "-ar", "22050", "-ac", if channels == 1 { "1" } else { "2" }, "-i"];
for (name, codec, align) in [("ima", "adpcm_ima_wav", 512usize), ("ms", "adpcm_ms", 512), ("yamaha", "adpcm_yamaha", 0)] {
let file = dir.join(format!("{name}{channels}.wav"));
let mut args: Vec<String> = input.iter().map(|a| a.to_string()).collect();
args.extend([s(&pcm), "-c:a".into(), codec.into()]);
if align > 0 {
args.extend(["-block_size".into(), align.to_string()]);
}
args.push(s(&file));
ffmpeg(&ff, &args.iter().map(String::as_str).collect::<Vec<_>>());
let back = dir.join(format!("{name}{channels}.out.pcm"));
ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]);
let theirs = read_pcm(&back);
let (tag, ch, block, data) = wav_parts(&std::fs::read(&file).expect("read"));
assert_eq!(ch, channels);
let ours = match name {
"ima" => {
assert_eq!(tag, 0x11);
ima::decode(&data, ch, block).expect("decode")
}
"ms" => {
assert_eq!(tag, 2);
ms::decode(&data, ch, block).expect("decode")
}
_ => yamaha::decode(&data, ch).expect("decode"),
};
let n = ours.len().min(theirs.len());
assert!(n >= 29_000 * channels, "{name} {channels}ch: {} ours, {} theirs", ours.len(), theirs.len());
if name == "ima" {
same_as_either(&format!("{name} {channels}ch"), &ours, &alt_ima_decode(&data, ch, block), &theirs);
} else {
let d = max_diff(&ours[..n], &theirs[..n]);
println!("{name} {channels}ch: {n} samples, largest difference from ffmpeg's decode {d}");
assert_eq!(d, 0, "{name} {channels}ch");
}
// our encoder is as good as ffmpeg's on the same audio, to within 3 dB
let mine = match name {
"ima" => ima::decode(&ima::encode(&x, ch, block).expect("encode"), ch, block).expect("decode"),
"ms" => ms::decode(&ms::encode(&x, ch, block).expect("encode"), ch, block).expect("decode"),
_ => yamaha::decode(&yamaha::encode(&x, ch).expect("encode"), ch).expect("decode"),
};
let m = x.len().min(mine.len()).min(theirs.len());
let (a, b) = (snr(&x[..m], &mine[..m]), snr(&x[..m], &theirs[..m]));
println!("{name} {channels}ch: SNR {a:.1} dB ours, {b:.1} dB ffmpeg's");
assert!(a + 3.0 >= b, "{name} {channels}ch: our encoder {a:.1} dB against ffmpeg's {b:.1} dB");
}
}
}
#[test]
fn ffmpeg_decodes_what_we_encode_to_the_samples_we_decode() {
let Some(ff) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("adpcm");
for channels in [1usize, 2] {
let x = signal(channels, 12_000);
let coefs: Vec<u8> = ms::COEFFICIENTS.iter().flat_map(|&(a, b)| [a as i16, b as i16].into_iter().flat_map(i16::to_le_bytes)).collect();
let streams: Vec<Stream> = {
let e = ima::encode(&x, channels, 512).unwrap();
let per = ima::samples_per_block(512, channels).unwrap() as u16;
let d = ima::decode(&e, channels, 512).unwrap();
let d_alt = alt_ima_decode(&e, channels, 512);
let ima_wav = wav(0x11, channels, 512, 4, &per.to_le_bytes(), &e);
let e = ms::encode(&x, channels, 512).unwrap();
let per = ms::samples_per_block(512, channels).unwrap() as u16;
let d2 = ms::decode(&e, channels, 512).unwrap();
let mut extra = per.to_le_bytes().to_vec();
extra.extend(7u16.to_le_bytes());
extra.extend(&coefs);
let ms_wav = wav(2, channels, 512, 4, &extra, &e);
let e = yamaha::encode(&x, channels).unwrap();
let d3 = yamaha::decode(&e, channels).unwrap();
let y_wav = wav(0x20, channels, 512 * channels, 4, &[], &e);
vec![("ima", ima_wav, d, d_alt), ("ms", ms_wav, d2.clone(), d2), ("yamaha", y_wav, d3.clone(), d3)]
};
for (name, bytes, ours, alt) in streams {
let file = dir.join(format!("our_{name}{channels}.wav"));
std::fs::write(&file, bytes).expect("write");
let back = dir.join(format!("our_{name}{channels}.pcm"));
ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]);
let theirs = read_pcm(&back);
let n = ours.len().min(theirs.len());
assert!(n + 2048 >= ours.len(), "{name} {channels}ch: ffmpeg decoded {} of {}", theirs.len(), ours.len());
same_as_either(&format!("{name} {channels}ch, our stream"), &ours, &alt, &theirs);
}
}
}
/// The audio tags of an FLV file: each tag's body without its flags byte.
fn flv_audio(bytes: &[u8]) -> Vec<Vec<u8>> {
let mut at = 13;
let mut out = Vec::new();
while at + 11 <= bytes.len() {
let kind = bytes[at];
let len = (usize::from(bytes[at + 1]) << 16) | (usize::from(bytes[at + 2]) << 8) | usize::from(bytes[at + 3]);
let body = &bytes[at + 11..(at + 11 + len).min(bytes.len())];
if kind == 8 && body.len() > 1 {
assert_eq!(body[0] >> 4, 1, "SWF ADPCM tag");
out.push(body[1..].to_vec());
}
at += 11 + len + 4;
}
out
}
/// An FLV file of 44.1 kHz audio tags with these ADPCM bodies.
fn flv(stereo: bool, tags: &[Vec<u8>]) -> Vec<u8> {
let mut out = b"FLV\x01\x04\0\0\0\x09\0\0\0\0".to_vec();
let flags = (1u8 << 4) | (3 << 2) | (1 << 1) | u8::from(stereo);
for (i, t) in tags.iter().enumerate() {
let len = t.len() + 1;
let ts = (i * 4096 * 1000 / 44_100) as u32;
out.extend([
8,
(len >> 16) as u8,
(len >> 8) as u8,
len as u8,
(ts >> 16) as u8,
(ts >> 8) as u8,
ts as u8,
(ts >> 24) as u8,
0,
0,
0,
flags,
]);
out.extend(t);
out.extend((len as u32 + 11).to_be_bytes());
}
out
}
#[test]
fn flash_adpcm_matches_ffmpeg_in_both_directions() {
let Some(ff) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("adpcm");
for channels in [1usize, 2] {
let x = signal(channels, 4096 * 3);
let pcm = dir.join(format!("swf_in{channels}.pcm"));
write_pcm(&pcm, &x);
// ffmpeg encodes (it needs 44.1 kHz for FLV)
let file = dir.join(format!("swf{channels}.flv"));
ffmpeg(&ff, &["-f", "s16le", "-ar", "44100", "-ac", &channels.to_string(), "-i", &s(&pcm), "-c:a", "adpcm_swf", "-f", "flv", &s(&file)]);
let tags = flv_audio(&std::fs::read(&file).expect("read"));
assert!(tags.len() >= 3, "{} tags", tags.len());
let back = dir.join(format!("swf{channels}.out.pcm"));
ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]);
let theirs = read_pcm(&back);
let ours: Vec<i16> = tags.iter().flat_map(|t| swf::decode(t, channels).expect("decode")).collect();
assert_eq!(ours.len(), 4096 * 3 * channels);
assert_eq!(theirs.len(), 4096 * 3 * channels);
let alt: Vec<i16> = tags.iter().flat_map(|t| alt_swf_decode(t, channels)).collect();
same_as_either(&format!("swf {channels}ch"), &ours, &alt, &theirs);
// ffmpeg decodes ours, one 4096-sample stream per tag
for bits in [2u32, 3, 4, 5] {
let tags: Vec<Vec<u8>> = x.chunks(4096 * channels).map(|c| swf::encode(c, channels, bits).expect("encode")).collect();
let ours: Vec<i16> = tags.iter().flat_map(|t| swf::decode(t, channels).expect("decode")).collect();
let file = dir.join(format!("our_swf{channels}_{bits}.flv"));
std::fs::write(&file, flv(channels == 2, &tags)).expect("write");
let back = dir.join(format!("our_swf{channels}_{bits}.pcm"));
ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]);
let theirs = read_pcm(&back);
assert_eq!(ours.len(), 4096 * 3 * channels);
assert_eq!(theirs.len(), 4096 * 3 * channels);
let alt: Vec<i16> = tags.iter().flat_map(|t| alt_swf_decode(t, channels)).collect();
same_as_either(&format!("swf {channels}ch {bits} bits, our stream"), &ours, &alt, &theirs);
}
}
}
+280
View File
@@ -0,0 +1,280 @@
//! 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::AudioError;
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<u8>, Vec<i16>) {
let n = d.block_samples() * d.channels();
if d.bits() == 8 {
let bytes: Vec<u8> = (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<i16> = (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<u8>, Vec<i16>) {
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<i16> {
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<i16> = 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]);
// a flags 1 frame of several blocks: each block starts from its own first samples
let (first, first_samples) = dpcm_pack(&[100, -100, 300, -50, 200, 0, 1000, 500], 2);
let (second, second_samples) = dpcm_pack(&[-7000, 7000, -6000, 6500, -6100, 6400, -3000, 3000], 2);
assert_eq!(d.decode(1, &[first, second, vec![1, 2, 3]].concat()).unwrap(), [first_samples, second_samples].concat());
// 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]);
// a flags 1 frame of more than one block plays every whole block
assert_eq!(
d.decode(1, &[0x80, 0x81, 0x82, 0x83, 0x90, 0x91, 0x92, 0x93, 0xA0]).unwrap(),
[0, 0x100, 0x200, 0x300, 0x1000, 0x1100, 0x1200, 0x1300]
);
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")));
assert_eq!(d.decode(4, &[]), Err(Error::Unsupported("unknown sound frame flags")));
// in the file API's error: unsupported stays unsupported, the rest is malformed input
assert!(matches!(AudioError::from(Error::Unsupported("x")), AudioError::Unsupported(_)));
assert!(matches!(AudioError::from(Error::Invalid("x")), AudioError::Malformed(_)));
let good = build(&spec(20, 0), &[]);
let with = |patch: &dyn Fn(&mut Vec<u8>)| {
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[804..806].fill(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<i16> = 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");
}
+48 -1
View File
@@ -430,6 +430,7 @@ pub struct Texture<'a> {
encoding: Encoding,
/// Where the top level's pixel data starts.
start: usize,
levels: u32,
}
impl<'a> Texture<'a> {
@@ -456,7 +457,8 @@ impl<'a> Texture<'a> {
if width == 0 || height == 0 {
return Err(bad("texture dimensions must be nonzero"));
}
Ok(Texture { bytes: b, flags, width, height, encoding, start })
let levels = le32(b, 28)?.max(1).min(mip_levels(width, height));
Ok(Texture { bytes: b, flags, width, height, encoding, start, levels })
}
pub fn width(&self) -> u32 {
@@ -472,6 +474,51 @@ impl<'a> Texture<'a> {
self.encoding.layout()
}
/// Number of declared mip levels, capped by the chain down to one pixel.
pub fn levels(&self) -> u32 {
self.levels
}
/// The encoding named by the header, including unsigned BC4 and BC5.
pub fn compression(&self) -> DdsCompression {
match self.encoding {
Encoding::Masks { .. } | Encoding::Unorm16 { .. } => DdsCompression::None,
Encoding::Bc1 => DdsCompression::Bc1,
Encoding::Bc2 => DdsCompression::Bc2,
Encoding::Bc3 => DdsCompression::Bc3,
Encoding::Bc4 => DdsCompression::Bc4,
Encoding::Bc5 => DdsCompression::Bc5,
}
}
/// A borrowed view of one mip level, without allocating or decoding pixels.
/// Lower levels are tightly packed; only the top level uses the header's row pitch.
pub fn mip_level(&self, index: u32) -> Result<Texture<'a>, DdsError> {
if index >= self.levels {
return Err(bad("mip level index is outside the declared chain"));
}
let (mut width, mut height, mut start) = (self.width, self.height, self.start);
for i in 0..index {
let pitch = if i == 0 && self.flags & DDSD_PITCH != 0 { Some(le32(self.bytes, 20)?) } else { None };
let (_, size) = self.encoding.level_layout(width, height, pitch)?;
start = start.checked_add(size).ok_or_else(|| bad("mip offset overflow"))?;
if start > self.bytes.len() {
return Err(bad("truncated mip data"));
}
width = (width / 2).max(1);
height = (height / 2).max(1);
}
Ok(Texture {
bytes: self.bytes,
flags: if index == 0 { self.flags } else { self.flags & !DDSD_PITCH },
width,
height,
encoding: self.encoding,
start,
levels: self.levels - index,
})
}
/// The top mip level's pixels in [`Texture::layout`], bounded by [`DEFAULT_MAX_DECODE_BYTES`].
pub fn decode(&self) -> Result<Vec<u8>, DdsError> {
self.decode_with_limit(DEFAULT_MAX_DECODE_BYTES)
+50
View File
@@ -44,3 +44,53 @@ fn default_budget_rejects_oversized_header_before_payload_or_allocation() {
assert!(matches!(texture.decode(), Err(craft_dds::DdsError::LimitExceeded { limit: craft_dds::DEFAULT_MAX_DECODE_BYTES, .. })));
assert!(matches!(texture.decode_with_limit(u64::MAX), Err(craft_dds::DdsError::Malformed(_))));
}
#[test]
fn mip_views_reuse_shared_decoders_and_keep_their_bounds() {
for (compression, layout, channels) in [
(DdsCompression::None, Layout::Gray, 1),
(DdsCompression::Bc1, Layout::Rgba, 4),
(DdsCompression::Bc4, Layout::Gray, 1),
(DdsCompression::Bc5, Layout::Rgb, 3),
] {
let bytes = encode(4, 4, layout, &vec![71; 16 * channels], DdsOptions { compression, mipmaps: true }).unwrap();
let texture = Texture::parse(&bytes).unwrap();
assert_eq!(texture.levels(), 3);
assert_eq!(texture.compression(), compression);
assert!(texture.mip_level(3).is_err());
assert!(texture.mip_level(u32::MAX).is_err());
for (index, side) in [(0, 4), (1, 2), (2, 1)] {
let level = texture.mip_level(index).unwrap();
assert_eq!((level.width(), level.height()), (side, side));
let len = side as usize * side as usize * channels;
assert!(matches!(level.decode_with_limit((len - 1) as u64), Err(craft_dds::DdsError::LimitExceeded { .. })));
assert_eq!(level.decode_with_limit(len as u64).unwrap().len(), len);
}
let nested = texture.mip_level(1).unwrap().mip_level(1).unwrap();
assert_eq!(nested.decode().unwrap(), texture.mip_level(2).unwrap().decode().unwrap());
}
}
#[test]
fn sixteen_bit_mip_views_preserve_samples_and_stored_offsets() {
for (layout, channels) in [(Layout::Gray, 1), (Layout::GrayA, 2), (Layout::Rgba, 4)] {
let pixels: Vec<u16> = (0..16).flat_map(|p| (0..channels).map(move |c| (p * 400 + c * 31 + 7) as u16)).collect();
let bytes = craft_dds::encode16(4, 4, layout, &pixels, DdsOptions { compression: DdsCompression::None, mipmaps: true }).unwrap();
let texture = Texture::parse(&bytes).unwrap();
assert_eq!(texture.compression(), DdsCompression::None);
assert_eq!(texture.levels(), 3);
assert_eq!(texture.decode16().unwrap(), pixels);
for (index, averages) in [(1, vec![1000, 1800, 4200, 5000]), (2, vec![3000])] {
let expected: Vec<u16> = averages.iter().flat_map(|p| (0..channels).map(move |c| (p + c * 31 + 7) as u16)).collect();
let level = texture.mip_level(index).unwrap();
let budget = (expected.len() * 2) as u64;
assert!(matches!(level.decode16_with_limit(budget - 1), Err(craft_dds::DdsError::LimitExceeded { .. })));
assert_eq!(level.decode16_with_limit(budget).unwrap(), expected);
let rounded: Vec<u8> = expected.iter().map(|&v| ((u32::from(v) + 128) / 257) as u8).collect();
assert_eq!(level.decode().unwrap(), rounded);
}
assert_eq!(texture.mip_level(1).unwrap().mip_level(1).unwrap().decode16().unwrap(), texture.mip_level(2).unwrap().decode16().unwrap());
let truncated = Texture::parse(&bytes[..bytes.len() - 1]).unwrap();
assert!(truncated.mip_level(2).unwrap().decode16().is_err());
}
}
+52 -11
View File
@@ -211,6 +211,26 @@ fn style_def(w: &mut Writer, id: &str, name: &str) {
/// opened file defined (`defs`), written back as they were read. A generated style is named
/// `"{name_prefix} {label}"` (`"Acme Medium 2 Accent 1"`).
pub fn table_styles_xml(used: &[String], defs: &[crate::table::TableStyleDef], name_prefix: &str) -> Vec<u8> {
table_styles_xml_with(used, defs.iter().map(|d| (d.id.as_str(), d.raw.as_str())), name_prefix, |raw| {
crate::xmlx::parse(raw.as_bytes()).is_ok_and(|x| x.is(Local("tblStyle")))
})
}
/// Write table style definitions without copying a caller's model or raw XML.
///
/// `defs` yields `(id, raw_xml)` in file order and must replay the same sequence when cloned.
/// `valid` retains the caller's bounded XML-admission policy; accepted fragments are emitted
/// verbatim. It must reject fragments the caller cannot safely preserve. The ordinary
/// [`table_styles_xml`] API continues to use this crate's bounded parser.
///
/// Input/output budgets remain caller-owned. Duplicate selection, case handling, and validation
/// order match [`table_styles_xml`]; invalid first definitions do not fall through to later ones.
pub fn table_styles_xml_with<'a>(
used: &[String],
defs: impl Iterator<Item = (&'a str, &'a str)> + Clone,
name_prefix: &str,
mut valid: impl FnMut(&str) -> bool,
) -> Vec<u8> {
let mut w = Writer::document();
w.tag("a:tblStyleLst").attr("xmlns:a", NS_A).attr("def", "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}").open();
let names = crate::table::table_styles();
@@ -218,19 +238,19 @@ pub fn table_styles_xml(used: &[String], defs: &[crate::table::TableStyleDef], n
// definitions by lower-case id (the first wins).
let mut done: std::collections::HashSet<&str> = std::collections::HashSet::new();
let mut done_lower: std::collections::HashSet<String> = std::collections::HashSet::new();
let mut def_of: std::collections::HashMap<String, &crate::table::TableStyleDef> = std::collections::HashMap::new();
for d in defs {
def_of.entry(d.id.to_ascii_lowercase()).or_insert(d);
let mut def_of: std::collections::HashMap<String, &'a str> = std::collections::HashMap::new();
for (id, raw) in defs.clone() {
def_of.entry(id.to_ascii_lowercase()).or_insert(raw);
}
for s in used {
if !done.insert(s.as_str()) {
continue;
}
done_lower.insert(s.to_ascii_lowercase());
if let Some(d) = def_of.get(&s.to_ascii_lowercase())
&& crate::xmlx::parse(d.raw.as_bytes()).is_ok_and(|x| x.is(Local("tblStyle")))
if let Some(raw) = def_of.get(&s.to_ascii_lowercase())
&& valid(raw)
{
w.raw(&d.raw);
w.raw(raw);
continue;
}
let (_, define) = guid_for_style(s);
@@ -241,13 +261,13 @@ pub fn table_styles_xml(used: &[String], defs: &[crate::table::TableStyleDef], n
style_def(&mut w, s, &name);
}
// Styles the file defined but no table uses still belong to the deck.
for d in defs {
if done_lower.contains(&d.id.to_ascii_lowercase()) {
for (id, raw) in defs {
if done_lower.contains(&id.to_ascii_lowercase()) {
continue;
}
if crate::xmlx::parse(d.raw.as_bytes()).is_ok_and(|x| x.is(Local("tblStyle"))) {
done_lower.insert(d.id.to_ascii_lowercase());
w.raw(&d.raw);
if valid(raw) {
done_lower.insert(id.to_ascii_lowercase());
w.raw(raw);
}
}
w.close();
@@ -258,6 +278,27 @@ pub fn table_styles_xml(used: &[String], defs: &[crate::table::TableStyleDef], n
mod tests {
use super::*;
#[test]
fn borrowed_writer_preserves_model_api_and_validation_order() {
let defs = [
crate::table::TableStyleDef { id: "custom".into(), raw: "<tblStyle/>".into(), ..Default::default() },
crate::table::TableStyleDef { id: "CUSTOM".into(), raw: "<tblStyle duplicate=\"1\"/>".into(), ..Default::default() },
];
let used = vec!["custom".into(), "custom".into(), "light1-accent1".into()];
let borrowed = || defs.iter().map(|d| (d.id.as_str(), d.raw.as_str()));
assert_eq!(
table_styles_xml(&used, &defs, "App"),
table_styles_xml_with(&used, borrowed(), "App", |raw| { crate::xmlx::parse(raw.as_bytes()).is_ok_and(|x| x.is(Local("tblStyle"))) })
);
let mut checked = Vec::new();
let bytes = table_styles_xml_with(&used, borrowed(), "App", |raw| {
checked.push(raw.to_owned());
false
});
assert_eq!(checked, ["<tblStyle/>"]);
assert!(!String::from_utf8(bytes).unwrap().contains("duplicate="));
}
#[test]
fn style_parts_follow_schema_order() {
const ORDER: [&str; 14] = [
+13
View File
@@ -0,0 +1,13 @@
[package]
name = "craft-har"
description = "Typed HTTP Archive capture reader with explicit input admission"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
serde_json = { workspace = true }
thiserror = { workspace = true }
+230
View File
@@ -0,0 +1,230 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
//! HTTP Archive (HAR 1.2) captures, read into typed records. No redaction happens here; callers
//! decide what to keep. Capture headers and bodies can contain secrets: redact before display or sharing.
//! `parse` preserves compatibility and parses the whole JSON before limiting returned entries.
//! Use `parse_bounded` to cap admitted bytes; this is not a precise allocator or output-byte limit.
use serde_json::Value;
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum HarError {
#[error("not valid JSON: {0}")]
BadJson(String),
#[error("not a HAR capture: {0}")]
NotHar(&'static str),
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Har {
pub version: Option<String>,
pub creator: Option<String>,
pub pages: usize,
pub entries: Vec<HarEntry>,
pub declared_entries: usize,
pub truncated: bool,
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct HarEntry {
/// 0-based position in `log.entries`.
pub ordinal: usize,
pub started: Option<String>,
pub time_ms: Option<f64>,
pub resource_type: Option<String>,
pub server_ip: Option<String>,
pub request: HarRequest,
pub response: HarResponse,
/// blocked, dns, connect, send, wait, receive, ssl (negative values mean "not applicable").
pub timings: Vec<(String, f64)>,
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct HarRequest {
pub method: String,
pub url: String,
pub http_version: Option<String>,
pub headers: Vec<(String, String)>,
pub cookie_names: Vec<String>,
pub post: Option<HarBody>,
pub body_size: Option<i64>,
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct HarBody {
pub mime: Option<String>,
pub text: Option<String>,
/// Form parameter names (values are deliberately not surfaced by this type's users).
pub params: Vec<(String, Option<String>)>,
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct HarResponse {
pub status: i64,
pub status_text: Option<String>,
pub http_version: Option<String>,
pub headers: Vec<(String, String)>,
pub cookie_names: Vec<String>,
pub redirect_url: Option<String>,
pub content_size: Option<i64>,
pub mime: Option<String>,
pub text: Option<String>,
/// `base64` when `text` is base64-encoded.
pub encoding: Option<String>,
pub body_size: Option<i64>,
}
fn s(v: &Value, k: &str) -> Option<String> {
v.get(k).and_then(Value::as_str).map(String::from)
}
fn pairs(v: Option<&Value>) -> Vec<(String, String)> {
v.and_then(Value::as_array)
.map(|a| {
a.iter()
.filter_map(|h| Some((h.get("name")?.as_str()?.to_string(), h.get("value").and_then(Value::as_str).unwrap_or_default().to_string())))
.collect()
})
.unwrap_or_default()
}
fn names(v: Option<&Value>) -> Vec<String> {
v.and_then(Value::as_array).map(|a| a.iter().filter_map(|c| c.get("name")?.as_str().map(String::from)).collect()).unwrap_or_default()
}
/// Parse a HAR document, keeping at most `max_entries` entries.
pub fn parse(json: &[u8], max_entries: usize) -> Result<Har, HarError> {
let json = json.strip_prefix(&[0xef, 0xbb, 0xbf]).unwrap_or(json);
let v: Value = serde_json::from_slice(json).map_err(|e| HarError::BadJson(e.to_string()))?;
let log = v.get("log").ok_or(HarError::NotHar("no \"log\" object"))?;
let entries = log.get("entries").and_then(Value::as_array).ok_or(HarError::NotHar("no \"log.entries\" array"))?;
let mut har = Har {
version: s(log, "version"),
creator: log
.get("creator")
.map(|c| format!("{} {}", s(c, "name").unwrap_or_default(), s(c, "version").unwrap_or_default()).trim().to_string()),
pages: log.get("pages").and_then(Value::as_array).map_or(0, Vec::len),
declared_entries: entries.len(),
..Default::default()
};
for (i, e) in entries.iter().enumerate() {
if har.entries.len() >= max_entries {
har.truncated = true;
break;
}
let req = e.get("request").unwrap_or(&Value::Null);
let res = e.get("response").unwrap_or(&Value::Null);
let content = res.get("content").unwrap_or(&Value::Null);
let post = req.get("postData").filter(|p| p.is_object()).map(|p| HarBody {
mime: s(p, "mimeType"),
text: s(p, "text"),
params: p
.get("params")
.and_then(Value::as_array)
.map(|a| a.iter().filter_map(|x| Some((x.get("name")?.as_str()?.to_string(), s(x, "value")))).collect())
.unwrap_or_default(),
});
let timings = e
.get("timings")
.and_then(Value::as_object)
.map(|m| m.iter().filter_map(|(k, v)| Some((k.clone(), v.as_f64()?))).collect())
.unwrap_or_default();
har.entries.push(HarEntry {
ordinal: i,
started: s(e, "startedDateTime"),
time_ms: e.get("time").and_then(Value::as_f64),
resource_type: s(e, "_resourceType"),
server_ip: s(e, "serverIPAddress"),
request: HarRequest {
method: s(req, "method").unwrap_or_default(),
url: s(req, "url").unwrap_or_default(),
http_version: s(req, "httpVersion"),
headers: pairs(req.get("headers")),
cookie_names: names(req.get("cookies")),
post,
body_size: req.get("bodySize").and_then(Value::as_i64),
},
response: HarResponse {
status: res.get("status").and_then(Value::as_i64).unwrap_or(0),
status_text: s(res, "statusText"),
http_version: s(res, "httpVersion"),
headers: pairs(res.get("headers")),
cookie_names: names(res.get("cookies")),
redirect_url: s(res, "redirectURL").filter(|u| !u.is_empty()),
content_size: content.get("size").and_then(Value::as_i64),
mime: s(content, "mimeType"),
text: s(content, "text"),
encoding: s(content, "encoding"),
body_size: res.get("bodySize").and_then(Value::as_i64),
},
timings,
});
}
Ok(har)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn reads_a_har_with_a_utf8_bom() {
let capture = br#"{"log":{"entries":[]}}"#;
let mut encoded = vec![0xef, 0xbb, 0xbf];
encoded.extend_from_slice(capture);
assert_eq!(parse(&encoded, 1).unwrap(), parse(capture, 1).unwrap());
assert!(parse(&[0xef, 0xbb], 1).is_err());
}
#[test]
fn parses_minimal_har() {
let j = br#"{"log":{"version":"1.2","creator":{"name":"x","version":"1"},"entries":[
{"startedDateTime":"2026-01-01T00:00:00Z","time":12.5,
"request":{"method":"POST","url":"https://api.example.test/v1/items/42","headers":[{"name":"Cookie","value":"s=1"}],"cookies":[{"name":"s","value":"1"}],
"postData":{"mimeType":"application/json","text":"{\"a\":1}"}},
"response":{"status":201,"headers":[],"content":{"size":2,"mimeType":"application/json","text":"{}"}},
"timings":{"wait":10,"receive":2.5}}]}}"#;
let h = parse(j, 10).unwrap();
assert_eq!(h.entries.len(), 1);
let e = &h.entries[0];
assert_eq!(e.request.method, "POST");
assert_eq!(e.response.status, 201);
assert_eq!(e.request.cookie_names, vec!["s"]);
assert_eq!(e.timings.len(), 2);
}
#[test]
fn rejects_non_har() {
assert!(parse(b"{}", 1).is_err());
assert!(parse(b"nope", 1).is_err());
assert!(parse(br#"{"log":{"entries":[1,null,"x"]}}"#, 10).is_ok());
}
}
/// Reject oversized input before parsing its JSON. `max_entries` only limits returned records.
pub fn parse_bounded(json: &[u8], max_entries: usize, max_bytes: usize) -> Result<Har, HarError> {
if json.len() > max_bytes {
return Err(HarError::NotHar("input byte limit exceeded"));
}
parse(json, max_entries)
}
#[cfg(test)]
mod admission_tests {
use super::*;
#[test]
fn input_admission_and_entry_limits_are_independent() {
let input = br#"{"log":{"entries":[null,{}]}}"#;
assert_eq!(parse_bounded(input, 2, input.len()).unwrap(), parse(input, 2).unwrap());
assert_eq!(parse_bounded(b"bad JSON", 1, 0), Err(HarError::NotHar("input byte limit exceeded")));
let empty = parse_bounded(input, 0, input.len()).unwrap();
assert!(empty.truncated && empty.entries.is_empty());
assert_eq!(empty.declared_entries, 2);
let one = parse_bounded(input, 1, input.len()).unwrap();
assert!(one.truncated);
assert_eq!(one.entries.len(), 1);
assert_eq!(one.entries[0].ordinal, 0);
assert!(!parse_bounded(input, 2, input.len()).unwrap().truncated);
}
}
+2
View File
@@ -14,11 +14,13 @@
//! [`hostile::hammer`] runs a parser over every truncation and mutations of a valid input and fails
//! on a panic or a case that does not finish in time; `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times
//! the iterations. It and [`with_deadline`] call `craft_testkit`.
//! [`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;
+343
View File
@@ -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
//! (<https://wiki.multimedia.cx/index.php/VMD>); 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<Audio>,
}
impl Spec {
/// A silent file of `width` x `height` with a grey ramp palette.
pub fn new(width: u16, height: u16) -> Spec {
let mut palette = [0; 768];
for (i, p) in palette.iter_mut().enumerate() {
*p = (i / 3 / 4) as u8;
}
Spec { width, height, left: 0, top: 0, palette, unpack: 1 << 20, codec_version: 0, audio: None }
}
}
/// One frame of a block: its 16-byte record and its data.
#[derive(Clone, Debug)]
pub struct Frame {
/// Frame type: 1 audio, 2 video.
pub kind: u8,
/// Bytes 6 to 15 of the frame record.
pub tail: [u8; 10],
/// The frame data.
pub data: Vec<u8>,
}
impl Frame {
/// A video frame updating `rect` (left, top, right, bottom; inclusive).
pub fn video(rect: [u16; 4], new_palette: bool, data: Vec<u8>) -> Frame {
let mut tail = [0; 10];
for (i, v) in rect.iter().enumerate() {
tail[i * 2..i * 2 + 2].copy_from_slice(&v.to_le_bytes());
}
tail[9] = if new_palette { 2 } else { 0 };
Frame { kind: 2, tail, data }
}
/// An audio frame with the given block flags (1 sound, 2 mask and blocks, 3 silence).
pub fn audio(flags: u8, data: Vec<u8>) -> Frame {
let mut tail = [0; 10];
tail[0] = flags;
Frame { kind: 1, tail, data }
}
}
/// A whole file: header, frame data, then the table of contents. Every block must hold the same
/// number of frames.
#[allow(clippy::panic)]
pub fn build(spec: &Spec, blocks: &[Vec<Frame>]) -> Vec<u8> {
let per_block = blocks.first().map_or(0, Vec::len);
assert!(blocks.iter().all(|b| b.len() == per_block), "every block holds the same number of frames");
let mut data = Vec::new();
let mut offsets = Vec::new();
let mut records = Vec::new();
for block in blocks {
offsets.push((HEADER_LEN + data.len()) as u32);
for f in block {
records.push(f.kind);
records.push(0);
records.extend_from_slice(&(f.data.len() as u32).to_le_bytes());
records.extend_from_slice(&f.tail);
data.extend_from_slice(&f.data);
}
}
let mut h = vec![0u8; HEADER_LEN];
let put16 = |h: &mut [u8], at: usize, v: u16| h[at..at + 2].copy_from_slice(&v.to_le_bytes());
let put32 = |h: &mut [u8], at: usize, v: u32| h[at..at + 4].copy_from_slice(&v.to_le_bytes());
put16(&mut h, 0, (HEADER_LEN - 2) as u16);
put16(&mut h, 4, spec.codec_version);
put16(&mut h, 6, blocks.len() as u16);
put16(&mut h, 8, spec.top);
put16(&mut h, 10, spec.left);
put16(&mut h, 12, spec.width);
put16(&mut h, 14, spec.height);
put16(&mut h, 16, if spec.audio.is_some() { 0x1000 } else { 0 });
put16(&mut h, 18, per_block as u16);
put32(&mut h, 20, HEADER_LEN as u32);
h[28..796].copy_from_slice(&spec.palette);
put32(&mut h, 800, spec.unpack);
if let Some(a) = spec.audio {
put16(&mut h, 804, a.sample_rate);
put16(&mut h, 806, a.frame_length as u16);
put16(&mut h, 808, a.buffers);
put16(&mut h, 810, a.flags);
}
put32(&mut h, 812, (HEADER_LEN + data.len()) as u32);
h.extend_from_slice(&data);
for o in offsets {
h.extend_from_slice(&[0, 0]);
h.extend_from_slice(&o.to_le_bytes());
}
h.extend_from_slice(&records);
h
}
/// The 770 bytes that open a video frame carrying a new palette.
pub fn palette_chunk(palette: &[u8; 768]) -> Vec<u8> {
let mut v = vec![0, 255];
v.extend_from_slice(palette);
v
}
/// LZ-pack `data` (what follows the coding method byte): the length, the optional marker that
/// selects long chains, then tagged literals and chains. `rng` picks between a literal and a
/// chain where both are possible, so both paths get exercised.
pub fn lz_pack(data: &[u8], marker: bool, rng: &mut Rng) -> Vec<u8> {
let mut out = (data.len() as u32).to_le_bytes().to_vec();
let mut queue = [0x20u8; 4096];
let mut qpos = if marker {
out.extend_from_slice(&[0x34, 0x12, 0x78, 0x56]);
0x111usize
} else {
0xFEE
};
let max_len = if marker { 18 + 255 } else { 18 };
let mut pos = 0;
while pos < data.len() {
// a tag of 0xFF with more than 8 bytes left means 8 raw bytes
let tag_at = out.len();
out.push(0);
let mut tag = 0u8;
for bit in 0..8 {
if pos >= data.len() {
break;
}
let left = data.len() - pos;
// the longest chain in the queue; a chain may run into the bytes it is writing
let (mut best_len, mut best_off) = (0usize, 0usize);
for off in 0..4096usize {
let mut n = 0;
while n < max_len.min(left) {
let behind = (off + n).wrapping_sub(qpos) & 0xFFF;
let have = if behind < n { data[pos + behind] } else { queue[(off + n) & 0xFFF] };
if have != data[pos + n] {
break;
}
n += 1;
}
if n > best_len {
(best_len, best_off) = (n, off);
}
}
if best_len >= 3 && rng.below(4) != 0 {
// sometimes a shorter chain than the longest
let len = if rng.below(3) == 0 { 3 + rng.below(best_len - 2) } else { best_len };
let nibble = if marker && len >= 18 { 15 } else { len - 3 };
out.push(best_off as u8);
out.push(((best_off >> 4) & 0xF0) as u8 | nibble as u8);
if marker && len >= 18 {
out.push((len - 18) as u8);
}
for i in 0..len {
queue[(qpos + i) & 0xFFF] = data[pos + i];
}
qpos = (qpos + len) & 0xFFF;
pos += len;
} else {
tag |= 1 << bit;
out.push(data[pos]);
queue[qpos] = data[pos];
qpos = (qpos + 1) & 0xFFF;
pos += 1;
}
}
out[tag_at] = tag;
}
out
}
/// The body of a method 1 (`rle` false) or method 3 frame that turns the `rect` of `prev` into
/// that of `cur`; both are whole pictures of `stride` bytes a row. Unchanged runs are skipped.
/// With `rle`, changed runs are run-length packed when `rng` says so (always when they begin
/// with 0xFF, which a plain run cannot).
///
/// With `rle`, no changed run is a single pixel: the description and ffmpeg disagree on how a
/// run-length run of one pixel ends, and the game files seen do not have one. A lone changed
/// pixel takes its neighbour along, so the rectangle must be at least two pixels wide.
pub fn delta_lines(prev: &[u8], cur: &[u8], stride: usize, rect: [u16; 4], rle: bool, rng: &mut Rng) -> Vec<u8> {
let [left, top, right, bottom] = rect.map(usize::from);
let width = right - left + 1;
let mut out = Vec::new();
for y in top..=bottom {
let row = y * stride + left;
let mut changed: Vec<bool> = (0..width).map(|x| prev[row + x] != cur[row + x]).collect();
if rle {
for x in 0..width {
let alone = changed[x] && (x == 0 || !changed[x - 1]) && (x + 1 == width || !changed[x + 1]);
if alone && x + 1 < width {
changed[x + 1] = true;
} else if alone && x > 0 {
changed[x - 1] = true;
}
}
}
let mut x = 0;
while x < width {
let mut end = x;
while end < width && changed[end] == changed[x] {
end += 1;
}
let mut n = (end - x).min(128);
if rle && changed[x] && end - x - n == 1 {
n -= 1;
}
if !changed[x] {
out.push((n - 1) as u8);
} else {
let run = &cur[row + x..row + x + n];
out.push(0x80 | (n - 1) as u8);
if rle && (run[0] == 0xFF || rng.below(2) == 0) {
out.push(0xFF);
rle_pack(run, &mut out);
} else {
out.extend_from_slice(run);
}
}
x += n;
}
}
out
}
fn rle_pack(run: &[u8], out: &mut Vec<u8>) {
let mut run = run;
if run.len() % 2 == 1 {
out.push(run[0]);
run = &run[1..];
}
let pairs = run.as_chunks::<2>().0;
let mut i = 0;
while i < pairs.len() {
let mut n = 1;
while i + n < pairs.len() && pairs[i + n] == pairs[i] && n < 127 {
n += 1;
}
if n > 1 {
out.push(n as u8);
out.extend_from_slice(&pairs[i]);
i += n;
continue;
}
// pairs up to the next repeat go out as they are
let start = i;
while i < pairs.len() && i - start < 127 && !(i + 1 < pairs.len() && pairs[i + 1] == pairs[i]) {
i += 1;
}
out.push(0x80 | (i - start) as u8);
out.extend(pairs[start..i].iter().flatten());
}
}
/// The step table of the 16-bit sound coding.
pub const DPCM_STEPS: [u16; 128] = {
let mut t = [0u16; 128];
let mut i = 1;
while i < 128 {
t[i] = match i {
1 => 8,
2..=33 => 16 * (i as u16 - 1),
34..=97 => 512 + 8 * (i as u16 - 33),
98..=113 => 1024 + 64 * (i as u16 - 97),
114..=121 => 2048 + 256 * (i as u16 - 113),
122..=125 => 4096 + 1024 * (i as u16 - 121),
126 => 12288,
_ => 16384,
};
i += 1;
}
t
};
/// Pack one block of 16-bit sound: `samples` are interleaved across `channels`. Returns the
/// block (each channel's first sample as it is, then one code a sample) and the samples a
/// decoder gets back from it.
pub fn dpcm_pack(samples: &[i16], channels: usize) -> (Vec<u8>, Vec<i16>) {
let mut out = Vec::new();
let mut decoded = Vec::new();
let mut pred = [0i32; 2];
for (i, &s) in samples.iter().enumerate() {
let ch = i % channels;
if i < channels {
out.extend_from_slice(&s.to_le_bytes());
pred[ch] = i32::from(s);
} else {
let diff = i32::from(s) - pred[ch];
let mag = diff.unsigned_abs();
let mut code = 0;
for (c, &step) in DPCM_STEPS.iter().enumerate() {
if u32::from(step).abs_diff(mag) < u32::from(DPCM_STEPS[code]).abs_diff(mag) {
code = c;
}
}
let step = i32::from(DPCM_STEPS[code]);
// stay inside 16 bits, so that a decoder's handling of overflow does not matter
let (next, byte) = if diff < 0 { (pred[ch] - step, 0x80 | code as u8) } else { (pred[ch] + step, code as u8) };
let (next, byte) = if (-32768..=32767).contains(&next) { (next, byte) } else { (pred[ch], 0) };
pred[ch] = next;
out.push(byte);
}
decoded.push(pred[ch] as i16);
}
(out, decoded)
}
+6
View File
@@ -24,6 +24,8 @@ avi = []
mxf = ["dep:chrono"]
# MPEG-2 Systems demuxer: transport streams and program streams (`craft_media::mpegts`).
mpegts = []
# Sierra VMD (Video and Music Data) demuxer (`craft_media::vmd`).
vmd = []
# Ogg demuxer (Ogg Opus and Vorbis mapping, `craft_media::ogg`).
ogg = []
# Serialize and Deserialize for `Container`, `CodecId`, `CodecParams` and `PcmFormat`.
@@ -79,6 +81,10 @@ required-features = ["mxf"]
name = "oracle_ogg"
required-features = ["ogg"]
[[test]]
name = "oracle_vmd"
required-features = ["vmd"]
[[test]]
name = "roundtrip"
required-features = ["isobmff"]
+57 -6
View File
@@ -2,7 +2,7 @@
Media containers and bit-level I/O for the Craft apps: an MSB-first bit reader and writer,
clean-room ISO BMFF (MP4), QuickTime (MOV), Matroska (MKV, WebM), MXF and AVI demuxers and muxers, and
Ogg and MPEG-2 Systems (transport and program stream) demuxers, written from the public specifications. No `unsafe`, no panics on malformed
Ogg, MPEG-2 Systems (transport and program stream) and Sierra VMD demuxers, written from the public specifications. No `unsafe`, no panics on malformed
input, builds for `wasm32-unknown-unknown`. Dependencies: `thiserror` (for `isobmff`), `chrono`
(for `mxf`), `serde` (optional).
@@ -22,12 +22,13 @@ that codec crates use to describe a file and configure a decoder.
| `avi` | `craft_media::avi` | none |
| `mxf` | `craft_media::mxf` | `chrono` |
| `mpegts` | `craft_media::mpegts` | none |
| `vmd` | `craft_media::vmd` | none |
| (none) | `Container`, `CodecId`, `CodecParams`, `PcmFormat`, `xiph_lace`, `ByteSource`, `ReadSeekSource` | none |
| `serde` | `Serialize`/`Deserialize` on `Container`, `CodecId`, `CodecParams` and `PcmFormat` | `serde` |
`default = ["isobmff"]`, so `bitstream` and `isobmff` build. `matroska` is opt-in: it is about as
much code as `isobmff`, and most users of MP4/MOV (LightCraft, FigCraft, SoundCraft, EffectCraft)
do not read Matroska. `ogg`, `avi`, `mxf` and `mpegts` are opt-in as well. The features are independent.
do not read Matroska. `ogg`, `avi`, `mxf`, `mpegts` and `vmd` are opt-in as well. The features are independent.
```toml
craft-media = { git = "https://github.com/storytold/craft-libs", rev = "<commit>", features = ["matroska"] }
@@ -814,14 +815,64 @@ ffmpeg's decoded sound sample for sample; and files written by `MxfWriter` from
which ffprobe must describe like their source and ffmpeg must decode to the same pictures and
sound.
## `vmd`
A clean-room demuxer for Sierra VMD (Video and Music Data), the video format of Sierra's and
Coktel Vision's 1990s games (Phantasmagoria, Gabriel Knight 2, Shivers, …). There is no official
specification; it is written from the public description at
<https://wiki.multimedia.cx/index.php/VMD>.
```rust
use craft_media::vmd::{FrameKind, open};
let file = open(&bytes)?; // header and table of contents
let (num, den) = file.frame_rate(); // pictures a second, as a fraction
for (i, frame) in file.frames.iter().enumerate() {
let data = file.read_frame(&bytes, i)?; // one frame's data, read on demand
match frame.kind {
FrameKind::Video { new_palette, .. } => { /* file.picture_rect(i), craft_video::vmd */ }
FrameKind::Audio { flags } => { /* craft_audio::vmd */ }
FrameKind::Other(_) => {}
}
}
```
- A file is a sequence of blocks, one picture period each (`Frame::block`). A block holds the
same number of frames in every block; a block with no picture has a frame of no data or of
type 0 in its place, and the picture stays as it was.
- `frame_rate()`: a file with sound plays one block of sound a picture (sample rate over block
length); a file without plays 10 pictures a second.
- Timing: the video frame of block `n` is shown at picture period `n`. Sound is one continuous
stream from the first picture on: decode the sound frames in file order and play the samples
end to end. The first sound frame holds many blocks (28 in most Phantasmagoria files), loaded
ahead by the player, so a later sound frame is heard that much later than the block it is
stored in, and the sound outlasts the pictures.
- `video_params()` and `audio_params()` return `CodecParams` with `CodecId::VmdVideo` and
`CodecId::VmdAudio` and the 816-byte header as `extradata`, which is what
`craft_video::vmd::Decoder::new` and `craft_audio::vmd::Decoder::new` take.
`header_bytes()` is the same header.
- `picture_rect(index)` places a video frame's update in the picture. Frame coordinates are
screen coordinates; a frame as large as the picture that is not at the screen's corner gives
the picture's position from then on, as ffmpeg was seen to do. A frame with no rectangle in
the picture can still carry a palette (`craft_video::vmd::Decoder::decode_palette`).
Gaps: only the 816-byte header is read. The later Coktel Vision revisions with a longer header
or one without a palette are refused (`Error::NotVmd`). Files with 16-bit, 24-bit or Indeo 3
pictures, or with IMA ADPCM sound, open, and report `CodecId::Unknown` for that stream. `sniff`
has only the two-byte header length to go by, so check the file extension too.
Tests: unit tests on files from the test kit's VMD writer (`craft_media_testkit::vmd`; ffmpeg
reads VMD but cannot write it), hostile input, and `tests/oracle_vmd.rs`, which compares the
streams and picture rate with ffprobe's.
## Containers, codecs and codec parameters
Always built, with no dependencies, so codec crates share them:
- `Container`: the file format (`Wav`, `Aiff`, `Flac`, `Mp4`, `QuickTime`, `Matroska`, `WebM`,
`Ogg`, `Caf`, `Adts`, `MpegAudio`, `Ac3`, `Avi`, `Mxf`, `MpegTs`, `MpegPs`), with `name()`.
`Ogg`, `Caf`, `Adts`, `MpegAudio`, `Ac3`, `Avi`, `Mxf`, `MpegTs`, `MpegPs`, `Vmd`), with `name()`.
- `CodecId`: audio and video codecs (`Aac`, `HeAac`, `Opus`, `Eac3`, `Speex`, …, `H264`, `Hevc`,
`Av1`, `ProRes`, `Dnxhd`, `Apv`, `Theora`, …, `Unknown`), with `name()`, `is_audio()`,
`Av1`, `ProRes`, `Dnxhd`, `Apv`, `Theora`, `VmdVideo`, `VmdAudio`, …, `Unknown`), with `name()`, `is_audio()`,
`is_video()`.
- `PcmFormat`: the layout of uncompressed samples, built with `PcmFormat::int(bits, signed,
big_endian)` or `PcmFormat::float(bits, big_endian)`.
@@ -833,7 +884,7 @@ Always built, with no dependencies, so codec crates share them:
Matroska's `CodecPrivate`, as ffmpeg's extradata does: the `AudioSpecificConfig` for AAC, the
`OpusHead` for Opus (MP4's `dOps` is converted), Xiph-laced headers for Vorbis (`xiph_lace`,
`None` for more than 256 packets), `fLaC` + metadata blocks for FLAC, the
`avcC`/`hvcC`/`av1C`/`apvC` record for video.
`avcC`/`hvcC`/`av1C`/`apvC` record for video, the 816-byte file header for VMD video and sound.
All are `#[non_exhaustive]`: new formats and fields are minor changes.
@@ -841,7 +892,7 @@ All are `#[non_exhaustive]`: new formats and fields are minor changes.
`craft_media::ByteSource` (`len`, `read_at(offset, buf)`) is what every demuxer reads from. It is
always built, so a crate that uses only `bitstream` can name it too. `isobmff::ByteSource`,
`matroska::ByteSource`, `ogg::ByteSource`, `avi::ByteSource`, `mxf::ByteSource` and `mpegts::ByteSource` are the same trait. It is implemented for `[u8]`,
`matroska::ByteSource`, `ogg::ByteSource`, `avi::ByteSource`, `mxf::ByteSource`, `mpegts::ByteSource` and `vmd::ByteSource` are the same trait. It is implemented for `[u8]`,
`Vec<u8>`, `&T`, `Arc<T>`, `Box<T>` and `std::fs::File` (not on wasm). `ReadSeekSource` adapts any
`Read + Seek`; it is `Send + Sync` when the reader is `Send`. Implement the trait once for a
custom source (a web `Blob`, a network range reader) to use every container with it.
+15 -2
View File
@@ -44,6 +44,8 @@ pub enum Container {
MpegTs,
/// MPEG-1/2 program stream (MPG, VOB).
MpegPs,
/// Sierra VMD (Video and Music Data).
Vmd,
}
impl Container {
@@ -66,6 +68,7 @@ impl Container {
Container::Mxf => "MXF",
Container::MpegTs => "MPEG-TS",
Container::MpegPs => "MPEG-PS",
Container::Vmd => "VMD",
}
}
}
@@ -132,6 +135,10 @@ pub enum CodecId {
Dnxhd,
/// APV (Advanced Professional Video).
Apv,
/// Sierra VMD video (8-bit paletted).
VmdVideo,
/// Sierra VMD audio (8-bit PCM or 16-bit DPCM).
VmdAudio,
/// A codec this crate has no identifier for.
Unknown,
}
@@ -168,6 +175,8 @@ impl CodecId {
CodecId::Theora => "Theora",
CodecId::Dnxhd => "DNxHD",
CodecId::Apv => "APV",
CodecId::VmdVideo => "VMD video",
CodecId::VmdAudio => "VMD audio",
CodecId::Unknown => "unknown",
}
}
@@ -192,6 +201,7 @@ impl CodecId {
| CodecId::Opus
| CodecId::Vorbis
| CodecId::Speex
| CodecId::VmdAudio
)
}
@@ -211,6 +221,7 @@ impl CodecId {
| CodecId::Theora
| CodecId::Dnxhd
| CodecId::Apv
| CodecId::VmdVideo
)
}
}
@@ -260,6 +271,7 @@ impl PcmFormat {
/// | H.264 / HEVC / AV1 | the `avcC` / `hvcC` / `av1C` record |
/// | VP9 | the MP4 `vpcC` payload, or Matroska's codec feature metadata |
/// | APV | the `apvC` record |
/// | VMD video, VMD audio | the 816-byte VMD file header |
///
/// `sample_rate` and `channels` are what the container declares (for HE-AAC with implicit
/// signalling, usually the core rate), except that Opus is always 48 kHz, the rate it decodes at;
@@ -359,13 +371,14 @@ mod tests {
#[test]
fn audio_and_video_are_disjoint() {
for c in [CodecId::Aac, CodecId::Opus, CodecId::Pcm, CodecId::Eac3, CodecId::Speex] {
for c in [CodecId::Aac, CodecId::Opus, CodecId::Pcm, CodecId::Eac3, CodecId::Speex, CodecId::VmdAudio] {
assert!(c.is_audio() && !c.is_video(), "{c:?}");
}
for c in [CodecId::H264, CodecId::Av1, CodecId::ProRes, CodecId::Theora, CodecId::Dnxhd, CodecId::Apv] {
for c in [CodecId::H264, CodecId::Av1, CodecId::ProRes, CodecId::Theora, CodecId::Dnxhd, CodecId::Apv, CodecId::VmdVideo] {
assert!(c.is_video() && !c.is_audio(), "{c:?}");
}
assert!(!CodecId::Unknown.is_audio() && !CodecId::Unknown.is_video());
assert_eq!((CodecId::VmdVideo.name(), CodecId::VmdAudio.name(), Container::Vmd.name()), ("VMD video", "VMD audio", "VMD"));
}
#[test]
+5 -1
View File
@@ -12,12 +12,13 @@
//! - `mxf` (feature `mxf`, enables `chrono`): a clean-room MXF demuxer and writer (OP1a, OP-Atom).
//! - `mpegts` (feature `mpegts`): a clean-room MPEG-2 Systems demuxer (transport streams and
//! program streams).
//! - `vmd` (feature `vmd`): a clean-room Sierra VMD (Video and Music Data) demuxer.
//! - [`Container`] and [`CodecId`] (no feature): the identifiers the codec crates report a file's
//! container and codec with.
//! - `FileReader` (native): a pooled file `ByteSource` so many clips can be open without holding a
//! descriptor each.
//!
//! `bitstream` and `isobmff` are on by default; `matroska`, `ogg`, `avi`, `mxf` and `mpegts` are opt-in. A crate that needs
//! `bitstream` and `isobmff` are on by default; `matroska`, `ogg`, `avi`, `mxf`, `mpegts` and `vmd` are opt-in. A crate that needs
//! only bit I/O uses `default-features = false, features = ["bitstream"]`.
#[cfg(feature = "avi")]
@@ -38,6 +39,9 @@ pub mod mxf;
#[cfg(feature = "ogg")]
pub mod ogg;
pub mod source;
#[cfg(feature = "vmd")]
pub mod vmd;
#[cfg(not(target_arch = "wasm32"))]
pub use file::{FileReader, MAX_OPEN_FILES};
+437
View File
@@ -0,0 +1,437 @@
//! Clean-room Sierra VMD (Video and Music Data) demuxer, written from the public format
//! description at <https://wiki.multimedia.cx/index.php/VMD> ("Description of the Sierra Video
//! and Music Data (VMD) Format", Mike Melanson and Vladimir Gneushev) and checked against
//! ffmpeg's reading of files made by this crate's tests.
//!
//! A VMD file is an 816-byte header (picture size, a 256-colour palette, the sound format), the
//! frame data, and a table of contents at the end: one 6-byte offset record a block, then one
//! 16-byte record a frame. A block is one picture period and holds the same number of frames in
//! every block: usually a sound frame and a video frame.
//!
//! Pictures and sound are timed differently. The video frame of block `n` is shown at picture
//! period `n` ([`Frame::block`], [`VmdFile::frame_rate`]). Sound is one continuous stream that
//! starts with the first picture: decode the sound frames in file order and play the samples end
//! to end. The first sound frame holds many blocks of sound, which the player loads ahead, so
//! each later sound frame is heard that much later than the block it is stored in, and the sound
//! runs on after the last picture.
//!
//! [`open`] reads the header and the table of contents; [`VmdFile::read_frame`] reads one frame's
//! data on demand. The video decoder is `craft_video::vmd` and the sound decoder
//! `craft_audio::vmd`; both take the header ([`VmdFile::header_bytes`]) as their configuration.
//!
//! Only the 816-byte header is read: the later Coktel Vision revisions with a longer header or
//! one without a palette are refused as [`Error::NotVmd`]. Files whose pictures are 16-bit,
//! 24-bit or Indeo 3 open, and say so in [`Header::video_format`].
//!
//! Every size and count comes from the file and is treated as hostile: the table of contents
//! must lie inside the file, its length is capped, and a frame is read only if all of it is
//! there.
//!
//! No dependencies beyond `std`, no `unsafe`, builds for `wasm32-unknown-unknown`.
#![warn(missing_docs)]
#[cfg(test)]
mod tests;
pub use crate::source::{ByteSource, ReadSeekSource};
use std::io;
/// Errors from reading a VMD file.
#[non_exhaustive]
#[derive(Debug)]
pub enum Error {
/// Not a VMD file with the 816-byte header.
NotVmd,
/// A read failed.
Io(io::Error),
/// Structurally invalid data.
Invalid(String),
}
impl std::fmt::Display for Error {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Error::NotVmd => f.write_str("not a VMD file"),
Error::Io(e) => write!(f, "I/O error: {e}"),
Error::Invalid(e) => write!(f, "invalid VMD: {e}"),
}
}
}
impl std::error::Error for Error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Error::Io(e) => Some(e),
_ => None,
}
}
}
impl From<io::Error> for Error {
fn from(e: io::Error) -> Self {
Error::Io(e)
}
}
/// Result alias for this module.
pub type Result<T> = std::result::Result<T, Error>;
/// Bytes of the file header, its two-byte length field included.
pub const HEADER_LEN: usize = 816;
/// Frames a table of contents may list. A file has at most 65 535 blocks of a few frames each;
/// this bounds the table a hostile header can ask for (16 bytes a frame).
const MAX_FRAMES: u64 = 1 << 22;
/// Whether `head` starts like a VMD file: the header length field, 0x32E. Two bytes are a weak
/// signature, so check the file extension as well, and expect [`open`] to refuse a false match.
pub fn sniff(head: &[u8]) -> bool {
head.get(..2) == Some(&[0x2E, 0x03])
}
/// How the pictures are stored.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VideoFormat {
/// 8-bit palette indices: what `craft_video::vmd` decodes.
Paletted,
/// 16-bit RGB (codec version 13).
Rgb16,
/// 24-bit RGB (codec version 5).
Rgb24,
/// Intel Indeo 3 (codec version 7, or the `iv32` mark).
Indeo3,
}
/// The sound format, from the header.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct AudioHeader {
/// Samples per second.
pub sample_rate: u16,
/// The frame length field, sign removed: samples a block and channel, except in old-style
/// stereo, where it counts both channels.
pub frame_length: u16,
/// 8 (unsigned PCM) or 16 (DPCM).
pub bits: u8,
/// 1 or 2.
pub channels: u8,
/// Number of sound buffers. In the game files seen it is one more than the blocks of sound
/// (silent ones included) in the file's first sound frame.
pub buffers: u16,
/// The audio flags as stored (0x8000 old-style stereo, 0x200 new-style stereo, 0x10 IMA
/// ADPCM).
pub flags: u16,
}
impl AudioHeader {
/// Samples of one block, for one channel.
pub fn block_samples(&self) -> u32 {
let n = u32::from(self.frame_length);
if self.flags & 0x8000 != 0 { n / 2 } else { n }
}
/// Whether the sound is IMA ADPCM, which `craft_audio::vmd` does not decode.
pub fn is_ima_adpcm(&self) -> bool {
self.flags & 0x10 != 0
}
}
/// The file header.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Header {
/// Bytes 2-3: the VMD handle and version.
pub version: u16,
/// Bytes 4-5: the video codec version.
pub codec_version: u16,
/// Number of blocks.
pub blocks: u16,
/// Top coordinate of the picture on the screen.
pub top: u16,
/// Left coordinate of the picture on the screen.
pub left: u16,
/// Picture width in pixels.
pub width: u16,
/// Picture height in pixels.
pub height: u16,
/// Flags (0x1000: the file has sound, if its sample rate is not 0).
pub flags: u16,
/// Frames in every block.
pub frames_per_block: u16,
/// Offset of the frame data.
pub data_offset: u32,
/// Bytes 24-27: `iv32` (in either case) when the video is Indeo 3.
pub indeo: [u8; 4],
/// The first palette: 256 R-G-B triplets of 6-bit components (0 to 63).
pub palette: [u8; 768],
/// Recommended size of the buffer a frame is loaded into.
pub load_buffer_size: u32,
/// Size of the buffer LZ-packed video unpacks into.
pub unpack_buffer_size: u32,
/// The sound format, if the file has sound.
pub audio: Option<AudioHeader>,
/// Offset of the table of contents.
pub toc_offset: u32,
}
impl Header {
/// How the pictures are stored.
pub fn video_format(&self) -> VideoFormat {
if self.indeo.eq_ignore_ascii_case(b"iv32") {
return VideoFormat::Indeo3;
}
match self.codec_version {
5 => VideoFormat::Rgb24,
7 => VideoFormat::Indeo3,
13 => VideoFormat::Rgb16,
_ => VideoFormat::Paletted,
}
}
fn parse(h: &[u8; HEADER_LEN]) -> Result<Header> {
let u16_at = |at: usize| u16::from_le_bytes([h[at], h[at + 1]]);
let u32_at = |at: usize| u32::from_le_bytes([h[at], h[at + 1], h[at + 2], h[at + 3]]);
if usize::from(u16_at(0)) != HEADER_LEN - 2 {
return Err(Error::NotVmd);
}
let flags = u16_at(16);
// the flag is the description's rule. A sample rate of 0 is no sound either: ffmpeg goes
// by the rate alone, and also plays a file that has a rate without the flag
let audio = (flags & 0x1000 != 0 && u16_at(804) != 0).then(|| {
let length = u16_at(806) as i16;
let audio_flags = u16_at(810);
AudioHeader {
sample_rate: u16_at(804),
frame_length: length.unsigned_abs(),
bits: if length < 0 { 16 } else { 8 },
channels: if audio_flags & 0x8200 != 0 { 2 } else { 1 },
buffers: u16_at(808),
flags: audio_flags,
}
});
let mut palette = [0; 768];
palette.copy_from_slice(&h[28..796]);
Ok(Header {
version: u16_at(2),
codec_version: u16_at(4),
blocks: u16_at(6),
top: u16_at(8),
left: u16_at(10),
width: u16_at(12),
height: u16_at(14),
flags,
frames_per_block: u16_at(18),
data_offset: u32_at(20),
indeo: [h[24], h[25], h[26], h[27]],
palette,
load_buffer_size: u32_at(796),
unpack_buffer_size: u32_at(800),
audio,
toc_offset: u32_at(812),
})
}
}
/// What a frame holds, from its record in the table of contents.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FrameKind {
/// Sound.
Audio {
/// 1: one block of sound; 2: a silence mask, then blocks of sound; 3: one block of
/// silence.
flags: u8,
},
/// A picture update. The coordinates are as stored, and include the last column and row;
/// [`VmdFile::picture_rect`] places them in the picture.
Video {
/// Left column.
left: u16,
/// Top row.
top: u16,
/// Right column.
right: u16,
/// Bottom row.
bottom: u16,
/// The data begins with a new palette.
new_palette: bool,
},
/// A frame type this module does not know.
Other(u8),
}
/// One frame.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Frame {
/// What the frame holds.
pub kind: FrameKind,
/// The block the frame is stored in. A block is one picture period, so this is when a video
/// frame is shown. It is not when a sound frame is heard: see the module documentation.
pub block: u32,
/// Offset of the frame data.
pub offset: u64,
/// Bytes of frame data; 0 for a frame that changes nothing.
pub size: u32,
}
/// An opened VMD file: the header and the frames of every block, in file order.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct VmdFile {
/// The header.
pub header: Header,
/// The frames, block after block.
pub frames: Vec<Frame>,
raw_header: Vec<u8>,
/// For each frame, the picture's screen position when the frame is decoded.
origins: Vec<(u16, u16)>,
}
/// Open a VMD file: read the header and the table of contents.
pub fn open<S: ByteSource + ?Sized>(src: &S) -> Result<VmdFile> {
let mut raw = [0u8; HEADER_LEN];
if src.len() < HEADER_LEN as u64 {
return Err(Error::NotVmd);
}
src.read_at(0, &mut raw)?;
let header = Header::parse(&raw)?;
let blocks = u64::from(header.blocks);
let per_block = u64::from(header.frames_per_block);
let count = blocks * per_block;
if count > MAX_FRAMES {
return Err(Error::Invalid(format!("{count} frames in the table of contents")));
}
let toc_len = blocks * 6 + count * 16;
let toc_offset = u64::from(header.toc_offset);
if toc_offset < HEADER_LEN as u64 || toc_offset.checked_add(toc_len).is_none_or(|end| end > src.len()) {
return Err(Error::Invalid("the table of contents is outside the file".into()));
}
// bounded by MAX_FRAMES and by the file length
let mut toc = vec![0u8; toc_len as usize];
src.read_at(toc_offset, &mut toc)?;
let (offsets, records) = toc.split_at(blocks as usize * 6);
let mut frames = Vec::with_capacity(count as usize);
for (block, (entry, records)) in offsets.as_chunks::<6>().0.iter().zip(records.chunks_exact((per_block as usize * 16).max(1))).enumerate() {
let mut offset = u64::from(u32::from_le_bytes([entry[2], entry[3], entry[4], entry[5]]));
for r in records.as_chunks::<16>().0 {
let size = u32::from_le_bytes([r[2], r[3], r[4], r[5]]);
let u16_at = |at: usize| u16::from_le_bytes([r[at], r[at + 1]]);
let kind = match r[0] {
1 => FrameKind::Audio { flags: r[6] },
2 => FrameKind::Video { left: u16_at(6), top: u16_at(8), right: u16_at(10), bottom: u16_at(12), new_palette: r[15] & 2 != 0 },
other => FrameKind::Other(other),
};
frames.push(Frame { kind, block: block as u32, offset, size });
// at most 65 535 frames of under 4 GiB each: no overflow
offset += u64::from(size);
}
}
// the picture's place on the screen as each frame finds it: see `picture_rect`
let mut origin = (0, 0);
let origins = frames
.iter()
.map(|f| {
if let FrameKind::Video { left, top, right, bottom, .. } = f.kind {
let full = right.checked_sub(left).and_then(|w| w.checked_add(1)) == Some(header.width)
&& bottom.checked_sub(top).and_then(|h| h.checked_add(1)) == Some(header.height);
if full && f.size > 0 && (left, top) != (0, 0) {
origin = (left, top);
}
}
origin
})
.collect();
Ok(VmdFile { header, frames, raw_header: raw.to_vec(), origins })
}
/// `size` zero bytes, or `None` if they cannot be had. `vec![0; size]` panics with a capacity
/// overflow for a size the address space cannot hold, which a frame of over 2 GiB is on a 32-bit
/// target.
fn zeroed(size: usize) -> Option<Vec<u8>> {
let mut bytes = Vec::new();
bytes.try_reserve_exact(size).ok()?;
bytes.resize(size, 0);
Some(bytes)
}
impl VmdFile {
/// The 816 header bytes as stored: the configuration (`CodecParams::extradata`) of the VMD
/// video and sound decoders.
pub fn header_bytes(&self) -> &[u8] {
&self.raw_header
}
/// Read the data of frame `index`. A frame that reaches past the end of the file is an
/// error.
pub fn read_frame<S: ByteSource + ?Sized>(&self, src: &S, index: usize) -> Result<Vec<u8>> {
let f = self.frames.get(index).ok_or_else(|| Error::Invalid(format!("no frame {index}")))?;
// checked before allocating: the size is the file's word
if f.offset.checked_add(u64::from(f.size)).is_none_or(|end| end > src.len()) {
return Err(Error::Invalid(format!("frame {index} reaches past the end of the file")));
}
let mut data = zeroed(f.size as usize).ok_or_else(|| Error::Invalid(format!("frame {index} is too large to load")))?;
src.read_at(f.offset, &mut data)?;
Ok(data)
}
/// Pictures a second, as a fraction. A file with sound plays one block of sound a picture;
/// one without plays 10 pictures a second.
pub fn frame_rate(&self) -> (u32, u32) {
match &self.header.audio {
Some(a) if a.block_samples() > 0 => (u32::from(a.sample_rate), a.block_samples()),
_ => (10, 1),
}
}
/// Where the video frame `index` updates the picture: `(left, top, right, bottom)` with the
/// last column and row included, or `None` for a frame that is not video or lies outside the
/// picture.
///
/// Frame coordinates are screen coordinates, and a picture need not sit at the screen's
/// corner. The description does not say where the picture's position comes from. This does
/// what ffmpeg was seen to do: the picture starts at the corner, and a video frame that has
/// data, is exactly as large as the picture and is not at the corner moves it there for that
/// frame and those after it. The position is taken off the frame's coordinates. The header's
/// own position fields are not used.
pub fn picture_rect(&self, index: usize) -> Option<(u16, u16, u16, u16)> {
let FrameKind::Video { left, top, right, bottom, .. } = self.frames.get(index)?.kind else { return None };
let h = &self.header;
let (x, y) = *self.origins.get(index)?;
let (left, right) = (left.checked_sub(x)?, right.checked_sub(x)?);
let (top, bottom) = (top.checked_sub(y)?, bottom.checked_sub(y)?);
(left <= right && top <= bottom && right < h.width && bottom < h.height).then_some((left, top, right, bottom))
}
/// What a video decoder needs, in the container-neutral form the codec crates take:
/// [`CodecId::VmdVideo`] for paletted pictures, with the header as `extradata`. 16-bit,
/// 24-bit and Indeo 3 pictures are [`CodecId::Unknown`] (Indeo 3 with the tag `IV32`).
///
/// [`CodecId::VmdVideo`]: crate::CodecId::VmdVideo
/// [`CodecId::Unknown`]: crate::CodecId::Unknown
pub fn video_params(&self) -> crate::CodecParams {
use crate::{CodecId, CodecParams};
let h = &self.header;
let params = match h.video_format() {
VideoFormat::Paletted => CodecParams::new(CodecId::VmdVideo).with_extradata(self.raw_header.clone()),
VideoFormat::Indeo3 => CodecParams::new(CodecId::Unknown).with_tag(*b"IV32"),
VideoFormat::Rgb16 | VideoFormat::Rgb24 => CodecParams::new(CodecId::Unknown),
};
params.with_size(u32::from(h.width), u32::from(h.height))
}
/// What a sound decoder needs, or `None` for a file without sound: [`CodecId::VmdAudio`]
/// with the header as `extradata`, or [`CodecId::Unknown`] for IMA ADPCM sound.
///
/// [`CodecId::VmdAudio`]: crate::CodecId::VmdAudio
/// [`CodecId::Unknown`]: crate::CodecId::Unknown
pub fn audio_params(&self) -> Option<crate::CodecParams> {
use crate::{CodecId, CodecParams};
let a = self.header.audio.as_ref()?;
let params = if a.is_ima_adpcm() {
CodecParams::new(CodecId::Unknown)
} else {
CodecParams::new(CodecId::VmdAudio).with_extradata(self.raw_header.clone())
};
Some(params.with_sample_rate(u32::from(a.sample_rate)).with_channels(u16::from(a.channels)))
}
}
+205
View File
@@ -0,0 +1,205 @@
use super::*;
use crate::CodecId;
use craft_media_testkit::vmd::{Audio, Frame as F, Spec, build};
fn sample(audio: bool) -> Vec<u8> {
let mut spec = Spec::new(16, 8);
spec.audio = audio.then_some(Audio { sample_rate: 22050, frame_length: 20, buffers: 4, flags: 0 });
let video = |rect, data: &[u8]| F::video(rect, false, data.to_vec());
let mut blocks = vec![vec![video([0, 0, 15, 7], &[2; 129])], vec![video([4, 2, 7, 3], &[2; 9])], vec![video([0, 0, 15, 7], &[])]];
if audio {
for b in &mut blocks {
b.insert(0, F::audio(1, vec![0x80; 20]));
}
}
build(&spec, &blocks)
}
#[test]
fn reads_header_and_frames() {
let d = sample(true);
assert!(sniff(&d));
let f = open(&d).unwrap();
let h = &f.header;
assert_eq!((h.width, h.height, h.blocks, h.frames_per_block), (16, 8, 3, 2));
assert_eq!(h.video_format(), VideoFormat::Paletted);
assert_eq!(h.audio, Some(AudioHeader { sample_rate: 22050, frame_length: 20, bits: 8, channels: 1, buffers: 4, flags: 0 }));
assert_eq!(h.palette[765..], [63, 63, 63]);
assert_eq!(f.header_bytes(), &d[..HEADER_LEN]);
assert_eq!(f.frame_rate(), (22050, 20));
assert_eq!(f.frames.len(), 6);
let sizes: Vec<u32> = f.frames.iter().map(|f| f.size).collect();
assert_eq!(sizes, [20, 129, 20, 9, 20, 0]);
assert_eq!(f.frames.iter().map(|f| f.block).collect::<Vec<_>>(), [0, 0, 1, 1, 2, 2]);
// frames follow each other from the block's offset
assert_eq!(f.frames[0].offset, HEADER_LEN as u64);
assert_eq!(f.frames[1].offset, HEADER_LEN as u64 + 20);
assert_eq!(f.frames[3].offset, HEADER_LEN as u64 + 20 + 129 + 20);
assert_eq!(f.frames[0].kind, FrameKind::Audio { flags: 1 });
assert_eq!(f.frames[3].kind, FrameKind::Video { left: 4, top: 2, right: 7, bottom: 3, new_palette: false });
assert_eq!(f.read_frame(&d, 3).unwrap(), [2; 9]);
assert_eq!(f.read_frame(&d, 5).unwrap(), [0u8; 0]);
assert!(f.read_frame(&d, 6).is_err());
let v = f.video_params();
assert_eq!((v.codec, v.width, v.height, v.extradata.len()), (CodecId::VmdVideo, Some(16), Some(8), HEADER_LEN));
let a = f.audio_params().unwrap();
assert_eq!((a.codec, a.sample_rate, a.channels), (CodecId::VmdAudio, Some(22050), Some(1)));
}
#[test]
fn silent_file_plays_ten_pictures_a_second() {
let f = open(&sample(false)).unwrap();
assert_eq!(f.header.audio, None);
assert!(f.audio_params().is_none());
assert_eq!(f.frame_rate(), (10, 1));
assert_eq!(f.frames.len(), 3);
}
#[test]
fn sound_formats() {
let open_with = |frame_length, flags| {
let mut spec = Spec::new(4, 4);
spec.audio = Some(Audio { sample_rate: 11025, frame_length, buffers: 1, flags });
let f = open(&build(&spec, &[])).unwrap();
let a = f.header.audio.unwrap();
(a.bits, a.channels, a.block_samples(), f.audio_params().unwrap().codec)
};
assert_eq!(open_with(-500, 0), (16, 1, 500, CodecId::VmdAudio));
// new-style stereo counts one channel, old-style both
assert_eq!(open_with(-500, 0x200), (16, 2, 500, CodecId::VmdAudio));
assert_eq!(open_with(500, 0x8000), (8, 2, 250, CodecId::VmdAudio));
assert_eq!(open_with(i16::MIN, 0), (16, 1, 32768, CodecId::VmdAudio));
assert_eq!(open_with(-500, 0x10).3, CodecId::Unknown);
// sound needs the header flag and a sample rate
let mut d = sample(true);
d[804..806].fill(0);
assert_eq!(open(&d).unwrap().header.audio, None);
let mut d = sample(true);
d[17] &= !0x10;
assert_eq!(open(&d).unwrap().header.audio, None);
}
#[test]
fn other_picture_formats_are_not_vmd_video() {
let params = |patch: fn(&mut Vec<u8>)| {
let mut d = sample(false);
patch(&mut d);
let f = open(&d).unwrap();
(f.header.video_format(), f.video_params().codec, f.video_params().tag)
};
assert_eq!(params(|d| d[4] = 5), (VideoFormat::Rgb24, CodecId::Unknown, None));
assert_eq!(params(|d| d[4] = 13), (VideoFormat::Rgb16, CodecId::Unknown, None));
assert_eq!(params(|d| d[4] = 7), (VideoFormat::Indeo3, CodecId::Unknown, Some(*b"IV32")));
assert_eq!(params(|d| d[24..28].copy_from_slice(b"iv32")).0, VideoFormat::Indeo3);
}
/// The cases ffmpeg was checked on. The picture is 20x10 and every frame has data unless said.
#[test]
fn picture_rect_follows_the_picture_position() {
let rects = |header_origin: (u16, u16), frames: &[([u16; 4], usize)]| {
let mut spec = Spec::new(20, 10);
(spec.left, spec.top) = header_origin;
let blocks: Vec<_> = frames.iter().map(|&(rect, size)| vec![F::video(rect, false, vec![2; size])]).collect();
let f = open(&build(&spec, &blocks)).unwrap();
(0..f.frames.len()).map(|i| f.picture_rect(i)).collect::<Vec<_>>()
};
let at = |l, t, r, b| Some((l, t, r, b));
// a picture at the screen's corner, whatever the header says
assert_eq!(rects((10, 5), &[([0, 0, 19, 9], 1), ([12, 6, 18, 9], 1)]), [at(0, 0, 19, 9), at(12, 6, 18, 9)]);
// a frame as large as the picture moves it; frames before that keep the corner
assert_eq!(rects((10, 5), &[([0, 0, 5, 5], 1), ([10, 5, 29, 14], 1), ([10, 5, 12, 7], 1)]), [at(0, 0, 5, 5), at(0, 0, 19, 9), at(0, 0, 2, 2)]);
assert_eq!(
rects((0, 0), &[([0, 0, 9, 4], 1), ([2, 2, 3, 3], 1), ([6, 4, 25, 13], 1), ([6, 4, 8, 6], 1)]),
[at(0, 0, 9, 4), at(2, 2, 3, 3), at(0, 0, 19, 9), at(0, 0, 2, 2)]
);
// a frame without data does not move it
assert_eq!(rects((0, 0), &[([3, 2, 22, 11], 0), ([3, 2, 5, 5], 1), ([0, 0, 2, 2], 1)]), [None, at(3, 2, 5, 5), at(0, 0, 2, 2)]);
// once moved, a full frame at the corner is outside; one elsewhere moves the picture again
assert_eq!(
rects((0, 0), &[([0, 0, 19, 9], 1), ([3, 2, 22, 11], 1), ([0, 0, 19, 9], 1), ([3, 2, 5, 5], 1)]),
[at(0, 0, 19, 9), at(0, 0, 19, 9), None, at(0, 0, 2, 3)]
);
assert_eq!(
rects((0, 0), &[([3, 2, 22, 11], 1), ([5, 5, 24, 14], 1), ([5, 5, 7, 7], 1), ([3, 0, 22, 9], 1), ([3, 2, 5, 5], 1)]),
[at(0, 0, 19, 9), at(0, 0, 19, 9), at(0, 0, 2, 2), at(0, 0, 19, 9), at(0, 2, 2, 5)]
);
// as wide as the picture but not as high is an ordinary frame
assert_eq!(rects((0, 0), &[([3, 2, 22, 8], 1), ([3, 2, 5, 5], 1)]), [None, at(3, 2, 5, 5)]);
// and so is one as high but not as wide
assert_eq!(rects((0, 0), &[([3, 2, 10, 11], 1), ([3, 2, 5, 5], 1)]), [None, at(3, 2, 5, 5)]);
// inverted and oversized frames are outside
assert_eq!(
rects((0, 0), &[([2, 0, 5, 0], 1), ([5, 0, 4, 0], 1), ([0, 1, 0, 0], 1), ([0, 0, 20, 9], 1), ([0, 0, 19, 10], 1)]),
[at(2, 0, 5, 0), None, None, None, None]
);
}
#[test]
fn rejects_what_is_not_vmd() {
assert!(matches!(open(&[0u8; 4][..]), Err(Error::NotVmd)));
assert!(matches!(open(&vec![0u8; 2000]), Err(Error::NotVmd)));
assert!(!sniff(b"RIFF"));
// the shorter header of later revisions
let mut d = sample(false);
d[0] = 0x32;
d[1] = 0;
assert!(matches!(open(&d), Err(Error::NotVmd)));
}
#[test]
fn table_of_contents_must_be_in_the_file() {
let d = sample(true);
assert!(matches!(open(&d[..d.len() - 1]), Err(Error::Invalid(_))));
let mut far = d.clone();
far[812..816].copy_from_slice(&u32::MAX.to_le_bytes());
assert!(matches!(open(&far), Err(Error::Invalid(_))));
let mut early = d.clone();
early[812..816].copy_from_slice(&0u32.to_le_bytes());
assert!(matches!(open(&early), Err(Error::Invalid(_))));
// 65 535 blocks of 65 535 frames is refused before anything is allocated
let mut many = d.clone();
many[6..8].copy_from_slice(&[0xFF; 2]);
many[18..20].copy_from_slice(&[0xFF; 2]);
assert!(matches!(open(&many), Err(Error::Invalid(e)) if e.contains("frames in the table")));
}
#[test]
fn frame_past_the_end_is_an_error() {
let mut d = sample(false);
let toc = u32::from_le_bytes([d[812], d[813], d[814], d[815]]) as usize;
// first frame record: its size field
let record = toc + 3 * 6;
d[record + 2..record + 6].copy_from_slice(&u32::MAX.to_le_bytes());
let f = open(&d).unwrap();
assert!(matches!(f.read_frame(&d, 0), Err(Error::Invalid(_))));
}
/// `vec![0; size]` panics for a size past `isize::MAX`, which a frame of over 2 GiB is on a
/// 32-bit target; the frame buffer must not.
#[test]
fn a_buffer_that_cannot_be_had_is_not_a_panic() {
assert_eq!(zeroed(usize::MAX), None);
assert_eq!(zeroed(isize::MAX as usize + 1), None);
assert_eq!(zeroed(3), Some(vec![0; 3]));
}
#[test]
fn hostile_input_never_panics() {
for (i, seed) in [sample(true), sample(false)].iter().enumerate() {
craft_media_testkit::hostile::hammer(&format!("vmd seed {i}"), seed, 30_000, |d| {
if let Ok(f) = open(d) {
let n = f.frames.len();
for k in [0, n / 2, n.saturating_sub(1), n, usize::MAX] {
let _ = f.read_frame(d, k);
}
for k in [0, n / 2, n.saturating_sub(1), n, usize::MAX] {
let _ = f.picture_rect(k);
}
let _ = (f.frame_rate(), f.video_params(), f.audio_params());
}
});
}
}
+68
View File
@@ -0,0 +1,68 @@
//! VMD files written by the test kit (ffmpeg cannot write VMD), read by ffprobe (skipped without
//! it): the picture size, the sound format and the picture rate agree with what the demuxer
//! reports.
use std::process::Command;
use craft_media::vmd::open;
use craft_media_testkit::vmd::{Audio, Frame, Spec, build};
/// `key=value` lines of ffprobe's stream description.
fn probe(bytes: &[u8], name: &str) -> Option<String> {
let ffprobe = craft_media_testkit::ffprobe()?;
let dir = craft_media_testkit::private_dir("vmd-probe");
let path = dir.join(name);
std::fs::write(&path, bytes).unwrap();
let out = Command::new(ffprobe)
.args(["-v", "error", "-show_entries", "stream=codec_name,width,height,sample_rate,channels,r_frame_rate", "-of", "default=nw=1"])
.arg(&path)
.output()
.unwrap();
std::fs::remove_dir_all(&dir).unwrap();
Some(String::from_utf8_lossy(&out.stdout).into_owned())
}
#[test]
fn ffprobe_agrees_on_the_streams() {
// (frame length field, audio flags): 8-bit mono, 16-bit mono, new and old stereo
let sounds = [None, Some((20i16, 0u16)), Some((-20, 0)), Some((-20, 0x200)), Some((-20, 0x8000)), Some((20, 0x8000))];
for (i, sound) in sounds.into_iter().enumerate() {
let mut spec = Spec::new(32, 24);
spec.audio = sound.map(|(frame_length, flags)| Audio { sample_rate: 22050, frame_length, buffers: 4, flags });
let mut picture = vec![2u8];
picture.extend(std::iter::repeat_n(7, 32 * 24));
let blocks: Vec<Vec<Frame>> = (0..3)
.map(|_| {
let mut block = vec![Frame::video([0, 0, 31, 23], false, picture.clone())];
if sound.is_some() {
// one block of silence
block.insert(0, Frame::audio(3, vec![]));
}
block
})
.collect();
let bytes = build(&spec, &blocks);
let f = open(&bytes).unwrap();
let Some(report) = probe(&bytes, &format!("streams{i}.vmd")) else { return };
let has = |line: &str| assert!(report.lines().any(|l| l == line), "case {i}: no `{line}` in\n{report}");
has("codec_name=vmdvideo");
has(&format!("width={}", f.header.width));
has(&format!("height={}", f.header.height));
let (num, den) = f.frame_rate();
let g = gcd(num, den);
has(&format!("r_frame_rate={}/{}", num / g, den / g));
match f.header.audio {
Some(a) => {
has("codec_name=vmdaudio");
has(&format!("sample_rate={}", a.sample_rate));
has(&format!("channels={}", a.channels));
}
None => assert!(!report.contains("vmdaudio"), "case {i}"),
}
}
}
fn gcd(a: u32, b: u32) -> u32 {
if b == 0 { a } else { gcd(b, a % b) }
}
+1
View File
@@ -13,5 +13,6 @@ workspace = true
[dependencies]
base64 = "0.23"
craft-image-codecs = { workspace = true }
craft-dds = { workspace = true }
thiserror = { workspace = true }
image = { version = "0.25", default-features = false }
+69 -1
View File
@@ -1,4 +1,4 @@
//! DDS compatibility facade; implementation and BC block codecs live in craft-image-codecs.
//! DDS compatibility facade; parsing, mip layout and BC block codecs live in craft-dds.
use crate::{CodecError, Image, Limits, SampleType, bridge};
use craft_image_codecs::Format;
@@ -73,3 +73,71 @@ pub fn encode(image: &Image, options: DdsOptions) -> Result<Vec<u8>, CodecError>
craft_image_codecs::EncodeOptions { dds: craft_image_codecs::DdsOptions { compression, mipmaps: options.mipmaps }, ..Default::default() };
bridge::encode(image, Format::Dds, &opts)
}
/// Metadata for the supported 2D DDS texture, available without pixel data.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DdsInfo {
pub width: u32,
pub height: u32,
pub levels: u32,
pub alpha: bool,
/// `None` for a shared decoder compression not exposed by this legacy writer API.
pub compression: Option<DdsCompression>,
}
fn dds_error(error: craft_dds::DdsError) -> CodecError {
match error {
craft_dds::DdsError::Malformed(reason) => CodecError::malformed("DDS", reason),
craft_dds::DdsError::Unsupported(reason) => CodecError::unsupported("DDS", reason),
craft_dds::DdsError::Encode(reason) => CodecError::encode("DDS", reason),
craft_dds::DdsError::Alloc(len) => CodecError::LimitExceeded(format!("cannot allocate {len} bytes for DDS")),
craft_dds::DdsError::LimitExceeded { required, limit } => {
CodecError::LimitExceeded(format!("decoded DDS requires {required} bytes, exceeding limit {limit}"))
}
other => CodecError::malformed("DDS", other),
}
}
fn layout(texture: &craft_dds::Texture<'_>) -> crate::ChannelLayout {
match texture.layout() {
craft_dds::Layout::Gray => crate::ChannelLayout::Gray,
craft_dds::Layout::GrayA => crate::ChannelLayout::GrayA,
craft_dds::Layout::Rgb => crate::ChannelLayout::Rgb,
craft_dds::Layout::Rgba => crate::ChannelLayout::Rgba,
}
}
pub fn info(bytes: &[u8]) -> Result<DdsInfo, CodecError> {
let texture = craft_dds::Texture::parse(bytes).map_err(dds_error)?;
let compression = match texture.compression() {
craft_dds::DdsCompression::None => Some(DdsCompression::None),
craft_dds::DdsCompression::Bc1 => Some(DdsCompression::Bc1),
craft_dds::DdsCompression::Bc2 => Some(DdsCompression::Bc2),
craft_dds::DdsCompression::Bc3 => Some(DdsCompression::Bc3),
_ => None,
};
let alpha = matches!(texture.layout(), craft_dds::Layout::GrayA | craft_dds::Layout::Rgba);
Ok(DdsInfo { width: texture.width(), height: texture.height(), levels: texture.levels(), alpha, compression })
}
/// Decode the declared mip chain, charging all retained pixels to one output-byte budget.
/// Cancellation is checked before each level; no partial chain is returned.
pub fn decode_levels(bytes: &[u8], limits: &Limits, cancel: &dyn Fn() -> bool) -> Result<Vec<Image>, CodecError> {
let texture = craft_dds::Texture::parse(bytes).map_err(dds_error)?;
let mut images = Vec::new();
images.try_reserve_exact(texture.levels() as usize).map_err(|_| CodecError::LimitExceeded("cannot allocate DDS mip list".into()))?;
let mut remaining = limits.max_alloc;
for i in 0..texture.levels() {
if cancel() {
return Err(CodecError::malformed("DDS", "DDS import cancelled"));
}
let level = texture.mip_level(i).map_err(dds_error)?;
let layout = layout(&level);
let level_limits = Limits { max_alloc: remaining, ..*limits };
level_limits.check(level.width(), level.height(), layout, SampleType::U8)?;
let pixels = level.decode_with_limit(remaining).map_err(dds_error)?;
remaining = remaining.checked_sub(pixels.len() as u64).ok_or_else(|| CodecError::LimitExceeded("DDS mip chain exceeds max_alloc".into()))?;
images.push(Image::from_u8(level.width(), level.height(), layout, pixels)?);
}
Ok(images)
}
+101
View File
@@ -411,3 +411,104 @@ fn rejects_bogus_sizes_and_pixel_formats() {
no_format.extend([0; 4]);
assert!(matches!(decode(&no_format), Err(CodecError::Unsupported { .. })));
}
fn mip_chain() -> Vec<u8> {
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_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();
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::<Vec<_>>(), [(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]);
}
+24 -7
View File
@@ -175,17 +175,32 @@ fn tar_with_name_copy_limit(data: &[u8], max_members: usize, mut name_bytes_left
break;
}
let typeflag = h.get(156).copied().unwrap_or(0);
let Some(mut size) = h.get(124..136).and_then(octal) else {
// Metadata records keep their own framing. For a member, PAX replaces the
// legacy size field entirely, so a valid override does not depend on its contents.
let override_size = match typeflag {
b'x' | b'g' | b'L' | b'K' => None,
_ => pax.size.take().or(pax.global_size),
};
let Some(size) = override_size.or_else(|| h.get(124..136).and_then(octal)) else {
out.warnings.push(format!("unreadable size at {pos:#x}"));
out.length = pos as u64;
break;
};
if !matches!(typeflag, b'x' | b'g' | b'L' | b'K')
&& let Some(s) = pax.size.take().or(pax.global_size)
{
size = s;
let mut data_off = pos + BLOCK;
let old_gnu_sparse = typeflag == b'S' && h.get(257..265) == Some(b"ustar \0");
if old_gnu_sparse {
// Old GNU sparse maps can continue in whole blocks before the stored extents.
let mut extended = h.get(482).is_some_and(|&flag| flag != 0);
while extended {
let Some(block) = r.slice(data_off, BLOCK) else {
out.warnings.push(format!("GNU sparse extension ends early at {data_off:#x}"));
out.length = data.len() as u64;
break 'headers;
};
extended = block.get(504).is_some_and(|&flag| flag != 0);
data_off += BLOCK;
}
}
let data_off = pos + BLOCK;
let Some(next) =
round_up(size, BLOCK as u64).and_then(|s| u64::try_from(data_off).ok()?.checked_add(s)).and_then(|n| usize::try_from(n).ok())
else {
@@ -262,7 +277,7 @@ fn tar_with_name_copy_limit(data: &[u8], max_members: usize, mut name_bytes_left
.or_else(|| Some(text(h.get(157..257).unwrap_or(&[]))))
.filter(|l| !l.is_empty());
let mut kind = tar_kind(typeflag, &name);
if std::mem::take(&mut pax.sparse) || !pax.global_sparse.is_empty() {
if std::mem::take(&mut pax.sparse) || !pax.global_sparse.is_empty() || old_gnu_sparse {
kind = MemberKind::Other;
out.warnings.push(format!("{name}: GNU sparse reconstruction is unsupported; stored extents are not the complete file"));
}
@@ -523,6 +538,8 @@ pub fn cpio_with_checksum(data: &[u8], max_members: usize, checksum: &mut dyn Fn
}
if format == "cpio-crc" {
match h.get(102..110).filter(|field| field.iter().all(u8::is_ascii_hexdigit)).and_then(hex_field).and_then(|n| u32::try_from(n).ok()) {
// GNU cpio writes the symlink target without a checksum.
Some(0) if kind == MemberKind::Symlink => {}
Some(expected) => {
if let Some(body) = r.slice(data_off, size) {
match checksum(body) {
+152
View File
@@ -402,3 +402,155 @@ mod tar_global_pax {
}
}
}
// Ported from Craft Anything gnu_sparse_extensions.rs (RRFZ).
mod gnu_sparse_extensions {
use crate::testkit::tar_entries;
use crate::{MemberKind, member_data, tar};
/// Build an old GNU sparse header followed by the requested number of extension blocks.
fn archive(extension_blocks: usize) -> Vec<u8> {
let mut archive = tar_entries(&[("sparse.dat", b'S', &[b'x'; 512], ""), ("after.txt", b'0', b"after", "")]);
archive[257..265].copy_from_slice(b"ustar \0");
archive[482] = u8::from(extension_blocks != 0);
archive[148..156].fill(b' ');
let sum: u32 = archive[..512].iter().map(|&byte| u32::from(byte)).sum();
archive[148..156].copy_from_slice(format!("{sum:06o}\0 ").as_bytes());
let mut extensions = vec![0; 512 * extension_blocks];
for block in extensions.as_chunks_mut::<512>().0.iter_mut().take(extension_blocks.saturating_sub(1)) {
block[504] = 1;
}
archive.splice(512..512, extensions);
archive
}
/// Actual file data starts after the entire sparse map. Later members remain readable.
#[test]
fn skips_old_gnu_sparse_extension_blocks() {
for blocks in [1, 2] {
let bytes = archive(blocks);
let listing = tar(&bytes, 8).unwrap();
assert!(listing.complete, "{blocks} extensions: {:?}", listing.warnings);
assert_eq!(listing.members.len(), 2);
assert_eq!(listing.members[0].kind, MemberKind::Other);
assert_eq!(listing.members[0].data_offset, (512 * (blocks + 1)) as u64);
assert_eq!(listing.members[1].name, "after.txt");
assert_eq!(member_data(&bytes, &listing.members[1]), Some(b"after".as_slice()));
}
}
/// A missing sparse extension cannot turn padding into a complete archive.
#[test]
fn refuses_a_truncated_old_gnu_sparse_extension() {
let mut bytes = archive(2);
bytes.truncate(512 + 512 + 17);
let listing = tar(&bytes, 8).unwrap();
assert!(!listing.complete);
assert!(listing.members.is_empty());
assert!(listing.warnings.iter().any(|warning| warning.contains("sparse extension")));
}
/// A sparse member with no extensions still leaves the next header at its usual offset.
#[test]
fn keeps_the_next_member_when_no_sparse_extensions_follow() {
let bytes = archive(0);
let listing = tar(&bytes, 8).unwrap();
assert!(listing.complete);
assert_eq!(listing.members[0].kind, MemberKind::Other);
assert_eq!(listing.members[1].name, "after.txt");
}
}
// Ported from Craft Anything cpio_symlink_crc.rs (RRFZ).
mod cpio_symlink_crc {
use crate::cpio;
use crate::testkit::cpio_newc;
/// Convert a single-member newc fixture to CRC and set the member checksum.
fn archive(mode: u32, checksum: u32) -> Vec<u8> {
let mut bytes = cpio_newc(&[("entry", b"target", mode)]);
bytes[..6].copy_from_slice(b"070702");
bytes[102..110].copy_from_slice(format!("{checksum:08x}").as_bytes());
let trailer = (110 + "entry".len() + 1 + 3) & !3;
let trailer = (trailer + "target".len() + 3) & !3;
bytes[trailer..trailer + 6].copy_from_slice(b"070702");
bytes
}
/// GNU-style CRC symlinks carry a zero placeholder and keep the recorded target.
#[test]
fn accepts_a_symlink_with_no_stored_checksum() {
let listing = cpio(&archive(0o120777, 0), 10).unwrap();
assert!(listing.complete);
assert_eq!(listing.members[0].link_target.as_deref(), Some("target"));
assert!(listing.warnings.is_empty(), "{:?}", listing.warnings);
}
/// A nonzero symlink checksum and even a zero regular-file checksum are checked.
#[test]
fn still_checks_nonzero_symlink_and_zero_regular_file_checksums() {
assert!(cpio(&archive(0o120777, 647), 10).unwrap().warnings.is_empty());
for bytes in [archive(0o120777, 646), archive(0o100644, 0)] {
assert!(cpio(&bytes, 10).unwrap().warnings.iter().any(|w| w.contains("checksum mismatch")));
}
}
}
// Ported from Craft Anything tar_pax_size_precedence.rs (RRFZ).
mod tar_pax_size_precedence {
use crate::testkit::tar_entries;
use crate::{member_data, tar};
/// Make an octal size unreadable while leaving the enclosing TAR header checksum valid.
fn corrupt_size(archive: &mut [u8], offset: usize) {
let header = &mut archive[offset..offset + 512];
header[124] = b'9';
header[148..156].fill(b' ');
let sum: u32 = header.iter().map(|&byte| u32::from(byte)).sum();
header[148..156].copy_from_slice(format!("{sum:06o}\0 ").as_bytes());
}
/// Local and inherited size records override the bad field and keep the following header aligned.
#[test]
fn valid_pax_size_controls_the_member_extent() {
for extension in *b"xg" {
let mut archive = tar_entries(&[("PaxHeader", extension, b"10 size=3\n", ""), ("file", b'0', b"abc", ""), ("next", b'0', b"def", "")]);
corrupt_size(&mut archive, 1024);
let list = tar(&archive, 10).unwrap();
assert!(list.complete, "{:?}", list.warnings);
assert_eq!(list.members.len(), 2);
assert_eq!(member_data(&archive, &list.members[0]), Some(b"abc".as_slice()));
assert_eq!(member_data(&archive, &list.members[1]), Some(b"def".as_slice()));
}
}
/// A local zero overrides a global size and does not consume the next header.
#[test]
fn a_local_zero_size_overrides_the_global_value() {
let mut archive = tar_entries(&[
("Global", b'g', b"12 size=600\n", ""),
("Local", b'x', b"10 size=0\n", ""),
("empty", b'0', b"", ""),
("next", b'0', &[b'a'; 600], ""),
]);
corrupt_size(&mut archive, 2048);
let list = tar(&archive, 10).unwrap();
assert!(list.complete, "{:?}", list.warnings);
assert_eq!(list.members.iter().map(|m| m.size).collect::<Vec<_>>(), [0, 600]);
}
/// An ordinary header without an override and a PAX header itself still need readable sizes.
#[test]
fn rejects_bad_sizes_without_an_applicable_override() {
let mut plain = tar_entries(&[("file", b'0', b"abc", "")]);
corrupt_size(&mut plain, 0);
let mut with_global = tar_entries(&[("Global", b'g', b"10 size=3\n", ""), ("Local", b'x', b"10 size=0\n", ""), ("file", b'0', b"", "")]);
corrupt_size(&mut with_global, 1024);
for archive in [plain, with_global] {
let list = tar(&archive, 10).unwrap();
assert!(!list.complete);
assert!(list.members.is_empty());
assert!(list.warnings.iter().any(|warning| warning.contains("unreadable size")));
}
}
}
+10 -3
View File
@@ -1,6 +1,6 @@
[package]
name = "craft-video"
description = "Clean-room pure-Rust video codecs, one feature per codec: DNxHD/DNxHR, VP8, ProRes, H.264, HEVC, VP9, AV1, MPEG-4 Part 2."
description = "Clean-room pure-Rust video codecs, one feature per codec: DNxHD/DNxHR, VP8, ProRes, H.264, HEVC, VP9, AV1, MPEG-4 Part 2, Sierra VMD."
version.workspace = true
edition.workspace = true
license.workspace = true
@@ -62,6 +62,9 @@ av1-decode = []
av1-encode = ["craft-media/isobmff"]
# Tiled AV1 fallback for frames that exceed the clean-room encoder's single-tile limits.
av1-large-encode = ["av1-encode", "dep:rav1e"]
# Sierra VMD video (8-bit paletted): decoder; `vmd` turns it on too.
vmd = ["vmd-decode"]
vmd-decode = []
# Decode and encode across worker threads (rayon) in the codecs that support it.
threads = ["dep:rayon", "rav1e?/threading"]
@@ -77,8 +80,12 @@ rav1e = { version = "0.8", default-features = false, optional = true }
[dev-dependencies]
craft-media-testkit = { workspace = true }
# The AVI muxer, for the MPEG-4 Part 2 encoder's end-to-end test.
craft-media = { workspace = true, features = ["avi"] }
# The AVI muxer, for the MPEG-4 Part 2 encoder's end-to-end test, and the VMD demuxer for the VMD decoder's.
craft-media = { workspace = true, features = ["avi", "vmd"] }
[[test]]
name = "vmd"
required-features = ["vmd-decode"]
[[test]]
name = "hap"
+4 -1
View File
@@ -30,6 +30,7 @@ No codec feature is on by default.
| `hevc` | [`hevc`](src/hevc/decode/README.md) | ITU-T H.265 / HEVC: decoder (`hevc-decode` alone) and encoder (`hevc-encode` alone) |
| `vp9` | [`vp9`](src/vp9/decode/README.md) | VP9: decoder (`vp9-decode` alone) and encoder (`vp9-encode` alone) |
| `av1` | [`av1`](src/av1/decode/README.md) | AV1 (AOMedia Video 1): decoder (`av1-decode` alone) and clean-room encoder (`av1-encode`); tiled rav1e fallback for large frames (`av1-large-encode`) |
| `vmd` | `vmd` | Sierra VMD video (the 8-bit paletted pictures of Sierra and Coktel Vision game videos): decoder (`vmd-decode`) |
| `threads` | — | Multi-threaded slice/row parallelism via `rayon` |
## Decoded frames
@@ -41,7 +42,9 @@ comes with its codec's feature):
- Planes are `[Y, Cb, Cr]`, `[R, G, B]` or `[Y]` (`ColorFamily`), plus an optional alpha plane.
DNx, VP9 and AV1 (identity matrix) store RGB as G, B, R; the conversion reorders them.
- Samples keep the decoder's storage, `u8` or `u16`, with a bit depth per plane (HEVC chroma may
differ from luma). Converting moves the buffers and copies no samples.
differ from luma). Converting moves the buffers and copies no samples, except for paletted
video: VMD holds its picture as palette indices in the decoder, so `VideoFrame::try_from(&decoder)`
looks them up and writes new 8-bit R, G, B planes.
- Chroma subsampling is a log2 shift per axis, 0 to 3 (FFV1 codes up to 3).
- Colour is given as ITU-T H.273 code points (`ColorTags`), mapped from each codec's own
signalling. Codecs that do not signal a value leave it unspecified (2).
+34
View File
@@ -369,3 +369,37 @@ impl TryFrom<crate::ffv1::Frame> for VideoFrame {
Ok(f)
}
}
#[cfg(feature = "vmd-decode")]
impl TryFrom<&crate::vmd::Decoder> for VideoFrame {
type Error = FrameError;
/// The decoder's current picture, its palette indices looked up in its palette: 8-bit R, G, B
/// planes at full size (the samples are copied, as VMD stores none of them as planes). VMD
/// signals no colour description beyond RGB, nor timing.
fn try_from(d: &crate::vmd::Decoder) -> Result<Self, FrameError> {
paletted(d.width(), d.height(), d.indices(), d.palette())
}
}
/// A picture of palette indices, `width` a row, as 8-bit R, G, B planes. Matrix 0 (identity), the
/// other colour tags unspecified.
#[cfg(feature = "vmd-decode")]
fn paletted(width: usize, height: usize, indices: &[u8], palette: &[[u8; 3]; 256]) -> Result<VideoFrame, FrameError> {
let too_large = FrameError::Shape("picture size does not fit in u32");
let (w, h) = (u32::try_from(width).map_err(|_| too_large.clone())?, u32::try_from(height).map_err(|_| too_large)?);
let n = width.checked_mul(height).ok_or(FrameError::Shape("picture size overflows"))?;
let indices = indices.get(..n).ok_or(FrameError::Plane("fewer palette indices than pixels"))?;
let mut planes = [Vec::with_capacity(n), Vec::with_capacity(n), Vec::with_capacity(n)];
for &i in indices {
let [r, g, b] = palette[usize::from(i)];
planes[0].push(r);
planes[1].push(g);
planes[2].push(b);
}
let [r, g, b] = planes;
let planes = vec![Plane::packed(w, h, 8, Samples::U8(r))?, Plane::packed(w, h, 8, Samples::U8(g))?, Plane::packed(w, h, 8, Samples::U8(b))?];
let mut f = VideoFrame::new(w, h, ColorFamily::Rgb, Subsampling::S444, planes, None)?;
f.color.matrix = 0;
Ok(f)
}
+3 -1
View File
@@ -4,7 +4,9 @@
//! common: planar samples at their stored width (`u8` or `u16`), per-plane bit depth, chroma
//! subsampling, an optional alpha plane, colour tags as ITU-T H.273 code points, and timing.
//! Every decoder output converts into it with `VideoFrame::try_from`, behind the codec's feature.
//! A conversion moves the sample buffers; it does not copy or rescale samples.
//! A conversion moves the sample buffers; it does not copy or rescale samples. Paletted video is
//! the exception: VMD's decoder holds palette indices, and converting it (`&vmd::Decoder`) writes
//! new 8-bit R, G, B planes from its palette.
//!
//! Plane order is fixed by [`ColorFamily`]: `[Y, Cb, Cr]`, `[R, G, B]` or `[Y]`. Decoders that
//! store RGB in another order (DNx, VP9 and identity-matrix AV1 store G, B, R) are reordered by
+4
View File
@@ -18,6 +18,7 @@
//! | `hevc` | [`hevc`] | ITU-T H.265 / HEVC: decoder (`hevc-decode`) and encoder (`hevc-encode`) |
//! | `vp9` | [`vp9`] | VP9: decoder (`vp9-decode`) and encoder (`vp9-encode`) |
//! | `av1` | [`av1`] | AV1 (AOMedia Video 1): decoder (`av1-decode`) and encoder (`av1-encode`) |
//! | `vmd` | [`vmd`] | Sierra VMD video (8-bit paletted): decoder (`vmd-decode`) |
//!
//! No codec is on by default. Feature `threads` spreads the work of the codecs that support it
//! over rayon worker threads.
@@ -78,3 +79,6 @@ pub mod raw_video;
/// Bounded Screen Video key-frame decoding (FLV codec 3).
#[cfg(feature = "screen-video")]
pub mod screen_video;
#[cfg(feature = "vmd-decode")]
pub mod vmd;
+402
View File
@@ -0,0 +1,402 @@
//! Sierra VMD video decoder: the 8-bit paletted pictures 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 <https://wiki.multimedia.cx/index.php/VMD>
//! ("Description of the Sierra Video and Music Data (VMD) Format", Mike Melanson and Vladimir
//! Gneushev). Where the description leaves a choice open, the decoder does what ffmpeg does with
//! the same bytes, observed from outside on files made by this crate's tests:
//!
//! - a frame's new palette replaces all 256 entries, whatever the two bytes before it say;
//! - a line of a method 1 or 3 frame must fill its width exactly.
//!
//! A [`Decoder`] is made from the 816-byte file header and holds one picture of palette indices.
//! Each video frame updates a rectangle of it: [`Decoder::decode`] takes the rectangle and the
//! palette flag from the frame's record in the file's table of contents (`craft_media::vmd`
//! reads both) and the frame data. The first frame of a file paints the whole picture; every
//! later frame depends on the ones before it, so decoding starts at the first frame.
//!
//! ```no_run
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # let bytes: Vec<u8> = Vec::new();
//! use craft_media::vmd::{FrameKind, open};
//! use craft_video::vmd::{Decoder, Rect};
//!
//! let file = open(&bytes)?;
//! let mut decoder = Decoder::new(file.header_bytes())?;
//! for (i, frame) in file.frames.iter().enumerate() {
//! let FrameKind::Video { new_palette, .. } = frame.kind else { continue };
//! let data = file.read_frame(&bytes, i)?;
//! match file.picture_rect(i) {
//! Some(rect) => decoder.decode(Rect::from(rect), new_palette, &data)?,
//! // a frame that paints nothing in the picture can still bring a palette
//! None if new_palette => decoder.decode_palette(&data)?,
//! None => {}
//! }
//! let rgb = decoder.rgb24(); // the picture after this block
//! }
//! # Ok(())
//! # }
//! ```
//!
//! Not decoded: the 16-bit and 24-bit pictures and the Indeo 3 video of later Coktel Vision
//! files ([`Error::Unsupported`]).
//!
//! Input is treated as hostile: the picture is checked against the decode memory budget
//! ([`crate::budget`]), LZ output is bounded by the header's unpack buffer size and by a few
//! bytes a pixel of the picture, and every copy is bounds-checked. No `unsafe`, no panics.
#![warn(missing_docs)]
use crate::budget::{DECODE_MEMORY_BUDGET, PictureShape};
/// Bytes of the VMD file header a [`Decoder`] is made from.
pub const HEADER_LEN: usize = 816;
/// Errors from decoding VMD video.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// The header or a frame is not valid.
#[error("invalid VMD video: {0}")]
Invalid(&'static str),
/// Valid, but not something this decoder handles.
#[error("unsupported VMD video: {0}")]
Unsupported(&'static str),
/// The picture does not fit the decode memory budget.
#[error("a VMD picture of {0}x{1} exceeds the decode memory budget")]
TooLarge(u16, u16),
}
/// Result alias for this module.
pub type Result<T> = std::result::Result<T, Error>;
/// The part of the picture a frame updates. `right` and `bottom` are the last column and row
/// updated, not one past them.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Rect {
/// First column.
pub left: u16,
/// First row.
pub top: u16,
/// Last column.
pub right: u16,
/// Last row.
pub bottom: u16,
}
impl From<(u16, u16, u16, u16)> for Rect {
/// From `(left, top, right, bottom)`, as `craft_media::vmd::VmdFile::picture_rect` returns
/// it.
fn from((left, top, right, bottom): (u16, u16, u16, u16)) -> Rect {
Rect { left, top, right, bottom }
}
}
/// A VMD video decoder: one picture of palette indices and the current palette.
#[derive(Clone, Debug)]
pub struct Decoder {
width: usize,
height: usize,
indices: Vec<u8>,
palette: [[u8; 3]; 256],
/// The header's unpack buffer size: the most an LZ-packed frame may unpack to.
unpack_limit: usize,
/// LZ output of the current frame, kept between frames to save the allocation.
unpacked: Vec<u8>,
}
impl Decoder {
/// A decoder for the file whose header is `header` (its first 816 bytes; more are ignored).
/// The picture starts as index 0 everywhere, with the header's palette.
pub fn new(header: &[u8]) -> Result<Decoder> {
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 h[24..28].eq_ignore_ascii_case(b"iv32") {
return Err(Error::Unsupported("Indeo 3 video"));
}
match u16_at(4) {
5 => return Err(Error::Unsupported("24-bit pictures")),
7 => return Err(Error::Unsupported("Indeo 3 video")),
13 => return Err(Error::Unsupported("16-bit pictures")),
_ => {}
}
let (width, height) = (u16_at(12), u16_at(14));
if width == 0 || height == 0 {
return Err(Error::Invalid("the picture has no pixels"));
}
// the indices, an RGBA copy of them for the caller, and the unpack buffer
let shape = PictureShape { width: width.into(), height: height.into(), shift_x: 0, shift_y: 0, chroma_planes: 0, bytes_per_sample: 9 };
if !shape.fits(1, DECODE_MEMORY_BUDGET) {
return Err(Error::TooLarge(width, height));
}
let (width, height) = (usize::from(width), usize::from(height));
let mut d = Decoder {
width,
height,
indices: vec![0; width * height],
palette: [[0; 3]; 256],
unpack_limit: u32::from_le_bytes([h[800], h[801], h[802], h[803]]) as usize,
unpacked: Vec::new(),
};
d.load_palette(&h[28..796]);
Ok(d)
}
/// Picture width in pixels.
pub fn width(&self) -> usize {
self.width
}
/// Picture height in pixels.
pub fn height(&self) -> usize {
self.height
}
/// The picture as palette indices: `width * height` bytes, rows from the top.
pub fn indices(&self) -> &[u8] {
&self.indices
}
/// The current palette as 8-bit R, G, B. The file stores 6-bit components; they are widened
/// by repeating their top bits, so 63 becomes 255.
pub fn palette(&self) -> &[[u8; 3]; 256] {
&self.palette
}
/// The picture as packed 8-bit R, G, B: `width * height * 3` bytes, rows from the top.
pub fn rgb24(&self) -> Vec<u8> {
let mut out = Vec::with_capacity(self.indices.len() * 3);
for &i in &self.indices {
out.extend_from_slice(&self.palette[usize::from(i)]);
}
out
}
/// The picture as packed 8-bit R, G, B, A with opaque alpha: `width * height * 4` bytes.
pub fn rgba8(&self) -> Vec<u8> {
let mut out = Vec::with_capacity(self.indices.len() * 4);
for &i in &self.indices {
let [r, g, b] = self.palette[usize::from(i)];
out.extend_from_slice(&[r, g, b, 255]);
}
out
}
/// Decode one video frame into the picture. `rect` is the part of the picture the frame
/// updates and `new_palette` whether its data begins with a palette, both from the frame's
/// record; `data` is the frame data. An empty frame changes nothing.
///
/// On an error the picture holds whatever the frame had painted up to that point; later
/// frames still decode against it.
pub fn decode(&mut self, rect: Rect, new_palette: bool, data: &[u8]) -> Result<()> {
let mut data = data;
if new_palette && !data.is_empty() {
self.decode_palette(data)?;
data = &data[770..];
}
let Some((&method, body)) = data.split_first() else { return Ok(()) };
if rect.right < rect.left || rect.bottom < rect.top || usize::from(rect.right) >= self.width || usize::from(rect.bottom) >= self.height {
return Err(Error::Invalid("the frame lies outside the picture"));
}
if method & 0x80 == 0 {
return self.render(rect, method, body);
}
let mut unpacked = std::mem::take(&mut self.unpacked);
// a frame needs at most three bytes a pixel (more only with run-length codes that
// paint nothing): unpacking stops past that, so that a frame's cost goes by the
// picture's size and not by what the file says
let useful = self.indices.len().saturating_mul(4).saturating_add(1024);
let result = lz_unpack(body, self.unpack_limit, useful, &mut unpacked).and_then(|()| self.render(rect, method & 0x7F, &unpacked));
self.unpacked = unpacked;
result
}
/// Take the palette that the data of a frame with a new palette begins with, and paint
/// nothing: for a video frame that has no rectangle in the picture (an empty one, as ffmpeg
/// was seen to accept, or one outside the picture). [`Decoder::decode`] does this itself for
/// the frames it is given. An empty frame changes nothing.
pub fn decode_palette(&mut self, data: &[u8]) -> Result<()> {
if data.is_empty() {
return Ok(());
}
// first index and count (ignored, see the module documentation), then 256 entries
let chunk = data.get(..770).ok_or(Error::Invalid("the palette is cut short"))?;
self.load_palette(&chunk[2..]);
Ok(())
}
fn load_palette(&mut self, vga: &[u8]) {
for (entry, rgb) in self.palette.iter_mut().zip(vga.as_chunks::<3>().0) {
for (c, &v) in entry.iter_mut().zip(rgb) {
let v = v & 0x3F;
*c = v << 2 | v >> 4;
}
}
}
/// Paint `data` (the frame body, unpacked if it was LZ-packed) onto `rect`.
fn render(&mut self, rect: Rect, method: u8, data: &[u8]) -> Result<()> {
const SHORT: Error = Error::Invalid("the frame data ends early");
let left = usize::from(rect.left);
let width = usize::from(rect.right) - left + 1;
let rows = usize::from(rect.top)..=usize::from(rect.bottom);
let mut src = Reader(data);
match method {
// lines of runs: skip (keep the pixels of the previous picture) or copy
1 | 3 => {
for y in rows {
let line = &mut self.indices[y * self.width + left..][..width];
let mut x = 0;
while x < width {
let code = src.byte().ok_or(SHORT)?;
let n = usize::from(code & 0x7F) + 1;
let run = line.get_mut(x..x + n).ok_or(Error::Invalid("a run crosses the end of its line"))?;
if code & 0x80 != 0 {
if method == 3 && src.peek() == Some(0xFF) {
src.byte();
unpack_rle(&mut src, run)?;
} else {
run.copy_from_slice(src.take(n).ok_or(SHORT)?);
}
}
x += n;
}
}
Ok(())
}
// the pixels as they are
2 => {
for y in rows {
let line = &mut self.indices[y * self.width + left..][..width];
line.copy_from_slice(src.take(width).ok_or(SHORT)?);
}
Ok(())
}
_ => Err(Error::Unsupported("unknown rendering method")),
}
}
}
/// A cursor over frame data.
struct Reader<'a>(&'a [u8]);
impl<'a> Reader<'a> {
fn peek(&self) -> Option<u8> {
self.0.first().copied()
}
fn byte(&mut self) -> Option<u8> {
let (&b, rest) = self.0.split_first()?;
self.0 = rest;
Some(b)
}
fn take(&mut self, n: usize) -> Option<&'a [u8]> {
let (head, rest) = self.0.split_at_checked(n)?;
self.0 = rest;
Some(head)
}
}
/// Fill `run` from the run-length coding of method 3: a single byte if the run is odd, then
/// pairs of bytes, either copied or one pair repeated.
fn unpack_rle(src: &mut Reader, run: &mut [u8]) -> Result<()> {
const SHORT: Error = Error::Invalid("the frame data ends early");
const LONG: Error = Error::Invalid("run-length data overruns its run");
let mut run = run;
if run.len() % 2 == 1 {
run[0] = src.byte().ok_or(SHORT)?;
run = &mut run[1..];
}
while !run.is_empty() {
let code = src.byte().ok_or(SHORT)?;
let n = usize::from(code & 0x7F) * 2;
let (head, rest) = run.split_at_mut_checked(n).ok_or(LONG)?;
if code & 0x80 != 0 {
head.copy_from_slice(src.take(n).ok_or(SHORT)?);
} else {
let pair = src.take(2).ok_or(SHORT)?;
for p in head.as_chunks_mut::<2>().0 {
p.copy_from_slice(pair);
}
}
run = rest;
}
Ok(())
}
/// Unpack an LZ-packed frame body into `out`: the unpacked length, an optional marker that
/// selects long chains, then tag bytes whose bits (lowest first) each announce a literal byte
/// or a chain copied from a 4096-byte window of earlier output. Packed data that ends before
/// the length is reached leaves `out` short; the rendering then fails if it needs more. A length
/// above `limit` is an error; unpacking stops after `useful` bytes.
fn lz_unpack(src: &[u8], limit: usize, useful: usize, out: &mut Vec<u8>) -> Result<()> {
out.clear();
let mut src = Reader(src);
let len = src.take(4).ok_or(Error::Invalid("the frame data ends early"))?;
let mut left = u32::from_le_bytes([len[0], len[1], len[2], len[3]]) as usize;
if left > limit {
return Err(Error::Invalid("an LZ-packed frame is larger than the unpack buffer"));
}
left = left.min(useful);
let mut window = Window { bytes: [0x20; 4096], at: 0xFEE };
let mut long_chains = false;
if src.0.starts_with(&[0x34, 0x12, 0x78, 0x56]) {
src.take(4);
window.at = 0x111;
long_chains = true;
}
while left > 0 {
let Some(tag) = src.byte() else { return Ok(()) };
if tag == 0xFF && left > 8 {
let Some(raw) = src.take(8) else { return Ok(()) };
for &b in raw {
window.emit(b, out);
}
left -= 8;
continue;
}
for bit in 0..8 {
if left == 0 {
break;
}
if tag >> bit & 1 == 1 {
let Some(b) = src.byte() else { return Ok(()) };
window.emit(b, out);
left -= 1;
continue;
}
let Some(&[lo, hi]) = src.take(2).and_then(|p| p.first_chunk::<2>()) else { return Ok(()) };
let from = usize::from(lo) | usize::from(hi & 0xF0) << 4;
let mut n = usize::from(hi & 0x0F) + 3;
if long_chains && n == 18 {
let Some(more) = src.byte() else { return Ok(()) };
n += usize::from(more);
}
let n = n.min(left);
// byte by byte: a chain may read what it has just written
for i in 0..n {
window.emit(window.bytes[(from + i) & 0xFFF], out);
}
left -= n;
}
}
Ok(())
}
/// The 4096 bytes of earlier output that LZ chains copy from, and where the next byte goes.
struct Window {
bytes: [u8; 4096],
at: usize,
}
impl Window {
fn emit(&mut self, b: u8, out: &mut Vec<u8>) {
out.push(b);
self.bytes[self.at] = b;
self.at = (self.at + 1) & 0xFFF;
}
}
+538
View File
@@ -0,0 +1,538 @@
//! VMD video decoder tests. ffmpeg reads VMD but cannot write it, so the files come from the
//! test kit's VMD writer, which packs random pictures with every coding mode: the three
//! rendering methods, LZ packing with short and long chains, partial updates and palette
//! changes. The decoder must return the pictures that were packed, and the same pictures as
//! ffmpeg (skipped without ffmpeg).
use std::io::Read;
use std::process::{Command, Stdio};
use craft_media::vmd::{FrameKind, open};
use craft_media_testkit::hostile::Rng;
use craft_media_testkit::vmd::{Frame, Spec, build, delta_lines, lz_pack, palette_chunk};
use craft_video::vmd::{Decoder, Error, Rect};
/// A file and the picture (indices and 6-bit palette) expected after each block.
struct Movie {
bytes: Vec<u8>,
width: usize,
pictures: Vec<(Vec<u8>, [u8; 768])>,
/// How each frame was packed, for failure messages.
notes: Vec<String>,
}
/// Change a random rectangle of `pic` with stretches of noise, flat colour, repeated pairs,
/// 0xFF and untouched pixels; returns the rectangle.
fn mutate(rng: &mut Rng, pic: &mut [u8], w: usize, h: usize) -> [u16; 4] {
let x0 = rng.below(w);
let x1 = x0 + rng.below(w - x0);
let y0 = rng.below(h);
let y1 = y0 + rng.below(h - y0);
for y in y0..=y1 {
let mut style = rng.below(5);
let (a, b) = (rng.next_u64() as u8, rng.next_u64() as u8);
for x in x0..=x1 {
if rng.below(12) == 0 {
style = rng.below(5);
}
let p = &mut pic[y * w + x];
match style {
0 => *p = rng.next_u64() as u8,
1 => *p = a,
2 => *p = if x % 2 == 0 { a } else { b },
3 => *p = 0xFF,
_ => {}
}
}
}
[x0 as u16, y0 as u16, x1 as u16, y1 as u16]
}
fn movie(seed: u64, w: usize, h: usize, frames: usize) -> Movie {
let mut rng = Rng(seed | 1);
let mut spec = Spec::new(w as u16, h as u16);
for p in spec.palette.iter_mut() {
*p = rng.below(64) as u8;
}
let mut palette = spec.palette;
let mut prev = vec![0u8; w * h];
let mut blocks = Vec::new();
let mut pictures = Vec::new();
let mut notes = Vec::new();
for n in 0..frames {
let mut cur = prev.clone();
let rect = if n == 0 {
for p in cur.iter_mut() {
*p = rng.next_u64() as u8;
}
mutate(&mut rng, &mut cur, w, h);
[0, 0, w as u16 - 1, h as u16 - 1]
} else {
mutate(&mut rng, &mut cur, w, h)
};
let method = 1 + rng.below(3) as u8;
// the writer's method 3 needs two pixels a line; the first frame has no picture before
// it to keep pixels from, and ffmpeg refuses methods 1 and 3 there
let method = match method {
_ if n == 0 => 2,
3 if rect[0] == rect[2] => 1,
m => m,
};
let mut body = match method {
2 => (rect[1]..=rect[3]).flat_map(|y| cur[usize::from(y) * w..][usize::from(rect[0])..=usize::from(rect[2])].to_vec()).collect(),
_ => delta_lines(&prev, &cur, w, rect, method == 3, &mut rng),
};
// ffmpeg refuses LZ packing of a body of a byte or two, which no encoder would pack
let packing = if body.len() < 16 { 0 } else { rng.below(3) };
if packing > 0 {
body = lz_pack(&body, packing == 2, &mut rng);
}
let new_palette = rng.below(4) == 0;
let mut data = Vec::new();
if new_palette {
for p in palette.iter_mut() {
*p = rng.below(64) as u8;
}
data = palette_chunk(&palette);
}
data.push(method | if packing > 0 { 0x80 } else { 0 });
data.extend_from_slice(&body);
notes.push(format!("method {method}, packing {packing}, new palette {new_palette}, rect {rect:?}, body {body:02x?}"));
blocks.push(vec![Frame::video(rect, new_palette, data)]);
pictures.push((cur.clone(), palette));
prev = cur;
}
Movie { bytes: build(&spec, &blocks), width: w, pictures, notes }
}
/// The pictures of a file as the decoder gives them: indices and RGB, one for each block.
fn decode_all(bytes: &[u8]) -> Vec<(Vec<u8>, Vec<u8>)> {
let file = open(bytes).unwrap();
let mut decoder = Decoder::new(file.header_bytes()).unwrap();
let mut out = Vec::new();
for (i, frame) in file.frames.iter().enumerate() {
let FrameKind::Video { new_palette, .. } = frame.kind else { continue };
let data = file.read_frame(bytes, i).unwrap();
match file.picture_rect(i) {
Some(rect) => decoder.decode(rect.into(), new_palette, &data).unwrap(),
None if new_palette => decoder.decode_palette(&data).unwrap(),
None => {}
}
out.push((decoder.indices().to_vec(), decoder.rgb24()));
}
out
}
fn rgb(indices: &[u8], palette: &[u8; 768]) -> Vec<u8> {
indices.iter().flat_map(|&i| palette[usize::from(i) * 3..][..3].iter().map(|&v| v << 2 | v >> 4)).collect()
}
/// (seed, width, height, frames): small pictures, one wider than the longest run (128) and one
/// larger than the LZ window (4096).
const MOVIES: [(u64, usize, usize, usize); 5] = [(1, 40, 30, 40), (2, 300, 5, 30), (3, 1, 1, 6), (4, 7, 64, 30), (5, 96, 80, 12)];
/// Each picture converts into a `VideoFrame` of R, G, B planes holding the colours the decoder
/// gives as RGB.
#[test]
fn pictures_convert_to_rgb_video_frames() {
use craft_video::frame::{ColorFamily, Samples, VideoFrame};
for (seed, w, h, frames) in MOVIES {
let m = movie(seed, w, h, frames);
let file = open(&m.bytes).unwrap();
let mut decoder = Decoder::new(file.header_bytes()).unwrap();
for (i, frame) in file.frames.iter().enumerate() {
let FrameKind::Video { new_palette, .. } = frame.kind else { continue };
let data = file.read_frame(&m.bytes, i).unwrap();
match file.picture_rect(i) {
Some(rect) => decoder.decode(rect.into(), new_palette, &data).unwrap(),
None if new_palette => decoder.decode_palette(&data).unwrap(),
None => {}
}
let f = VideoFrame::try_from(&decoder).unwrap();
assert_eq!((f.width(), f.height(), f.family(), f.bit_depth()), (w as u32, h as u32, ColorFamily::Rgb, 8));
assert_eq!(f.color.matrix, 0);
let plane = |p: usize| match f.plane(p).map(|p| p.samples()) {
Some(Samples::U8(s)) => s.clone(),
other => panic!("plane {p}: {other:?}"),
};
let (r, g, b) = (plane(0), plane(1), plane(2));
let interleaved: Vec<u8> = (0..w * h).flat_map(|i| [r[i], g[i], b[i]]).collect();
assert!(interleaved == decoder.rgb24(), "movie {seed}: frame {i}");
}
}
}
#[test]
fn decodes_the_pictures_that_were_packed() {
for (seed, w, h, frames) in MOVIES {
let m = movie(seed, w, h, frames);
let got = decode_all(&m.bytes);
assert_eq!(got.len(), frames);
for (n, ((indices, rgb24), (want, palette))) in got.iter().zip(&m.pictures).enumerate() {
assert!(indices == want, "movie {seed}: indices of frame {n}");
assert!(*rgb24 == rgb(want, palette), "movie {seed}: colours of frame {n}");
}
}
}
#[test]
fn matches_ffmpeg() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg_or_skip("vmd video oracle") else { return };
let dir = craft_media_testkit::private_dir("vmd-video");
for (seed, w, h, frames) in MOVIES {
let m = movie(seed, w, h, frames);
let path = dir.join(format!("movie{seed}.vmd"));
let run = |bytes: &[u8]| {
std::fs::write(&path, bytes).unwrap();
Command::new(&ffmpeg)
.args(["-v", "error", "-i"])
.arg(&path)
.args(["-an", "-fps_mode", "passthrough", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"])
.output()
.unwrap()
};
let out = run(&m.bytes);
if !out.status.success() || !out.stderr.is_empty() {
// the same movie cut after each frame in turn shows which frame ffmpeg refuses
let bad = (1..=frames).find(|&k| !run(&movie(seed, w, h, k).bytes).stderr.is_empty()).map_or(0, |k| k - 1);
panic!("movie {seed}: ffmpeg refuses frame {bad} ({}): {}", m.notes[bad], String::from_utf8_lossy(&out.stderr));
}
let theirs: Vec<&[u8]> = out.stdout.chunks(m.width * h * 3).collect();
let ours = decode_all(&m.bytes);
assert_eq!(theirs.len(), ours.len(), "movie {seed}: frame count");
for (n, (theirs, (_, ours))) in theirs.iter().zip(&ours).enumerate() {
assert!(*theirs == ours.as_slice(), "movie {seed}: frame {n} differs from ffmpeg");
}
}
std::fs::remove_dir_all(&dir).unwrap();
}
/// A 16x2 decoder whose picture is all 0x40.
fn flat() -> Decoder {
let header = build(&Spec::new(16, 2), &[]);
let mut d = Decoder::new(&header).unwrap();
let mut key = vec![2u8];
key.extend([0x40; 32]);
d.decode(FULL, false, &key).unwrap();
d
}
const FULL: Rect = Rect { left: 0, top: 0, right: 15, bottom: 1 };
/// Method 3 lines as ffmpeg was seen to decode them: the second line is skipped whole.
#[test]
fn run_length_lines() {
let cases: [(&[u8], [u8; 16]); 5] = [
// 16 bytes that do not begin with 0xFF are copied
(&[0x8F, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16], [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
// 0xFF: a pair three times, two pairs as they are, a pair three times
(
&[0x8F, 0xFF, 3, 0xA0, 0xB0, 0x82, 1, 2, 3, 4, 3, 0xC0, 0xD0],
[0xA0, 0xB0, 0xA0, 0xB0, 0xA0, 0xB0, 1, 2, 3, 4, 0xC0, 0xD0, 0xC0, 0xD0, 0xC0, 0xD0],
),
// an odd run starts with a single byte; the last pixel is a plain run of one
(
&[0x8E, 0xFF, 0xE0, 7, 0xA0, 0xB0, 0x80, 0xE4],
[0xE0, 0xA0, 0xB0, 0xA0, 0xB0, 0xA0, 0xB0, 0xA0, 0xB0, 0xA0, 0xB0, 0xA0, 0xB0, 0xA0, 0xB0, 0xE4],
),
// skip 8, then run-length
(&[7, 0x87, 0xFF, 4, 0x50, 0x60], [0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x50, 0x60, 0x50, 0x60, 0x50, 0x60, 0x50, 0x60]),
// skip 8, then plain
(&[7, 0x87, 1, 2, 3, 4, 5, 6, 7, 8], [0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 1, 2, 3, 4, 5, 6, 7, 8]),
];
for (line, want) in cases {
let mut d = flat();
let mut data = vec![3u8];
data.extend_from_slice(line);
data.push(15);
d.decode(FULL, false, &data).unwrap();
assert_eq!(d.indices()[..16], want, "{line:x?}");
assert_eq!(d.indices()[16..], [0x40; 16], "{line:x?}");
}
// method 1 has no run-length coding: 0xFF is a pixel
let mut d = flat();
d.decode(FULL, false, &[1, 0x81, 0xFF, 9, 13, 15]).unwrap();
assert_eq!(d.indices()[..3], [0xFF, 9, 0x40]);
}
#[test]
fn lz_chains() {
let unpack = |packed: &[u8]| {
let mut d = flat();
let mut data = vec![0x82u8];
data.extend_from_slice(packed);
d.decode(FULL, false, &data).map(|()| d.indices().to_vec())
};
// three literals, a chain that repeats them, then chains into the window's fill of 0x20:
// 5 bytes, 18 bytes (the longest short chain), 3 bytes
let short = [32, 0, 0, 0, 0b0000_0111, 0x90, 0xA0, 0xB0, 0xEE, 0xF0, 0x00, 0x02, 0x00, 0x0F, 0x00, 0x00];
let mut want = vec![0x90, 0xA0, 0xB0, 0x90, 0xA0, 0xB0];
want.resize(32, 0x20);
assert_eq!(unpack(&short).unwrap(), want);
// with the marker the window starts at 0x111, and a length of 18 takes one more byte: 18 + 5
let long = [32, 0, 0, 0, 0x34, 0x12, 0x78, 0x56, 0b0000_0111, 0x90, 0xA0, 0xB0, 0x11, 0x10, 0x00, 0x0F, 5];
// 29 of the 32 bytes arrive (3 literals, 3 and 23 chained): the first row is painted, the
// second, three bytes short, is not
assert_eq!(unpack(&long), Err(Error::Invalid("the frame data ends early")));
let mut d = flat();
let mut data = vec![0x82u8];
data.extend_from_slice(&long);
let _ = d.decode(FULL, false, &data);
let mut want = vec![0x90, 0xA0, 0xB0, 0x90, 0xA0, 0xB0];
want.resize(16, 0x20);
want.extend([0x40; 16]);
assert_eq!(d.indices(), want);
// a chain that overlaps what it writes repeats it: one literal, then 18 copies of it
let overlap = [32, 0, 0, 0, 0b0000_0001, 7, 0xEE, 0xFF, 0xEE, 0xFA];
assert_eq!(unpack(&overlap).unwrap(), [7; 32]);
// a tag of 0xFF with more than 8 bytes left is 8 raw bytes
let mut raw = vec![32, 0, 0, 0];
for chunk in (0u8..32).collect::<Vec<_>>().chunks(8) {
raw.push(0xFF);
raw.extend_from_slice(chunk);
}
assert_eq!(unpack(&raw).unwrap(), (0u8..32).collect::<Vec<_>>());
// with 8 bytes or fewer left, a tag of 0xFF is eight literal bits, of which only the bytes
// left are read: 13 bytes are 8 raw and 5 literals
let mut d = flat();
let tail = [0x82, 13, 0, 0, 0, 0xFF, 1, 2, 3, 4, 5, 6, 7, 8, 0xFF, 9, 10, 11, 12, 13];
d.decode(Rect { right: 12, bottom: 0, ..FULL }, false, &tail).unwrap();
assert_eq!(d.indices()[..14], [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 0x40]);
}
/// A frame that says it unpacks to the whole unpack buffer costs no more than its picture: the
/// same 8 packed bytes repeated would otherwise be unpacked to megabytes for every frame.
#[test]
fn lz_unpacking_stops_at_what_a_picture_can_use() {
let mut spec = Spec::new(16, 2);
spec.unpack = u32::MAX;
let mut d = Decoder::new(&build(&spec, &[])).unwrap();
// 4 GiB declared; long chains of 273 bytes from the window's fill, far more than 32 pixels
let mut data = vec![0x82, 0xFF, 0xFF, 0xFF, 0xFF, 0x34, 0x12, 0x78, 0x56];
for _ in 0..40_000 {
data.push(0);
data.extend([0x00, 0x0F, 0xFF].repeat(8));
}
let start = std::time::Instant::now();
for _ in 0..200 {
d.decode(FULL, false, &data).unwrap();
}
assert_eq!(d.indices(), [0x20; 32]);
// 87 MB of output for each frame without the stop: seconds, not milliseconds
assert!(start.elapsed() < std::time::Duration::from_secs(2), "{:?}", start.elapsed());
// the stop leaves room for the largest body a frame needs: every two pixels as a run-length
// run of their own, five bytes for two pixels
let (w, h) = (128, 32);
let mut d = Decoder::new(&build(&Spec::new(w, h), &[])).unwrap();
let body: Vec<u8> = (0..w * h / 2).flat_map(|i| [0x81, 0xFF, 0x81, i as u8, (i >> 8) as u8]).collect();
// LZ packing with literals only: tags of 0xFF, eight bytes each
let mut data = vec![0x83];
data.extend((body.len() as u32).to_le_bytes());
for chunk in body.chunks(8) {
data.push(0xFF);
data.extend_from_slice(chunk);
}
d.decode(Rect { left: 0, top: 0, right: w - 1, bottom: h - 1 }, false, &data).unwrap();
let want: Vec<u8> = (0..w * h / 2).flat_map(|i| [i as u8, (i >> 8) as u8]).collect();
assert!(d.indices() == want);
}
#[test]
fn palette_changes() {
let mut d = flat();
assert_eq!(d.palette()[0x40], [0x41; 3]);
assert_eq!(d.palette()[255], [255; 3]);
let mut palette = [0u8; 768];
palette[0x40 * 3..][..3].copy_from_slice(&[63, 1, 32]);
// a palette and nothing else
d.decode(FULL, true, &palette_chunk(&palette)).unwrap();
assert_eq!(d.palette()[0x40], [255, 4, 130]);
assert_eq!(d.rgb24()[..3], [255, 4, 130]);
assert_eq!(d.rgba8()[..4], [255, 4, 130, 255]);
assert_eq!(d.indices(), [0x40; 32]);
// every entry is replaced, whatever the first-index and count bytes say
let mut chunk = palette_chunk(&[63; 768]);
chunk[..2].copy_from_slice(&[4, 2]);
d.decode(FULL, true, &chunk).unwrap();
assert_eq!((d.palette()[0], d.palette()[255]), ([255; 3], [255; 3]));
// components are 6 bits: higher bits are dropped
d.decode(FULL, true, &palette_chunk(&[0x41; 768])).unwrap();
assert_eq!(d.palette()[7], [4; 3]);
assert_eq!(d.decode(FULL, true, &[0; 769]), Err(Error::Invalid("the palette is cut short")));
}
/// A frame whose rectangle is empty paints nothing, but its palette counts: the pictures after
/// it use it. ffmpeg was seen to do the same with such a frame.
#[test]
fn palette_of_a_frame_without_a_rectangle() {
let spec = Spec::new(4, 2);
let picture = |fill: u8| [vec![2], vec![fill; 8]].concat();
let mut palette = [0u8; 768];
palette[5 * 3..][..3].copy_from_slice(&[63, 0, 63]);
palette[6 * 3..][..3].copy_from_slice(&[0, 63, 0]);
let bytes = build(
&spec,
&[
vec![Frame::video([0, 0, 3, 1], false, picture(5))],
// right is one less than left: no pixels, a palette and a picture that is not painted
vec![Frame::video([1, 1, 0, 1], true, [palette_chunk(&palette), picture(6)].concat())],
vec![Frame::video([0, 0, 1, 0], false, picture(6)[..3].to_vec())],
],
);
assert_eq!(open(&bytes).unwrap().picture_rect(1), None);
let pictures = decode_all(&bytes);
// index 5 is dark grey in the header's palette
assert_eq!(pictures[0], (vec![5; 8], [4u8; 24].to_vec()));
assert_eq!(pictures[1], (vec![5; 8], [255, 0, 255].repeat(8)));
assert_eq!(pictures[2].0, [6, 6, 5, 5, 5, 5, 5, 5]);
assert_eq!(pictures[2].1[..9], [0, 255, 0, 0, 255, 0, 255, 0, 255]);
let mut d = flat();
d.decode_palette(&[]).unwrap();
assert_eq!(d.palette()[0x40], [0x41; 3]);
assert_eq!(d.decode_palette(&[0; 769]), Err(Error::Invalid("the palette is cut short")));
}
#[test]
fn partial_updates_and_empty_frames() {
let mut d = flat();
d.decode(Rect { left: 4, top: 1, right: 7, bottom: 1 }, false, &[2, 1, 2, 3, 4]).unwrap();
assert_eq!(d.indices()[..20], [[0x40; 4]; 5].concat());
assert_eq!(d.indices()[20..24], [1, 2, 3, 4]);
let before = d.indices().to_vec();
d.decode(FULL, false, &[]).unwrap();
assert_eq!(d.indices(), before);
assert_eq!((d.width(), d.height()), (16, 2));
}
#[test]
fn bad_frames_are_errors() {
let mut d = flat();
for rect in [Rect { right: 16, ..FULL }, Rect { bottom: 2, ..FULL }, Rect { left: 9, right: 8, ..FULL }, Rect { top: 1, bottom: 0, ..FULL }] {
assert_eq!(d.decode(rect, false, &[2; 40]), Err(Error::Invalid("the frame lies outside the picture")), "{rect:?}");
}
assert_eq!(d.decode(FULL, false, &[2; 32]), Err(Error::Invalid("the frame data ends early")));
assert_eq!(d.decode(FULL, false, &[1, 0x8F]), Err(Error::Invalid("the frame data ends early")));
// 9 + 8 pixels in a line of 16
assert_eq!(d.decode(FULL, false, &[1, 8, 7]), Err(Error::Invalid("a run crosses the end of its line")));
assert_eq!(d.decode(FULL, false, &[3, 0x8F, 0xFF, 9, 1, 2]), Err(Error::Invalid("run-length data overruns its run")));
assert_eq!(d.decode(FULL, false, &[4, 0, 0]), Err(Error::Unsupported("unknown rendering method")));
// the header allows 1 MiB of LZ output
assert_eq!(d.decode(FULL, false, &[0x82, 0, 0, 0x10, 0x01]), Err(Error::Invalid("an LZ-packed frame is larger than the unpack buffer")));
}
#[test]
fn bad_headers_are_errors() {
let good = build(&Spec::new(16, 2), &[]);
let with = |patch: &dyn Fn(&mut Vec<u8>)| {
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[12..14].fill(0)), Some(Error::Invalid("the picture has no pixels")));
assert_eq!(with(&|h| h[4] = 5), Some(Error::Unsupported("24-bit pictures")));
assert_eq!(with(&|h| h[4] = 13), Some(Error::Unsupported("16-bit pictures")));
assert_eq!(with(&|h| h[4] = 7), Some(Error::Unsupported("Indeo 3 video")));
assert_eq!(with(&|h| h[24..28].copy_from_slice(b"IV32")), Some(Error::Unsupported("Indeo 3 video")));
// 65 535 x 65 535 is refused before anything is allocated
assert_eq!(with(&|h| h[12..16].fill(0xFF)), Some(Error::TooLarge(65535, 65535)));
}
#[test]
fn hostile_input_never_panics() {
for (seed, w, h, frames) in [(11, 24, 10, 12), (12, 140, 3, 8)] {
let m = movie(seed, w, h, frames);
craft_media_testkit::hostile::hammer(&format!("vmd video seed {seed}"), &m.bytes, 20_000, |d| {
let Ok(file) = open(d) else { return };
let Ok(mut decoder) = Decoder::new(file.header_bytes()) else { return };
for (i, frame) in file.frames.iter().enumerate() {
let FrameKind::Video { new_palette, left, top, right, bottom } = frame.kind else { continue };
let Ok(data) = file.read_frame(d, i) else { continue };
// the rectangle as stored too: the decoder must refuse what does not fit
let _ = decoder.decode(Rect { left, top, right, bottom }, new_palette, &data);
if let Some(rect) = file.picture_rect(i) {
let _ = decoder.decode(rect.into(), new_palette, &data);
}
let _ = decoder.decode_palette(&data);
}
let _ = decoder.rgb24();
});
}
}
/// Real files, for whoever has some: every `.vmd` in the directory `CRAFT_MEDIA_VMD_SAMPLES`
/// names must decode to the pictures 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 video 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 pictures = 0u64;
for path in &paths {
let name = path.display();
let source = std::fs::File::open(path).unwrap();
let file = open(&source).unwrap();
let mut decoder = Decoder::new(file.header_bytes()).unwrap();
let mut child = Command::new(&ffmpeg)
.args(["-v", "quiet", "-i"])
.arg(path)
// passthrough: one picture a video frame, none repeated to fill blocks that have no video
.args(["-an", "-fps_mode", "passthrough", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"])
.stdout(Stdio::piped())
.stderr(Stdio::null())
.spawn()
.unwrap();
let mut theirs_out = child.stdout.take().unwrap();
let mut theirs = vec![0u8; decoder.width() * decoder.height() * 3];
for (i, frame) in file.frames.iter().enumerate() {
let FrameKind::Video { new_palette, .. } = frame.kind else { continue };
// ffmpeg gives no picture for a frame without data
if frame.size == 0 {
continue;
}
let data = file.read_frame(&source, i).unwrap();
// as the documented loop does: a frame without a rectangle may still bring a palette
match file.picture_rect(i) {
Some(rect) => decoder.decode(rect.into(), new_palette, &data),
None if new_palette => decoder.decode_palette(&data),
None => panic!("{name}: frame {i} lies outside the picture"),
}
.unwrap_or_else(|e| panic!("{name}: frame {i}: {e}"));
theirs_out.read_exact(&mut theirs).unwrap_or_else(|e| panic!("{name}: ffmpeg has no picture for frame {i}: {e}"));
let ours = decoder.rgb24();
if theirs != ours {
let wrong: Vec<usize> = (0..ours.len() / 3).filter(|&p| ours[p * 3..][..3] != theirs[p * 3..][..3]).collect();
let (w, first) = (decoder.width(), wrong[0]);
panic!(
"{name}: frame {i} (block {}) differs from ffmpeg in {} pixels, first at ({}, {}); {:?}, data starts {:02x?}",
frame.block,
wrong.len(),
first % w,
first / w,
frame.kind,
&data[..data.len().min(8)]
);
}
pictures += 1;
}
assert_eq!(theirs_out.read(&mut theirs).unwrap(), 0, "{name}: ffmpeg has more pictures");
// pictures that match but an ffmpeg that failed are no comparison
let status = child.wait().unwrap();
assert!(status.success(), "{name}: ffmpeg exited with {status}");
}
println!("{} files, {pictures} pictures match ffmpeg", paths.len());
}
+45
View File
@@ -411,6 +411,51 @@ mod tests {
assert_eq!(root.range(), 0..text.len());
}
#[test]
fn traversal_identity_and_accessors_preserve_element_and_text_semantics() {
let source = "<?before value?><r xmlns='urn:r' xmlns:p='urn:p' a='plain' p:a='qualified' xml:lang='en'>first<!--gap--><?inside value?>second<empty/><p:child>last</p:child></r>";
let doc = Document::parse(source).unwrap();
let other = Document::parse(source).unwrap();
let root = doc.root_element();
assert!(root != other.root_element());
assert!(std::ptr::eq(root.document(), &doc));
assert!(root.is_element());
assert!(!root.is_text());
assert_eq!(root.tag_name().name(), "r");
assert_eq!(root.lookup_prefix("urn:p"), Some("p"));
assert_eq!(root.lookup_prefix(XML_NS), Some("xml"));
assert_eq!(root.lookup_prefix("absent"), None);
assert_eq!(root.lookup_namespace_uri(Some("xml")), Some(XML_NS));
assert_eq!(root.lookup_namespace_uri(Some("xmlns")), Some(XMLNS_NS));
assert_eq!(root.lookup_namespace_uri(Some("absent")), None);
let attrs: Vec<_> = root.attributes().map(|a| (a.namespace(), a.name(), a.value())).collect();
assert_eq!(attrs, vec![(None, "a", "plain"), (Some("urn:p"), "a", "qualified"), (Some(XML_NS), "lang", "en")]);
let namespaces: Vec<_> = root.namespaces().map(|n| (n.name(), n.uri())).collect();
assert!(namespaces.contains(&(None, "urn:r")));
assert!(namespaces.contains(&(Some("p"), "urn:p")));
let all: Vec<_> = doc.descendants().collect();
assert_eq!(all.len(), 5);
assert!(all.iter().zip(root.descendants()).all(|(a, b)| *a == b));
assert_eq!(all.iter().filter(|n| n.is_element()).map(|n| n.tag_name().name()).collect::<Vec<_>>(), vec!["r", "empty", "child"]);
let text = root.children().next().unwrap();
assert!(text.is_text());
assert!(!text.is_element());
assert_eq!(text.text(), Some("firstsecond"));
assert_eq!(text.tag_name().name(), "");
assert_eq!(text.tag_name().namespace(), None);
assert_eq!(text.attribute("a"), None);
assert_eq!(text.attributes().len(), 0);
assert_eq!(text.namespaces().len(), 0);
assert_eq!(text.lookup_prefix("urn:p"), None);
assert_eq!(text.lookup_namespace_uri(Some("p")), None);
assert_eq!(text.range(), 0..0);
assert_eq!(text.children().count(), 0);
assert_eq!(text.descendants().count(), 1);
assert!(doc.get_node(NodeId(usize::MAX)).is_none());
assert_eq!(root.children().nth(1).unwrap().text(), None);
assert_eq!(Document::parse("<r><child/>tail</r>").unwrap().root_element().text(), None);
}
#[test]
fn inherited_namespace_declarations_have_an_aggregate_budget() {
use std::fmt::Write;