diff --git a/quest/m2/README.md b/quest/m2/README.md index 1ae9ab6e886..7b79537706a 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -204,7 +204,6 @@ quests that require them. - [Small API fixes before the cut](/quest/m2/api-shape/README.md) - one path and one spelling per item, names by role, and no dead or wrong-role public surface across net, transport, media, native, apps, JS, and bindings - [Public constructors spawn nothing, or say why](/quest/m2/spawn-constructors.md) - each public library entry point that spawns returns a driver its caller polls, or is listed as kept - [moq-audio codecs return zero or more outputs](/quest/m2/audio-codec-seam.md) - `encode` and `decode` return any number of outputs and gain `flush`, as moq-video's do -- [A mix-minus removes several sources](/quest/m2/bus-minus-several.md) - a guest's return feed drops every copy of their own sound - [Plan: recovery boundaries](/quest/m2/intra-refresh-boundary.md) - the catalog's new `warmup` contract is settled before the cut publishes it - [MoQ on rind](/quest/m1/rind/README.md) - every MoQ crate takes its crypto from rind, a pure-Rust graviola fork, so no build compiles C crypto (held in m1 by an open claim) - [Finishing a producer returns a Finished handle](/quest/m2/finished-handle.md) - `finish(self)` consumes moq-net's and the media crates' producers, so appending after finish doesn't compile diff --git a/quest/m2/bus-minus-several.md b/quest/m2/bus-minus-several.md deleted file mode 100644 index 46d3fc5c16a..00000000000 --- a/quest/m2/bus-minus-several.md +++ /dev/null @@ -1,15 +0,0 @@ -# [S] A mix-minus removes several sources - -## Goal - -A `bus` mix-minus takes out any number of sources, so a guest's return feed -can drop every copy of that guest's own sound. - -## Plan - -Decided 2026-11-05 (maintainer, on moq-dev/studio's /quest-plan): m3, since the studio is a named consumer that is not urgent. Moved to m2: Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests). `moq_audio::bus` is new since `release`, so changing `minus` after the cut would cost another moq-audio major. - -`Mix::minus` (`rs/moq-audio/src/bus.rs`) takes one `Strip`. A studio guest -with a camera and a screen share has two sources of their own sound, so their -return feed echoes one of them ([moq-dev/studio#37](https://github.com/moq-dev/studio/pull/37)). Change `minus` -itself rather than adding a second method. diff --git a/rs/moq-audio/CHANGELOG.md b/rs/moq-audio/CHANGELOG.md index 188f7e9c5d0..1898d084d1a 100644 --- a/rs/moq-audio/CHANGELOG.md +++ b/rs/moq-audio/CHANGELOG.md @@ -23,8 +23,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Breaking:** the bus routes sources into several mixes. `Bus::new` returns the bus and the one `Driver` that advances it on the caller's clock; each mix has its own meter and independent readers whose blocks carry their clock - position, and a mix-minus drops one source. A strip carries a per-source sync - delay. See `MIGRATE.md`. + position, and a mix-minus drops any set of its sources. A strip carries a + per-source sync delay. See `MIGRATE.md`. - **Breaking:** open one `capture::Producer` and pass its independent consumers to the bus and encoder. Samples, timestamps, source gaps, and terminal failures are shared; slow readers lose only their own expired buffers. See `MIGRATE.md`. diff --git a/rs/moq-audio/benches/bus.rs b/rs/moq-audio/benches/bus.rs index 8de0272f26b..10574599f02 100644 --- a/rs/moq-audio/benches/bus.rs +++ b/rs/moq-audio/benches/bus.rs @@ -6,8 +6,9 @@ //! source into every mix; `sparse` routes one source into each, which should //! cost little more than the sources alone. //! - `bus_minus`: a program of every source plus a mix-minus per source, the -//! per-guest return feed, which should grow with the source count rather -//! than its square. +//! per-guest return feed, swept over the source count and how many sources +//! each minus removes. It should grow with the source count rather than its +//! square, and with the removed count only once a minus removes most sources. //! //! Run with `cargo bench -p moq-audio --bench bus`. @@ -100,18 +101,23 @@ fn bench_minus(c: &mut Criterion) { let mut group = c.benchmark_group("bus_minus"); group.throughput(Throughput::Elements(BLOCK as u64)); - for count in [1usize, 4, 16, 64] { - let (bus, mut driver, mut sources, block) = sources(count, 48_000); - let program = bus.mix(); - for (_, strip) in &sources { - program.route(strip); - } - let minuses: Vec<_> = sources.iter().map(|(_, strip)| program.minus(strip)).collect(); + for removed in [1usize, 4, 16] { + for count in [16usize, 64] { + let (bus, mut driver, mut sources, block) = sources(count, 48_000); + let program = bus.mix(); + for (_, strip) in &sources { + program.route(strip); + } + // Each guest's minus removes itself and the next `removed - 1` sources. + let minuses: Vec<_> = (0..count) + .map(|guest| program.minus((0..removed).map(|offset| &sources[(guest + offset) % count].1))) + .collect(); - group.bench_function(BenchmarkId::from_parameter(count), |b| { - b.iter(|| run(&mut driver, &mut sources, &block)); - }); - drop(minuses); + group.bench_function(BenchmarkId::new(format!("remove{removed}"), count), |b| { + b.iter(|| run(&mut driver, &mut sources, &block)); + }); + drop(minuses); + } } group.finish(); } diff --git a/rs/moq-audio/src/bus.rs b/rs/moq-audio/src/bus.rs index a804e8079a5..2649640bd7b 100644 --- a/rs/moq-audio/src/bus.rs +++ b/rs/moq-audio/src/bus.rs @@ -3,7 +3,7 @@ //! A [`Bus`] holds sources, each a [`Live`] or [`Positioned`] channel fed with //! PCM and controlled by a [`Strip`] of gain, mute, pan, sync delay, and level //! meter, and [`Mix`]es, each the sum of the sources routed into it. A -//! [`Minus`] is a mix-minus: one mix with one of its sources taken out, for a +//! [`Minus`] is a mix-minus: one mix with some of its sources taken out, for a //! guest's return feed. Every mix //! publishes interleaved `f32` at the bus's [`Config`] to any number of //! independent [`Reader`]s. @@ -239,7 +239,8 @@ struct Routed { struct MinusState { id: u64, parent: usize, - excluded: Strip, + /// Deduplicated, so each is subtracted at most once. + excluded: Vec, output: Output, } @@ -513,7 +514,8 @@ impl Driver { /// Call it as the clock advances, with exactly that much time's worth of /// frames: the bus has no clock of its own, so this is what paces every /// source. A source with nothing buffered contributes silence. Each mix - /// costs only the sources routed into it, and a mix-minus one more. + /// costs only the sources routed into it, and a mix-minus one more per + /// source it removes. pub fn advance(&mut self, frames: usize) { if frames == 0 { return; @@ -556,12 +558,14 @@ impl Driver { let buffer = &mut minus.output.buffer; buffer.clear(); buffer.extend_from_slice(&parent.output.buffer); - let excluded = key(&minus.excluded); - if parent.routed.contains(&excluded) - && let Some(source) = sources.get(&excluded) - { - for (out, sample) in buffer.iter_mut().zip(&source.block) { - *out -= *sample; + for strip in &minus.excluded { + let excluded = key(strip); + if parent.routed.contains(&excluded) + && let Some(source) = sources.get(&excluded) + { + for (out, sample) in buffer.iter_mut().zip(&source.block) { + *out -= *sample; + } } } minus.output.publish(*position, channels, self.retention); @@ -775,12 +779,20 @@ impl Mix { routes } - /// A mix-minus: this mix without `strip`'s source, for that source's own - /// return feed. + /// A mix-minus: this mix without the sources of `strips`, such as every + /// source carrying one guest's sound, for that guest's return feed. /// - /// It follows this mix's routing, and costs one subtraction per block - /// rather than a second sum. Keeps this mix alive while it lives. - pub fn minus(&self, strip: &Strip) -> Minus { + /// It follows this mix's routing, and costs one subtraction per removed + /// source per block rather than a second sum. A strip listed twice is + /// removed once. Keeps this mix alive while it lives. + pub fn minus<'a>(&self, strips: impl IntoIterator) -> Minus { + // Collected before locking the mixer, since the caller's iterator may lock it. + let mut seen = HashSet::new(); + let excluded: Vec = strips + .into_iter() + .filter(|strip| seen.insert(key(strip))) + .cloned() + .collect(); let (id, history, level) = match self.shared.bus.upgrade() { Some(bus) => { let id = bus.next.fetch_add(1, Ordering::Relaxed); @@ -789,7 +801,7 @@ impl Mix { mixer.minuses.push(MinusState { id, parent: self.shared.slot, - excluded: strip.clone(), + excluded, output, }); (id, history, level) @@ -830,7 +842,7 @@ impl Mix { } } -/// A mix-minus, built by [`Mix::minus`]: a mix without one of its sources. +/// A mix-minus, built by [`Mix::minus`]: a mix without some of its sources. /// /// Cheap to clone. It ends when its last handle drops. #[derive(Clone)] @@ -1426,50 +1438,48 @@ mod tests { assert!(all_near(&last[1], 0.125)); } - /// A mix-minus is its parent without one source, and follows the parent's - /// routing as it changes. + /// A mix-minus is its parent without each of its sources, and follows the + /// parent's routing as it changes. #[test] - fn a_mix_minus_drops_one_source() { + fn a_mix_minus_drops_its_sources() { let (bus, mut driver) = Bus::new(Config::default()).unwrap(); let (mut host, host_strip) = source(&bus); - let (mut guest, guest_strip) = source(&bus); + let (mut camera, camera_strip) = source(&bus); + let (mut screen, screen_strip) = source(&bus); let (mut music, music_strip) = source(&bus); let program = bus.mix(); - for strip in [&host_strip, &guest_strip, &music_strip] { + for strip in [&host_strip, &camera_strip, &screen_strip, &music_strip] { program.route(strip); } - let guest_return = program.minus(&guest_strip); + // Listing a strip twice removes it once, and the strips may come from an + // iterator that reads the bus. + let guest_return = program.minus( + [&camera_strip, &screen_strip, &camera_strip] + .into_iter() + .filter(|strip| program.routes(strip)), + ); let mut minus_reader = guest_return.reader(); let mut program_reader = program.reader(); - let mut sources = [(&mut host, 0.25), (&mut guest, 0.125), (&mut music, 0.0625)]; - let last = feed( - &mut driver, - &mut sources, - &mut [&mut program_reader, &mut minus_reader], - 20, - ); - assert!(all_near(&last[0], 0.4375)); + let mut sources = [ + (&mut host, 0.25), + (&mut camera, 0.125), + (&mut screen, 0.03125), + (&mut music, 0.0625), + ]; + let mut readers = [&mut program_reader, &mut minus_reader]; + let last = feed(&mut driver, &mut sources, &mut readers, 20); + assert!(all_near(&last[0], 0.46875)); assert!(all_near(&last[1], 0.3125)); program.unroute(&music_strip); - let last = feed( - &mut driver, - &mut sources, - &mut [&mut program_reader, &mut minus_reader], - 5, - ); + let last = feed(&mut driver, &mut sources, &mut readers, 5); assert!(all_near(&last[1], 0.25)); - // Excluding a source the parent does not route leaves the parent as is. - program.unroute(&guest_strip); - let last = feed( - &mut driver, - &mut sources, - &mut [&mut program_reader, &mut minus_reader], - 5, - ); - assert!(all_near(&last[0], 0.25)); + // Excluding a source the parent does not route leaves the rest removed. + program.unroute(&camera_strip); + let last = feed(&mut driver, &mut sources, &mut readers, 5); + assert!(all_near(&last[0], 0.28125)); assert!(all_near(&last[1], 0.25)); // The mix-minus keeps its parent mixed after the parent's handle drops. @@ -1713,7 +1723,7 @@ mod tests { ready(&mut bus.mix().reader()).is_none(), "a mix made after the driver ends at once" ); - assert!(ready(&mut kept.minus(&Strip::default()).reader()).is_none()); + assert!(ready(&mut kept.minus([&Strip::default()]).reader()).is_none()); } /// The bus runs on whatever clock its caller owns. Paced by `kio::clock` on