Utility routines for processing text in scores and other musical objects.


class music21.text.TextBox(content=None, x=500, y=500, **keywords)

A TextBox is arbitrary text that might be positioned anywhere on a page, independent of notes or staffs. A page attribute specifies what page this text is found on; style.absoluteY and style.absoluteX position the text from the bottom left corner in units of tenths.

This object is similar to the TextExpression object, but does not have as many position parameters, enclosure attributes, and the ability to convert to RepeatExpressions and TempoTexts.

>>> y = 1000  # set a fixed vertical distance
>>> s = stream.Stream()

Specify character, x position, y position

>>> tb = text.TextBox('m', 250, y)
>>> = 40
>>> = 'bottom'
>>> s.append(tb)
>>> tb = text.TextBox('u', 300, y)
>>> = 60
>>> = 'bottom'
>>> s.append(tb)
>>> tb = text.TextBox('s', 550, y)
>>> = 120
>>> = 'bottom'
>>> s.append(tb)
>>> tb = text.TextBox('ic', 700, y)
>>> = 'bottom'
>>> = 20
>>> = 'italic'
>>> s.append(tb)
>>> tb = text.TextBox('21', 850, y)
>>> = 'bottom'
>>> = 80
>>> = 'bold'
>>> = 'italic'
>>> s.append(tb)

TextBox bases

TextBox read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

TextBox read/write properties


Get or set the content.

>>> te = text.TextBox('Con fuoco')
>>> te.content
'Con fuoco'
>>> = 'center'

Get or set the page number. The first page (page 1) is the default.

>>> te = text.TextBox('Great Score')
>>> te.content
'Great Score'
>>> = 2

Read/write properties inherited from Music21Object:

TextBox methods

Methods inherited from Music21Object:

Methods inherited from ProtoM21Object:

TextBox instance variables

Instance variables inherited from Music21Object:


class music21.text.LanguageDetector(text=None)

Attempts to detect language on the basis of trigrams.

>>> ld = text.LanguageDetector()
>>> ld.mostLikelyLanguage('Guten Morgen Frau Wieck. Ich bin Robert.')

Note that accuracy improves with longer texts, and that the trigrams are case sensitive. Putting “Morgen” in lowercase evaluates the text as Dutch.

Supported languages are currently:

>>> text.LanguageDetector.languageLong
{'en': 'English',
 'fr': 'French',
 'it': 'Italian',
 'de': 'German',
 'cn': 'Chinese',
 'la': 'Latin',
 'nl': 'Dutch'}

See also, documentation for Trigram.

LanguageDetector methods

LanguageDetector.mostLikelyLanguage(excerpt: str) str | None

Returns the code of the most likely language for a passage, works on unicode or ascii. Current languages are:

>>> text.LanguageDetector.languageCodes
['en', 'fr', 'it', 'de', 'cn', 'la', 'nl']

or None if no language is detected.

>>> ld = text.LanguageDetector()
>>> ld.mostLikelyLanguage('Hello there, how are you doing today? '
...                       + "I haven't seen you in a while.")
>>> ld.mostLikelyLanguage('Ciao come stai? Sono molto lento oggi, ma non so perche.')
>>> ld.mostLikelyLanguage('Credo in unum deum. Patrem omnipotentem. Factorum celi')
>>> ld = text.LanguageDetector()
>>> ld.mostLikelyLanguage('') is None

returns a number representing the most likely language for a passage or 0 if there is no text.

Useful for feature extraction.

The codes are the index of the language name in LanguageDetector.languageCodes + 1

>>> ld = text.LanguageDetector()
>>> for index in range(len(ld.languageCodes)):
...    print(str(index + 1) + ' ' +  ld.languageCodes[index])
1 en
2 fr
3 it
4 de
5 cn
6 la
7 nl
>>> numLang = ld.mostLikelyLanguageNumeric('Hello there, how are you doing today? '
...                + "I haven't seen you in a while.")
>>> numLang
>>> ld.languageCodes[numLang - 1]
classmethod LanguageDetector.readExcerpts()

Read the stored trigrams once and store them for later.

Called on first LanguageDectector read.


class music21.text.Trigram(excerptList=None)

See LanguageDetector above. From

The frequency of three character sequences is calculated. When treated as a vector, this information can be compared to other trigrams, and the difference between them seen as an angle. The cosine of this angle varies between 1 for complete similarity, and 0 for utter difference. Since letter combinations are characteristic to a language, this can be used to determine the language of a body of text. For example:

>>> reference_en = Trigram('/path/to/reference/text/english')
>>> reference_de = Trigram('/path/to/reference/text/german')
>>> unknown = Trigram('url://pointing/to/unknown/text')
>>> unknown.similarity(reference_de)
>>> unknown.similarity(reference_en)
#_DOCS_SHOW 0.95

would indicate the unknown text is almost certainly English. As syntax sugar, the minus sign is overloaded to return the difference between texts, so the above objects would give you:

#_DOCS_SHOW >>> unknown - reference_de #_DOCS_SHOW 0.6 #_DOCS_SHOW >>> reference_en - unknown # order doesn’t matter. #_DOCS_SHOW 0.05

As it stands, the Trigram ignores character set information, which means you can only accurately compare within a single encoding (iso-8859-1 in the examples). A more complete implementation might convert to unicode first.

As an extra bonus, there is a method to make up nonsense words in the style of the Trigram’s text.

>>> reference_en.makeWords(30)
My withillonquiver and ald, by now wittlectionsurper, may sequia,
tory, I ad my notter. Marriusbabilly She lady for rachalle spen hat knong al elf

Trigram read-only properties


Trigram methods


Returns a character likely to follow the given string two character string, or a space if nothing is found.


returns a string of made-up words based on the known text.


calculates the scalar length of the trigram vector and stores it in self.length.


returns a number between 0 and 1 indicating similarity between two trigrams. 1 means an identical ratio of trigrams; 0 means no trigrams in common.


music21.text.assembleAllLyrics(streamIn, maxLyrics=10, lyricSeparation='\n')

Concatenate all Lyrics text from a stream separated by lyricSeparation. The Stream is automatically recursed.

uses assembleLyrics to do the heavy work.

maxLyrics just determines how many times we should parse through the score, since it is not easy to determine what the maximum number of lyrics exist in the score.

Here is a demo with one note and five lyrics.

>>> f = corpus.parse('demos/multiple-verses.xml')
>>> text.assembleLyrics(f, 1)
'1. First'
>>> text.assembleLyrics(f, 2)
'2. Second'
>>> l = text.assembleAllLyrics(f)
>>> l
'1. First\n2. Second\n3. Third\n4. Fourth\n5. Fifth'
  • Changed in v8: no lyric separator appears at the beginning.

music21.text.assembleLyrics(streamIn, lineNumber=1)

Concatenate text from a stream. The Stream is automatically flattened.

The lineNumber parameter determines which line of text is assembled, as a ONE-indexed identifier in the .lyrics array. (To be changed in v8 to go with an identifier.). This means that lineNumber=0 will retrieve the last line of text.

>>> s = stream.Stream()
>>> n1 = note.Note()
>>> n1.lyric = 'Hi'
>>> n2 = note.Note()
>>> n2.lyric = 'there'
>>> s.append(n1)
>>> s.append(n2)
>>> text.assembleLyrics(s)
'Hi there'

Composite lyrics can also be assembled.

>>> composite = note.Lyric()
>>> composite0 = note.Lyric(text="He'", syllabic='begin')
>>> composite1 = note.Lyric(text="ya", syllabic='end')
>>> composite1.elisionBefore = '_'
>>> composite.components = [composite0, composite1]
>>> n1.lyrics[0] = composite
>>> text.assembleLyrics(s)
"He'_ya there"

To get the lyrics from another line, set the lineNumber attribute. (see also assembleAllLyrics() to get all lyrics).

>>> n1.addLyric('Bye')
>>> n2.addLyric('Now')
>>> text.assembleLyrics(s, lineNumber=2)
'Bye Now'
music21.text.postpendArticle(src, language=None)

Given a text string, if an article is found in a leading position, place it at the end with a comma.

>>> text.postpendArticle('The Ale is Dear')
'Ale is Dear, The'
>>> text.postpendArticle('The Ale is Dear', 'en')
'Ale is Dear, The'
>>> text.postpendArticle('The Ale is Dear', 'it')
'The Ale is Dear'
>>> text.postpendArticle('Il Combattimento di Tancredi e Clorinda', 'it')
'Combattimento di Tancredi e Clorinda, Il'
music21.text.prependArticle(src, language=None)

Given a text string, if an article is found in a trailing position with a comma, place the article in front and remove the comma.

>>> text.prependArticle('Ale is Dear, The')
'The Ale is Dear'
>>> text.prependArticle('Ale is Dear, The', 'en')
'The Ale is Dear'
>>> text.prependArticle('Ale is Dear, The', 'it')
'Ale is Dear, The'
>>> text.prependArticle('Combattimento di Tancredi e Clorinda, Il', 'it')
'Il Combattimento di Tancredi e Clorinda'