Struct tune::mts::SingleNoteTuningChangeMessage

pub struct SingleNoteTuningChangeMessage { /* private fields */ }

Retunes one or multiple MIDI notes using the Single Note Tuning Change message format.

Implementations

impl SingleNoteTuningChangeMessage

pub fn from_tuning(
    options: &SingleNoteTuningChangeOptions,
    tuning: impl KeyboardMapping<PianoKey>,
    keys: impl IntoIterator<Item = PianoKey>
) -> Result<Self, SingleNoteTuningChangeError>

Creates a SingleNoteTuningChangeMessage from the provided tuning and keys.

Examples

let scl = Scl::builder()
    .push_ratio(Ratio::octave().divided_into_equal_steps(7))
    .build()
    .unwrap();
let kbm = KbmRoot::from(NoteLetter::D.in_octave(4)).to_kbm();

let tuning_message = SingleNoteTuningChangeMessage::from_tuning(
    &Default::default(),
    (scl, kbm),
    (21..109).map(PianoKey::from_midi_number),
)
.unwrap();

assert_eq!(tuning_message.sysex_bytes().count(), 1);
assert_eq!(tuning_message.out_of_range_notes().len(), 13);

pub fn from_tuning_changes(
    options: &SingleNoteTuningChangeOptions,
    tuning_changes: impl IntoIterator<Item = SingleNoteTuningChange>
) -> Result<Self, SingleNoteTuningChangeError>

Creates a SingleNoteTuningChangeMessage from the provided tuning_changes.

Examples

let key = NoteLetter::A.in_octave(4).as_piano_key();

let good = SingleNoteTuningChange { key, target_pitch: Pitch::from_hz(445.0) };
let too_low = SingleNoteTuningChange { key, target_pitch: Pitch::from_hz(1.0) };
let too_high = SingleNoteTuningChange { key, target_pitch: Pitch::from_hz(100000.0) };

let tuning_message = SingleNoteTuningChangeMessage::from_tuning_changes(
    &Default::default(), [good, too_low, too_high]
)
.unwrap();

assert_eq!(tuning_message.sysex_bytes().count(), 1);
assert_eq!(tuning_message.out_of_range_notes(), [too_low, too_high]);

pub fn sysex_bytes(&self) -> impl Iterator<Item = &[u8]>

Returns the tuning message conforming to the MIDI tuning standard.

If less than 128 notes are retuned the iterator yields a single tuning message. If the number of retuned notes is 128 two messages with a batch of 64 notes are yielded. If the number of retuned notes is 0 no message is yielded.

Examples

let create_tuning_message_with_num_changes = |num_changes| {
    let tuning_changes = (0..num_changes).map(|midi_number| {
        SingleNoteTuningChange {
            key: PianoKey::from_midi_number(midi_number),
            target_pitch: Note::from_midi_number(midi_number).pitch(),
        }
    });

    SingleNoteTuningChangeMessage::from_tuning_changes(
        &Default::default(),
        tuning_changes,
    )
    .unwrap()
};

assert_eq!(create_tuning_message_with_num_changes(0).sysex_bytes().count(), 0);
assert_eq!(create_tuning_message_with_num_changes(127).sysex_bytes().count(), 1);
assert_eq!(create_tuning_message_with_num_changes(128).sysex_bytes().count(), 2);

pub fn out_of_range_notes(&self) -> &[SingleNoteTuningChange]

Return notes whose target pitch is not representable by the tuning message.

Trait Implementations

impl Clone for SingleNoteTuningChangeMessage

fn clone(&self) -> SingleNoteTuningChangeMessage

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SingleNoteTuningChangeMessage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.