Files
prometeu-runtime/crates/console/prometeu-drivers/src/audio/bank_format.rs
T
bquarkz 8510c5b00d feat(audio): add 32-voice PCM mixing and native music sequencing
Add self-contained SoundBanks and MusicBanks with per-sample PCM16 and IMA ADPCM storage, materialized to resident PCM16. Integrate instrument envelopes, automation, shared DSP and host lifecycle controls while preserving staged real-time execution.
2026-11-20 22:15:24 +00:00

593 lines
22 KiB
Rust

//! 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<u16, String> {
Ok(u16::from_le_bytes(bytes(b, o, 2)?.try_into().unwrap()))
}
fn u32le(b: &[u8], o: usize) -> Result<u32, String> {
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<T>(n: usize) -> Result<Vec<T>, 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<u32>,
tracks: usize,
name: String,
samples_at: usize,
metadata: usize,
payload_end: usize,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
events: Vec<MusicEvent>,
current: Option<SampleMaterializer>,
compiler: Option<MusicCompiler>,
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<Self, String> {
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<Option<DecodedAudioBank>, 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<AudioBankMetrics, String> {
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<DecodedAudioBank, String> {
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<Vec<i16>, 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<Vec<u8>, 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<i16> = (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::<f64>()
/ 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<u8> {
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;