Struct Pitch 

pub struct Pitch { /* private fields */ }

A musical pitch with spelling, octave, accidental and optional microtone.

Implementations

impl Pitch

pub fn name_in_key_signature(&self, altered_pitches: &[Pitch]) -> bool

music21’s _nameInKeySignature: whether one of a key signature’s altered pitches has this pitch’s step and the same accidental. A pitch with no accidental object never matches.

pub fn step_in_key_signature(&self, altered_pitches: &[Pitch]) -> bool

music21’s _stepInKeySignature: whether a key signature alters this pitch’s step at all, whatever the accidental.

pub fn update_accidental_display( &mut self, options: &AccidentalDisplayOptions<'_>, )

Decides whether this pitch’s accidental should be shown, given the pitches before it, and records the answer as the accidental’s display_status, adding a natural where a cautionary one is called for: music21’s updateAccidentalDisplay, with the same rules for repeats, octaves, ties, key signatures and simultaneities.

impl Pitch

pub fn simplify_enharmonic(&self, most_common: bool) -> Result<Pitch>

Returns a simpler enharmonic spelling of this pitch.

When most_common is true, common spellings such as E- are preferred over less common equivalents such as D#, following music21’s Pitch.simplifyEnharmonic behavior.

pub fn simplify_enharmonic_in_place(&mut self, most_common: bool) -> Result<()>

Simplifies this pitch’s enharmonic spelling in place.

pub fn get_higher_enharmonic(&self) -> Result<Pitch>

Returns the next higher enharmonic spelling.

pub fn get_higher_enharmonic_in_place(&mut self) -> Result<()>

Replaces this pitch with its next higher enharmonic spelling.

pub fn get_lower_enharmonic(&self) -> Result<Pitch>

Returns the next lower enharmonic spelling.

pub fn get_lower_enharmonic_in_place(&mut self) -> Result<()>

Replaces this pitch with its next lower enharmonic spelling.

pub fn respelled_for(&self, signature: &KeySignature) -> Result<Pitch>

Returns the enharmonic music21’s getEnharmonic picks: sharps respell upward and flats downward, and a natural goes down for C, D and G and up for the rest, so C is B-sharp and E is F-flat. This pitch respelled to agree with a key signature, when the two disagree about the same sounding note.

This is the rule music21 applies after transposing by a number of semitones: a G- in a key that writes an F# is written F#, and the other way round, because a chromatic step says how far to move and not how to spell what it lands on. A pitch with no accidental, or one the signature does not alter, is left as it is.

pub fn get_enharmonic(&self) -> Result<Pitch>

The next enharmonic spelling of this pitch: music21’s getEnharmonic.

A sharpened pitch respells on the letter above and a flattened one on the letter below; a natural takes whichever direction its letter has room for, so C answers B#.

pub fn is_enharmonic(&self, other: &Pitch) -> bool

Returns whether the two pitches sound the same. Without an octave on either side only the pitch class is compared.

pub fn all_common_enharmonics(&self, alter_limit: IntegerType) -> Vec<Pitch>

Returns the other spellings of this pitch with at most alter_limit sharps or flats, simplest first, as music21’s getAllCommonEnharmonics lists them.

pub fn transpose_below_target( &self, target: &Pitch, minimize: bool, ) -> Result<Pitch>

Returns this pitch moved down by octaves until it is at or below target. With minimize it is then raised back to within an octave.

pub fn transpose_above_target( &self, target: &Pitch, minimize: bool, ) -> Result<Pitch>

Returns this pitch moved up by octaves until it is at or above target. With minimize it is then lowered back to within an octave.

impl Pitch

pub fn convert_quarter_tones_to_microtones(&self) -> Result<Pitch>

Returns the pitch with any quarter-tone accidental folded into the microtone: music21’s convertQuarterTonesToMicrotones, so a half-sharp C becomes C with +50c and a one-and-a-half-sharp D becomes D-sharp with +50c. Other accidentals are untouched.

pub fn convert_microtones_to_quarter_tones(&self) -> Result<Pitch>

Returns the pitch with its microtone rounded into the nearest quarter-tone accidental and the remainder kept as a microtone: music21’s convertMicrotonesToQuarterTones, so C with +30c becomes a half-sharp C with -20c and C with +150c becomes C-sharp with +50c.

pub fn harmonic_and_fundamental_from_pitch( &self, fundamental: &Pitch, ) -> Result<(u32, Pitch)>

Returns which harmonic of fundamental this pitch is closest to, and the fundamental retuned by the difference so that the harmonic lands exactly here: music21’s harmonicAndFundamentalFromPitch, so E5 over C2 is the tenth harmonic of C2 raised 14 cents.

pub fn harmonic_and_fundamental_string_from_pitch( &self, fundamental: &Pitch, ) -> Result<String>

Returns Self::harmonic_and_fundamental_from_pitch in music21’s notation, 10thH/C2(+14c).

pub fn harmonic(&self, number: u32) -> Result<Pitch>

Returns the numberth harmonic of this pitch as a fundamental, spelled to the nearest twelve-tone pitch with the remainder as a microtone and this pitch recorded as its fundamental. The first harmonic is the pitch itself.

pub fn harmonic_from_fundamental( &self, fundamental: &Pitch, ) -> Result<(u32, FloatType)>

Returns which harmonic of fundamental this pitch is closest to, and the distance to that harmonic in cents: negative when this pitch lies above the harmonic, positive when below.

pub fn harmonic_string(&self, fundamental: Option<&Pitch>) -> Result<String>

Describes this pitch as a harmonic of fundamental, or of its own fundamental when none is given, in music21’s notation: "3rdH(-2c)/C2".

impl Pitch

pub fn german(&self) -> Result<String>

Returns the German name, where B is H, B- is B, sharps add is and flats add es or s. Errors on a microtonal accidental.

pub fn italian(&self) -> Result<String>

Returns the Italian solfège name, such as "do diesis" or "si doppio bemolle". Errors on a microtonal accidental or more than four sharps or flats.

pub fn french(&self) -> Result<String>

Returns the French solfège name, such as "ré bémol" or "fa double dièse". Errors on a microtonal accidental or more than four sharps or flats.

pub fn spanish(&self) -> Result<String>

Returns the Spanish solfège name, such as "re bemol" or "fa doble sostenido". Errors on a microtonal accidental or more than four sharps or flats.

pub fn unicode_name(&self) -> String

Returns the name with the accidental as a Unicode symbol, such as "C♯" or "G𝄫".

pub fn full_name(&self) -> String

Returns music21’s fullName: the step, the accidental’s full name, the octave and any microtone, as in E-flat in octave 4 (+20c).

pub fn name_with_octave_and_microtone(&self) -> String

Returns the name with its octave and, when it has one that is not zero, its microtone: music21’s str(Pitch), A4(+20c).

pub fn unicode_name_with_octave(&self) -> String

Returns Self::unicode_name followed by the octave when one is set.

impl Pitch

pub fn from_options(options: PitchOptions) -> Result<Self>

Builds a pitch from PitchOptions.

This is the port of music21’s keyword-argument Pitch.__init__: a name wins over an explicit step, and octave, accidental, microtone, pitch_class, midi and ps are applied afterwards in that order.

pub fn builder() -> PitchOptions

Creates a PitchOptions builder.

pub fn from_name(name: impl Into<String>) -> Result<Self>

Builds a pitch from a name such as "C#4" or "E-".

pub fn from_number(number: FloatType) -> Result<Self>

Builds a pitch from a pitch-space number.

pub fn from_step(step: char) -> Result<Self>

Builds a pitch from a diatonic step.

pub fn from_name_and_octave( name: impl Into<String>, octave: IntegerType, ) -> Result<Self>

Builds a pitch from a pitch name and explicit octave.

pub fn from_pitch_class( pitch_class: impl Into<PitchClassSpecifier>, ) -> Result<Self>

Builds a pitch from a pitch class.

pub fn from_midi(midi: IntegerType) -> Result<Self>

Builds a pitch from a MIDI note number.

pub fn from_pitch_space(ps: FloatType) -> Result<Self>

Builds a pitch from a pitch-space value.

pub fn name_with_octave(&self) -> String

Returns the pitch name with the octave suffix when one is set.

pub fn name(&self) -> String

Returns the pitch name without octave, such as "F#" or "B-".

pub fn alter(&self) -> FloatType

Returns the total semitone alteration from the natural step.

pub fn accidental(&self) -> &Accidental

Returns this pitch’s accidental object.

Unlike Python music21, this crate stores an explicit natural accidental for natural pitches.

pub fn microtone(&self) -> Option<&Microtone>

Returns this pitch’s microtone adjustment, when present.

pub fn pitch_class(&self) -> PitchClass

Returns this pitch’s normalized pitch class.

pub fn set_octave(&mut self, octave: Octave)

Puts this pitch in an octave, or in none at all: music21’s settable octave, which only moves the pitch and does not respell it.

pub fn transpose(&self, interval: &Interval) -> Result<Pitch>

Returns this pitch transposed by the interval, as music21’s Pitch.transpose does: a pitch whose spelling was inferred from a number is respelled to its most common enharmonic afterwards, one spelled explicitly keeps its accidentals.

pub fn ps(&self) -> FloatType

Returns the pitch-space value for this pitch.

pub fn pitch_space(&self) -> FloatType

Returns the pitch-space value for this pitch.

pub fn midi(&self) -> IntegerType

Returns the MIDI note number the way music21’s midi reports it: the pitch space rounded half up, then folded into 0 to 127 by octaves, so a pitch above the MIDI range reports its highest in-range octave and one below it its lowest.

pub fn frequency_hz(&self) -> FloatType

Returns this pitch’s twelve-tone equal-temperament frequency in hertz.

pub fn frequency_hz_in(&self, tuning_system: TuningSystem) -> FloatType

Returns this pitch’s frequency in hertz for a supported tuning system.

The pitch-space value is used as the tuning-system degree index, so this is most musically meaningful for twelve-tone systems.

pub fn set_accidental(&mut self, accidental: Option<Accidental>)

Sets or removes the accidental the way music21’s accidental setter does: None leaves the pitch with no accidental object, which Self::accidental still reports as a natural.

pub fn set_accidental_alter(&mut self, alter: FloatType) -> Result<()>

Sets the accidental from a semitone alteration the way music21’s setter does with a float: the part that is a quarter-tone or larger becomes the accidental and the rest a microtone, so -1.5 is a flat with fifty cents down.

pub fn has_accidental(&self) -> bool

Whether the pitch carries an accidental object at all. music21 keeps none on a pitch spelled with a bare letter (D) or built from a number that needs none, and an explicit natural (Dn) is one, so D and Dn differ here while Self::accidental answers a natural for both.

pub fn spelling_is_inferred(&self) -> bool

music21’s spellingIsInferred: whether the crate chose the spelling rather than being told it. A pitch built from a number, a MIDI value, a pitch class or a frequency has an inferred spelling, and only such a pitch is respelled by a transposition.

pub fn set_spelling_is_inferred(&mut self, inferred: bool)

Says whether the spelling was chosen or given.

pub fn explicit_accidental(&self) -> Option<&Accidental>

The accidental object, if the pitch carries one; see Self::has_accidental.

pub fn explicit_accidental_mut(&mut self) -> Option<&mut Accidental>

The accidental object for editing in place, if the pitch carries one.

pub fn set_microtone_cents(&mut self, cents: FloatType) -> Result<()>

Sets the microtone from a cent shift, removing it when the shift is zero.

pub fn fundamental(&self) -> Option<&Pitch>

Returns the fundamental this pitch was built against, when one was set.

pub fn implicit_octave(&self) -> IntegerType

Returns the octave, or music21’s default of 4 when none is set.

This is what music21’s .octave answers, which is always an int. Self::octave keeps the Option, which is music21’s own _octave and says strictly more; Self::octave_is_implicit tells the two apart.

pub fn octave_is_implicit(&self) -> bool

Whether this pitch was never given an octave, so it stands for its pitch class in any octave: music21’s octaveIsImplicit.

Such a pitch prints without an octave number and reports the default octave from Self::implicit_octave.

pub fn set_octave_is_implicit(&mut self, implicit: bool)

Makes the octave implicit or explicit: the setter of music21’s octaveIsImplicit.

Making it explicit puts the pitch in the default octave, as music21 does; making it implicit takes the octave away. Setting it to what it already is does nothing.

pub fn pitch_class_string(&self) -> String

Returns the pitch class as music21’s pitchClassString, one character with A and B for ten and eleven. Like music21’s integer pitchClass it rounds a microtone away with Python’s round-half-to-even, so C with +20c is 0 where Self::pitch_class would say 0.2, and a half-sharp C is 0 even though its MIDI number rounds up to 61.

pub fn cent_shift_from_midi(&self) -> IntegerType

Returns how many cents the pitch sits from the nearest MIDI note, rounded to a whole cent: music21’s getCentShiftFromMidi, so a half-sharp C reads -50 because it rounds up to C-sharp.

pub fn from_frequency(hertz: FloatType) -> Result<Self>

Builds a pitch from a frequency in hertz, spelled in twelve-tone equal temperament at A4 = 440 with any remainder as a microtone.

pub fn diatonic_note_number(&self) -> IntegerType

Returns music21’s diatonicNoteNum: the staff position counting C0 as 1, with the implicit octave standing in when none is set.

pub fn is_twelve_tone(&self) -> bool

Returns whether this pitch lies on the twelve-tone grid: no quarter tone accidental and no microtone.

pub fn octave(&self) -> Octave

Returns the stored octave.

Returns None when the pitch was created without an explicit octave, such as Pitch::from_name("C"). In calculations, octave-less pitches use the library default octave.

Trait Implementations

impl Clone for Pitch

fn clone(&self) -> Pitch

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Pitch

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

Formats the value using the given formatter.

impl Default for Pitch

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Pitch

Available on crate feature serde only.

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Pitch

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

Formats the value using the given formatter.

impl From<&Pitch> for Note

fn from(value: &Pitch) -> Self

Converts to this type from the input type.

impl From<Pitch> for Note

fn from(value: Pitch) -> Self

Converts to this type from the input type.

impl FromStr for Pitch

type Err = Error

The associated error which can be returned from parsing.

fn from_str(value: &str) -> Result<Self>

Parses a string s to return a value of this type.

impl IntoNote for Pitch

fn try_into_note(self) -> Result<Note>

Converts the value into a note.

const FROM_INTEGER_PITCH: bool = false

Whether this value came from an integer pitch class or MIDI-like number.

impl IntoNote for &Pitch

fn try_into_note(self) -> Result<Note>

Converts the value into a note.

const FROM_INTEGER_PITCH: bool = false

Whether this value came from an integer pitch class or MIDI-like number.

impl PartialEq for Pitch

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Pitch

Available on crate feature serde only.

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&Pitch> for Pitch

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Pitch) -> Result<Self>

Performs the conversion.

impl TryFrom<&str> for Pitch

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self>

Performs the conversion.

impl TryFrom<String> for Pitch

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self>

Performs the conversion.

impl TryFrom<f64> for Pitch

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: FloatType) -> Result<Self>

Performs the conversion.

impl TryFrom<i32> for Pitch

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: IntegerType) -> Result<Self>

Performs the conversion.