sim-lib-music-serial 0.1.0

Immutable serial plans with stable row and event identity, explicit provenance, and validated partial temporal order.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! Canonical music-core rendering for serial realizations.

use std::collections::BTreeMap;

use sim_lib_music_core::{
    AmbiguousConversionPolicy, Music, ObjectId, PianoRoll, Score, ScoreForm, ScoreFormKind, Staff,
    StaffNote, StaffVoice, convert_score,
};

use crate::{SerialRealization, StrictRealizationError};

/// Score metadata used when wrapping a rendered serial realization.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SerialRenderOptions {
    /// Tempo in beats per minute.
    pub tempo_bpm: u32,
    /// Time signature numerator and denominator.
    pub time_signature: (u8, u8),
    /// Optional key label.
    pub key: Option<String>,
}

impl Default for SerialRenderOptions {
    fn default() -> Self {
        Self {
            tempo_bpm: 60,
            time_signature: (4, 4),
            key: None,
        }
    }
}

/// Renders one realization to the canonical identity-bearing [`Staff`].
pub fn render_serial_staff(
    realization: &SerialRealization,
) -> Result<Staff, StrictRealizationError> {
    let mut voices = BTreeMap::<_, StaffVoice>::new();
    for event in realization.events() {
        let planned = realization
            .plan()
            .event(&event.event_id)
            .expect("realization events must reference plan events");
        let voice = voices
            .entry(planned.voice.clone())
            .or_insert_with(|| StaffVoice {
                id: planned.voice.clone(),
                name: planned.voice.as_str().to_owned(),
                duration: event.onset + event.duration,
                notes: Vec::new(),
            });
        voice.duration = voice.duration.max(event.onset + event.duration);
    }
    for note in realization.notes() {
        let voice = voices
            .entry(note.voice.clone())
            .or_insert_with(|| StaffVoice {
                id: note.voice.clone(),
                name: note.voice.as_str().to_owned(),
                duration: note.onset + note.note.duration,
                notes: Vec::new(),
            });
        voice.duration = voice.duration.max(note.onset + note.note.duration);
        voice.notes.push(StaffNote {
            voice_id: note.voice.clone(),
            note_id: ObjectId::new(format!(
                "serial-note/{}/{}/{}",
                note.event_id, note.note_index, note.origin.source_ordinal.ordinal
            ))
            .map_err(|error| StrictRealizationError::MusicCore(error.to_string()))?,
            event_id: ObjectId::new(format!(
                "serial-event/{}/{}",
                note.event_id, note.note_index
            ))
            .map_err(|error| StrictRealizationError::MusicCore(error.to_string()))?,
            onset: note.onset,
            note: note.note.clone(),
        });
    }
    Staff::new(voices.into_values().collect())
        .map_err(|error| StrictRealizationError::MusicCore(error.to_string()))
}

/// Renders one realization to the canonical [`PianoRoll`] through [`Staff`].
pub fn render_serial_piano_roll(
    realization: &SerialRealization,
) -> Result<PianoRoll, StrictRealizationError> {
    let staff = render_serial_staff(realization)?;
    let report = convert_score(
        &ScoreForm::Staff(staff),
        ScoreFormKind::PianoRoll,
        AmbiguousConversionPolicy::Reject,
    )
    .map_err(|error| StrictRealizationError::MusicCore(error.to_string()))?;
    let ScoreForm::PianoRoll(roll) = report.value else {
        unreachable!("piano-roll conversion must return a piano roll");
    };
    Ok(roll)
}

/// Wraps the canonical piano roll in a music-core [`Score`].
pub fn render_serial_score(
    realization: &SerialRealization,
    options: &SerialRenderOptions,
) -> Result<Score, StrictRealizationError> {
    Score::new(
        options.tempo_bpm,
        options.time_signature,
        options.key.clone(),
        Music::PianoRoll(render_serial_piano_roll(realization)?),
    )
    .map_err(|error| StrictRealizationError::MusicCore(error.to_string()))
}