:orphan:

MultiPresetInstrument
=====================

*Example script* (scamp_extensions): `examples/Playback/Playback implementations/multipreset_example.py <https://github.com/MarcTheSpark/scamp_extensions/blob/main/examples/Playback/Playback%20implementations/multipreset_example.py>`__

*Download:* :download:`multipreset_example.py <downloads/playback_playback_implementations_multipreset_example/multipreset_example.py>`

**Requires the** ``scamp_extensions`` **package** (``pip install scamp_extensions``).

Demo of the MultiPresetInstrument, a convenience meta-instrument for subsuming several different playing techniques and their associated notations under a single instrument interface.

*Topics:* :doc:`Playback › Playback implementations <playback>`

.. raw:: html

   <div style="border:1px solid #ccc;padding:8px;margin:0.2em 0 0.6em;display:inline-block;max-width:100%"><img src="../_static/media/Playback/Playback%20implementations/multipreset_example.svg" alt="score" style="max-width:100%;height:auto;display:block"></div>

.. raw:: html

   <div style="margin:0.6em 0"><audio controls preload="none" src="../_static/media/Playback/Playback%20implementations/multipreset_example.mp3" style="width:100%;max-width:520px"></audio></div>

.. code-block:: python

   from scamp import *
   from scamp_extensions.playback import MultiPresetInstrument

   s = Session(tempo=90)

   # This sets up a new viola instrument within Session s that can do arco, pizzicato and harmonic playback
   # the first line creates the instrument using Session s and names it "viola".
   # we can then add presets to the instrument, giving each preset a name, a ScampInstrument or soundfont preset to use,
   # and properties/notations that get bundled with the notes when that preset is used.
   # `bundled_properties` get attached to every note played by a preset
   # `bundled_properties_on_switch` get attached to the first note played by a preset when we switch to it
   # `bundled_properties_on_switch_away` get attached to the next note when we switch away from a preset. This is usually
   # a "cancelling" notation, like "arco" after a section of "pizz"
   viola = MultiPresetInstrument(s, "Viola").\
       add_preset("arco", "viola").\
       add_preset("pizz", "pizzicato", bundled_properties_on_switch="text: pizz",
                  bundled_properties_on_switch_away="text: arco").\
       add_preset("harmonic", "bowed glass", bundled_properties="notehead: harmonic, pitch + 12")

   s.start_transcribing()

   # when playing notes/chords, the MultiPresetInstrument has an extra `preset` argument that can be used to specify
   # the desired preset to use.
   viola.play_note(60, 1, 2)
   viola.play_note(55, 1, 1, preset="pizz")
   viola.play_note(67, 1, 1.5, preset="harmonic")
   viola.play_note(68, 1, 0.5, preset="pizz")
   viola.play_note(67, 1, 0.5, preset="pizz")
   viola.play_note(65, 1, 0.5, preset="pizz")
   viola.play_note(63, 1, 1)
   viola.play_note(62, 1, 1)
   viola.play_note(67, 1, 1, preset="harmonic")
   note_handle = viola.start_note(60, 1.0)
   note_handle.change_pitch(67, 3)
   wait(3)
   note_handle.end()
   note_handle = viola.start_note(67, 1.0, preset="pizz")
   note_handle.change_pitch(60, 1)
   wait(1)
   note_handle.end()
   note_handle = viola.start_note(60, 1.0, preset="pizz")
   note_handle.change_pitch(67, 1)
   wait(1)
   note_handle.end()
   note_handle = viola.play_note(67, 1.0, 1.0, preset="harmonic")

   viola.play_note(60, 1, 3)

   s.stop_transcribing().to_score(time_signature="3/4").show()