Chant

Chant21Object

class chant21.chant.Chant21Object

Base class for objects in Chant21. Most importantly, all those object can be exported to simple Python objects (dictionaries and lists), which in turn are directly serializable to JSON. Conversely, such objects can be used to recursively set the properties of a Chant21 object.

annotation
hasAnnotation

True if the element has a non-empty annotation

toObject(includeChildren: bool = True, includeEditorial: bool = True, includeVolpiano: bool = False) → dict

Export the object to a plain Python dictionary. The returned object can have the following properties:

  • type: the name of the chant21 class, such as ‘note’
  • elements: a list of dictionaries representing child elements
  • annotation: annotations for the object
  • volpiano: a volpiano string representing the object
  • editorial: a dictionary with editorial information

Specific classes will moreover add the properties necessary to fully describe the object. The class Note for example adds a pitch property:

>>> a = Note('A')
>>> a.toObject()
{'type': 'note', 'pitch': 'A'}
>>> b = Note('B')
>>> syll = Syllable()
>>> syll.append(a)
>>> syll.append(b)
>>> syll.toObject()
{'type': 'syllable', 'elements': [{'type': 'note', 'pitch': 'A'}, {'type': 'note', 'pitch': 'B'}]}
Parameters:
  • includeChildren (bool, optional) – Whether to include child objects, by default True. Children are exported as a list in obj['elements'].
  • includeEditorial (bool, optional) – Whether to include editorial information, by default True. The editorial information is exported as obj['editorial'].
  • includeVolpiano (bool, optional) – Wether to include a Volpiano representation, by default False. The Volpiano version is exported as obj['volpiano'].
Returns:

A dictionary with at least a field type, but possibly also editorial, annotation, volpiano and elements.
Return type:

dict
fromObject(obj: dict, parent=None, parseChildren=True)

Set the properties of the current class instance using a dictionary of properties. The dictionary should be of the same form as the one returned by chant.Chant21Object.toObject().

>>> n = Note('C')
>>> n.fromObject({'type': 'note', 'pitch': 'A4'})
>>> n
<chant21.chant.Note A>
Parameters:
  • obj (dict) – The object to import
  • parent (Chant21Object, optional) – The parent object; this is set automatically when importing the children, by default None.
  • parseChildren (bool, optional) – Whether to also import the child objects, by default True

Chant

class chant21.chant.Chant(*args, **keywords)
show(*args, makeFlatter=True, **kwargs)

Display the chant, as html or using the display options of music21.

Chant21 allows you to visualize the structure of a chant interactively in an IPython environment:

from music21 import converter
import chant21
ch = converter.parse('cantus: 1---f-g--h---g--f--h---3/Abra cadabra')
ch.show('html', showWords=True, showOptions=True)
Show:

Section

1---
 
f-g--
A-
h---
bra
g--
ca-
f--
da-
h---
bra
3
 
conversion {'originalFormat': 'cantus/volpiano', 'converter': 'chant21', 'version': '0.4.6'}
chant21version 0.4.6

Optional keywords include showOptions, showSections, showWords, showSyllables, showNeumes, showMetadata and showMisalignments. See chant21.html.toWidget() for more information.

Parameters:
  • how (string, optional) – How to display the chant? If 'html' a HTML rendition of the chant displayed, which only works in an IPython context. Otherwise the argument is passed to music21.stream.Part.show().
  • makeFlatter (bool, optional) – Flatten the chant before showing it, by default True. This has no effect when displaying as html.
toObject(**kwargs)

Export the object to a simple dictionary. See chant21.chant.Chant21Object.toObject()

fromObject(obj, **kwargs)

Set properties from a dictionary. See chant21.chant.Chant21Object.toObject()

toCHSON(fp=None, includeEditorial=True, **jsonKwargs)
toHTML(filepath=None, chantOnly=True, **kwargs)

Export the chant to HTML and render the music in the Volpiano typeface. There are two ways of exporting the chant: either a complete file is generated, with a title and metadata, or a ‘widget’ with only the music is returned. The latter is used in Jupyter notebooks.

Parameters:
  • filepath ([type], optional) – If set the chant is exported to an HTML file, otherwise a HTML string is returned, by default None
  • chantOnly (bool, optional) – Create a widget with only the chant, not the title and additional metadata. By default True
  • **kwargs (optional) – Optional keyword arguments for chant21.html.toFile() or chant21.html.toWidget(). Keywords include showOptions, showSections, showWords, showSyllables, showNeumes, showMetadata and showMisalignments.
Returns:

A html string if the html is not written to a file.
Return type:

str or none
flatter

A copy of the chant where words, syllables and neumes have been flattened. It is not completely flat, since measures are preserved. This method is useful for visualizing chants: ch.flatter.show() will also show measures and barlines, where as ch.flat.show() will not.

>>> from music21 import converter
>>> ch = converter.parse("(c4) A(dc~)B(c/e) (::) c(dc/fg) (::)", format='gabc')
>>> ch.show('text')
{0.0} <chant21.chant.Section>
    {0.0} <chant21.chant.Word>
        {0.0} <chant21.chant.Syllable>
            {0.0} <music21.clef.Clef>
    {0.0} <chant21.chant.Word>
        {0.0} <chant21.chant.Syllable lyrics=A>
            {0.0} <chant21.chant.Neume>
                {0.0} <chant21.chant.Note D>
                {1.0} <chant21.chant.Note C>
        {2.0} <chant21.chant.Syllable lyrics=B>
            {0.0} <chant21.chant.Neume>
                {0.0} <chant21.chant.Note C>
            {1.0} <chant21.chant.Neume>
                {0.0} <chant21.chant.Note E>
{4.0} <chant21.chant.Section>
    {0.0} <chant21.chant.Word>
        {0.0} <chant21.chant.Syllable>
            {0.0} <chant21.chant.PausaFinalis>
    {0.0} <chant21.chant.Word>
        {0.0} <chant21.chant.Syllable lyrics=c>
            {0.0} <chant21.chant.Neume>
                {0.0} <chant21.chant.Note D>
                {1.0} <chant21.chant.Note C>
            {2.0} <chant21.chant.Neume>
                {0.0} <chant21.chant.Note F>
                {1.0} <chant21.chant.Note G>
    {4.0} <chant21.chant.Word>
        {0.0} <chant21.chant.Syllable>
            {0.0} <chant21.chant.PausaFinalis>
>>> ch.flatter.show('text')
{0.0} <music21.stream.Measure 0 offset=0.0>
    {0.0} <music21.clef.Clef>
    {0.0} <chant21.chant.Note D>
    {1.0} <chant21.chant.Note C>
    {2.0} <chant21.chant.Note C>
    {3.0} <chant21.chant.Note E>
    {4.0} <chant21.chant.PausaFinalis>
{4.0} <music21.stream.Measure 0 offset=4.0>
    {0.0} <chant21.chant.Note D>
    {1.0} <chant21.chant.Note C>
    {2.0} <chant21.chant.Note F>
    {3.0} <chant21.chant.Note G>
    {4.0} <chant21.chant.PausaFinalis>
phrases

Returns all the phrases in a chant, where phrases are all segments between two pausas.

Note that phrases are only reliable in GABC, and not in Cantus Volpiano. In gabc all pausa minima (breathing marks) are marked (by ,) and reliable indicators of phrase boundaries. In Cantus Volpiano, pausa minima however have a different meaning: they mark column or page boundaries.

>>> from music21 import converter
>>> ch = converter.parse("(c4) A(dc)B(c,) C(dc) (::)", format='gabc')
>>> ch.phrases.show('text') #doctest: +ELLIPSIS
{0.0} <music21.stream.Stream 0x...>
    {0.0} <music21.clef.Clef>
    {0.0} <chant21.chant.Note D>
    {1.0} <chant21.chant.Note C>
    {2.0} <chant21.chant.Note C>
{3.0} <music21.stream.Stream 0x...>
    {0.0} <chant21.chant.Note D>
    {1.0} <chant21.chant.Note C>
Type:music21.stream.Part
sections
addNeumeSlurs()

Add slurs over all notes that form a single neume.

>>> from music21 import converter
>>> ch = converter.parse('1---fgf-ga', format='cantus')
>>> ch.flatter.show('text')
{0.0} <music21.stream.Measure 0 offset=0.0>
    {0.0} <music21.clef.Clef>
    {0.0} <chant21.chant.Note F>
    {1.0} <chant21.chant.Note G>
    {2.0} <chant21.chant.Note F>
    {3.0} <chant21.chant.Note G>
    {4.0} <chant21.chant.Note A>
>>> ch.addNeumeSlurs()
>>> ch.flatter.show('text')
{0.0} <music21.stream.Measure 0 offset=0.0>
    {0.0} <music21.clef.Clef>
    {0.0} <music21.spanner.Slur <chant21.chant.Note F><chant21.chant.Note G><chant21.chant.Note F>>
    {0.0} <chant21.chant.Note F>
    {1.0} <chant21.chant.Note G>
    {2.0} <chant21.chant.Note F>
    {3.0} <music21.spanner.Slur <chant21.chant.Note G><chant21.chant.Note A>>
    {3.0} <chant21.chant.Note G>
    {4.0} <chant21.chant.Note A>
makeBreathMarks()
makeBarlines()
makeMetadata()
joinTextAcrossPausas()

Section

class chant21.chant.Section(givenElements=None, *args, **keywords)

Bases: chant21.chant.Chant21Object, music21.stream.Stream

name
words
joinWordsAcrossPausas(joinSyllablesAcrossPausas=True)

Merge words containing pausas

toObject(**kwargs)

Export the object to a plain Python dictionary. The returned object can have the following properties:

  • type: the name of the chant21 class, such as ‘note’
  • elements: a list of dictionaries representing child elements
  • annotation: annotations for the object
  • volpiano: a volpiano string representing the object
  • editorial: a dictionary with editorial information

Specific classes will moreover add the properties necessary to fully describe the object. The class Note for example adds a pitch property:

>>> a = Note('A')
>>> a.toObject()
{'type': 'note', 'pitch': 'A'}
>>> b = Note('B')
>>> syll = Syllable()
>>> syll.append(a)
>>> syll.append(b)
>>> syll.toObject()
{'type': 'syllable', 'elements': [{'type': 'note', 'pitch': 'A'}, {'type': 'note', 'pitch': 'B'}]}
Parameters:
  • includeChildren (bool, optional) – Whether to include child objects, by default True. Children are exported as a list in obj['elements'].
  • includeEditorial (bool, optional) – Whether to include editorial information, by default True. The editorial information is exported as obj['editorial'].
  • includeVolpiano (bool, optional) – Wether to include a Volpiano representation, by default False. The Volpiano version is exported as obj['volpiano'].
Returns:

A dictionary with at least a field type, but possibly also editorial, annotation, volpiano and elements.
Return type:

dict

Word

class chant21.chant.Word(givenElements=None, *args, **keywords)

Bases: chant21.chant.Chant21Object, music21.stream.Stream

musicAndTextAligned = None
syllables
flatLyrics
hasLyrics
hasAnnotation

True if the element has a non-empty annotation

joinSyllablesAcrossPausas()

Merge syllables if they are separated by a syllable containing only a pausa. This is often the case on long melismas.

updateSyllableLyrics()
toObject(**kwargs)

Export the object to a plain Python dictionary. The returned object can have the following properties:

  • type: the name of the chant21 class, such as ‘note’
  • elements: a list of dictionaries representing child elements
  • annotation: annotations for the object
  • volpiano: a volpiano string representing the object
  • editorial: a dictionary with editorial information

Specific classes will moreover add the properties necessary to fully describe the object. The class Note for example adds a pitch property:

>>> a = Note('A')
>>> a.toObject()
{'type': 'note', 'pitch': 'A'}
>>> b = Note('B')
>>> syll = Syllable()
>>> syll.append(a)
>>> syll.append(b)
>>> syll.toObject()
{'type': 'syllable', 'elements': [{'type': 'note', 'pitch': 'A'}, {'type': 'note', 'pitch': 'B'}]}
Parameters:
  • includeChildren (bool, optional) – Whether to include child objects, by default True. Children are exported as a list in obj['elements'].
  • includeEditorial (bool, optional) – Whether to include editorial information, by default True. The editorial information is exported as obj['editorial'].
  • includeVolpiano (bool, optional) – Wether to include a Volpiano representation, by default False. The Volpiano version is exported as obj['volpiano'].
Returns:

A dictionary with at least a field type, but possibly also editorial, annotation, volpiano and elements.
Return type:

dict
fromObject(obj, **kwargs)

Set the properties of the current class instance using a dictionary of properties. The dictionary should be of the same form as the one returned by chant.Chant21Object.toObject().

>>> n = Note('C')
>>> n.fromObject({'type': 'note', 'pitch': 'A4'})
>>> n
<chant21.chant.Note A>
Parameters:
  • obj (dict) – The object to import
  • parent (Chant21Object, optional) – The parent object; this is set automatically when importing the children, by default None.
  • parseChildren (bool, optional) – Whether to also import the child objects, by default True

Syllable

class chant21.chant.Syllable(givenElements=None, *args, **keywords)

Bases: chant21.chant.Chant21Object, music21.stream.Stream

lyric
hasLyrics
neumes
toObject(**kwargs)

Export the object to a plain Python dictionary. The returned object can have the following properties:

  • type: the name of the chant21 class, such as ‘note’
  • elements: a list of dictionaries representing child elements
  • annotation: annotations for the object
  • volpiano: a volpiano string representing the object
  • editorial: a dictionary with editorial information

Specific classes will moreover add the properties necessary to fully describe the object. The class Note for example adds a pitch property:

>>> a = Note('A')
>>> a.toObject()
{'type': 'note', 'pitch': 'A'}
>>> b = Note('B')
>>> syll = Syllable()
>>> syll.append(a)
>>> syll.append(b)
>>> syll.toObject()
{'type': 'syllable', 'elements': [{'type': 'note', 'pitch': 'A'}, {'type': 'note', 'pitch': 'B'}]}
Parameters:
  • includeChildren (bool, optional) – Whether to include child objects, by default True. Children are exported as a list in obj['elements'].
  • includeEditorial (bool, optional) – Whether to include editorial information, by default True. The editorial information is exported as obj['editorial'].
  • includeVolpiano (bool, optional) – Wether to include a Volpiano representation, by default False. The Volpiano version is exported as obj['volpiano'].
Returns:

A dictionary with at least a field type, but possibly also editorial, annotation, volpiano and elements.
Return type:

dict
fromObject(obj, **kwargs)

Set the properties of the current class instance using a dictionary of properties. The dictionary should be of the same form as the one returned by chant.Chant21Object.toObject().

>>> n = Note('C')
>>> n.fromObject({'type': 'note', 'pitch': 'A4'})
>>> n
<chant21.chant.Note A>
Parameters:
  • obj (dict) – The object to import
  • parent (Chant21Object, optional) – The parent object; this is set automatically when importing the children, by default None.
  • parseChildren (bool, optional) – Whether to also import the child objects, by default True

Neume

class chant21.chant.Neume(givenElements=None, *args, **keywords)

Bases: chant21.chant.Chant21Object, music21.stream.Stream

addSlur()

Adds a slur to the neumes notes

Alterations

class chant21.chant.Alteration(**kwargs)

Bases: chant21.chant.Chant21Object, music21.base.Music21Object

Placeholder of the exact position of alterations in the chant.

Alterations record the exact position of the alterations in the score, which is used when converting to other formats such as volpiano. Importantly, alterations are meaningless placeholder objects for music21. That means that alterations need not be shown in the exact same place where we find them in the chant (i.e., the location of the Alteration object). Music21 places accidentals according to a different logic, based on the pitches of the notes. However, the exact location of alterations is preserved in the the HTLM rendition (using chant.show('html')).

pitch = None

the pitch at which the accidental is found in the score.

Type:music21.pitch.Pitch
toObject(**kwargs)

Export the object to a plain Python dictionary. The returned object can have the following properties:

  • type: the name of the chant21 class, such as ‘note’
  • elements: a list of dictionaries representing child elements
  • annotation: annotations for the object
  • volpiano: a volpiano string representing the object
  • editorial: a dictionary with editorial information

Specific classes will moreover add the properties necessary to fully describe the object. The class Note for example adds a pitch property:

>>> a = Note('A')
>>> a.toObject()
{'type': 'note', 'pitch': 'A'}
>>> b = Note('B')
>>> syll = Syllable()
>>> syll.append(a)
>>> syll.append(b)
>>> syll.toObject()
{'type': 'syllable', 'elements': [{'type': 'note', 'pitch': 'A'}, {'type': 'note', 'pitch': 'B'}]}
Parameters:
  • includeChildren (bool, optional) – Whether to include child objects, by default True. Children are exported as a list in obj['elements'].
  • includeEditorial (bool, optional) – Whether to include editorial information, by default True. The editorial information is exported as obj['editorial'].
  • includeVolpiano (bool, optional) – Wether to include a Volpiano representation, by default False. The Volpiano version is exported as obj['volpiano'].
Returns:

A dictionary with at least a field type, but possibly also editorial, annotation, volpiano and elements.
Return type:

dict
fromObject(obj, **kwargs)

Set the properties of the current class instance using a dictionary of properties. The dictionary should be of the same form as the one returned by chant.Chant21Object.toObject().

>>> n = Note('C')
>>> n.fromObject({'type': 'note', 'pitch': 'A4'})
>>> n
<chant21.chant.Note A>
Parameters:
  • obj (dict) – The object to import
  • parent (Chant21Object, optional) – The parent object; this is set automatically when importing the children, by default None.
  • parseChildren (bool, optional) – Whether to also import the child objects, by default True
volpiano

a volpiano string representing the alteration.

Type:str
class chant21.chant.Flat(**kwargs)

Bases: chant21.chant.Alteration

A placeholder class for flat signs. See Alteration for details.

class chant21.chant.Natural(**kwargs)

Bases: chant21.chant.Alteration

A placeholder class for natural signs. See Alteration for details.