music21.serial¶

This module defines objects for defining and manipulating structures common to serial and/or twelve-tone music, including ToneRow subclasses.

Serial searching methods that were previously here have been moved to alpha.search.serial

Functions¶

music21.serial.getHistoricalRowByName(rowName)¶

Given the name referring to a twelve-tone row used in the historical literature, returns a HistoricalTwelveToneRow object with attributes describing the row.

The names of the rows with stored attributes are below (each must be passed as a string, in single quotes).

>>> for r in sorted(list(serial.historicalDict)):
...     print(r)   
RowBergChamberConcerto
RowBergDerWein
RowBergLulu
RowBergLuluActIIScene1
RowBergLuluActIScene20
RowBergLyricSuite
RowBergLyricSuitePerm
RowBergViolinConcerto
RowBergWozzeckPassacaglia
RowSchoenbergFragOrganSonata
RowSchoenbergFragPiano
RowSchoenbergFragPianoPhantasia
RowSchoenbergIsraelExists
RowSchoenbergJakobsleiter
RowSchoenbergMosesAron
RowSchoenbergOp23No5
RowSchoenbergOp24Mvmt4
RowSchoenbergOp24Mvmt5
RowSchoenbergOp25
RowSchoenbergOp26
RowSchoenbergOp27No1
RowSchoenbergOp27No2
RowSchoenbergOp27No3
RowSchoenbergOp27No4
RowSchoenbergOp28No1
RowSchoenbergOp28No3
RowSchoenbergOp29
RowSchoenbergOp30
RowSchoenbergOp31
RowSchoenbergOp32
RowSchoenbergOp33A
RowSchoenbergOp33B
RowSchoenbergOp34
RowSchoenbergOp35No1
RowSchoenbergOp35No2
RowSchoenbergOp35No3
RowSchoenbergOp35No5
RowSchoenbergOp36
RowSchoenbergOp37
RowSchoenbergOp41
RowSchoenbergOp42
RowSchoenbergOp44
RowSchoenbergOp45
RowSchoenbergOp46
RowSchoenbergOp47
RowSchoenbergOp48No1
RowSchoenbergOp48No2
RowSchoenbergOp48No3
RowSchoenbergOp50A
RowSchoenbergOp50B
RowSchoenbergOp50C
RowWebernOp17No2
RowWebernOp17No3
RowWebernOp18No1
RowWebernOp18No2
RowWebernOp18No3
RowWebernOp19No1
RowWebernOp19No2
RowWebernOp20
RowWebernOp21
RowWebernOp22
RowWebernOp23
RowWebernOp24
RowWebernOp25
RowWebernOp26
RowWebernOp27
RowWebernOp28
RowWebernOp29
RowWebernOp30
RowWebernOp31
RowWebernOpNo17No1

>>> a = serial.getHistoricalRowByName('RowWebernOp29')
>>> a.row
[3, 11, 2, 1, 5, 4, 7, 6, 10, 9, 0, 8]
>>> a.composer
'Webern'
>>> a.opus
'Op. 29'
>>> a.title
'Cantata I'
>>> a.isLinkChord()
False

music21.serial.pcToToneRow(pcSet)¶

A convenience function that, given a list of pitch classes represented as integers and turns it in to a ToneRow object.

>>> a = serial.pcToToneRow(range(12))
>>> a.show('text')
{0.0} <music21.note.Note C>
{1.0} <music21.note.Note C#>
{2.0} <music21.note.Note D>
{3.0} <music21.note.Note E->
{4.0} <music21.note.Note E>
{5.0} <music21.note.Note F>
{6.0} <music21.note.Note F#>
{7.0} <music21.note.Note G>
{8.0} <music21.note.Note G#>
{9.0} <music21.note.Note A>
{10.0} <music21.note.Note B->
{11.0} <music21.note.Note B>
>>> matrixObj = a.matrix()
>>> print(matrixObj)
  0  1  2  3  4  5  6  7  8  9  A  B
  B  0  1  2  3  4  5  6  7  8  9  A
...

>>> a = serial.pcToToneRow([4,5,0,6,7,2,'a',8,9,1,'b',3])
>>> matrixObj = a.matrix()
>>> print(matrixObj)
  0  1  8  2  3  A  6  4  5  9  7  B
  B  0  7  1  2  9  5  3  4  8  6  A
...

music21.serial.rowToMatrix(p)¶: takes a row of numbers of converts it to a 12-tone matrix.

HistoricalTwelveToneRow¶

class music21.serial.HistoricalTwelveToneRow(composer=None, opus=None, title=None, row=None)¶: Subclass of TwelveToneRow storing additional attributes of a twelve-tone row used in the historical literature.

HistoricalTwelveToneRow bases

HistoricalTwelveToneRow read-only properties

Read-only properties inherited from Stream:

Read-only properties inherited from StreamCoreMixin:

spannerBundle

Read-only properties inherited from Music21Object:

classSet

classes

measureNumber

HistoricalTwelveToneRow read/write properties

Read/write properties inherited from Stream:

Read/write properties inherited from Music21Object:

quarterLength

HistoricalTwelveToneRow methods

Methods inherited from TwelveToneRow:

areCombinatorial()
findHistorical()
findTransformedHistorical()

getLinkClassification()
isAllInterval()

isLinkChord()
matrix()

Methods inherited from ToneRow:

findOriginalCenteredTransformations()
findZeroCenteredTransformations()
getIntervalsAsString()
isSameRow()

isTwelveToneRow()
makeTwelveToneRow()
noteNames()

originalCenteredTransformation()
pitchClasses()
zeroCenteredTransformation()

Methods inherited from Stream:

Methods inherited from StreamCoreMixin:

asTimespans()

coreGatherMissingSpanners()

elementsChanged()

Methods inherited from Music21Object:

HistoricalTwelveToneRow instance variables

HistoricalTwelveToneRow.composer¶: The name of the composer.

HistoricalTwelveToneRow.opus¶: The opus of the work, or None.

HistoricalTwelveToneRow.title¶: The title of the work.

Instance variables inherited from ToneRow:

row

Instance variables inherited from Stream:

Instance variables inherited from Music21Object:

ToneRow¶

class music21.serial.ToneRow¶: A Stream representation of a tone row, or an ordered sequence of pitches; can most importantly be used to deal with serial transformations.

ToneRow bases

ToneRow read-only properties

Read-only properties inherited from Stream:

Read-only properties inherited from StreamCoreMixin:

spannerBundle

Read-only properties inherited from Music21Object:

classSet

classes

measureNumber

ToneRow read/write properties

Read/write properties inherited from Stream:

Read/write properties inherited from Music21Object:

quarterLength

ToneRow methods

ToneRow.findOriginalCenteredTransformations(otherRow)¶

Gives the list of original-centered serial transformations taking one ToneRow to another, the second specified in the argument. Each transformation is given as a tuple of the transformation type and index.

See originalCenteredTransformation() for an explanation of this convention.

>>> chromatic = serial.pcToToneRow([2, 3, 4, 5, 6, 7, 8, 9, 'A', 'B', 0, 1])
>>> reversechromatic = serial.pcToToneRow([8, 7, 6, 5, 4, 3, 2, 1, 0, 'B', 'A', 9])
>>> chromatic.findOriginalCenteredTransformations(reversechromatic)
[('I', 6), ('R', 7)]
>>> schoenberg25 = serial.getHistoricalRowByName('RowSchoenbergOp25')
>>> schoenberg26 = serial.getHistoricalRowByName('RowSchoenbergOp26')
>>> schoenberg25.findOriginalCenteredTransformations(schoenberg26)
[]
>>> schoenberg26.findOriginalCenteredTransformations(
...     schoenberg26.originalCenteredTransformation('RI',8))
[('RI', 8)]

ToneRow.findZeroCenteredTransformations(otherRow)¶

Gives the list of zero-centered serial transformations taking one ToneRow to another, the second specified in the argument. Each transformation is given as a tuple of the transformation type and index.

See zeroCenteredTransformation() for an explanation of this convention.

>>> chromatic = serial.pcToToneRow([2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 1])
>>> reversechromatic = serial.pcToToneRow([8, 7, 6, 5, 4, 3, 2, 1, 0, 11, 10, 9])
>>> chromatic.findZeroCenteredTransformations(reversechromatic)
[('I', 8), ('R', 9)]
>>> schoenberg25 = serial.getHistoricalRowByName('RowSchoenbergOp25')
>>> schoenberg26 = serial.pcToToneRow(serial.getHistoricalRowByName(
...                                        'RowSchoenbergOp26').row)
>>> schoenberg25.findZeroCenteredTransformations(schoenberg26)
[]
>>> schoenberg26.findZeroCenteredTransformations(
...     schoenberg26.zeroCenteredTransformation('RI',8))
[('RI', 8)]

ToneRow.getIntervalsAsString()¶

Returns the string of intervals between consecutive pitch classes of a ToneRow. ‘T’ = 10, ‘E’ = 11.

>>> cRow = serial.pcToToneRow([0])
>>> cRow.getIntervalsAsString()
''
>>> reversechromatic = serial.pcToToneRow([11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0])
>>> reversechromatic.getIntervalsAsString()
'EEEEEEEEEEE'

ToneRow.isSameRow(row)¶

Convenience function describing if two rows are the same.

>>> row1 = serial.pcToToneRow([6, 7, 8])
>>> row2 = serial.pcToToneRow([-6, 19, 128])
>>> row3 = serial.pcToToneRow([6, 7, -8])
>>> row1.isSameRow(row2)
True
>>> row2.isSameRow(row1)
True
>>> row1.isSameRow(row3)
False

ToneRow.isTwelveToneRow()¶

Describes whether or not a ToneRow constitutes a twelve-tone row. Note that a TwelveToneRow object might not be a twelve-tone row.

>>> serial.pcToToneRow(range(0,12)).isTwelveToneRow()
True
>>> serial.pcToToneRow(range(0,10)).isTwelveToneRow()
False
>>> serial.pcToToneRow([3,3,3,3,3,3,3,3,3,3,3,3]).isTwelveToneRow()
False

ToneRow.makeTwelveToneRow()¶

Convenience function returning a TwelveToneRow with the same pitches. Note that a ToneRow may be created without being a true twelve tone row.

>>> a = serial.pcToToneRow(range(0,11))
>>> type(a)
<class 'music21.serial.ToneRow'>
>>> n = note.Note()
>>> n.pitch.pitchClass = 11
>>> a.append(n)
>>> a = a.makeTwelveToneRow()
...
>>> type(a)
<class 'music21.serial.TwelveToneRow'>

ToneRow.noteNames()¶

Convenience function showing the note names of a ToneRow as a list.

>>> chromatic = serial.pcToToneRow(range(0,12))
>>> chromatic.noteNames()
['C', 'C#', 'D', 'E-', 'E', 'F', 'F#', 'G', 'G#', 'A', 'B-', 'B']
>>> halfStep = serial.pcToToneRow([0,1])
>>> halfStep.noteNames()
['C', 'C#']

ToneRow.originalCenteredTransformation(transformationType, index)¶

Returns a ToneRow giving a transformation of a tone row. Admissible transformations are ‘T’ (transposition), ‘I’ (inversion), ‘R’ (retrograde), and ‘RI’ (retrograde inversion).

In the “original-centered” convention, which is less common than the “zero-centered” convention, the original row is not initially transposed to start on the pitch class 0. Thus, the transformation Tn transposes the original row up by n semitones, and the transformations In, Rn, and RIn first transform the row appropriately (without transposition), then transpose the resulting row by n semitones.

>>> chromatic = serial.pcToToneRow(range(0,12))
>>> chromatic.pitchClasses()
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
>>> chromaticP3 = chromatic.originalCenteredTransformation('T',3)
>>> chromaticP3.pitchClasses()
[3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 1, 2]
>>> chromaticI6 = chromatic.originalCenteredTransformation('I',6)
>>> chromaticI6.pitchClasses()
[6, 5, 4, 3, 2, 1, 0, 11, 10, 9, 8, 7]
>>> schoenberg = serial.getHistoricalRowByName('RowSchoenbergOp26')
>>> schoenberg.pitchClasses()
[3, 7, 9, 11, 1, 0, 10, 2, 4, 6, 8, 5]
>>> schoenbergR8 = schoenberg.originalCenteredTransformation('R',8)
>>> schoenbergR8.pitchClasses()
[1, 4, 2, 0, 10, 6, 8, 9, 7, 5, 3, 11]
>>> schoenbergRI9 = schoenberg.originalCenteredTransformation('RI',9)
>>> schoenbergRI9.noteNames()
['B-', 'G', 'A', 'B', 'C#', 'F', 'E-', 'D', 'E', 'F#', 'G#', 'C']

ToneRow.pitchClasses()¶

Convenience function showing the pitch classes of a ToneRow as a list.

>>> L = [5*i for i in range(0,12)]
>>> quintupleRow = serial.pcToToneRow(L)
>>> quintupleRow
<music21.serial.TwelveToneRow 0x104760780>
>>> quintupleRow.pitchClasses()
[0, 5, 10, 3, 8, 1, 6, 11, 4, 9, 2, 7]
>>> halfStep = serial.pcToToneRow([0, 1])
>>> halfStep.pitchClasses()
[0, 1] 

ToneRow.zeroCenteredTransformation(transformationType, index)¶

Returns a ToneRow giving a transformation of a tone row. Admissible transformationTypes are ‘P’ (prime), ‘I’ (inversion), ‘R’ (retrograde), and ‘RI’ (retrograde inversion).

In the “zero-centered” convention, the transformations Pn and In start on the pitch class n, and the transformations Rn and RIn end on the pitch class n.

>>> chromatic = serial.pcToToneRow(range(0,12))
>>> chromatic.pitchClasses()
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
>>> chromaticP3 = chromatic.zeroCenteredTransformation('P',3)
>>> chromaticP3.pitchClasses()
[3, 4, 5, 6, 7, 8, 9, 10, 11, 0, 1, 2]
>>> chromaticI6 = chromatic.zeroCenteredTransformation('I',6)
>>> chromaticI6.pitchClasses()
[6, 5, 4, 3, 2, 1, 0, 11, 10, 9, 8, 7]
>>> schoenberg = serial.getHistoricalRowByName('RowSchoenbergOp26')
>>> schoenberg.pitchClasses()
[3, 7, 9, 11, 1, 0, 10, 2, 4, 6, 8, 5]
>>> schoenbergR8 = schoenberg.zeroCenteredTransformation('R',8)
>>> schoenbergR8.pitchClasses()
[10, 1, 11, 9, 7, 3, 5, 6, 4, 2, 0, 8]
>>> schoenbergRI9 = schoenberg.zeroCenteredTransformation('RI',9)
>>> schoenbergRI9.noteNames()
['G', 'E', 'F#', 'G#', 'B-', 'D', 'C', 'B', 'C#', 'E-', 'F', 'A']

Methods inherited from Stream:

Methods inherited from StreamCoreMixin:

asTimespans()

coreGatherMissingSpanners()

elementsChanged()

Methods inherited from Music21Object:

ToneRow instance variables

ToneRow.row¶: A list representing the pitch class values of the row.

Instance variables inherited from Stream:

Instance variables inherited from Music21Object:

TwelveToneMatrix¶

class music21.serial.TwelveToneMatrix(*arguments, **keywords)¶

An object representation of a 2-dimensional array of 12 pitches. Internal representation is as a Stream, which stores 12 Streams, each Stream a horizontal row of pitches in the matrix.

This object is commonly used by calling the matrix() method of TwelveToneRow() (or a subclass).

TwelveToneMatrix bases

TwelveToneMatrix read-only properties

Read-only properties inherited from Stream:

Read-only properties inherited from StreamCoreMixin:

spannerBundle

Read-only properties inherited from Music21Object:

classSet

classes

measureNumber

TwelveToneMatrix read/write properties

Read/write properties inherited from Stream:

Read/write properties inherited from Music21Object:

quarterLength

TwelveToneMatrix methods

Methods inherited from Stream:

Methods inherited from StreamCoreMixin:

asTimespans()

coreGatherMissingSpanners()

elementsChanged()

Methods inherited from Music21Object:

TwelveToneMatrix instance variables

Instance variables inherited from Stream:

Instance variables inherited from Music21Object:

TwelveToneRow¶

class music21.serial.TwelveToneRow¶: A Stream representation of a twelve-tone row, capable of producing a 12-tone matrix.

TwelveToneRow bases

TwelveToneRow read-only properties

Read-only properties inherited from Stream:

Read-only properties inherited from StreamCoreMixin:

spannerBundle

Read-only properties inherited from Music21Object:

classSet

classes

measureNumber

TwelveToneRow read/write properties

Read/write properties inherited from Stream:

Read/write properties inherited from Music21Object:

quarterLength

TwelveToneRow methods

TwelveToneRow.areCombinatorial(transType1, index1, transType2, index2, convention)¶

Describes whether or not two transformations of a twelve-tone row are combinatorial.

The first and second arguments describe one transformation, while the third and fourth describe another. One of the zero-centered or original-centered conventions for tone row transformations must be specified in the last argument; see zeroCenteredTransformation() and originalCenteredTransformation() explanations of these conventions.

>>> moses = serial.getHistoricalRowByName('RowSchoenbergMosesAron')
>>> moses.pitchClasses()
[9, 10, 4, 2, 3, 1, 7, 5, 6, 8, 11, 0]
>>> moses.areCombinatorial('P', 1, 'I', 4, 'zero')
True
>>> moses.areCombinatorial('R', 5, 'RI', 6, 'original')
False

TwelveToneRow.findHistorical()¶

Checks if a given music21.serial.TwelveToneRow is the same as any of the historical twelve-tone rows stored by music21: see music21.serial.getHistoricalRowByName(). Returns a list of names of historical rows to which the input row is identical.

>>> row = serial.pcToToneRow([2, 3, 9, 1, 11, 5, 8, 7, 4, 0, 10, 6])
>>> row.findHistorical()
['RowSchoenbergOp32']
>>> chromatic = serial.pcToToneRow(range(0,12))
>>> chromatic.findHistorical()
[]

TwelveToneRow.findTransformedHistorical(convention)¶

Checks if a given music21.serial.TwelveToneRow is a transformation of any of the historical twelve-tone rows stored by music21: see music21.serial.getHistoricalRowByName(). Returns a list of tuples, the tuple consisting of the name of a historical row, and a list of transformations relating the input row to the historical row.

The convention for serial transformations must also be specified as ‘zero’ or ‘original’, as explained in findZeroCenteredTransformations() and findOriginalCenteredTransformations().

>>> row = serial.pcToToneRow([5, 9, 11, 3, 6, 7, 4, 10, 0, 8, 2, 1])
>>> row.findTransformedHistorical('original')
[('RowSchoenbergOp32', [('R', 11)])]

TwelveToneRow.getLinkClassification()¶

Gives the classification number of a Link Chord (as given in http://www.johnlinkmusic.com/LinkChords.pdf), that is, is an all-interval twelve-tone row containing a voicing of the all-trichord hexachord: [0, 1, 2, 4, 7, 8]. In addition, gives a list of sets of five contiguous intervals within the row representing a voicing of the all-trichord hexachord. Note that the interval sets may be transformed.

Named for John Link who discovered them.

>>> bergLyric = serial.getHistoricalRowByName('RowBergLyricSuite')
>>> bergLyric.pitchClasses()
[5, 4, 0, 9, 7, 2, 8, 1, 3, 6, 10, 11]
>>> bergLyric.isAllInterval()
True
>>> bergLyric.getLinkClassification()
(None, [])
>>> link = serial.pcToToneRow([0, 3, 8, 2, 10, 11, 9, 4, 1, 5, 7, 6])
>>> link.getLinkClassification()
(62, ['8352E'])
>>> doubleLink = serial.pcToToneRow([0, 1, 8, 5, 7, 10, 4, 3, 11, 9, 2, 6])
>>> doubleLink.getLinkClassification()
(33, ['236E8', '36E8T'])

TwelveToneRow.isAllInterval()¶

Describes whether or not a TwelveToneRow is an all-interval row.

>>> chromatic = serial.pcToToneRow(range(0,12))
>>> chromatic.pitchClasses()
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
>>> chromatic.isAllInterval()
False
>>> bergLyric = serial.getHistoricalRowByName('RowBergLyricSuite')
>>> bergLyric.pitchClasses()
[5, 4, 0, 9, 7, 2, 8, 1, 3, 6, 10, 11]
>>> bergLyric.isAllInterval()
True

TwelveToneRow.isLinkChord()¶

Describes whether or not a TwelveToneRow is a Link Chord.

>>> bergLyric = serial.getHistoricalRowByName('RowBergLyricSuite')
>>> bergLyric.pitchClasses()
[5, 4, 0, 9, 7, 2, 8, 1, 3, 6, 10, 11]
>>> bergLyric.isAllInterval()
True
>>> bergLyric.isLinkChord()
False
>>> link = serial.pcToToneRow([0, 3, 8, 2, 10, 11, 9, 4, 1, 5, 7, 6])
>>> link.isLinkChord()
True
>>> doubleLink = serial.pcToToneRow([0, 1, 8, 5, 7, 10, 4, 3, 11, 9, 2, 6])
>>> doubleLink.isLinkChord()
True

TwelveToneRow.matrix()¶

Returns a TwelveToneMatrix object for the row. That object can just be printed (or displayed via .show())

>>> src = serial.getHistoricalRowByName('RowSchoenbergOp37')
>>> [p.name for p in src]
['D', 'C#', 'A', 'B-', 'F', 'E-', 'E', 'C', 'G#', 'G', 'F#', 'B']
>>> len(src)
12
>>> s37 = serial.getHistoricalRowByName('RowSchoenbergOp37').matrix()
>>> print(s37)
  0  B  7  8  3  1  2  A  6  5  4  9
  1  0  8  9  4  2  3  B  7  6  5  A
  5  4  0  1  8  6  7  3  B  A  9  2
  4  3  B  0  7  5  6  2  A  9  8  1
...
>>> [str(e.pitch) for e in s37[0]]
['C', 'B', 'G', 'G#', 'E-', 'C#', 'D', 'B-', 'F#', 'F', 'E', 'A']