Struct ScoreEngine 

pub struct ScoreEngine {
    pub score: Score,
    pub commands: CommandStack,
    pub version: u64,
    pub clipboard: Option<Vec<Note>>,
    /* private fields */
}

Fields

score: Score

commands: CommandStack

version: u64

clipboard: Option<Vec<Note>>

Implementations

impl ScoreEngine

pub fn new() -> Self

pub fn apply(&mut self, cmd: Command) -> Result<ChangeHint, Error>

pub fn undo(&mut self) -> Result<ChangeHint, Error>

pub fn redo(&mut self) -> Result<ChangeHint, Error>

pub fn batch_apply(&mut self, cmds: Vec<Command>) -> Result<ChangeHint, Error>

Apply multiple commands as a single undo entry.

pub fn batch_apply_labeled( &mut self, cmds: Vec<Command>, label: &str, ) -> Result<ChangeHint, Error>

Apply a batch of commands as a single undo entry with an explicit label.

The label appears as the command_key in undo/redo UI (e.g. "ApplyAI").

pub fn undo_label(&self) -> Option<String>

Label of the next undoable command (for “Undo: Add Note” menu items).

pub fn redo_label(&self) -> Option<String>

Label of the next redoable command (for “Redo: Add Note” menu items).

pub fn undo_key(&self) -> Option<String>

i18n key of the next undoable command (e.g. "SetTempo").

pub fn redo_key(&self) -> Option<String>

i18n key of the next redoable command.

pub fn replace_score(&mut self, score: Score)

Replace a score that has already crossed a validation boundary.

For deserialized or host-provided data, prefer ScoreEngine::try_replace_score.

pub fn try_replace_score(&mut self, score: Score) -> Result<(), Error>

Replace the score after checking its structural invariants.

Unlike ScoreEngine::replace_score, this is the safe boundary for deserialized or host-provided scores. On failure, the engine and its history remain unchanged.

pub fn export_history(&self) -> EngineHistory

Export the command history for serialization (crash recovery, AI replay).

The returned EngineHistory can be stored as JSON and later restored with ScoreEngine::from_history.

pub fn from_history(history: EngineHistory) -> Result<Self, Error>

Reconstruct an engine from a previously exported EngineHistory.

Replays all commands against history.initial_score in order. Returns an error if any command fails (e.g. index out of bounds due to stale data).

pub fn from_history_on_base( history: EngineHistory, base: Score, ) -> Result<Self, Error>

Reconstruct history only when its declared base matches the supplied collaboration base.

This prevents a stale command log from being replayed onto an unrelated score. Callers can use EngineHistory::base_matches for a non-mutating preflight check first.

pub fn append_history_extension( &mut self, incoming: &EngineHistory, ) -> Result<usize, Error>

Append a remote history only when it strictly extends this engine’s command log.

The complete incoming history is replayed into a candidate engine before replacement. Diverged or base-mismatched histories, or replay failures, leave this engine unchanged.

pub fn copy_voice( &mut self, part_index: usize, staff_index: usize, measure_index: usize, voice_index: usize, ) -> Result<(), Error>

pub fn paste_voice( &mut self, part_index: usize, staff_index: usize, measure_index: usize, voice_index: usize, ) -> Result<ChangeHint, Error>

pub fn copy_range( &mut self, start: NoteAddr, end: NoteAddr, ) -> Result<(), Error>

Copy a range of measures from a single voice into the range clipboard.

The range is inclusive: all measures from start.measure to end.measure. start and end must share the same part, staff, and voice.

pub fn paste_range(&mut self, target: NoteAddr) -> Result<ChangeHint, Error>

Paste the range clipboard starting at target, creating an undo-able command.

The voice index from the original copy_range call is used; target.voice is ignored.

pub fn paste_score_fragment( &mut self, fragment: ScoreFragment, target: NoteAddr, ) -> Result<ChangeHint, Error>

Paste a versioned multi-lane score fragment at target as one undoable operation. Relative fragment addresses are resolved from target.

pub fn paste_score_fragment_with_policy( &mut self, fragment: ScoreFragment, target: NoteAddr, policy: ScoreFragmentPastePolicy, ) -> Result<ChangeHint, Error>

Paste a versioned multi-lane fragment with an explicit collision policy.

pub fn exchange_voices( &mut self, part_index: usize, staff_index: usize, start_measure: usize, end_measure: usize, first_voice: usize, second_voice: usize, ) -> Result<ChangeHint, Error>

Exchange two voices over an inclusive measure range as one undoable operation, retaining source MusicXML voice numbers and typed spans.

pub fn implode_staves( &mut self, part_index: usize, source_staves: Vec<usize>, target_staff: usize, start_measure: usize, end_measure: usize, ) -> Result<ChangeHint, Error>

Move compatible primary staff voices into the voices of target_staff as one undoable, lossless structural transformation.

pub fn explode_voices( &mut self, part_index: usize, source_staff: usize, target_staves: Vec<usize>, start_measure: usize, end_measure: usize, ) -> Result<ChangeHint, Error>

Move voices from source_staff to the primary voices of target_staves as one undoable structural transformation.

pub fn explode_chord_pitches( &mut self, part_index: usize, source_staff: usize, target_staves: Vec<usize>, start_measure: usize, end_measure: usize, ) -> Result<ChangeHint, Error>

Split pitches in primary-voice chords across compatible staves while retaining all chord-attached notation on the first source pitch.

pub fn scale_voice_range( &mut self, part_index: usize, staff_index: usize, voice: usize, start_measure: usize, end_measure: usize, scale: DurationScale, ) -> Result<ChangeHint, Error>

Scale every note in a voice range by one half or double while keeping each affected measure rhythmically complete.

pub fn toggle_slur( &mut self, start: NoteAddr, end: NoteAddr, ) -> Result<ChangeHint, Error>

Toggle the slur between two notes (undo-able).

pub fn add_staff( &mut self, part_index: usize, clef: Clef, ) -> Result<ChangeHint, Error>

Add a staff to a part (undo-able).

pub fn delete_staff( &mut self, part_index: usize, staff_index: usize, ) -> Result<ChangeHint, Error>

Remove a staff from a part (undo-able). Fails if it is the last remaining staff.

pub fn set_stem( &mut self, addr: NoteAddr, stem_up: Option<bool>, ) -> Result<ChangeHint, Error>

Set or clear the stem direction on an existing note (undo-able).

stem_up: None = auto, Some(true) = up, Some(false) = down.

pub fn set_note_placement( &mut self, addr: NoteAddr, offset_x: Option<f64>, offset_y: Option<f64>, relative_x: Option<f64>, relative_y: Option<f64>, ) -> Result<ChangeHint, Error>

Set or clear MusicXML-compatible note placement offsets in tenths (undo-able).

pub fn set_duration( &mut self, addr: NoteAddr, duration: Duration, dot_count: u8, ) -> Result<ChangeHint, Error>

Set the duration and dot count on an existing note (undo-able).

pub fn set_arpeggio( &mut self, addr: NoteAddr, direction: Option<bool>, ) -> Result<ChangeHint, Error>

Set or clear the arpeggio direction on an existing note (undo-able).

pub fn set_note_head( &mut self, addr: NoteAddr, note_head: NoteHead, ) -> Result<ChangeHint, Error>

Set the note head shape on an existing note (undo-able).

pub fn set_part_group( &mut self, group: Option<PartGroup>, ) -> Result<ChangeHint, Error>

Add or replace a part group (undo-able). Pass None to clear all groups.

pub fn toggle_trill_line( &mut self, start: NoteAddr, end: NoteAddr, ) -> Result<ChangeHint, Error>

Toggle a trill line span between two notes (undo-able).

pub fn set_cue( &mut self, addr: NoteAddr, is_cue: bool, ) -> Result<ChangeHint, Error>

Set or clear the cue flag on a note (undo-able). Cue notes have zero beats.

pub fn set_unpitched( &mut self, addr: NoteAddr, is_unpitched: bool, ) -> Result<ChangeHint, Error>

Set or clear the unpitched flag while retaining display placement.

pub fn set_instrument_id( &mut self, addr: NoteAddr, instrument_id: Option<String>, ) -> Result<ChangeHint, Error>

Set or clear a source instrument identifier attached to a note.

pub fn set_tuplet( &mut self, addr: NoteAddr, tuplet: Option<TupletInfo>, ) -> Result<ChangeHint, Error>

Set or clear the tuplet on an existing note (undo-able).

pub fn respell_score(&mut self, prefer_flat: bool) -> Result<ChangeHint, Error>

Respell all pitches in the score (undo-able).

pub fn respell_score_to_key(&mut self) -> Result<ChangeHint, Error>

Respell all pitches to match the score’s key signature (undo-able).

pub fn respell_staff_region( &mut self, part_index: usize, staff_index: usize, start_measure: usize, end_measure: usize, policy: RespellPolicy, ) -> Result<ChangeHint, Error>

Respell one staff’s measure range start_measure..end_measure (undo-able).

pub fn begin_slur(&mut self, start: NoteAddr) -> Result<(), Error>

Begin a two-step slur: record start and wait for end_slur.

Returns an error if start does not point to a valid note.

pub fn end_slur(&mut self, end: NoteAddr) -> Result<ChangeHint, Error>

Complete the slur started by begin_slur (undo-able).

Returns Error::InvalidCommand if begin_slur has not been called.

Trait Implementations

impl Default for ScoreEngine

fn default() -> Self

Returns the “default value” for a type.