Struct Instrument 

pub struct Instrument { /* private fields */ }

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

use music21::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 muted(&self) -> Option<bool>

Whether the drum is struck muted: music21’s muted, which is the drum it plays and not a flag beside it – a muted conga drum is key 62 where an open one is 63.

Three of music21’s classes carry it, and None here is an instrument that is not one of them.

pub fn set_muted(&mut self, muted: bool)

Strikes it muted or open, where it is an instrument that can be.

A conga drum’s muting is the high drum’s alone, so asking it of the low one does nothing, exactly as music21’s setter does nothing unless the modifier is high.

pub fn headless(&self) -> Option<bool>

Whether the tambourine has no drum head – the rock and pop kind, a ring of jingles – where a classical one is headed: music21’s headless, which only its Tambourine carries, so None is an instrument that is not one.

No document says it: MIDI and MusicXML both write a tambourine the same either way, and music21’s MIDI reader takes every one as headless because most such files are rock.

pub fn set_headless(&mut self, headless: bool)

Says whether the tambourine is headless, where it is a tambourine at all; asked of anything else it does nothing, as Instrument::muted does.

pub fn pitched(&self) -> Option<bool>

Whether the whistle sounds a definite pitch – a tin whistle does, a referee’s does not: music21’s pitched, which only its Whistle carries, so None is an instrument that is not one.

pub fn set_pitched(&mut self, pitched: bool)

Says whether the whistle is pitched, where it is a whistle at all.

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::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::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