acorde_core/model/

notation.rs

use super::score::NoteAddr;
use serde::{Deserialize, Serialize};

use super::pitch::{Pitch, Step};

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Clef {
    Treble,
    Bass,
    Alto,
    Tenor,
    Percussion,
    /// Treble clef with an 8 below: sounds an octave lower (tenor voice, guitar).
    Treble8vb,
    /// Treble clef with an 8 above: sounds an octave higher.
    Treble8va,
    /// Bass clef with an 8 below: sounds an octave lower (contrabass, bass guitar).
    Bass8vb,
    /// Bass clef with an 8 above: sounds an octave higher.
    Bass8va,
    /// C clef on the bottom line.
    Soprano,
    /// C clef on the second line.
    MezzoSoprano,
    /// C clef on the top line.
    Baritone,
    /// An ABC 2.1 clef whose middle staff line is explicitly mapped to a written pitch.
    ///
    /// ABC's `middle=` modifier changes staff placement only. It does not transpose the
    /// written pitch or playback, so the original ABC pitch remains intact.
    AbcMiddle {
        /// The conventional clef glyph to draw.
        base: Box<Clef>,
        /// Written pitch placed on the middle staff line.
        middle: Pitch,
    },
}

impl Clef {
    pub fn to_musicxml_sign(&self) -> &'static str {
        match self {
            Clef::Treble | Clef::Treble8vb | Clef::Treble8va => "G",
            Clef::Bass | Clef::Bass8vb | Clef::Bass8va => "F",
            Clef::Alto | Clef::Tenor | Clef::Soprano | Clef::MezzoSoprano | Clef::Baritone => "C",
            Clef::Percussion => "percussion",
            Clef::AbcMiddle { base, .. } => base.to_musicxml_sign(),
        }
    }

    pub fn musicxml_line(&self) -> u8 {
        match self {
            Clef::Treble | Clef::Treble8vb | Clef::Treble8va => 2,
            Clef::Bass | Clef::Bass8vb | Clef::Bass8va => 4,
            Clef::Alto => 3,
            Clef::Tenor => 4,
            Clef::Percussion => 2,
            Clef::Soprano => 1,
            Clef::MezzoSoprano => 2,
            Clef::Baritone => 5,
            Clef::AbcMiddle { base, .. } => base.musicxml_line(),
        }
    }

    /// Octaves the music sounds above (+) or below (−) the written notes: the small 8 on the
    /// clef (MusicXML `<clef-octave-change>`, MEI `@clef.dis`/`@dis.place`).
    pub fn octave_change(&self) -> i8 {
        match self {
            Clef::Treble8vb | Clef::Bass8vb => -1,
            Clef::Treble8va | Clef::Bass8va => 1,
            Clef::AbcMiddle { base, .. } => base.octave_change(),
            _ => 0,
        }
    }

    /// The clef without its octave mark.
    pub fn without_octave(&self) -> Clef {
        match self {
            Clef::Treble8vb | Clef::Treble8va => Clef::Treble,
            Clef::Bass8vb | Clef::Bass8va => Clef::Bass,
            Clef::AbcMiddle { base, middle } => Clef::AbcMiddle {
                base: Box::new(base.without_octave()),
                middle: middle.clone(),
            },
            other => other.clone(),
        }
    }

    /// Attach ABC 2.1's visual `middle=` placement to a conventional clef.
    ///
    /// Nested custom placements and percussion clefs have no unambiguous ABC meaning and are
    /// rejected by returning `None`.
    pub fn with_abc_middle(base: Clef, middle: Pitch) -> Option<Clef> {
        (!matches!(base, Clef::AbcMiddle { .. } | Clef::Percussion)).then_some(Clef::AbcMiddle {
            base: Box::new(base),
            middle,
        })
    }

    /// The pitch explicitly placed on the middle line by ABC's `middle=` modifier.
    pub fn abc_middle(&self) -> Option<&Pitch> {
        match self {
            Clef::AbcMiddle { middle, .. } => Some(middle),
            _ => None,
        }
    }

    /// The clef for a sign (`G`, `F`, `C`, `percussion`), a staff line (1 = bottom) and an
    /// octave change (±1), as MusicXML, MEI and MuseScore describe clefs. `None` for
    /// combinations the model does not have (French violin clef, a 15ma clef, sub-bass clef).
    pub fn from_sign(sign: &str, line: Option<u8>, octave_change: i8) -> Option<Clef> {
        let clef = match (sign.trim().to_ascii_uppercase().as_str(), line) {
            ("G", None | Some(2)) => Clef::Treble,
            ("F", None | Some(4)) => Clef::Bass,
            ("C", Some(1)) => Clef::Soprano,
            ("C", Some(2)) => Clef::MezzoSoprano,
            ("C", None | Some(3)) => Clef::Alto,
            ("C", Some(4)) => Clef::Tenor,
            ("C", Some(5)) | ("F", Some(3)) => Clef::Baritone,
            ("PERCUSSION", _) => Clef::Percussion,
            _ => return None,
        };
        Some(match (clef, octave_change) {
            (clef, 0) => clef,
            (Clef::Treble, -1) => Clef::Treble8vb,
            (Clef::Treble, 1) => Clef::Treble8va,
            (Clef::Bass, -1) => Clef::Bass8vb,
            (Clef::Bass, 1) => Clef::Bass8va,
            (Clef::Percussion, _) => Clef::Percussion,
            _ => return None,
        })
    }

    /// The clef named as in score JSON (`"Treble"`, `"Treble8vb"`, `"MezzoSoprano"`, …).
    pub fn from_name(name: &str) -> Option<Clef> {
        Some(match name {
            "Treble" => Clef::Treble,
            "Bass" => Clef::Bass,
            "Alto" => Clef::Alto,
            "Tenor" => Clef::Tenor,
            "Percussion" => Clef::Percussion,
            "Treble8vb" => Clef::Treble8vb,
            "Treble8va" => Clef::Treble8va,
            "Bass8vb" => Clef::Bass8vb,
            "Bass8va" => Clef::Bass8va,
            "Soprano" => Clef::Soprano,
            "MezzoSoprano" => Clef::MezzoSoprano,
            "Baritone" => Clef::Baritone,
            _ => return None,
        })
    }

    /// MIDI note number of the middle staff line (used for stem direction heuristics).
    pub fn middle_line_midi(&self) -> u8 {
        match self {
            Clef::Treble => 71,       // B4
            Clef::Bass => 50,         // D3
            Clef::Alto => 60,         // C4
            Clef::Tenor => 57,        // A3
            Clef::Percussion => 71,   // B4 (same as Treble)
            Clef::Treble8vb => 59,    // B3
            Clef::Treble8va => 83,    // B5
            Clef::Bass8vb => 38,      // D2
            Clef::Bass8va => 62,      // D4
            Clef::Soprano => 67,      // G4
            Clef::MezzoSoprano => 64, // E4
            Clef::Baritone => 53,     // F3
            Clef::AbcMiddle { middle, .. } => middle.to_midi().clamp(0, 127) as u8,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct KeySignature {
    /// -7 (7 flats) to +7 (7 sharps), 0 = C major / A minor.
    pub fifths: i8,
    /// "major" or "minor"
    pub mode: String,
}

impl Default for KeySignature {
    fn default() -> Self {
        Self {
            fifths: 0,
            mode: "major".to_string(),
        }
    }
}

impl KeySignature {
    // Order of sharps added one by one as fifths increases: F C G D A E B
    const SHARP_ORDER: [Step; 7] = [
        Step::F,
        Step::C,
        Step::G,
        Step::D,
        Step::A,
        Step::E,
        Step::B,
    ];
    // Order of flats: B E A D G C F
    const FLAT_ORDER: [Step; 7] = [
        Step::B,
        Step::E,
        Step::A,
        Step::D,
        Step::G,
        Step::C,
        Step::F,
    ];

    /// Accidental alter (`-1`, `0`, or `+1`) applied to `step` in this key signature.
    pub fn alter_for_step(&self, step: &Step) -> i8 {
        if self.fifths > 0 {
            let count = self.fifths.min(7) as usize;
            if Self::SHARP_ORDER[..count].contains(step) {
                1
            } else {
                0
            }
        } else if self.fifths < 0 {
            let count = (-self.fifths).min(7) as usize;
            if Self::FLAT_ORDER[..count].contains(step) {
                -1
            } else {
                0
            }
        } else {
            0
        }
    }

    /// True if `pitch` is diatonic to this key (octave-independent, checks step + alter).
    pub fn contains_pitch(&self, pitch: &Pitch) -> bool {
        pitch.alter == self.alter_for_step(&pitch.step)
    }

    /// Tonic step and alter for this key.
    ///
    /// Examples: G major → `(Step::G, 0)`, Bb major → `(Step::B, -1)`, F# minor → `(Step::F, 1)`.
    pub fn tonic(&self) -> (Step, i8) {
        if self.mode == "minor" {
            let (maj_step, maj_alter) = Self::major_tonic_from_fifths(self.fifths);
            // Relative minor tonic = major tonic - 3 semitones.
            let major_midi = Pitch::with_alter(maj_step, 4, maj_alter).to_midi();
            let minor_midi = (major_midi - 3).clamp(0, 127) as u8;
            let p = Pitch::from_midi(minor_midi, self.fifths < 0);
            (p.step, p.alter)
        } else {
            Self::major_tonic_from_fifths(self.fifths)
        }
    }

    /// Human-readable key name: `"C major"`, `"G major"`, `"F# minor"`, `"Bb major"` etc.
    pub fn display_name(&self) -> String {
        let (step, alter) = self.tonic();
        let acc = match alter {
            1 => "#",
            -1 => "b",
            _ => "",
        };
        format!("{}{} {}", step.to_char(), acc, self.mode)
    }

    fn major_tonic_from_fifths(fifths: i8) -> (Step, i8) {
        // Index = fifths + 7 (range 0..=14).
        // -7=Cb, -6=Gb, -5=Db, -4=Ab, -3=Eb, -2=Bb, -1=F, 0=C, +1=G, +2=D, +3=A, +4=E, +5=B, +6=F#, +7=C#
        const TONICS: [(Step, i8); 15] = [
            (Step::C, -1), // -7: Cb
            (Step::G, -1), // -6: Gb
            (Step::D, -1), // -5: Db
            (Step::A, -1), // -4: Ab
            (Step::E, -1), // -3: Eb
            (Step::B, -1), // -2: Bb
            (Step::F, 0),  // -1: F
            (Step::C, 0),  //  0: C
            (Step::G, 0),  // +1: G
            (Step::D, 0),  // +2: D
            (Step::A, 0),  // +3: A
            (Step::E, 0),  // +4: E
            (Step::B, 0),  // +5: B
            (Step::F, 1),  // +6: F#
            (Step::C, 1),  // +7: C#
        ];
        let idx = (fifths.clamp(-7, 7) + 7) as usize;
        TONICS[idx].clone()
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TimeSignature {
    pub numerator: u8,
    pub denominator: u8,
}

/// Written display of a 4/4 or 2/2 meter, separate from its rhythmic value.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum TimeSymbol {
    Common,
    Cut,
}

impl Default for TimeSignature {
    fn default() -> Self {
        Self {
            numerator: 4,
            denominator: 4,
        }
    }
}

impl TimeSignature {
    pub fn beats_per_measure(&self) -> f64 {
        self.numerator as f64
    }

    pub fn beat_unit_beats(&self) -> f64 {
        4.0 / self.denominator as f64
    }

    pub fn total_beats(&self) -> f64 {
        self.beats_per_measure() * self.beat_unit_beats()
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Dynamic {
    Pppp,
    Ppp,
    Pp,
    P,
    Mp,
    Mf,
    F,
    Ff,
    Fff,
    Ffff,
    Sfz,
    Rfz,
    Fz,
    Sf,
    /// Forte-piano: loud attack, then piano.
    Fp,
    /// Sforzando-piano: accented attack, then piano.
    Sfp,
    /// Sforzando-pianissimo: accented attack, then pianissimo.
    Sfpp,
    /// Piano-forte: soft attack, then forte.
    Pf,
    /// Sforzatissimo: a stronger sforzando.
    Sffz,
    /// Sforzato-piano: sforzato attack, then piano.
    Sfzp,
    /// Niente: fading to nothing.
    N,
}

impl Dynamic {
    /// Every dynamic, for exhaustive mapping tables.
    pub const ALL: [Dynamic; 21] = [
        Dynamic::Pppp,
        Dynamic::Ppp,
        Dynamic::Pp,
        Dynamic::P,
        Dynamic::Mp,
        Dynamic::Mf,
        Dynamic::F,
        Dynamic::Ff,
        Dynamic::Fff,
        Dynamic::Ffff,
        Dynamic::Sfz,
        Dynamic::Rfz,
        Dynamic::Fz,
        Dynamic::Sf,
        Dynamic::Fp,
        Dynamic::Sfp,
        Dynamic::Sfpp,
        Dynamic::Pf,
        Dynamic::Sffz,
        Dynamic::Sfzp,
        Dynamic::N,
    ];

    /// Parse a MusicXML dynamics element name (also MEI `<dynam>` and MuseScore dynamic
    /// text), folding the extreme `ppppp`/`fffff` levels into the nearest supported one.
    pub fn from_musicxml_str(name: &str) -> Option<Dynamic> {
        Some(match name {
            "pppppp" | "ppppp" => Dynamic::Pppp,
            "ffffff" | "fffff" => Dynamic::Ffff,
            "rf" => Dynamic::Rfz,
            other => *Self::ALL
                .iter()
                .find(|dynamic| dynamic.to_musicxml_str() == other)?,
        })
    }

    /// The level that continues after this marking, until the next one: itself for a level
    /// (p, f, …), the second level for a compound (fp → p, pf → f), and `None` for an
    /// accent on one note (sf, sfz, fz, rfz), after which the previous level resumes.
    pub fn sustained_level(&self) -> Option<Dynamic> {
        match self {
            Dynamic::Sfz | Dynamic::Rfz | Dynamic::Fz | Dynamic::Sf | Dynamic::Sffz => None,
            Dynamic::Fp | Dynamic::Sfp | Dynamic::Sfzp => Some(Dynamic::P),
            Dynamic::Sfpp => Some(Dynamic::Pp),
            Dynamic::Pf => Some(Dynamic::F),
            level => Some(*level),
        }
    }

    pub fn to_musicxml_str(&self) -> &'static str {
        match self {
            Dynamic::Pppp => "pppp",
            Dynamic::Ppp => "ppp",
            Dynamic::Pp => "pp",
            Dynamic::P => "p",
            Dynamic::Mp => "mp",
            Dynamic::Mf => "mf",
            Dynamic::F => "f",
            Dynamic::Ff => "ff",
            Dynamic::Fff => "fff",
            Dynamic::Ffff => "ffff",
            Dynamic::Sfz => "sfz",
            Dynamic::Rfz => "rfz",
            Dynamic::Fz => "fz",
            Dynamic::Sf => "sf",
            Dynamic::Fp => "fp",
            Dynamic::Sfp => "sfp",
            Dynamic::Sfpp => "sfpp",
            Dynamic::Pf => "pf",
            Dynamic::Sffz => "sffz",
            Dynamic::Sfzp => "sfzp",
            Dynamic::N => "n",
        }
    }

    pub fn to_velocity(&self) -> u8 {
        match self {
            Dynamic::Pppp => 16,
            Dynamic::Ppp => 24,
            Dynamic::Pp => 36,
            Dynamic::P => 48,
            Dynamic::Mp => 60,
            Dynamic::Mf => 72,
            Dynamic::F => 84,
            Dynamic::Ff => 96,
            Dynamic::Fff => 108,
            Dynamic::Ffff => 120,
            Dynamic::Sfz => 112,
            Dynamic::Rfz => 104,
            Dynamic::Fz => 100,
            Dynamic::Sf => 96,
            Dynamic::Fp => 84,
            Dynamic::Sfp | Dynamic::Sfpp => 96,
            Dynamic::Pf => 48,
            Dynamic::Sffz => 120,
            Dynamic::Sfzp => 112,
            Dynamic::N => 8,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Articulation {
    Staccato,
    Staccatissimo,
    Accent,
    Tenuto,
    Marcato,
    Fermata,
    Trill,
    Mordent,
    InvertedMordent,
    Turn,
    InvertedTurn,
    Shake,
    Tremolo(u8),
    BreathMark,
    Caesura,
    /// String up-bow (MusicXML `<up-bow/>`).
    UpBow,
    /// String down-bow (MusicXML `<down-bow/>`).
    DownBow,
    /// Harmonic circle (MusicXML `<harmonic/>`).
    Harmonic,
    /// Open string / open mute circle (MusicXML `<open-string/>`).
    OpenString,
    /// Stopped note or closed mute "+" (MusicXML `<stopped/>`).
    Stopped,
    /// Snap (Bartók) pizzicato (MusicXML `<snap-pizzicato/>`).
    SnapPizzicato,
    /// Right-hand tapping, drawn "T" (MusicXML `<tap/>`, MEI `tap`, Guitar Pro tapping).
    Tap,
    /// Left-hand tapping (MusicXML `<tap hand="left"/>`, Guitar Pro left-hand tapping).
    LeftHandTap,
    /// Vibrato on one note, a short wavy line above it (Guitar Pro note vibrato).
    Vibrato,
    /// A slide into the note from below (MusicXML `<scoop/>`, Guitar Pro slide in from below).
    Scoop,
    /// A slide into the note from above (MusicXML `<plop/>`, Guitar Pro slide in from above).
    Plop,
    /// A slide up out of the note (MusicXML `<doit/>`, Guitar Pro slide out upwards).
    Doit,
    /// A slide down out of the note (MusicXML `<falloff/>`, Guitar Pro slide out downwards).
    Falloff,
}

impl Articulation {
    /// String and brass techniques that MusicXML writes inside `<technical>` rather than
    /// `<articulations>`.
    pub fn is_technical_mark(&self) -> bool {
        matches!(
            self,
            Self::UpBow
                | Self::DownBow
                | Self::Harmonic
                | Self::OpenString
                | Self::Stopped
                | Self::SnapPizzicato
                | Self::Tap
                | Self::LeftHandTap
                | Self::Vibrato
        )
    }
}

/// Guitar-specific playing technique attached to a note.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum GuitarTechnique {
    Bend,
    Slide,
    HammerOn,
    PullOff,
}

/// Deterministic policy for selecting one candidate from an ordered fingering list.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
pub enum FingeringSelectionPolicy {
    /// Preserve the source/application's first candidate.
    #[default]
    SourceOrder,
    /// Select the numerically smallest candidate.
    LowestNumber,
    /// Select the numerically largest candidate.
    HighestNumber,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub enum Barline {
    #[default]
    Normal,
    Double,
    Final,
    RepeatStart,
    RepeatEnd,
    RepeatBoth,
    Dashed,
    Dotted,
    Invisible,
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub enum HairpinKind {
    Crescendo,
    Decrescendo,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TupletInfo {
    /// Notes in the tuplet group (e.g. 3 for triplet).
    pub actual_notes: u8,
    /// Normal notes displaced (e.g. 2 for triplet = 3-in-2).
    pub normal_notes: u8,
}

/// Explicit written tuplet boundary. Timing remains defined by [`TupletInfo`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum TupletBoundary {
    Start,
    Stop,
    StartStop,
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Default)]
pub enum BeamState {
    #[default]
    None,
    Begin,
    Continue,
    End,
    BeginEnd,
    BackwardHook,
    ForwardHook,
}

/// Ottava (octave transposition bracket).
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub enum OttavaKind {
    /// 8va — sounds one octave higher than written.
    Va8,
    /// 8vb — sounds one octave lower than written.
    Vb8,
    /// 15ma — sounds two octaves higher than written.
    Ma15,
    /// 15mb — sounds two octaves lower than written.
    Mb15,
}

impl OttavaKind {
    /// MusicXML `octave-shift@type`: the direction the notes are *displayed* shifted from
    /// their (sounding) pitch, so an 8va — sounding higher than written — is `down`.
    pub fn musicxml_type(&self) -> &'static str {
        match self {
            OttavaKind::Va8 | OttavaKind::Ma15 => "down",
            OttavaKind::Vb8 | OttavaKind::Mb15 => "up",
        }
    }

    /// Diatonic steps by which notes under this mark are drawn from their sounding pitch.
    pub fn display_shift_steps(&self) -> i32 {
        match self {
            OttavaKind::Va8 => -7,
            OttavaKind::Ma15 => -14,
            OttavaKind::Vb8 => 7,
            OttavaKind::Mb15 => 14,
        }
    }

    pub fn musicxml_size(&self) -> u8 {
        match self {
            OttavaKind::Va8 | OttavaKind::Vb8 => 8,
            OttavaKind::Ma15 | OttavaKind::Mb15 => 15,
        }
    }
}

/// How a pitch's accidental is shown when the notation rules alone would not decide it: a
/// cautionary (courtesy) accidental the source asked for, one in parentheses or brackets, or
/// an editorial one. `Auto` (the default) leaves the accidental to the key and the bar.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
pub enum AccidentalDisplay {
    #[default]
    Auto,
    /// Explicitly written without a cautionary or editorial role.
    Explicit,
    /// Always shown, without parentheses (MusicXML `cautionary="yes"`, MEI `@func="caution"`).
    Cautionary,
    /// Always shown, in parentheses (MusicXML `parentheses="yes"`/`bracket="yes"`, MEI
    /// `@enclose`, MuseScore accidental brackets).
    Parenthesized,
    /// An editor's addition (MusicXML `editorial="yes"`, MEI `@func="edit"`), always shown.
    Editorial,
}

/// Note head shape.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
pub enum NoteHead {
    #[default]
    Normal,
    Diamond,  // natural harmonics
    X,        // muted / dead note
    Slash,    // ghost note
    Cross,    // percussion special
    Triangle, // tap harmonics
}

/// Lyric syllable attached to a note.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Lyric {
    /// The syllable text.
    pub text: String,
    /// Syllabic position: "single" | "begin" | "middle" | "end"
    pub syllabic: String,
    /// A melisma extender line follows the syllable, under the notes up to (not including)
    /// the next note with a lyric or the next rest (MusicXML `<extend>`, MEI `con="u"`).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub extend: bool,
}

/// A lyric syllable for verse 2 or later. Verse 1 stays in `Note.lyric`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct VerseLyric {
    /// Verse number, from 2 to [`VerseLyric::MAX_VERSE`].
    pub verse: u8,
    pub lyric: Lyric,
}

impl VerseLyric {
    /// Highest supported verse number.
    pub const MAX_VERSE: u8 = 32;
}

/// A typed score text annotation. The text itself is kept separate from its
/// presentation role so consumers do not need to infer semantics from prose.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct StyledText {
    pub style: TextStyle,
    pub text: String,
    /// Position in quarter-note beats from the start of the measure. This is a
    /// semantic direction anchor; it is independent of engraved x offsets.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub position_beats: Option<f64>,
    /// Optional vertical placement hint from interchange formats.
    #[serde(default)]
    pub placement: Option<String>,
    /// MusicXML default horizontal offset in tenths, when attached to a direction text.
    #[serde(default)]
    pub offset_x: Option<f64>,
    /// MusicXML default vertical offset in tenths, when attached to a direction text.
    #[serde(default)]
    pub offset_y: Option<f64>,
    /// MusicXML relative horizontal offset in tenths, retaining its relative-coordinate meaning.
    #[serde(default)]
    pub relative_x: Option<f64>,
    /// MusicXML relative vertical offset in tenths, retaining its relative-coordinate meaning.
    #[serde(default)]
    pub relative_y: Option<f64>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum TextStyle {
    Expression,
    Technique,
    Lyrics,
    ChordSymbol,
    FiguredBass,
    RehearsalMark,
    Generic,
}

/// Cross-staff placement metadata. The note remains in its source staff, so
/// its stable playback address continues to identify the original note.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CrossStaff {
    pub target_staff: usize,
    #[serde(default)]
    pub target_voice: Option<usize>,
}

/// A tablature string/fret position attached to a pitched note.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TabPosition {
    /// One-based string number, matching MusicXML `<string>`.
    pub string: u8,
    pub fret: u8,
}

/// Tablature staff metadata. Tuning MIDI values are ordered by string number.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TablatureConfig {
    pub lines: u8,
    pub tuning_midi: Vec<i16>,
    #[serde(default)]
    pub capo: u8,
}

/// Structured chord symbol attached to a note.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChordSymbol {
    /// Root note name: "C", "F#", "Bb", etc.
    pub root: String,
    /// MusicXML harmony kind: "major", "minor", "dominant", "major-seventh", etc.
    pub kind: String,
    /// Slash-chord bass note.
    pub bass: Option<String>,
    /// Optional vertical placement hint from interchange formats (for example `above`/`below`).
    #[serde(default)]
    pub placement: Option<String>,
    /// Whether the source harmony carries a continuation/extender line.
    #[serde(default)]
    pub extender: bool,
    /// MEI harmonic-analysis scale degree (Humdrum **deg syntax), when supplied.
    #[serde(default)]
    pub harmonic_degree: Option<String>,
    /// MEI harmonic function token (for example `T`, `PD`, or `D`), when supplied.
    #[serde(default)]
    pub harmony_function: Option<String>,
    /// MEI `harm@type` classification token(s), when supplied.
    #[serde(default)]
    pub harmony_type: Option<String>,
    /// MEI `harm@chordref` URI, retained without resolving an external chord definition.
    #[serde(default)]
    pub chord_ref: Option<String>,
    /// Optional note address where a harmony range ends.
    ///
    /// This is primarily used by MEI `harm@tstamp2`/`endid`.  The field is
    /// optional so older score JSON and formats without harmony ranges remain
    /// fully compatible.
    #[serde(default)]
    pub range_end: Option<NoteAddr>,
    /// Structured chord extensions such as add9, alter5, or omit3.
    #[serde(default)]
    pub degrees: Vec<ChordDegree>,
}

/// A reusable MEI chord/tablature definition referenced by `harm@chordref`.
///
/// The fields intentionally retain the source spelling for deprecated MEI tuning
/// attributes.  Consumers may interpret the member positions without requiring
/// the canonical score to invent an instrument catalog.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChordDefinition {
    #[serde(default)]
    pub id: Option<String>,
    #[serde(default)]
    pub label: Option<String>,
    #[serde(default)]
    pub kind: Option<String>,
    #[serde(default)]
    pub fret_position: Option<u32>,
    #[serde(default)]
    pub tab_strings: Option<String>,
    #[serde(default)]
    pub tab_courses: Option<String>,
    #[serde(default)]
    pub members: Vec<ChordDefinitionMember>,
    #[serde(default)]
    pub barres: Vec<ChordBarre>,
}

/// One pitch and/or tablature position in a [`ChordDefinition`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChordDefinitionMember {
    #[serde(default)]
    pub id: Option<String>,
    #[serde(default)]
    pub pitch: Option<Pitch>,
    #[serde(default)]
    pub tab_string: Option<u8>,
    #[serde(default)]
    pub tab_course: Option<u8>,
    #[serde(default)]
    pub tab_fret: Option<u16>,
    #[serde(default)]
    pub fingering: Option<u8>,
}

/// A barre range inside a [`ChordDefinition`] fretboard diagram.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChordBarre {
    #[serde(default)]
    pub start_member: Option<String>,
    #[serde(default)]
    pub end_member: Option<String>,
    #[serde(default)]
    pub fret: Option<u16>,
    #[serde(default)]
    pub label: Option<String>,
    #[serde(default)]
    pub kind: Option<String>,
}

/// One structured MusicXML chord degree.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChordDegree {
    /// Scale degree number (normally 1 through 13).
    pub value: u8,
    /// Semitone alteration relative to the diatonic degree.
    pub alter: i8,
    /// MusicXML degree type, such as `add`, `alter`, or `subtract`.
    pub kind: String,
}

/// One structured figure in a figured-bass annotation.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FiguredBassFigure {
    /// Source figure number, retained as text because MusicXML permits non-numeric figures.
    pub number: String,
    /// Raw source alteration value, such as `-1`, `0`, or `1`.
    #[serde(default)]
    pub alter: Option<String>,
    /// Optional source prefix decoration.
    #[serde(default)]
    pub prefix: Option<String>,
    /// Optional source suffix decoration.
    #[serde(default)]
    pub suffix: Option<String>,
    /// Whether MEI marks this figure with a horizontal extender.
    #[serde(default)]
    pub extender: bool,
}

/// A MusicXML figured-bass group at a score-time position in the measure.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FiguredBassGroup {
    /// Editable voice slot containing the following note.
    #[serde(default)]
    pub voice: usize,
    /// Position in quarter-note beats from the start of the measure.
    pub position_beats: f64,
    /// Duration in quarter-note beats, when explicitly present in the source.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub duration_beats: Option<f64>,
    /// Figures in source order.
    pub figures: Vec<FiguredBassFigure>,
    /// Raw extend type for each figure; an empty string represents an untyped extend.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extend_types: Vec<Option<String>>,
}

impl ChordDegree {
    /// Render the degree using the compact chord-label convention.
    pub fn display_text(&self) -> String {
        let accidental = match self.alter {
            -2 => "bb",
            -1 => "b",
            1 => "#",
            2 => "##",
            _ => "",
        };
        match self.kind.as_str() {
            "subtract" => format!("no{}{}", accidental, self.value),
            "alter" => format!("{}{}", accidental, self.value),
            _ => format!("add{}{}", accidental, self.value),
        }
    }
}

/// Chord kinds (MusicXML `<kind>` values, plus aliases other formats use) and the compact
/// suffix a chord label writes after its root. The first entry for a suffix is the kind a label
/// reads back as.
pub const CHORD_KIND_SUFFIXES: &[(&str, &str)] = &[
    ("major", ""),
    ("minor", "m"),
    ("augmented", "aug"),
    ("diminished", "dim"),
    ("dominant", "7"),
    ("major-seventh", "maj7"),
    ("minor-seventh", "m7"),
    ("diminished-seventh", "dim7"),
    ("augmented-seventh", "aug7"),
    ("half-diminished", "m7b5"),
    ("major-minor", "mMaj7"),
    ("minor-major-seventh", "mMaj7"),
    ("minor-major", "mMaj7"),
    ("major-sixth", "6"),
    ("minor-sixth", "m6"),
    ("dominant-ninth", "9"),
    ("major-ninth", "maj9"),
    ("minor-ninth", "m9"),
    ("dominant-11th", "11"),
    ("major-11th", "maj11"),
    ("minor-11th", "m11"),
    ("dominant-13th", "13"),
    ("major-13th", "maj13"),
    ("minor-13th", "m13"),
    ("suspended-second", "sus2"),
    ("suspended-fourth", "sus4"),
    ("power", "5"),
    ("major-add9", "add9"),
    ("minor-add9", "madd9"),
    ("dominant-flat-five", "7b5"),
    ("dominant-sharp-five", "7#5"),
];

impl ChordSymbol {
    /// The chord kind a compact label suffix (`"m7"`, `"aug7"`, `"13"`) stands for.
    pub fn kind_for_suffix(suffix: &str) -> Option<&'static str> {
        CHORD_KIND_SUFFIXES
            .iter()
            .find(|(_, candidate)| *candidate == suffix)
            .map(|(kind, _)| *kind)
    }

    pub fn display_text(&self) -> String {
        let kind_str = CHORD_KIND_SUFFIXES
            .iter()
            .find(|(kind, _)| *kind == self.kind)
            .map_or(self.kind.as_str(), |(_, suffix)| *suffix);
        let bass_str = match &self.bass {
            Some(b) => format!("/{}", b),
            None => String::new(),
        };
        let degree_str = self
            .degrees
            .iter()
            .map(ChordDegree::display_text)
            .collect::<String>();
        format!("{}{}{}{}", self.root, kind_str, degree_str, bass_str)
    }
}

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

    #[test]
    fn key_alter_c_major_all_natural() {
        let key = KeySignature {
            fifths: 0,
            mode: "major".into(),
        };
        for step in [
            Step::C,
            Step::D,
            Step::E,
            Step::F,
            Step::G,
            Step::A,
            Step::B,
        ] {
            assert_eq!(key.alter_for_step(&step), 0, "step {:?}", step);
        }
    }

    #[test]
    fn key_alter_g_major_fsharp() {
        let key = KeySignature {
            fifths: 1,
            mode: "major".into(),
        };
        assert_eq!(key.alter_for_step(&Step::F), 1);
        assert_eq!(key.alter_for_step(&Step::G), 0);
    }

    #[test]
    fn key_alter_f_major_bflat() {
        let key = KeySignature {
            fifths: -1,
            mode: "major".into(),
        };
        assert_eq!(key.alter_for_step(&Step::B), -1);
        assert_eq!(key.alter_for_step(&Step::C), 0);
    }

    #[test]
    fn key_alter_bb_major() {
        let key = KeySignature {
            fifths: -2,
            mode: "major".into(),
        };
        assert_eq!(key.alter_for_step(&Step::B), -1);
        assert_eq!(key.alter_for_step(&Step::E), -1);
        assert_eq!(key.alter_for_step(&Step::A), 0);
    }

    #[test]
    fn key_contains_pitch_g_major() {
        let key = KeySignature {
            fifths: 1,
            mode: "major".into(),
        };
        // In-key: G, A, B, C, D, E, F# (alter=1)
        assert!(key.contains_pitch(&Pitch::new(Step::G, 4)));
        assert!(key.contains_pitch(&Pitch::new(Step::D, 4)));
        assert!(key.contains_pitch(&Pitch::with_alter(Step::F, 4, 1))); // F#
        // Out-of-key: F natural
        assert!(!key.contains_pitch(&Pitch::new(Step::F, 4)));
    }

    #[test]
    fn key_display_name_c_major() {
        let key = KeySignature {
            fifths: 0,
            mode: "major".into(),
        };
        assert_eq!(key.display_name(), "C major");
    }

    #[test]
    fn key_display_name_bb_major() {
        let key = KeySignature {
            fifths: -2,
            mode: "major".into(),
        };
        assert_eq!(key.display_name(), "Bb major");
    }

    #[test]
    fn key_display_name_fsharp_minor() {
        let key = KeySignature {
            fifths: 3,
            mode: "minor".into(),
        };
        assert_eq!(key.display_name(), "F# minor");
    }

    #[test]
    fn key_tonic_d_major() {
        let key = KeySignature {
            fifths: 2,
            mode: "major".into(),
        };
        let (step, alter) = key.tonic();
        assert_eq!(step, Step::D);
        assert_eq!(alter, 0);
    }

    #[test]
    fn key_tonic_a_minor() {
        // A minor = relative minor of C major (fifths=0)
        let key = KeySignature {
            fifths: 0,
            mode: "minor".into(),
        };
        let (step, alter) = key.tonic();
        assert_eq!(step, Step::A);
        assert_eq!(alter, 0);
    }

    #[test]
    fn chord_display_major() {
        let c = ChordSymbol {
            root: "C".into(),
            kind: "major".into(),
            bass: None,
            placement: None,
            extender: false,
            harmonic_degree: None,
            harmony_function: None,
            harmony_type: None,
            chord_ref: None,
            range_end: None,
            degrees: Vec::new(),
        };
        assert_eq!(c.display_text(), "C");
    }

    #[test]
    fn chord_display_minor_seventh_slash() {
        let c = ChordSymbol {
            root: "D".into(),
            kind: "minor-seventh".into(),
            bass: Some("F".into()),
            placement: None,
            extender: false,
            harmonic_degree: None,
            harmony_function: None,
            harmony_type: None,
            chord_ref: None,
            range_end: None,
            degrees: Vec::new(),
        };
        assert_eq!(c.display_text(), "Dm7/F");
    }

    #[test]
    fn chord_display_structured_degrees() {
        let c = ChordSymbol {
            root: "C".into(),
            kind: "dominant".into(),
            bass: None,
            placement: None,
            extender: false,
            harmonic_degree: None,
            harmony_function: None,
            harmony_type: None,
            chord_ref: None,
            range_end: None,
            degrees: vec![
                ChordDegree {
                    value: 9,
                    alter: 1,
                    kind: "add".into(),
                },
                ChordDegree {
                    value: 5,
                    alter: -1,
                    kind: "alter".into(),
                },
                ChordDegree {
                    value: 3,
                    alter: 0,
                    kind: "subtract".into(),
                },
            ],
        };
        assert_eq!(c.display_text(), "C7add#9b5no3");
    }

    #[test]
    fn chord_symbol_legacy_json_defaults_degrees() {
        let chord: ChordSymbol =
            serde_json::from_str(r#"{"root":"C","kind":"major","bass":null,"placement":null}"#)
                .expect("legacy chord symbol JSON deserializes");
        assert!(chord.degrees.is_empty());
        assert!(!chord.extender);
        assert!(chord.harmonic_degree.is_none());
        assert!(chord.harmony_function.is_none());
        assert!(chord.harmony_type.is_none());
    }

    #[test]
    fn time_sig_total_beats_three_four() {
        let ts = TimeSignature {
            numerator: 3,
            denominator: 4,
        };
        assert!((ts.total_beats() - 3.0).abs() < 1e-9);
    }

    #[test]
    fn time_sig_total_beats_six_eight() {
        let ts = TimeSignature {
            numerator: 6,
            denominator: 8,
        };
        assert!((ts.total_beats() - 3.0).abs() < 1e-9);
    }

    #[test]
    fn clef_treble_middle_b4() {
        assert_eq!(Clef::Treble.middle_line_midi(), 71);
    }

    #[test]
    fn clef_bass_middle_d3() {
        assert_eq!(Clef::Bass.middle_line_midi(), 50);
    }

    #[test]
    fn clef_alto_middle_c4() {
        assert_eq!(Clef::Alto.middle_line_midi(), 60);
    }

    #[test]
    fn clef_tenor_middle_a3() {
        assert_eq!(Clef::Tenor.middle_line_midi(), 57);
    }
}