feat(audio): add 32-voice PCM mixing and native music sequencing

Add self-contained SoundBanks and MusicBanks with per-sample PCM16 and IMA ADPCM storage, materialized to resident PCM16. Integrate instrument envelopes, automation, shared DSP and host lifecycle controls while preserving staged real-time execution.
This commit is contained in:
2026-11-20 22:15:24 +00:00
parent a32f834b2b
commit 8510c5b00d
40 changed files with 4708 additions and 509 deletions
@@ -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();
@@ -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<Arc<Sample>>,
pub batches: [Option<Vec<AudioCommand>>; 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<Arc<Sample>>) {
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<Arc<HeapRb<Packet>>>;
type Cons = CachingCons<Arc<HeapRb<Packet>>>;
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<Packet> {
@@ -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);
}
@@ -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<prometeu_hal::music_bank::MusicBank> {
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);
}
+139 -2
View File
@@ -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<prometeu_drivers::engine::AudioMixer>,
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<Option<CrashReport>, 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);
}
}