music21_rs/

volume.rs

//! How loud a note is: music21's `volume.Volume`.
//!
//! A volume is one number held two ways — a MIDI velocity from 0 to 127 and
//! the same value as a scalar from 0 to 1 — plus the rule for reading it
//! against the dynamic marks around it. A volume does not know the note it
//! belongs to, so [`Volume::realized_with`] takes the dynamic scalar and the
//! articulation shift as arguments; the marks themselves are found in a
//! stream by [`dynamic_context`], [`dynamics_in_force`] and
//! [`realize_volume`].

use std::cmp::Ordering;
use std::fmt;

use crate::{
    defaults::{FloatType, IntegerType},
    dynamics::{Dynamic, dynamic_str_from_decimal as dynamic_name},
    error::{Error, Result},
    stream::{Stream, StreamElement, StreamKind},
};

/// The velocity music21 assumes when none was set, as a scalar. It is the
/// `0.5` base level shifted by `0.20866`, which is what makes an unset note
/// sound at a natural mezzo-forte rather than at half volume.
const UNSET_VELOCITY_SHIFT: FloatType = 0.20866;

/// The middle of the dynamic range that scalars move away from.
const BASE_LEVEL: FloatType = 0.5;

/// How loud a note is: music21's `volume.Volume`.
#[derive(Clone, Debug, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[must_use]
pub struct Volume {
    velocity_scalar: Option<FloatType>,
    velocity_is_relative: bool,
}

impl Default for Volume {
    /// A volume with no velocity set, which reads as music21's default
    /// loudness rather than as silence.
    fn default() -> Self {
        Self {
            velocity_scalar: None,
            velocity_is_relative: true,
        }
    }
}

impl Volume {
    /// A volume with no velocity of its own.
    pub fn new() -> Self {
        Self::default()
    }

    /// Takes everything another volume says, the velocity and whether it is
    /// relative: music21's `mergeAttributes`.
    pub fn merge_attributes(&mut self, other: &Volume) {
        self.velocity_scalar = other.velocity_scalar;
        self.velocity_is_relative = other.velocity_is_relative;
    }

    /// A volume at a MIDI velocity, `0` to `127`, clamped to that range.
    pub fn from_velocity(velocity: IntegerType) -> Self {
        let mut volume = Self::new();
        volume.set_velocity(Some(velocity));
        volume
    }

    /// A volume at a scalar between `0` and `1`, clamped to that range.
    pub fn from_velocity_scalar(scalar: FloatType) -> Result<Self> {
        let mut volume = Self::new();
        volume.set_velocity_scalar(Some(scalar))?;
        Ok(volume)
    }

    /// The MIDI velocity, `0` to `127`, or `None` when none was set.
    pub fn velocity(&self) -> Option<IntegerType> {
        let scalar = self.velocity_scalar?;
        let velocity = (scalar * 127.0).clamp(0.0, 127.0);
        Some(velocity.round_ties_even() as IntegerType)
    }

    /// Sets the MIDI velocity, clamped to `0` through `127`, or clears it.
    pub fn set_velocity(&mut self, velocity: Option<IntegerType>) {
        self.velocity_scalar = velocity.map(|velocity| {
            if velocity <= 0 {
                0.0
            } else if velocity >= 127 {
                1.0
            } else {
                FloatType::from(velocity) / 127.0
            }
        });
    }

    /// The velocity as a scalar between `0` and `1`, or `None` when none was
    /// set.
    pub fn velocity_scalar(&self) -> Option<FloatType> {
        self.velocity_scalar
    }

    /// Sets the velocity from a scalar, clamped to `0` through `1`, or
    /// clears it. A value that is not a number is an error, as in music21.
    pub fn set_velocity_scalar(&mut self, scalar: Option<FloatType>) -> Result<()> {
        match scalar {
            None => self.velocity_scalar = None,
            Some(scalar) if scalar.is_nan() => {
                return Err(Error::Volume(
                    "value provided for velocityScalar must be a number, not NaN".to_string(),
                ));
            }
            Some(scalar) => self.velocity_scalar = Some(scalar.clamp(0.0, 1.0)),
        }
        Ok(())
    }

    /// Whether the velocity shifts the dynamics around it (music21's
    /// default) or fixes the loudness on its own, as a velocity read from a
    /// MIDI file does.
    pub fn velocity_is_relative(&self) -> bool {
        self.velocity_is_relative
    }

    /// Sets whether the velocity is relative to its context.
    pub fn set_velocity_is_relative(&mut self, relative: bool) {
        self.velocity_is_relative = relative;
    }

    /// Whether a velocity was ever set: music21's `hasVolumeInformation` on
    /// the note that owns it.
    pub fn has_velocity_information(&self) -> bool {
        self.velocity_scalar.is_some()
    }

    /// The loudness this volume comes to on its own, between `0` and `1`:
    /// music21's `realized` with no dynamic or articulation context.
    pub fn realized(&self) -> FloatType {
        self.realized_with(None, 0.0, BASE_LEVEL, true)
    }

    /// The loudness this volume comes to against the dynamic in force and
    /// whatever the articulations add: music21's `getRealized`, with the
    /// context search it would do through a stream replaced by its answers.
    ///
    /// A relative velocity doubles the scalar range, so `0.5` leaves the base
    /// level alone and `0.7` raises it; an absolute one decides the answer by
    /// itself. The dynamic scales; an articulation *shifts*, which is why an
    /// accent on a note nobody has marked lifts it rather than doubling it.
    /// `clip` holds the result inside `0` to `1`.
    pub fn realized_with(
        &self,
        dynamic_scalar: Option<FloatType>,
        articulation_shift: FloatType,
        base_level: FloatType,
        clip: bool,
    ) -> FloatType {
        self.realize(true, dynamic_scalar, articulation_shift, base_level, clip)
    }

    /// [`Volume::realized_with`] leaving this volume's velocity out: music21's
    /// `getRealized(useVelocity=False)`. The base level stands in for the
    /// velocity, with no shift for its being unset, and the dynamic and the
    /// articulations then act on it as they would.
    pub fn realized_without_velocity(
        &self,
        dynamic_scalar: Option<FloatType>,
        articulation_shift: FloatType,
        base_level: FloatType,
        clip: bool,
    ) -> FloatType {
        self.realize(false, dynamic_scalar, articulation_shift, base_level, clip)
    }

    fn realize(
        &self,
        use_velocity: bool,
        dynamic_scalar: Option<FloatType>,
        articulation_shift: FloatType,
        base_level: FloatType,
        clip: bool,
    ) -> FloatType {
        let mut value = base_level;
        if use_velocity {
            match self.velocity_scalar {
                Some(scalar) if !self.velocity_is_relative => value = scalar,
                Some(scalar) => value *= scalar * 2.0,
                None => value += UNSET_VELOCITY_SHIFT,
            }
        }
        if self.velocity_is_relative {
            if let Some(dynamic_scalar) = dynamic_scalar {
                value *= dynamic_scalar * 2.0;
            }
            value += articulation_shift;
        }
        if clip {
            value = value.clamp(0.0, 1.0);
        }
        value
    }

    /// The realized loudness as one of music21's dynamic marks, `ppp`
    /// through `fff`: `dynamics.dynamicStrFromDecimal` of the realized value.
    pub fn realized_dynamic(&self) -> &'static str {
        dynamic_name(self.realized())
    }

    /// The realized loudness written out to two places, which is what
    /// music21's `getRealizedStr` and `cachedRealizedStr` answer.
    pub fn realized_str(&self) -> String {
        rounded_str(self.realized())
    }
}

/// A loudness written out the way Python writes `str(round(value, 2))`: to
/// two places, with the trailing zeros dropped but never the point.
pub fn rounded_str(value: FloatType) -> String {
    let rounded = (value * 100.0).round() / 100.0;
    let written = format!("{rounded}");
    if written.contains('.') {
        written
    } else {
        format!("{written}.0")
    }
}

/// Where [`realize_volume`] looks for the dynamic a note sounds under:
/// music21's `useDynamicContext`, which is `True`, `False` or a `Dynamic`.
#[derive(Clone, Debug, Default, PartialEq)]
pub enum DynamicContext {
    /// The dynamics in the stream, each in force until the next. A note
    /// before the first of them sounds under none.
    #[default]
    FromStream,
    /// No dynamic at all.
    Ignored,
    /// One dynamic for everything, whatever the stream holds.
    Fixed(Dynamic),
}

/// Sets how loud every note and chord of a stream sounds, from the dynamics
/// in force: music21's `realizeVolume` with `setAbsoluteVelocity`.
///
/// Each note's volume is realized against the dynamic it stands under and
/// the answer is written back as its velocity, no longer relative, so that a
/// stream played from its velocities alone sounds as marked. Without
/// `use_velocity` a note's own velocity is left out of the realizing and the
/// dynamic alone decides.
///
/// music21 without `setAbsoluteVelocity` only fills each volume's cache of
/// its realized value. There is no such cache here, so this is always the
/// call that writes. The crate carries no articulations, so none shifts a
/// note; [`Volume::realized_with`] takes that shift as an argument for a
/// caller that has them.
///
/// ```
/// use music21_rs::{volume::{realize_volume, DynamicContext}, Dynamic, Note, Stream};
///
/// let mut stream = Stream::new();
/// stream.insert(0.0, Dynamic::new("pp"));
/// stream.insert(0.0, Note::from_name("G3")?);
/// stream.insert(1.0, Dynamic::new("ff"));
/// stream.insert(1.0, Note::from_name("G3")?);
/// realize_volume(&mut stream, &DynamicContext::FromStream, true);
/// let velocities: Vec<_> = stream
///     .notes()
///     .iter()
///     .map(|(_, note)| match note {
///         music21_rs::StreamElement::Note(note) => note.volume().velocity(),
///         _ => None,
///     })
///     .collect();
/// assert_eq!(velocities, [Some(45), Some(127)]);
/// # Ok::<(), music21_rs::Error>(())
/// ```
pub fn realize_volume(stream: &mut Stream, context: &DynamicContext, use_velocity: bool) {
    let in_force: Vec<Option<FloatType>> = match context {
        DynamicContext::Ignored => vec![None; stream.leaves().len()],
        DynamicContext::Fixed(dynamic) => {
            vec![Some(dynamic.volume_scalar()); stream.leaves().len()]
        }
        DynamicContext::FromStream => {
            let leaves = stream.leaves();
            dynamics_in_force(stream)
                .into_iter()
                .map(|found| match found.map(|position| leaves[position].1) {
                    Some(StreamElement::Dynamic(dynamic)) => Some(dynamic.volume_scalar()),
                    _ => None,
                })
                .collect()
        }
    };

    let realized = |volume: &Volume, dynamic: Option<FloatType>| -> Volume {
        let value = if use_velocity {
            volume.realized_with(dynamic, 0.0, BASE_LEVEL, true)
        } else {
            volume.realized_without_velocity(dynamic, 0.0, BASE_LEVEL, true)
        };
        let mut absolute = volume.clone();
        absolute.set_velocity_is_relative(false);
        absolute
            .set_velocity_scalar(Some(value))
            .expect("a clipped loudness is within the range a velocity takes");
        absolute
    };
    let mut position = 0;
    stream.for_each_mut(&mut |_, element| {
        let dynamic = in_force[position];
        position += 1;
        match element {
            StreamElement::Note(note) => {
                let volume = realized(&note.volume(), dynamic);
                note.set_volume(Some(volume));
            }
            StreamElement::Chord(chord) => {
                let volume = realized(&chord.volume(), dynamic);
                chord.set_volume(Some(volume));
            }
            _ => {}
        }
    });
}

/// The dynamic each element of a stream stands under: for every element
/// [`Stream::leaves`] lists, the position in that list of the dynamic in
/// force where it stands, or `None` where no dynamic is.
///
/// A dynamic is in force from where it stands until the next, the last until
/// the end of the stream, which is music21's `extendDuration`; a note before
/// the first dynamic stands under none, and of two dynamics at one offset the
/// later-listed is the one in force. This is the search [`realize_volume`]
/// realizes against, for a caller that keeps something of its own beside
/// each element.
///
/// ```
/// use music21_rs::{volume::dynamics_in_force, Dynamic, Note, Stream};
///
/// let mut stream = Stream::new();
/// stream.insert(0.0, Note::from_name("G3")?);
/// stream.insert(1.0, Dynamic::new("ff"));
/// stream.insert(1.0, Note::from_name("G3")?);
/// assert_eq!(dynamics_in_force(&stream), [None, Some(1), Some(1)]);
/// # Ok::<(), music21_rs::Error>(())
/// ```
pub fn dynamics_in_force(stream: &Stream) -> Vec<Option<usize>> {
    let leaves = stream.leaves();
    // The leaves in the order music21's `flatten` gives them.
    let order = Stream::flatten_order(&leaves);
    let dynamics: Vec<(Held, usize)> = order
        .iter()
        .filter(|position| matches!(leaves[**position].1, StreamElement::Dynamic(_)))
        .map(|position| (Held::of(leaves[*position].0), *position))
        .collect();
    // `extendDuration`: each dynamic lasts until the next, the last until
    // the end, each span snapped as `opFrac` snaps it. music21 then adds a
    // span to a start, and where either is a float that sum is a float, so
    // a span can end a hair past where the next one starts.
    let total = Held::of(stream.end_offset());
    let mut spans: Vec<((Held, Held), usize)> = Vec::new();
    for (index, &(start, position)) in dynamics.iter().enumerate() {
        let next = dynamics.get(index + 1).map_or(total, |(next, _)| *next);
        let key = (start, start.add(next.span_from(start)));
        // Two dynamics with one span: the later is the one kept.
        match spans
            .iter_mut()
            .find(|(held, _)| held.0.same(key.0) && held.1.same(key.1))
        {
            Some(held) => held.1 = position,
            None => spans.push((key, position)),
        }
    }
    spans.sort_by(|left, right| {
        left.0
            .0
            .compare(right.0.0)
            .then(left.0.1.compare(right.0.1))
    });

    let mut answers: Vec<Option<usize>> = vec![None; leaves.len()];
    let mut last = 0;
    for &position in &order {
        let at = Held::of(leaves[position].0);
        let found = spans[last.min(spans.len())..]
            .iter()
            .position(|((start, end), _)| {
                end.compare(at) == Ordering::Greater && at.compare(*start) != Ordering::Less
            })
            .map(|index| index + last);
        if crate::makenotation::is_not_rest(leaves[position].1)
            && let Some(index) = found
        {
            last = index;
        }
        answers[position] = found.map(|index| spans[index].1);
    }
    answers
}

/// An offset as music21 holds one once `opFrac` has had it: a float where it
/// is a binary fraction, and the exact fraction otherwise.
#[derive(Clone, Copy, Debug)]
enum Held {
    Float(FloatType),
    Exact(i128, i128),
}

impl Held {
    fn of(value: FloatType) -> Self {
        let snapped = crate::makenotation::op_frac(value);
        match crate::duration::limited_fraction(snapped, 65535) {
            Some((numerator, denominator)) if !is_power_of_two(denominator) => {
                Self::Exact(numerator, denominator)
            }
            _ => Self::Float(snapped),
        }
    }

    fn float(self) -> FloatType {
        match self {
            Self::Float(value) => value,
            Self::Exact(numerator, denominator) => {
                numerator as FloatType / denominator as FloatType
            }
        }
    }

    /// Python's `+`: exact for two fractions, a float otherwise.
    fn add(self, other: Self) -> Self {
        match (self, other) {
            (Self::Exact(a, b), Self::Exact(c, d)) => reduced(a * d + c * b, b * d),
            _ => Self::Float(self.float() + other.float()),
        }
    }

    /// `opFrac(self - start)`: the distance snapped to a float where it is a
    /// binary fraction.
    fn span_from(self, start: Self) -> Self {
        match (self, start) {
            (Self::Exact(a, b), Self::Exact(c, d)) => match reduced(a * d - c * b, b * d) {
                Self::Exact(numerator, denominator)
                    if is_power_of_two(denominator) || denominator > 65535 =>
                {
                    Self::of(numerator as FloatType / denominator as FloatType)
                }
                exact => exact,
            },
            _ => Self::of(self.float() - start.float()),
        }
    }

    /// The two compared exactly, as Python compares a float with a fraction.
    fn compare(self, other: Self) -> Ordering {
        let (a, b) = self.ratio();
        let (c, d) = other.ratio();
        match (a.checked_mul(d), c.checked_mul(b)) {
            (Some(left), Some(right)) => left.cmp(&right),
            _ => self.float().total_cmp(&other.float()),
        }
    }

    fn same(self, other: Self) -> bool {
        self.compare(other) == Ordering::Equal
    }

    /// The exact value as a fraction, a float being a binary one.
    fn ratio(self) -> (i128, i128) {
        match self {
            Self::Exact(numerator, denominator) => (numerator, denominator),
            Self::Float(value) => {
                let mut exact = value;
                let mut denominator: i128 = 1;
                while exact.fract() != 0.0 && denominator < (1 << 70) {
                    exact *= 2.0;
                    denominator *= 2;
                }
                (exact as i128, denominator)
            }
        }
    }
}

fn reduced(numerator: i128, denominator: i128) -> Held {
    let (mut a, mut b) = (numerator.abs(), denominator.abs());
    while b != 0 {
        (a, b) = (b, a % b);
    }
    let divisor = a.max(1);
    Held::Exact(numerator / divisor, denominator / divisor)
}

fn is_power_of_two(value: i128) -> bool {
    value > 0 && value & (value - 1) == 0
}

/// The dynamic a note's volume is read against: music21's
/// `getDynamicContext`, which asks the note for the nearest dynamic at or
/// before it.
///
/// `position` is the note's place in [`Stream::leaves`], and the answer is
/// the dynamic's place there, or `None` where no dynamic comes before it.
/// The search starts in the stream holding the note and works outwards, as
/// music21's `getContextByClass` does: a measure, a voice or a plain stream
/// is searched first among its own elements and then through the streams it
/// holds, a part only through them, and a score or an opus only among its
/// own elements -- so a dynamic in another part is never the one, while a
/// dynamic nearer the note in its own voice wins over a later one in
/// another voice. A dynamic at the note's own offset is before it.
///
/// ```
/// use music21_rs::{volume::dynamic_context, Dynamic, Note, Stream, StreamKind};
///
/// let mut measure = Stream::with_kind(StreamKind::Measure);
/// measure.insert(0.0, Dynamic::new("ff"));
/// measure.insert(0.0, Note::from_name("C4")?);
/// measure.insert(1.0, Note::from_name("D4")?);
/// assert_eq!(dynamic_context(&measure, 2), Some(0));
/// assert_eq!(dynamic_context(&Stream::new(), 0), None);
/// # Ok::<(), music21_rs::Error>(())
/// ```
pub fn dynamic_context(stream: &Stream, position: usize) -> Option<usize> {
    // The streams holding the note, outermost first: each with the offset it
    // starts at and the position of its first leaf.
    let mut chain: Vec<(&Stream, FloatType, usize)> = Vec::new();
    let at = holders_of(stream, 0.0, 0, position, &mut chain)?;
    for &(site, start, first) in chain.iter().rev() {
        let at = at - start;
        let own_first = !matches!(site.kind(), StreamKind::Part | StreamKind::PartStaff);
        let then_inside = !matches!(site.kind(), StreamKind::Score | StreamKind::Opus);
        if own_first && let Some(found) = last_dynamic(site, first, at, false) {
            return Some(found);
        }
        if then_inside && let Some(found) = last_dynamic(site, first, at, true) {
            return Some(found);
        }
    }
    None
}

/// Walks down to the leaf at `position`, pushing every stream on the way,
/// and answers the leaf's offset; `None` where there is no such leaf.
fn holders_of<'a>(
    stream: &'a Stream,
    start: FloatType,
    first: usize,
    position: usize,
    chain: &mut Vec<(&'a Stream, FloatType, usize)>,
) -> Option<FloatType> {
    chain.push((stream, start, first));
    let mut next = first;
    for event in stream.events() {
        let offset = start + event.offset();
        match event.element() {
            StreamElement::Stream(inner) => {
                let count = inner.leaves().len();
                if position < next + count {
                    return holders_of(inner, offset, next, position, chain);
                }
                next += count;
            }
            _ => {
                if next == position {
                    return Some(offset);
                }
                next += 1;
            }
        }
    }
    None
}

/// The last dynamic at or before `at` among a stream's own elements, or
/// among everything it holds where `inside`, as its place among the leaves.
fn last_dynamic(stream: &Stream, first: usize, at: FloatType, inside: bool) -> Option<usize> {
    let mut found: Option<(FloatType, usize)> = None;
    let mut consider = |offset: FloatType, position: usize| {
        if offset <= at + 1e-9 && found.is_none_or(|(best, _)| offset >= best) {
            found = Some((offset, position));
        }
    };
    if inside {
        for (position, (offset, element)) in stream.leaves().into_iter().enumerate() {
            if matches!(element, StreamElement::Dynamic(_)) {
                consider(offset, first + position);
            }
        }
    } else {
        let mut next = first;
        for event in stream.events() {
            match event.element() {
                StreamElement::Stream(inner) => next += inner.leaves().len(),
                StreamElement::Dynamic(_) => {
                    consider(event.offset(), next);
                    next += 1;
                }
                _ => next += 1,
            }
        }
    }
    found.map(|(_, position)| position)
}

impl fmt::Display for Volume {
    /// music21's `repr` body, `realized=0.71`.
    ///
    /// music21 writes `round(self.realized, 2)` into an f-string, so Python's
    /// float formatting drops a trailing zero the way `{:.2}` does not: half
    /// velocity reads `realized=0.5`, not `realized=0.50`.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut rounded = format!("{:.2}", self.realized());
        while rounded.ends_with('0') && !rounded.ends_with(".0") {
            rounded.pop();
        }
        write!(f, "realized={rounded}")
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn merging_takes_the_other_volumes_velocity() {
        let mut loud = Volume::from_velocity(111);
        loud.set_velocity_is_relative(false);
        let mut volume = Volume::new();
        volume.merge_attributes(&loud);
        assert_eq!(volume.velocity(), Some(111));
        assert!(!volume.velocity_is_relative());
    }

    #[test]
    fn velocity_and_scalar_are_the_same_number() {
        let mut volume = Volume::new();
        assert_eq!(volume.velocity(), None);
        assert_eq!(volume.velocity_scalar(), None);
        assert!(!volume.has_velocity_information());

        volume.set_velocity(Some(64));
        assert_eq!(volume.velocity(), Some(64));
        assert!(volume.has_velocity_information());
        assert!((volume.velocity_scalar().unwrap() - 64.0 / 127.0).abs() < 1e-12);

        volume.set_velocity(Some(200));
        assert_eq!(volume.velocity(), Some(127));
        volume.set_velocity(Some(-5));
        assert_eq!(volume.velocity(), Some(0));
        volume.set_velocity(None);
        assert_eq!(volume.velocity(), None);
    }

    #[test]
    fn scalars_clamp_and_round_trip() {
        let volume = Volume::from_velocity_scalar(0.5).unwrap();
        assert_eq!(volume.velocity(), Some(64));
        assert_eq!(
            Volume::from_velocity_scalar(2.0).unwrap().velocity_scalar(),
            Some(1.0)
        );
        assert_eq!(
            Volume::from_velocity_scalar(-1.0)
                .unwrap()
                .velocity_scalar(),
            Some(0.0)
        );
        assert!(Volume::from_velocity_scalar(FloatType::NAN).is_err());
        assert_eq!(Volume::from_velocity(127).velocity_scalar(), Some(1.0));
    }

    #[test]
    fn realized_matches_music21() {
        // An unset velocity realizes at the shifted base level, which is
        // music21's default loudness for a note nobody has marked.
        let unset = Volume::new();
        assert!((unset.realized() - 0.70866).abs() < 1e-9);
        assert_eq!(unset.realized_dynamic(), "f");
        assert_eq!(unset.realized_str(), "0.71");

        // A relative velocity doubles its scalar against the base level, so
        // half velocity leaves the base level where it is.
        let half = Volume::from_velocity_scalar(0.5).unwrap();
        assert!((half.realized() - 0.5).abs() < 1e-9);
        assert_eq!(half.realized_dynamic(), "mf");
        assert_eq!(half.realized_str(), "0.5");

        // An absolute velocity decides the answer by itself.
        let mut absolute = Volume::from_velocity_scalar(0.5).unwrap();
        absolute.set_velocity_is_relative(false);
        assert!((absolute.realized() - 0.5).abs() < 1e-9);
        let mut loud = Volume::from_velocity_scalar(1.0).unwrap();
        loud.set_velocity_is_relative(false);
        assert!((loud.realized() - 1.0).abs() < 1e-9);

        // Relative velocities scale with the dynamic around them, and clip.
        assert!((half.realized_with(Some(0.5), 0.0, 0.5, true) - 0.5).abs() < 1e-9);
        assert!((half.realized_with(Some(1.0), 0.0, 0.5, true) - 1.0).abs() < 1e-9);
        assert!((half.realized_with(Some(1.0), 0.0, 0.5, false) - 1.0).abs() < 1e-9);
        assert!(loud.realized_with(Some(1.0), 0.0, 0.5, false) > 0.99);

        // An articulation shifts rather than scales, so an accent on a note
        // nobody has marked lifts it a little.
        let unmarked = Volume::new();
        assert!((unmarked.realized_with(None, 0.1, 0.5, true) - 0.80866).abs() < 1e-9);
        // Read off music21: a note nobody has marked, realized under pp and
        // ff with its velocity left out, is the base level scaled and no more.
        assert!(
            (unmarked.realized_without_velocity(Some(0.25), 0.0, 0.5, true) - 0.25).abs() < 1e-9
        );
        assert!(
            (unmarked.realized_without_velocity(Some(0.85), 0.0, 0.5, true) - 0.85).abs() < 1e-9
        );
    }

    #[test]
    fn realized_names_cover_the_dynamic_range() {
        assert_eq!(dynamic_name(0.0), "n");
        assert_eq!(dynamic_name(0.05), "pppp");
        assert_eq!(dynamic_name(0.12), "ppp");
        assert_eq!(dynamic_name(0.2), "pp");
        assert_eq!(dynamic_name(0.3), "p");
        assert_eq!(dynamic_name(0.4), "mp");
        assert_eq!(dynamic_name(0.6), "mf");
        assert_eq!(dynamic_name(0.7), "f");
        assert_eq!(dynamic_name(0.85), "ff");
        assert_eq!(dynamic_name(1.0), "fff");
        assert_eq!(Volume::from_velocity(64).to_string(), "realized=0.5");
        assert_eq!(Volume::new().to_string(), "realized=0.71");
        let mut silent = Volume::new();
        silent.set_velocity(Some(0));
        silent.set_velocity_is_relative(false);
        assert_eq!(silent.to_string(), "realized=0.0");
    }

    /// Every number here is music21's: the first run is its own
    /// `testRealizeVolumeA`, the rest were read off it.
    #[test]
    fn a_stream_is_realized_against_the_dynamics_in_force() {
        use crate::{Note, Stream, StreamElement};

        let velocities = |stream: &Stream| -> Vec<Option<IntegerType>> {
            stream
                .notes()
                .iter()
                .map(|(_, element)| match element {
                    StreamElement::Note(note) => note.volume().velocity(),
                    _ => None,
                })
                .collect()
        };
        let notes = |count: usize| {
            let mut stream = Stream::new();
            for _ in 0..count {
                stream.push(Note::from_name("G3").unwrap());
            }
            stream
        };

        let mut stream = notes(16);
        for (index, mark) in ["pp", "p", "mp", "f", "mf", "ff", "ppp", "mf"]
            .into_iter()
            .enumerate()
        {
            stream.insert(index as FloatType * 2.0, Dynamic::new(mark));
        }
        realize_volume(&mut stream, &DynamicContext::FromStream, true);
        assert_eq!(
            velocities(&stream),
            [
                45, 45, 63, 63, 81, 81, 126, 126, 99, 99, 127, 127, 27, 27, 99, 99
            ]
            .map(Some)
        );

        // A note before the first dynamic sounds under none, a velocity of
        // its own scales the answer, and an absolute one decides it.
        let mut stream = notes(4);
        stream.insert(1.0, Dynamic::new("p"));
        stream.insert(3.0, Dynamic::new("ff"));
        let mut position = 0;
        stream.for_each_mut(&mut |_, element| {
            if let StreamElement::Note(note) = element {
                let mut volume = note.volume();
                match position {
                    2 => volume.set_velocity(Some(100)),
                    3 => {
                        volume.set_velocity(Some(64));
                        volume.set_velocity_is_relative(false);
                    }
                    _ => {}
                }
                note.set_volume(Some(volume));
                position += 1;
            }
        });
        realize_volume(&mut stream, &DynamicContext::FromStream, true);
        assert_eq!(velocities(&stream), [90, 63, 70, 64].map(Some));

        let mut stream = notes(2);
        stream.insert(0.0, Dynamic::new("p"));
        stream.for_each_mut(&mut |offset, element| {
            if let (true, StreamElement::Note(note)) = (offset == 1.0, element) {
                note.set_volume(Some(Volume::from_velocity(100)));
            }
        });
        realize_volume(&mut stream, &DynamicContext::FromStream, false);
        assert_eq!(velocities(&stream), [44, 44].map(Some));

        let mut stream = notes(2);
        stream.insert(0.0, Dynamic::new("p"));
        realize_volume(
            &mut stream,
            &DynamicContext::Fixed(Dynamic::new("sfz")),
            true,
        );
        assert_eq!(velocities(&stream), [126, 126].map(Some));

        let mut stream = notes(2);
        stream.insert(0.0, Dynamic::new("p"));
        realize_volume(&mut stream, &DynamicContext::Ignored, true);
        assert_eq!(velocities(&stream), [90, 90].map(Some));
    }
}