music21_rs/

tempo.rs

//! Metronome marks, a port of the stream-free part of music21's `tempo`.

use crate::{
    defaults::FloatType,
    duration::Duration,
    error::{Error, Result},
};

/// The tempo words music21 knows and the beats per minute each implies,
/// in music21's order.
pub const DEFAULT_TEMPO_VALUES: [(&str, FloatType); 30] = [
    ("larghissimo", 16.0),
    ("largamente", 32.0),
    ("grave", 40.0),
    ("molto adagio", 40.0),
    ("largo", 46.0),
    ("lento", 52.0),
    ("adagio", 56.0),
    ("slow", 56.0),
    ("langsam", 56.0),
    ("larghetto", 60.0),
    ("adagietto", 66.0),
    ("andante", 72.0),
    ("andantino", 80.0),
    ("andante moderato", 83.0),
    ("maestoso", 88.0),
    ("moderato", 92.0),
    ("moderate", 92.0),
    ("allegretto", 108.0),
    ("animato", 120.0),
    ("allegro moderato", 128.0),
    ("allegro", 132.0),
    ("fast", 132.0),
    ("schnell", 132.0),
    ("allegrissimo", 140.0),
    ("molto allegro", 144.0),
    ("très vite", 144.0),
    ("vivace", 160.0),
    ("vivacissimo", 168.0),
    ("presto", 184.0),
    ("prestissimo", 208.0),
];

/// Converts a tempo counted in one note value into the same tempo counted in
/// another, both given in quarter lengths.
///
/// Sixty half notes a minute is a hundred and twenty quarters.
pub fn convert_tempo_by_referent(
    number: FloatType,
    source_quarter_length: FloatType,
    destination_quarter_length: FloatType,
) -> FloatType {
    let seconds_per_source_beat = 60.0 / number;
    let seconds_per_quarter = seconds_per_source_beat / source_quarter_length;
    60.0 / (seconds_per_quarter * destination_quarter_length)
}

/// Returns the tempo word music21 pairs with a beats-per-minute value, when
/// one lies within two beats of it. Ties go to the lower value, then the
/// alphabetically earlier word, as music21 sorts them.
pub fn default_text_for_number(number: FloatType) -> Option<&'static str> {
    let mut sorted = DEFAULT_TEMPO_VALUES;
    sorted.sort_by(|left, right| {
        left.1
            .partial_cmp(&right.1)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then_with(|| left.0.cmp(right.0))
    });
    sorted
        .iter()
        .find(|(_, value)| (value - 2.0..=value + 2.0).contains(&number))
        .map(|(text, _)| *text)
}

/// Returns the beats per minute music21 pairs with a tempo word, matching the
/// whole text case-insensitively first and any single word of it second.
pub fn default_number_for_text(text: &str) -> Option<FloatType> {
    let lowered = text.to_lowercase();
    let lookup = |candidate: &str| {
        DEFAULT_TEMPO_VALUES
            .iter()
            .find(|(name, _)| *name == candidate)
            .map(|(_, value)| *value)
    };
    lookup(&lowered).or_else(|| lookup(text)).or_else(|| {
        text.split(' ')
            .filter_map(|word| lookup(&word.to_lowercase()))
            .next_back()
    })
}

/// A metronome marking: a beats-per-minute number, a tempo word, and the
/// note value the number counts.
///
/// Either half may be implied from the other: a number alone picks up the
/// nearest tempo word, and a word alone picks up its conventional number.
#[derive(Clone, Debug, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[must_use]
pub struct MetronomeMark {
    number: Option<FloatType>,
    text: Option<String>,
    referent: Duration,
    number_implicit: bool,
    text_implicit: bool,
    /// What the mark is played at, where that is not what it says.
    #[cfg_attr(feature = "serde", serde(default))]
    number_sounding: Option<FloatType>,
}

impl Default for MetronomeMark {
    /// A mark that says nothing yet: no number, no word, counting quarters.
    /// music21 builds one of these and fills it in.
    fn default() -> Self {
        Self::build(None, None, Duration::quarter())
    }
}

impl MetronomeMark {
    /// A mark of `number` beats per minute, counting quarter notes, with the
    /// tempo word implied from the number when one is close enough.
    pub fn new(number: FloatType) -> Self {
        Self::build(Some(number), None, Duration::quarter())
    }

    /// A mark from a tempo word alone, with the number implied from the word
    /// when music21 knows it.
    pub fn from_text(text: impl Into<String>) -> Self {
        Self::build(None, Some(text.into()), Duration::quarter())
    }

    /// A mark carrying both an explicit number and an explicit word.
    pub fn with_number_and_text(number: FloatType, text: impl Into<String>) -> Self {
        Self::build(Some(number), Some(text.into()), Duration::quarter())
    }

    /// Changes the note value the number counts, so `Duration::half()` makes
    /// the number a count of half notes.
    pub fn with_referent(mut self, referent: Duration) -> Self {
        self.referent = referent;
        self
    }

    fn build(number: Option<FloatType>, text: Option<String>, referent: Duration) -> Self {
        let number_implicit = number.is_none();
        let text_implicit = text.is_none();
        let number = number.or_else(|| text.as_deref().and_then(default_number_for_text));
        let text = text.or_else(|| number.and_then(default_text_for_number).map(String::from));
        Self {
            number_implicit: number_implicit && number.is_some(),
            text_implicit: text_implicit && text.is_some(),
            number,
            text,
            referent,
            number_sounding: None,
        }
    }

    /// The same tempo counted in a different note value: music21's
    /// `getEquivalentByReferent`, so quarter = 60 becomes eighth = 120. The
    /// tempo word is carried over unchanged, implied or not.
    pub fn equivalent_by_referent(&self, referent: Duration) -> MetronomeMark {
        let number = self.number.map(|number| {
            convert_tempo_by_referent(
                number,
                self.referent.quarter_length(),
                referent.quarter_length(),
            )
        });
        Self::build(number, self.text.clone(), referent)
    }

    /// The same number counted in a different note value, so the tempo
    /// itself changes: music21's `getMaintainedNumberWithReferent`.
    pub fn maintained_number_with_referent(&self, referent: Duration) -> MetronomeMark {
        Self::build(self.number, self.text.clone(), referent)
    }

    /// The beats per minute, if known.
    pub fn number(&self) -> Option<FloatType> {
        self.number
    }

    /// Sets the beats per minute, which is then no longer implied. A mark
    /// with no word of its own picks one up, as music21 does.
    pub fn set_number(&mut self, number: Option<FloatType>) {
        self.number = number;
        self.number_implicit = false;
        if self.text.is_none()
            && let Some(number) = number
            && let Some(text) = default_text_for_number(number)
        {
            self.text = Some(text.to_string());
            self.text_implicit = true;
        }
    }

    /// Sets the tempo word, which is then no longer implied. A mark with no
    /// number of its own picks one up.
    pub fn set_text(&mut self, text: impl Into<String>) {
        let text = text.into();
        self.text_implicit = false;
        if self.number.is_none()
            && let Some(number) = default_number_for_text(&text)
        {
            self.number = Some(number);
            self.number_implicit = true;
        }
        self.text = Some(text);
    }

    /// Sets the note value the number counts, leaving the number alone — so
    /// the tempo itself changes.
    pub fn set_referent(&mut self, referent: Duration) {
        self.referent = referent;
    }

    /// The tempo word, if any.
    pub fn text(&self) -> Option<&str> {
        self.text.as_deref()
    }

    /// The tempo word as something a score would carry: music21's
    /// `getTextExpression`. A word only implied from the number is not
    /// answered unless `return_implicit` asks for it.
    pub fn text_expression(&self, return_implicit: bool) -> Option<&str> {
        if self.text_implicit && !return_implicit {
            return None;
        }
        self.text.as_deref()
    }

    /// The note value the number counts.
    pub fn referent(&self) -> &Duration {
        &self.referent
    }

    /// Whether the number was implied from the tempo word.
    pub fn number_implicit(&self) -> bool {
        self.number_implicit
    }

    /// Says so, or unsays it. music21 lets a caller write this: its MIDI
    /// reader copies a mark onto every staff and marks the copies implicit,
    /// which is how the parts after the first hide the number.
    pub fn set_number_implicit(&mut self, implicit: bool) {
        self.number_implicit = implicit;
    }

    /// Whether the tempo word was implied from the number.
    pub fn text_implicit(&self) -> bool {
        self.text_implicit
    }

    /// music21's `numberSounding`: how fast the mark is actually played,
    /// where that is not the number written over the staff.
    ///
    /// A score may say *Allegro* and be played at a hundred and forty-four,
    /// and a MusicXML `<sound tempo=...>` with no metronome mark beside it
    /// is a tempo that sounds and is never written. Nothing here is
    /// answered from it unless it is asked for: [`Self::quarter_bpm`] reads
    /// the written number, and [`Self::sounding_quarter_bpm`] reads this.
    pub fn number_sounding(&self) -> Option<FloatType> {
        self.number_sounding
    }

    /// Sets how fast the mark is played, apart from what it says.
    pub fn set_number_sounding(&mut self, number: Option<FloatType>) {
        self.number_sounding = number;
    }

    /// A mark built to be played at this speed.
    ///
    /// It does not become the mark's number: a mark that says nothing and
    /// sounds at a hundred and sixty-eight still says nothing, which is how
    /// music21 carries a tempo that is played and never written.
    pub fn with_number_sounding(mut self, number: FloatType) -> Self {
        self.number_sounding = Some(number);
        self
    }

    /// The tempo as quarter notes per minute, whatever the referent.
    pub fn quarter_bpm(&self) -> Option<FloatType> {
        self.number
            .map(|number| convert_tempo_by_referent(number, self.referent.quarter_length(), 1.0))
    }

    /// The same, at the speed the mark is played rather than the one it
    /// says: music21's `getQuarterBPM(useNumberSounding=True)`.
    pub fn sounding_quarter_bpm(&self) -> Option<FloatType> {
        match self.number_sounding {
            Some(number) => Some(convert_tempo_by_referent(
                number,
                self.referent.quarter_length(),
                1.0,
            )),
            None => self.quarter_bpm(),
        }
    }

    /// Seconds each quarter note lasts.
    ///
    /// A mark of nought beats a minute is refused rather than answered with
    /// an infinity, which is what dividing by it gives and what every
    /// arithmetic downstream of it would then carry.
    pub fn seconds_per_quarter(&self) -> Result<FloatType> {
        let quarter_bpm = self.quarter_bpm().ok_or_else(|| {
            Error::Tempo("cannot derive seconds without a tempo number".to_string())
        })?;
        if quarter_bpm == 0.0 {
            return Err(Error::Tempo(
                "a tempo of no beats a minute lasts no seconds a beat".to_string(),
            ));
        }
        Ok(60.0 / quarter_bpm)
    }

    /// Seconds a span of the given quarter length lasts at this tempo.
    pub fn quarter_length_to_seconds(&self, quarter_length: FloatType) -> Result<FloatType> {
        Ok(self.seconds_per_quarter()? * quarter_length)
    }

    /// Seconds a duration lasts at this tempo.
    pub fn duration_to_seconds(&self, duration: &Duration) -> Result<FloatType> {
        self.quarter_length_to_seconds(duration.quarter_length())
    }

    /// The duration that lasts the given number of seconds at this tempo.
    pub fn seconds_to_duration(&self, seconds: FloatType) -> Result<Duration> {
        if seconds.is_nan() || seconds <= 0.0 {
            return Err(Error::Tempo(
                "seconds must be a number greater than zero".to_string(),
            ));
        }
        Duration::new(seconds / self.seconds_per_quarter()?)
    }
}

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

    #[test]
    fn a_mark_can_be_rewritten_one_half_at_a_time() {
        let mut mark = MetronomeMark::from_text("adagio");
        assert!(mark.number_implicit());
        mark.set_number(Some(60.0));
        assert!(!mark.number_implicit());
        assert_eq!(mark.number(), Some(60.0));
        mark.set_number_implicit(true);
        assert!(mark.number_implicit());
        mark.set_referent(Duration::half());
        assert_eq!(mark.referent().quarter_length(), 2.0);
        assert_eq!(mark.quarter_bpm(), Some(120.0));

        let mut numbered = MetronomeMark::new(90.0);
        assert!(numbered.text_implicit());
        numbered.set_text("largo");
        assert!(!numbered.text_implicit());
        assert_eq!(numbered.text(), Some("largo"));
        assert_eq!(numbered.number(), Some(90.0));
        let mut wordless = MetronomeMark::default();
        wordless.set_number(Some(184.0));
        assert_eq!(wordless.text(), Some("presto"));
        assert!(wordless.text_implicit());
        wordless.set_number(None);
        assert_eq!(wordless.number(), None);
    }

    /// music21's own `getTextExpression` examples.
    #[test]
    fn an_implied_word_is_only_answered_when_asked_for() {
        let presto = MetronomeMark::from_text("presto");
        assert_eq!(presto.number(), Some(184.0));
        assert_eq!(presto.text_expression(false), Some("presto"));

        let ninety = MetronomeMark::new(90.0);
        assert!(ninety.text_implicit());
        assert_eq!(ninety.text_expression(false), None);
        assert_eq!(ninety.text_expression(true), Some("maestoso"));
    }

    #[test]
    fn a_mark_may_be_played_faster_than_it_is_written() {
        // music21's own example: a tempo that sounds and is never written.
        let playback = MetronomeMark::default().with_number_sounding(168.0);
        assert_eq!(playback.number_sounding(), Some(168.0));
        // It says nothing: the tempo is played and never written.
        assert_eq!(playback.number(), None);
        assert_eq!(playback.text(), None);
        assert_eq!(playback.quarter_bpm(), None);
        assert_eq!(playback.sounding_quarter_bpm(), Some(168.0));

        // A mark that says a number keeps it, and only the sounding tempo
        // reads the other.
        let mut written = MetronomeMark::new(60.0).with_referent(Duration::half());
        assert_eq!(written.quarter_bpm(), Some(120.0));
        assert_eq!(written.sounding_quarter_bpm(), Some(120.0));
        written.set_number_sounding(Some(90.0));
        assert_eq!(written.number(), Some(60.0));
        assert_eq!(written.quarter_bpm(), Some(120.0));
        assert_eq!(written.sounding_quarter_bpm(), Some(180.0));
    }

    #[test]
    fn referent_changes_match_music21() {
        let quarter_sixty = MetronomeMark::new(60.0);
        let eighths = quarter_sixty.equivalent_by_referent(Duration::eighth());
        assert_eq!(eighths.number(), Some(120.0));
        assert_eq!(eighths.referent().quarter_length(), 0.5);
        assert_eq!(eighths.text(), Some("larghetto"));
        let halves = quarter_sixty.equivalent_by_referent(Duration::half());
        assert_eq!(halves.number(), Some(30.0));

        let andante = MetronomeMark::with_number_and_text(72.0, "andante")
            .with_referent(Duration::new(1.5).unwrap());
        let quarters = andante.equivalent_by_referent(Duration::quarter());
        assert_eq!(quarters.number(), Some(108.0));
        assert_eq!(quarters.text(), Some("andante"));
        assert_eq!(
            andante.equivalent_by_referent(Duration::half()).number(),
            Some(54.0)
        );

        let kept = andante.maintained_number_with_referent(Duration::eighth());
        assert_eq!(kept.number(), Some(72.0));
        assert_eq!(kept.referent().quarter_length(), 0.5);
        assert_eq!(kept.text(), Some("andante"));
    }

    #[test]
    fn numbers_imply_the_tempo_words_music21_picks() {
        let cases = [
            (120.0, Some("animato")),
            (60.0, Some("larghetto")),
            (61.0, Some("larghetto")),
            (62.0, Some("larghetto")),
            (63.0, None),
            (90.0, Some("maestoso")),
            (92.0, Some("moderate")),
            (100.0, None),
            (118.0, Some("animato")),
            (122.0, Some("animato")),
            (123.0, None),
            (16.0, Some("larghissimo")),
            (12.0, None),
            (56.5, Some("adagio")),
            (300.0, None),
        ];
        for (number, text) in cases {
            let mark = MetronomeMark::new(number);
            assert_eq!(mark.text(), text, "{number}");
            assert_eq!(mark.text_implicit(), text.is_some(), "{number}");
            assert!(!mark.number_implicit());
        }
    }

    #[test]
    fn words_imply_their_conventional_numbers() {
        let cases = [
            ("allegro", Some(132.0)),
            ("Allegro", Some(132.0)),
            ("ALLEGRO ", Some(132.0)),
            ("très vite", Some(144.0)),
            ("andante moderato", Some(83.0)),
            ("unknown words", None),
        ];
        for (text, number) in cases {
            let mark = MetronomeMark::from_text(text);
            assert_eq!(mark.number(), number, "{text}");
            assert_eq!(mark.number_implicit(), number.is_some(), "{text}");
            assert_eq!(mark.text(), Some(text));
            assert!(!mark.text_implicit());
        }
        let both = MetronomeMark::with_number_and_text(120.0, "fast");
        assert_eq!(both.number(), Some(120.0));
        assert_eq!(both.text(), Some("fast"));
        assert!(!both.number_implicit() && !both.text_implicit());
    }

    #[test]
    fn referents_convert_to_quarter_bpm_and_seconds() {
        let quarter = MetronomeMark::new(120.0);
        assert_eq!(quarter.quarter_bpm(), Some(120.0));
        assert_eq!(quarter.quarter_length_to_seconds(1.0).unwrap(), 0.5);
        assert_eq!(
            quarter.seconds_to_duration(0.75).unwrap().quarter_length(),
            1.5
        );

        let half = MetronomeMark::new(60.0).with_referent(Duration::half());
        assert_eq!(half.quarter_bpm(), Some(120.0));
        assert_eq!(half.text(), Some("larghetto"));
        assert_eq!(half.quarter_length_to_seconds(1.0).unwrap(), 0.5);
        assert_eq!(
            half.duration_to_seconds(&Duration::new(3.0).unwrap())
                .unwrap(),
            1.5
        );
        assert_eq!(half.seconds_to_duration(1.0).unwrap().quarter_length(), 2.0);

        let eighth = MetronomeMark::new(120.0).with_referent(Duration::eighth());
        assert_eq!(eighth.quarter_bpm(), Some(60.0));
        assert_eq!(eighth.seconds_per_quarter().unwrap(), 1.0);

        let dotted = MetronomeMark::new(56.5).with_referent(Duration::half());
        assert!((dotted.quarter_bpm().unwrap() - 113.0).abs() < 1e-9);

        assert_eq!(convert_tempo_by_referent(60.0, 1.0, 2.0), 30.0);
        assert_eq!(convert_tempo_by_referent(60.0, 2.0, 1.0), 120.0);

        let unknown = MetronomeMark::from_text("unknown words");
        assert_eq!(unknown.quarter_bpm(), None);
        assert!(unknown.seconds_per_quarter().is_err());
        assert!(quarter.seconds_to_duration(0.0).is_err());

        let motionless = MetronomeMark::new(0.0);
        assert_eq!(motionless.quarter_bpm(), Some(0.0));
        assert!(motionless.seconds_per_quarter().is_err());
        assert!(
            motionless
                .duration_to_seconds(&Duration::quarter())
                .is_err()
        );
        assert!(motionless.quarter_length_to_seconds(1.0).is_err());
    }
}