Struct Note

Source

pub struct Note {
    pub base_start_tick: u32,
    pub pitch: Pitch,
    pub duration: Duration,
    pub tie: bool,
    pub tied: bool,
    pub base_velocity: Velocity,
    pub start_tick_trimmer: Trimmer,
    pub duration_trimmer: RateTrimmer,
    pub velocity_trimmer: Trimmer,
    pub channel: Channel,
}

Expand description

Represents a musical note with timing, pitch, duration, and velocity information.

A Note is the fundamental building block of musical composition in this library. It contains all the information needed to play a single note, including:

Timing information (start tick)
Pitch (musical note and octave)
Duration (note length)
Velocity (how hard the note is played)
Tie information (for connecting notes)
Trimmers for fine-tuning timing, duration, and velocity

§Examples

use klavier_core::note::{Note, NoteBuilder};
use klavier_core::pitch::Pitch;
use klavier_core::solfa::Solfa;
use klavier_core::octave::Octave;
use klavier_core::sharp_flat::SharpFlat;
use klavier_core::duration::{Duration, Numerator, Denominator, Dots};
use klavier_core::velocity::Velocity;

// Create a note using the builder pattern
let note = NoteBuilder::default()
    .base_start_tick(0)
    .pitch(Pitch::new(Solfa::C, Octave::Oct4, SharpFlat::Null))
    .duration(Duration::new(Numerator::Whole, Denominator::from_value(4).unwrap(), Dots::ZERO))
    .base_velocity(Velocity::new(100))
    .build()
    .unwrap();

Fields§

§base_start_tick: u32

The base start tick position of the note (before any trimmer adjustments).

§pitch: Pitch

The pitch of the note (musical note, octave, and accidental).

§duration: Duration

The duration of the note (note length).

§tie: bool

Whether this note is tied to the next note (tie start).

§tied: bool

Whether this note is tied from the previous note (tie end).

§base_velocity: Velocity

The base velocity of the note (before any trimmer adjustments).

§start_tick_trimmer: Trimmer

Trimmer for adjusting the start tick position.

§duration_trimmer: RateTrimmer

Trimmer for adjusting the duration as a rate multiplier.

§velocity_trimmer: Trimmer

Trimmer for adjusting the velocity.

§channel: Channel

The MIDI channel for this note.

Implementations§

Source §

impl Note

Source

pub fn start_tick(&self) -> u32

Returns the actual start tick of the note after applying the start tick trimmer.

This method calculates the final start tick by adding the base start tick and the trimmer adjustment. If the result would be negative, it returns 0.

§Returns

The actual start tick position (always >= 0).

Source

pub fn tick_len(&self) -> u32

Returns the actual tick length of the note after applying the duration trimmer.

This method calculates the final duration by applying the rate trimmer to the base duration’s tick length.

§Returns

The actual tick length of the note.

Source

pub fn up_score_offset(&self) -> Result<Self, PitchError>

Creates a new note with the pitch raised by one semitone.

§Returns

Ok(Note) - A new note with the pitch raised by one semitone.
Err(PitchError) - If the pitch is already at the maximum value.

§Examples

let note = Note {
    pitch: Pitch::new(Solfa::C, Octave::Oct4, SharpFlat::Null),
    ..Default::default()
};
let higher_note = note.up_score_offset().unwrap();
assert_eq!(higher_note.pitch, Pitch::new(Solfa::D, Octave::Oct4, SharpFlat::Null));

Source

pub fn down_score_offset(&self) -> Result<Self, PitchError>

Creates a new note with the pitch lowered by one semitone.

§Returns

Ok(Note) - A new note with the pitch lowered by one semitone.
Err(PitchError) - If the pitch is already at the minimum value.

Source

pub fn with_duration(&self, d: Duration) -> Self

Creates a new note with the specified duration.

§Arguments

d - The new duration for the note.

§Returns

A new note with the specified duration.

Source

pub fn with_duration_numerator(&self, numerator: Numerator) -> Self

Creates a new note with the specified duration numerator.

This method only updates the duration if the numerator is different from the current one, optimizing for cases where no change is needed.

§Arguments

numerator - The new numerator for the note’s duration.

§Returns

A new note with the specified duration numerator.

Source

pub fn with_tick_added( &self, tick_delta: i32, is_trim: bool, ) -> Result<Self, TickError>

Creates a new note with the start tick adjusted by the specified delta.

§Arguments

tick_delta - The amount to add to the start tick (can be negative).
is_trim - If true, adjusts the trimmer; if false, adjusts the base start tick.

§Returns

Ok(Note) - A new note with the adjusted start tick.
Err(TickError::Minus) - If the resulting tick would be negative.

§Examples

let note = Note {
    base_start_tick: 100,
    ..Default::default()
};
let later_note = note.with_tick_added(50, false).unwrap();
assert_eq!(later_note.base_start_tick, 150);

Source

pub fn drag(&self, tick_delta: i32, score_offset_delta: i32) -> Self

Creates a new note with both timing and pitch adjusted (for drag operations).

This method is typically used for interactive editing where a note is being dragged both horizontally (time) and vertically (pitch).

§Arguments

tick_delta - The amount to add to the start tick.
score_offset_delta - The amount to adjust the pitch (in semitones).

§Returns

A new note with adjusted timing and pitch.

§Panics

Panics if the pitch adjustment would result in an invalid pitch.

Source

pub fn add_dots(&self, dots_to_add: i32) -> Result<Self, InvalidDot>

Creates a new note with additional dots added to the duration.

Dots extend the duration of a note. Each dot adds half the value of the previous duration component.

§Arguments

dots_to_add - The number of dots to add (can be negative to remove dots).

§Returns

Ok(Note) - A new note with the adjusted dot count.
Err(InvalidDot) - If the resulting dot count is outside the valid range.

§Examples

let note = Note {
    duration: Duration::new(Numerator::Whole, Denominator::from_value(4).unwrap(), Dots::ZERO),
    ..Default::default()
};
let dotted_note = note.add_dots(1).unwrap();
assert_eq!(dotted_note.duration.dots, Dots::ONE);

Source

pub fn toggle_sharp(&self) -> Result<Self, PitchError>

Creates a new note with the sharp accidental toggled.

If the note has no accidental, it becomes sharp. If the note is already sharp, it becomes natural.

§Returns

Ok(Note) - A new note with the sharp toggled.
Err(PitchError) - If the operation would result in an invalid pitch.

Source

pub fn toggle_flat(&self) -> Result<Self, PitchError>

Creates a new note with the flat accidental toggled.

If the note has no accidental, it becomes flat. If the note is already flat, it becomes natural.

§Returns

Ok(Note) - A new note with the flat toggled.
Err(PitchError) - If the operation would result in an invalid pitch.

Source

pub fn toggle_natural(&self) -> Result<Self, PitchError>

Creates a new note with the natural accidental toggled.

If the note has an accidental (sharp or flat), it becomes natural. If the note is already natural, this may have no effect depending on the key signature.