feat(audio): add guest voice controls and reliable lifecycle delivery
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-14 09:08:27 +01:00
parent 3899b7f12c
commit e0e01ed1de
23 changed files with 1442 additions and 482 deletions
+280 -168
View File
@@ -13,8 +13,7 @@ use prometeu_hal::sample::Sample;
/// State of a single playback voice (channel).
///
/// The Core maintains this state to provide information to the App (e.g., is_playing),
/// but the actual real-time mixing is performed by the Host using commands.
/// This state belongs exclusively to the mixer, which observes natural completion.
pub struct Channel {
/// The actual sample data being played.
pub sample: Option<Arc<Sample>>,
@@ -30,7 +29,7 @@ pub struct Channel {
pub pan: u8,
/// Loop configuration for this voice.
pub loop_mode: LoopMode,
/// Playback priority (used for voice stealing policies).
/// Internal priority metadata; the guest explicitly selects its voice.
pub priority: u8,
}
@@ -64,7 +63,7 @@ pub enum AudioCommand {
priority: u8,
loop_mode: LoopMode,
},
/// Immediately stop playback on a voice.
/// Stop playback on a voice when this command is applied.
Stop { voice_id: usize },
/// Update volume of an ongoing playback.
SetVolume { voice_id: usize, volume: u8 },
@@ -72,36 +71,65 @@ pub enum AudioCommand {
SetPan { voice_id: usize, pan: u8 },
/// Update pitch of an ongoing playback.
SetPitch { voice_id: usize, pitch: f64 },
/// Pause all audio processing.
MasterPause,
/// Resume audio processing.
MasterResume,
}
/// PROMETEU Audio Subsystem.
///
/// Models a multi-channel PCM sampler (SPU).
/// The audio system in Prometeu is **command-based**. This means the Core
/// doesn't generate raw audio samples; instead, it sends high-level commands
/// (like `Play`, `Stop`, `SetVolume`) to a queue. The physical host backend
/// (e.g., CPAL on desktop) then consumes these commands and performs the
/// actual mixing at the native hardware sample rate.
///
/// ### Key Features:
/// - **16 Simultaneous Voices**: Independent volume, pan, and pitch.
/// - **Sample-based Synthesis**: Plays PCM data stored in SoundBanks.
/// - **Stereo Output**: 48kHz output target.
mod transport;
pub use transport::{AudioDelivery, AudioTransport};
pub const MAX_COMMANDS_PER_FRAME: usize = 1024;
/// Bounded producer staging. Samples belong to staged/published commands and the
/// mixer, never to a second playback mirror that cannot observe completion.
pub struct Audio {
/// Local state of the hardware voices. This state is used for logic
/// (e.g., checking if a sound is still playing) and is synchronized with the Host.
pub voices: [Channel; MAX_CHANNELS],
/// Queue of pending commands to be processed by the Host mixer.
/// This queue is typically flushed and sent to the Host once per frame.
pub commands: Vec<AudioCommand>,
/// Interface to access sound memory banks (ARAM).
commands: Vec<AudioCommand>,
/// Admission survives an early lifecycle flush of the interrupted frame.
frame_commands_admitted: usize,
lifecycle_commands: Vec<AudioCommand>,
in_lifecycle: bool,
session: Option<u32>,
transport: AudioTransport,
pub sound_banks: Arc<dyn SoundBankPoolAccess>,
}
impl Audio {
pub fn new(sound_banks: Arc<dyn SoundBankPoolAccess>) -> Self {
Self {
commands: Vec::new(),
frame_commands_admitted: 0,
lifecycle_commands: Vec::new(),
in_lifecycle: false,
session: None,
transport: AudioTransport::default(),
sound_banks,
}
}
pub fn transport(&self) -> AudioTransport {
self.transport.clone()
}
fn enqueue(&mut self, voice: usize, command: AudioCommand) -> AudioOpStatus {
if voice >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
let admitted = if self.in_lifecycle {
self.lifecycle_commands.len()
} else {
self.frame_commands_admitted
};
if admitted >= MAX_COMMANDS_PER_FRAME {
return AudioOpStatus::CommandLimit;
}
if self.in_lifecycle {
self.lifecycle_commands.push(command);
} else {
self.commands.push(command);
self.frame_commands_admitted += 1;
}
AudioOpStatus::Ok
}
}
impl AudioBridge for Audio {
fn play(
&mut self,
@@ -112,14 +140,23 @@ impl AudioBridge for Audio {
pan: u8,
pitch: f64,
priority: u8,
loop_mode: prometeu_hal::LoopMode,
loop_mode: LoopMode,
) -> AudioOpStatus {
let lm = match loop_mode {
prometeu_hal::LoopMode::Off => LoopMode::Off,
prometeu_hal::LoopMode::On => LoopMode::On,
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
let Some(bank) = self.sound_banks.sound_bank_slot(bank_id as usize) else {
return AudioOpStatus::BankInvalid;
};
self.play(bank_id, sample_id, voice_id, volume, pan, pitch, priority, lm)
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)
}
fn play_sample(
&mut self,
sample: Arc<Sample>,
@@ -128,156 +165,84 @@ impl AudioBridge for Audio {
pan: u8,
pitch: f64,
priority: u8,
loop_mode: prometeu_hal::LoopMode,
) -> AudioOpStatus {
let lm = match loop_mode {
prometeu_hal::LoopMode::Off => LoopMode::Off,
prometeu_hal::LoopMode::On => LoopMode::On,
};
self.play_sample(sample, voice_id, volume, pan, pitch, priority, lm)
}
fn stop(&mut self, voice_id: usize) {
self.stop(voice_id)
}
fn set_volume(&mut self, voice_id: usize, volume: u8) {
self.set_volume(voice_id, volume)
}
fn set_pan(&mut self, voice_id: usize, pan: u8) {
self.set_pan(voice_id, pan)
}
fn set_pitch(&mut self, voice_id: usize, pitch: f64) {
self.set_pitch(voice_id, pitch)
}
fn is_playing(&self, voice_id: usize) -> bool {
self.is_playing(voice_id)
}
fn clear_commands(&mut self) {
self.clear_commands()
}
}
impl Audio {
/// Initializes the audio system with empty voices and sound bank access.
pub fn new(sound_banks: Arc<dyn SoundBankPoolAccess>) -> Self {
Self {
voices: std::array::from_fn(|_| Channel::default()),
commands: Vec::new(),
sound_banks,
}
}
#[allow(clippy::too_many_arguments)]
pub fn play(
&mut self,
bank_id: u8,
sample_id: u16,
voice_id: usize,
volume: u8,
pan: u8,
pitch: f64,
priority: u8,
loop_mode: LoopMode,
) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
// Resolve the sample from the hardware pools
let bank_slot = self.sound_banks.sound_bank_slot(bank_id as usize);
if bank_slot.is_none() {
return AudioOpStatus::BankInvalid;
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
let sample =
bank_slot.and_then(|bank| bank.samples.get(sample_id as usize).map(Arc::clone));
if let Some(s) = sample {
// println!(
// "[Audio] Resolved sample from bank {} sample {}. Playing on voice {}.",
// bank_id, sample_id, voice_id
// );
self.play_sample(s, voice_id, volume, pan, pitch, priority, loop_mode)
} else {
AudioOpStatus::SampleNotFound
}
}
#[allow(clippy::too_many_arguments)]
pub fn play_sample(
&mut self,
sample: Arc<Sample>,
voice_id: usize,
volume: u8,
pan: u8,
pitch: f64,
priority: u8,
loop_mode: LoopMode,
) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
// Update local state
self.voices[voice_id] = Channel {
sample: Some(Arc::clone(&sample)),
active: true,
pos: 0.0,
pitch,
volume,
pan,
loop_mode,
priority,
};
// Push command to the host
self.commands.push(AudioCommand::Play {
sample,
self.enqueue(
voice_id,
volume,
pan,
pitch,
priority,
loop_mode,
});
AudioOpStatus::Ok
AudioCommand::Play { sample, voice_id, volume, pan, pitch, priority, loop_mode },
)
}
pub fn stop(&mut self, voice_id: usize) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].active = false;
self.voices[voice_id].sample = None;
self.commands.push(AudioCommand::Stop { voice_id });
fn stop(&mut self, voice_id: usize) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::Stop { voice_id })
}
fn set_volume(&mut self, voice_id: usize, volume: u8) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::SetVolume { voice_id, volume })
}
fn set_pan(&mut self, voice_id: usize, pan: u8) -> AudioOpStatus {
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 {
return AudioOpStatus::VoiceInvalid;
}
}
pub fn set_volume(&mut self, voice_id: usize, volume: u8) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].volume = volume;
self.commands.push(AudioCommand::SetVolume { voice_id, volume });
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
self.enqueue(voice_id, AudioCommand::SetPitch { voice_id, pitch })
}
pub fn set_pan(&mut self, voice_id: usize, pan: u8) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].pan = pan;
self.commands.push(AudioCommand::SetPan { voice_id, pan });
}
fn ready(&self) -> bool {
self.transport.ready()
}
pub fn set_pitch(&mut self, voice_id: usize, pitch: f64) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].pitch = pitch;
self.commands.push(AudioCommand::SetPitch { voice_id, pitch });
}
fn begin_frame(&mut self) { /* Staging may already contain debugger steps. */
}
pub fn is_playing(&self, voice_id: usize) -> bool {
if voice_id < MAX_CHANNELS { self.voices[voice_id].active } else { false }
fn finish_frame(&mut self) {
self.transport.publish(std::mem::take(&mut self.commands), false);
self.frame_commands_admitted = 0;
}
/// Clears the command queue. The Host should consume this every frame.
pub fn clear_commands(&mut self) {
fn abort_frame(&mut self) {
self.commands.clear();
self.frame_commands_admitted = 0;
}
fn lifecycle_ready(&self) -> bool {
self.transport.lifecycle_ready()
}
fn begin_lifecycle(&mut self) {
self.in_lifecycle = true;
}
fn finish_lifecycle(&mut self, success: bool) {
self.in_lifecycle = false;
if success {
// Publish the earlier frame prefix first so a callback stop cannot
// be undone by an old play on resume. Do not replenish frame quota.
let mut commands = std::mem::take(&mut self.commands);
commands.append(&mut self.lifecycle_commands);
self.transport.publish(commands, true);
} else {
self.lifecycle_commands.clear();
self.abort_frame();
}
}
fn set_session(&mut self, session: Option<u32>) {
if self.session != session {
self.reset();
self.session = session;
}
}
fn reset(&mut self) {
self.abort_frame();
self.lifecycle_commands.clear();
self.in_lifecycle = false;
self.transport.reset();
}
fn set_paused(&mut self, paused: bool) {
self.transport.set_paused(paused);
}
}
@@ -326,7 +291,154 @@ mod tests {
let status = audio.play_sample(sample(), MAX_CHANNELS, 255, 128, 1.0, 0, LoopMode::Off);
assert_eq!(status, AudioOpStatus::VoiceInvalid);
assert!(!audio.voices.iter().any(|voice| voice.active));
assert!(audio.commands.is_empty());
}
}
#[cfg(test)]
mod control_tests {
use super::*;
use crate::MemoryBanks;
fn audio() -> Audio {
Audio::new(Arc::new(MemoryBanks::new()))
}
#[test]
fn quota_is_shared_and_rejections_never_publish_partial_effects() {
let mut audio = audio();
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_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);
let sample = Arc::new(Sample::new(48_000, vec![1]));
assert_eq!(
audio.play_sample(sample.clone(), 0, 255, 0, 1.0, 0, LoopMode::Off),
AudioOpStatus::CommandLimit
);
assert_eq!(Arc::strong_count(&sample), 1);
assert!(audio.transport.try_take().unwrap().frame.is_none());
audio.finish_frame();
assert!(!audio.ready());
assert_eq!(
audio.transport.try_take().unwrap().frame.unwrap().len(),
MAX_COMMANDS_PER_FRAME
);
assert!(audio.ready());
audio.begin_frame();
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
#[test]
fn lifecycle_and_reset_bypass_full_guest_batch_and_release_samples() {
let mut audio = audio();
audio.set_session(Some(1));
let sample = Arc::new(Sample::new(48_000, vec![1]));
let weak = Arc::downgrade(&sample);
assert_eq!(audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On), AudioOpStatus::Ok);
for _ in 1..MAX_COMMANDS_PER_FRAME {
audio.stop(1);
}
audio.finish_frame();
assert!(!audio.ready());
assert!(audio.lifecycle_ready());
audio.begin_lifecycle();
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
audio.finish_lifecycle(true);
audio.set_paused(true);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.paused);
assert_eq!(delivery.frame.as_ref().unwrap().len(), MAX_COMMANDS_PER_FRAME);
assert!(matches!(
delivery.lifecycle.as_ref().unwrap()[0],
AudioCommand::Stop { voice_id: 0 }
));
let old_epoch = delivery.epoch;
drop(delivery);
assert!(weak.upgrade().is_none(), "driver must not retain a playback mirror");
audio.stop(0);
audio.finish_frame();
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
audio.set_session(Some(2));
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.epoch > old_epoch);
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(audio.ready());
}
#[test]
fn lifecycle_publishes_prefix_first_and_aborted_batches_are_cancelled() {
let mut audio = audio();
audio.set_pan(0, 17);
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none());
let lifecycle = delivery.lifecycle.unwrap();
assert!(matches!(lifecycle[0], AudioCommand::SetPan { pan: 17, .. }));
assert!(matches!(lifecycle[1], AudioCommand::Stop { voice_id: 1 }));
audio.set_volume(0, 23);
audio.finish_frame();
let commands = audio.transport.try_take().unwrap().frame.unwrap();
assert_eq!(commands.len(), 1);
assert!(matches!(commands[0], AudioCommand::SetVolume { volume: 23, .. }));
audio.stop(0);
audio.abort_frame();
audio.finish_frame();
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(false);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
}
#[test]
fn prefix_flush_preserves_quota_and_combined_delivery_is_bounded() {
let mut audio = audio();
for _ in 0..MAX_COMMANDS_PER_FRAME {
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
audio.begin_lifecycle();
for _ in 0..MAX_COMMANDS_PER_FRAME {
assert_eq!(audio.stop(1), AudioOpStatus::Ok);
}
assert_eq!(audio.stop(1), AudioOpStatus::CommandLimit);
audio.finish_lifecycle(true);
let delivery = audio.transport.try_take().unwrap().lifecycle.unwrap();
assert_eq!(delivery.len(), 2 * MAX_COMMANDS_PER_FRAME);
assert!(matches!(delivery[0], AudioCommand::Stop { voice_id: 0 }));
assert!(matches!(delivery[MAX_COMMANDS_PER_FRAME], AudioCommand::Stop { voice_id: 1 }));
assert_eq!(audio.stop(0), AudioOpStatus::CommandLimit);
// Resume and another pause must not replenish the interrupted frame quota.
for _ in 0..2 {
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
audio.transport.consume_silently();
assert_eq!(audio.stop(0), AudioOpStatus::CommandLimit);
}
audio.finish_frame();
assert!(audio.transport.try_take().unwrap().frame.is_none());
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
#[test]
fn failed_callback_cancels_unpublished_prefix_and_its_sample_reference() {
let mut audio = audio();
let sample = Arc::new(Sample::new(48_000, vec![1]));
let weak = Arc::downgrade(&sample);
audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On);
audio.begin_lifecycle();
audio.stop(0);
audio.finish_lifecycle(false);
audio.finish_frame();
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(weak.upgrade().is_none());
}
}
@@ -0,0 +1,86 @@
use super::AudioCommand;
use std::sync::{Arc, Mutex};
/// One pending frame plus an independent lifecycle lane. Control state never
/// competes with guest commands for capacity. The lifecycle batch can include
/// an interrupted frame prefix (at most 1024 + 1024 commands). Only one consumer
/// may drain it.
#[derive(Clone, Default)]
pub struct AudioTransport(Arc<Mutex<Mailbox>>);
#[derive(Default)]
struct Mailbox {
epoch: u64,
paused: bool,
frame: Option<Vec<AudioCommand>>,
lifecycle: Option<Vec<AudioCommand>>,
}
pub struct AudioDelivery {
pub epoch: u64,
pub paused: bool,
pub frame: Option<Vec<AudioCommand>>,
pub lifecycle: Option<Vec<AudioCommand>>,
}
impl AudioTransport {
/// The real-time consumer never waits for the producer's short critical section.
pub fn try_take(&self) -> Option<AudioDelivery> {
let mut state = self.0.try_lock().ok()?;
Some(AudioDelivery {
epoch: state.epoch,
paused: state.paused,
frame: state.frame.take(),
lifecycle: state.lifecycle.take(),
})
}
pub fn consume_silently(&self) {
let _ = self.try_take();
}
pub fn ready(&self) -> bool {
let state = self.0.lock().expect("audio mailbox");
state.frame.is_none() && state.lifecycle.is_none()
}
pub fn lifecycle_ready(&self) -> bool {
self.0.lock().expect("audio mailbox").lifecycle.is_none()
}
pub(super) fn publish(&self, commands: Vec<AudioCommand>, lifecycle: bool) {
if commands.is_empty() {
return;
}
let mut state = self.0.lock().expect("audio mailbox");
let target = if lifecycle { &mut state.lifecycle } else { &mut state.frame };
assert!(target.is_none(), "audio producer must respect backpressure");
*target = Some(commands);
}
pub(super) fn reset(&self) {
let mut state = self.0.lock().expect("audio mailbox");
state.epoch = state.epoch.checked_add(1).expect("audio epoch exhausted");
state.frame = None;
state.lifecycle = None;
state.paused = false;
}
pub(super) fn set_paused(&self, paused: bool) {
self.0.lock().expect("audio mailbox").paused = paused;
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn realtime_consumer_does_not_wait_for_publication_lock() {
let transport = AudioTransport::default();
let guard = transport.0.lock().unwrap();
assert!(transport.try_take().is_none());
drop(guard);
assert!(transport.try_take().is_some());
}
}
+4 -1
View File
@@ -11,7 +11,10 @@ mod touch;
mod wall_clock;
pub use crate::asset::AssetManager;
pub use crate::audio::{Audio, AudioCommand, Channel, MAX_CHANNELS, OUTPUT_SAMPLE_RATE};
pub use crate::audio::{
Audio, AudioCommand, AudioDelivery, AudioTransport, Channel, MAX_CHANNELS,
MAX_COMMANDS_PER_FRAME, OUTPUT_SAMPLE_RATE,
};
pub use crate::frame_composer::{ComposerBuffer, FrameComposer, SceneStatus, SpriteController};
pub use crate::gfx::Gfx;
pub use crate::local_render_backend::LocalFramebufferRenderBackend;
@@ -112,7 +112,7 @@ mod tests {
Game2DFramePacket::default(),
))
.expect("test platform render sink should accept local submission");
assert!(!platform.audio().is_playing(0));
assert!(platform.audio().ready());
assert!(!platform.input().pad().any());
assert!(platform.telemetry().telemetry_snapshot().is_none());
}