Staff Text
==========

*Example script* (scamp): `examples/Tutorial/22_staff_text.py <https://github.com/MarcTheSpark/scamp/blob/main/examples/Tutorial/22_staff_text.py>`__

*Download:* :download:`22_staff_text.py <downloads/tutorial_22_staff_text/22_staff_text.py>`

Demonstrates various ways of adding text annotations to notes that are played. Text is one of the various notational details that can be passed to the fourth, optional "properties" argument of play_note.

*Topics:* :doc:`Notation & engraving › Special notations <notation_engraving>`

.. 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/Tutorial/22_staff_text.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/Tutorial/22_staff_text.mp3" style="width:100%;max-width:520px"></audio></div>

.. code-block:: python

   from scamp import *

   s = Session()
   violin = s.new_part("violin")
   s.start_transcribing()

   # the simplest way to add text is to place a "text: [string]" entry in the fourth properties argument
   violin.play_note(81, 0.7, 2, "text: chillingly")
   # you can also use a StaffText object, which is a little more customizable
   violin.play_note(69, 0.5, 2, StaffText("cresc.", bold=True, placement="below"))
   # if you want multiple texts for the same note, you can separate them by commas
   violin.play_note(70, 0.5, 1, "text: soft, text: (with pathos)")
   # if you want to italicise the text without bothering with a StaffText object, you
   # can use a leading/trailing asterisk or underscore, following Markdown conventions
   # (only works on the whole text; you can't italicise only part of the text, for now)
   violin.play_note(71, 0.8, 1, "text: *louder*")
   # you can also do bold using a double asterisk/underscore
   violin.play_note(72, 0.9, 1.5, "text: **LOUD**")
   violin.play_note(73, 0.9, 0.25)
   # here we see that texts can be given as part of a properties dictionary, under the
   # "texts" entry. Also note how three asterisks can be used for bold italic.
   violin.play_chord([62, 74], 1.0, 4.25, {
       "articulation": "accent",
       "texts": ["***INSANELY LOUD***",  StaffText("(break something)", placement="below")]
   })

   performance = s.stop_transcribing()
   performance.to_score().show()