feat(media,video,audio): add Sierra VMD demuxer and decoders

Sierra VMD (Video and Music Data) is the video format of Sierra and
Coktel Vision games of the 1990s. Written clean-room from the public
format description at https://wiki.multimedia.cx/index.php/VMD, with
ffmpeg as a black-box oracle.

- craft-media: `vmd` feature, a demuxer for the 816-byte header and the
  table of contents; `Container::Vmd`, `CodecId::VmdVideo` and
  `CodecId::VmdAudio`.
- craft-video: `vmd` feature, a decoder for 8-bit paletted pictures
  (rendering methods 1 to 3, LZ packing, palette changes).
- craft-audio: `vmd-decode` feature, a decoder for 8-bit PCM and 16-bit
  DPCM sound, mono and stereo.
- craft-media-testkit: a VMD fixture writer, since ffmpeg reads VMD but
  cannot write it.

Tests compare the decoders with ffmpeg on generated files, and on real
files when CRAFT_MEDIA_VMD_SAMPLES names a directory of them. 16-bit,
24-bit and Indeo 3 pictures, IMA ADPCM sound and the later header
revisions are not decoded.
This commit is contained in:
alehel committed 2026-11-15 01:50:28 +01:00
1 parent f2cd524f74
commit 6ac5f83bb2
20 files changed
+2329 -12

No files matched your search

+1 -1
View File
@@ -254,7 +254,7 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit
- [`craft-math`](crates/math/README.md): equations as one tree (the Office Math object model) with its syntaxes, read and written: OMML, presentation MathML, LaTeX math and the UnicodeMath linear format.
- [`craft-media`](crates/media/README.md): bit-level I/O (`bitstream`), clean-room MP4/MOV
(`isobmff`), Matroska/WebM (`matroska`) and MXF (`mxf`) demuxers and muxers, Ogg (`ogg`), AVI (`avi`) and
MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and
MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, a Sierra VMD (`vmd`) demuxer, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and
video codecs will go in a separate crate.
- [`craft-lottie`](crates/lottie/README.md): Lottie (Bodymovin) JSON: the document model of
lottie-spec 1.0 (animation, assets, layers by type, shape items, masks, effects, text, markers)
+8
View File
@@ -49,6 +49,8 @@ ac3-encode = ["craft-media/bitstream"]
eac3-encode = ["craft-media/bitstream"]
# MPEG-1/2 Layer III (MP3) encoder (`mp3`).
mp3-encode = ["craft-media/bitstream"]
# Sierra VMD sound decoder (`vmd::Decoder`): 8-bit PCM and 16-bit DPCM.
vmd-decode = []
# Multi-resolution waveform overviews (`peaks`).
peaks = []
# Encode AAC channels in parallel (with `aac-encode`).
@@ -67,6 +69,8 @@ symphonia = { version = "0.6.1", optional = true, default-features = false, feat
[dev-dependencies]
craft-media-testkit = { workspace = true }
# The VMD demuxer, for the VMD sound decoder's tests.
craft-media = { workspace = true, features = ["vmd"] }
proptest = { workspace = true }
serde_json = { workspace = true }
@@ -74,6 +78,10 @@ serde_json = { workspace = true }
name = "audio"
required-features = ["decode", "lossless-encode", "peaks"]
[[test]]
name = "vmd"
required-features = ["vmd-decode"]
[[test]]
name = "codecs"
required-features = ["decode", "encode"]
+1
View File
@@ -42,6 +42,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` |
| `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` |
| `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` |
| `vmd-decode` | `vmd::Decoder`: Sierra VMD sound (8-bit PCM and 16-bit DPCM), frame by frame from `craft_media::vmd` | none |
| `peaks` | `peaks::Peaks` | none |
| `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` |
| `serde` | `Serialize`/`Deserialize` on the shared types | `serde` |
+14 -1
View File
@@ -27,7 +27,8 @@
//! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`,
//! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and
//! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`]
//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder).
//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder), [`vmd`]
//! (`vmd-decode`: Sierra VMD sound).
//!
//! The shared types below build with no features.
@@ -53,6 +54,8 @@ pub mod peaks;
mod read;
#[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))]
mod track;
#[cfg(feature = "vmd-decode")]
pub mod vmd;
#[cfg(any(feature = "decode-native", feature = "pcm-encode"))]
mod wav;
#[cfg(any(
@@ -224,6 +227,16 @@ impl From<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 {
+178
View File
@@ -0,0 +1,178 @@
//! Sierra VMD sound decoder (feature `vmd-decode`): the 8-bit PCM and 16-bit DPCM sound of VMD
//! (Video and Music Data) files, as in Sierra's and Coktel Vision's 1990s games.
//!
//! Clean-room, from the public format description at <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, several. 8-bit samples are widened to 16 bits. Blocks do not depend
//! on each other, so decoding can start at any frame.
//!
//! Not decoded: IMA ADPCM sound (audio flag 0x10) and the external codecs of later Coktel Vision
//! files ([`Error::Unsupported`]).
//!
//! Input is treated as hostile: a frame yields at most 32 blocks (the width of the silence
//! mask) of at most 65 535 samples a channel, and a block is decoded only if all of it is there. No `unsafe`, no panics.
#![warn(missing_docs)]
/// Bytes of the VMD file header a [`Decoder`] is made from.
pub const HEADER_LEN: usize = 816;
/// Errors from decoding VMD sound.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// The header or a frame is not valid.
#[error("invalid VMD sound: {0}")]
Invalid(&'static str),
/// Valid, but not something this decoder handles.
#[error("unsupported VMD sound: {0}")]
Unsupported(&'static str),
}
/// The steps of the 16-bit coding: a code's low seven bits pick one, its top bit the sign.
const STEPS: [u16; 128] = [
0, 8, 16, 32, 48, 64, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240, 256, 272, 288, 304, 320, 336, 352, 368, 384, 400, 416, 432, 448, 464,
480, 496, 512, 520, 528, 536, 544, 552, 560, 568, 576, 584, 592, 600, 608, 616, 624, 632, 640, 648, 656, 664, 672, 680, 688, 696, 704, 712, 720,
728, 736, 744, 752, 760, 768, 776, 784, 792, 800, 808, 816, 824, 832, 840, 848, 856, 864, 872, 880, 888, 896, 904, 912, 920, 928, 936, 944, 952,
960, 968, 976, 984, 992, 1000, 1008, 1016, 1024, 1088, 1152, 1216, 1280, 1344, 1408, 1472, 1536, 1600, 1664, 1728, 1792, 1856, 1920, 1984, 2048,
2304, 2560, 2816, 3072, 3328, 3584, 3840, 4096, 5120, 6144, 7168, 8192, 12288, 16384,
];
/// A VMD sound decoder.
#[derive(Clone, Debug)]
pub struct Decoder {
sample_rate: u32,
channels: usize,
sixteen_bit: bool,
/// Samples of one block, all channels counted.
block_samples: usize,
}
impl Decoder {
/// A decoder for the file whose header is `header` (its first 816 bytes; more are ignored).
pub fn new(header: &[u8]) -> Result<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 {
return Err(Error::Invalid("the file has no sound"));
}
let flags = u16_at(810);
if flags & 0x10 != 0 {
return Err(Error::Unsupported("IMA ADPCM sound"));
}
let length = u16_at(806) as i16;
let frame_length = usize::from(length.unsigned_abs());
// old-style stereo counts both channels, new-style one
let (channels, block_samples) = match flags {
f if f & 0x8000 != 0 => (2, frame_length & !1),
f if f & 0x200 != 0 => (2, frame_length * 2),
_ => (1, frame_length),
};
Ok(Decoder { sample_rate: u32::from(u16_at(804)), channels, sixteen_bit: length < 0, block_samples })
}
/// Samples a second.
pub fn sample_rate(&self) -> u32 {
self.sample_rate
}
/// 1 or 2.
pub fn channels(&self) -> usize {
self.channels
}
/// Bits a sample in the file: 8 (PCM) or 16 (DPCM). The decoder returns `i16` for both.
pub fn bits(&self) -> u8 {
if self.sixteen_bit { 16 } else { 8 }
}
/// Samples of one block for each channel.
pub fn block_samples(&self) -> usize {
self.block_samples / self.channels
}
/// Bytes of one block of sound in a frame.
pub fn block_bytes(&self) -> usize {
if self.sixteen_bit { (self.block_samples + self.channels).min(self.block_samples * 2) } else { self.block_samples }
}
/// Decode one sound frame: `flags` is the frame's flag byte from its record, `data` the
/// frame data. Returns interleaved samples, [`Decoder::block_samples`] for each channel and
/// block.
///
/// - flags 1: one block of sound;
/// - flags 2: a 32-bit mask, then blocks of sound: the sound a player loads ahead at the
/// start of a file. From bit 0 up, a set bit is a block of silence and a clear bit the next
/// block of data, while there is one. ffmpeg plays the silent blocks first instead;
/// the order here is the description's;
/// - flags 3: one block of silence.
///
/// An empty frame gives no samples. A block cut short is an error.
pub fn decode(&self, flags: u8, data: &[u8]) -> Result<Vec<i16>, Error> {
let mut out = Vec::new();
match flags {
3 => out.resize(self.block_samples, 0),
_ if data.is_empty() => {}
1 => self.block(data, &mut out)?,
2 => {
let (mask, mut data) = data.split_first_chunk::<4>().ok_or(Error::Invalid("the silence mask is cut short"))?;
let mask = u32::from_le_bytes(*mask);
// bit by bit: a set bit is a silent block, a clear one takes the next block of data
// while there is one. The header's buffer count is not needed: game files hold
// one block fewer than it says.
for i in 0..32 {
if mask >> i & 1 == 1 {
out.resize(out.len() + self.block_samples, 0);
} else if !data.is_empty() && data.len() >= self.block_bytes() {
self.block(data, &mut out)?;
data = &data[self.block_bytes()..];
}
}
}
_ => return Err(Error::Unsupported("unknown sound frame flags")),
}
Ok(out)
}
/// Decode the block at the start of `data` onto `out`.
fn block(&self, data: &[u8], out: &mut Vec<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(())
}
}
+265
View File
@@ -0,0 +1,265 @@
//! VMD sound decoder tests. ffmpeg reads VMD but cannot write it, so the files come from the
//! test kit's VMD writer. The decoder must return the samples that were packed, and the same
//! samples as ffmpeg (skipped without ffmpeg).
use std::process::Command;
use craft_audio::vmd::{Decoder, Error};
use craft_media::vmd::{FrameKind, open};
use craft_media_testkit::hostile::Rng;
use craft_media_testkit::vmd::{Audio, Frame, Spec, build, dpcm_pack};
/// (frame length field, audio flags, channels, 16-bit): every layout the decoder handles.
const FORMATS: [(i16, u16, usize, bool); 6] =
[(50, 0, 1, false), (50, 0x200, 2, false), (50, 0x8000, 2, false), (-50, 0, 1, true), (-50, 0x200, 2, true), (-50, 0x8000, 2, true)];
fn spec(frame_length: i16, flags: u16) -> Spec {
let mut spec = Spec::new(4, 4);
spec.audio = Some(Audio { sample_rate: 22050, frame_length, buffers: 5, flags });
spec
}
fn decoder(frame_length: i16, flags: u16) -> Decoder {
Decoder::new(&build(&spec(frame_length, flags), &[])).unwrap()
}
/// One block of random sound: its bytes in the file and the samples it decodes to.
fn block(rng: &mut Rng, d: &Decoder) -> (Vec<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]);
// steps past 16 bits stop at the ends
let mut data = 30000i16.to_le_bytes().to_vec();
data.extend([0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]);
assert_eq!(decoder(-7, 0).decode(1, &data).unwrap(), [30000, 32767, 16383, -1, -16385, -32768, -32768]);
}
#[test]
fn eight_bit_and_silence() {
let d = decoder(4, 0);
assert_eq!(d.decode(1, &[0x80, 0x00, 0xFF, 0x70]).unwrap(), [0, -32768, 0x7F00, -0x1000]);
assert_eq!(d.decode(3, &[]).unwrap(), [0; 4]);
assert_eq!(d.decode(1, &[]).unwrap(), [0i16; 0]);
assert_eq!(decoder(4, 0x200).decode(3, &[]).unwrap(), [0; 8]);
assert_eq!(decoder(-4, 0x8000).decode(3, &[]).unwrap(), [0; 4]);
}
#[test]
fn silence_mask_runs_bit_by_bit() {
let d = decoder(2, 0);
let frame = |mask: u32, data: &[u8]| d.decode(2, &[&mask.to_le_bytes()[..], data].concat());
let (a, b) = ([0x90, 0x91], [0xA0, 0xA1]);
let (sa, sb) = ([0x1000, 0x1100], [0x2000, 0x2100]);
assert_eq!(frame(0, &[a, b].concat()).unwrap(), [sa, sb].concat());
// silent, sound, silent, sound
assert_eq!(frame(0b0101, &[a, b].concat()).unwrap(), [[0, 0], sa, [0, 0], sb].concat());
// game files set a bit for every block when all are silent
assert_eq!(frame(0b0111, &[]).unwrap(), [0; 6]);
// a trailing part of a block is left out
assert_eq!(frame(0, &[0x90, 0x91, 0xA0]).unwrap(), sa);
assert_eq!(d.decode(2, &[0, 0, 0]), Err(Error::Invalid("the silence mask is cut short")));
}
#[test]
fn bad_input_is_an_error() {
let d = decoder(-20, 0);
assert_eq!(d.decode(1, &[0; 20]), Err(Error::Invalid("a block of sound is cut short")));
assert_eq!(d.decode(4, &[0; 21]), Err(Error::Unsupported("unknown sound frame flags")));
let good = build(&spec(20, 0), &[]);
let with = |patch: &dyn Fn(&mut Vec<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[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");
}
+2
View File
@@ -13,11 +13,13 @@
//!
//! [`hostile::hammer`] runs a parser over truncations and mutations of a valid input and fails on
//! a panic or a slow run; `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations.
//! [`vmd`] writes Sierra VMD fixtures, which ffmpeg can read but not write.
//!
//! Failing loudly is what a test helper is for: a wrong `CRAFT_MEDIA_*` setting or an unwritable
//! fixture directory panics, which fails the test that asked.
pub mod hostile;
pub mod vmd;
use std::path::{Path, PathBuf};
use std::process::Command;
+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"]
+50 -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"] }
@@ -801,14 +802,57 @@ 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(frame), 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.
- `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(frame)` places a video frame's update in the picture (frame coordinates are
screen coordinates when the picture does not sit at the screen origin).
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)`.
@@ -820,7 +864,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.
@@ -828,7 +872,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.
+12
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;
+4 -1
View File
@@ -12,10 +12,11 @@
//! - `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.
//!
//! `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")]
@@ -34,6 +35,8 @@ pub mod mxf;
#[cfg(feature = "ogg")]
pub mod ogg;
pub mod source;
#[cfg(feature = "vmd")]
pub mod vmd;
pub use id::{CodecId, CodecParams, Container, PcmFormat, xiph_lace};
pub use source::{ByteSource, ReadSeekSource};
+405
View File
@@ -0,0 +1,405 @@
//! 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.
//!
//! [`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: how many blocks a frame with a silence mask covers.
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).
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);
let audio = (flags & 0x1000 != 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 belongs to: its picture period.
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>,
}
/// 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);
}
}
Ok(VmdFile { header, frames, raw_header: raw.to_vec() })
}
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 = vec![0u8; f.size as usize];
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.sample_rate > 0 && a.block_samples() > 0 => (u32::from(a.sample_rate), a.block_samples()),
_ => (10, 1),
}
}
/// Where a video frame's update lies in 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 in files whose picture does not sit at the
/// screen origin, and the description does not say how to tell. This follows what ffmpeg
/// does with such files: coordinates that still fit the picture once the header's origin is
/// taken off are screen coordinates, any others are picture coordinates.
pub fn picture_rect(&self, frame: &Frame) -> Option<(u16, u16, u16, u16)> {
let FrameKind::Video { left, top, right, bottom, .. } = frame.kind else { return None };
let h = &self.header;
if right < left || bottom < top {
return None;
}
let on_screen = left
.checked_sub(h.left)
.zip(top.checked_sub(h.top))
.zip(right.checked_sub(h.left).zip(bottom.checked_sub(h.top)))
.filter(|&(_, (r, b))| r < h.width && b < h.height);
match on_screen {
Some(((l, t), (r, b))) => Some((l, t, r, b)),
None => (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)))
}
}
+161
View File
@@ -0,0 +1,161 @@
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);
}
#[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);
}
#[test]
fn picture_rect_takes_off_the_screen_origin() {
let mut spec = Spec::new(16, 8);
(spec.left, spec.top) = (4, 2);
let frame = |rect| F::video(rect, false, vec![]);
let d = build(
&spec,
&[vec![frame([4, 2, 19, 9])], vec![frame([2, 0, 5, 0])], vec![frame([6, 2, 9, 2])], vec![frame([0, 0, 16, 7])], vec![frame([5, 0, 4, 0])]],
);
let f = open(&d).unwrap();
let rects: Vec<_> = f.frames.iter().map(|fr| f.picture_rect(fr)).collect();
assert_eq!(rects, [Some((0, 0, 15, 7)), Some((2, 0, 5, 0)), Some((2, 0, 5, 0)), 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(_))));
}
#[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(_))));
}
#[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 fr in &f.frames {
let _ = f.picture_rect(fr);
}
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) }
}
+9 -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
@@ -52,6 +52,8 @@ vp9-encode = ["craft-media/isobmff"]
av1 = ["av1-decode", "av1-encode"]
av1-decode = []
av1-encode = ["craft-media/isobmff"]
# Sierra VMD video (8-bit paletted): decoder.
vmd = []
# Decode and encode across worker threads (rayon) in the codecs that support it.
threads = ["dep:rayon"]
@@ -62,8 +64,12 @@ rayon = { workspace = true, 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"]
[[test]]
name = "dnx"
+1
View File
@@ -28,4 +28,5 @@ 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 encoder (`av1-encode` alone) |
| `vmd` | `vmd` | Sierra VMD video (the 8-bit paletted pictures of Sierra and Coktel Vision game videos): decoder |
| `threads` | — | Multi-threaded slice/row parallelism via `rayon` |
+4
View File
@@ -15,6 +15,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 |
//!
//! No codec is on by default. Feature `threads` spreads the work of the codecs that support it
//! over rayon worker threads.
@@ -55,3 +56,6 @@ pub mod vp9;
#[cfg(any(feature = "av1-decode", feature = "av1-encode"))]
pub mod av1;
#[cfg(feature = "vmd")]
pub mod vmd;
+382
View File
@@ -0,0 +1,382 @@
//! 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 Some(rect) = file.picture_rect(frame) else { continue };
//! decoder.decode(Rect::from(rect), new_palette, &file.read_frame(&bytes, i)?)?;
//! 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 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 and an RGBA copy of them for the caller
let shape = PictureShape { width: width.into(), height: height.into(), shift_x: 0, shift_y: 0, chroma_planes: 0, bytes_per_sample: 5 };
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 data.is_empty() {
return Ok(());
}
if new_palette {
// 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..]);
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);
let result = lz_unpack(body, self.unpack_limit, &mut unpacked).and_then(|()| self.render(rect, method & 0x7F, &unpacked));
self.unpacked = unpacked;
result
}
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.
fn lz_unpack(src: &[u8], limit: 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"));
}
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;
}
}
+415
View File
@@ -0,0 +1,415 @@
//! 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 rect = Rect::from(file.picture_rect(frame).unwrap());
decoder.decode(rect, new_palette, &file.read_frame(bytes, i).unwrap()).unwrap();
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)];
#[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];
let mut want = vec![0x90, 0xA0, 0xB0, 0x90, 0xA0, 0xB0];
want.resize(29, 0x20);
want.extend([0x40; 3]);
// 29 of the 32 bytes arrive: the picture's last three pixels are not painted
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);
assert_eq!(d.indices()[..16], want[..16]);
// 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<_>>());
}
#[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]));
assert_eq!(d.decode(FULL, true, &[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(frame) {
let _ = decoder.decode(rect.into(), new_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 rect = file.picture_rect(frame).unwrap_or_else(|| panic!("{name}: frame {i} lies outside the picture"));
let data = file.read_frame(&source, i).unwrap();
decoder.decode(rect.into(), new_palette, &data).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");
child.wait().unwrap();
}
println!("{} files, {pictures} pictures match ffmpeg", paths.len());
}