diff --git a/crates/console/prometeu-drivers/examples/audio_measure.rs b/crates/console/prometeu-drivers/examples/audio_measure.rs new file mode 100644 index 0000000..a093dd7 --- /dev/null +++ b/crates/console/prometeu-drivers/examples/audio_measure.rs @@ -0,0 +1,256 @@ +//! Repeatable CPU/memory observations, not a handheld or physical-device guarantee. +use prometeu_drivers::{ + Audio, MemoryBanks, SoundBankPoolInstaller, + bank_format::{decode_audio_bank, encode_ima_wav4}, + engine::{AudioMixer, Packet}, +}; +use prometeu_hal::{ + AudioBridge, LoopMode, + audio_bridge::AudioControl, + music_bank::{Instrument, MusicBank, MusicEvent}, + sample::Sample, + sound_bank::SoundBank, +}; +use serde_json::{Value, json}; +use std::{ + alloc::{GlobalAlloc, Layout, System}, + sync::{ + Arc, + atomic::{AtomicUsize, Ordering}, + }, + time::Instant, +}; +struct Counter; +static LIVE: AtomicUsize = AtomicUsize::new(0); +static PEAK: AtomicUsize = AtomicUsize::new(0); +unsafe impl GlobalAlloc for Counter { + unsafe fn alloc(&self, l: Layout) -> *mut u8 { + let p = unsafe { System.alloc(l) }; + if !p.is_null() { + let n = LIVE.fetch_add(l.size(), Ordering::Relaxed) + l.size(); + PEAK.fetch_max(n, Ordering::Relaxed); + } + p + } + unsafe fn dealloc(&self, p: *mut u8, l: Layout) { + LIVE.fetch_sub(l.size(), Ordering::Relaxed); + unsafe { System.dealloc(p, l) } + } +} +#[global_allocator] +static ALLOCATOR: Counter = Counter; +fn stats(values: &mut [u64]) -> Value { + values.sort_unstable(); + let n = values.len(); + json!({"p50_ns":values[n/2],"p95_ns":values[n*95/100],"p99_ns":values[n*99/100],"max_ns":values[n-1]}) +} +fn music(channels: u8) -> Arc { + let pcm = (0..4096) + .flat_map(|i| { + std::iter::repeat_n(((i as f64 * 0.05).sin() * 800.0) as i16, channels as usize) + }) + .collect(); + let sample = + Arc::new(Sample::new(48000, pcm).with_channels(channels).unwrap().with_loop(0, 4096)); + let events = (0..12) + .map(|id| MusicEvent { kind: 1, a: id, c: 60 + id as i32, d: 180, ..Default::default() }) + .collect(); + Arc::new( + MusicBank::compile( + "measure".into(), + vec![sample], + vec![Instrument { + looping: true, + attack_us: 1000, + decay_us: 10_000, + sustain: 50000, + release_us: 10_000, + send: 20000, + vibrato_cents: 10, + vibrato_millihz: 5000, + tremolo_depth: 1000, + tremolo_millihz: 3000, + ..Default::default() + }], + events, + 960, + 500000, + 3840, + None, + 1, + ) + .unwrap(), + ) +} +fn scenario(channels: u8, dsp: bool, replacement: bool) -> Value { + let banks = Arc::new(MemoryBanks::new()); + let mut audio = Audio::new(banks.clone()); + banks.install_music_bank(0, music(channels)); + banks.install_music_bank(1, music(channels)); + audio.music_play(0, 0, true); + audio.music_play(1, 1, true); + let sample = Arc::new( + Sample::new(48000, vec![500; 4096 * channels as usize]) + .with_channels(channels) + .unwrap() + .with_loop(0, 4096), + ); + for voice in 0..8 { + audio.play_sample(sample.clone(), voice, 255, 128, 1.0, 0, LoopMode::On); + audio.control(AudioControl::SfxSend { voice, gain: 100 }); + } + if dsp { + for group in 0..3 { + audio.control(AudioControl::Effect { + group, + cutoff_hz: 6000, + delay_frames: 4800, + feedback: 0.5, + wet: 0.3, + dry: 0.7, + }); + } + } + audio.finish_frame(); + let mut mixer = AudioMixer::new(); + let mut packet = Packet::new(); + mixer.apply_delivery_into(audio.transport().try_take().unwrap(), &mut packet); + packet.recycle(&audio.transport()); + let mut pcm = [0.0; 512]; + let mut timings = Vec::with_capacity(1000); + let mut overruns = 0; + let mut max_retired = 0; + let baseline = LIVE.load(Ordering::Relaxed); + PEAK.store(baseline, Ordering::Relaxed); + for iteration in 0..1000 { + if replacement && iteration % 10 == 0 { + banks.install_music_bank(0, music(channels)); + audio.music_play(0, 0, true); + audio.control(AudioControl::MusicFade { + group: 1, + gain: 180, + frames: 2400, + smooth: true, + }); + audio.finish_frame(); + } + let start = Instant::now(); + mixer.retire_inactive(&mut packet); + if let Some(delivery) = audio.transport().try_take() { + mixer.apply_delivery_into(delivery, &mut packet); + } + mixer.mix(&mut pcm); + mixer.retire_inactive(&mut packet); + let elapsed = start.elapsed().as_nanos() as u64; + if elapsed > 5_333_333 { + overruns += 1; + } + timings.push(elapsed); + max_retired = max_retired.max(packet.retained_pcm_bytes()); + packet.recycle(&audio.transport()); + std::hint::black_box(&pcm); + } + json!({"channels_per_voice":channels,"dsp":dsp,"replacement_every_10_buffers":replacement,"buffers":1000,"frames_per_buffer":256,"nominal_buffer_ns":5_333_333,"observed_budget_overruns":overruns,"timing":stats(&mut timings),"maximum_active_voices":mixer.diagnostics.maximum_voices,"engine_prepared_bytes":mixer.prepared_bytes(),"maximum_retired_pcm_bytes":max_retired,"baseline_allocated_bytes":baseline,"peak_allocated_bytes":PEAK.load(Ordering::Relaxed)}) +} +fn codec_and_memory() -> Value { + let pcm: Vec = (0..480_000) + .flat_map(|i| { + [((i as f64 * 0.04).sin() * 12000.0) as i16, ((i as f64 * 0.06).cos() * 9000.0) as i16] + }) + .collect(); + let start = Instant::now(); + let compressed = encode_ima_wav4(&pcm, 2, 512).unwrap(); + let encode_ns = start.elapsed().as_nanos(); + let mut bytes = vec![0u8; 88]; + bytes[..4].copy_from_slice(b"SBNK"); + bytes[4] = 1; + bytes[48] = 1; + bytes[49] = 2; + bytes[80] = 255; + bytes[81] = 128; + for (at, n) in [ + (8, 1u32), + (20, 960), + (24, 500000), + (32, u32::MAX), + (52, 48000), + (56, 480000), + (68, 88), + (72, compressed.len() as u32), + (84, 65536), + ] { + bytes[at..at + 4].copy_from_slice(&n.to_le_bytes()); + } + bytes[76..78].copy_from_slice(&512u16.to_le_bytes()); + bytes[78..80].copy_from_slice(&505u16.to_le_bytes()); + bytes.extend(&compressed); + let mut decode = Vec::with_capacity(20); + let baseline = LIVE.load(Ordering::Relaxed); + PEAK.store(baseline, Ordering::Relaxed); + for _ in 0..20 { + let start = Instant::now(); + let bank = decode_audio_bank(&bytes, false).unwrap(); + decode.push(start.elapsed().as_nanos() as u64); + std::hint::black_box(bank); + } + let decode_peak = PEAK.load(Ordering::Relaxed); + let banks = MemoryBanks::new(); + for slot in 0..16 { + banks.install_sound_bank( + slot, + Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48000, vec![0; 1_048_576]))])), + ); + } + let large_music = || { + let sample = Arc::new(Sample::new(48000, vec![0; 1_048_576]).with_loop(0, 1_048_576)); + Arc::new( + MusicBank::compile( + "large".into(), + vec![sample], + vec![Instrument { looping: true, ..Default::default() }], + vec![MusicEvent { kind: 1, a: 1, c: 60, d: 255, ..Default::default() }], + 960, + 500000, + 3840, + None, + 1, + ) + .unwrap(), + ) + }; + for slot in 0..16 { + banks.install_music_bank(slot, large_music()); + } + let snapshot = banks.audio_memory(); + let mut mixer = AudioMixer::new(); + let mut packet = Packet::new(); + use prometeu_drivers::SoundBankPoolAccess; + mixer.apply_delivery_into( + prometeu_drivers::AudioDelivery { + epoch: 0, + paused: false, + frame: Some(vec![prometeu_drivers::AudioCommand::MusicPlay { + group: 0, + bank: banks.music_bank_slot(0).unwrap(), + looping: true, + }]), + lifecycle: None, + }, + &mut packet, + ); + packet.recycle(&prometeu_drivers::AudioTransport::default()); + mixer.mix(&mut [0.0; 2]); + let before = LIVE.load(Ordering::Relaxed); + PEAK.store(before, Ordering::Relaxed); + banks.install_music_bank(0, large_music()); + mixer.retire_inactive(&mut packet); + let retired = packet.retained_pcm_bytes(); + let replacement_peak = PEAK.load(Ordering::Relaxed); + packet.recycle(&prometeu_drivers::AudioTransport::default()); + let after = LIVE.load(Ordering::Relaxed); + + json!({"source_frames":480000,"channels":2,"pcm_bytes":pcm.len()*2,"cartridge_sample_bytes":compressed.len(),"compression_ratio":compressed.len()as f64/(pcm.len()*2)as f64,"encode_ns":encode_ns,"decode_timing":stats(&mut decode),"decode_baseline_allocated_bytes":baseline,"decode_peak_allocated_bytes":decode_peak,"large_bank_count":snapshot.banks.len(),"large_banks_unique_pcm_bytes":snapshot.unique_pcm_bytes,"replacement_baseline_allocated_bytes":before,"replacement_peak_allocated_bytes":replacement_peak,"replacement_after_reclamation_bytes":after,"retained_replaced_pcm_bytes":retired,"resident_accounted_metadata_bytes":snapshot.metadata_bytes,"resident_total_accounted_bytes":snapshot.total_accounted_bytes}) +} +fn main() { + println!("{}",serde_json::to_string_pretty(&json!({"arch":std::env::consts::ARCH,"os":std::env::consts::OS,"observations":[scenario(1,false,false),scenario(2,false,false),scenario(2,true,false),scenario(2,true,true)],"codecs_and_memory":codec_and_memory()})).unwrap()); +} diff --git a/crates/console/prometeu-drivers/src/asset.rs b/crates/console/prometeu-drivers/src/asset.rs index 0e8bc21..32c09f5 100644 --- a/crates/console/prometeu-drivers/src/asset.rs +++ b/crates/console/prometeu-drivers/src/asset.rs @@ -1,6 +1,7 @@ #![allow(clippy::collapsible_if)] mod decode; mod resumable; +use crate::audio::bank_format::{DecodedAudioBank, decode_audio_bank}; use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller}; use prometeu_hal::AssetBridge; use prometeu_hal::asset::{ @@ -14,7 +15,7 @@ use prometeu_hal::cartridge::AssetsPayloadSource; use prometeu_hal::color::Color; use prometeu_hal::glyph::Glyph; use prometeu_hal::glyph_bank::{GlyphBank, TileSize}; -use prometeu_hal::sample::Sample; +use prometeu_hal::music_bank::MusicBank; use prometeu_hal::scene_bank::SceneBank; use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer}; use prometeu_hal::sound_bank::SoundBank; @@ -61,6 +62,7 @@ pub struct AssetPipelineTelemetry { pub active_progress: u16, pub glyph_latency: AssetLatencyPercentiles, pub sound_latency: AssetLatencyPercentiles, + pub music_latency: AssetLatencyPercentiles, pub scene_latency: AssetLatencyPercentiles, pub last_asset_id: Option, pub last_asset_latency: AssetLatencyPercentiles, @@ -130,6 +132,7 @@ impl AssetPipelineTelemetryState { ); self.snapshot.glyph_latency = percentile_snapshot(self.bank_samples.get(&BankType::GLYPH)); self.snapshot.sound_latency = percentile_snapshot(self.bank_samples.get(&BankType::SOUNDS)); + self.snapshot.music_latency = percentile_snapshot(self.bank_samples.get(&BankType::MUSIC)); self.snapshot.scene_latency = percentile_snapshot(self.bank_samples.get(&BankType::SCENE)); self.snapshot.last_asset_id = Some(asset_id); self.snapshot.last_asset_latency = percentile_snapshot(self.asset_samples.get(&asset_id)); @@ -329,12 +332,14 @@ pub struct AssetManager { gfx_slots: Arc; 16]>>, glyph_slot_index: GlyphAssetSlotIndex, sound_slots: Arc; 16]>>, + music_slots: Arc; 16]>>, scene_slots: Arc; 16]>>, /// Residency policy for GFX glyph banks. gfx_policy: BankPolicy, /// Residency policy for sound banks. sound_policy: BankPolicy, + music_policy: BankPolicy, /// Residency policy for scene banks. scene_policy: BankPolicy, @@ -370,6 +375,7 @@ struct AssetLoadJobResources<'a> { pipeline_telemetry: &'a Arc>, gfx_policy: &'a BankPolicy, sound_policy: &'a BankPolicy, + music_policy: &'a BankPolicy, scene_policy: &'a BankPolicy, } @@ -479,6 +485,7 @@ struct AssetLoadWorker { } impl AssetLoadWorker { + #[allow(clippy::too_many_arguments)] fn new( handles: Arc>, target_generations: Arc>, @@ -486,6 +493,7 @@ impl AssetLoadWorker { pipeline_telemetry: Arc>, gfx_policy: BankPolicy, sound_policy: BankPolicy, + music_policy: BankPolicy, scene_policy: BankPolicy, ) -> Self { let queue = Arc::new(AssetLoadQueue::default()); @@ -498,6 +506,7 @@ impl AssetLoadWorker { pipeline_telemetry: &pipeline_telemetry, gfx_policy: &gfx_policy, sound_policy: &sound_policy, + music_policy: &music_policy, scene_policy: &scene_policy, }; while let Some(job) = worker_queue.next_job() { @@ -554,6 +563,9 @@ enum AssetOpMode { } impl AssetBridge for AssetManager { + fn unload_audio(&self, music: bool, slot: usize) -> AssetOpStatus { + self.unload_audio(music, slot) + } fn bind_background_work( &mut self, lane: Arc, @@ -647,7 +659,9 @@ impl AssetManager { fn op_mode_for(entry: &AssetEntry) -> Result { match (entry.bank_type, entry.codec) { (BankType::GLYPH, AssetCodec::None) => Ok(AssetOpMode::StageInMemory), - (BankType::SOUNDS, AssetCodec::None) => Ok(AssetOpMode::DirectFromSlice), + (BankType::SOUNDS, AssetCodec::None) | (BankType::MUSIC, AssetCodec::None) => { + Ok(AssetOpMode::DirectFromSlice) + } (BankType::SCENE, AssetCodec::None) => Ok(AssetOpMode::DirectFromSlice), } } @@ -670,6 +684,7 @@ impl AssetManager { let pipeline_telemetry = Arc::new(Mutex::new(AssetPipelineTelemetryState::default())); let gfx_policy = BankPolicy::new(); let sound_policy = BankPolicy::new(); + let music_policy = BankPolicy::new(); let scene_policy = BankPolicy::new(); let load_worker = AssetLoadWorker::new( Arc::clone(&handles), @@ -678,6 +693,7 @@ impl AssetManager { Arc::clone(&pipeline_telemetry), gfx_policy.clone(), sound_policy.clone(), + music_policy.clone(), scene_policy.clone(), ); @@ -689,9 +705,11 @@ impl AssetManager { gfx_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), glyph_slot_index: GlyphAssetSlotIndex::new(), sound_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), + music_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), scene_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), gfx_policy, sound_policy, + music_policy, scene_policy, handles, target_handles: Arc::new(RwLock::new(HashMap::new())), @@ -776,6 +794,23 @@ impl AssetManager { } } } + BankType::MUSIC => { + if let Ok(bank) = + Self::perform_load_music_bank(&entry, self.assets_data.clone()) + { + let bank_arc = Arc::new(bank); + self.music_policy.put_resident( + entry.asset_id, + Arc::clone(&bank_arc), + entry.decoded_size as usize, + ); + self.sound_installer.install_music_bank(slot_index, bank_arc); + let mut slots = self.music_slots.write().unwrap(); + if slot_index < slots.len() { + slots[slot_index] = Some(entry.asset_id); + } + } + } BankType::SCENE => { if let Ok(bank) = Self::perform_load_scene_bank(&entry, self.assets_data.clone()) @@ -840,6 +875,7 @@ impl AssetManager { fn clear_staging_for_handle(&self, handle_id: HandleId) { self.gfx_policy.take_staging(handle_id); self.sound_policy.take_staging(handle_id); + self.music_policy.take_staging(handle_id); self.scene_policy.take_staging(handle_id); } @@ -855,6 +891,7 @@ impl AssetManager { match slot.asset_type { BankType::GLYPH => self.gfx_slots.read().unwrap().get(slot.index).and_then(|s| *s), BankType::SOUNDS => self.sound_slots.read().unwrap().get(slot.index).and_then(|s| *s), + BankType::MUSIC => self.music_slots.read().unwrap().get(slot.index).and_then(|s| *s), BankType::SCENE => self.scene_slots.read().unwrap().get(slot.index).and_then(|s| *s), } } @@ -874,6 +911,7 @@ impl AssetManager { let slot = match entry.bank_type { BankType::GLYPH => SlotRef::gfx(slot_index), BankType::SOUNDS => SlotRef::audio(slot_index), + BankType::MUSIC => SlotRef::music(slot_index), BankType::SCENE => SlotRef::scene(slot_index), }; @@ -899,6 +937,14 @@ impl AssetManager { false } } + BankType::MUSIC => { + if let Some(bank) = self.music_policy.get_resident(asset_id) { + self.music_policy.stage(handle_id, bank, entry.decoded_size as usize); + true + } else { + false + } + } BankType::SCENE => { if let Some(bank) = self.scene_policy.get_resident(asset_id) { self.scene_policy.stage(handle_id, bank, entry.decoded_size as usize); @@ -1081,6 +1127,57 @@ impl AssetManager { } } } + BankType::MUSIC => { + let result = + Self::perform_load_music_bank(&job.entry, Arc::clone(resources.assets_data)); + match result { + Ok(musicbank) => { + if !Self::is_current_target_generation( + resources.target_generations, + job.slot, + job.request_generation, + ) { + resources.pipeline_telemetry.lock().unwrap().record_stale_discard(); + return; + } + let bank_arc = Arc::new(musicbank); + let resident_arc = resources.music_policy.put_resident( + job.asset_id, + bank_arc, + job.entry.decoded_size as usize, + ); + if !Self::is_current_target_generation( + resources.target_generations, + job.slot, + job.request_generation, + ) { + resources.pipeline_telemetry.lock().unwrap().record_stale_discard(); + return; + } + resources.music_policy.stage( + job.handle_id, + resident_arc, + job.entry.decoded_size as usize, + ); + Self::complete_load_job(resources.handles, &job, LoadStatus::READY); + Self::record_load_job_finished( + resources.pipeline_telemetry, + &job, + started_at, + LoadStatus::READY, + ); + } + Err(_) => { + Self::complete_load_job(resources.handles, &job, LoadStatus::ERROR); + Self::record_load_job_finished( + resources.pipeline_telemetry, + &job, + started_at, + LoadStatus::ERROR, + ); + } + } + } BankType::SCENE => { let result = Self::perform_load_scene_bank(&job.entry, Arc::clone(resources.assets_data)); @@ -1268,6 +1365,32 @@ impl AssetManager { } } + fn perform_load_music_bank( + entry: &AssetEntry, + assets_data: Arc>, + ) -> Result { + let op_mode = Self::op_mode_for(entry)?; + let slice = { + let assets_data = assets_data.read().unwrap(); + assets_data + .open_slice(entry.offset, entry.size) + .map_err(|_| "Asset offset/size out of bounds".to_string())? + }; + + match op_mode { + AssetOpMode::DirectFromSlice => { + let mut reader = + slice.open_reader().map_err(|_| "Asset payload read failed".to_string())?; + Self::decode_music_bank_from_reader(entry, &mut reader) + } + AssetOpMode::StageInMemory => { + let buffer = + slice.read_all().map_err(|_| "Asset payload read failed".to_string())?; + Self::decode_music_bank_from_buffer(entry, &buffer) + } + } + } + fn perform_load_scene_bank( entry: &AssetEntry, assets_data: Arc>, @@ -1334,13 +1457,32 @@ impl AssetManager { entry: &AssetEntry, buffer: &[u8], ) -> Result { - let sample_rate = decode::sound_rate(entry)?; decode::payload_size(entry, buffer.len())?; - let mut data = Vec::with_capacity(buffer.len() / 2); - decode::append_pcm(&mut data, buffer); + let bank = decode_audio_bank(buffer, false)?; + if bank.decoded_size() as u64 != entry.decoded_size { + return Err("audio decoded_size mismatch".into()); + } + if let DecodedAudioBank::Sound(bank) = bank { + Ok(bank) + } else { + Err("audio bank type mismatch".into()) + } + } - let sample = Arc::new(Sample::new(sample_rate, data)); - Ok(SoundBank::new(vec![sample])) + fn decode_music_bank_from_buffer( + entry: &AssetEntry, + buffer: &[u8], + ) -> Result { + decode::payload_size(entry, buffer.len())?; + let bank = decode_audio_bank(buffer, true)?; + if bank.decoded_size() as u64 != entry.decoded_size { + return Err("audio decoded_size mismatch".into()); + } + if let DecodedAudioBank::Music(bank) = bank { + Ok(bank) + } else { + Err("audio bank type mismatch".into()) + } } fn decode_sound_bank_from_reader( @@ -1352,6 +1494,15 @@ impl AssetManager { Self::decode_sound_bank_from_buffer(entry, &raw) } + fn decode_music_bank_from_reader( + entry: &AssetEntry, + reader: &mut impl Read, + ) -> Result { + let mut raw = Vec::new(); + reader.read_to_end(&mut raw).map_err(|_| "Asset payload read failed".to_string())?; + Self::decode_music_bank_from_buffer(entry, &raw) + } + pub fn status(&self, handle: HandleId) -> LoadStatus { if let Some(status) = self.handles.read().unwrap().get(&handle).map(|h| h.status) { return status; @@ -1480,6 +1631,7 @@ impl AssetManager { let slot_ref = match bank_type { BankType::GLYPH => SlotRef::gfx(slot), BankType::SOUNDS => SlotRef::audio(slot), + BankType::MUSIC => SlotRef::music(slot), BankType::SCENE => SlotRef::scene(slot), }; let handle = self.handle_for_slot(slot_ref); @@ -1595,6 +1747,16 @@ impl AssetManager { h.status = LoadStatus::COMMITTED; } } + BankType::MUSIC => { + if let Some((bank, _)) = self.music_policy.take_staging(handle_id) { + self.sound_installer.install_music_bank(h.slot.index, bank); + let mut slots = self.music_slots.write().unwrap(); + if h.slot.index < slots.len() { + slots[h.slot.index] = Some(h._asset_id); + } + h.status = LoadStatus::COMMITTED; + } + } BankType::SCENE => { if let Some((bank, _)) = self.scene_policy.take_staging(handle_id) { self.scene_installer.install_scene_bank(h.slot.index, bank); @@ -1609,12 +1771,57 @@ impl AssetManager { } } } + self.reap_audio_cache(); + } + + fn reap_audio_cache(&self) { + fn reap(policy: &BankPolicy, slots: &[Option; 16]) { + let mut resident = policy.resident.write().unwrap(); + resident.retain(|id, entry| { + let keep = slots.contains(&Some(*id)) || Arc::strong_count(&entry.value) > 1; + if !keep { + policy.used_bytes.fetch_sub(entry.bytes, Ordering::Relaxed); + } + keep + }); + } + reap(&self.sound_policy, &self.sound_slots.read().unwrap()); + reap(&self.music_policy, &self.music_slots.read().unwrap()); + } + + pub fn unload_audio(&self, music: bool, slot: usize) -> AssetOpStatus { + if slot >= 16 { + return AssetOpStatus::InvalidState; + } + let target = if music { SlotRef::music(slot) } else { SlotRef::audio(slot) }; + self.bump_target_generation(target); + if let Some(handle) = self.target_handles.read().unwrap().get(&target).copied() { + self.clear_staging_for_handle(handle); + if let Some(h) = self.handles.write().unwrap().get_mut(&handle) { + h.status = LoadStatus::CANCELED; + } + } + let slots = if music { &self.music_slots } else { &self.sound_slots }; + let mut ids = slots.write().unwrap(); + let previous = ids[slot].take(); + self.sound_installer.unload_audio_bank(music, slot); + if let Some(id) = previous.filter(|id| !ids.contains(&Some(*id))) { + if music { + if let Some(old) = self.music_policy.resident.write().unwrap().remove(&id) { + self.music_policy.used_bytes.fetch_sub(old.bytes, Ordering::Relaxed); + } + } else if let Some(old) = self.sound_policy.resident.write().unwrap().remove(&id) { + self.sound_policy.used_bytes.fetch_sub(old.bytes, Ordering::Relaxed); + } + } + AssetOpStatus::Ok } pub fn bank_telemetry(&self) -> Vec { vec![ self.bank_telemetry_for(BankType::GLYPH), self.bank_telemetry_for(BankType::SOUNDS), + self.bank_telemetry_for(BankType::MUSIC), self.bank_telemetry_for(BankType::SCENE), ] } @@ -1627,6 +1834,9 @@ impl AssetManager { BankType::SOUNDS => { self.sound_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count() } + BankType::MUSIC => { + self.music_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count() + } BankType::SCENE => { self.scene_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count() } @@ -1679,6 +1889,27 @@ impl AssetManager { SlotStats { asset_id, asset_name, generation: 0, resident_bytes: bytes } } + BankType::MUSIC => { + let slots = self.music_slots.read().unwrap(); + let asset_id = slots.get(slot.index).and_then(|s| *s); + + let (bytes, asset_name) = if let Some(id) = &asset_id { + let bytes = self + .music_policy + .resident + .read() + .unwrap() + .get(id) + .map(|entry| entry.bytes) + .unwrap_or(0); + let name = self.assets.read().unwrap().get(id).map(|e| e.asset_name.clone()); + (bytes, name) + } else { + (0, None) + }; + + SlotStats { asset_id, asset_name, generation: 0, resident_bytes: bytes } + } BankType::SCENE => { let slots = self.scene_slots.read().unwrap(); let asset_id = slots.get(slot.index).and_then(|s| *s); @@ -1711,6 +1942,7 @@ impl AssetManager { } self.gfx_policy.clear(); self.sound_policy.clear(); + self.music_policy.clear(); self.scene_policy.clear(); self.handles.write().unwrap().clear(); self.target_handles.write().unwrap().clear(); @@ -1721,9 +1953,11 @@ impl AssetManager { self.gfx_slots.write().unwrap().fill(None); self.glyph_slot_index.clear(); self.sound_slots.write().unwrap().fill(None); + self.music_slots.write().unwrap().fill(None); self.scene_slots.write().unwrap().fill(None); self.gfx_installer.clear_glyph_banks(); self.sound_installer.clear_sound_banks(); + self.sound_installer.clear_music_banks(); self.scene_installer.clear_scene_banks(); } @@ -2512,7 +2746,7 @@ mod tests { let scene_installer = Arc::clone(&banks) as Arc; // 100 samples of 16-bit PCM (zeros) - let data = vec![0u8; 200]; + let data = crate::bank_format::test_pcm_bank(&[0u8; 200], 44100); let asset_entry = AssetEntry { asset_id: 1, @@ -2558,7 +2792,7 @@ mod tests { let sound_installer = Arc::clone(&banks) as Arc; let scene_installer = Arc::clone(&banks) as Arc; - let data = vec![0u8; 200]; + let data = crate::bank_format::test_pcm_bank(&[0u8; 200], 44100); let asset_entry = AssetEntry { asset_id: 2, diff --git a/crates/console/prometeu-drivers/src/asset/decode.rs b/crates/console/prometeu-drivers/src/asset/decode.rs index dcc4397..261bdf6 100644 --- a/crates/console/prometeu-drivers/src/asset/decode.rs +++ b/crates/console/prometeu-drivers/src/asset/decode.rs @@ -69,13 +69,6 @@ pub(super) fn write_palettes( palettes[at / 16][at % 16] = Color::rgba(rgba[0], rgba[1], rgba[2], rgba[3]); } } -pub(super) fn sound_rate(entry: &AssetEntry) -> Result { - Ok(entry.metadata_as_sound_bank()?.sample_rate) -} -// Callers split on even chunk boundaries. Only the final odd byte is ignored. -pub(super) fn append_pcm(data: &mut Vec, bytes: &[u8]) { - data.extend(bytes.as_chunks::<2>().0.iter().map(|p| i16::from_le_bytes(*p))); -} pub(super) fn payload_size(entry: &AssetEntry, actual: usize) -> Result<(), String> { if actual as u64 != entry.size { return Err("Invalid asset payload size".into()); diff --git a/crates/console/prometeu-drivers/src/asset/decode/tests.rs b/crates/console/prometeu-drivers/src/asset/decode/tests.rs index 8c21f7f..232da84 100644 --- a/crates/console/prometeu-drivers/src/asset/decode/tests.rs +++ b/crates/console/prometeu-drivers/src/asset/decode/tests.rs @@ -32,47 +32,33 @@ fn pcm_entry(size: u64) -> AssetEntry { } #[test] -fn pcm_chunk_edges_and_odd_tails_have_explicit_baseline_outputs() { +fn pcm_chunk_edges_validate_all_declared_frames_and_reject_odd_tails() { for len in [0, 1, 2, 3, 4095, 4096, 4097, 8191, 8192, 8193] { - let bytes: Vec = (0..len).map(|i| if i % 2 == 0 { 0x34 } else { 0x12 }).collect(); - let entry = pcm_entry(len as u64); - let expected = json!([[vec![0x1234_i16; len / 2], 44100, null, null]]); - let buffer = AssetManager::decode_sound_bank_from_buffer(&entry, &bytes).unwrap(); - let reader = AssetManager::decode_sound_bank_from_reader(&entry, &mut &bytes[..]).unwrap(); - let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes))); - let production = AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap(); - assert_eq!(sound_snapshot(&buffer), expected, "buffer len={len}"); - assert_eq!(sound_snapshot(&reader), expected, "reader len={len}"); - assert_eq!(sound_snapshot(&production), expected, "legacy load len={len}"); - assert_eq!( - resumable::conformance_result(&entry, &source).unwrap(), - expected, - "resumable len={len}" - ); + let raw: Vec = (0..len).map(|i| if i % 2 == 0 { 0x34 } else { 0x12 }).collect(); + let bytes = crate::bank_format::test_pcm_bank(&raw, 44100); + let expected = if len % 2 == 0 { + Some(json!([[vec![0x1234_i16; len / 2], 44100, null, null]])) + } else { + None + }; + check_case("pcm-chunk", &pcm_entry(bytes.len() as u64), bytes, expected); } } - #[test] -fn physically_truncated_pcm_file_is_rejected_by_both_modes() { - // Two actual bytes, three declared bytes: the missing byte is an odd tail. - // The approved rule rejects missing declared bytes, including an odd tail. - let fixture = FileFixture::new("truncated-pcm", &[0x34, 0x12]); - let entry = pcm_entry(3); - let source = fixture.source(3); +fn physically_truncated_pcm_file_is_rejected_by_all_modes() { + let bytes = crate::bank_format::test_pcm_bank(&[0x34, 0x12], 44100); + let entry = pcm_entry(bytes.len() as u64); + let fixture = FileFixture::new("truncated-pcm", &bytes[..bytes.len() - 1]); + let source = fixture.source(bytes.len() as u64); assert!(AssetManager::perform_load_sound_bank(&entry, source.clone()).is_err()); assert!(resumable::conformance_result(&entry, &source).is_err()); - // With the declared byte physically present, both accept and ignore it. - std::fs::write(&fixture.0, [0x34, 0x12, 0xff]).unwrap(); + std::fs::write(&fixture.0, &bytes).unwrap(); let expected = json!([[[0x1234], 44100, null, null]]); assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected); assert_eq!( - sound_snapshot(&AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap()), + sound_snapshot(&AssetManager::perform_load_sound_bank(&entry, source).unwrap()), expected ); - // Memory carriers reject the range before either decoder can accept it. - let memory = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(vec![0x34, 0x12]))); - assert!(AssetManager::perform_load_sound_bank(&entry, memory.clone()).is_err()); - assert!(resumable::conformance_result(&entry, &memory).is_err()); } #[test] @@ -129,6 +115,8 @@ fn check_case(name: &str, entry: &AssetEntry, bytes: Vec, expected: Option AssetManager::perform_load_music_bank(entry, source.clone()) + .map(|b| music_snapshot(&b)), BankType::SCENE => AssetManager::perform_load_scene_bank(entry, source.clone()) .map(|b| scene_snapshot(&b)), }; @@ -153,6 +141,8 @@ fn check_case(name: &str, entry: &AssetEntry, bytes: Vec, expected: Option AssetManager::decode_music_bank_from_buffer(entry, &bytes) + .map(|b| music_snapshot(&b)), (BankType::SCENE, 0) => AssetManager::decode_scene_bank_from_buffer(entry, &bytes) .map(|b| scene_snapshot(&b)), (BankType::SCENE, _) => { @@ -319,35 +309,29 @@ fn scene_tile_chunk_edges_flags_and_reserved_bytes() { } #[test] -fn pcm_metadata_and_source_range_corpus() { - for metadata in [ - json!(null), - json!({}), - json!({"sample_rate":-1,"channels":1}), - json!({"sample_rate":44100,"channels":"bad"}), - ] { - let mut e = pcm_entry(2); - e.metadata = metadata; - check_case("pcm-metadata", &e, vec![0x34, 0x12], None); +fn pcm_descriptor_and_source_range_corpus() { + let bytes = crate::bank_format::test_pcm_bank(&[0x34, 0x12], 44100); + let entry = pcm_entry(bytes.len() as u64); + // Audio metadata lives in the versioned payload, so it can vary per sample. + for (offset, value) in + [(48, 99u32), (49, 0), (52, 0), (56, 2), (60, 1), (68, 0), (72, 3), (84, 0)] + { + let mut invalid = bytes.clone(); + if offset == 48 || offset == 49 { + invalid[offset] = value as u8; + } else { + invalid[offset..offset + 4].copy_from_slice(&value.to_le_bytes()); + } + check_case("descriptor", &entry, invalid, None); } - // These fields are currently descriptive, not extra PCM layout constraints. - let mut e = pcm_entry(2); - e.metadata = json!({"sample_rate":0,"channels":0}); - e.decoded_size = 999; - check_case( - "pcm-permissive-metadata", - &e, - vec![0x34, 0x12], - Some(json!([[[0x1234], 0, null, null]])), - ); for offset in [1, u64::MAX] { - let mut e = pcm_entry(2); - e.offset = offset; - check_case("source-range", &e, vec![0x34, 0x12], None); + let mut invalid = entry.clone(); + invalid.offset = offset; + check_case("source-range", &invalid, bytes.clone(), None); } - let mut e = pcm_entry(2); - e.size = u64::MAX; - check_case("source-size-overflow", &e, vec![0x34, 0x12], None); + let mut invalid = entry; + invalid.decoded_size += 1; + check_case("decoded-size", &invalid, bytes, None); } pub(in crate::asset) fn glyph_snapshot(bank: &GlyphBank) -> Value { @@ -430,3 +414,48 @@ fn physically_truncated_glyph_palette_is_rejected_by_both_modes() { ); assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected); } + +pub(in crate::asset) fn music_snapshot(bank: &prometeu_hal::music_bank::MusicBank) -> Value { + json!({"name": bank.name, "events": bank.events.len(), "pcm": bank.metrics.pcm_bytes}) +} + +#[test] +fn mixed_audio_fixtures_conform_across_all_asset_decode_modes() { + for (music, bytes) in [ + ( + false, + &include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-sound.sbnk" + ))[..], + ), + ( + true, + &include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-music.mbnk" + ))[..], + ), + ] { + let decoded = crate::bank_format::decode_audio_bank(bytes, music).unwrap(); + let size = decoded.decoded_size(); + let expected = match decoded { + DecodedAudioBank::Sound(b) => sound_snapshot(&b), + DecodedAudioBank::Music(b) => music_snapshot(&b), + }; + let entry = AssetEntry { + asset_id: 7, + asset_name: "mixed".into(), + bank_type: if music { BankType::MUSIC } else { BankType::SOUNDS }, + offset: 0, + size: bytes.len() as u64, + decoded_size: size as u64, + codec: AssetCodec::None, + metadata: json!({"version":1}), + }; + check_case("mixed-audio", &entry, bytes.to_vec(), Some(expected)); + let mut invalid = bytes.to_vec(); + invalid[0] = 0; + check_case("mixed-bad-magic", &entry, invalid, None); + } +} diff --git a/crates/console/prometeu-drivers/src/asset/resumable.rs b/crates/console/prometeu-drivers/src/asset/resumable.rs index 11be923..40d70a7 100644 --- a/crates/console/prometeu-drivers/src/asset/resumable.rs +++ b/crates/console/prometeu-drivers/src/asset/resumable.rs @@ -11,6 +11,7 @@ pub(super) struct Resources { telemetry: Arc>, gfx: BankPolicy, sound: BankPolicy, + music: BankPolicy, scene: BankPolicy, } impl Resources { @@ -22,6 +23,7 @@ impl Resources { telemetry: m.pipeline_telemetry.clone(), gfx: m.gfx_policy.clone(), sound: m.sound_policy.clone(), + music: m.music_policy.clone(), scene: m.scene_policy.clone(), } } @@ -142,6 +144,18 @@ pub(super) fn schedule( job.entry.decoded_size as usize, ); } + Decoded::Music(bank) => { + let resident = resources.music.put_resident( + job.asset_id, + Arc::new(bank), + job.entry.decoded_size as usize, + ); + resources.music.stage( + job.handle_id, + resident, + job.entry.decoded_size as usize, + ); + } Decoded::Scene(bank) => { let resident = resources.scene.put_resident( job.asset_id, @@ -188,6 +202,7 @@ pub(super) fn schedule( enum Decoded { Glyph(GlyphBank), Sound(SoundBank), + Music(MusicBank), Scene(SceneBank), } enum State { @@ -199,10 +214,11 @@ enum State { palette_position: usize, }, Sound { - sample_rate: u32, - data: Vec, + raw: Vec, remaining: usize, + music: bool, }, + Audio(Box>), Scene { layers: [SceneLayer; SCENE_LAYER_COUNT_V1], layer: usize, @@ -245,12 +261,16 @@ impl Decoder { palette_position: 0, } } - BankType::SOUNDS => { - let sample_rate = decode::sound_rate(entry)?; + BankType::SOUNDS | BankType::MUSIC => { + let mut raw = Vec::new(); + raw.try_reserve_exact( + usize::try_from(entry.size).map_err(|_| "audio size overflow")?, + ) + .map_err(|_| "audio allocation failed")?; State::Sound { - sample_rate, - data: Vec::with_capacity(entry.size as usize / 2), + raw, remaining: entry.size as usize, + music: entry.bank_type == BankType::MUSIC, } } BankType::SCENE => { @@ -294,18 +314,34 @@ impl Decoder { }; Ok(Some(Decoded::Glyph(bank))) } - State::Sound { sample_rate, data, remaining } => { + State::Sound { raw, remaining, music } => { if *remaining > 0 { - let n = (*remaining).min(bytes.len()); - self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?; - decode::append_pcm(data, &bytes[..n]); + let n = (*remaining).min(4096); + let mut buffer = [0; 4096]; + self.reader.read_exact(&mut buffer[..n]).map_err(|e| e.to_string())?; + raw.extend_from_slice(&buffer[..n]); *remaining -= n; return Ok(None); } - let rate = *sample_rate; - let data = std::mem::take(data); + let decoder = crate::bank_format::AudioBankMaterializer::new( + std::borrow::Cow::Owned(std::mem::take(raw)), + *music, + )?; + self.state = State::Audio(Box::new(decoder)); + Ok(None) + } + State::Audio(decoder) => { + let Some(bank) = decoder.step()? else { + return Ok(None); + }; + if bank.decoded_size() as u64 != self.entry.decoded_size { + return Err("audio decoded_size mismatch".into()); + } self.state = State::Done; - Ok(Some(Decoded::Sound(SoundBank::new(vec![Arc::new(Sample::new(rate, data))])))) + Ok(Some(match bank { + DecodedAudioBank::Sound(b) => Decoded::Sound(b), + DecodedAudioBank::Music(b) => Decoded::Music(b), + })) } State::Scene { layers, layer, tiles_left, header, decoded } => { if !*header { @@ -372,6 +408,7 @@ pub(super) fn conformance_result( Decoded::Glyph(bank) => super::decode::tests::glyph_snapshot(&bank), Decoded::Sound(bank) => super::decode::tests::sound_snapshot(&bank), Decoded::Scene(bank) => super::decode::tests::scene_snapshot(&bank), + Decoded::Music(bank) => super::decode::tests::music_snapshot(&bank), }); } } @@ -448,9 +485,12 @@ mod tests { panic!("decoder did not finish") } #[test] - fn resumable_sound_and_scene_preserve_existing_formats() { + fn resumable_audio_bank_and_scene_use_canonical_formats() { let pcm: Vec = (0..5000).map(|n| n as i16 - 2500).collect(); - let bytes: Vec = pcm.iter().flat_map(|n| n.to_le_bytes()).collect(); + let bytes = crate::bank_format::test_pcm_bank( + &pcm.iter().flat_map(|n| n.to_le_bytes()).collect::>(), + 44100, + ); let entry = AssetEntry { asset_id: 1, asset_name: "pcm".into(), @@ -485,7 +525,7 @@ mod tests { } #[test] fn shared_preload_waits_for_worker_and_frame_publication() { - let bytes = vec![0; 8192]; + let bytes = crate::bank_format::test_pcm_bank(&[0; 8192], 44100); let entry = AssetEntry { asset_id: 1, asset_name: "pcm".into(), @@ -521,7 +561,7 @@ mod tests { #[test] fn canceled_and_superseded_partial_decoders_never_publish() { use crate::memory_banks::SoundBankPoolAccess; - let bytes = vec![0x12; 16384]; + let bytes = crate::bank_format::test_pcm_bank(&[0x12; 16384], 44100); let entry = AssetEntry { asset_id: 1, asset_name: "pcm".into(), diff --git a/crates/console/prometeu-drivers/src/audio.rs b/crates/console/prometeu-drivers/src/audio.rs index a43b5f4..c967fe0 100644 --- a/crates/console/prometeu-drivers/src/audio.rs +++ b/crates/console/prometeu-drivers/src/audio.rs @@ -1,8 +1,14 @@ -use prometeu_hal::{AudioBridge, AudioOpStatus}; +use prometeu_hal::music_bank::MusicBank; +use prometeu_hal::{AudioBridge, AudioOpStatus, audio_bridge::AudioControl}; use std::sync::Arc; +use std::sync::atomic::AtomicBool; +pub mod bank_format; /// Maximum number of simultaneous audio voices supported by the hardware. -pub const MAX_CHANNELS: usize = 16; +pub const MAX_CHANNELS: usize = 32; +pub const SFX_CHANNELS: usize = 8; +pub const SFX_START: usize = 24; +pub mod engine; /// Standard sample rate for the final audio output. pub const OUTPUT_SAMPLE_RATE: u32 = 48000; @@ -19,13 +25,14 @@ pub struct Channel { pub sample: Option>, /// Whether this channel is currently active. pub active: bool, + pub alive: Option>, /// Current playback position within the sample (fractional for pitch shifting). pub pos: f64, /// Playback speed multiplier (1.0 = original speed). pub pitch: f64, /// Voice volume (0-255). pub volume: u8, - /// Stereo panning (0=Full Left, 127=Center, 255=Full Right). + /// Stereo panning (0=Full Left, 128=Center, 255=Full Right). pub pan: u8, /// Loop configuration for this voice. pub loop_mode: LoopMode, @@ -38,10 +45,11 @@ impl Default for Channel { Self { sample: None, active: false, + alive: None, pos: 0.0, pitch: 1.0, volume: 255, - pan: 127, + pan: 128, loop_mode: LoopMode::Off, priority: 0, } @@ -53,9 +61,16 @@ impl Default for Channel { /// Because the Core logic runs at 60Hz and Audio is generated at 48kHz, /// we use an asynchronous command queue to synchronize them. pub enum AudioCommand { + MusicPlay { + group: usize, + bank: Arc, + looping: bool, + }, + Control(AudioControl), /// Start playing a sample on a specific voice. Play { sample: Arc, + alive: Option>, voice_id: usize, volume: u8, pan: u8, @@ -64,13 +79,24 @@ pub enum AudioCommand { loop_mode: LoopMode, }, /// Stop playback on a voice when this command is applied. - Stop { voice_id: usize }, + Stop { + voice_id: usize, + }, /// Update volume of an ongoing playback. - SetVolume { voice_id: usize, volume: u8 }, + SetVolume { + voice_id: usize, + volume: u8, + }, /// Update panning of an ongoing playback. - SetPan { voice_id: usize, pan: u8 }, + SetPan { + voice_id: usize, + pan: u8, + }, /// Update pitch of an ongoing playback. - SetPitch { voice_id: usize, pitch: f64 }, + SetPitch { + voice_id: usize, + pitch: f64, + }, } mod transport; @@ -109,7 +135,7 @@ impl Audio { } fn enqueue(&mut self, voice: usize, command: AudioCommand) -> AudioOpStatus { - if voice >= MAX_CHANNELS { + if voice >= SFX_CHANNELS { return AudioOpStatus::VoiceInvalid; } let admitted = if self.in_lifecycle { @@ -142,7 +168,7 @@ impl AudioBridge for Audio { priority: u8, loop_mode: LoopMode, ) -> AudioOpStatus { - if voice_id >= MAX_CHANNELS { + if voice_id >= SFX_CHANNELS { return AudioOpStatus::VoiceInvalid; } if !pitch.is_finite() || pitch <= 0.0 { @@ -154,7 +180,19 @@ impl AudioBridge for Audio { let Some(sample) = bank.samples.get(sample_id as usize).cloned() else { return AudioOpStatus::SampleNotFound; }; - self.play_sample(sample, voice_id, volume, pan, pitch, priority, loop_mode) + self.enqueue( + voice_id, + AudioCommand::Play { + sample, + alive: Some(bank.alive.clone()), + voice_id, + volume, + pan, + pitch, + priority, + loop_mode, + }, + ) } fn play_sample( @@ -167,7 +205,7 @@ impl AudioBridge for Audio { priority: u8, loop_mode: LoopMode, ) -> AudioOpStatus { - if voice_id >= MAX_CHANNELS { + if voice_id >= SFX_CHANNELS { return AudioOpStatus::VoiceInvalid; } if !pitch.is_finite() || pitch <= 0.0 { @@ -175,10 +213,57 @@ impl AudioBridge for Audio { } self.enqueue( voice_id, - AudioCommand::Play { sample, voice_id, volume, pan, pitch, priority, loop_mode }, + AudioCommand::Play { + sample, + alive: None, + voice_id, + volume, + pan, + pitch, + priority, + loop_mode, + }, ) } + fn music_play(&mut self, group: usize, bank: usize, looping: bool) -> AudioOpStatus { + if group > 1 { + return AudioOpStatus::ArgRangeInvalid; + } + let Some(bank) = self.sound_banks.music_bank_slot(bank) else { + return AudioOpStatus::BankInvalid; + }; + self.enqueue(0, AudioCommand::MusicPlay { group, bank, looping }) + } + fn control(&mut self, control: AudioControl) -> AudioOpStatus { + let valid = match control { + AudioControl::MusicStop { group } + | AudioControl::MusicPause { group, .. } + | AudioControl::MusicVolume { group, .. } + | AudioControl::MusicFade { group, .. } => group < 2, + AudioControl::Crossfade { source, target, .. } => { + source < 2 && target < 2 && source != target + } + AudioControl::BusVolume { bus, .. } => bus < 3, + AudioControl::GroupVolume { group, .. } => group < 3, + AudioControl::SfxSend { voice, .. } => voice < SFX_CHANNELS, + AudioControl::Effect { group, cutoff_hz, delay_frames, feedback, wet, dry } => { + group < 3 + && cutoff_hz <= OUTPUT_SAMPLE_RATE / 2 + && delay_frames <= 96_000 + && feedback.is_finite() + && feedback.abs() < 1.0 + && wet.is_finite() + && dry.is_finite() + && (0.0..=1.0).contains(&wet) + && (0.0..=1.0).contains(&dry) + } + }; + if !valid { + return AudioOpStatus::ArgRangeInvalid; + } + self.enqueue(0, AudioCommand::Control(control)) + } fn stop(&mut self, voice_id: usize) -> AudioOpStatus { self.enqueue(voice_id, AudioCommand::Stop { voice_id }) } @@ -189,7 +274,7 @@ impl AudioBridge for Audio { self.enqueue(voice_id, AudioCommand::SetPan { voice_id, pan }) } fn set_pitch(&mut self, voice_id: usize, pitch: f64) -> AudioOpStatus { - if voice_id >= MAX_CHANNELS { + if voice_id >= SFX_CHANNELS { return AudioOpStatus::VoiceInvalid; } if !pitch.is_finite() || pitch <= 0.0 { @@ -311,7 +396,7 @@ mod control_tests { for _ in 0..MAX_COMMANDS_PER_FRAME - 1 { assert_eq!(audio.stop(0), AudioOpStatus::Ok); } - assert_eq!(audio.set_volume(15, 0), AudioOpStatus::Ok); + assert_eq!(audio.set_volume(7, 0), AudioOpStatus::Ok); assert_eq!(audio.set_pan(0, 255), AudioOpStatus::CommandLimit); assert_eq!(audio.set_pitch(16, f64::NAN), AudioOpStatus::VoiceInvalid); assert_eq!(audio.set_pitch(0, f64::NAN), AudioOpStatus::ArgRangeInvalid); diff --git a/crates/console/prometeu-drivers/src/audio/bank_format.rs b/crates/console/prometeu-drivers/src/audio/bank_format.rs new file mode 100644 index 0000000..7d37be3 --- /dev/null +++ b/crates/console/prometeu-drivers/src/audio/bank_format.rs @@ -0,0 +1,592 @@ +//! 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; diff --git a/crates/console/prometeu-drivers/src/audio/bank_tests.rs b/crates/console/prometeu-drivers/src/audio/bank_tests.rs new file mode 100644 index 0000000..0a1ab2e --- /dev/null +++ b/crates/console/prometeu-drivers/src/audio/bank_tests.rs @@ -0,0 +1,182 @@ +use super::*; +use crate::{AssetManager, MemoryBanks, SoundBankPoolAccess}; +use prometeu_hal::{ + asset::{AssetCodec, AssetEntry, AssetOpStatus, BankType, LoadStatus, SlotRef}, + cartridge::AssetsPayloadSource, +}; +use std::time::{Duration, Instant}; +fn fixtures() -> Vec<(&'static [u8], bool)> { + vec![ + ( + include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/pcm-only.sbnk" + )), + false, + ), + ( + include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/ima-only.sbnk" + )), + false, + ), + ( + include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-sound.sbnk" + )), + false, + ), + ( + include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-music.mbnk" + )), + true, + ), + ] +} +#[test] +fn packer_binary_fixtures_materialize_mixed_stereo_banks_and_separate_encoded_from_pcm_sizes() { + for (index, (bytes, music)) in fixtures().into_iter().enumerate() { + let decoded = decode_audio_bank(bytes, music).unwrap(); + let (samples, metrics) = match &decoded { + DecodedAudioBank::Sound(b) => (&b.samples, b.metrics), + DecodedAudioBank::Music(b) => { + assert_eq!(b.events.len(), 4); + assert_eq!(b.instruments.len(), 2); + assert_eq!(b.tracks, 2); + (&b.samples, b.metrics) + } + }; + assert_eq!(metrics.cartridge_bytes, bytes.len()); + assert_eq!(metrics.pcm_bytes, if index < 2 { 2000 } else { 6000 }); + assert_eq!(samples[0].frames_len(), 1000); + assert_eq!(samples[0].loop_end, Some(1000)); + if index >= 2 { + assert_eq!(samples[1].channels, 2); + assert_eq!(samples[1].frames_len(), 1000); + } + if index != 0 { + assert!(decoded.decoded_size() > bytes.len()); + } + } +} +#[test] +fn complete_validation_rejects_truncation_unknown_codec_bad_loops_and_reserved_bytes() { + for (bytes, music) in fixtures() { + for cut in [0, 4, 47, 48, bytes.len() - 1] { + assert!(decode_audio_bank(&bytes[..cut], music).is_err()); + } + let name = u32le(bytes, 40).unwrap() as usize; + let sample = 48 + name; + for (at, value) in + [(4, 2), (44, 1), (sample, 99), (sample + 1, 3), (sample + 2, 2), (sample + 34, 1)] + { + let mut bad = bytes.to_vec(); + bad[at] = value; + assert!(decode_audio_bank(&bad, music).is_err(), "{at}"); + } + let mut bad = bytes.to_vec(); + bad[sample + 12..sample + 16].copy_from_slice(&1001u32.to_le_bytes()); + assert!(decode_audio_bank(&bad, music).is_err()); + let mut bad = bytes.to_vec(); + bad.push(0); + assert!(decode_audio_bank(&bad, music).is_err()); + // Mutating every byte must produce either a validated bank or a clean error. + for i in 0..bytes.len() { + let mut changed = bytes.to_vec(); + changed[i] ^= 0xff; + let _ = decode_audio_bank(&changed, music); + } + } +} +fn entry(id: i32, offset: usize, bytes: &[u8], music: bool) -> AssetEntry { + AssetEntry { + asset_id: id, + asset_name: format!("bank{id}"), + bank_type: if music { BankType::MUSIC } else { BankType::SOUNDS }, + offset: offset as u64, + size: bytes.len() as u64, + decoded_size: decode_audio_bank(bytes, music).unwrap().decoded_size() as u64, + codec: AssetCodec::None, + metadata: serde_json::json!({"version":1}), + } +} +fn ready(manager: &AssetManager, handle: u32) { + let end = Instant::now() + Duration::from_secs(3); + while matches!( + manager.status(handle), + LoadStatus::QUEUED | LoadStatus::LOADING | LoadStatus::PENDING | LoadStatus::ACTIVE + ) { + assert!(Instant::now() < end); + std::thread::yield_now(); + } + assert_eq!(manager.status(handle), LoadStatus::READY); +} +#[test] +fn audio_loading_commit_replacement_and_unload_are_atomic_and_type_isolated() { + let fixtures = fixtures(); + let sound = fixtures[2].0; + let music = fixtures[3].0; + let mut payload = sound.to_vec(); + payload.extend_from_slice(music); + let bad_at = payload.len(); + let mut corrupt = sound.to_vec(); + corrupt[0] = 0; + payload.extend(&corrupt); + let mut bad = entry(3, bad_at, sound, false); + bad.decoded_size += 1; + let banks = Arc::new(MemoryBanks::new()); + let manager = AssetManager::new( + vec![entry(1, 0, sound, false), entry(2, sound.len(), music, true), bad], + AssetsPayloadSource::from_bytes(payload), + banks.clone(), + banks.clone(), + banks.clone(), + ); + let s = manager.load(1, 0).unwrap(); + ready(&manager, s); + assert!(banks.sound_bank_slot(0).is_none()); + assert_eq!(manager.commit(s), AssetOpStatus::Ok); + manager.apply_commits(); + let old = banks.sound_bank_slot(0).unwrap(); + let m = manager.load(2, 0).unwrap(); + ready(&manager, m); + manager.commit(m); + manager.apply_commits(); + assert!(old.alive.load(std::sync::atomic::Ordering::Acquire)); + assert!(banks.music_bank_slot(0).is_some()); + let failing = manager.load(3, 0).unwrap(); + let end = Instant::now() + Duration::from_secs(3); + while manager.status(failing) != LoadStatus::ERROR { + assert!(Instant::now() < end); + std::thread::yield_now(); + } + manager.apply_commits(); + assert!(Arc::ptr_eq(&old, &banks.sound_bank_slot(0).unwrap())); + let replacement = manager.load(1, 0).unwrap(); + ready(&manager, replacement); + assert!(old.alive.load(std::sync::atomic::Ordering::Acquire)); + manager.commit(replacement); + manager.apply_commits(); + assert!(!old.alive.load(std::sync::atomic::Ordering::Acquire)); + assert_eq!(manager.unload_audio(true, 0), AssetOpStatus::Ok); + assert!(banks.music_bank_slot(0).is_none()); + assert!(banks.sound_bank_slot(0).is_some()); + assert_eq!(manager.slot_info(SlotRef::music(0)).asset_id, None); + assert_eq!(manager.unload_audio(false, 0), AssetOpStatus::Ok); + assert!(banks.sound_bank_slot(0).is_none()); + assert_eq!(manager.unload_audio(false, 16), AssetOpStatus::InvalidState); +} +#[test] +fn codec_tooling_rejects_overflowing_block_parameters_without_panicking() { + for align in [0, 4, usize::MAX - 3, usize::MAX] { + assert!(encode_ima_wav4(&[1, 2], 1, align).is_err()); + assert!(decode_ima_wav4(&[0; 8], 1, 9, align, 9).is_err()); + } + assert!(encode_ima_wav4(&[1], 1, 65532).is_err()); + assert!(decode_ima_wav4(&[0; 8], 1, usize::MAX, 8, 9).is_err()); + assert!(encode_ima_wav4(&[1], 0, 256).is_err()); +} diff --git a/crates/console/prometeu-drivers/src/audio/engine.rs b/crates/console/prometeu-drivers/src/audio/engine.rs new file mode 100644 index 0000000..82ef4d3 --- /dev/null +++ b/crates/console/prometeu-drivers/src/audio/engine.rs @@ -0,0 +1,924 @@ +//! Host-independent bounded PCM engine. Construct resources off the render lane. +use super::{ + AudioCommand, AudioDelivery, AudioTransport, Channel, LoopMode, MAX_CHANNELS, + MAX_COMMANDS_PER_FRAME, SFX_CHANNELS, SFX_START, +}; +use prometeu_hal::{ + audio_bridge::AudioControl, + music_bank::{Instrument, MAX_MUSIC_TRACKS, MusicBank, MusicEvent}, + sample::Sample, +}; +use std::{ + sync::{ + Arc, + atomic::{AtomicBool, Ordering}, + }, + time::{Duration, Instant}, +}; + +pub const RETIRED_CAPACITY: usize = 2 * (3 * MAX_COMMANDS_PER_FRAME + MAX_CHANNELS + 2); +/// Owning resources leave the real-time lane in a preallocated packet. +#[allow(dead_code)] +enum Retired { + Sample(Arc), + Bank(Arc), + Token(Arc), +} +pub struct Packet { + retired: Vec, + pub batches: [Option>; 2], +} +impl Default for Packet { + fn default() -> Self { + Self::new() + } +} +impl Packet { + pub fn new() -> Self { + Self { retired: Vec::with_capacity(RETIRED_CAPACITY), batches: [None, None] } + } + fn push(&mut self, owner: Retired) { + assert!(self.retired.len() < RETIRED_CAPACITY, "audio retirement bound"); + self.retired.push(owner); + } + fn voice(&mut self, voice: &mut Channel) { + if let Some(s) = voice.sample.take() { + self.push(Retired::Sample(s)); + } + if let Some(t) = voice.alive.take() { + self.push(Retired::Token(t)); + } + voice.active = false; + } + pub fn recycle(&mut self, transport: &AudioTransport) { + self.retired.clear(); + for batch in &mut self.batches { + if let Some(batch) = batch.take() { + transport.recycle_commands(batch); + } + } + } + /// Service thread only: count distinct retired PCM payloads, excluding Arc overhead. + pub fn retained_pcm_bytes(&self) -> usize { + let mut seen = std::collections::HashSet::new(); + let mut bytes = 0; + let mut add = |sample: &Arc| { + if seen.insert(Arc::as_ptr(sample)) { + bytes += sample.data.capacity() * 2; + } + }; + for owner in &self.retired { + match owner { + Retired::Sample(sample) => add(sample), + Retired::Bank(bank) => { + for sample in bank.samples.iter() { + add(sample); + } + } + Retired::Token(_) => {} + } + } + for batch in self.batches.iter().flatten() { + for command in batch { + match command { + AudioCommand::Play { sample, .. } => add(sample), + AudioCommand::MusicPlay { bank, .. } => { + for sample in bank.samples.iter() { + add(sample); + } + } + _ => {} + } + } + } + bytes + } + pub fn is_empty(&self) -> bool { + self.retired.is_empty() && self.batches.iter().all(Option::is_none) + } + pub fn capacity(&self) -> usize { + self.retired.capacity() + } +} + +#[derive(Clone, Copy)] +struct Ramp { + from: f64, + to: f64, + start: u64, + duration: u32, + smooth: bool, +} +impl Ramp { + fn constant(value: f64) -> Self { + Self { from: value, to: value, start: 0, duration: 0, smooth: false } + } + fn at(self, now: u64) -> f64 { + if self.duration == 0 { + return self.to; + } + let elapsed = now.saturating_sub(self.start); + if elapsed >= self.duration as u64 { + return self.to; + } + let x = elapsed as f64 / self.duration as f64; + let x = if self.smooth { x * x * (3.0 - 2.0 * x) } else { x }; + self.from + (self.to - self.from) * x + } + fn set(&mut self, value: f64, now: u64, duration: u32, smooth: bool) { + *self = Self { from: self.at(now), to: value, start: now, duration, smooth }; + } + fn done(self, now: u64) -> bool { + now.saturating_sub(self.start) >= self.duration as u64 + } +} +#[derive(Clone, Copy)] +struct SendRamp { + base: Ramp, + scale: Ramp, +} +impl Default for SendRamp { + fn default() -> Self { + Self { base: Ramp::constant(0.0), scale: Ramp::constant(1.0) } + } +} +impl SendRamp { + fn at(self, now: u64, instrument_default: f64) -> f64 { + self.base.at(now) + self.scale.at(now) * instrument_default + } + fn set(&mut self, to: f64, now: u64, frames: u32, smooth: bool) { + self.base.set(to, now, frames, smooth); + self.scale.set(0.0, now, frames, smooth); + } +} +#[derive(Clone, Copy)] +struct Track { + gain: Ramp, + pan: Ramp, + pitch: Ramp, + send: SendRamp, + vibrato: Option<(u32, f64)>, + tremolo: Option<(u32, f64)>, +} +impl Default for Track { + fn default() -> Self { + Self { + gain: Ramp::constant(1.0), + pan: Ramp::constant(128.0), + pitch: Ramp::constant(0.0), + send: SendRamp::default(), + vibrato: None, + tremolo: None, + } + } +} +struct MusicGroup { + bank: Option>, + active: bool, + paused: bool, + looping: bool, + time: u128, + cursor: usize, + frame: u64, + iteration: u64, + tracks: [Track; MAX_MUSIC_TRACKS], + gain: Ramp, + stop_after_fade: bool, +} +impl Default for MusicGroup { + fn default() -> Self { + Self { + bank: None, + active: false, + paused: false, + looping: false, + time: 0, + cursor: 0, + frame: 0, + iteration: 0, + tracks: [Track::default(); MAX_MUSIC_TRACKS], + gain: Ramp::constant(1.0), + stop_after_fade: false, + } + } +} +#[derive(Clone, Copy)] +struct VoiceState { + inst: Instrument, + track: usize, + note_id: u32, + iteration: u64, + born: u64, + age: u64, + release_age: Option, + release_level: f64, + release_order: Option, + level: f64, + cached_cents: f64, + pitch_factor: f64, + glide: Ramp, + send: f64, + zone: usize, +} +impl Default for VoiceState { + fn default() -> Self { + Self { + inst: Instrument::default(), + track: 0, + note_id: 0, + iteration: 0, + born: 0, + age: 0, + release_age: None, + release_level: 0.0, + release_order: None, + level: 1.0, + cached_cents: f64::INFINITY, + pitch_factor: 1.0, + glide: Ramp::constant(0.0), + send: 0.0, + zone: 0, + } + } +} +struct Effect { + delay: Vec<[f32; 2]>, + write: usize, + history: usize, + frames: usize, + feedback: f32, + wet: f32, + dry: f32, + coefficient: f32, + filter: [f32; 2], +} +impl Effect { + fn new() -> Self { + Self { + delay: vec![[0.0; 2]; 96_000], + write: 0, + history: 0, + frames: 0, + feedback: 0.0, + wet: 0.0, + dry: 1.0, + coefficient: 1.0, + filter: [0.0; 2], + } + } + fn reset(&mut self) { + self.write = 0; + self.history = 0; + self.filter = [0.0; 2]; + } + fn process(&mut self, input: [f32; 2], send: [f32; 2]) -> [f32; 2] { + if self.frames == 0 && self.coefficient == 1.0 { + self.filter = input; + return [input[0] * self.dry, input[1] * self.dry]; + } + let mut out = [0.0; 2]; + for c in 0..2 { + self.filter[c] += self.coefficient * (input[c] - self.filter[c]); + // Flush subnormals without denormal-sensitive host settings. + if self.filter[c].abs() < 1e-20 { + self.filter[c] = 0.0; + } + let echo = if self.frames != 0 && self.history >= self.frames { + self.delay[(self.write + 96_000 - self.frames) % 96_000][c] + } else { + 0.0 + }; + out[c] = self.filter[c] * self.dry + echo * self.wet; + self.delay[self.write][c] = send[c] + echo * self.feedback; + if self.delay[self.write][c].abs() < 1e-20 { + self.delay[self.write][c] = 0.0; + } + } + self.write = (self.write + 1) % 96_000; + self.history = (self.history + 1).min(96_000); + out + } +} +#[derive(Debug, Clone, Copy, Default)] +pub struct AudioDiagnostics { + pub frames: u64, + pub active_voices: usize, + pub maximum_voices: usize, + pub last_render_us: u64, + pub maximum_render_us: u64, +} + +pub struct AudioMixer { + pub voices: [Channel; MAX_CHANNELS], + states: [VoiceState; MAX_CHANNELS], + groups: [MusicGroup; 2], + effects: [Effect; 3], + bus: [f32; 3], + sfx_gain: f32, + exponential: [f64; 1025], + sine: [f64; 4097], + pub last_processing_time: Duration, + paused: bool, + epoch: u64, + pub diagnostics: AudioDiagnostics, + note_serial: u64, +} +impl Default for AudioMixer { + fn default() -> Self { + Self::new() + } +} +impl AudioMixer { + pub fn new() -> Self { + Self { + voices: std::array::from_fn(|_| Channel::default()), + states: [VoiceState::default(); MAX_CHANNELS], + groups: std::array::from_fn(|_| MusicGroup::default()), + effects: std::array::from_fn(|_| Effect::new()), + bus: [1.0; 3], + sfx_gain: 1.0, + exponential: std::array::from_fn(|i| { + ((-6.0 * i as f64 / 1024.0).exp() - (-6.0f64).exp()) / (1.0 - (-6.0f64).exp()) + }), + sine: std::array::from_fn(|i| (std::f64::consts::TAU * i as f64 / 4096.0).sin()), + last_processing_time: Duration::ZERO, + paused: false, + epoch: 0, + diagnostics: AudioDiagnostics::default(), + note_serial: 0, + } + } + pub fn prepared_bytes(&self) -> usize { + std::mem::size_of::() + + self + .effects + .iter() + .map(|e| e.delay.capacity() * std::mem::size_of::<[f32; 2]>()) + .sum::() + } + fn stop_group(&mut self, group: usize, packet: &mut Packet) { + for v in &mut self.voices[group * 12..group * 12 + 12] { + packet.voice(v); + } + if let Some(bank) = self.groups[group].bank.take() { + packet.push(Retired::Bank(bank)); + } + let gain = self.groups[group].gain.at(self.groups[group].frame); + self.groups[group] = MusicGroup::default(); + self.groups[group].gain = Ramp::constant(gain); + self.effects[group].reset(); + } + pub fn retire_inactive(&mut self, packet: &mut Packet) { + for g in 0..2 { + if self.groups[g].bank.as_ref().is_some_and(|b| !b.alive.load(Ordering::Acquire)) + || (self.groups[g].stop_after_fade && !self.groups[g].active) + { + self.stop_group(g, packet); + } + } + for v in &mut self.voices { + if !v.active || v.alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire)) { + packet.voice(v); + } + } + } + pub fn apply_delivery_into(&mut self, delivery: AudioDelivery, packet: &mut Packet) { + if delivery.epoch < self.epoch { + packet.batches = [delivery.frame, delivery.lifecycle]; + return; + } + if delivery.epoch != self.epoch { + for group in 0..2 { + self.stop_group(group, packet); + } + for voice in &mut self.voices { + packet.voice(voice); + *voice = Channel::default(); + } + for group in &mut self.groups { + group.gain = Ramp::constant(1.0); + } + for effect in &mut self.effects { + effect.reset(); + effect.frames = 0; + effect.feedback = 0.0; + effect.wet = 0.0; + effect.dry = 1.0; + effect.coefficient = 1.0; + } + self.bus = [1.0; 3]; + self.sfx_gain = 1.0; + self.epoch = delivery.epoch; + } + packet.batches = [delivery.frame, delivery.lifecycle]; + for index in 0..2 { + if let Some(mut batch) = packet.batches[index].take() { + for command in &mut batch { + let command = + std::mem::replace(command, AudioCommand::Stop { voice_id: SFX_CHANNELS }); + self.process_command(command, packet); + } + packet.batches[index] = Some(batch); + } + } + self.paused = delivery.paused; + } + /// Convenience for non-real-time signal tests/offline owners. + pub fn apply_delivery(&mut self, delivery: AudioDelivery) { + self.apply_delivery_into(delivery, &mut Packet::new()); + } + pub fn fill_buffer(&mut self, buffer: &mut [f32]) { + self.mix(buffer); + self.retire_inactive(&mut Packet::new()); + } + fn process_command(&mut self, command: AudioCommand, packet: &mut Packet) { + match command { + AudioCommand::Play { + sample, + alive, + voice_id, + volume, + pan, + pitch, + priority, + loop_mode, + } => { + if voice_id >= SFX_CHANNELS + || alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire)) + { + packet.push(Retired::Sample(sample)); + if let Some(t) = alive { + packet.push(Retired::Token(t)); + } + return; + } + let index = SFX_START + voice_id; + packet.voice(&mut self.voices[index]); + self.voices[index] = Channel { + sample: Some(sample), + alive, + active: true, + pos: 0.0, + pitch, + volume, + pan, + loop_mode, + priority, + }; + self.states[index] = VoiceState::default(); + } + AudioCommand::Stop { voice_id } => { + if voice_id < SFX_CHANNELS { + packet.voice(&mut self.voices[SFX_START + voice_id]); + } + } + AudioCommand::SetVolume { voice_id, volume } => { + if voice_id < SFX_CHANNELS { + self.voices[SFX_START + voice_id].volume = volume; + } + } + AudioCommand::SetPan { voice_id, pan } => { + if voice_id < SFX_CHANNELS { + self.voices[SFX_START + voice_id].pan = pan; + } + } + AudioCommand::SetPitch { voice_id, pitch } => { + if voice_id < SFX_CHANNELS { + self.voices[SFX_START + voice_id].pitch = pitch; + } + } + AudioCommand::MusicPlay { group, bank, looping } => { + if group >= 2 || !bank.alive.load(Ordering::Acquire) { + packet.push(Retired::Bank(bank)); + return; + } + self.stop_group(group, packet); + self.groups[group].bank = Some(bank); + self.groups[group].active = true; + self.groups[group].looping = looping; + } + AudioCommand::Control(control) => match control { + AudioControl::GroupVolume { group, gain } => { + if group == 2 { + self.sfx_gain = gain as f32 / 255.0; + } else { + self.groups[group].gain = Ramp::constant(gain as f64 / 255.0); + self.groups[group].stop_after_fade = false; + } + } + AudioControl::MusicStop { group } => self.stop_group(group, packet), + AudioControl::MusicPause { group, paused } => self.groups[group].paused = paused, + AudioControl::MusicVolume { group, gain } => { + self.groups[group].gain = Ramp::constant(gain as f64 / 255.0); + self.groups[group].stop_after_fade = false; + } + AudioControl::MusicFade { group, gain, frames, smooth } => { + let g = &mut self.groups[group]; + g.gain.set(gain as f64 / 255.0, g.frame, frames, smooth); + g.stop_after_fade = false; + } + AudioControl::Crossfade { source, target, frames, smooth } => { + if !self.groups[source].active || !self.groups[target].active { + return; + } + for (g, value) in [(source, 0.0), (target, 1.0)] { + let group = &mut self.groups[g]; + group.gain.set(value, group.frame, frames, smooth); + group.stop_after_fade = g == source; + } + } + AudioControl::BusVolume { bus, gain } => self.bus[bus] = gain as f32 / 255.0, + AudioControl::SfxSend { voice, gain } => { + self.states[SFX_START + voice].send = gain as f64 / 255.0 + } + AudioControl::Effect { group, cutoff_hz, delay_frames, feedback, wet, dry } => { + let effect = &mut self.effects[group]; + effect.coefficient = if cutoff_hz == 0 { + 1.0 + } else { + (1.0 - (-std::f32::consts::TAU * cutoff_hz as f32 / 48_000.0).exp()) + .clamp(0.0, 1.0) + }; + if effect.frames != delay_frames as usize { + effect.reset(); + } + effect.frames = delay_frames as usize; + effect.feedback = feedback; + effect.wet = wet; + effect.dry = dry; + } + }, + } + } + fn release(&mut self, index: usize) { + let state = &mut self.states[index]; + if state.release_age.is_none() { + let level = envelope(state, &self.exponential); + state.release_age = Some(state.age); + state.release_order = Some(self.note_serial); + self.note_serial = self.note_serial.wrapping_add(1); + state.release_level = level; + } + } + fn event(&mut self, group: usize, event: MusicEvent, zone: usize) { + let frame = self.groups[group].frame; + let track = event.track as usize; + if event.kind == 1 { + let bank = self.groups[group].bank.as_ref().unwrap(); + let inst = bank.instruments[zone]; + let cents = (event.c - inst.root as i32) as f64 * 100.0 + inst.tuning_cents as f64; + let range = group * 12..group * 12 + 12; + self.note_serial = self.note_serial.wrapping_add(1); + let legato = if event.flags & 1 != 0 { + range + .clone() + .filter(|&i| { + self.voices[i].active + && self.states[i].track == track + && self.states[i].release_age.is_none() + }) + .max_by_key(|&i| (self.states[i].born, i)) + } else { + None + }; + if let Some(index) = legato.filter(|&i| self.states[i].zone == zone) { + let state = &mut self.states[index]; + state.glide.set(cents, frame, event.duration_frames, event.curve == 1); + state.note_id = event.a; + state.born = self.note_serial; + state.iteration = self.groups[group].iteration; + self.voices[index].volume = ((inst.gain as u16 * event.d as u16 + 127) / 255) as u8; + return; + } + let index = legato.unwrap_or_else(|| { + range.clone().find(|&i| !self.voices[i].active).unwrap_or_else(|| { + range + .min_by_key(|&i| { + ( + self.states[i].release_age.is_none(), + self.states[i].release_order.unwrap_or(self.states[i].born), + i, + ) + }) + .unwrap() + }) + }); + // Music samples always have an owner in this group's retained bank. + self.voices[index] = Channel { + sample: Some(bank.samples[inst.sample as usize].clone()), + alive: None, + active: true, + pos: 0.0, + pitch: 1.0, + volume: ((inst.gain as u16 * event.d as u16 + 127) / 255) as u8, + pan: inst.pan, + loop_mode: if inst.looping { LoopMode::On } else { LoopMode::Off }, + priority: 0, + }; + self.states[index] = VoiceState { + inst, + track, + note_id: event.a, + iteration: self.groups[group].iteration, + born: self.note_serial, + glide: Ramp::constant(cents), + send: inst.send as f64 / 65535.0, + zone, + ..VoiceState::default() + }; + } else if event.kind == 2 { + for index in group * 12..group * 12 + 12 { + let state = &self.states[index]; + if self.voices[index].active + && state.track == track + && state.note_id == event.a + && state.iteration == self.groups[group].iteration + { + self.release(index); + } + } + } else { + let t = &mut self.groups[group].tracks[track]; + let smooth = event.curve == 1; + match event.kind { + 4 => t.gain.set(event.c as f64 / 65535.0, frame, event.duration_frames, smooth), + 5 => t.pan.set(event.c as f64, frame, event.duration_frames, smooth), + 6 => t.pitch.set(event.c as f64, frame, event.duration_frames, smooth), + 7 => t.vibrato = Some((event.a, event.c as f64)), + 8 => t.tremolo = Some((event.a, event.c as f64 / 65535.0)), + 9 => t.send.set(event.c as f64 / 65535.0, frame, event.duration_frames, smooth), + _ => {} // Tempo/instrument selection were resolved during compilation. + } + } + } + fn sequence(&mut self, group: usize) { + if !self.groups[group].active || self.groups[group].paused { + return; + } + loop { + let g = &self.groups[group]; + let bank = g.bank.as_ref().unwrap(); + if let Some(event) = bank.events.get(g.cursor).filter(|e| e.time <= g.time) { + let event = *event; + self.groups[group].cursor += 1; + self.event(group, event.event, event.zone); + continue; + } + if g.time < bank.end_time { + break; + } + let loop_start = bank.loop_time.unwrap_or(0); + let loop_event = if bank.loop_time.is_some() { bank.loop_event } else { 0 }; + let loop_length = bank.end_time - loop_start; + for index in group * 12..group * 12 + 12 { + self.release(index); + } + let g = &mut self.groups[group]; + if !g.looping { + g.active = false; + break; + } + g.time -= loop_length; + g.cursor = loop_event; + g.iteration = g.iteration.wrapping_add(1); + } + } + pub fn mix(&mut self, buffer: &mut [f32]) { + let start = Instant::now(); + buffer.fill(0.0); + if self.paused { + self.last_processing_time = start.elapsed(); + return; + } + for frame in buffer.as_chunks_mut::<2>().0 { + // Invalidated resources stay owned until a reclamation packet is available. + for g in 0..2 { + if self.groups[g].bank.as_ref().is_some_and(|b| !b.alive.load(Ordering::Acquire)) { + self.groups[g].active = false; + for v in &mut self.voices[g * 12..g * 12 + 12] { + v.active = false; + } + self.effects[g].reset(); + } + self.sequence(g); + } + let mut dry = [[0.0f32; 2]; 3]; + let mut send = [[0.0f32; 2]; 3]; + let mut active = 0; + for index in 0..MAX_CHANNELS { + let group = if index < 12 { + 0 + } else if index < 24 { + 1 + } else { + 2 + }; + if group < 2 && self.groups[group].paused { + continue; + } + let voice = &mut self.voices[index]; + if !voice.active { + continue; + } + if voice.alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire)) { + voice.active = false; + continue; + } + let Some(sample) = &voice.sample else { + continue; + }; + let len = sample.frames_len(); + if len == 0 { + voice.active = false; + continue; + } + active += 1; + let state = &mut self.states[index]; + let mut volume = voice.volume as f64 / 255.0; + let mut pan = voice.pan as f64; + let mut pitch = voice.pitch; + let mut amount = state.send; + if group < 2 { + let g = &self.groups[group]; + let track = g.tracks[state.track]; + state.level = envelope(state, &self.exponential); + if state.release_age.is_some() && state.level <= 0.0 { + voice.active = false; + continue; + } + let vib = track + .vibrato + .unwrap_or((state.inst.vibrato_millihz, state.inst.vibrato_cents as f64)); + let trem = track.tremolo.unwrap_or(( + state.inst.tremolo_millihz, + state.inst.tremolo_depth as f64 / 65535.0, + )); + let cents = state.glide.at(g.frame) + + track.pitch.at(g.frame) + + lfo(&self.sine, state.age, vib.0) * vib.1; + if cents != state.cached_cents { + state.pitch_factor = (cents / 1200.0).exp2(); + state.cached_cents = cents; + } + pitch *= state.pitch_factor; + volume *= state.level + * track.gain.at(g.frame) + * (1.0 - trem.1 * (lfo(&self.sine, state.age, trem.0) + 1.0) * 0.5); + pan = (pan + track.pan.at(g.frame) - 128.0).clamp(0.0, 255.0); + amount = track.send.at(g.frame, state.send); + state.age = state.age.wrapping_add(1); + } + let channels = sample.channels as usize; + let (loop_start, end) = match (voice.loop_mode, sample.loop_start, sample.loop_end) + { + (LoopMode::On, Some(a), Some(b)) if a < b && b as usize <= len => { + (a as f64, b as f64) + } + _ => (0.0, len as f64), + }; + let pos = voice.pos as usize; + if pos >= len { + voice.active = false; + continue; + } + let next = if voice.loop_mode == LoopMode::On && (pos + 1) as f64 >= end { + loop_start as usize + } else { + pos + 1 + }; + let frac = (voice.pos - pos as f64) as f32; + let value = |c: usize| { + let a = sample.data[pos * channels + c] as f32 / 32768.0; + let b = + sample.data.get(next * channels + c).copied().unwrap_or(0) as f32 / 32768.0; + a + (b - a) * frac + }; + if volume != 0.0 { + let normalized_pan = + if pan <= 128.0 { pan / 256.0 } else { 0.5 + (pan - 128.0) / 254.0 }; + let gains = if channels == 1 { + [(1.0 - normalized_pan).sqrt(), normalized_pan.sqrt()] + } else { + [ + if pan <= 128.0 { 1.0 } else { (255.0 - pan) / 127.0 }, + if pan >= 128.0 { 1.0 } else { pan / 128.0 }, + ] + }; + for c in 0..2 { + let v = + value(if channels == 1 { 0 } else { c }) * (volume * gains[c]) as f32; + dry[group][c] += v; + send[group][c] += v * amount as f32; + } + } + let ratio = sample.sample_rate as f64 / 48_000.0; + if ratio > 0.0 { + if pitch >= (end - voice.pos) / ratio { + if voice.loop_mode == LoopMode::Off { + voice.active = false; + } else { + let length = end - loop_start; + let step = (pitch % (length / ratio)) * ratio; + voice.pos = + loop_start + (voice.pos - loop_start + step).rem_euclid(length); + if voice.pos >= end { + voice.pos = loop_start; + } + } + } else { + voice.pos += pitch * ratio; + } + } + } + self.diagnostics.active_voices = active; + self.diagnostics.maximum_voices = self.diagnostics.maximum_voices.max(active); + for group in 0..3 { + if group < 2 && self.groups[group].paused { + continue; + } + let gain = if group < 2 { + self.groups[group].gain.at(self.groups[group].frame) as f32 * self.bus[0] + } else { + self.bus[1] * self.sfx_gain + }; + let values = self.effects[group].process(dry[group], send[group]); + for c in 0..2 { + frame[c] += values[c] * gain; + } + } + for value in frame { + *value = (*value * self.bus[2]).clamp(-1.0, 1.0); + } + for group in &mut self.groups { + if !group.paused + && let Some(bank) = &group.bank + { + group.frame = group.frame.wrapping_add(1); + if group.active { + group.time += bank.denominator; + } + if group.stop_after_fade && group.gain.done(group.frame) { + group.active = false; + } + } + } + // Crossfade completion silences/relinquishes notes; bank reclamation is deferred. + for g in 0..2 { + if self.groups[g].stop_after_fade && !self.groups[g].active { + for voice in &mut self.voices[g * 12..g * 12 + 12] { + voice.active = false; + } + self.effects[g].reset(); + } + } + self.diagnostics.frames += 1; + } + self.last_processing_time = start.elapsed(); + self.diagnostics.last_render_us = self.last_processing_time.as_micros() as u64; + self.diagnostics.maximum_render_us = + self.diagnostics.maximum_render_us.max(self.diagnostics.last_render_us); + } +} +fn lfo(table: &[f64; 4097], age: u64, millihz: u32) -> f64 { + let phase = ((age % 48_000_000) * millihz as u64 % 48_000_000) as f64 / 48_000_000.0 * 4096.0; + let index = phase as usize; + table[index] + (table[index + 1] - table[index]) * (phase - index as f64) +} +fn micros_frames(value: u32) -> u64 { + (value as u64 * 48_000).div_ceil(1_000_000) +} +fn envelope(state: &VoiceState, table: &[f64; 1025]) -> f64 { + let curve = |x: f64| { + if state.inst.curve == 0 { + 1.0 - x + } else { + let p = x.clamp(0.0, 1.0) * 1024.0; + let i = (p as usize).min(1023); + table[i] + (table[i + 1] - table[i]) * (p - i as f64) + } + }; + if let Some(start) = state.release_age { + let duration = micros_frames(state.inst.release_us); + let elapsed = state.age - start; + return if duration == 0 || elapsed >= duration { + 0.0 + } else { + state.release_level * curve(elapsed as f64 / duration as f64) + }; + } + let attack = micros_frames(state.inst.attack_us); + let decay = micros_frames(state.inst.decay_us); + if state.age < attack { + return state.age as f64 / attack as f64; + } + let sustain = state.inst.sustain as f64 / 65535.0; + if state.age - attack < decay { + sustain + (1.0 - sustain) * curve((state.age - attack) as f64 / decay as f64) + } else { + sustain + } +} + +#[cfg(test)] +#[path = "engine_tests.rs"] +mod tests; diff --git a/crates/console/prometeu-drivers/src/audio/engine_tests.rs b/crates/console/prometeu-drivers/src/audio/engine_tests.rs new file mode 100644 index 0000000..10453aa --- /dev/null +++ b/crates/console/prometeu-drivers/src/audio/engine_tests.rs @@ -0,0 +1,508 @@ +use super::*; +use crate::{Audio, MemoryBanks, SoundBankPoolAccess, SoundBankPoolInstaller}; +use prometeu_hal::{AudioBridge, AudioOpStatus, music_bank::AUDIO_PPQ, sound_bank::SoundBank}; +fn note(tick: u32, id: u32) -> MusicEvent { + MusicEvent { tick, kind: 1, a: id, c: 60, d: 255, ..Default::default() } +} +fn bank(events: Vec, inst: Instrument, tempo: u32, duration: u32) -> Arc { + Arc::new( + MusicBank::compile( + "test".into(), + vec![Arc::new( + Sample::new(48_000, vec![1024, -2048, 1024, -2048]) + .with_channels(2) + .unwrap() + .with_loop(0, 2), + )], + vec![inst], + events, + AUDIO_PPQ, + tempo, + duration, + None, + 1, + ) + .unwrap(), + ) +} +fn pair() -> (Arc, Audio, AudioMixer) { + let banks = Arc::new(MemoryBanks::new()); + (banks.clone(), Audio::new(banks), AudioMixer::new()) +} +fn publish(audio: &mut Audio, mixer: &mut AudioMixer) { + audio.finish_frame(); + mixer.apply_delivery(audio.transport().try_take().unwrap()); +} +fn install(banks: &MemoryBanks, slot: usize, events: Vec) { + banks.install_music_bank( + slot, + bank(events, Instrument { looping: true, ..Default::default() }, 20_000, 100_000), + ); +} +#[test] +fn thirty_two_stereo_voices_have_fixed_group_ownership_and_safe_clipping() { + let (banks, mut audio, mut mixer) = pair(); + install(&banks, 0, (0..12).map(|n| note(0, n)).collect()); + assert_eq!(audio.music_play(0, 0, true), AudioOpStatus::Ok); + assert_eq!(audio.music_play(1, 0, true), AudioOpStatus::Ok); + let sample = Arc::new(Sample::new(48_000, vec![1024, -2048])); + // Stereo uses one cursor/slot; no channel consumes a second voice. + let sample = Arc::new( + Sample::new(48_000, sample.data.clone()).with_channels(2).unwrap().with_loop(0, 1), + ); + for i in 0..8 { + assert_eq!( + audio.play_sample(sample.clone(), i, 255, 128, 1.0, 0, LoopMode::On), + AudioOpStatus::Ok + ); + } + assert_eq!(audio.stop(8), AudioOpStatus::VoiceInvalid); + publish(&mut audio, &mut mixer); + let mut pcm = [0.0; 2]; + mixer.mix(&mut pcm); + assert_eq!(mixer.voices.iter().filter(|v| v.active).count(), 32); + assert_eq!(mixer.diagnostics.maximum_voices, 32); + assert_eq!(pcm, [1.0, -1.0]); + audio.control(AudioControl::MusicStop { group: 0 }); + publish(&mut audio, &mut mixer); + assert!(mixer.voices[..12].iter().all(|v| !v.active)); + assert!(mixer.voices[12..].iter().all(|v| v.active)); + for i in 0..8 { + audio.stop(i); + } + publish(&mut audio, &mut mixer); + assert!(mixer.voices[12..24].iter().all(|v| v.active)); +} +#[test] +fn audio_time_does_not_wait_for_frame_sync_and_buffer_partition_is_invariant() { + let (banks, mut audio, mut a) = pair(); + install(&banks, 0, vec![note(17, 1)]); + audio.music_play(0, 0, false); + publish(&mut audio, &mut a); + let mut b = AudioMixer::new(); + let resident = banks.music_bank_slot(0).unwrap(); + b.process_command( + AudioCommand::MusicPlay { group: 0, bank: resident, looping: false }, + &mut Packet::new(), + ); + let mut whole = vec![0.0; 4000]; + a.mix(&mut whole); + let mut pieces = vec![0.0; 4000]; + for piece in pieces.chunks_mut(14) { + b.mix(piece); + } + assert_eq!(whole, pieces); + assert!(whole[..34].iter().all(|&v| v == 0.0)); + assert_ne!(whole[34], 0.0); + assert_eq!(a.groups[0].frame, 2000); +} +#[test] +fn fractional_tempo_changes_and_loop_remainder_have_no_cumulative_drift() { + let events = vec![MusicEvent { tick: 2, kind: 3, a: 30_001, ..Default::default() }, note(3, 1)]; + let music = bank(events, Instrument::default(), 20_001, 5); + assert_eq!(music.events[1].time, 2 * 20_001u128 * 48_000 + 30_001u128 * 48_000); + let mut mixer = AudioMixer::new(); + let end = music.end_time; + let den = music.denominator; + mixer.process_command( + AudioCommand::MusicPlay { group: 0, bank: music, looping: true }, + &mut Packet::new(), + ); + let n = 100_000; + mixer.mix(&mut vec![0.0; n * 2]); + // The first event of a loop is evaluated before the rendered frame. + assert_eq!(mixer.groups[0].iteration, ((n - 1) as u128 * den / end) as u64); + assert_eq!(mixer.groups[0].time, n as u128 * den - mixer.groups[0].iteration as u128 * end); +} +#[test] +fn music_allocator_uses_free_then_release_then_oldest_and_stale_off_does_not_stop_reuse() { + let (banks, mut audio, mut mixer) = pair(); + let mut events: Vec<_> = (0..12).map(|n| note(0, n)).collect(); + events.push(MusicEvent { tick: 1, kind: 2, a: 3, ..Default::default() }); + events.push(note(2, 12)); + events.push(MusicEvent { tick: 3, kind: 2, a: 3, ..Default::default() }); + events.push(note(4, 13)); + banks.install_music_bank( + 0, + bank( + events, + Instrument { looping: true, release_us: 1_000_000, ..Default::default() }, + 20_000, + 1000, + ), + ); + audio.music_play(0, 0, false); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 10]); + assert_eq!(mixer.states[3].note_id, 12); + assert_eq!(mixer.states[0].note_id, 13); + assert!(mixer.states[3].release_age.is_none()); +} +#[test] +fn envelopes_have_exact_endpoints_and_note_off_releases() { + let mut state = VoiceState { + inst: Instrument { + attack_us: 1000, + decay_us: 1000, + sustain: 32768, + release_us: 1000, + curve: 0, + ..Default::default() + }, + ..Default::default() + }; + let mut mixer = AudioMixer::new(); + for (age, value) in [(0, 0.0), (24, 0.5), (48, 1.0), (96, 32768.0 / 65535.0)] { + state.age = age; + assert!((envelope(&state, &mixer.exponential) - value).abs() < 1e-12); + } + state.release_age = Some(96); + state.release_level = 0.5; + for (age, value) in [(96, 0.5), (120, 0.25), (144, 0.0)] { + state.age = age; + assert!((envelope(&state, &mixer.exponential) - value).abs() < 1e-12); + } + for i in 0..10_000 { + let x = i as f64 / 10_000.0; + state.inst.curve = 1; + state.inst.release_us = 1_000_000; + state.release_age = Some(0); + state.release_level = 1.0; + state.age = (x * 48_000.0) as u64; + let x = state.age as f64 / 48_000.0; + let expected = ((-6.0 * x).exp() - (-6.0f64).exp()) / (1.0 - (-6.0f64).exp()); + assert!((envelope(&state, &mixer.exponential) - expected).abs() < 1e-4); + } + let music = bank( + vec![note(0, 1), MusicEvent { tick: 2, kind: 2, a: 1, ..Default::default() }], + Instrument { looping: true, release_us: 1000, ..Default::default() }, + 20_000, + 1000, + ); + mixer.process_command( + AudioCommand::MusicPlay { group: 0, bank: music, looping: false }, + &mut Packet::new(), + ); + mixer.mix(&mut [0.0; 8]); + assert!(mixer.voices[0].active); + mixer.mix(&mut [0.0; 100]); + assert!(!mixer.voices[0].active); +} +#[test] +fn legato_retains_cursor_and_envelope_only_for_same_zone() { + let (banks, mut audio, mut mixer) = pair(); + let mut legato = note(1, 2); + legato.flags = 1; + legato.c = 72; + legato.duration_frames = 10; + legato.curve = 1; + install(&banks, 0, vec![note(0, 1), legato]); + audio.music_play(0, 0, false); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 8]); + assert_eq!(mixer.voices[..12].iter().filter(|v| v.active).count(), 1); + assert_eq!(mixer.states[0].age, 4); + assert!((mixer.states[0].cached_cents - 124.8).abs() < 1e-10); + assert_eq!(mixer.states[0].note_id, 2); + assert_eq!(mixer.states[0].glide.to, 1200.0); +} +#[test] +fn pause_freezes_sequence_envelopes_fade_and_effect_timeline() { + let (banks, mut audio, mut mixer) = pair(); + install(&banks, 0, vec![note(0, 1)]); + audio.music_play(0, 0, true); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 6]); + audio.control(AudioControl::MusicPause { group: 0, paused: true }); + publish(&mut audio, &mut mixer); + let before = (mixer.groups[0].time, mixer.states[0].age, mixer.effects[0].write); + let mut pcm = [1.0; 200]; + mixer.mix(&mut pcm); + assert_eq!(pcm, [0.0; 200]); + assert_eq!(before, (mixer.groups[0].time, mixer.states[0].age, mixer.effects[0].write)); + audio.control(AudioControl::MusicPause { group: 0, paused: false }); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 2]); + assert_eq!(mixer.states[0].age, before.1 + 1); +} +#[test] +fn crossfade_stops_outgoing_group_and_target_keeps_its_sequence() { + let (banks, mut audio, mut mixer) = pair(); + install(&banks, 0, vec![note(0, 1)]); + audio.music_play(0, 0, true); + audio.music_play(1, 0, true); + audio.control(AudioControl::MusicVolume { group: 1, gain: 0 }); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 10]); + audio.control(AudioControl::Crossfade { source: 0, target: 1, frames: 10, smooth: true }); + publish(&mut audio, &mut mixer); + mixer.fill_buffer(&mut [0.0; 20]); + assert!(mixer.groups[0].bank.is_none()); + assert_eq!(mixer.groups[1].frame, 15); + assert_eq!(mixer.groups[1].gain.at(15), 1.0); + assert!(mixer.voices[12].active); +} +#[test] +fn shared_delay_has_selective_sends_and_sfx_tails_survive_unload() { + let (banks, mut audio, mut mixer) = pair(); + banks.install_sound_bank( + 0, + Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![16384]))])), + ); + audio.control(AudioControl::Effect { + group: 2, + cutoff_hz: 0, + delay_frames: 2, + feedback: 0.5, + wet: 1.0, + dry: 0.0, + }); + audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::Off); + audio.control(AudioControl::SfxSend { voice: 0, gain: 255 }); + publish(&mut audio, &mut mixer); + let mut first = [0.0; 2]; + mixer.mix(&mut first); + assert_eq!(first, [0.0; 2]); + banks.unload_audio_bank(false, 0); + let mut tail = [0.0; 8]; + mixer.fill_buffer(&mut tail); + assert_eq!(tail, [0.0, 0.0, 0.5, 0.0, 0.0, 0.0, 0.25, 0.0]); +} +#[test] +fn replacing_or_unloading_bank_invalidates_queued_play_and_only_its_resident_instance() { + let (banks, mut audio, mut mixer) = pair(); + let source = Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![16384; 4]))])); + banks.install_sound_bank(0, source.clone()); + banks.install_sound_bank(1, source); + audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::On); + audio.play(1, 0, 1, 255, 0, 1.0, 0, LoopMode::On); + audio.finish_frame(); + banks.unload_audio_bank(false, 0); + mixer.apply_delivery(audio.transport().try_take().unwrap()); + assert!(!mixer.voices[24].active); + assert!(mixer.voices[25].active); + install(&banks, 0, vec![note(0, 1)]); + audio.music_play(0, 0, true); + audio.music_play(1, 0, true); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 2]); + banks.unload_audio_bank(true, 0); + mixer.fill_buffer(&mut [0.0; 2]); + assert!(mixer.voices[..24].iter().all(|v| !v.active)); + assert!(mixer.groups.iter().all(|g| g.bank.is_none())); + assert!(mixer.voices[25].active); +} + +#[test] +fn stealing_respects_release_order_and_serialized_onsets_within_one_frame() { + let (banks, mut audio, mut mixer) = pair(); + install(&banks, 0, (0..14).map(|n| note(0, n)).collect()); + audio.music_play(0, 0, false); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 2]); + assert_eq!(mixer.states[0].note_id, 12); + assert_eq!(mixer.states[1].note_id, 13); + let mut events: Vec<_> = (0..12).map(|n| note(0, n)).collect(); + events.push(MusicEvent { tick: 1, kind: 2, a: 4, ..Default::default() }); + events.push(MusicEvent { tick: 2, kind: 2, a: 2, ..Default::default() }); + events.push(note(3, 20)); + banks.install_music_bank( + 0, + bank( + events, + Instrument { looping: true, release_us: 1_000_000, ..Default::default() }, + 20000, + 1000, + ), + ); + audio.music_play(0, 0, false); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 8]); + assert_eq!(mixer.states[4].note_id, 20); + assert!(mixer.states[2].release_age.is_some()); +} +#[test] +fn incompatible_legato_retriggers_the_same_voice_with_no_hidden_polyphony() { + let sample = Arc::new(Sample::new(48000, vec![1000; 8]).with_loop(0, 8)); + let mut legato = note(2, 2); + legato.flags = 1; + legato.c = 72; + let music = MusicBank::compile( + "zones".into(), + vec![sample.clone(), sample], + vec![ + Instrument { low: 0, high: 63, looping: true, ..Default::default() }, + Instrument { low: 64, high: 127, sample: 1, looping: true, ..Default::default() }, + ], + vec![note(0, 1), legato], + 960, + 20000, + 1000, + None, + 1, + ) + .unwrap(); + let mut mixer = AudioMixer::new(); + mixer.process_command( + AudioCommand::MusicPlay { group: 0, bank: Arc::new(music), looping: false }, + &mut Packet::new(), + ); + mixer.mix(&mut [0.0; 6]); + assert_eq!(mixer.voices[..12].iter().filter(|v| v.active).count(), 1); + assert_eq!(mixer.states[0].age, 1); + assert_eq!(mixer.states[0].zone, 1); + assert_eq!(mixer.states[0].note_id, 2); +} +#[test] +fn parameter_ramps_lfos_and_send_override_use_the_current_audio_value() { + let mut send = SendRamp::default(); + assert_eq!(send.at(0, 0.8), 0.8); + send.set(0.0, 0, 100, false); + assert_eq!(send.at(50, 0.8), 0.4); + send.set(1.0, 50, 100, false); + assert_eq!(send.at(50, 0.8), 0.4); + assert!((send.at(100, 0.8) - 0.7).abs() < 1e-12); + assert_eq!(send.at(150, 0.8), 1.0); + let events = vec![ + note(0, 1), + MusicEvent { kind: 4, c: 0, duration_frames: 480, ..Default::default() }, + MusicEvent { kind: 5, c: 255, duration_frames: 480, ..Default::default() }, + MusicEvent { kind: 6, c: 1200, duration_frames: 480, ..Default::default() }, + MusicEvent { kind: 7, a: 100000, c: 1200, ..Default::default() }, + MusicEvent { kind: 8, a: 100000, c: 65535, ..Default::default() }, + ]; + let mut mixer = AudioMixer::new(); + mixer.process_command( + AudioCommand::MusicPlay { + group: 0, + bank: bank(events, Instrument { looping: true, ..Default::default() }, 20000, 1000), + looping: false, + }, + &mut Packet::new(), + ); + let mut pcm = [0.0; 962]; + mixer.mix(&mut pcm); + assert_eq!(&pcm[..2], &[1.0 / 64.0, -1.0 / 32.0]); + assert!(pcm[240].abs() < 1e-8 && pcm[241].abs() < 1e-8); + assert_eq!(&pcm[960..], &[0.0, 0.0]); + assert!(mixer.voices[0].active); + assert_eq!(mixer.groups[0].tracks[0].gain.at(240), 0.5); + assert_eq!(mixer.groups[0].tracks[0].pan.at(240), 191.5); + assert_eq!(mixer.groups[0].tracks[0].pitch.at(240), 600.0); + let mut ramp = Ramp::constant(0.0); + ramp.set(1.0, 0, 100, true); + assert_eq!(ramp.at(0), 0.0); + assert_eq!(ramp.at(50), 0.5); + assert_eq!(ramp.at(100), 1.0); + let endpoint = 1.0 / 65535.0; + ramp.set(endpoint, 100, 100, false); + assert_eq!(ramp.at(200), endpoint); + assert_eq!(ramp.at(1000), endpoint); +} +#[test] +fn music_sfx_and_master_gains_remain_independent_of_group_gain() { + let (_, mut audio, mut mixer) = pair(); + audio.play_sample( + Arc::new(Sample::new(48000, vec![16384; 4])), + 0, + 255, + 0, + 1.0, + 0, + LoopMode::On, + ); + audio.control(AudioControl::GroupVolume { group: 2, gain: 128 }); + audio.control(AudioControl::BusVolume { bus: 1, gain: 128 }); + audio.control(AudioControl::BusVolume { bus: 2, gain: 128 }); + publish(&mut audio, &mut mixer); + let mut pcm = [0.0; 2]; + mixer.mix(&mut pcm); + assert!((pcm[0] - 0.5 * (128.0f32 / 255.0).powi(3)).abs() < 1e-7); + assert_eq!(pcm[1], 0.0); +} +#[test] +fn invalidating_one_music_slot_clears_only_its_effect_history() { + let (banks, mut audio, mut mixer) = pair(); + install(&banks, 0, vec![note(0, 1)]); + install(&banks, 1, vec![note(0, 1)]); + audio.music_play(0, 0, true); + audio.music_play(1, 1, true); + for group in 0..2 { + audio.control(AudioControl::Effect { + group, + cutoff_hz: 6000, + delay_frames: 48, + feedback: 0.5, + wet: 0.3, + dry: 0.7, + }); + } + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 100]); + banks.unload_audio_bank(true, 0); + mixer.retire_inactive(&mut Packet::new()); + assert_eq!(mixer.effects[0].history, 0); + assert_eq!(mixer.effects[1].history, 50); + assert!(mixer.voices[12].active); +} +#[test] +fn crossfade_with_absent_target_does_not_silence_the_active_source() { + let (banks, mut audio, mut mixer) = pair(); + install(&banks, 0, vec![note(0, 1)]); + audio.music_play(0, 0, true); + audio.control(AudioControl::Crossfade { source: 0, target: 1, frames: 0, smooth: false }); + publish(&mut audio, &mut mixer); + mixer.mix(&mut [0.0; 2]); + assert!(mixer.groups[0].active); + assert_eq!(mixer.groups[0].gain.at(1), 1.0); +} +#[test] +fn resident_memory_diagnostics_deduplicate_shared_pcm_across_all_slots() { + let banks = MemoryBanks::new(); + let sample = Arc::new(Sample::new(48000, vec![1, 2, 3, 4])); + let source = Arc::new(SoundBank::new(vec![sample])); + for slot in 0..16 { + banks.install_sound_bank(slot, source.clone()); + banks.install_music_bank(slot, bank(vec![note(0, 1)], Instrument::default(), 20000, 1000)); + } + let snapshot = banks.audio_memory(); + assert_eq!(snapshot.banks.len(), 32); + assert_eq!(snapshot.unique_pcm_bytes, 8 + 16 * 8); + assert!(snapshot.metadata_bytes > 0); + assert_eq!( + snapshot.total_accounted_bytes, + snapshot.allocated_pcm_bytes + snapshot.metadata_bytes + ); +} +#[test] +fn group_configuration_survives_play_stop_and_replacement_but_not_session_reset() { + let (banks, mut audio, mut mixer) = pair(); + install(&banks, 0, vec![note(0, 1)]); + audio.control(AudioControl::MusicVolume { group: 0, gain: 0 }); + audio.music_play(0, 0, true); + publish(&mut audio, &mut mixer); + let mut pcm = [1.0; 2]; + mixer.mix(&mut pcm); + assert_eq!(pcm, [0.0; 2]); + assert_eq!(mixer.groups[0].gain.at(0), 0.0); + audio.control(AudioControl::Effect { + group: 0, + cutoff_hz: 1000, + delay_frames: 48, + feedback: 0.5, + wet: 0.5, + dry: 0.5, + }); + audio.control(AudioControl::MusicStop { group: 0 }); + audio.music_play(0, 0, true); + publish(&mut audio, &mut mixer); + assert_eq!(mixer.groups[0].gain.at(0), 0.0); + assert_eq!(mixer.effects[0].frames, 48); + audio.reset(); + mixer.apply_delivery(audio.transport().try_take().unwrap()); + assert_eq!(mixer.groups[0].gain.at(0), 1.0); + assert_eq!(mixer.effects[0].frames, 0); + assert_eq!(mixer.effects[0].coefficient, 1.0); + assert_eq!(mixer.effects[0].wet, 0.0); + assert_eq!(mixer.effects[0].dry, 1.0); +} diff --git a/crates/console/prometeu-drivers/src/audio/transport.rs b/crates/console/prometeu-drivers/src/audio/transport.rs index 4de1c57..d15e54f 100644 --- a/crates/console/prometeu-drivers/src/audio/transport.rs +++ b/crates/console/prometeu-drivers/src/audio/transport.rs @@ -123,6 +123,7 @@ mod reuse_tests { let allocation = batch.as_ptr(); batch.push(AudioCommand::Play { sample, + alive: None, voice_id: 0, volume: 255, pan: 0, diff --git a/crates/console/prometeu-drivers/src/lib.rs b/crates/console/prometeu-drivers/src/lib.rs index 4f3a54d..a67d04c 100644 --- a/crates/console/prometeu-drivers/src/lib.rs +++ b/crates/console/prometeu-drivers/src/lib.rs @@ -13,6 +13,7 @@ mod touch; mod wall_clock; pub use crate::asset::AssetManager; +pub use crate::audio::bank_format; pub use crate::audio::{ Audio, AudioCommand, AudioDelivery, AudioTransport, Channel, MAX_CHANNELS, MAX_COMMANDS_PER_FRAME, OUTPUT_SAMPLE_RATE, @@ -29,3 +30,5 @@ pub use crate::test_platform::TestPlatform; pub use crate::wall_clock::ControlledWallClock; pub mod memcard; + +pub use crate::audio::{SFX_CHANNELS, SFX_START, engine}; diff --git a/crates/console/prometeu-drivers/src/memory_banks.rs b/crates/console/prometeu-drivers/src/memory_banks.rs index aa694f7..f903277 100644 --- a/crates/console/prometeu-drivers/src/memory_banks.rs +++ b/crates/console/prometeu-drivers/src/memory_banks.rs @@ -7,6 +7,7 @@ //! the render read surface. use prometeu_hal::glyph_bank::GlyphBank; +use prometeu_hal::music_bank::MusicBank; use prometeu_hal::render_resources::RenderResourceAccess as HalRenderResourceAccess; use prometeu_hal::scene_bank::SceneBank; use prometeu_hal::sound_bank::SoundBank; @@ -30,6 +31,7 @@ pub trait GlyphBankPoolInstaller: Send + Sync { /// Non-generic interface for peripherals to access sound banks. pub trait SoundBankPoolAccess: Send + Sync { + fn music_bank_slot(&self, slot: usize) -> Option>; /// Returns a reference to the resident SoundBank in the specified slot, if any. fn sound_bank_slot(&self, slot: usize) -> Option>; /// Returns the total number of slots available in this bank. @@ -38,6 +40,9 @@ pub trait SoundBankPoolAccess: Send + Sync { /// Non-generic interface for the AssetManager to install sound banks. pub trait SoundBankPoolInstaller: Send + Sync { + fn install_music_bank(&self, slot: usize, bank: Arc); + fn clear_music_banks(&self); + fn unload_audio_bank(&self, music: bool, slot: usize); /// Atomically swaps the resident SoundBank in the specified slot. fn install_sound_bank(&self, slot: usize, bank: Arc); /// Clears all resident SoundBank slots. @@ -68,6 +73,7 @@ pub trait SceneBankPoolInstaller: Send + Sync { pub struct MemoryBanks { glyph_bank_pool: Arc>; 16]>>, sound_bank_pool: Arc>; 16]>>, + music_bank_pool: Arc>; 16]>>, scene_bank_pool: Arc>; 16]>>, } @@ -83,6 +89,7 @@ impl MemoryBanks { Self { glyph_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), sound_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), + music_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), scene_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), } } @@ -113,6 +120,9 @@ impl GlyphBankPoolInstaller for MemoryBanks { } impl SoundBankPoolAccess for MemoryBanks { + fn music_bank_slot(&self, slot: usize) -> Option> { + self.music_bank_pool.read().unwrap().get(slot).and_then(Clone::clone) + } fn sound_bank_slot(&self, slot: usize) -> Option> { let pool = self.sound_bank_pool.read().unwrap(); pool.get(slot).and_then(|s| s.as_ref().map(Arc::clone)) @@ -124,15 +134,61 @@ impl SoundBankPoolAccess for MemoryBanks { } impl SoundBankPoolInstaller for MemoryBanks { + fn install_music_bank(&self, slot: usize, bank: Arc) { + if slot >= 16 { + return; + } + let prepared = Arc::new(bank.resident_copy()); + let mut pool = self.music_bank_pool.write().unwrap(); + if let Some(target) = pool.get_mut(slot) { + if let Some(old) = target.take() { + old.invalidate(); + } + *target = Some(prepared); + } + } + fn clear_music_banks(&self) { + let mut pool = self.music_bank_pool.write().unwrap(); + for bank in pool.iter_mut() { + if let Some(old) = bank.take() { + old.invalidate(); + } + } + } + fn unload_audio_bank(&self, music: bool, slot: usize) { + if music { + if let Some(bank) = + self.music_bank_pool.write().unwrap().get_mut(slot).and_then(Option::take) + { + bank.invalidate(); + } + } else if let Some(bank) = + self.sound_bank_pool.write().unwrap().get_mut(slot).and_then(Option::take) + { + bank.invalidate(); + } + } fn install_sound_bank(&self, slot: usize, bank: Arc) { + if slot >= 16 { + return; + } + let prepared = Arc::new(bank.resident_copy()); let mut pool = self.sound_bank_pool.write().unwrap(); if slot < 16 { - pool[slot] = Some(bank); + if let Some(old) = pool[slot].take() { + old.invalidate(); + } + pool[slot] = Some(prepared); } } fn clear_sound_banks(&self) { - self.sound_bank_pool.write().unwrap().fill(None); + let mut pool = self.sound_bank_pool.write().unwrap(); + for bank in pool.iter_mut() { + if let Some(old) = bank.take() { + old.invalidate(); + } + } } } @@ -246,3 +302,84 @@ mod tests { assert_eq!(HalRenderResourceAccess::scene_bank_count(&banks), 16); } } + +/// Owner-thread diagnostics: canonical bank costs and unique PCM allocation costs +/// are separate, so loading the same asset in two slots does not double-count RAM. +#[derive(Debug, Clone)] +pub struct AudioSlotMemory { + pub music: bool, + pub slot: usize, + pub name: String, + pub metrics: prometeu_hal::sound_bank::AudioBankMetrics, +} +#[derive(Debug, Default)] +pub struct AudioMemorySnapshot { + pub banks: Vec, + pub unique_pcm_bytes: usize, + pub allocated_pcm_bytes: usize, + /// Resident Rust structs/vector/string capacities; excludes allocator/Arc headers and host caches. + pub metadata_bytes: usize, + pub total_accounted_bytes: usize, +} +impl MemoryBanks { + pub fn audio_memory(&self) -> AudioMemorySnapshot { + let mut snapshot = AudioMemorySnapshot::default(); + let mut seen = std::collections::HashSet::new(); + let mut metadata = 0usize; + let mut vectors = std::collections::HashSet::new(); + let mut add = + |music, slot, name: String, metrics, samples: &[Arc]| { + for sample in samples { + if seen.insert(Arc::as_ptr(sample)) { + metadata += std::mem::size_of::(); + snapshot.unique_pcm_bytes += sample.data.len() * 2; + snapshot.allocated_pcm_bytes += sample.data.capacity() * 2; + } + } + snapshot.banks.push(AudioSlotMemory { music, slot, name, metrics }); + }; + for (slot, bank) in self.sound_bank_pool.read().unwrap().iter().enumerate() { + if let Some(b) = bank { + add(false, slot, b.name.clone(), b.metrics, &b.samples); + snapshot.metadata_bytes += std::mem::size_of::() + + b.name.capacity() + + std::mem::size_of::(); + if vectors.insert(Arc::as_ptr(&b.samples) as usize) { + snapshot.metadata_bytes += std::mem::size_of::< + Vec>, + >() + b.samples.capacity() + * std::mem::size_of::>(); + } + } + } + for (slot, bank) in self.music_bank_pool.read().unwrap().iter().enumerate() { + if let Some(b) = bank { + add(true, slot, b.name.clone(), b.metrics, &b.samples); + snapshot.metadata_bytes += std::mem::size_of::() + + b.name.capacity() + + std::mem::size_of::(); + if vectors.insert(Arc::as_ptr(&b.samples) as usize) { + snapshot.metadata_bytes += std::mem::size_of::< + Vec>, + >() + b.samples.capacity() + * std::mem::size_of::>(); + } + if vectors.insert(Arc::as_ptr(&b.instruments) as usize) { + snapshot.metadata_bytes += std::mem::size_of::< + Vec, + >() + b.instruments.capacity() + * std::mem::size_of::(); + } + if vectors.insert(Arc::as_ptr(&b.events) as usize) { + snapshot.metadata_bytes += std::mem::size_of::< + Vec, + >() + b.events.capacity() + * std::mem::size_of::(); + } + } + } + snapshot.metadata_bytes += metadata; + snapshot.total_accounted_bytes = snapshot.allocated_pcm_bytes + snapshot.metadata_bytes; + snapshot + } +} diff --git a/crates/console/prometeu-hal/src/asset.rs b/crates/console/prometeu-hal/src/asset.rs index 173cfbe..0d512db 100644 --- a/crates/console/prometeu-hal/src/asset.rs +++ b/crates/console/prometeu-hal/src/asset.rs @@ -8,6 +8,7 @@ pub type AssetId = i32; pub enum BankType { GLYPH, SOUNDS, + MUSIC, SCENE, // TILEMAPS, // BLOBS, @@ -41,9 +42,8 @@ pub struct GlyphBankMetadata { } #[derive(Debug, Clone, Deserialize, Serialize)] -pub struct SoundBankMetadata { - pub sample_rate: u32, - pub channels: u32, +pub struct AudioBankMetadata { + pub version: u16, } #[derive(Debug, Clone, Default, Deserialize, Serialize)] @@ -73,15 +73,16 @@ impl AssetEntry { .map_err(|e| format!("Invalid GLYPH metadata for asset {}: {}", self.asset_id, e)) } - pub fn metadata_as_sound_bank(&self) -> Result { - if self.bank_type != BankType::SOUNDS { - return Err(format!( - "Asset {} is not a SOUNDS bank (type: {:?})", - self.asset_id, self.bank_type - )); + pub fn metadata_as_audio_bank(&self) -> Result { + if !matches!(self.bank_type, BankType::SOUNDS | BankType::MUSIC) { + return Err("asset is not an audio bank".into()); } - serde_json::from_value(self.metadata.clone()) - .map_err(|e| format!("Invalid SOUNDS metadata for asset {}: {}", self.asset_id, e)) + let metadata: AudioBankMetadata = serde_json::from_value(self.metadata.clone()) + .map_err(|e| format!("Invalid audio metadata: {e}"))?; + if metadata.version != 1 { + return Err("unsupported audio metadata version".into()); + } + Ok(metadata) } pub fn metadata_as_scene_bank(&self) -> Result { @@ -189,6 +190,9 @@ pub struct SlotRef { } impl SlotRef { + pub fn music(index: usize) -> Self { + Self { asset_type: BankType::MUSIC, index } + } pub fn gfx(index: usize) -> Self { Self { asset_type: BankType::GLYPH, index } } diff --git a/crates/console/prometeu-hal/src/asset_bridge.rs b/crates/console/prometeu-hal/src/asset_bridge.rs index c1c187f..0624da0 100644 --- a/crates/console/prometeu-hal/src/asset_bridge.rs +++ b/crates/console/prometeu-hal/src/asset_bridge.rs @@ -6,6 +6,9 @@ use crate::asset::{ use crate::cartridge::AssetsPayloadSource; pub trait AssetBridge { + fn unload_audio(&self, _music: bool, _slot: usize) -> AssetOpStatus { + AssetOpStatus::InvalidState + } /// Bind before cartridge preload/loading. Hosts supporting memcard must use /// this same lane for assets; an unsupported bridge refuses the fast profile. fn bind_background_work( diff --git a/crates/console/prometeu-hal/src/audio_bridge.rs b/crates/console/prometeu-hal/src/audio_bridge.rs index 696636a..ab682f2 100644 --- a/crates/console/prometeu-hal/src/audio_bridge.rs +++ b/crates/console/prometeu-hal/src/audio_bridge.rs @@ -20,6 +20,20 @@ pub enum AudioOpStatus { CommandLimit = 7, } +/// High-level commands are staged with the ordinary frame/lifecycle batch. +#[derive(Debug, Clone, Copy)] +pub enum AudioControl { + GroupVolume { group: usize, gain: u8 }, + MusicStop { group: usize }, + MusicPause { group: usize, paused: bool }, + MusicVolume { group: usize, gain: u8 }, + MusicFade { group: usize, gain: u8, frames: u32, smooth: bool }, + Crossfade { source: usize, target: usize, frames: u32, smooth: bool }, + BusVolume { bus: usize, gain: u8 }, + Effect { group: usize, cutoff_hz: u32, delay_frames: u32, feedback: f32, wet: f32, dry: f32 }, + SfxSend { voice: usize, gain: u8 }, +} + pub trait AudioBridge { #[allow(clippy::too_many_arguments)] fn play( @@ -44,6 +58,8 @@ pub trait AudioBridge { priority: u8, loop_mode: LoopMode, ) -> AudioOpStatus; + fn music_play(&mut self, group: usize, bank: usize, looping: bool) -> AudioOpStatus; + fn control(&mut self, control: AudioControl) -> AudioOpStatus; fn stop(&mut self, voice_id: usize) -> AudioOpStatus; fn set_volume(&mut self, voice_id: usize, volume: u8) -> AudioOpStatus; fn set_pan(&mut self, voice_id: usize, pan: u8) -> AudioOpStatus; diff --git a/crates/console/prometeu-hal/src/lib.rs b/crates/console/prometeu-hal/src/lib.rs index 8aa51e6..005caa2 100644 --- a/crates/console/prometeu-hal/src/lib.rs +++ b/crates/console/prometeu-hal/src/lib.rs @@ -18,6 +18,7 @@ pub mod host_return; pub mod input_signals; pub mod log; pub mod memcard; +pub mod music_bank; pub mod native_helpers; pub mod native_interface; pub mod owned_frame; diff --git a/crates/console/prometeu-hal/src/music_bank.rs b/crates/console/prometeu-hal/src/music_bank.rs new file mode 100644 index 0000000..9ffb401 --- /dev/null +++ b/crates/console/prometeu-hal/src/music_bank.rs @@ -0,0 +1,376 @@ +//! Resident, self-contained music data. Construction/compilation is off the audio lane. +use crate::{sample::Sample, sound_bank::AudioBankMetrics}; +use std::sync::{ + Arc, + atomic::{AtomicBool, Ordering}, +}; + +pub const AUDIO_PPQ: u32 = 960; +pub const AUDIO_RATE: u32 = 48_000; +pub const MAX_MUSIC_TRACKS: usize = 256; +pub const MAX_EVENTS_PER_FRAME: usize = 64; + +#[derive(Debug, Clone, Copy)] +pub struct Instrument { + pub id: u16, + pub sample: u16, + pub low: u8, + pub high: u8, + pub root: u8, + pub looping: bool, + pub tuning_cents: i16, + pub pan: u8, + pub gain: u8, + pub attack_us: u32, + pub decay_us: u32, + pub sustain: u16, + pub release_us: u32, + pub vibrato_millihz: u32, + pub vibrato_cents: u16, + pub tremolo_depth: u16, + pub tremolo_millihz: u32, + pub send: u16, + pub curve: u8, +} +impl Default for Instrument { + fn default() -> Self { + Self { + id: 0, + sample: 0, + low: 0, + high: 127, + root: 60, + looping: false, + tuning_cents: 0, + pan: 128, + gain: 255, + attack_us: 0, + decay_us: 0, + sustain: u16::MAX, + release_us: 0, + vibrato_millihz: 0, + vibrato_cents: 0, + tremolo_depth: 0, + tremolo_millihz: 0, + send: 0, + curve: 1, + } + } +} + +#[derive(Debug, Clone, Copy, Default)] +pub struct MusicEvent { + pub tick: u32, + pub kind: u8, + pub track: u8, + pub flags: u16, + pub a: u32, + pub b: u32, + pub c: i32, + pub d: i32, + pub duration_frames: u32, + pub curve: u32, +} +#[derive(Debug, Clone, Copy)] +pub struct TimedMusicEvent { + pub time: u128, + pub event: MusicEvent, + pub zone: usize, +} +#[derive(Debug)] +pub struct MusicBank { + pub name: String, + pub samples: Arc>>, + pub instruments: Arc>, + pub events: Arc>, + pub denominator: u128, + pub end_time: u128, + pub loop_time: Option, + pub loop_event: usize, + pub tracks: usize, + pub alive: Arc, + pub metrics: AudioBankMetrics, +} +impl MusicBank { + #[allow(clippy::too_many_arguments)] + pub fn compile( + name: String, + samples: Vec>, + instruments: Vec, + events: Vec, + ppq: u32, + tempo: u32, + duration: u32, + loop_tick: Option, + tracks: usize, + ) -> Result { + let mut compiler = MusicCompiler::new( + name, + samples, + instruments, + events, + ppq, + tempo, + duration, + loop_tick, + tracks, + )?; + loop { + if let Some(bank) = compiler.step()? { + return Ok(bank); + } + } + } + pub fn invalidate(&self) { + self.alive.store(false, Ordering::Release); + } + pub fn resident_copy(&self) -> Self { + Self { + name: self.name.clone(), + samples: self.samples.clone(), + instruments: self.instruments.clone(), + events: self.events.clone(), + denominator: self.denominator, + end_time: self.end_time, + loop_time: self.loop_time, + loop_event: self.loop_event, + tracks: self.tracks, + alive: Arc::new(AtomicBool::new(true)), + metrics: self.metrics, + } + } +} + +/// Cooperative off-lane validation/clock compilation. At most 64 zones/events +/// per step; lookup is logarithmic and the loop-seam check is bounded by 65. +pub struct MusicCompiler { + name: Option, + samples: Vec>, + instruments: Vec, + source: std::vec::IntoIter, + compiled: Vec, + zones: std::collections::BTreeMap<(u16, u8), usize>, + zone_cursor: usize, + ppq: u32, + tempo: u32, + duration: u32, + loop_tick: Option, + tracks: usize, + tick: u32, + time: u128, + loop_time: Option, + selected: [u32; MAX_MUSIC_TRACKS], +} +impl MusicCompiler { + #[allow(clippy::too_many_arguments)] + pub fn new( + name: String, + samples: Vec>, + instruments: Vec, + events: Vec, + ppq: u32, + tempo: u32, + duration: u32, + loop_tick: Option, + tracks: usize, + ) -> Result { + if ppq != AUDIO_PPQ + || tempo == 0 + || duration == 0 + || tracks == 0 + || tracks > MAX_MUSIC_TRACKS + || loop_tick.is_some_and(|t| t >= duration) + { + return Err("invalid music clock/tracks/loop".into()); + } + let mut compiled = Vec::new(); + compiled.try_reserve_exact(events.len()).map_err(|_| "music allocation failed")?; + Ok(Self { + name: Some(name), + samples, + instruments, + source: events.into_iter(), + compiled, + zones: std::collections::BTreeMap::new(), + zone_cursor: 0, + ppq, + tempo, + duration, + loop_tick, + tracks, + tick: 0, + time: 0, + loop_time: None, + selected: [u32::MAX; MAX_MUSIC_TRACKS], + }) + } + pub fn step(&mut self) -> Result, String> { + let denominator = self.ppq as u128 * 1_000_000; + for _ in 0..64 { + if self.zone_cursor < self.instruments.len() { + let i = self.zone_cursor; + let inst = self.instruments[i]; + if inst.low > inst.high + || inst.high > 127 + || inst.root > 127 + || inst.curve > 1 + || inst.sample as usize >= self.samples.len() + || inst.vibrato_millihz > 100_000 + || inst.tremolo_millihz > 100_000 + || inst.vibrato_cents > 2400 + { + return Err("invalid instrument zone/modulation".into()); + } + if inst.looping && self.samples[inst.sample as usize].loop_start.is_none() { + return Err("instrument requires a sample loop".into()); + } + if self + .zones + .range((inst.id, 0)..=(inst.id, inst.high)) + .next_back() + .is_some_and(|(_, j)| self.instruments[*j].high >= inst.low) + { + return Err("overlapping instrument zones".into()); + } + self.zones.insert((inst.id, inst.low), i); + self.zone_cursor += 1; + continue; + } + let Some(event) = self.source.next() else { + return self.finish(denominator).map(Some); + }; + if event.tick < self.tick + || event.tick > self.duration + || event.track as usize >= self.tracks + || event.curve > 1 + || event.flags & !1 != 0 + || !(1..=10).contains(&event.kind) + { + return Err("invalid music event ordering/shape".into()); + } + if let Some(t) = self.loop_tick.filter(|&t| t >= self.tick && t <= event.tick) + && self.loop_time.is_none() + { + self.loop_time = Some( + self.time + (t - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128, + ); + } + self.time += (event.tick - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128; + self.tick = event.tick; + let mut zone = 0; + match event.kind { + 1 => { + if !(0..=127).contains(&event.c) || !(0..=255).contains(&event.d) { + return Err("invalid note/velocity".into()); + } + let id = if event.b == u32::MAX { + self.selected[event.track as usize] + } else { + event.b + }; + if id > u16::MAX as u32 { + return Err("note has no bank-local instrument".into()); + } + zone = *self + .zones + .range((id as u16, 0)..=(id as u16, event.c as u8)) + .next_back() + .map(|(_, i)| i) + .filter(|&&i| self.instruments[i].high as i32 >= event.c) + .ok_or("note has no bank-local instrument zone")?; + } + 3 => { + if event.a == 0 { + return Err("zero tempo".into()); + } + self.tempo = event.a; + } + 4 | 9 => { + if !(0..=65535).contains(&event.c) { + return Err("invalid gain/send".into()); + } + } + 5 => { + if !(0..=255).contains(&event.c) { + return Err("invalid pan".into()); + } + } + 6 => { + if !(-9600..=9600).contains(&event.c) { + return Err("invalid pitch bend".into()); + } + } + 7 | 8 => { + if event.a > 100_000 + || event.c < 0 + || event.c > if event.kind == 7 { 2400 } else { 65535 } + { + return Err("invalid modulation".into()); + } + } + 10 => { + if event.a > u16::MAX as u32 + || self + .zones + .range((event.a as u16, 0)..=(event.a as u16, 127)) + .next() + .is_none() + { + return Err("unknown instrument".into()); + } + self.selected[event.track as usize] = event.a; + } + _ => {} + } + if self.compiled.len() >= MAX_EVENTS_PER_FRAME + && self.time - self.compiled[self.compiled.len() - MAX_EVENTS_PER_FRAME].time + < denominator + { + return Err("music event density exceeds real-time bound".into()); + } + self.compiled.push(TimedMusicEvent { time: self.time, event, zone }); + } + Ok(None) + } + fn finish(&mut self, denominator: u128) -> Result { + if let Some(t) = self.loop_tick.filter(|&t| t >= self.tick) + && self.loop_time.is_none() + { + self.loop_time = + Some(self.time + (t - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128); + } + let end_time = self.time + + (self.duration - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128; + if end_time < denominator || self.loop_time.is_some_and(|t| end_time - t < denominator) { + return Err("music/loop shorter than one output frame".into()); + } + let loop_event = + self.loop_time.map_or(0, |t| self.compiled.partition_point(|e| e.time < t)); + let length = end_time - self.loop_time.unwrap_or(0); + let slice = &self.compiled[loop_event..]; + for i in 0..slice.len().min(MAX_EVENTS_PER_FRAME + 1) { + let tail = + slice.len().saturating_sub(MAX_EVENTS_PER_FRAME - i.min(MAX_EVENTS_PER_FRAME)); + if tail < slice.len() + && slice.len() - tail + i + 1 > MAX_EVENTS_PER_FRAME + && slice[i].time + length - slice[tail].time < denominator + { + return Err("music loop seam event density".into()); + } + } + let pcm_bytes = self.samples.iter().map(|s| s.data.len() * 2).sum(); + Ok(MusicBank { + name: self.name.take().ok_or("compiler already complete")?, + samples: Arc::new(std::mem::take(&mut self.samples)), + instruments: Arc::new(std::mem::take(&mut self.instruments)), + events: Arc::new(std::mem::take(&mut self.compiled)), + denominator, + end_time, + loop_time: self.loop_time, + loop_event, + tracks: self.tracks, + alive: Arc::new(AtomicBool::new(true)), + metrics: AudioBankMetrics { pcm_bytes, ..Default::default() }, + }) + } +} diff --git a/crates/console/prometeu-hal/src/sample.rs b/crates/console/prometeu-hal/src/sample.rs index 7c5356f..ab0b2f4 100644 --- a/crates/console/prometeu-hal/src/sample.rs +++ b/crates/console/prometeu-hal/src/sample.rs @@ -1,13 +1,27 @@ +#[derive(Debug)] pub struct Sample { pub sample_rate: u32, + pub channels: u8, pub data: Vec, pub loop_start: Option, pub loop_end: Option, + pub default_volume: u8, + pub default_pan: u8, + pub default_pitch: f64, } impl Sample { pub fn new(sample_rate: u32, data: Vec) -> Self { - Self { sample_rate, data, loop_start: None, loop_end: None } + Self { + sample_rate, + channels: 1, + data, + loop_start: None, + loop_end: None, + default_volume: 255, + default_pan: 128, + default_pitch: 1.0, + } } pub fn with_loop(mut self, start: u32, end: u32) -> Self { @@ -17,6 +31,14 @@ impl Sample { } pub fn frames_len(&self) -> usize { - self.data.len() + self.data.len() / self.channels.max(1) as usize + } + + pub fn with_channels(mut self, channels: u8) -> Result { + if !(1..=2).contains(&channels) || !self.data.len().is_multiple_of(channels as usize) { + return Err("audio sample channels/frame count".into()); + } + self.channels = channels; + Ok(self) } } diff --git a/crates/console/prometeu-hal/src/sound_bank.rs b/crates/console/prometeu-hal/src/sound_bank.rs index 136ba7c..e4d7475 100644 --- a/crates/console/prometeu-hal/src/sound_bank.rs +++ b/crates/console/prometeu-hal/src/sound_bank.rs @@ -1,16 +1,47 @@ use crate::sample::Sample; use std::sync::Arc; +use std::sync::atomic::{AtomicBool, Ordering}; + +#[derive(Debug, Clone, Copy, Default)] +pub struct AudioBankMetrics { + pub cartridge_bytes: usize, + pub pcm_bytes: usize, + pub canonical_decoded_bytes: usize, + pub materialization_ns: u64, +} /// A container for audio assets. /// /// A SoundBank stores multiple audio samples that can be played by the /// audio subsystem. +#[derive(Debug)] pub struct SoundBank { - pub samples: Vec>, + pub samples: Arc>>, + pub name: String, + pub alive: Arc, + pub metrics: AudioBankMetrics, } impl SoundBank { pub fn new(samples: Vec>) -> Self { - Self { samples } + let pcm_bytes = samples.iter().map(|s| s.data.len() * 2).sum(); + Self { + samples: Arc::new(samples), + name: String::new(), + alive: Arc::new(AtomicBool::new(true)), + metrics: AudioBankMetrics { pcm_bytes, ..Default::default() }, + } + } + + pub fn invalidate(&self) { + self.alive.store(false, Ordering::Release); + } + pub fn resident_copy(&self) -> Self { + Self { + samples: self.samples.clone(), + name: self.name.clone(), + alive: Arc::new(AtomicBool::new(true)), + metrics: self.metrics, + } } } diff --git a/crates/console/prometeu-hal/src/syscalls.rs b/crates/console/prometeu-hal/src/syscalls.rs index 4410506..ac25bd3 100644 --- a/crates/console/prometeu-hal/src/syscalls.rs +++ b/crates/console/prometeu-hal/src/syscalls.rs @@ -59,6 +59,19 @@ pub enum Syscall { AudioSetVolume = 0x3004, AudioSetPan = 0x3005, AudioSetPitch = 0x3006, + MusicPlay = 0x3010, + MusicStop = 0x3011, + MusicPause = 0x3012, + MusicResume = 0x3013, + MusicSetVolume = 0x3014, + MusicFadeTo = 0x3015, + MusicCrossfade = 0x3016, + AudioSetBusVolume = 0x3020, + AudioSetEffect = 0x3021, + AudioSetSend = 0x3022, + AudioUnloadBank = 0x3023, + AudioSetGroupVolume = 0x3024, + FsOpen = 0x4001, FsRead = 0x4002, FsWrite = 0x4003, diff --git a/crates/console/prometeu-hal/src/syscalls/domains/audio.rs b/crates/console/prometeu-hal/src/syscalls/domains/audio.rs index a8f8aff..fda5db3 100644 --- a/crates/console/prometeu-hal/src/syscalls/domains/audio.rs +++ b/crates/console/prometeu-hal/src/syscalls/domains/audio.rs @@ -31,4 +31,64 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[ .rets(1) .caps(caps::AUDIO) .cost(5), + SyscallRegistryEntry::builder(Syscall::MusicPlay, "music", "play") + .args(3) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::MusicStop, "music", "stop") + .args(1) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::MusicPause, "music", "pause") + .args(1) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::MusicResume, "music", "resume") + .args(1) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::MusicSetVolume, "music", "set_volume") + .args(2) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::MusicFadeTo, "music", "fade_to") + .args(4) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::MusicCrossfade, "music", "crossfade") + .args(4) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::AudioSetBusVolume, "audio", "set_bus_volume") + .args(2) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::AudioSetEffect, "audio", "set_effect") + .args(6) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::AudioSetSend, "audio", "set_send") + .args(2) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::AudioUnloadBank, "audio", "unload_bank") + .args(2) + .rets(1) + .caps(caps::AUDIO) + .cost(5), + SyscallRegistryEntry::builder(Syscall::AudioSetGroupVolume, "audio", "set_group_volume") + .args(2) + .rets(1) + .caps(caps::AUDIO) + .cost(5), ]; diff --git a/crates/console/prometeu-hal/src/syscalls/registry.rs b/crates/console/prometeu-hal/src/syscalls/registry.rs index bf70a2f..0a20bee 100644 --- a/crates/console/prometeu-hal/src/syscalls/registry.rs +++ b/crates/console/prometeu-hal/src/syscalls/registry.rs @@ -37,6 +37,19 @@ impl Syscall { 0x3004 => Some(Self::AudioSetVolume), 0x3005 => Some(Self::AudioSetPan), 0x3006 => Some(Self::AudioSetPitch), + 0x3010 => Some(Self::MusicPlay), + 0x3011 => Some(Self::MusicStop), + 0x3012 => Some(Self::MusicPause), + 0x3013 => Some(Self::MusicResume), + 0x3014 => Some(Self::MusicSetVolume), + 0x3015 => Some(Self::MusicFadeTo), + 0x3016 => Some(Self::MusicCrossfade), + 0x3020 => Some(Self::AudioSetBusVolume), + 0x3021 => Some(Self::AudioSetEffect), + 0x3022 => Some(Self::AudioSetSend), + 0x3023 => Some(Self::AudioUnloadBank), + 0x3024 => Some(Self::AudioSetGroupVolume), + 0x4001 => Some(Self::FsOpen), 0x4002 => Some(Self::FsRead), 0x4003 => Some(Self::FsWrite), @@ -110,6 +123,19 @@ impl Syscall { Self::AudioSetVolume => "AudioSetVolume", Self::AudioSetPan => "AudioSetPan", Self::AudioSetPitch => "AudioSetPitch", + Self::MusicPlay => "MusicPlay", + Self::MusicStop => "MusicStop", + Self::MusicPause => "MusicPause", + Self::MusicResume => "MusicResume", + Self::MusicSetVolume => "MusicSetVolume", + Self::MusicFadeTo => "MusicFadeTo", + Self::MusicCrossfade => "MusicCrossfade", + Self::AudioSetBusVolume => "AudioSetBusVolume", + Self::AudioSetEffect => "AudioSetEffect", + Self::AudioSetSend => "AudioSetSend", + Self::AudioUnloadBank => "AudioUnloadBank", + Self::AudioSetGroupVolume => "AudioSetGroupVolume", + Self::FsOpen => "FsOpen", Self::FsRead => "FsRead", Self::FsWrite => "FsWrite", diff --git a/crates/console/prometeu-system/src/services/memcard/transaction/tests.rs b/crates/console/prometeu-system/src/services/memcard/transaction/tests.rs index 5d139dc..45c2092 100644 --- a/crates/console/prometeu-system/src/services/memcard/transaction/tests.rs +++ b/crates/console/prometeu-system/src/services/memcard/transaction/tests.rs @@ -960,7 +960,7 @@ fn persistent_save_preempts_real_multichunk_asset_decoders() { self.inner.sync() } } - for kind in [BankType::GLYPH, BankType::SOUNDS, BankType::SCENE] { + for kind in [BankType::GLYPH, BankType::SOUNDS, BankType::MUSIC, BankType::SCENE] { let (card, disk) = formatted(); drop(card); let events: Events = Arc::default(); @@ -985,8 +985,37 @@ fn persistent_save_preempts_real_multichunk_asset_decoders() { ) } BankType::SOUNDS => { - (vec![0x12; 16385], 16385, serde_json::json!({"sample_rate":44100,"channels":1})) + let mut bytes = vec![0u8; 88]; + bytes[..4].copy_from_slice(b"SBNK"); + bytes[4] = 1; + bytes[49] = 1; + bytes[80] = 255; + bytes[81] = 128; + for (at, value) in [ + (8, 1u32), + (20, 960), + (24, 500000), + (32, u32::MAX), + (52, 44100), + (56, 8192), + (68, 88), + (72, 16384), + (84, 65536), + ] { + bytes[at..at + 4].copy_from_slice(&value.to_le_bytes()); + } + bytes.extend([0x12; 16384]); + (bytes, 16472, serde_json::json!({"version":1})) } + BankType::MUSIC => ( + include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-music.mbnk" + )) + .to_vec(), + 6395, + serde_json::json!({"version":1}), + ), BankType::SCENE => { let mut bytes = vec![0; 140]; bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]); @@ -1079,6 +1108,12 @@ fn persistent_save_preempts_real_multichunk_asset_decoders() { assert_eq!(bank.samples[0].sample_rate, 44100); assert_eq!(bank.samples[0].data, vec![0x1212; 8192]); } + BankType::MUSIC => { + let bank = banks.music_bank_slot(0).unwrap(); + assert_eq!(bank.events.len(), 4); + assert_eq!(bank.samples.len(), 2); + assert_eq!(bank.samples[1].channels, 2); + } BankType::SCENE => { let bank = banks.scene_bank_slot(0).unwrap(); assert_eq!( diff --git a/crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs b/crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs index 1d1edaf..222540f 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs @@ -4,6 +4,7 @@ use crate::services::memcard::MemcardService; use prometeu_bytecode::{TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_TYPE, Value}; use prometeu_hal::app_mode::AppMode; use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType}; +use prometeu_hal::audio_bridge::AudioControl; use prometeu_hal::color::Color; use prometeu_hal::glyph::Glyph; use prometeu_hal::log::{LogLevel, LogSource}; @@ -465,7 +466,7 @@ impl NativeInterface for VmRuntimeHost<'_> { let pan_raw = expect_int(args, 3)?; let pitch = expect_number(args, 4, "pitch")?; - if !(0..16).contains(&voice_id_raw) { + if !(0..8).contains(&voice_id_raw) { ret.push_int(AudioOpStatus::VoiceInvalid as i64); return Ok(()); } @@ -508,7 +509,7 @@ impl NativeInterface for VmRuntimeHost<'_> { prometeu_hal::LoopMode::On }; - if !(0..16).contains(&voice_id_raw) { + if !(0..8).contains(&voice_id_raw) { ret.push_int(AudioOpStatus::VoiceInvalid as i64); return Ok(()); } @@ -558,7 +559,7 @@ impl NativeInterface for VmRuntimeHost<'_> { } else { 1.0 }; - let status = if !(0..16).contains(&voice) { + let status = if !(0..8).contains(&voice) { AudioOpStatus::VoiceInvalid } else if !(0..=255).contains(&value) || !pitch.is_finite() || pitch <= 0.0 { AudioOpStatus::ArgRangeInvalid @@ -575,6 +576,113 @@ impl NativeInterface for VmRuntimeHost<'_> { ret.push_int(status as i64); Ok(()) } + Syscall::MusicPlay + | Syscall::MusicStop + | Syscall::MusicPause + | Syscall::MusicResume + | Syscall::MusicSetVolume + | Syscall::MusicFadeTo + | Syscall::MusicCrossfade + | Syscall::AudioSetBusVolume + | Syscall::AudioSetEffect + | Syscall::AudioSetSend + | Syscall::AudioUnloadBank + | Syscall::AudioSetGroupVolume => { + macro_rules! uint { + ($i:expr, $max:expr) => {{ + let n = expect_int(args, $i)?; + if !(0..=$max).contains(&n) { + ret.push_int(AudioOpStatus::ArgRangeInvalid as i64); + return Ok(()); + } + n as u32 + }}; + } + let status = match syscall { + Syscall::MusicPlay => { + let group = uint!(0, 1); + let bank = uint!(1, 15); + let looping = uint!(2, 1); + platform.audio_mut().music_play(group as usize, bank as usize, looping != 0) + } + Syscall::AudioUnloadBank => { + let music = uint!(0, 1); + let slot = uint!(1, 15); + let result = platform.assets().unload_audio(music != 0, slot as usize); + ret.push_int(if result == AssetOpStatus::Ok { + AudioOpStatus::Ok + } else { + AudioOpStatus::BankInvalid + } as i64); + return Ok(()); + } + _ => { + let control = match syscall { + Syscall::MusicStop => { + AudioControl::MusicStop { group: uint!(0, 1) as usize } + } + Syscall::MusicPause | Syscall::MusicResume => { + AudioControl::MusicPause { + group: uint!(0, 1) as usize, + paused: syscall == Syscall::MusicPause, + } + } + Syscall::MusicSetVolume => AudioControl::MusicVolume { + group: uint!(0, 1) as usize, + gain: uint!(1, 255) as u8, + }, + Syscall::MusicFadeTo => { + let group = uint!(0, 1) as usize; + let gain = uint!(1, 255) as u8; + let ms = uint!(2, (u32::MAX / 48) as i64); + let curve = uint!(3, 1); + AudioControl::MusicFade { + group, + gain, + frames: ms * 48, + smooth: curve != 0, + } + } + Syscall::MusicCrossfade => { + let source = uint!(0, 1) as usize; + let target = uint!(1, 1) as usize; + let ms = uint!(2, (u32::MAX / 48) as i64); + let curve = uint!(3, 1); + AudioControl::Crossfade { + source, + target, + frames: ms * 48, + smooth: curve != 0, + } + } + Syscall::AudioSetGroupVolume => AudioControl::GroupVolume { + group: uint!(0, 2) as usize, + gain: uint!(1, 255) as u8, + }, + Syscall::AudioSetBusVolume => AudioControl::BusVolume { + bus: uint!(0, 2) as usize, + gain: uint!(1, 255) as u8, + }, + Syscall::AudioSetSend => AudioControl::SfxSend { + voice: uint!(0, 7) as usize, + gain: uint!(1, 255) as u8, + }, + Syscall::AudioSetEffect => AudioControl::Effect { + group: uint!(0, 2) as usize, + cutoff_hz: uint!(1, 24_000), + delay_frames: uint!(2, 2000) * 48, + feedback: expect_number(args, 3, "feedback")? as f32, + wet: expect_number(args, 4, "wet")? as f32, + dry: expect_number(args, 5, "dry")? as f32, + }, + _ => unreachable!(), + }; + platform.audio_mut().control(control) + } + }; + ret.push_int(status as i64); + Ok(()) + } Syscall::FsOpen => { let path = expect_string(args, 0, "path")?; if *self.fs_state != FsState::Mounted { @@ -749,6 +857,7 @@ impl NativeInterface for VmRuntimeHost<'_> { 0 => BankType::GLYPH, 1 => BankType::SOUNDS, 2 => BankType::SCENE, + 3 => BankType::MUSIC, other => { return Err(VmFault::Trap( TRAP_TYPE, @@ -770,6 +879,8 @@ impl NativeInterface for VmRuntimeHost<'_> { let asset_type = match expect_int(args, 0)? as u32 { 0 => BankType::GLYPH, 1 => BankType::SOUNDS, + 2 => BankType::SCENE, + 3 => BankType::MUSIC, _ => return Err(VmFault::Trap(TRAP_TYPE, "Invalid asset type".to_string())), }; let telemetry = platform diff --git a/crates/console/prometeu-system/src/services/vm_runtime/tests_audio.rs b/crates/console/prometeu-system/src/services/vm_runtime/tests_audio.rs index 9ec92c6..332235b 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/tests_audio.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/tests_audio.rs @@ -14,13 +14,16 @@ struct Harness { } impl Harness { fn new(code: &str, name: &str, args: u16) -> Self { + Self::new_domain(code, "audio", name, args) + } + fn new_domain(code: &str, module: &str, name: &str, args: u16) -> Self { let mut runtime = VirtualMachineRuntime::new(None); let mut vm = VirtualMachine::default(); let mut log = LogService::new(4096); let program = serialized_single_function_module( assemble(code).unwrap(), vec![SyscallDecl { - module: "audio".into(), + module: module.into(), name: name.into(), version: 1, arg_slots: args, @@ -76,7 +79,7 @@ impl Harness { fn guest_audio_status_matrix_and_type_traps() { for (name, args, inputs, expected) in [ ("stop", 1, "PUSH_I32 0", 0), - ("stop", 1, "PUSH_I32 15", 0), + ("stop", 1, "PUSH_I32 7", 0), ("stop", 1, "PUSH_I32 -1", 1), ("stop", 1, "PUSH_I32 16", 1), ("set_volume", 2, "PUSH_I32 0\nPUSH_I32 0", 0), @@ -84,7 +87,7 @@ fn guest_audio_status_matrix_and_type_traps() { ("set_volume", 2, "PUSH_I32 0\nPUSH_I32 256", 3), ("set_pan", 2, "PUSH_I32 0\nPUSH_I32 -1", 3), ("set_pan", 2, "PUSH_I32 16\nPUSH_I32 -1", 1), - ("set_pan", 2, "PUSH_I32 15\nPUSH_I32 255", 0), + ("set_pan", 2, "PUSH_I32 7\nPUSH_I32 255", 0), ("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 1", 0), ("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 0", 3), ("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 -1", 3), @@ -216,3 +219,61 @@ fn normal_entry_return_is_a_successful_implicit_audio_frame() { } assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1); } + +#[test] +fn music_and_bus_controls_resolve_with_audio_capability_and_validate_without_partial_commands() { + use prometeu_drivers::SoundBankPoolInstaller; + use prometeu_drivers::bank_format::{DecodedAudioBank, decode_audio_bank}; + for (module, name, args, inputs, expected) in [ + ("music", "play", 3, "PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 1", 0), + ("music", "play", 3, "PUSH_I32 0\nPUSH_I32 16\nPUSH_I32 1", 3), + ("music", "stop", 1, "PUSH_I32 1", 0), + ("music", "pause", 1, "PUSH_I32 0", 0), + ("music", "resume", 1, "PUSH_I32 0", 0), + ("music", "set_volume", 2, "PUSH_I32 0\nPUSH_I32 255", 0), + ("music", "fade_to", 4, "PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 2000\nPUSH_I32 1", 0), + ("music", "crossfade", 4, "PUSH_I32 0\nPUSH_I32 1\nPUSH_I32 2000\nPUSH_I32 0", 0), + ("music", "crossfade", 4, "PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 2000\nPUSH_I32 0", 3), + ("audio", "set_group_volume", 2, "PUSH_I32 2\nPUSH_I32 255", 0), + ("audio", "set_bus_volume", 2, "PUSH_I32 2\nPUSH_I32 255", 0), + ("audio", "set_send", 2, "PUSH_I32 7\nPUSH_I32 128", 0), + ( + "audio", + "set_effect", + 6, + "PUSH_I32 2\nPUSH_I32 4000\nPUSH_I32 2000\nPUSH_F64 f64:0x3fe0000000000000\nPUSH_F64 f64:0x3fd3333333333333\nPUSH_F64 f64:0x3fe6666666666666", + 0, + ), + ( + "audio", + "set_effect", + 6, + "PUSH_I32 2\nPUSH_I32 4000\nPUSH_I32 2001\nPUSH_F64 f64:0x3fe0000000000000\nPUSH_F64 f64:0x3fd3333333333333\nPUSH_F64 f64:0x3fe6666666666666", + 3, + ), + ("audio", "unload_bank", 2, "PUSH_I32 1\nPUSH_I32 0", 0), + ] { + let mut h = Harness::new_domain( + &format!("{inputs}\nHOSTCALL 0\nFRAME_SYNC\nHALT"), + module, + name, + args, + ); + let bytes = include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-music.mbnk" + )); + let DecodedAudioBank::Music(bank) = decode_audio_bank(bytes, true).unwrap() else { + panic!() + }; + h.platform.local_hardware().memory_banks.install_music_bank(0, Arc::new(bank)); + assert!(h.tick().is_none(), "{module}.{name}"); + assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(expected)], "{module}.{name}"); + let batch = h.transport().try_take().unwrap().frame; + assert_eq!( + batch.map_or(0, |v| v.len()), + usize::from(expected == 0 && name != "unload_bank"), + "{module}.{name}" + ); + } +} diff --git a/crates/host/prometeu-host-desktop-winit/src/audio.rs b/crates/host/prometeu-host-desktop-winit/src/audio.rs index 383ff6d..2ea7e6c 100644 --- a/crates/host/prometeu-host-desktop-winit/src/audio.rs +++ b/crates/host/prometeu-host-desktop-winit/src/audio.rs @@ -1,10 +1,14 @@ mod reclamation; pub use reclamation::AudioReclaimer; -use reclamation::{CallbackLane, Packet}; +use reclamation::CallbackLane; +#[cfg(test)] +use reclamation::Packet; use cpal::traits::{DeviceTrait, HostTrait, StreamTrait}; -use prometeu_drivers::{AudioCommand, Channel, MAX_CHANNELS, OUTPUT_SAMPLE_RATE}; -use prometeu_drivers::{AudioDelivery, AudioTransport}; +use prometeu_drivers::AudioTransport; +use prometeu_drivers::OUTPUT_SAMPLE_RATE; +pub use prometeu_drivers::engine::AudioMixer; +#[cfg(test)] use prometeu_hal::LoopMode; use ringbuf::HeapRb; use ringbuf::traits::{Consumer, Producer, Split}; @@ -243,6 +247,9 @@ impl AudioCallback { let (lane, reclaimer) = reclamation::pool(); (Self { mixer: AudioMixer::new(), lane }, reclaimer) } + pub fn diagnostics(&self) -> prometeu_drivers::engine::AudioDiagnostics { + self.mixer.diagnostics + } pub fn render(&mut self, transport: &AudioTransport, data: &mut [f32]) { let mut packet = self.lane.take(); if let Some(packet) = &mut packet { @@ -380,201 +387,6 @@ mod tests { } } -pub struct AudioMixer { - voices: [Channel; MAX_CHANNELS], - pub last_processing_time: Duration, - paused: bool, - epoch: u64, -} - -impl Default for AudioMixer { - fn default() -> Self { - Self::new() - } -} - -impl AudioMixer { - pub fn new() -> Self { - Self { - voices: Default::default(), - last_processing_time: Duration::ZERO, - paused: false, - epoch: 0, - } - } - - fn apply_delivery_into(&mut self, delivery: AudioDelivery, packet: &mut Packet) { - if delivery.epoch < self.epoch { - packet.batches = [delivery.frame, delivery.lifecycle]; - return; - } - if delivery.epoch != self.epoch { - for voice in &mut self.voices { - packet.retire(voice.sample.take()); - *voice = Channel::default(); - } - self.epoch = delivery.epoch; - } - for (slot, batch) in packet.batches.iter_mut().zip([delivery.frame, delivery.lifecycle]) { - *slot = batch; - } - // Move commands out of slots, keeping each vector allocation in its packet. - for index in 0..2 { - if let Some(mut batch) = packet.batches[index].take() { - for command in &mut batch { - let command = - std::mem::replace(command, AudioCommand::Stop { voice_id: MAX_CHANNELS }); - self.process_command(command, packet); - } - packet.batches[index] = Some(batch); - } - } - self.paused = delivery.paused; - } - - fn retire_inactive(&mut self, packet: &mut Packet) { - for voice in &mut self.voices { - if !voice.active { - packet.retire(voice.sample.take()); - } - } - } - - // Signal-only tests use synchronous reclamation outside a data callback. - #[cfg(test)] - fn apply_delivery(&mut self, delivery: AudioDelivery) { - self.apply_delivery_into(delivery, &mut Packet::new()); - } - #[cfg(test)] - fn fill_buffer(&mut self, buffer: &mut [f32]) { - self.mix(buffer); - self.retire_inactive(&mut Packet::new()); - } - - fn process_command(&mut self, cmd: AudioCommand, packet: &mut Packet) { - match cmd { - AudioCommand::Play { sample, voice_id, volume, pan, pitch, priority, loop_mode } => { - if voice_id < MAX_CHANNELS { - packet.retire(self.voices[voice_id].sample.take()); - self.voices[voice_id] = Channel { - sample: Some(sample), - active: true, - pos: 0.0, - pitch, - volume, - pan, - loop_mode, - priority, - }; - } else { - packet.retire(Some(sample)); - } - } - AudioCommand::Stop { voice_id } => { - if voice_id < MAX_CHANNELS { - self.voices[voice_id].active = false; - packet.retire(self.voices[voice_id].sample.take()); - } - } - AudioCommand::SetVolume { voice_id, volume } => { - if voice_id < MAX_CHANNELS { - self.voices[voice_id].volume = volume; - } - } - AudioCommand::SetPan { voice_id, pan } => { - if voice_id < MAX_CHANNELS { - self.voices[voice_id].pan = pan; - } - } - AudioCommand::SetPitch { voice_id, pitch } => { - if voice_id < MAX_CHANNELS { - self.voices[voice_id].pitch = pitch; - } - } - } - } - - fn mix(&mut self, buffer: &mut [f32]) { - let start = std::time::Instant::now(); - // Zeroes the buffer (stereo) - for sample in buffer.iter_mut() { - *sample = 0.0; - } - - if self.paused { - self.last_processing_time = start.elapsed(); - return; - } - - for voice in self.voices.iter_mut() { - if !voice.active { - continue; - } - let Some(sample) = voice.sample.as_ref() else { - continue; - }; - let len = sample.data.len(); - if len == 0 { - voice.active = false; - continue; - } - let (loop_start, end) = match (voice.loop_mode, sample.loop_start, sample.loop_end) { - (LoopMode::On, Some(start), Some(end)) if start < end && end as usize <= len => { - (start as f64, end as f64) - } - _ => (0.0, len as f64), - }; - let ratio = sample.sample_rate as f64 / OUTPUT_SAMPLE_RATE as f64; - let volume = voice.volume as f32 / 255.0; - let pan = voice.pan as f32 / 255.0; - let left = volume * (1.0 - pan).sqrt(); - let right = volume * pan.sqrt(); - for frame in buffer.as_chunks_mut::<2>().0 { - let pos = voice.pos as usize; - if pos >= len { - voice.active = false; - break; - } - let s1 = sample.data[pos] as f32 / 32768.0; - let next = if voice.loop_mode == LoopMode::On && (pos + 1) as f64 >= end { - loop_start as usize - } else { - pos + 1 - }; - let s2 = sample.data.get(next).copied().unwrap_or(0) as f32 / 32768.0; - let value = s1 + (s2 - s1) * (voice.pos - pos as f64) as f32; - frame[0] += value * left; - frame[1] += value * right; - if ratio == 0.0 { - continue; - } - if voice.pitch >= (end - voice.pos) / ratio { - if voice.loop_mode == LoopMode::Off { - voice.active = false; - break; - } - let length = end - loop_start; - // Reduce before multiplication: every finite positive pitch, - // including f64::MAX, remains finite and wraps multiple loops. - let step = (voice.pitch % (length / ratio)) * ratio; - voice.pos = loop_start + (voice.pos - loop_start + step).rem_euclid(length); - if voice.pos >= end { - voice.pos = loop_start; - } - } else { - voice.pos += voice.pitch * ratio; - } - } - } - - // Final clamp to avoid clipping (optional if using f32, but good for fidelity) - for sample in buffer.iter_mut() { - *sample = sample.clamp(-1.0, 1.0); - } - self.last_processing_time = start.elapsed(); - } -} - #[cfg(test)] mod control_tests { use super::*; @@ -622,8 +434,8 @@ mod control_tests { for (frame, value) in pcm.as_chunks::<2>().0.iter().zip(expected) { assert_eq!(*frame, [value as f32 / 32768.0, 0.0]); } - assert_eq!(mixer.voices[0].active, looping); - assert_eq!(mixer.voices[0].sample.is_some(), looping); + assert_eq!(mixer.voices[24].active, looping); + assert_eq!(mixer.voices[24].sample.is_some(), looping); } } @@ -653,7 +465,7 @@ mod control_tests { let value = if looping || i < 4 { (i % 4 + 1) as f32 / 8.0 } else { 0.0 }; assert_eq!(*frame, [value, 0.0], "markers {start:?}/{end:?}, loop {looping}"); } - assert_eq!(mixer.voices[0].active, looping); + assert_eq!(mixer.voices[24].active, looping); } } } @@ -683,7 +495,7 @@ mod control_tests { assert!((frame[0] - value).abs() <= 1e-6); assert_eq!(frame[1], 0.0); } - assert_eq!(mixer.voices[0].active, looping); + assert_eq!(mixer.voices[24].active, looping); } } } @@ -701,8 +513,8 @@ mod control_tests { let mut pcm = [1.0; 8]; mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.0; 8]); - assert!(!mixer.voices[0].active); - assert!(mixer.voices[0].sample.is_none()); + assert!(!mixer.voices[24].active); + assert!(mixer.voices[24].sample.is_none()); } } } @@ -722,7 +534,7 @@ mod control_tests { let mut pcm = [0.0; 10]; mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.125, 0.0, 0.25, 0.0, 0.5, 0.0, 0.25, 0.0, 0.5, 0.0]); - assert_eq!(mixer.voices[0].pos, 1.0); + assert_eq!(mixer.voices[24].pos, 1.0); } } @@ -742,12 +554,12 @@ mod control_tests { let mut pcm = [0.0; 128]; mixer.fill_buffer(&mut pcm); assert!(pcm.iter().all(|value| value.is_finite())); - assert!(mixer.voices[0].pos.is_finite()); + assert!(mixer.voices[24].pos.is_finite()); if rate == 0 { - assert_eq!(mixer.voices[0].pos, 0.0); + assert_eq!(mixer.voices[24].pos, 0.0); assert!(pcm.as_chunks::<2>().0.iter().all(|frame| *frame == [0.125, 0.0])); } else if looping { - assert!((1.0..3.0).contains(&mixer.voices[0].pos)); + assert!((1.0..3.0).contains(&mixer.voices[24].pos)); assert!( pcm.as_chunks::<2>() .0 @@ -759,7 +571,7 @@ mod control_tests { assert_eq!(&pcm[..2], &[0.125, 0.0]); assert!(pcm[2..].iter().all(|value| *value == 0.0)); } - assert_eq!(mixer.voices[0].active, looping || rate == 0); + assert_eq!(mixer.voices[24].active, looping || rate == 0); } } } @@ -773,29 +585,29 @@ mod control_tests { let mut pcm = [0.0; 4]; mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.5, 0.0, 0.5, 0.0]); - assert_eq!(mixer.voices[0].pos, 2.0); + assert_eq!(mixer.voices[24].pos, 2.0); audio.set_pan(0, 255); audio.set_volume(0, 51); audio.set_pitch(0, 2.0); audio.finish_frame(); apply(&audio, &mut mixer); - assert_eq!(mixer.voices[0].pos, 2.0); + assert_eq!(mixer.voices[24].pos, 2.0); mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.0, 0.1, 0.0, 0.1]); - assert_eq!(mixer.voices[0].pos, 6.0); + assert_eq!(mixer.voices[24].pos, 6.0); audio.set_volume(0, 0); audio.finish_frame(); apply(&audio, &mut mixer); mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.0; 4]); - assert_eq!(mixer.voices[0].pos, 10.0); + assert_eq!(mixer.voices[24].pos, 10.0); audio.stop(0); audio.stop(0); audio.finish_frame(); apply(&audio, &mut mixer); mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.0; 4]); - assert!(mixer.voices[0].sample.is_none()); + assert!(mixer.voices[24].sample.is_none()); } #[test] @@ -811,7 +623,7 @@ mod control_tests { let mut pcm = [0.0; 2]; mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.25, 0.0]); - assert_eq!(mixer.voices[0].pos, 1.0); + assert_eq!(mixer.voices[24].pos, 1.0); } #[test] @@ -825,7 +637,7 @@ mod control_tests { let mut pcm = [1.0; 4]; mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.0; 4]); - assert_eq!(mixer.voices[0].pos, 0.0); + assert_eq!(mixer.voices[24].pos, 0.0); audio.begin_lifecycle(); audio.set_pan(0, 255); audio.finish_lifecycle(true); @@ -833,7 +645,7 @@ mod control_tests { apply(&audio, &mut mixer); mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.0, 0.5, 0.0, 0.5]); - assert_eq!(mixer.voices[0].pos, 2.0); + assert_eq!(mixer.voices[24].pos, 2.0); play(&mut audio, Arc::new(Sample::new(48_000, vec![16384; 16])), 1.0, true); audio.finish_frame(); let stale = audio.transport().try_take().unwrap(); @@ -854,7 +666,7 @@ mod control_tests { audio.stop(0); audio.finish_lifecycle(true); apply(&audio, &mut mixer); - assert!(mixer.voices[0].sample.is_none()); + assert!(mixer.voices[24].sample.is_none()); audio.begin_lifecycle(); audio.finish_lifecycle(true); audio.set_paused(false); @@ -866,7 +678,7 @@ mod control_tests { apply(&audio, &mut mixer); mixer.fill_buffer(&mut pcm); assert_eq!(pcm, [0.0; 16]); - assert!(mixer.voices[0].sample.is_none()); + assert!(mixer.voices[24].sample.is_none()); } #[test] @@ -885,8 +697,8 @@ mod control_tests { mixer.fill_buffer(&mut pcm); assert!(pcm.iter().all(|v| v.is_finite())); assert!(pcm.as_chunks::<2>().0.iter().all(|frame| *frame == [0.5, 0.0])); - assert!(mixer.voices[0].active); - assert!(mixer.voices[0].pos >= 1.0 && mixer.voices[0].pos < 3.0); + assert!(mixer.voices[24].active); + assert!(mixer.voices[24].pos >= 1.0 && mixer.voices[24].pos < 3.0); } let (mut audio, mut mixer) = pair(); let sample = Arc::new(Sample::new(48_000, vec![16384])); @@ -899,7 +711,7 @@ mod control_tests { } #[test] - fn unloading_bank_keeps_playback_until_stop() { + fn unloading_bank_stops_playback_and_rejects_stale_play() { use prometeu_drivers::SoundBankPoolInstaller; use prometeu_hal::sound_bank::SoundBank; let banks = Arc::new(MemoryBanks::new()); @@ -914,8 +726,8 @@ mod control_tests { apply(&audio, &mut mixer); let mut pcm = [0.0; 8]; mixer.fill_buffer(&mut pcm); - assert_eq!(pcm[0], 0.5); - assert!(weak.upgrade().is_some()); + assert_eq!(pcm[0], 0.0); + assert!(weak.upgrade().is_none()); assert_eq!(audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::On), AudioOpStatus::BankInvalid); audio.stop(0); audio.finish_frame(); diff --git a/crates/host/prometeu-host-desktop-winit/src/audio/reclamation.rs b/crates/host/prometeu-host-desktop-winit/src/audio/reclamation.rs index 832cab8..f876007 100644 --- a/crates/host/prometeu-host-desktop-winit/src/audio/reclamation.rs +++ b/crates/host/prometeu-host-desktop-winit/src/audio/reclamation.rs @@ -1,40 +1,16 @@ //! Two packets circulate free -> callback -> returned -> service -> free. //! While the callback owns a packet, at most one packet can occupy the return //! lane, so its capacity-two enqueue cannot fail. Neither lane grows. -use prometeu_drivers::{AudioCommand, AudioTransport, MAX_CHANNELS, MAX_COMMANDS_PER_FRAME}; -use prometeu_hal::sample::Sample; +use prometeu_drivers::AudioTransport; +pub(super) use prometeu_drivers::engine::Packet; +#[cfg(test)] +use prometeu_drivers::engine::RETIRED_CAPACITY; use ringbuf::{ HeapRb, traits::{Consumer, Producer, Split}, wrap::{CachingCons, CachingProd}, }; use std::sync::Arc; - -pub(super) const RETIRED_CAPACITY: usize = 3 * MAX_COMMANDS_PER_FRAME + MAX_CHANNELS; -pub(super) struct Packet { - retired: Vec>, - pub batches: [Option>; 2], -} -impl Packet { - pub(super) fn new() -> Self { - Self { retired: Vec::with_capacity(RETIRED_CAPACITY), batches: [None, None] } - } - pub(super) fn retire(&mut self, sample: Option>) { - if let Some(sample) = sample { - // Every owner comes from at most 3072 Play commands or 16 slots. - assert!(self.retired.len() < RETIRED_CAPACITY, "audio retirement bound"); - self.retired.push(sample); - } - } - fn recycle(&mut self, transport: &AudioTransport) { - self.retired.clear(); - for batch in &mut self.batches { - if let Some(batch) = batch.take() { - transport.recycle_commands(batch); - } - } - } -} type Prod = CachingProd>>; type Cons = CachingCons>>; pub(super) struct CallbackLane { @@ -43,6 +19,7 @@ pub(super) struct CallbackLane { } /// Main-thread endpoint. Service independently of guest progress or pause. pub struct AudioReclaimer { + pub maximum_retired_pcm_bytes: usize, free: Prod, returned: Cons, } @@ -52,7 +29,10 @@ pub(super) fn pool() -> (CallbackLane, AudioReclaimer) { for _ in 0..2 { assert!(free.try_push(Packet::new()).is_ok()); } - (CallbackLane { free: free_cons, returned }, AudioReclaimer { free, returned: returned_cons }) + ( + CallbackLane { free: free_cons, returned }, + AudioReclaimer { free, returned: returned_cons, maximum_retired_pcm_bytes: 0 }, + ) } impl CallbackLane { pub(super) fn take(&mut self) -> Option { @@ -66,6 +46,8 @@ impl CallbackLane { impl AudioReclaimer { pub fn service(&mut self, transport: &AudioTransport) { while let Some(mut packet) = self.returned.try_pop() { + self.maximum_retired_pcm_bytes = + self.maximum_retired_pcm_bytes.max(packet.retained_pcm_bytes()); packet.recycle(transport); assert!(self.free.try_push(packet).is_ok(), "audio packet conservation"); } @@ -89,8 +71,8 @@ mod tests { service.service(&transport); for _ in 0..2 { let packet = callback.take().unwrap(); - assert_eq!(packet.retired.capacity(), RETIRED_CAPACITY); - assert!(packet.retired.is_empty()); + assert_eq!(packet.capacity(), RETIRED_CAPACITY); + assert!(packet.is_empty()); assert!(packet.batches.iter().all(Option::is_none)); callback.give_back(packet); } diff --git a/crates/host/prometeu-host-desktop-winit/tests/audio_callback_allocations.rs b/crates/host/prometeu-host-desktop-winit/tests/audio_callback_allocations.rs index b4e301e..365f448 100644 --- a/crates/host/prometeu-host-desktop-winit/tests/audio_callback_allocations.rs +++ b/crates/host/prometeu-host-desktop-winit/tests/audio_callback_allocations.rs @@ -104,7 +104,7 @@ fn callback_owners_do_not_use_allocator() { fn stalled_service_bounds_retention_and_recovers_pending_delivery() { let mut audio = Audio::new(Arc::new(MemoryBanks::new())); let (mut callback, mut reclaimer) = AudioCallback::new(); - let owners: Vec<_> = (0..16).map(|voice| play(&mut audio, voice, false)).collect(); + let owners: Vec<_> = (0..8).map(|voice| play(&mut audio, voice, false)).collect(); audio.finish_frame(); // Keep all voices playing until both packets have been returned. render(&mut callback, &audio, &mut [], "start_16"); @@ -135,7 +135,7 @@ fn full_frame_and_combined_lifecycle_fit_one_packet() { let mut audio = Audio::new(Arc::new(MemoryBanks::new())); let (mut callback, mut reclaimer) = AudioCallback::new(); let mut owners = Vec::new(); - for voice in 0..16 { + for voice in 0..8 { owners.push(play(&mut audio, voice, false)); } audio.finish_frame(); @@ -158,7 +158,7 @@ fn full_frame_and_combined_lifecycle_fit_one_packet() { let mut pcm = [0.0; 32]; render(&mut callback, &audio, &mut pcm, "3072_commands_plus_completion"); reclaimer.service(&audio.transport()); - assert!(owners.iter().skip(16).all(|owner| owner.upgrade().is_none())); + assert!(owners.iter().skip(8).all(|owner| owner.upgrade().is_none())); audio.reset(); render(&mut callback, &audio, &mut pcm, "reset_remaining_voices"); reclaimer.service(&audio.transport()); @@ -169,8 +169,8 @@ fn full_frame_and_combined_lifecycle_fit_one_packet() { /// fixture reads the checked-in asset pack and writes a temporary host save; /// it does not certify asset decoding or guest memcard scheduling. #[test] -#[ignore = "requires physical audio output; 16 quiet voices and temporary file I/O"] -fn physical_callback_duration_16_voices_with_io_pressure() { +#[ignore = "requires physical audio output; 8 quiet voices and temporary file I/O"] +fn physical_callback_duration_8_sfx_voices_with_io_pressure() { use cpal::traits::{DeviceTrait, HostTrait, StreamTrait}; use prometeu_host_desktop_winit::fs_backend::HostDirBackend; use prometeu_system::fs::FsBackend; @@ -185,7 +185,7 @@ fn physical_callback_duration_16_voices_with_io_pressure() { let mut audio = Audio::new(Arc::new(MemoryBanks::new())); let (mut callback, mut reclaimer) = AudioCallback::new(); let mut owners = vec![]; - for voice in 0..16 { + for voice in 0..8 { let sample = Arc::new(Sample::new(48000, vec![32; 4800])); owners.push(Arc::downgrade(&sample)); audio.play_sample(sample, voice, 8, 127, 1.0, 0, LoopMode::On); @@ -264,18 +264,18 @@ fn physical_callback_duration_16_voices_with_io_pressure() { ); assert!(!failed.load(Ordering::Relaxed)); assert_eq!(allocator_calls.load(Ordering::Relaxed), 0); - assert_eq!((live_before, live_after), (16, 0)); + assert_eq!((live_before, live_after), (8, 0)); } #[test] #[ignore = "release timing observation with temporary asset-read/save-write pressure"] -fn callback_duration_16_voices_with_io_pressure() { +fn callback_duration_8_sfx_voices_with_io_pressure() { use prometeu_host_desktop_winit::fs_backend::HostDirBackend; use prometeu_system::fs::FsBackend; use std::time::Instant; let mut audio = Audio::new(Arc::new(MemoryBanks::new())); let (mut callback, mut reclaimer) = AudioCallback::new(); - let owners: Vec<_> = (0..16).map(|voice| play(&mut audio, voice, true)).collect(); + let owners: Vec<_> = (0..8).map(|voice| play(&mut audio, voice, true)).collect(); audio.finish_frame(); let mut pcm = [0.0; 512]; // 256 stereo frames: nominal 5.333 ms at 48 kHz. callback.render(&audio.transport(), &mut pcm); @@ -311,7 +311,7 @@ fn callback_duration_16_voices_with_io_pressure() { samples[500], samples[950], samples[990], samples[999] ); assert_eq!(counts, (0, 0)); - assert_eq!((before, after), (16, 0)); + assert_eq!((before, after), (8, 0)); } #[test] @@ -341,7 +341,269 @@ fn unloaded_banks_empty_samples_and_controls_reclaim_on_service() { audio.finish_frame(); render(&mut callback, &audio, &mut pcm, "controls_stop_empty"); assert!(pcm.iter().all(|&sample| sample == 0.0)); - assert!(weak.upgrade().is_some() && weak_empty.upgrade().is_some()); + assert!(weak.upgrade().is_none() && weak_empty.upgrade().is_some()); reclaimer.service(&audio.transport()); assert!(weak.upgrade().is_none() && weak_empty.upgrade().is_none()); } + +fn music_fixture() -> Arc { + use prometeu_hal::music_bank::{Instrument, MusicBank, MusicEvent}; + let sample = + Arc::new(Sample::new(48000, vec![1000, -1500]).with_channels(2).unwrap().with_loop(0, 1)); + let mut events: Vec<_> = (0..12) + .map(|id| MusicEvent { kind: 1, a: id, c: 60, d: 255, ..Default::default() }) + .collect(); + // Every frame replaces a voice while envelopes and modulation keep running. + for tick in 1..500 { + events.push(MusicEvent { + tick, + kind: 1, + a: 12 + tick, + c: 60 + (tick % 12) as i32, + d: 180, + ..Default::default() + }); + } + Arc::new( + MusicBank::compile( + "rt".into(), + vec![sample], + vec![Instrument { + looping: true, + attack_us: 100, + release_us: 1000, + vibrato_millihz: 6000, + vibrato_cents: 20, + tremolo_millihz: 4000, + tremolo_depth: 1000, + send: 32768, + ..Default::default() + }], + events, + 960, + 20_000, + 1000, + None, + 1, + ) + .unwrap(), + ) +} +#[test] +fn thirty_two_stereo_voices_sequences_dsp_and_bank_retirement_never_call_allocator() { + use prometeu_drivers::SoundBankPoolInstaller; + use prometeu_hal::audio_bridge::AudioControl; + let banks = Arc::new(MemoryBanks::new()); + let mut audio = Audio::new(banks.clone()); + banks.install_music_bank(0, music_fixture()); + audio.music_play(0, 0, true); + audio.music_play(1, 0, true); + for voice in 0..8 { + let sample = + Arc::new(Sample::new(48000, vec![500, -500]).with_channels(2).unwrap().with_loop(0, 1)); + audio.play_sample(sample, voice, 255, 128, 1.0, 0, LoopMode::On); + } + for group in 0..3 { + audio.control(AudioControl::Effect { + group, + cutoff_hz: 6000, + delay_frames: 48, + feedback: 0.5, + wet: 0.3, + dry: 0.7, + }); + } + audio.finish_frame(); + let (mut callback, mut reclaimer) = AudioCallback::new(); + let mut pcm = [0.0; 512]; + render(&mut callback, &audio, &mut pcm, "32_stereo_sequencers_adsr_modulation_dsp"); + assert_eq!(callback.diagnostics().maximum_voices, 32); + reclaimer.service(&audio.transport()); + for _ in 0..20 { + banks.install_music_bank(0, music_fixture()); + audio.music_play(0, 0, true); + audio.music_play(1, 0, true); + audio.control(AudioControl::Crossfade { source: 0, target: 1, frames: 48, smooth: true }); + audio.finish_frame(); + render(&mut callback, &audio, &mut pcm, "32_bank_replacement_and_crossfade"); + reclaimer.service(&audio.transport()); + } + // Exhaust both packets, then invalidate banks and keep processing safely. + render(&mut callback, &audio, &mut pcm, "pool_first"); + render(&mut callback, &audio, &mut pcm, "pool_second"); + banks.unload_audio_bank(true, 0); + for _ in 0..10 { + render(&mut callback, &audio, &mut pcm, "music_invalidated_without_packet"); + } + reclaimer.service(&audio.transport()); + render(&mut callback, &audio, &mut pcm, "retire_after_starvation"); + reclaimer.service(&audio.transport()); +} + +#[test] +#[ignore = "physical 48 kHz output; emits a quiet tone for two seconds"] +fn physical_32_stereo_voices_with_dsp_and_bank_replacement() { + use cpal::traits::{DeviceTrait, HostTrait, StreamTrait}; + use prometeu_drivers::SoundBankPoolInstaller; + use prometeu_hal::{ + audio_bridge::AudioControl, + music_bank::{Instrument, MusicBank, MusicEvent}, + }; + use ringbuf::{ + HeapRb, + traits::{Consumer, Producer, Split}, + }; + use std::{ + sync::atomic::{AtomicUsize, Ordering}, + time::{Duration, Instant}, + }; + let device = cpal::default_host().default_output_device().expect("physical output device"); + let name = device.name().unwrap(); + let sample = Arc::new( + Sample::new( + 48000, + (0..256) + .flat_map(|i| { + let v = ((i as f64 * std::f64::consts::TAU / 256.0).sin() * 512.0) as i16; + [v, v] + }) + .collect(), + ) + .with_channels(2) + .unwrap() + .with_loop(0, 256), + ); + let make_bank = || { + Arc::new( + MusicBank::compile( + "physical".into(), + vec![sample.clone()], + vec![Instrument { looping: true, send: 32768, ..Default::default() }], + (0..12) + .map(|n| MusicEvent { + kind: 1, + a: n, + c: 60 + n as i32, + d: 255, + ..Default::default() + }) + .collect(), + 960, + 500000, + 3840, + None, + 1, + ) + .unwrap(), + ) + }; + let banks = Arc::new(MemoryBanks::new()); + banks.install_music_bank(0, make_bank()); + banks.install_music_bank(1, make_bank()); + let mut audio = Audio::new(banks.clone()); + audio.music_play(0, 0, true); + audio.music_play(1, 1, true); + for group in 0..2 { + audio.control(AudioControl::MusicVolume { group, gain: 8 }); + } + for voice in 0..8 { + audio.play_sample(sample.clone(), voice, 8, 128, 1.0, 0, LoopMode::On); + audio.control(AudioControl::SfxSend { voice, gain: 100 }); + } + for group in 0..3 { + audio.control(AudioControl::Effect { + group, + cutoff_hz: 6000, + delay_frames: 4800, + feedback: 0.5, + wet: 0.3, + dry: 0.7, + }); + } + audio.finish_frame(); + let (mut callback, mut reclaimer) = AudioCallback::new(); + let transport = audio.transport(); + let (mut writer, mut reader) = HeapRb::<(u64, usize, usize)>::new(4096).split(); + let failures = Arc::new(AtomicUsize::new(0)); + let allocator = Arc::new(AtomicUsize::new(0)); + let failure = failures.clone(); + let allocations = allocator.clone(); + let config = cpal::StreamConfig { + channels: 2, + sample_rate: cpal::SampleRate(48000), + buffer_size: cpal::BufferSize::Fixed(256), + }; + let stream = device + .build_output_stream( + &config, + move |data: &mut [f32], _: &cpal::OutputCallbackInfo| { + let start = Instant::now(); + let (a, d) = measured(|| callback.render(&transport, data)); + allocations.fetch_add(a + d, Ordering::Relaxed); + let _ = writer.try_push(( + start.elapsed().as_nanos() as u64, + data.len() / 2, + callback.diagnostics().maximum_voices, + )); + }, + move |_| { + failure.fetch_add(1, Ordering::Relaxed); + }, + None, + ) + .unwrap(); + let temporary = + std::env::temp_dir().join(format!("prometeu-audio-32-pressure-{}", std::process::id())); + let pressure = vec![0x5a; 512 * 1024]; + let fixture = include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-music.mbnk" + )); + stream.play().unwrap(); + let end = Instant::now() + Duration::from_secs(2); + let mut replacements = 0; + while Instant::now() < end { + std::fs::write(&temporary, &pressure).unwrap(); + let decoded = prometeu_drivers::bank_format::decode_audio_bank(fixture, true).unwrap(); + std::hint::black_box(decoded); + reclaimer.service(&audio.transport()); + if audio.ready() { + banks.install_music_bank(0, make_bank()); + audio.music_play(0, 0, true); + audio.control(AudioControl::MusicVolume { group: 0, gain: 8 }); + audio.finish_frame(); + replacements += 1; + } + std::thread::sleep(Duration::from_millis(2)); + } + stream.pause().unwrap(); + drop(stream); + reclaimer.service(&audio.transport()); + std::fs::remove_file(temporary).unwrap(); + let mut timings = Vec::new(); + let mut overruns = 0; + let mut maximum_voices = 0; + while let Some((n, frames, voices)) = reader.try_pop() { + maximum_voices = maximum_voices.max(voices); + timings.push(n); + if n as u128 > frames as u128 * 1_000_000_000 / 48000 { + overruns += 1; + } + } + timings.sort_unstable(); + assert!(!timings.is_empty()); + let n = timings.len(); + println!( + "physical_32_stereo device={name:?} maximum_voices={maximum_voices} callbacks={n} replacements={replacements} p50_ns={} p95_ns={} p99_ns={} max_ns={} budget_overruns={overruns} device_errors={} allocator_calls={} maximum_retired_pcm_bytes={}", + timings[n / 2], + timings[n * 95 / 100], + timings[n * 99 / 100], + timings[n - 1], + failures.load(Ordering::Relaxed), + allocator.load(Ordering::Relaxed), + reclaimer.maximum_retired_pcm_bytes + ); + assert_eq!(maximum_voices, 32); + assert_eq!(failures.load(Ordering::Relaxed), 0); + assert_eq!(allocator.load(Ordering::Relaxed), 0); +} diff --git a/crates/host/prometeu-host-headless/src/host.rs b/crates/host/prometeu-host-headless/src/host.rs index 8da66d7..d3979f2 100644 --- a/crates/host/prometeu-host-headless/src/host.rs +++ b/crates/host/prometeu-host-headless/src/host.rs @@ -124,6 +124,8 @@ impl std::error::Error for HostError {} /// In-process host. The desktop winit runner is a separate crate and is not linked here. pub struct HeadlessHost { + audio: Box, + audio_packet: prometeu_drivers::engine::Packet, firmware: Firmware, platform: HeadlessPlatform, signals: InputSignals, @@ -156,6 +158,25 @@ impl HeadlessHost { self.firmware.os.memcard().admission.state } + fn apply_audio_commands(&mut self) { + let transport = self.platform.hardware.audio.transport(); + self.audio.retire_inactive(&mut self.audio_packet); + if let Some(delivery) = transport.try_take() { + self.audio.apply_delivery_into(delivery, &mut self.audio_packet); + } + self.audio_packet.recycle(&transport); + } + /// Render stereo 48 kHz independently of firmware/graphics progress. + pub fn render_audio(&mut self, output: &mut [f32]) { + self.apply_audio_commands(); + self.audio.mix(output); + self.audio.retire_inactive(&mut self.audio_packet); + self.audio_packet.recycle(&self.platform.hardware.audio.transport()); + } + pub fn audio_diagnostics(&self) -> prometeu_drivers::engine::AudioDiagnostics { + self.audio.diagnostics + } + pub fn new() -> Self { let clock = Arc::new(ControlledWallClock::default()); Self::with_clock(clock.clone(), Some(clock)) @@ -174,6 +195,8 @@ impl HeadlessHost { let hardware = Hardware::new_with_memory_banks(Arc::clone(&memory_banks), clock); let store = LatestRenderFrameStore::default(); Self { + audio: Box::new(prometeu_drivers::engine::AudioMixer::new()), + audio_packet: prometeu_drivers::engine::Packet::new(), firmware: Firmware::new(None), platform: HeadlessPlatform { hardware, store }, signals: InputSignals::default(), @@ -341,12 +364,14 @@ impl HeadlessHost { pub fn pause(&mut self) -> Result<(), HostError> { self.require_active("pause")?; self.firmware.os.vm().set_paused(true); + self.platform.hardware.audio.set_paused(true); Ok(()) } pub fn resume(&mut self) -> Result<(), HostError> { self.require_active("resume")?; self.firmware.os.vm().set_paused(false); + self.platform.hardware.audio.set_paused(false); Ok(()) } @@ -354,8 +379,9 @@ impl HeadlessHost { pub fn step(&mut self) -> Result, HostError> { self.require_active("step")?; self.firmware.os.vm().set_paused(true); + self.platform.hardware.audio.set_paused(true); let report = self.firmware.os.vm().debug_step_active_session(&mut self.platform); - self.platform.hardware.audio.transport().consume_silently(); + self.apply_audio_commands(); Ok(report) } @@ -543,7 +569,7 @@ impl HeadlessHost { fn tick_once(&mut self) { self.firmware.tick(&self.signals, &mut self.platform); - self.platform.hardware.audio.transport().consume_silently(); + self.apply_audio_commands(); } fn execution_status(&mut self) -> HostExecutionStatus { @@ -732,3 +758,114 @@ mod tests { directory } } + +#[cfg(test)] +mod offline_audio_tests { + use super::*; + use prometeu_drivers::{ + SoundBankPoolInstaller, + bank_format::{DecodedAudioBank, decode_audio_bank}, + }; + #[test] + fn cartridge_preloads_both_bank_types_and_guest_music_sfx_reach_shared_renderer() { + use prometeu_bytecode::{assembler::assemble, model::SyscallDecl}; + use prometeu_hal::cartridge::{ + ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude, + }; + use prometeu_test_support::program::{TestProgram, int64_signature}; + let unique = + std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(); + let root = std::env::temp_dir() + .join(format!("prometeu-audio-cartridge-{}-{unique}", std::process::id())); + std::fs::create_dir_all(&root).unwrap(); + let code=assemble("PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 1\nHOSTCALL 0\nPOP_N 1\nPUSH_I32 1\nPUSH_I32 0\nPUSH_I32 1\nHOSTCALL 0\nPOP_N 1\nPUSH_I32 0\nPUSH_I32 1\nPUSH_I32 0\nPUSH_I32 128\nPUSH_I32 128\nPUSH_I32 1\nPUSH_I32 1\nHOSTCALL 1\nPOP_N 1\nFRAME_SYNC\nRET").unwrap(); + let mut program = TestProgram::single(code, int64_signature(0, 0), 0, 7); + program.syscalls = vec![ + SyscallDecl { + module: "music".into(), + name: "play".into(), + version: 1, + arg_slots: 3, + ret_slots: 1, + }, + SyscallDecl { + module: "audio".into(), + name: "play".into(), + version: 1, + arg_slots: 7, + ret_slots: 1, + }, + ]; + std::fs::write(root.join("program.pbx"), program.serialize()).unwrap(); + std::fs::write(root.join("manifest.json"),r#"{"magic":"PMTU","cartridge_version":1,"app_id":87,"title":"Audio pipeline","app_version":"1.0","app_mode":"Game","capabilities":["audio"]}"#).unwrap(); + let sound = include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-sound.sbnk" + )); + let music = include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-music.mbnk" + )); + let header=serde_json::to_vec(&serde_json::json!({"asset_table":[{"asset_id":1,"asset_name":"sfx","bank_type":"SOUNDS","offset":0,"size":sound.len(),"decoded_size":6139,"codec":"NONE","metadata":{"version":1}},{"asset_id":2,"asset_name":"music","bank_type":"MUSIC","offset":sound.len(),"size":music.len(),"decoded_size":6395,"codec":"NONE","metadata":{"version":1}}],"preload":[{"asset_id":1,"slot":0},{"asset_id":2,"slot":0}]})).unwrap(); + let mut pack = AssetsPackPrelude { + magic: ASSETS_PA_MAGIC, + schema_version: ASSETS_PA_SCHEMA_VERSION, + header_len: header.len() as u32, + payload_offset: (32 + header.len()) as u64, + flags: 0, + reserved: 0, + header_checksum: 0, + } + .to_bytes() + .to_vec(); + pack.extend(header); + pack.extend(sound); + pack.extend(music); + std::fs::write(root.join("assets.pa"), pack).unwrap(); + let mut host = HeadlessHost::new(); + host.boot(root.to_string_lossy()).unwrap(); + assert!(matches!( + host.advance_frame().unwrap(), + AdvanceFrameOutcome::FrameCompleted { .. } + )); + host.resume().unwrap(); + let before = host.firmware.os.vm().logical_frame_index(); + let mut output = vec![0.0; 9600]; + host.render_audio(&mut output); + assert!(output.iter().any(|v| *v != 0.0)); + assert_eq!(host.audio_diagnostics().maximum_voices, 5); + assert_eq!(host.firmware.os.vm().logical_frame_index(), before); + let audio_before = host.audio_diagnostics().frames; + host.pause().unwrap(); + let mut paused = [1.0; 200]; + host.render_audio(&mut paused); + assert_eq!(paused, [0.0; 200]); + assert_eq!(host.audio_diagnostics().frames, audio_before); + host.resume().unwrap(); + host.render_audio(&mut paused); + assert_eq!(host.audio_diagnostics().frames, audio_before + 100); + drop(host); + std::fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn explicit_audio_render_advances_shared_sequence_without_any_game_frame() { + let mut host = HeadlessHost::new(); + let bytes = include_bytes!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../../test-fixtures/audio/mixed-music.mbnk" + )); + let DecodedAudioBank::Music(bank) = decode_audio_bank(bytes, true).unwrap() else { + panic!() + }; + host.platform.hardware.memory_banks.install_music_bank(0, Arc::new(bank)); + host.platform.hardware.audio.music_play(0, 0, true); + host.platform.hardware.audio.finish_frame(); + let before = host.firmware.os.vm().logical_frame_index(); + let mut pcm = vec![0.0; 4800]; + host.render_audio(&mut pcm); + assert_eq!(host.audio_diagnostics().frames, 2400); + assert!(pcm.iter().any(|v| *v != 0.0)); + assert_eq!(host.firmware.os.vm().logical_frame_index(), before); + } +} diff --git a/docs/specs/runtime/05-audio-peripheral.md b/docs/specs/runtime/05-audio-peripheral.md index ff30b96..0e92c18 100644 --- a/docs/specs/runtime/05-audio-peripheral.md +++ b/docs/specs/runtime/05-audio-peripheral.md @@ -1,70 +1,82 @@ # Audio Peripheral -Domain: virtual hardware: audio +Domain: virtual hardware: audio. Function: normative. -Function: normative +## Machine contract -Didactic companion: [Audio admission and lifecycle delivery](../../../discussion/lessons/DSC-0055-guest-audio-voice-control/LSN-0069-audio-admission-needs-a-delivery-boundary-and-independent-lifecycle-control.md). +The peripheral mixes **32 PCM voices** into stereo output at **48000 Hz**: +12 Music A, 12 Music B, and 8 SFX. Groups never borrow voices. Mono and stereo +samples each consume one logical voice. Music groups have independent resident +bank selection, sequence, tempo, loop, volume, pause, automation and effects. +A shared Rust engine performs desktop, headless and offline execution; the host +owns physical scheduling and the output device. -## 1 Scope and machine limits +The authoritative binary format, instrument/event model, numerical rules and new +high-level ABI are in [Audio banks and sequences](05a-audio-bank-format.md). +SoundBank and MusicBank each have 16 independent resident slots. A MusicBank +contains exactly one complete composition and every required instrument/sample. +Loading is explicit and atomic. PCM16_LE and IMA_ADPCM_WAV4 are selected per +sample, decoded completely during loading and resident as PCM16. The mixer never +decodes assets or loads a bank implicitly. -The AUDIO peripheral provides command-driven PCM playback on **16 explicitly selected voices**. Each voice plays one immutable mono PCM16 sample, with independent volume, stereo pan, playback rate and optional looping. The output target is **48,000 Hz stereo**, with saturating mixing. Hosts may use normalized floating-point device buffers to represent that output. +## SFX controls and status -The guest controls playback at logical-frame boundaries. The host renders samples independently of the 60 Hz game loop. These are separate clocks: a successful syscall admits a command, without promising that sound has already reached the device or a fixed latency in milliseconds. +Existing audio play/control identities keep their single current meaning; no +legacy voice/format path is provided. `audio.play(bank,sample,voice,volume,pan, +pitch,loop)` and `audio.play_sample(sample,voice,volume,pan,pitch)` address SFX +local voices **0..7**. The latter selects resident SoundBank 0 with looping off. +A play replaces that voice. Stop is immediate/idempotent and setters do not +start an inactive voice. No allocation/stealing of another SFX voice occurs. -This surface does not define playback handles, completion queries/events, automatic voice allocation, music sequencing, synthesis, streaming, envelopes or background audio producers. +Volume and pan/balance are 0..255; bank slots are 0..15 and sample indices +0..65535. Pitch is finite and positive; loop is exactly 0 or 1. Validate before +narrowing. Structural type/capability checks precede operational validation; +voice precedes resource lookup, and invalid commands never consume quota. -## 2 Guest ABI v1 +All operations require AUDIO and return one status at five logical cycles: +0 OK (admitted asynchronously), 1 VOICE_INVALID (direct SFX play/stop/setters), +2 SAMPLE_NOT_FOUND, 3 ARG_RANGE_INVALID (including high-level group/bus/send selectors), 4 ASSET_NOT_FOUND (reserved), +5 NO_EFFECT (reserved), 6 BANK_INVALID, +7 COMMAND_LIMIT. Loading/decoding remains asset-manager work. -Every entry requires capability `AUDIO`, returns exactly one `status:int`, and has fixed syscall cost **5 cycles**, including operational rejection. Structural ABI misuse follows the VM trap policy. Mixing time is host work, not the syscall's logical cycle charge. +## Playback and signal -| Identity | ID | Arguments in order | -| --- | --- | --- | -| `audio.play_sample` | `0x3001` | `sample:int, voice:int, volume:int, pan:int, pitch:number` | -| `audio.play` | `0x3002` | `bank:int, sample:int, voice:int, volume:int, pan:int, pitch:number, loop:int` | -| `audio.stop` | `0x3003` | `voice:int` | -| `audio.set_volume` | `0x3004` | `voice:int, volume:int` | -| `audio.set_pan` | `0x3005` | `voice:int, pan:int` | -| `audio.set_pitch` | `0x3006` | `voice:int, pitch:number` | +Immutable samples are referenced without PCM copies per voice. Source-rate ratio +and pitch advance a fractional cursor with linear interpolation. Loop bounds are +validated decoded frames, start inclusive/end exclusive; playback begins at zero +and preserves an intro. Loop-off ends at the full sample length. Interpolation +wraps at loop-end when looping. A finite large rate must wrap safely without an +infinite position. Empty nonlooped samples are inactive without reading memory. -`number` means the existing VM numeric carriers accepted by audio playback, including integer and floating-point values; it is not a new ABI type. `play_sample` uses bank 0 and looping off. Both plays use internal priority 0. The public API has no priority argument. +Mono uses equal-power pan; stereo balance preserves its original two channels at +center. Instrument/track/group, Music Bus, SFX Bus and master gains compose before +final saturation. The three groups each have shared low-pass/delay processing and +selective sends; no per-voice DSP chain exists. Fade, envelope, LFO, portamento and +musical event timing use the audio timeline, independently of the game frame. -### 2.1 Ranges and validation +## Ownership, replacement and real-time processing -- Voice: integer **0..15**. -- Bank: integer **0..15**, referring to an installed sound bank. Validate before narrowing; 256 must never alias bank 0. -- Sample index: integer **0..65535**; the sample must exist in the selected bank. -- Volume: integer **0..255**. Zero silences output while playback position continues advancing. -- Pan: integer **0..255**, from fully left to fully right. The mixer uses equal-power gains `sqrt(1-pan/255)` and `sqrt(pan/255)`. -- Pitch: **finite and strictly positive**; 1 means original speed. NaN, infinity, zero and negative values are rejected. No 0.25..4 restriction is imposed. Setters and plays use the same range. -- Loop: integer **0 or 1**, meaning off or on. Other values are rejected, without normalization. +Unload/replacement invalidates the old bank instance. Its active groups/voices +stop on audio consumption, and stale queued plays cannot restart it. Failed +replacement preparation preserves the old bank. Developers can fade/stop first. +Old references stay valid until reclaimed safely outside the callback; buffers +already delivered to a physical device cannot be recalled. Music invalidation +clears only affected group effect history. Already mixed SFX delay tails may end +naturally while their source voices are stopped. -Structural type/shape/capability checks precede operational validation. Validate voice first, then other arguments/resources, then command admission. Rejection must not alter playback state or enqueue a command. When multiple operational errors exist, voice takes precedence; bank validity precedes sample lookup for bank playback. - -### 2.2 Status values - -| Value | Name | Meaning | -| --- | --- | --- | -| 0 | `OK` | Command admitted; application is asynchronous | -| 1 | `VOICE_INVALID` | Voice outside 0..15 | -| 2 | `SAMPLE_NOT_FOUND` | Sample absent from the selected installed bank | -| 3 | `ARG_RANGE_INVALID` | Invalid sample index, volume, pan, pitch or loop value | -| 4 | `ASSET_NOT_FOUND` | Reserved existing status | -| 5 | `NO_EFFECT` | Reserved existing status; inactive-voice controls do not use it | -| 6 | `BANK_INVALID` | Invalid or uninstalled sound bank | -| 7 | `COMMAND_LIMIT` | Current guest batch already admitted 1,024 commands | - -Stop and setters can return 0, 1, 3 where applicable, or 7. Stopping an inactive voice or changing its parameters succeeds. No helper based on the driver's former activity mirror is exposed as a playback-completion query. - -## 3 Ordering and voice reuse - -Commands in a published batch apply in emission order before a subsequent output buffer. The API does not promise sample offsets within a buffer. - -A play explicitly replaces the selected voice, resets its position, and supplies every playback parameter. There is no automatic stealing of another voice. `play(A), stop, play(B)` on one voice leaves B playing. A setter following play changes that playback without resetting position. Stop is idempotent, releases the sample and silences the voice. Setters on inactive voices do not establish defaults for future plays. +The callback must not allocate, deallocate a last runtime owner, block, perform +I/O, decode assets, or execute unbounded event/control work. Samples, MusicBanks, +invalidation tokens, command vectors and prepared DSP storage follow bounded +retirement/service rules. Host service runs while guest execution is paused or +backpressured. Absence/failure of an output device must not deadlock publication. +Headless conformance executes the shared engine with explicit frame advancement; +silent command consumption alone is not evidence of sequencer or PCM behavior. +Headless pause/resume publishes global audio pause state immediately, so explicit +audio rendering does not need another VM/graphics tick to observe that control. ## 4 Admission, publication and backpressure -A logical frame admits at most **1,024 commands**, shared by both plays and all four controls. Invalid calls do not consume quota. An excess call returns `COMMAND_LIMIT`; a rejected stop requires a guest retry. Quota depends on the logical frame, not the device callback speed or number of physical host ticks. +A logical frame admits at most **1,024 commands**, shared by guest SFX, music, bus and effect commands. Bank unload is an asset-owner action outside this admission quota, as specified in the audio-bank ABI. Invalid calls do not consume quota. An excess call returns `COMMAND_LIMIT`; a rejected stop requires a guest retry. Quota depends on the logical frame, not the device callback speed or number of physical host ticks. Except for the lifecycle prefix publication defined below, commands remain staged until successful logical-frame completion: explicit `FRAME_SYNC` or the runtime's implicit frame end when the entry function returns (`EndOfRom`). An aborted/faulted frame or `HALT` cancels its unpublished commands. Debugger stepping preserves staging and publishes at either successful completion boundary. @@ -82,58 +94,11 @@ Home and debugger pause stop progression of Game voices, preserving their positi Reset, termination, crash or cartridge replacement ends the audio session, stops all its voices and invalidates its pending/staged commands. Internal session generations prevent old deliveries from restarting playback. Ending a session may cancel previously admitted commands. Silence is guaranteed from processing the transition in the mixer; buffers already submitted to a physical device cannot be recalled. -## 6 Samples, interpolation and ownership -Samples are immutable PCM16 mono, with a source sample rate and optional loop bounds. With looping off, playback ignores all loop markers and ends at the full sample length. With looping on, both markers must be present and satisfy `start < end <= sample length`; otherwise the loop interval is the full sample `[0, length)`. Playback starts at position zero, preserving the intro before the selected loop start, and wraps at the exclusive loop end. Empty samples terminate without reading PCM data. +## Qualification -Linear interpolation uses fractional playback position. With looping off, the next value is the next actual sample frame, or zero beyond the full sample length. With looping on, interpolation across the selected loop end uses the loop-start frame. Playback rate combines source/output sample-rate ratio and pitch. Loop steps may cross multiple repetitions; finite positive pitch, including `f64::MAX`, must not accidentally terminate a short loop or produce an infinite position. - -Unloading or replacing a bank does not interrupt a sample already retained by an admitted command or mixer voice. New plays resolve the current bank. Memory may remain retained after the command is cancelled or playback ends, stops, is replaced, or its session ends, until the host service reclaims the retired owner. Logical inactivity and physical reclamation are separate. The driver must not maintain a second playback mirror that cannot observe completion. - -## 7 Host responsibilities and evidence - -The desktop host consumes batches, mixes PCM and schedules the physical output. If no output device is available, it consumes committed batches silently. A failed or stalled device is diagnosed and detached so pending publication cannot block the guest indefinitely. The desktop implementation treats two seconds without callback progress as a stalled output. - -Headless execution consumes committed batches silently and preserves incomplete frame/callback staging. It validates admission and runtime behavior, without proving audible output. Synthetic mixer tests establish signal behavior; a real device smoke establishes stream initialization and callback consumption, while listening remains a separate observation. Bit-identical PCM across physical devices is not required. - -### Bounded desktop reclamation - -The successful desktop data callback MUST perform no allocation or deallocation -of runtime-owned memory, including command-vector storage and the last Sample/PCM -owner. This excludes CPAL/device internals and asynchronous driver error reporting. -It is not an absolute device-latency guarantee. - -Initialization allocates exactly two retirement packets outside the callback. -Each has room for two returned command-vector owners and 3,088 retired Sample -references: one 1,024-command frame, one combined 2,048-command lifecycle delivery, -and sixteen existing voices. Fixed-capacity SPSC free and return lanes each hold -two packets and MUST NOT grow. A checked-out packet implies a free return slot; -returning it never waits or frees overflow ownership. - -The callback MUST obtain a packet before taking a publication. It moves commands -out of vector slots, retaining the vector allocation in the packet, and moves -replaced/stopped/reset voice owners into retirement storage. Stale deliveries are -returned whole. Natural completion marks a voice inactive. Without an available -packet, no publication is taken, accepted commands remain pending under existing -backpressure, and at most sixteen inactive voice slots retain their Sample owners. -Inactive slots produce silence and do not advance. They are existing mixer slots, -not another playback mirror. Pending pause/session transitions apply when the -mixer next obtains a packet and processes control state; already emitted device -buffers cannot be recalled. - -`HostAudio::service` MUST drain and recycle packets independently of guest progress, -including paused/backpressured execution, before the next guest attempt. It frees -retired references and clears returned commands outside the callback. Empty vector -storage can be reused through a bounded four-buffer transport cache; excess empty -storage is released on the service lane. These buffers retain no Sample owners. -There is no change to guest quotas, FIFO/prefix order, session epochs, sixteen-voice -capacity, or pause position. - -Failed/stalled output is stopped and dropped before silent consumption takes over, -so only one consumer drains the publication transport. Teardown releases callback, -packet and pending-publication ownership outside the data callback. Headless/test -hosts continue consuming silently through the same transport, without constructing -an audio callback or requiring a device. - -See [callback qualification](../../vm-arch/audio-callback-qualification.md) for -executed allocation, signal, ownership and device observations. +Functional, ownership and allocation tests must cover 32 **stereo** voices, two +independent compositions plus SFX, DSP/automation, malformed banks and continuous +replacement. Report cartridge bytes, decoded PCM and actual resident/retired/DSP +memory separately. Historical 16-voice measurements do not qualify this contract. +Hardware ARM/battery qualification requires an identified physical target. diff --git a/docs/specs/runtime/05a-audio-bank-format.md b/docs/specs/runtime/05a-audio-bank-format.md new file mode 100644 index 0000000..f1a797e --- /dev/null +++ b/docs/specs/runtime/05a-audio-bank-format.md @@ -0,0 +1,270 @@ +# Audio bank and sequence format + +Domain: virtual hardware / cartridge assets. Function: normative. + +## Banks and materialization + +`SOUNDS` and `MUSIC` each have 16 independent resident slots. Loading is explicit. +The outer asset codec is `NONE`; sample descriptors select the audio codec. +The runtime validates and materializes the entire bank before publishing it. +Every sample is immutable interleaved PCM16 in resident memory. Glyph, palette, +and scene payload formats are unchanged. There is no legacy audio payload path. + +All integers below are little endian. Offsets are relative to the bank start. +Reserved bytes must be zero. Counts, lengths, arithmetic, UTF-8, enums, references, +and nonoverlapping payload bounds are validated before allocation/publication. +`decoded_size` is the canonical metadata/table bytes plus decoded PCM bytes; +actual resident allocation overhead is reported separately. No per-bank byte cap +is imposed; allocation failure is an operational load error. + +## Header (48 bytes) + +| Offset | Type | Meaning | +|---:|---|---| +| 0 | bytes[4] | `SBNK` or `MBNK` | +| 4 | u16 | version = 1 | +| 6 | u16 | flags = 0 | +| 8 | u32 | sample count | +| 12 | u32 | instrument-zone count | +| 16 | u32 | event count | +| 20 | u32 | PPQ = 960 | +| 24 | u32 | initial microseconds per quarter note, positive | +| 28 | u32 | song duration in ticks | +| 32 | u32 | song loop start tick, or 0xffffffff | +| 36 | u32 | track count (0..256) | +| 40 | u32 | UTF-8 song/bank name length | +| 44 | u32 | reserved | + +The name follows the header, then sample descriptors, instrument zones, events, +and sample payloads, in that order. A SoundBank has at least one sample and no +instruments, tracks, events, duration, or song loop. A MusicBank contains exactly +one composition; all references are bank-local. Duration must be positive, loop +start must precede duration, and the compiled loop must span at least one output +frame. Events are sorted by tick; array order breaks equal-time ties. + +## Sample descriptor (40 bytes) + +| Offset | Type | Meaning | +|---:|---|---| +| 0 | u8 | codec: 0 = PCM16_LE, 1 = IMA_ADPCM_WAV4 | +| 1 | u8 | channels: 1 or 2 | +| 2 | u16 | flags: bit 0 means loop bounds present | +| 4 | u32 | source sample rate, positive | +| 8 | u32 | decoded frames per channel | +| 12 | u32 | loop start frame | +| 16 | u32 | exclusive loop end frame | +| 20 | u32 | payload offset | +| 24 | u32 | payload bytes | +| 28 | u16 | IMA block alignment in bytes; zero for PCM | +| 30 | u16 | IMA decoded frames per block; zero for PCM | +| 32 | u8 | default volume (0..255) | +| 33 | u8 | default pan/balance (0..255, center 128) | +| 34 | u16 | reserved | +| 36 | u32 | default rate multiplier, unsigned Q16.16, positive | + +PCM payload size is exactly frames * channels * 2. Loops use decoded frames and +must satisfy start < end <= frames. Without a loop flag both bounds are zero. +Zero-length nonlooped samples are inert. No implicit downmix is performed. + +IMA_ADPCM_WAV4 uses the WAVE IMA four-bit block layout, not RTP DVI4. Each block +starts with a four-byte header per channel: initial PCM i16, step index u8 in +0..88, and reserved zero. The initial PCM frame is emitted. Codes are decoded +low nibble first; stereo alternates four code bytes (eight frames) for left and +four for right. Each channel has independent predictor/index state. Predictor is +saturated to i16 and index to 0..88 after each code. Block alignment is a positive +multiple of 4*channels, at least 8*channels. Frames/block equals +1 + (block_alignment - 4*channels)*2/channels. Every stored block is complete; +only the final block may contain padding beyond the declared decoded frame count. +Its unused codes are zero. The packer defaults to 256 bytes per channel (505 +frames/block); loops need not align to blocks because playback uses decoded PCM. +The codec is lossy and selected explicitly for each sample. Encoder/decoder code +must have documented project-compatible provenance and independent conformance +vectors. Runtime does not parse a WAV/RIFF container. + +## Instrument zone (64 bytes) + +| Offset | Type | Meaning | +|---:|---|---| +| 0 | u16 | instrument ID | +| 2 | u16 | sample index | +| 4 | u8 | lowest note (0..127) | +| 5 | u8 | highest note inclusive | +| 6 | u8 | sample root note | +| 7 | u8 | flags: bit 0 enables looping | +| 8 | i16 | fine tuning in cents | +| 10 | u8 | pan/balance | +| 11 | u8 | gain | +| 12 | u32 | attack duration in microseconds | +| 16 | u32 | decay duration in microseconds | +| 20 | u16 | sustain gain (0..65535) | +| 22 | u16 | reserved | +| 24 | u32 | release duration in microseconds | +| 28 | u32 | vibrato frequency in millihertz | +| 32 | u16 | vibrato depth in cents | +| 34 | u16 | tremolo depth (0..65535) | +| 36 | u32 | tremolo frequency in millihertz | +| 40 | u16 | default delay send (0..65535) | +| 42 | u8 | curve: 0 = all linear, 1 = linear attack/exponential decay/release | +| 43 | bytes[21] | reserved | + +Zones of the same instrument may not overlap. Note-on resolves exactly one zone. +ADSR stages reach exact endpoints within their declared output-frame duration; +zero duration transitions immediately. Sustain is constant. Note-off releases +from the current gain. Exponential segments use the normalized curve +(exp(-6*x)-exp(-6))/(1-exp(-6)), x in [0,1], with exact endpoints; table +interpolation is permitted within 1e-4 absolute gain error. + +## Event (32 bytes) + +The record contains tick:u32, kind:u8, track:u8, flags:u16, a:u32, b:u32, +c:i32, d:i32, duration_frames:u32, curve:u32. Curve is 0 linear or 1 smoothstep. +Durations run on audio time, independently of later musical tempo changes. + +| Kind | Operation | Operands | +|---:|---|---| +| 1 | note-on | a note identity, b instrument, c note, d velocity 0..255; flag 1 legato | +| 2 | note-off | a note identity | +| 3 | tempo | a positive microseconds/quarter; global | +| 4 | track gain ramp | c destination 0..65535 | +| 5 | track pan ramp | c destination 0..255 | +| 6 | track pitch ramp | c bend in cents | +| 7 | vibrato | a millihertz, c depth cents | +| 8 | tremolo | a millihertz, c depth 0..65535 | +| 9 | track delay send ramp | c destination 0..65535 | +| 10 | instrument selection | a instrument ID; note-on b=0xffffffff inherits it | + +Note-on duration_frames is portamento duration when legato is set. Compatible +legato retains cursor/envelope on the most recent active note of that track; +incompatible instrument/zone/sample retriggers. It never creates a hidden voice. +Stealing selects the lowest free local index, oldest release, then oldest note; +Release age starts at note-off; note age starts at note-on. Serialized event +order resolves same-frame ages, with local index as final tie-breaker. +Obsolete note-off cannot affect a reused voice. Authored note identities must +distinguish simultaneously live logical notes of a track. + +Events and tempo segments compile into exact rational frame times using u128 +checked arithmetic and denominator PPQ*1000000. Events execute at the first +integer output frame not earlier than their represented time. Carry fractional +remainder across tempo changes and song loops. At a loop boundary, notes from +the previous iteration enter release and identities are renewed. A frame may +execute at most 64 events per group; validate this bound, including the loop +seam, during loading. Reject zero-time loops and malformed references. + +## Processing, effects, and lifecycle + +Three fixed groups own 12/12/8 voices. A stereo sample consumes one voice. +Mono pan uses equal-power gains; stereo balance preserves L/R at center and +attenuates only the opposite side toward an extreme. Mono normalized pan is +p/256 for p<=128 and 0.5+(p-128)/254 above center; gains are sqrt(1-pan) and +sqrt(pan). Stereo gains are [1,p/128] left of center and [(255-p)/127,1] +right of center. Gain and pitch changes +do not reset a cursor. Sum in floating point and clamp only at final output. + +Each group has a shared low-pass and stereo delay; selective sends contribute +to that group's delay only. Group gain follows dry/wet recombination. Music A/B +feed Music Bus; SFX feeds SFX Bus; bus and master gains are independent. +Each track initially uses each instrument's default send. A track send event +sets an absolute destination: interpolate from each voice's current send to +that destination, including interrupted transitions. New notes resolve their +instrument default through the same transition. SFX send defaults to zero on +new playback and is explicitly set with audio.set_send. + +The filter is a one-pole low-pass: y += a*(x-y), +a=1-exp(-2*pi*cutoff/48000). Cutoff zero bypasses filtering. Delay receives +unfiltered selective sends; feedback is local to the delay. Output is +dry*filtered_input + wet*delayed_input. Changing delay length clears history +in O(1); no per-voice filter or delay is allocated. + +Linear interpolation is used for PCM. Vibrato/tremolo use deterministic LFO +phase on audio time; gain ramps support linear and smoothstep curves. + +Delay storage is prepared for 2000 ms per group at 48 kHz, stereo f32: 2304000 +bytes total, independent of bank size. This is an explicit bounded processing +budget, not a measured battery/ARM guarantee. Feedback must remain strictly +inside (-1,1) after coefficient conversion. Reset invalidates history in O(1), +without clearing all buffer bytes in the callback. Pause freezes group DSP and +musical time. Music unload/replacement clears its group's history; stopping SFX +of one bank allows already mixed shared delay history to finish naturally. + +Resident banks carry invalidation tokens. Installing/unloading a slot invalidates +its old instance; retained commands/voices check that token before generating +more PCM. Failure to prepare a replacement leaves the old instance valid. Asset +commit remains an owner-side frame-boundary operation, independent of audio +consumption. No command may resurrect an invalid bank, including after pause. +Samples, bank owners, command vectors and invalidation tokens are reclaimed by +host service outside the callback; the callback never blocks or destroys a last +owner. Already submitted device buffers are not recalled. + +Retirement uses two preallocated packets. Each has capacity +2*(3*1024+32+2) resource owners plus two command-vector owners. A staged play +retains at most a sample and invalidation token; music owns the whole immutable +bank, so note references can be released while that bank is still retained. +Retire the bank only after releasing its note references. No callback operation +can grow the packet; packet starvation retains inactive owners until service. + +The existing 1024 frame/callback quotas, independent lifecycle slot, FIFO prefix +publication, aborted-frame cancellation, session invalidation and bounded +backpressure remain in force. Musical events do not consume VM frame quota. + +## High-level ABI additions + +All operations require AUDIO, return one status and cost five logical cycles. +Existing audio play/control calls address only SFX local voices 0..7. Music groups +are 0=A and 1=B; DSP groups are 0=A,1=B,2=SFX; buses are 0=Music,1=SFX,2=Master. + +| ID | Operation | Arguments | +|---|---|---| +| 0x3010 | music.play | group, resident bank slot, loop 0/1 | +| 0x3011 | music.stop | group | +| 0x3012 | music.pause | group | +| 0x3013 | music.resume | group | +| 0x3014 | music.set_volume | group, gain 0..255 | +| 0x3015 | music.fade_to | group, gain 0..255, milliseconds, curve 0/1 | +| 0x3016 | music.crossfade | source group, target group, milliseconds, curve 0/1 | +| 0x3020 | audio.set_bus_volume | bus, gain 0..255 | +| 0x3021 | audio.set_effect | group, cutoff Hz (0=bypass), delay ms 0..2000, feedback number, wet number 0..1, dry number 0..1 | +| 0x3022 | audio.set_send | SFX voice, gain 0..255 | +| 0x3023 | audio.unload_bank | type 0=SoundBank/1=MusicBank, slot | +| 0x3024 | audio.set_group_volume | group 0/1/2, gain 0..255 (independent of bus gain) | + +Group/slot/voice errors and nonfinite/out-of-range arguments reject before +admission without consuming quota. No command returns a playback handle or +synchronously waits for the consumer. Crossfade schedules both ramps and stops +the source at completion. If either group is inactive when the consumer applies +the crossfade, it has no effect; admission success is not a consumer acknowledgement. +Fade alone to +zero keeps sequence time advancing. Unload is an independent bounded owner +control, so an exhausted guest audio command quota cannot prevent invalidation. +It returns AudioOpStatus, mapping unavailable owner control to BANK_INVALID. It +is an asset-owner action: a later VM frame fault does not restore an unloaded bank. +Music play/stop/replacement preserve the current group gain and cancel its old +fade, so setting gain before play is effective. DSP configuration belongs to the +group and persists across bank changes; its history follows the reset policy above. +Session/epoch reset restores gains, buses and DSP configuration to defaults. + +## Codec references and diagnostics + +The IMA WAVE block header includes the first uncompressed sample and uses low +nibble first. RTP DVI4 has a different framing/order; the distinction is +documented in [RFC 3551 section 4.5.1](https://www.rfc-editor.org/rfc/rfc3551#section-4.5.1). +The implementation is project-owned code under the project MIT license; no +third-party decoder or additional codec library is linked. PCM WAV source +layout follows [WAVEFORMATEX](https://learn.microsoft.com/en-us/windows/win32/api/mmreg/ns-mmreg-waveformatex). +Only the packer reads WAV containers. + +Owner-side bank diagnostics expose cartridge bytes, canonical decoded bytes, +PCM length/allocation bytes per resident bank, and unique PCM totals across +slots. Accounted metadata/total includes resident structs, strings and vector +capacities, excluding Arc/allocator headers and asset-manager caches; allocator +peak observations are separate actual allocation measurements. Materialization elapsed time includes cooperative yields; pipeline load +latency is separately recorded by bank type. Mixer diagnostics expose active +and maximum voices, frames and render time; the service lane measures retained +PCM separately from resident slots. Retained PCM can overlap resident PCM; those +reference counts must not be summed as additional memory. These are host diagnostics, not new guest +byte-budget quotas. The measurement executable includes allocator peak tracking +for replacement/load observations. Prepared engine memory includes fixed DSP +capacity; transport, retirement packets and bank memory are additional. + +Integer event timing and codec PCM output are deterministic. Floating-point +mixing/DSP replay is tested with identical buffer partitions on a host; bitwise +identity across different CPU/libm implementations is not qualified here. diff --git a/docs/specs/runtime/15-asset-management.md b/docs/specs/runtime/15-asset-management.md index 6d3f5ec..27e0050 100644 --- a/docs/specs/runtime/15-asset-management.md +++ b/docs/specs/runtime/15-asset-management.md @@ -245,35 +245,49 @@ If a scene glyph dependency cannot be resolved: ### 4.3 Decoding validation and physical payload completeness Complete-buffer/reader decoding and resumable decoding MUST use the same driver -format authority for glyph layout, sound metadata and PCM conversion, and scene +format authority for glyph layout, audio bank/sample descriptors and PCM conversion, and scene headers, layers, tile ranges and decoded-size validation. Execution mode MUST NOT change acceptance or semantic bank output for the same declared asset slice. Every byte of the declared slice MUST be physically available. A short file read MUST fail; it must not publish a partial sound or accept a physically complete scene whose byte length is shorter than the declared asset size. This applies -even when the missing sound byte would have been an ignored odd PCM tail. -A physically present final unpaired PCM byte remains accepted and ignored. +including a missing byte in any audio header, descriptor or sample payload. +Audio payloads follow the versioned [audio bank format](05a-audio-bank-format.md); malformed frame counts and unpaired PCM bytes are rejected. The shared worker retains resumable state and reads at most 4096 payload bytes per decode step. Scene header and layer steps read their fixed headers; tile -steps use complete tile records. PCM steps end on sample boundaries except for -the final odd tail. Save work takes priority at the next safe step. Cancellation +steps use complete tile records. Audio preparation separately yields after at +most 4096 PCM bytes, one bounded IMA block, or 64 metadata/clock records. PCM +steps end on complete channel frames. Save work takes priority at the next safe +step. Cancellation and target generation are checked before continuing and before staging a complete bank; frame-boundary publication remains separate from decoding. The conformance corpus checks explicit outputs and refusal outcomes across buffer, reader, legacy load and resumable entry points. It covers empty supported forms, chunk edges, palettes, truncated and trailing data, metadata, declared -sizes, scene ranges and nonfinite parallax. Ignored reserved fields remain -ignored; this validation sharing does not introduce new codecs or payload versions. +sizes, scene ranges and nonfinite parallax. Audio reserved bytes must be zero; +audio codecs and payload versions are defined in the audio bank format. + +### 4.4 Audio banks + +`SOUNDS` uses SBNK and `MUSIC` uses MBNK as defined in +[Audio banks and sequences](05a-audio-bank-format.md). Outer codec is NONE; +individual samples select PCM16_LE or IMA_ADPCM_WAV4. Complete validation and +PCM16 materialization precede commit. Audio `decoded_size` counts canonical +metadata/tables plus decoded PCM; actual allocation overhead is separate telemetry. +A single MusicBank is self-contained and has no external asset dependencies. +Replacement/unload invalidates its previous instance and stops its audio users; +last-owner destruction remains outside the callback. ## 5 Banks and Slots The current runtime exposes bank types: - `GLYPH` -- `SOUNDS` +- `SOUNDS` (16 SoundBank slots) +- `MUSIC` (16 independent MusicBank slots) - `SCENE` Assets are loaded into explicit slots identified by slot index at the public ABI boundary. @@ -305,13 +319,15 @@ BankTelemetry { Rules: - the visible contract MUST NOT expose byte-oriented bank occupancy as the canonical summary; -- canonical bank names are `GLYPH` and `SOUNDS`; +- canonical bank names are `GLYPH`, `SOUNDS`, `MUSIC` and `SCENE`; - detailed occupancy inspection remains host-owned and slot-based through slot references, not bank byte totals; - public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI; - any residual byte accounting MAY exist internally, but it is not part of the visible bank telemetry contract. The rationale for this boundary is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md). +Guest bank selectors use GLYPH=0, SOUNDS=1, SCENE=2, MUSIC=3. + ## 6 Load Lifecycle The runtime asset manager exposes a staged lifecycle: diff --git a/docs/specs/runtime/16-host-abi-and-syscalls.md b/docs/specs/runtime/16-host-abi-and-syscalls.md index 7933803..edbaf65 100644 --- a/docs/specs/runtime/16-host-abi-and-syscalls.md +++ b/docs/specs/runtime/16-host-abi-and-syscalls.md @@ -379,3 +379,7 @@ Native boundaries MUST respect the [Registry typed-value and ownership contract] ## Fn Execution Boundary Typed Fn callbacks execute as ordinary guest calls on the single VM context. Boot remains physical FunctionId 0; preparation requires an empty capture environment and existing argument checks. FRAME_SYNC preserves context for next-PC resumption; successful last-root RET completes entry and leaves rooted results before threshold GC. No native callback registration, retention or reentry API is introduced; raw HeapRef/ValueSnapshot copies do not establish guest roots or authorize cross-session imports. Syscalls remain non-first-class. + +The `audio` and `music` modules both require the AUDIO capability. Their staged +commands, numeric ranges, costs and audio-time semantics are defined in the +[audio peripheral](05-audio-peripheral.md) and [bank/ABI tables](05a-audio-bank-format.md). diff --git a/docs/specs/runtime/README.md b/docs/specs/runtime/README.md index 464acbd..c3cb322 100644 --- a/docs/specs/runtime/README.md +++ b/docs/specs/runtime/README.md @@ -83,6 +83,7 @@ In the current state, no chapter under the active `docs/specs/runtime/` root is | [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) | VM memory model | normative | | [`04-gfx-peripheral.md`](04-gfx-peripheral.md) | virtual hardware: graphics | normative | | [`05-audio-peripheral.md`](05-audio-peripheral.md) | virtual hardware: audio | normative | +| [`05a-audio-bank-format.md`](05a-audio-bank-format.md) | audio banks, codecs, sequencer and ABI | normative | | [`06-input-peripheral.md`](06-input-peripheral.md) | virtual hardware: input | normative | | [`07-touch-peripheral.md`](07-touch-peripheral.md) | virtual hardware: touch | normative | | [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) | virtual hardware: save memory | normative | diff --git a/docs/vm-arch/audio-callback-qualification.md b/docs/vm-arch/audio-callback-qualification.md index c39401a..df1f441 100644 --- a/docs/vm-arch/audio-callback-qualification.md +++ b/docs/vm-arch/audio-callback-qualification.md @@ -1,4 +1,11 @@ -# Desktop audio callback qualification +# Historical desktop audio callback qualification + +These observations and owner counts describe the previous 16-voice engine. +They do not qualify the current 32-voice hardware contract. Current capacity, +ownership and ABI are defined in the [audio bank contract](../specs/runtime/05a-audio-bank-format.md). +The current executable measurement harness is `cargo run --release -p prometeu-drivers --example audio_measure`; +physical/allocator tests live in `audio_callback_allocations.rs`. + The desktop callback moves discarded Sample references and command-vector owners into two preallocated return packets. Host service reclaims them outside the data diff --git a/test-fixtures/audio/ima-only.sbnk b/test-fixtures/audio/ima-only.sbnk new file mode 100644 index 0000000..64f140e Binary files /dev/null and b/test-fixtures/audio/ima-only.sbnk differ diff --git a/test-fixtures/audio/mixed-music.mbnk b/test-fixtures/audio/mixed-music.mbnk new file mode 100644 index 0000000..924f8c0 Binary files /dev/null and b/test-fixtures/audio/mixed-music.mbnk differ diff --git a/test-fixtures/audio/mixed-sound.sbnk b/test-fixtures/audio/mixed-sound.sbnk new file mode 100644 index 0000000..be47155 Binary files /dev/null and b/test-fixtures/audio/mixed-sound.sbnk differ diff --git a/test-fixtures/audio/pcm-only.sbnk b/test-fixtures/audio/pcm-only.sbnk new file mode 100644 index 0000000..707f681 Binary files /dev/null and b/test-fixtures/audio/pcm-only.sbnk differ