diff --git a/crates/host/prometeu-host-desktop-winit/src/audio.rs b/crates/host/prometeu-host-desktop-winit/src/audio.rs index c883af9..aa30633 100644 --- a/crates/host/prometeu-host-desktop-winit/src/audio.rs +++ b/crates/host/prometeu-host-desktop-winit/src/audio.rs @@ -426,8 +426,8 @@ impl AudioMixer { voice.sample = None; continue; } - let (loop_start, end) = match (sample.loop_start, sample.loop_end) { - (Some(start), Some(end)) if start < end && end as usize <= len => { + 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), @@ -512,6 +512,168 @@ mod control_tests { ); } + #[test] + fn one_shot_ignores_markers_and_loop_preserves_intro() { + for looping in [false, true] { + let (mut audio, mut mixer) = pair(); + let sample = + Sample::new(48_000, vec![1024, 2048, 4096, 8192, 12288, 16384, 20480, 24576]) + .with_loop(2, 4); + play(&mut audio, Arc::new(sample), 1.0, looping); + audio.finish_frame(); + apply(&audio, &mut mixer); + let mut pcm = [0.0; 20]; + mixer.fill_buffer(&mut pcm); + let expected = if looping { + [1024, 2048, 4096, 8192, 4096, 8192, 4096, 8192, 4096, 8192] + } else { + [1024, 2048, 4096, 8192, 12288, 16384, 20480, 24576, 0, 0] + }; + 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); + } + } + + #[test] + fn absent_partial_and_invalid_markers_fall_back_to_full_sample() { + for (start, end) in [ + (None, None), + (Some(1), None), + (None, Some(2)), + (Some(2), Some(2)), + (Some(3), Some(1)), + (Some(0), Some(5)), + (Some(u32::MAX), Some(u32::MAX)), + (Some(0), Some(0)), + ] { + for looping in [false, true] { + let (mut audio, mut mixer) = pair(); + let mut sample = Sample::new(48_000, vec![4096, 8192, 12288, 16384]); + sample.loop_start = start; + sample.loop_end = end; + play(&mut audio, Arc::new(sample), 1.0, looping); + audio.finish_frame(); + apply(&audio, &mut mixer); + let mut pcm = [0.0; 16]; + mixer.fill_buffer(&mut pcm); + for (i, frame) in pcm.as_chunks::<2>().0.iter().enumerate() { + 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); + } + } + } + + #[test] + fn fractional_interpolation_uses_loop_seam_or_actual_tail() { + // Both rate conversion and fractional pitch produce a half-frame step. + for (rate, pitch) in [(48_000, 0.5), (24_000, 1.0), (96_000, 0.25)] { + for looping in [false, true] { + let (mut audio, mut mixer) = pair(); + play( + &mut audio, + Arc::new(Sample::new(rate, vec![4096, 8192, 16384, 24576]).with_loop(1, 3)), + pitch, + looping, + ); + audio.finish_frame(); + apply(&audio, &mut mixer); + let mut pcm = [0.0; 18]; + mixer.fill_buffer(&mut pcm); + let expected = if looping { + [0.125, 0.1875, 0.25, 0.375, 0.5, 0.375, 0.25, 0.375, 0.5] + } else { + [0.125, 0.1875, 0.25, 0.375, 0.5, 0.625, 0.75, 0.375, 0.0] + }; + for (frame, value) in pcm.as_chunks::<2>().0.iter().zip(expected) { + assert!((frame[0] - value).abs() <= 1e-6); + assert_eq!(frame[1], 0.0); + } + assert_eq!(mixer.voices[0].active, looping); + } + } + } + + #[test] + fn empty_samples_terminate_without_indexing() { + for looping in [false, true] { + for marked in [false, true] { + let (mut audio, mut mixer) = pair(); + let sample = Sample::new(48_000, vec![]); + let sample = if marked { sample.with_loop(0, 1) } else { sample }; + play(&mut audio, Arc::new(sample), f64::MAX, looping); + audio.finish_frame(); + apply(&audio, &mut mixer); + 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()); + } + } + } + + #[test] + fn multiple_wrap_pitch_preserves_selected_interval_and_signal() { + for (rate, pitch) in [(48_000, 5.0), (96_000, 2.5)] { + let (mut audio, mut mixer) = pair(); + play( + &mut audio, + Arc::new(Sample::new(rate, vec![4096, 8192, 16384, 24576]).with_loop(1, 3)), + pitch, + true, + ); + audio.finish_frame(); + apply(&audio, &mut mixer); + 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); + } + } + + #[test] + fn extreme_pitch_and_source_rates_keep_positions_finite() { + for rate in [0, 1, 44_100, 48_000, 96_000, u32::MAX] { + for looping in [false, true] { + let (mut audio, mut mixer) = pair(); + play( + &mut audio, + Arc::new(Sample::new(rate, vec![4096, 8192, 16384, 24576]).with_loop(1, 3)), + f64::MAX, + looping, + ); + audio.finish_frame(); + apply(&audio, &mut mixer); + 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()); + if rate == 0 { + assert_eq!(mixer.voices[0].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!( + pcm.as_chunks::<2>() + .0 + .iter() + .skip(1) + .all(|frame| (0.25..=0.5).contains(&frame[0])) + ); + } else { + 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); + } + } + } + #[test] fn pcm_controls_preserve_position_and_stop_is_idempotent() { let (mut audio, mut mixer) = pair(); @@ -632,7 +794,7 @@ mod control_tests { let mut pcm = [0.0; 128]; mixer.fill_buffer(&mut pcm); assert!(pcm.iter().all(|v| v.is_finite())); - assert!(pcm.chunks_exact(2).all(|frame| frame == [0.5, 0.0])); + 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); } diff --git a/discussion/lessons/DSC-0055-guest-audio-voice-control/LSN-0069-audio-admission-needs-a-delivery-boundary-and-independent-lifecycle-control.md b/discussion/lessons/DSC-0055-guest-audio-voice-control/LSN-0069-audio-admission-needs-a-delivery-boundary-and-independent-lifecycle-control.md index dcf109e..7410c36 100644 --- a/discussion/lessons/DSC-0055-guest-audio-voice-control/LSN-0069-audio-admission-needs-a-delivery-boundary-and-independent-lifecycle-control.md +++ b/discussion/lessons/DSC-0055-guest-audio-voice-control/LSN-0069-audio-admission-needs-a-delivery-boundary-and-independent-lifecycle-control.md @@ -46,6 +46,18 @@ The mixer also reduces large pitch steps before multiplication when wrapping loo ## Evidence and Limits +### Sample Metadata Does Not Select Playback Mode + +Loop markers describe an optional interval within a sample; the playback command decides whether to use it. Applying a loop end to one-shot playback silently discards the tail, even though the data remains available. The mixer now selects the full sample boundary when looping is off. When looping is on, a complete interval satisfying `start < end <= length` preserves the intro and wraps at the selected end; absent, partial or invalid markers fall back to the full sample. Empty samples terminate before indexing. + +Interpolation follows the same selected boundary. A one-shot interpolates into the actual tail and finally toward zero, while a loop seam interpolates toward the loop-start frame. Distinct intro, loop and tail values make these behaviors observable: an eight-frame sample with markers `(2, 4)` emits all eight frames once with looping off, and emits frame indices `0, 1, 2, 3, 2, 3, 2, 3` with looping on. Constant PCM alone cannot detect this defect. + +The correction derives from DEC-0060 in DSC-0064. Synthetic regressions cover exact PCM, fractional seams and tails, incomplete and invalid markers, empty samples, rate conversion, multiple wraps and extreme finite pitch. These tests exercise the existing delivery and control paths without establishing new device timing or reclamation guarantees. The [sample contract](../../../docs/specs/runtime/05-audio-peripheral.md#6-samples-interpolation-and-ownership) remains normative. + +Local macOS/aarch64 qualification on 2026-10-14 passed 19 host audio tests (one physical-device test ignored), nine driver audio tests and ten runtime audio tests. The existing `make ci-domains` target passed with 1,027 tests passed, zero failed and 11 ignored, including all 15 domain gates. Strict all-target/all-feature Clippy passed for the desktop host. Strict workspace qualification remains pending because of existing VM lint errors; this correction does not claim to resolve the repository-wide quality gate. + +### Original Voice-Control Qualification + Validation was run locally on macOS/aarch64 on 2026-10-14: - `cargo test --workspace --all-targets --all-features --no-fail-fast`: **1,016 passed**, zero failed, eleven ignored across 55 reported suites. diff --git a/docs/specs/runtime/05-audio-peripheral.md b/docs/specs/runtime/05-audio-peripheral.md index b3f2507..92b1275 100644 --- a/docs/specs/runtime/05-audio-peripheral.md +++ b/docs/specs/runtime/05-audio-peripheral.md @@ -84,7 +84,9 @@ Reset, termination, crash or cartridge replacement ends the audio session, stops ## 6 Samples, interpolation and ownership -Samples are immutable PCM16 mono, with a source sample rate and optional loop bounds. Linear interpolation uses fractional playback position. Playback rate combines source/output sample-rate ratio and pitch. Looping uses the sample's valid loop interval, or the full sample when no valid interval is present. Loop steps may cross multiple repetitions; finite positive pitch must not accidentally terminate a short loop or produce an infinite position. +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. + +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 can remain retained until the command is cancelled or the playback ends, stops, is replaced, or its session ends. The driver must not retain a second sample reference indefinitely after the mixer observes natural completion.