fader_master/core/src/group.rs

114 lines
3.9 KiB
Rust

//! Pure plans over current observations; creating a plan never confirms a write.
use crate::{ChannelGainError, ChannelGains, Gain, StreamHandle};
use std::collections::BTreeMap;
/// Application group gain semantics.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum VolumeMode {
/// Sync group: each stream reaches the requested scalar gain.
#[default]
Absolute,
/// Reserved VCA-style group backed by [`RelativeGroupState`].
Relative,
}
/// Prepared state for a future VCA-style relative group.
///
/// Each member's last independently controlled or externally observed channel
/// vector is its maximum. A normalized group position scales every member from
/// silence to that remembered maximum. Group-generated confirmations must not
/// be passed to [`Self::observe_independent`], because moving the group does not
/// redefine a member's maximum.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct RelativeGroupState {
maxima: BTreeMap<StreamHandle, ChannelGains>,
}
impl RelativeGroupState {
/// Creates an empty relative group state.
#[must_use]
pub const fn new() -> Self {
Self {
maxima: BTreeMap::new(),
}
}
/// Records a member's latest independent fader or external position.
pub fn observe_independent(&mut self, stream: StreamHandle, channels: ChannelGains) {
self.maxima.insert(stream, channels);
}
/// Forgets a member that is no longer resolved by this group.
pub fn remove(&mut self, stream: StreamHandle) {
self.maxima.remove(&stream);
}
/// Plans member gains at a normalized group position in `0..=1`.
///
/// The stored maxima are not mutated, so lowering and raising the group is
/// reversible until an independent member edit explicitly rebases one.
pub fn plan(
&self,
position: Gain,
ceiling: Gain,
) -> Result<BTreeMap<StreamHandle, ChannelGains>, ChannelGainError> {
if position > Gain::UNITY {
return Err(ChannelGainError::AboveWriteCeiling {
target: position.get(),
ceiling: Gain::UNITY.get(),
});
}
self.maxima
.iter()
.map(|(handle, maximum)| {
let desired =
Gain::new((maximum.maximum().get() * position.get()).min(ceiling.get()))?;
Ok((*handle, maximum.scaled_to(desired, ceiling)?))
})
.collect()
}
}
/// Aggregate gain view; absence of this value means no stream is observable.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct VolumeView {
/// Maximum channel gain across all resolved streams.
pub maximum: Gain,
/// Whether stream maxima disagree.
pub mixed: bool,
}
/// Aggregates stream maxima without manufacturing a zero for offline targets.
pub fn volume_view(live: &BTreeMap<StreamHandle, ChannelGains>) -> Option<VolumeView> {
let mut maxima = live.values().map(ChannelGains::maximum);
let first = maxima.next()?;
let mut view = VolumeView {
maximum: first,
mixed: false,
};
for maximum in maxima {
view.mixed |= maximum != first;
if maximum > view.maximum {
view.maximum = maximum;
}
}
Some(view)
}
/// Computes one bounded channel-vector command per resolved stream.
///
/// This is the active sync/absolute group planner. Every member reaches the
/// target while retaining its channel balance. Requests above the configured
/// ceiling are clipped; no observation is modified. Successful and failed
/// writes must later be reconciled separately.
pub fn plan_volume(
live: &BTreeMap<StreamHandle, ChannelGains>,
target: Gain,
ceiling: Gain,
) -> Result<BTreeMap<StreamHandle, ChannelGains>, ChannelGainError> {
let bounded = Gain::new(target.get().min(ceiling.get()))?;
live.iter()
.map(|(handle, channels)| Ok((*handle, channels.scaled_to(bounded, ceiling)?)))
.collect()
}