Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 175 additions & 25 deletions rs/moq-audio/src/playback/device.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ use crate::Error;
/// second choice.
const RATES: &[u32] = &[48_000, 44_100];

/// Channel counts to try, best first. The mixer produces stereo, and mono is
/// the only other count worth naming: anything else is a surround layout we
/// would be guessing the speaker order of.
const CHANNELS: &[u16] = &[2, 1];

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add regression coverage for stereo-first negotiation

Add a regression test with otherwise-equivalent mono and stereo ranges where mono is enumerated first, and assert that negotiation selects stereo. No existing test exercises negotiate, so this fix can regress back to enumeration-order selection unnoticed; the repository explicitly requires every bug fix to include a test encoding its root cause.

AGENTS.md reference: AGENTS.md:L146-L152

Useful? React with 👍 / 👎.


/// Sample formats we can write, best first: `f32` is what the mixer produces,
/// and the rest are conversions on the way out.
///
Expand Down Expand Up @@ -86,37 +91,72 @@ pub(super) fn open(selector: Option<&str>) -> Result<cpal::Device, Error> {

/// Pick the stream format to open `device` with.
///
/// Only considers formats in [`FORMATS`], then prefers a rate the pipeline
/// already runs at, then falls back to the highest the device supports, since
/// resampling down is kinder than resampling up.
/// Only considers formats in [`FORMATS`], and prefers in that order: a channel
/// count in [`CHANNELS`], a rate the pipeline already runs at, then a format we
/// write without converting. Failing all of those it takes the highest rate the
/// device supports, since resampling down is kinder than resampling up.
pub(super) fn negotiate(device: &cpal::Device) -> Result<cpal::SupportedStreamConfig, Error> {
let supported: Vec<_> = device
let supported = device
.supported_output_configs()
.map_err(|err| Error::Playback(format!("cannot enumerate output configs: {err}")))?
.filter(|config| FORMATS.contains(&config.sample_format()))
.collect();

for &rate in RATES {
for &format in FORMATS {
let config = supported
.iter()
.filter(|c| c.sample_format() == format)
.find_map(|c| (*c).try_with_sample_rate(rate));

if let Some(config) = config {
return Ok(config);
}
}
}
.map_err(|err| Error::Playback(format!("cannot enumerate output configs: {err}")))?;

choose(supported).ok_or_else(|| Error::Unsupported("output device offers no sample format we can write".into()))
}

// Rate first, format as the tie-break, so an exotic device still opens.
/// Pick the best of the stream configurations a device reports.
///
/// Split out from [`negotiate`] so it can be tested without a device: the
/// preference order is three levels deep and the outermost exists to fix an
/// audible bug.
fn choose(supported: impl Iterator<Item = cpal::SupportedStreamConfigRange>) -> Option<cpal::SupportedStreamConfig> {
supported
.into_iter()
.max_by_key(|c| (c.max_sample_rate(), std::cmp::Reverse(rank(c.sample_format()))))
.map(|c| c.with_max_sample_rate())
.ok_or_else(|| Error::Unsupported("output device offers no sample format we can write".into()))
.filter(|config| FORMATS.contains(&config.sample_format()))
.min_by_key(preference)
.map(|config| match preferred_rate(&config) {
Some(rate) => config.try_with_sample_rate(rate).expect("a rate the range covers"),
None => config.with_max_sample_rate(),
})
}

/// Rank a configuration against the ones this crate would rather have, lowest
/// first.
///
/// One key rather than nested loops because the levels are not independent: a
/// stereo device offering only 96 kHz has to beat a mono one offering 48 kHz,
/// and a pass per channel count that gave up when neither preferred rate matched
/// would hand that to the mono device and downmix. The channel count leads
/// because a downmix is audible where a resample is not.
fn preference(config: &cpal::SupportedStreamConfigRange) -> (usize, usize, std::cmp::Reverse<u32>, usize) {
let channels = CHANNELS
.iter()
.position(|count| *count == config.channels())
.unwrap_or(CHANNELS.len());
let rate = match preferred_rate(config) {
Some(rate) => (RATES.iter().position(|r| *r == rate).expect("from RATES"), rate),
// Nothing we asked for, so take the most the device offers: resampling
// down is kinder than resampling up.
None => (RATES.len(), config.max_sample_rate()),
};
(
channels,
rate.0,
std::cmp::Reverse(rate.1),
rank(config.sample_format()),
)
}

/// The first rate in [`RATES`] this configuration covers, if any.
fn preferred_rate(config: &cpal::SupportedStreamConfigRange) -> Option<u32> {
RATES
.iter()
.copied()
.find(|rate| config.min_sample_rate() <= *rate && *rate <= config.max_sample_rate())
}

/// Where `format` sits in [`FORMATS`], so a lower rank is a better format.
///
/// Unlisted formats sort last, which is what makes this usable as a tie-break
/// against a device offering something we filtered out.
fn rank(format: cpal::SampleFormat) -> usize {
FORMATS.iter().position(|f| *f == format).unwrap_or(FORMATS.len())
}
Expand All @@ -129,3 +169,113 @@ fn describe(device: &cpal::Device, id: &cpal::DeviceId) -> String {
.map(|d| d.name().to_string())
.unwrap_or_else(|_| id.id().to_string())
}

#[cfg(test)]
mod tests {
use cpal::{SampleFormat, SupportedBufferSize, SupportedStreamConfigRange};

use super::*;

fn range(channels: u16, rate: u32, format: SampleFormat) -> SupportedStreamConfigRange {
SupportedStreamConfigRange::new(channels, rate, rate, SupportedBufferSize::Unknown, format)
}

/// The bug this ordering exists for: an ALSA plugin node that lists mono
/// first would otherwise be opened in mono, downmixing a stereo broadcast on
/// the way to a stereo sink.
#[test]
fn stereo_wins_even_when_the_device_lists_mono_first() {
let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 48_000, SampleFormat::F32)].into_iter())
.expect("a config");
assert_eq!(chosen.channels(), 2);
}

/// Preferring stereo must not refuse a device that has no stereo to offer.
#[test]
fn mono_is_taken_when_that_is_all_there_is() {
let chosen = choose([range(1, 48_000, SampleFormat::F32)].into_iter()).expect("a config");
assert_eq!(chosen.channels(), 1);
}

/// Neither preferred count is offered, so the pass that accepts any count
/// has to catch it. Without it a surround-only sink would not open at all.
#[test]
fn a_count_we_do_not_prefer_still_opens() {
let chosen = choose([range(6, 48_000, SampleFormat::F32)].into_iter()).expect("a config");
assert_eq!(chosen.channels(), 6);
}

/// Rate is preferred within a channel count, not across one: a stereo config
/// at an awkward rate beats a mono config at the pipeline's own rate,
/// because resampling is inaudible and a downmix is not.
#[test]
fn channels_outrank_the_sample_rate() {
let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 44_100, SampleFormat::F32)].into_iter())
.expect("a config");
assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 44_100));
}

/// Within a channel count and rate, take the format the mixer already
/// produces rather than one that costs a conversion.
#[test]
fn f32_is_preferred_over_a_format_we_convert_to() {
let chosen = choose([range(2, 48_000, SampleFormat::I16), range(2, 48_000, SampleFormat::F32)].into_iter())
.expect("a config");
assert_eq!(chosen.sample_format(), SampleFormat::F32);
}

/// A device offering only formats we cannot write is an error rather than a
/// stream that plays noise.
#[test]
fn a_device_we_cannot_write_to_is_rejected() {
assert!(choose([range(2, 48_000, SampleFormat::I8)].into_iter()).is_none());
assert!(choose(std::iter::empty()).is_none());
}

/// Channels lead even when neither preferred rate is on offer.
///
/// The case two review bots found in the first version of this, which gave
/// up on a channel count as soon as no preferred rate matched it: a device
/// with stereo only at 96 kHz and mono at 48 kHz went to mono, which is the
/// downmix the whole preference exists to avoid.
#[test]
fn stereo_at_an_awkward_rate_beats_mono_at_a_preferred_one() {
let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 96_000, SampleFormat::F32)].into_iter())
.expect("a config");
assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 96_000));
}

/// The same with neither count on a preferred rate, so the ordering rests on
/// the channel rank alone rather than on one side matching a rate.
#[test]
fn stereo_beats_mono_when_neither_is_on_a_preferred_rate() {
let chosen = choose(
[
range(1, 192_000, SampleFormat::F32),
range(2, 96_000, SampleFormat::F32),
]
.into_iter(),
)
.expect("a config");
assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 96_000));
}

/// Nothing in the preferred lists matches, so the last resort picks the
/// highest rate and breaks the tie on format.
#[test]
fn the_last_resort_takes_the_highest_rate() {
let chosen = choose(
[
range(2, 96_000, SampleFormat::I16),
range(2, 96_000, SampleFormat::F32),
range(2, 32_000, SampleFormat::F32),
]
.into_iter(),
)
.expect("a config");
assert_eq!(
(chosen.sample_rate(), chosen.sample_format()),
(96_000, SampleFormat::F32)
);
}
}
Loading