Struct Chord 

pub struct Chord { /* private fields */ }

A collection of notes analyzed as one vertical sonority.

Chord accepts several note-like inputs, including whitespace-separated pitch names, slices of pitches or notes, MIDI pitch numbers, vectors, and None for an empty chord.

Implementations

impl Chord

pub fn new<T>(notes: T) -> Result<Self>

where T: IntoNotes + Clone,

Builds a chord from any supported note collection.

Empty inputs are valid: pass "", an empty vector or slice, or Option::<&str>::None to construct an empty chord.

pub fn empty() -> Result<Self>

Builds an empty chord.

pub fn known_chord_types() -> Vec<KnownChordType>

Returns the unpitched chord types known to the music21-derived table.

pub fn pitched_common_name(&self) -> String

Returns the primary music21-style common name with a pitch prefix.

pub fn pitched_common_names(&self) -> Vec<String>

Returns every known music21-style common name with pitch prefixes.

Most chords have a single common name, while some Forte-table entries have aliases. This method exposes all of them in table order.

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

Returns the preferred chord symbol, when available.

This is separate from Self::pitched_common_name: common names follow the music21/Forte tables, while chord symbols use music21-style figures such as Cmaj7, F#m7b5, or Ddom7dim5/CaddA,E-.

pub fn chord_symbols(&self) -> Vec<String>

Returns ranked chord symbols for this pitch-class set.

Empty and microtonal chords return no symbols because this notation layer assumes twelve-tone equal-tempered pitch classes.

pub fn chord_symbol_with_root( &self, root: impl Into<PitchClassSpecifier>, ) -> Result<Option<String>>

Returns the preferred chord symbol using an explicit root.

This is useful for pitch-class sets and browser tables where the caller already knows the harmonic spelling anchor and does not want an inversion/root inference pass to choose another chord member. String roots are parsed as pitch names; numeric roots are parsed as pitch classes, so use numbers for pitch-class-only values such as 10 or 11.

pub fn chord_symbols_with_root( &self, root: impl Into<PitchClassSpecifier>, ) -> Result<Vec<String>>

Returns ranked chord symbols using an explicit root.

Empty, microtonal, and rootless-with-respect-to-the-given-root chords return no symbols. Non-integer roots are rejected because chord symbols are generated in twelve-tone pitch-class space.

pub fn guitar_fingering(&self) -> Option<GuitarFingering>

Returns a suggested standard-tuning guitar fingering.

The fingering is a compact voicing on six-string guitar in E2-A2-D3-G3-B3-E4 tuning. It prefers shapes that cover all chord pitches, place the root in the bass when possible, avoid internal muted strings, and stay within a small fret span.

pub fn guitar_fingering_with_tuning( &self, tuning: &GuitarTuning, ) -> Option<GuitarFingering>

Returns a suggested guitar fingering for the supplied tuning.

The tuning strings must be ordered from low to high. Fingering generation uses exact pitch spaces, so both the chord pitches and open-string octaves affect the result.

pub fn common_name(&self) -> String

Returns the primary unpitched music21-style common name.

For chords with multiple table aliases, this is the first common name in table order. Use Self::common_names to get every unpitched alias.

pub fn common_names(&self) -> Vec<String>

Returns all unpitched common-name aliases known for this chord.

pub fn pitch_classes(&self) -> Vec<u8>

Returns the distinct pitch classes in ascending order.

pub fn polyrhythm_components(&self) -> Vec<UnsignedIntegerType>

Maps this chord’s pitch classes to a reduced integer polyrhythm ratio.

Pitch classes are measured from the inferred root when possible, or from the lowest pitch class otherwise. Each semitone offset is mapped to a compact just-intonation ratio and reduced to whole-number components.

pub fn polyrhythm_ratio_string(&self) -> String

Returns Self::polyrhythm_components formatted as a:b:c.

pub fn pitches(&self) -> Vec<Pitch>

Returns cloned pitches for every note in the chord, in input order.

pub fn notes(&self) -> &[Note]

Returns the notes in input order.

pub fn duration(&self) -> Option<&Duration>

Returns the chord duration when one has been assigned.

pub fn set_duration(&mut self, duration: Duration)

Assigns a duration to the chord.

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

Returns a copy of this chord with the supplied duration.

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

Returns the inferred root pitch name when the chord has one.

Returns None for empty chords, where there is no pitch from which a root can be inferred.

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

Returns the lowest pitch name in the chord.

Returns None for empty chords, where there is no bass pitch.

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

Returns the Forte class, such as "3-11B", when available.

Returns None when the chord’s pitch-class set has no Forte-table entry, including empty or otherwise unsupported pitch-class sets.

pub fn normal_form(&self) -> Option<Vec<u8>>

Returns the transposed normal form when table metadata is available.

Returns None when the chord’s pitch-class set cannot be found in the chord tables, including empty or otherwise unsupported pitch-class sets.

pub fn interval_class_vector(&self) -> Option<Vec<u8>>

Returns the interval-class vector when table metadata is available.

Returns None when the chord’s pitch-class set cannot be found in the chord tables, including empty or otherwise unsupported pitch-class sets.

pub fn inversion(&self) -> Option<u8>

Returns the tertian inversion number, where root position is 0.

Returns None for empty chords, chords with fewer than three distinct pitch classes, or chords whose bass-to-root interval does not match a supported tertian inversion.

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

Returns a human-readable inversion label.

Returns None whenever Self::inversion returns None.

pub fn resolution_chord( &self, tonic: &str, mode: Option<&str>, ) -> Result<Option<Self>>

Returns the first likely tonal resolution chord in the given key.

This is intentionally conservative rather than a universal harmonic oracle. It covers the resolution families that music21 exposes most directly: dominant-function sonorities, leading-tone diminished sonorities, and contextual augmented-sixth sonorities. Unsupported chords return Ok(None).

pub fn resolution_chords( &self, tonic: &str, mode: Option<&str>, ) -> Result<Vec<Self>>

Returns likely tonal resolution chords in the given key.

Dominant-function chords resolve by root motion up a perfect fourth to a diatonic triad in the supplied key, so secondary dominants such as D7 in C major resolve to the G-major triad. Leading-tone diminished sonorities resolve up by semitone to a diatonic triad. Italian, French, German, and Swiss-style augmented-sixth sonorities in context resolve to the dominant triad.

pub fn resolution_chords_in_key(&self, key: &Key) -> Result<Vec<Self>>

Returns likely tonal resolution chords in the supplied key.

pub fn resolution_suggestions_in_key( &self, key: &Key, ) -> Result<Vec<ChordResolutionSuggestion>>

Returns likely tonal resolution suggestions in the supplied key.

pub fn resolution_suggestions(&self) -> Result<Vec<ChordResolutionSuggestion>>

Returns likely tonal resolution chords with inferred key contexts.

This is a convenience wrapper around Self::resolution_chords for exploratory tools: dominant-function sonorities are tested against the key a perfect fourth above their root, leading-tone sonorities against the key a semitone above their root, and augmented-sixth sonorities against all built-in major/minor tonic spellings.

Trait Implementations

impl Clone for Chord

fn clone(&self) -> Chord

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Chord

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Chord

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Chord

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

Formats the value using the given formatter.

impl From<Chord> for StreamElement

fn from(value: Chord) -> Self

Converts to this type from the input type.

impl FromStr for Chord

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 Serialize for Chord

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&[&str]> for Chord

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<&[Note]> for Chord

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &[Note]) -> Result<Self>

Performs the conversion.

impl TryFrom<&[Pitch]> for Chord

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<&[String]> for Chord

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<&[i32]> for Chord

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<&str> for Chord

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 Chord

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.