2. Instruments

>>> import abjad

2.1. Creating instruments

Use instrumenttools to create an instrument:

>>> violin = abjad.instrumenttools.Violin()

2.2. Understanding the interpreter representation of an instrument

The interpreter representation of an instrument tells you the instrument’s class:

>>> violin
Violin()

2.3. Attaching instruments to a component

Use attach() to attach an instrument to a leaf:

>>> staff = abjad.Staff("c'4 d'4 e'4 f'4")
>>> attach(violin, staff[0])
>>> show(staff)

2.4. Inspecting the instrument attached to a component

Use the inspector to get the instrument attached to a leaf:

>>> abjad.inspect(staff).get_indicator(abjad.Instrument)

2.5. Inspecting a component’s effective instrument

Use the inspector to get the instrument currently in effect for a component:

>>> for note in staff:
...     abjad.inspect(note).get_effective(abjad.Instrument)
... 
Violin()
Violin()
Violin()
Violin()

2.6. Detaching instruments from a component

Use detach() to detach an instrument from a component:

>>> abjad.detach(violin, staff)
()
>>> show(staff)

2.7. Getting the name of an instrument

Use instrument_name to get the name of any instrument:

>>> violin.instrument_name
'violin'

Use instrument_name_markup to get the instrument name markup of any instrument:

>>> violin.instrument_name_markup
Markup(contents=['Violin'])
>>> show(violin.instrument_name_markup)

2.8. Getting the short name of an instrument

Use short_instrument_name to get the short name of any instrument:

>>> violin.short_instrument_name
'vn.'

Use short_instrument_name_markup to get the short instrument name markup of any instrument:

>>> violin.short_instrument_name_markup
Markup(contents=['Vn.'])
>>> show(violin.short_instrument_name_markup)

2.9. Getting an instrument’s range

Use pitch_range to get the range of any instrument:

>>> violin.pitch_range
PitchRange('[G3, G7]')
>>> show(violin.pitch_range)

2.10. Getting an instrument’s level of transposition

Use sounding_pitch_of_written_middle_c to get an instrument’s level of transposition:

>>> violin.sounding_pitch_of_written_middle_c
NamedPitch("c'")
>>> show(violin.sounding_pitch_of_written_middle_c)

2.11. Getting an instrument’s allowable clefs

Use allowable_clefs to get clefs on which an instrument is conventionally notated:

>>> violin.allowable_clefs
ClefList([Clef(name='treble')])
>>> show(violin.allowable_clefs)

2.12. Customizing instrument properties

You can change the properties of any instrument at initialization:

>>> viola = abjad.instrumenttools.Viola(
...     instrument_name='Bratsche',
...     short_instrument_name='Br.',
...     allowable_clefs=['alto', 'treble'],
...     pitch_range='[C3, C6]',
...     )
>>> staff = abjad.Staff("c'4 d'4 e'4 fs'4")
>>> attach(viola, staff[0])
>>> clef = abjad.Clef('alto')
>>> attach(clef, staff[0])
>>> show(staff)