//! SBNK/MBNK v1. IMA WAVE4 algorithm implemented here from the published Intel //! format, not copied from a third-party decoder. Project MIT license applies. use prometeu_hal::{ music_bank::{Instrument, MusicBank, MusicCompiler, MusicEvent}, sample::Sample, sound_bank::{AudioBankMetrics, SoundBank}, }; use std::sync::Arc; pub const HEADER_BYTES: usize = 48; pub const SAMPLE_BYTES: usize = 40; pub const INSTRUMENT_BYTES: usize = 64; pub const EVENT_BYTES: usize = 32; pub enum DecodedAudioBank { Sound(SoundBank), Music(MusicBank), } impl DecodedAudioBank { pub fn decoded_size(&self) -> usize { match self { Self::Sound(b) => b.metrics.canonical_decoded_bytes, Self::Music(b) => b.metrics.canonical_decoded_bytes, } } } fn bytes(data: &[u8], offset: usize, len: usize) -> Result<&[u8], String> { data.get(offset..offset.checked_add(len).ok_or("audio offset overflow")?) .ok_or_else(|| "truncated audio bank".into()) } fn u16le(b: &[u8], o: usize) -> Result { Ok(u16::from_le_bytes(bytes(b, o, 2)?.try_into().unwrap())) } fn u32le(b: &[u8], o: usize) -> Result { Ok(u32::from_le_bytes(bytes(b, o, 4)?.try_into().unwrap())) } fn zero(b: &[u8]) -> Result<(), String> { if b.iter().any(|&x| x != 0) { Err("nonzero audio reserved bytes".into()) } else { Ok(()) } } fn vector(n: usize) -> Result, String> { let mut v = Vec::new(); v.try_reserve_exact(n).map_err(|_| "audio allocation failed")?; Ok(v) } /// One bank owns its serialized bytes while materializing. IO and CPU preparation /// yield separately; no partially decoded bank escapes this object. pub struct AudioBankMaterializer<'a> { data: std::borrow::Cow<'a, [u8]>, music: bool, ns: usize, ni: usize, ne: usize, ppq: u32, tempo: u32, duration: u32, loop_tick: Option, tracks: usize, name: String, samples_at: usize, metadata: usize, payload_end: usize, samples: Vec>, instruments: Vec, events: Vec, current: Option, compiler: Option, pcm_bytes: usize, started: std::time::Instant, } struct SampleMaterializer { sample: Sample, codec: u8, frames: usize, offset: usize, size: usize, align: usize, spb: usize, consumed: usize, } impl<'a> AudioBankMaterializer<'a> { pub fn new(data: std::borrow::Cow<'a, [u8]>, music: bool) -> Result { let started = std::time::Instant::now(); bytes(&data, 0, HEADER_BYTES)?; if &data[..4] != if music { b"MBNK" } else { b"SBNK" } || u16le(&data, 4)? != 1 || u16le(&data, 6)? != 0 { return Err("unsupported audio bank magic/version/flags".into()); } let ns = u32le(&data, 8)? as usize; let ni = u32le(&data, 12)? as usize; let ne = u32le(&data, 16)? as usize; let ppq = u32le(&data, 20)?; let tempo = u32le(&data, 24)?; let duration = u32le(&data, 28)?; let lp = u32le(&data, 32)?; let tracks = u32le(&data, 36)? as usize; let name_len = u32le(&data, 40)? as usize; zero(bytes(&data, 44, 4)?)?; if ns > 65536 || ppq != 960 || tempo == 0 || (!music && (ns == 0 || ni != 0 || ne != 0 || duration != 0 || tracks != 0 || lp != u32::MAX)) { return Err("invalid audio bank counts/clock".into()); } if music && (duration == 0 || !(1..=256).contains(&tracks) || (lp != u32::MAX && lp >= duration)) { return Err("invalid music clock/tracks/loop".into()); } let mut offset = HEADER_BYTES.checked_add(name_len).ok_or("audio name overflow")?; let samples_at = offset; for (n, size) in [(ns, SAMPLE_BYTES), (ni, INSTRUMENT_BYTES), (ne, EVENT_BYTES)] { offset = offset .checked_add(n.checked_mul(size).ok_or("audio table overflow")?) .ok_or("audio table overflow")?; } bytes(&data, 0, offset)?; let text = std::str::from_utf8(bytes(&data, HEADER_BYTES, name_len)?) .map_err(|_| "audio name UTF-8")?; let mut name = String::new(); name.try_reserve_exact(text.len()).map_err(|_| "audio allocation failed")?; name.push_str(text); Ok(Self { data, music, ns, ni, ne, ppq, tempo, duration, loop_tick: (lp != u32::MAX).then_some(lp), tracks, name, samples_at, metadata: offset, payload_end: offset, samples: vector(ns)?, instruments: vector(ni)?, events: vector(ne)?, current: None, compiler: None, pcm_bytes: 0, started, }) } fn start_sample(&mut self) -> Result<(), String> { let d = bytes(&self.data, self.samples_at + self.samples.len() * SAMPLE_BYTES, SAMPLE_BYTES)?; let codec = d[0]; let channels = d[1]; let flags = u16le(d, 2)?; let rate = u32le(d, 4)?; let frames = u32le(d, 8)? as usize; let start = u32le(d, 12)?; let end = u32le(d, 16)?; let offset = u32le(d, 20)? as usize; let size = u32le(d, 24)? as usize; let align = u16le(d, 28)? as usize; let spb = u16le(d, 30)? as usize; let pitch = u32le(d, 36)?; zero(bytes(d, 34, 2)?)?; if !(1..=2).contains(&channels) || rate == 0 || pitch == 0 || flags & !1 != 0 || offset != self.payload_end || (flags == 0 && (start != 0 || end != 0)) || (flags == 1 && (start >= end || end as usize > frames)) { return Err("invalid audio sample descriptor/loop".into()); } let scalar = frames.checked_mul(channels as usize).ok_or("PCM frame overflow")?; let resident = scalar.checked_mul(2).ok_or("PCM byte overflow")?; bytes(&self.data, offset, size)?; match codec { 0 => { if size != resident || align != 0 || spb != 0 { return Err("PCM payload/frame count mismatch".into()); } } 1 => { let c = channels as usize; if align < 8 * c || !align.is_multiple_of(4 * c) || spb != 1 + (align - 4 * c) * 2 / c || !size.is_multiple_of(align) || size / align != frames.div_ceil(spb) { return Err("IMA block layout/frame count".into()); } } _ => return Err("unsupported sample codec".into()), } let mut sample = Sample::new(rate, vector(scalar)?).with_channels(channels)?; if flags == 1 { sample = sample.with_loop(start, end); } sample.default_volume = d[32]; sample.default_pan = d[33]; sample.default_pitch = pitch as f64 / 65536.0; self.pcm_bytes = self.pcm_bytes.checked_add(resident).ok_or("resident audio size overflow")?; self.current = Some(SampleMaterializer { sample, codec, frames, offset, size, align, spb, consumed: 0, }); Ok(()) } /// Decode at most 4096 PCM bytes or one independently bounded IMA block; /// parse at most 64 metadata records; compile at most 64 music records. pub fn step(&mut self) -> Result, String> { if let Some(compiler) = &mut self.compiler { return match compiler.step()? { Some(mut bank) => { bank.metrics = self.metrics()?; Ok(Some(DecodedAudioBank::Music(bank))) } None => Ok(None), }; } if self.samples.len() < self.ns { if self.current.is_none() { self.start_sample()?; } let current = self.current.as_mut().unwrap(); if current.consumed < current.size { if current.codec == 0 { let count = (current.size - current.consumed).min(4096); let part = bytes(&self.data, current.offset + current.consumed, count)?; current .sample .data .extend(part.as_chunks::<2>().0.iter().map(|p| i16::from_le_bytes(*p))); current.consumed += count; } else { let frames = (current.frames - current.sample.frames_len()).min(current.spb); let pcm = decode_ima_wav4( bytes(&self.data, current.offset + current.consumed, current.align)?, current.sample.channels, frames, current.align, current.spb, )?; current.sample.data.extend(pcm); current.consumed += current.align; } } if current.consumed == current.size { self.payload_end = current.offset + current.size; let current = self.current.take().unwrap(); self.samples.push(Arc::new(current.sample)); } return Ok(None); } if self.payload_end != self.data.len() { return Err("audio trailing/unreferenced payload".into()); } if !self.music { let mut bank = SoundBank::new(std::mem::take(&mut self.samples)); bank.name = std::mem::take(&mut self.name); bank.metrics = self.metrics()?; return Ok(Some(DecodedAudioBank::Sound(bank))); } let inst_at = self.samples_at + self.ns * SAMPLE_BYTES; if self.instruments.len() < self.ni { for _ in 0..64 { if self.instruments.len() == self.ni { break; } let d = bytes( &self.data, inst_at + self.instruments.len() * INSTRUMENT_BYTES, INSTRUMENT_BYTES, )?; if d[7] & !1 != 0 { return Err("instrument flags".into()); } zero(bytes(d, 22, 2)?)?; zero(bytes(d, 43, 21)?)?; self.instruments.push(Instrument { id: u16le(d, 0)?, sample: u16le(d, 2)?, low: d[4], high: d[5], root: d[6], looping: d[7] & 1 != 0, tuning_cents: u16le(d, 8)? as i16, pan: d[10], gain: d[11], attack_us: u32le(d, 12)?, decay_us: u32le(d, 16)?, sustain: u16le(d, 20)?, release_us: u32le(d, 24)?, vibrato_millihz: u32le(d, 28)?, vibrato_cents: u16le(d, 32)?, tremolo_depth: u16le(d, 34)?, tremolo_millihz: u32le(d, 36)?, send: u16le(d, 40)?, curve: d[42], }); } return Ok(None); } if self.events.len() < self.ne { let at = inst_at + self.ni * INSTRUMENT_BYTES; for _ in 0..64 { if self.events.len() == self.ne { break; } let d = bytes(&self.data, at + self.events.len() * EVENT_BYTES, EVENT_BYTES)?; self.events.push(MusicEvent { tick: u32le(d, 0)?, kind: d[4], track: d[5], flags: u16le(d, 6)?, a: u32le(d, 8)?, b: u32le(d, 12)?, c: u32le(d, 16)? as i32, d: u32le(d, 20)? as i32, duration_frames: u32le(d, 24)?, curve: u32le(d, 28)?, }); } return Ok(None); } self.compiler = Some(MusicCompiler::new( std::mem::take(&mut self.name), std::mem::take(&mut self.samples), std::mem::take(&mut self.instruments), std::mem::take(&mut self.events), self.ppq, self.tempo, self.duration, self.loop_tick, self.tracks, )?); Ok(None) } fn metrics(&self) -> Result { Ok(AudioBankMetrics { cartridge_bytes: self.data.len(), pcm_bytes: self.pcm_bytes, canonical_decoded_bytes: self .metadata .checked_add(self.pcm_bytes) .ok_or("decoded audio size overflow")?, materialization_ns: self.started.elapsed().as_nanos().min(u64::MAX as u128) as u64, }) } } pub fn decode_audio_bank(data: &[u8], music: bool) -> Result { let mut decoder = AudioBankMaterializer::new(std::borrow::Cow::Borrowed(data), music)?; loop { if let Some(bank) = decoder.step()? { return Ok(bank); } } } const STEP: [i32; 89] = [ 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66, 73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190, 209, 230, 253, 279, 307, 337, 371, 408, 449, 494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272, 2499, 2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493, 10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350, 22385, 24623, 27086, 29794, 32767, ]; const INDEX: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8]; fn ima_code(code: u8, predictor: &mut i32, index: &mut usize) -> i16 { let step = STEP[*index]; let mut diff = step >> 3; if code & 1 != 0 { diff += step >> 2; } if code & 2 != 0 { diff += step >> 1; } if code & 4 != 0 { diff += step; } *predictor = (*predictor + if code & 8 != 0 { -diff } else { diff }).clamp(-32768, 32767); *index = (*index as i32 + INDEX[(code & 7) as usize]).clamp(0, 88) as usize; *predictor as i16 } pub fn decode_ima_wav4( data: &[u8], channels: u8, frames: usize, align: usize, spb: usize, ) -> Result, String> { let c = channels as usize; if !(1..=2).contains(&channels) || align > u16::MAX as usize || align < 8 * c || !align.is_multiple_of(4 * c) || spb != 1 + (align - 4 * c) * 2 / c || !data.len().is_multiple_of(align) || data.len() / align != frames.div_ceil(spb) { return Err("invalid IMA WAVE4 block/frame layout".into()); } let mut out = vector(frames.checked_mul(c).ok_or("IMA frame overflow")?)?; for (block_index, block) in data.chunks_exact(align).enumerate() { let mut pred = [0i32; 2]; let mut index = [0usize; 2]; for ch in 0..c { pred[ch] = i16::from_le_bytes([block[ch * 4], block[ch * 4 + 1]]) as i32; index[ch] = block[ch * 4 + 2] as usize; if index[ch] > 88 || block[ch * 4 + 3] != 0 { return Err("IMA predictor index/reserved".into()); } out.push(pred[ch] as i16); } let remaining = (frames - block_index * spb).min(spb); for group in 0..(spb - 1) / 8 { let mut decoded = [[0i16; 8]; 2]; for ch in 0..c { for n in 0..8 { let b = block[4 * c + group * 4 * c + ch * 4 + n / 2]; let code = (b >> ((n % 2) * 4)) & 15; if 1 + group * 8 + n >= remaining && code != 0 { return Err("nonzero IMA padding".into()); } decoded[ch][n] = ima_code(code, &mut pred[ch], &mut index[ch]); } } for n in 0..8 { if 1 + group * 8 + n < remaining { for channel in decoded.iter().take(c) { out.push(channel[n]); } } } } } Ok(out) } /// Deterministic storage encoder used by conformance tools/fixtures (never RT). pub fn encode_ima_wav4(pcm: &[i16], channels: u8, align: usize) -> Result, String> { let c = channels as usize; if !(1..=2).contains(&channels) || !pcm.len().is_multiple_of(c) || align > u16::MAX as usize || align < 8 * c || !align.is_multiple_of(4 * c) { return Err("IMA encoder shape".into()); } let spb = 1 + (align - 4 * c) * 2 / c; if spb > u16::MAX as usize { return Err("IMA block exceeds descriptor range".into()); } let frames = pcm.len() / c; let nblocks = frames.div_ceil(spb); let mut out = vector(nblocks.checked_mul(align).ok_or("IMA encoded size overflow")?)?; for block in 0..nblocks { let first = block * spb; let count = (frames - first).min(spb); let mut pred = [0i32; 2]; let mut index = [0usize; 2]; for ch in 0..c { pred[ch] = pcm[first * c + ch] as i32; let n = (count - 1).min(32); let sum: i32 = (1..=n) .map(|i| { (pcm[(first + i) * c + ch] as i32 - pcm[(first + i - 1) * c + ch] as i32).abs() }) .sum(); let mean = if n == 0 { 0 } else { sum / n as i32 }; index[ch] = STEP.iter().position(|&s| s >= mean).unwrap_or(88); out.extend_from_slice(&(pred[ch] as i16).to_le_bytes()); out.push(index[ch] as u8); out.push(0); } for group in 0..(spb - 1) / 8 { for ch in 0..c { for byte in 0..4 { let mut packed = 0; for nibble in 0..2 { let f = 1 + group * 8 + byte * 2 + nibble; let code = if f >= count { 0 } else { let diff = pcm[(first + f) * c + ch] as i32 - pred[ch]; let mut magnitude = diff.abs(); let step = STEP[index[ch]]; let mut code = if diff < 0 { 8 } else { 0 }; if magnitude >= step { code |= 4; magnitude -= step; } if magnitude >= step >> 1 { code |= 2; magnitude -= step >> 1; } if magnitude >= step >> 2 { code |= 1; } code }; ima_code(code, &mut pred[ch], &mut index[ch]); packed |= code << (nibble * 4); } out.push(packed); } } } } Ok(out) } #[cfg(test)] mod tests { use super::*; #[test] fn ima_known_nibbles_and_stereo_headers() { let block = [0, 0, 0, 0, 0x11, 0, 0, 0]; assert_eq!(decode_ima_wav4(&block, 1, 3, 8, 9).unwrap(), [0, 1, 2]); let mut stereo = vec![0, 0, 0, 0, 100, 0, 0, 0]; stereo.extend([0u8; 8]); let decoded = decode_ima_wav4(&stereo, 2, 9, 16, 9).unwrap(); assert_eq!(&decoded[..6], [0, 100, 0, 100, 0, 100]); stereo[2] = 89; assert!(decode_ima_wav4(&stereo, 2, 9, 16, 9).is_err()); } #[test] fn ima_partial_block_padding_round_trip_is_deterministic() { let pcm: Vec = (0..1111) .flat_map(|i| { [ ((i as f64 * 0.03).sin() * 12000.0) as i16, ((i as f64 * 0.02).cos() * 9000.0) as i16, ] }) .collect(); let encoded = encode_ima_wav4(&pcm, 2, 512).unwrap(); assert_eq!(encoded, encode_ima_wav4(&pcm, 2, 512).unwrap()); let decoded = decode_ima_wav4(&encoded, 2, 1111, 512, 505).unwrap(); assert_eq!(decoded.len(), pcm.len()); assert_eq!(decoded[1010], pcm[1010]); assert!(decode_ima_wav4(&encoded[..encoded.len() - 1], 2, 1111, 512, 505).is_err()); let error: f64 = pcm.iter().zip(decoded).map(|(&a, b)| (a as f64 - b as f64).powi(2)).sum::() / pcm.len() as f64; assert!(error.sqrt() < 400.0, "RMS error {error}"); } } #[cfg(test)] pub(crate) fn test_pcm_bank(raw: &[u8], rate: u32) -> Vec { let mut bytes = vec![0u8; 88]; bytes[..4].copy_from_slice(b"SBNK"); bytes[4] = 1; for (at, value) in [ (8, 1), (20, 960), (24, 500000), (32, u32::MAX), (52, rate), (56, (raw.len() / 2) as u32), (68, 88), (72, raw.len() as u32), (84, 65536), ] { bytes[at..at + 4].copy_from_slice(&value.to_le_bytes()); } bytes[49] = 1; bytes[80] = 255; bytes[81] = 128; bytes.extend_from_slice(raw); bytes } #[cfg(test)] #[path = "bank_tests.rs"] mod bank_tests;