Struct Instrument 

pub struct Instrument { /* private fields */ }

An instrument of one of music21’s kinds: music21’s Instrument.

use music21_rs::instrument::{Instrument, SearchLanguage};

let clarinet = Instrument::from_name("Clarinet in A", SearchLanguage::All)?;
assert_eq!(clarinet.kind(), "Clarinet");
assert!(clarinet.is_a("WoodwindInstrument"));
assert_eq!(clarinet.transposition().unwrap().directed_name(), "m-3");

Implementations

impl Instrument

pub fn new() -> Self

music21’s bare Instrument, which says nothing about itself.

pub fn of_kind(class: &str) -> Result<Self>

An instrument of the kind music21 names by that class, as a new one of that class starts out: "Piano", "BassClarinet", "Triangle".

pub fn part_id(&self) -> Option<&str>

The id of the part this instrument plays, as a score writes it: music21’s partId, P1 in a score read from MusicXML.

pub fn set_part_id(&mut self, id: Option<String>)

Sets the id of the part this instrument plays.

pub fn instrument_id(&self) -> Option<&str>

The instrument’s own id within its part, P1-I1: music21’s instrumentId.

pub fn set_instrument_id(&mut self, id: Option<String>)

Sets the instrument’s own id.

pub fn kinds() -> impl Iterator<Item = &'static str>

Every kind of instrument music21 has a class for, families first.

pub fn from_midi_program(program: u8) -> Result<Self>

The instrument music21 makes of a General MIDI program, 0 to 127, with its program set to that number: music21’s instrumentFromMidiProgram.

pub fn from_name(text: &str, language: SearchLanguage) -> Result<Self>

The instrument a score’s name for one means, read the way music21’s fromString reads it.

The name is taken apart into every run of its words, and the longest run naming an instrument wins, a later one breaking a tie unless the one found is already of its kind – so "Bb Piccolo Trumpet" is a trumpet, not a piccolo. The instrument is named with the text as given. For an instrument that comes in several keys, a run naming a pitch sets its transposition: "Horn in F", "Klarinette in B.".

pub fn kind(&self) -> &str

The kind of instrument this is: music21’s class name for it.

pub fn class_name(&self) -> Option<&'static str>

music21’s own name for this kind of instrument, where it is one music21 has a class for: the name as the table spells it, which is what is_a and the class lineage answer with.

pub fn families(&self) -> &'static [&'static str]

The families this kind belongs to, nearest first and ending with Instrument: a clarinet is a WoodwindInstrument.

pub fn is_a(&self, class: &str) -> bool

Whether this is an instrument of that kind or of a kind in that family, as music21’s isinstance answers.

pub fn name(&self) -> Option<&str>

The instrument’s name: music21’s instrumentName.

pub fn set_name(&mut self, name: Option<String>)

Sets the instrument’s name, or takes it away.

pub fn abbreviation(&self) -> Option<&str>

The instrument’s abbreviation: music21’s instrumentAbbreviation.

pub fn set_abbreviation(&mut self, abbreviation: Option<String>)

Sets the abbreviation, or takes it away.

pub fn part_name(&self) -> Option<&str>

What the part this instrument plays is called, where that is not the instrument’s name: music21’s partName.

pub fn set_part_name(&mut self, name: Option<String>)

Sets what the part is called.

pub fn part_abbreviation(&self) -> Option<&str>

The part’s abbreviation: music21’s partAbbreviation.

pub fn set_part_abbreviation(&mut self, abbreviation: Option<String>)

Sets the part’s abbreviation.

pub fn best_name(&self) -> Option<&str>

The best name there is for this instrument: the part’s name, the part’s abbreviation, the instrument’s name or its abbreviation, the first of those given. music21’s bestName.

pub fn sound(&self) -> Option<&str>

The sound’s MusicXML id, "wind.reed.clarinet.bflat" and the like: music21’s instrumentSound.

pub fn set_sound(&mut self, sound: Option<String>)

Sets the sound’s id.

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

The General MIDI program, counted from nought: music21’s midiProgram.

pub fn set_midi_program(&mut self, program: Option<u8>)

Sets the General MIDI program.

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

The MIDI channel, counted from nought, 9 being the drums: music21’s midiChannel.

pub fn set_midi_channel(&mut self, channel: Option<u8>)

Sets the MIDI channel.

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

The lowest note the instrument plays, as it sounds: music21’s lowestNote.

pub fn set_lowest(&mut self, pitch: Option<Pitch>)

Sets the lowest note.

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

The highest note the instrument plays: music21’s highestNote.

pub fn set_highest(&mut self, pitch: Option<Pitch>)

Sets the highest note.

pub fn transposition(&self) -> Option<&Interval>

The interval from what is written for the instrument to what sounds: a B-flat clarinet sounds a major second below, M-2. music21’s transposition.

pub fn set_transposition(&mut self, interval: Option<Interval>)

Sets the transposition, or takes it away.

pub fn sounding(&self, written: &Pitch) -> Result<Pitch>

What sounds when written is played: the pitch moved by the transposition, or itself for an instrument that does not transpose.

pub fn written(&self, sounding: &Pitch) -> Result<Pitch>

What is written for sounding to be heard.

pub fn in_percussion_map(&self) -> bool

Whether the instrument is one of General MIDI’s percussion map: music21’s inGMPercMap.

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

The General MIDI drum the instrument plays, for unpitched percussion: music21’s percMapPitch.

pub fn set_percussion_pitch(&mut self, pitch: Option<u8>)

Sets the General MIDI drum the instrument plays.

pub fn set_in_percussion_map(&mut self, in_map: bool)

Says whether the instrument is in the General MIDI percussion map.

pub fn string_pitches(&self) -> Option<&[Pitch]>

The open strings, lowest first unless the tuning is reentrant, for a string instrument music21 tunes: music21’s stringPitches.

use music21_rs::Instrument;

let violin = Instrument::of_kind("Violin")?;
let open: Vec<String> = violin
    .string_pitches()
    .unwrap()
    .iter()
    .map(|pitch| pitch.name_with_octave())
    .collect();
assert_eq!(open, ["G3", "D4", "A4", "E5"]);

pub fn set_string_pitches(&mut self, pitches: Vec<Pitch>)

Retunes the open strings, a scordatura.

pub fn modifier(&self) -> Option<&str>

How an unpitched percussion instrument is played, such as "low" for a bongo or "rimshot" for a snare: music21’s modifier.

pub fn set_modifier(&mut self, modifier: &str)

Sets how the instrument is played. A modifier its drum map knows changes the drum it plays, and is written back as that drum’s own name for it, so a woodblock set to "LO" plays the low block and says "low".

use music21_rs::Instrument;

let mut woodblock = Instrument::of_kind("Woodblock")?;
woodblock.set_modifier("LO");
assert_eq!(woodblock.modifier(), Some("low"));
assert_eq!(woodblock.percussion_pitch(), Some(77));

pub fn auto_assign_midi_channel( &mut self, used: &[u8], max_channels: u8, ) -> Result<u8>

Takes a MIDI channel no instrument in used has, and returns it: music21’s autoAssignMidiChannel.

Unpitched percussion goes to channel 9 when that is free; otherwise the lowest free channel below max_channels that is not a drum channel is taken. It is an error when every channel is in use; where none is free the answer is 0 and no channel is set, as music21 answers.

pub fn all_names( &self, language: SearchLanguage, ) -> Vec<(SearchLanguage, Vec<&'static str>)>

Every name a score may call this kind of instrument in one language, or in each of them: music21’s getAllNamesForInstrument.

The names are those of the nearest kind in the instrument’s family that the tables name at all – its own, or for a guitar, which they do not name, a string instrument’s – whatever the instrument itself is called.

Trait Implementations

impl Clone for Instrument

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Instrument

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

Formats the value using the given formatter.

impl Default for Instrument

fn default() -> Self

music21’s bare Instrument, which says nothing about itself.

impl<'de> Deserialize<'de> for Instrument

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 Instrument

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

music21’s str of an instrument, less the part id a score gives it: the part’s name where it differs from the instrument’s, then the instrument’s name.

impl From<Instrument> for StreamElement

fn from(value: Instrument) -> Self

Converts to this type from the input type.

impl PartialEq for Instrument

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for Instrument

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 StructuralPartialEq for Instrument