.. _usersGuide_32_articulations:

.. WARNING: DO NOT EDIT THIS FILE:
   AUTOMATICALLY GENERATED.
   PLEASE EDIT THE .py FILE DIRECTLY.

User's Guide, Chapter 32: Articulations
=======================================

Articulations are elements attached usually to Notes that specify how
the note should be played. In ``music21`` we use the term articulation
also to refer to indications that are specific to instruments, such as
bowing or fingering information. They all live in the
:ref:`moduleArticulations` module and start with the class
:class:`~music21.articulations.Articulation`.

.. code:: ipython3

    from music21 import *
    
    art = articulations.Articulation()
    art




.. parsed-literal::
   :class: ipython-result

    <music21.articulations.Articulation>



All articulations have a ``.placement`` attribute which can be 'above',
'below', or None.

.. code:: ipython3

    print(art.placement)


.. parsed-literal::
   :class: ipython-result

    None


.. code:: ipython3

    art.placement = 'above'
    art.placement




.. parsed-literal::
   :class: ipython-result

    'above'



All articulations have additional ``.style`` information, which we will
discuss in more depth later:

.. code:: ipython3

    art.style.absoluteX = 20

Now, most of the time you won't want *any* articulation, you will want
*the* specific articulation such as ``Staccato``, ``Accent``, etc. So
there are classes for each of them:

.. code:: ipython3

    stac = articulations.Staccato()
    acc = articulations.Accent()

To make an articulation display, attach it to the ``.articulations``
list on a Note:

.. code:: ipython3

    n1 = note.Note('A4')
    n1.articulations




.. parsed-literal::
   :class: ipython-result

    []



.. code:: ipython3

    n1.articulations.append(stac)
    n1.articulations




.. parsed-literal::
   :class: ipython-result

    [<music21.articulations.Staccato>]



.. code:: ipython3

    n1.show()



.. image:: usersGuide_32_articulations_12_0.png
   :width: 191px
   :height: 49px


Because ``.articulations`` is a list, a note may have multiple
articulations:

.. code:: ipython3

    n1.articulations.append(acc)
    n1.show()



.. image:: usersGuide_32_articulations_14_0.png
   :width: 191px
   :height: 49px


.. code:: ipython3

    doit = articulations.Doit()
    n1.articulations.append(doit)
    n1.show()



.. image:: usersGuide_32_articulations_15_0.png
   :width: 222px
   :height: 49px


Some articulations affect the length of the note:

.. code:: ipython3

    stac.lengthShift




.. parsed-literal::
   :class: ipython-result

    0.7



The ``0.7`` in this case indicates that the note should be played for
70% of its normal length.

Others affect the volume:

.. code:: ipython3

    acc.volumeShift




.. parsed-literal::
   :class: ipython-result

    0.1



Here, instead of 10% of the normal volume (that'd be a weird accent), it
means 10% more than its normal volume. This inconsistency may be fixed
in a later version.

Many articulations have additional parameters.
:class:`~music21.articulations.StrongAccent` for instance can point up
or down:

.. code:: ipython3

    sacc = articulations.StrongAccent()
    sacc.pointDirection




.. parsed-literal::
   :class: ipython-result

    'up'



.. code:: ipython3

    sacc.placement = 'above'
    
    n2 = note.Note('A4')
    n2.articulations.append(sacc)
    
    sacc2 = articulations.StrongAccent()
    sacc2.pointDirection = 'down'
    sacc2.placement = 'below'
    
    n3 = note.Note('A4')
    n3.articulations.append(sacc2)
    
    m = stream.Measure()
    m.append([n2, n3])
    m.show()



.. image:: usersGuide_32_articulations_24_0.png
   :width: 203px
   :height: 55px


Unfortunately, neither MuseScore (which generates these images) nor
Finale respect ``.placement`` or ``pointDirection`` at this time.

As we saw in :ref:`Chapter 13<usersGuide_13_music21object2>`, when a
note is split, its articulations go either on the first note of the
split, the last, or all the notes:

.. code:: ipython3

    n12, n22 = n1.splitAtQuarterLength(0.5)
    m2 = stream.Measure()
    m2.append([n12, n22])
    m2.show()



.. image:: usersGuide_32_articulations_26_0.png
   :width: 233px
   :height: 49px


This property is determined by the ``.tieAttach`` value for an
articulation:

.. code:: ipython3

    acc.tieAttach, stac.tieAttach




.. parsed-literal::
   :class: ipython-result

    ('first', 'last')



Breath marks can have a ``.symbol`` of 'comma' or 'tick':

.. code:: ipython3

    bm2 = articulations.BreathMark()
    bm2.symbol = 'comma'
    n2.articulations.append(bm2)
    
    bm3 = articulations.BreathMark()
    bm3.symbol = 'tick'
    n3.articulations.append(bm3)
    
    m.show()



.. image:: usersGuide_32_articulations_30_0.png
   :width: 239px
   :height: 55px


Again, unfortunately, some MusicXML readers do not respect this value.

MusicXML distinguishes articulations from technical indications, but in
``music21`` these are all in the ``articulations`` module and stored in
the ``.articulations`` list. They do, however, have
``TechnicalIndication`` in their classes. A Fingering is something that
MusicXML considers a TechnicalIndication:

.. code:: ipython3

    f = articulations.Fingering(5)
    f.classes




.. parsed-literal::
   :class: ipython-result

    ('Fingering',
     'TechnicalIndication',
     'Articulation',
     'Music21Object',
     'ProtoM21Object',
     'object')



.. code:: ipython3

    f.fingerNumber




.. parsed-literal::
   :class: ipython-result

    5



.. code:: ipython3

    n3.articulations = []
    n3.articulations.append(f)
    m.show()



.. image:: usersGuide_32_articulations_34_0.png
   :width: 230px
   :height: 55px


``Music21`` can represent all the information in MusicXML articulations,
and every MusicXML technical indication with the exception of guitar
information, arrows, and woodwind/brass fingering.

This is a short chapter, because once you know a bit about
articulations, you'll just want to spend your time in the
:ref:`moduleArticulations` module reference to learn more about them.
But there is a related concept called "expressions" that we will learn
about in
:ref:`Chapter 33: Expressions and Ornaments<usersGuide_33_expressions>`