Overview: Meters, Time Signatures, and Processing Beams, Accents, and Beats

Meters and time signatures are represented in music21 as groups of nested hierarchical structures. In many cases, the default configuration of a music21 TimeSignature object will do what you want. However, by configuring the fundamental component objects, the MeterTerminal and MeterSequence objects, a wide range of options are available.

The TimeSignature object additionally features numerous high-level methods to provide access to and configuration of display, beaming, beat, and accent information.

This overview will illustrate key features of music21’s meter objects. For complete documentation of these objects, see music21.meter.

For a more formal discussion of these designs, see the paper “Modeling Beats, Accents, Beams, and Time Signatures Hierarchically with music21 Meter Objects” (Ariza and Cuthbert 2010), at the following URL: http://mit.edu/music21/papers/2010MeterObjects.pdf

Basic Time Signature

While the full structure and configuration options of TimeSignature objects will be discussed below, a few quick demonstrations will get you up and running quickly with the many common tasks.

Getting Time Signatures From Parts and Measures

In general, TimeSignature objects are found within Measure objects (a Stream subclass). However, in some cases TimeSignature objects can exist directly on a Stream.

TimeSignature objects, as a subclass of the Music21Object, have an offset and can be positioned anywhere on a Stream. When placed in a Measure, TimeSignature objects are often placed at the start, or zero offset position. The Measure property timeSignature can be used to set or get a TimeSignature at the zero offset position. If a Measure does not have a TimeSignature, the timeSignature property returns None.

In the following example, a score is parsed from the music21.corpus module parse() function. The alto Part Stream is accessed by its identification string, ‘Alto,’ using the getElementById() method. We can produce notation output of this Part by calling the show() method.

>>> from music21 import *
>>> sSrc = corpus.parse('bach/bwv57.8.xml')
>>> sPart = sSrc.getElementById('Alto')
>>> sPart.show()  

To examine the TimeSignature object active for this part, there are a few approaches. One method is to simply search for the class within all objects in the Part, or the flattened Part Stream representation. Remember that a Part is generally built of Measures, or Stream-embedded containers. To get all the elements in the Stream we can use the flat property, and then search for a class with the getElementsByClass() method. This returns a new Stream containing all found classes. The first element in this Stream is the TimeSignature.

>>> sPart.flat.getElementsByClass(meter.TimeSignature)[0]
<music21.meter.TimeSignature 3/4>

Alternatively, we can look at the first Measure in the Stream, and examine the timeSignature property. Notice that the second Measure does not have a TimeSignature.

>>> sPart.getElementsByClass('Measure')[0].timeSignature
<music21.meter.TimeSignature 3/4>
>>> sPart.getElementsByClass('Measure')[1].timeSignature == None

Setting a Time Signature in a Measure

We can create a new TimeSignature object by providing a string representation of the meter. In most cases, intuitive string-based time signature representations will give you the expected results. Assigning a new TimeSignature object, however, simple associated it with a Measure: it will not automatically rebar or reposition notes within bars. For example, the same part examined above can be modified. Here, the first Measure’s timeSignature property is set to a new object. Note that, when viewing the Part, the time signature is changed even though the position of the notes in Measures is not changed.

>>> sPart.getElementsByClass('Measure')[0].timeSignature = meter.TimeSignature('5/4')
>>> sPart.show()   

Rebaring with Changing Time Signatures

To actually change the position of the notes, creating new Measures with new TimeSignatures, we need to rebar the music. The simplest way to do this is to get all the notes from a Part using the notesAndRests property on a flat Stream representation. Then, by inserting a new TimeSignature at the start of this Stream using the insert() method, we can generate new notation with the show() method. Note that here we are not creating Measures directly; instead, we are assigning TimeSignature objects into a Stream of notes. When the show() method is called, Measures are created within a temporary Stream according to the relevant TimeSignature objects.

>>> sNew = sPart.flat.notesAndRests
>>> sNew.insert(0, meter.TimeSignature('2/4'))
>>> sNew.show()   

The notesAndRests property, while useful, only gathers Notes, Rests, or other subclasses of GeneralNote. Notice that, in the above example, the KeySignature and Insturment objects, as apparent in the notation, have been removed.

If we want to get all elements in the Stream except those that are a specific class, the getElementsNotOfClass() method can be used. In the example below, we gather all elements that are not TimeSignature objects, and then assign a new TimeSignature to the new Stream.

>>> sNew = sPart.flat.getElementsNotOfClass(meter.TimeSignature)
>>> sNew.insert(0, meter.TimeSignature('2/4'))
>>> sNew.show()    

We can continue to add multiple TimeSignature objects to this Stream of Notes. First, we will replace the 2/4 bar previously added with a new TimeSignature, using the Stream replace() method. Then, we will insert a number of additional TimeSignature objects at offsets further into the Stream. Again, as this Stream has no Measures, temporary Measures are automatically created when calling the show() method.

>>> ts = sNew.getTimeSignatures()[0]
>>> ts
<music21.meter.TimeSignature 2/4>
>>> sNew.replace(ts, meter.TimeSignature('5/8'))
>>> sNew.insert(10, meter.TimeSignature('7/8'))
>>> sNew.insert(17, meter.TimeSignature('9/8'))
>>> sNew.insert(26, meter.TimeSignature('3/8'))
>>> sNew.show()   

If we wanted to apply this sequence of TimeSignature objects to a complete score, we can extract all the TimeSignature objects from our new Stream with the getTimeSignatures() method.

>>> tsStream = sNew.getTimeSignatures()
>>> tsStream.show('t')
{0.0} <music21.meter.TimeSignature 5/8>
{10.0} <music21.meter.TimeSignature 7/8>
{17.0} <music21.meter.TimeSignature 9/8>
{26.0} <music21.meter.TimeSignature 3/8>

We can then iterate through the Part objects in the source Stream, get a flat representation of notes, and use the makeMeasures() method to create new Parts. The makeMeasures() method can take an optional Stream of TimeSignature objects that are used to configure the making of Measures.

After Measure creation, Notes need to be split and extend with ties. the Stream makeTies() method can be used. These new Parts can be added to a new Stream and displayed.

>>> sRebar = stream.Stream()
>>> for part in sSrc.getElementsByClass('Part'):
...     newPart = part.flat.getElementsNotOfClass('TimeSignature')
...     newPart = newPart.makeMeasures(tsStream)
...     newPart.makeTies(inPlace=True)
...     sRebar.insert(0, newPart)
>>> sRebar.show()   

Finding the Beat of a Note in a Measure

If a Note is in a Measure, and that Measure or a preceding Measure has a TimeSignature, it is possible to find the beat, or the position of the Note in terms of the count of whole or fractional subdivisions of top-level beat partitions.

The Note beat property will return, if available, a numerical representation of the beat, with a floating point value corresponding to the proportional position through the beat. The Note beatStr property returns a string representation, replacing floating point values with fractions when available.

>>> sSrc = corpus.parse('bach/bwv57.8.xml')
>>> sPart = sSrc.getElementById('Soprano')
>>> sPart.flat.notesAndRests[0]
<music21.note.Note B->
>>> sPart.flat.notesAndRests[4].beat
>>> sPart.flat.notesAndRests[4].beatStr
'2 1/2'

We can annotate each Note in the Part with the string returned by beatStr using the Note addLyric method.

>>> for n in sPart.flat.notesAndRests:
...     n.addLyric(n.beatStr)
>>> sPart.show()    

If we change the TimeSignature in a Part, the beat counts will reflect this change. For example, if the Bass part of the same chorale is re-barred in 6/8, new, syncopated beat counts will be given.

>>> sPart = sSrc.getElementById('Alto')
>>> sPart = sPart.flat.getElementsNotOfClass(meter.TimeSignature)
>>> sMeasures = sPart.makeMeasures(meter.TimeSignature('6/8'))
>>> sMeasures.makeTies(inPlace=True)
>>> for n in sMeasures.flat.notesAndRests:
...     n.addLyric(n.beatStr)
>>> sMeasures.show()   

Objects for Organizing Hierarchical Partitions

Hierarchical metrical structures can be described as a type of fractional, space-preserving tree structure. With such a structure we partition and divide a single duration into one or more parts, where each part is a fraction of the whole. Each part can, in turn, be similarly divided. The objects for configuring this structure are the MeterTerminal and the MeterSequence objects.

MeterTerminal and the MeterSequence objects are for advanced configuration. For basic data access about common meters, see the discussion of TimeSignature, below.

Creating and Editing MeterTerminal Objects

A MeterTerminal is a node of the metrical tree structure, defined as a duration expressed as a fraction of a whole note. Thus, 1/4 is 1 quarter length (QL) duration; 3/8 is 1.5 QL; 3/16 is 0.75 QL. For this model, denominators are limited to n = 2 x, for x between 1 and 7 (e.g. 1/1 to 1/128).

MeterTerminals can additionally store a weight, or a numerical value that can be interpreted in a variety of different ways.

The following examples in the Python interpreter demonstrate creating a MeterTerminal and accessing the numerator and denominator attributes. The duration attribute stores a Duration object.

>>> from music21 import meter
>>> mt = meter.MeterTerminal('3/4')
>>> mt
<MeterTerminal 3/4>
>>> mt.numerator, mt.denominator
(3, 4)
>>> mt.duration.quarterLength

A MeterTerminal can be broken into an ordered sequence of MeterTerminal objects that sum to the same duration. This new object, to be discussed below, is the MeterSequence. A MeterTerminal can be broken into these duration-preserving components with the subdivide() method. An argument for subdivision can be given as a desired number of equal-valued components, a list of numerators assuming equal-denominators, or a list of string fraction representations.

>>> mt.subdivide(3)
<MeterSequence {1/4+1/4+1/4}>
>>> mt.subdivide([3,3])
<MeterSequence {3/8+3/8}>
>>> mt.subdivide(['1/4','4/8'])
<MeterSequence {1/4+4/8}>

Creating and Editing MeterSequence Objects

A MeterSequence object is a sub-class of a MeterTerminal. Like a MeterTerminal, a MeterSequence has a numerator, a denominator, and a duration attribute. A MeterSequence, however, can be a hierarchical tree or sub-tree, containing an ordered sequence of MeterTerminal and/or MeterSequence objects.

The ordered collection of MeterTerminal and/or MeterSequence objects can be accessed like Python lists. MeterSequence objects, like MeterTerminal objects, store a weight that by default is the sum of constituent weights.

The partition() and subdivide() methods can be used to configure the nested hierarchical structure.

The partition() method replaces existing MeterTerminal or MeterSequence objects in place with a new arrangement, specified as a desired number of equal-valued components, a list of numerators assuming equal-denominators, or a list of string fraction representations.

The subdivide() method returns a new MeterSequence (leaving the source MeterSequence unchanged) with an arrangement of MeterTerminals as specified by an argument in the same form as for the partition() method.

Note that MeterTerminal objects cannot be partitioned in place. A common way to convert a MeterTerminal into a MeterSequence is to reassign the returned MeterSequence from the subdivide() method to the position occupied by the MeterTerminal.

The following example creates and partitions a MeterSequence by re-assigning subdivisions to MeterTerminal objects. The use of Python list-like index access is also demonstrated.

>>> ms = meter.MeterSequence('3/4')
>>> ms
<MeterSequence {3/4}>
>>> ms.partition([3,3])
>>> ms
<MeterSequence {3/8+3/8}>
>>> ms[0]
<MeterTerminal 3/8>
>>> ms[0] = ms[0].subdivide([3,3])
>>> ms[0]
<MeterSequence {3/16+3/16}>
>>> ms
<MeterSequence {{3/16+3/16}+3/8}>
>>> ms[1] = ms[1].subdivide([1,1,1])
>>> ms[1][0]
<MeterTerminal 1/8>
>>> ms[1]
<MeterSequence {1/8+1/8+1/8}>
>>> ms
<MeterSequence {{3/16+3/16}+{1/8+1/8+1/8}}>

The resulting structure can be graphically displayed with the following diagram:


Numerous MeterSequence attributes provide convenient ways to access information about, or new objects from, the nested tree structure. The depth attribute returns the depth count at any node within the tree structure; the flat property returns a new, flat MeterSequence constructed from all the lowest-level MeterTerminal objects (all leaf nodes).

>>> ms.depth
>>> ms[0].depth
>>> ms.flat
<MeterSequence {3/16+3/16+1/8+1/8+1/8}>

Numerous methods provide ways to access levels (slices) of the hierarchical structure, or all nodes found at a desired hierarchical level. As all components preserve the duration of their container, all levels have the same total duration. The getLevel() method returns, for a given depth, a new, flat MeterSequence. The getLevelSpan() method returns, for a given depth, the time span of each node as a list of start and end values.

>>> ms.getLevel(0)
<MeterSequence {3/8+3/8}>
>>> ms.getLevel(1)
<MeterSequence {3/16+3/16+1/8+1/8+1/8}>
>>> ms.getLevelSpan(1)
[(0.0, 0.75), (0.75, 1.5), (1.5, 2.0), (2.0, 2.5), (2.5, 3.0)]
>>> ms[1].getLevelSpan(1)
[(0.0, 0.5), (0.5, 1.0), (1.0, 1.5)]

Finally, numerous methods provide ways to find and access the relevant nodes (the MeterTerminal or MeterSequence objects) active given a quarter length position into the tree structure. The offsetToIndex() method returns, for a given QL, the index of the active node. The offsetToSpan() method returns, for a given QL, the span of the active node. The offsetToDepth() method returns, for a given QL, the maximum depth at this position.

>>> ms.offsetToIndex(2.5)
>>> ms.offsetToSpan(2.5)
(1.5, 3.0)
>>> ms.offsetToDepth(.5)
>>> ms[0].offsetToDepth(.5)
>>> ms.getLevel(1).offsetToSpan(.5)
(0, 0.75)

Advanced Time Signature Configuration

The music21 TimeSignature object contains four parallel MeterSequence objects, each assigned to the attributes displaySequence, beatSequence, beamSequence, accentSequence. The following displays a graphical realization of these four MeterSequence objects.


The TimeSignature provides a model of all common hierarchical structures contained within a bar. Common meters are initialized with expected defaults; however, full MeterSequence customization is available.

Configuring Display

The TimeSignature displaySequence MeterSequence employs the highest-level partitions to configure the displayed time signature symbol. If more than one partition is given, those partitions will be interpreted as additive meter components. If partitions have a common denominator, a summed numerator (over a single denominator) can be displayed by setting the TimeSignature summedNumerator attribute to True. Lower-level subdivisions of the TimeSignature MeterSequence are not employed.

Note that a new MeterSequence instance can be assigned to the displaySequence attribute with a duration and/or partitioning completely independent from the beatSequence, beamSequence, and accentSequence MeterSequences.

The following example demonstrates setting the display MeterSequence for a TimeSignature.

>>> ts1 = meter.TimeSignature('5/8') # assumes two partitions
>>> ts1.displaySequence.partition(['3/16','1/8','5/16'])
>>> ts2 = meter.TimeSignature('5/8') # assumes two partitions
>>> ts2.displaySequence.partition(['2/8', '3/8'])
>>> ts2.summedNumerator = True
>>> s = stream.Stream()
>>> for ts in [ts1, ts2]:
...     m = stream.Measure()
...     m.timeSignature = ts
...     n = note.Note('b')
...     n.quarterLength = 0.5
...     m.repeatAppend(n, 5)
...     s.append(m)
>>> s.show()   

Configuring Beam

The TimeSignature beamSequence MeterSequence employs the complete hierarchical structure to configure the single or multi-level beaming of a bar. The outer-most partitions can specify one or more top-level partitions. Lower-level partitions subdivide beam-groups, providing the appropriate beam-breaks when sufficiently small durations are employed.

The beamSequence MeterSequence is generally used to create and configure Beams objects stored in Note objects. The TimeSignature getBeams() method, given a list of Duration objects, returns a list of Beams objects based on the TimeSignature beamSequence MeterSequence.

Many users may find the Stream makeBeams() method the most convenient way to apply beams to a Measure or Stream of Note objects. This method returns a new Stream with created and configured Beams.

The following example beams a bar of 3/4 in four different ways. The diversity and complexity of beaming is offered here to illustrate the flexibility of this model.

>>> ts1 = meter.TimeSignature('3/4')
>>> ts1.beamSequence.partition(1)
>>> ts1.beamSequence[0] = ts1.beamSequence[0].subdivide(['3/8', '5/32', '4/32', '3/32'])
>>> ts2 = meter.TimeSignature('3/4')
>>> ts2.beamSequence.partition(3)
>>> ts3 = meter.TimeSignature('3/4')
>>> ts3.beamSequence.partition(3)
>>> for i in range(len(ts3.beamSequence)):
...     ts3.beamSequence[i] = ts3.beamSequence[i].subdivide(2)
>>> ts4 = meter.TimeSignature('3/4')
>>> ts4.beamSequence.partition(['3/8', '3/8'])
>>> for i in range(len(ts4.beamSequence)):
...     ts4.beamSequence[i] = ts4.beamSequence[i].subdivide(['6/32', '6/32'])
...     for j in range(len(ts4.beamSequence[i])):
...         ts4.beamSequence[i][j] = ts4.beamSequence[i][j].subdivide(2)
>>> s = stream.Stream()
>>> for ts in [ts1, ts2, ts3, ts4]:
...     m = stream.Measure()
...     m.timeSignature = ts
...     n = note.Note('b')
...     n.quarterLength = 0.125
...     m.repeatAppend(n, 24)
...     s.append(m.makeBeams())
>>> s.show()   

The following is a fractional grid representation of the four beam partitions created.


Configuring Beat

The TimeSignature beatSequence MeterSequence employs the hierarchical structure to define the beats and beat divisions of a bar. The outer-most partitions can specify one ore more top level beats. Inner partitions can specify the beat division partitions. For most common meters, beats and beat divisions are pre-configured by default.

In the following example, a simple and a compound meter is created, and the default beat partitions are examined. The getLevel() method can be used to show the beat and background beat partitions. The timeSignature beatDuration, beat, and beatCountName properties can be used to return commonly needed beat information. The TimeSignature beatDivisionCount, and beatDivisionCountName properties can be used to return commonly needed beat division information. These descriptors can be combined to return a string representation of the TimeSignature classification with classification property.

>>> ts = meter.TimeSignature('3/4')
>>> ts.beatSequence.getLevel(0)
<MeterSequence {1/4+1/4+1/4}>
>>> ts.beatSequence.getLevel(1)
<MeterSequence {1/8+1/8+1/8+1/8+1/8+1/8}>
>>> ts.beatDuration
<music21.duration.Duration 1.0>
>>> ts.beatCount
>>> ts.beatCountName
>>> ts.beatDivisionCount
>>> ts.beatDivisionCountName
>>> ts.classification
'Simple Triple'
>>> ts = meter.TimeSignature('12/16')
>>> ts.beatSequence.getLevel(0)
<MeterSequence {3/16+3/16+3/16+3/16}>
>>> ts.beatSequence.getLevel(1)
<MeterSequence {1/16+1/16+1/16+1/16+1/16+1/16+1/16+1/16+1/16+1/16+1/16+1/16}>
>>> ts.beatDuration
<music21.duration.Duration 0.75>
>>> ts.beatCount
>>> ts.beatCountName
>>> ts.beatDivisionCount
>>> ts.beatDivisionCountName
>>> ts.classification
'Compound Quadruple'

Annotating Found Notes with Beat Count

The getBeat() method returns the currently active beat given a quarter length position into the TimeSignature.

In the following example, all leading tones, or C#s, are collected into a new Stream and displayed with annotations for part, measure, and beat.

>>> from music21 import corpus, meter, stream
>>> score = corpus.parse('bach/bwv366.xml')
>>> ts = score.flat.getElementsByClass('TimeSignature')[0]
>>> ts.beatSequence.partition(3)
>>> found = stream.Stream()
>>> offsetQL = 0
>>> for part in score.parts:
...     found.insert(offsetQL, part.flat.getElementsByClass('Clef')[0])
...     for i in range(len(part.getElementsByClass('Measure'))):
...         m = part.getElementsByClass('Measure')[i]
...         for n in m.notesAndRests:
...             if n.name == 'C#':
...                 n.addLyric('%s, m. %s' % (part.id[0], m.number))
...                 n.addLyric('beat %s' % ts.getBeat(n.offset))
...                 found.insert(offsetQL, n)
...                 offsetQL += 4
>>> found.show('musicxml')   

Using Beat Depth to Provide Metrical Analysis

Another application of the beatSequence MeterSequence is to define the hierarchical depth active for a given note found within the TimeSignature.

The getBeatDepth() method, when set with the optional parameter aligh to “quantize”, shows the number of hierarchical levels that start at or before that point. This value is described by Lerdahl and Jackendoff as metrical analysis.

In the following example, beatSequence MeterSequence is partitioned first into one subdivision, and then each subsequent subdivision into two, down to four layers of partitioning.

The number of hierarchical levels, found with the getBeatDepth() method, is appended to each note with the addLyric() method.

>>> from music21 import corpus, meter
>>> score = corpus.parse('bach/bwv281.xml')
>>> partBass = score.getElementById('Bass')
>>> ts = partBass.flat.getElementsByClass('TimeSignature')[0]
>>> ts.beatSequence.partition(1)
>>> for h in range(len(ts.beatSequence)):
...     ts.beatSequence[h] = ts.beatSequence[h].subdivide(2)
...     for i in range(len(ts.beatSequence[h])):
...         ts.beatSequence[h][i] = ts.beatSequence[h][i].subdivide(2)
...         for j in range(len(ts.beatSequence[h][i])):
...             ts.beatSequence[h][i][j] = ts.beatSequence[h][i][j].subdivide(2)
>>> for m in partBass.getElementsByClass('Measure'):
...     for n in m.notesAndRests:
...         for i in range(ts.getBeatDepth(n.offset)):
...             n.addLyric('*')
>>> partBass.getElementsByClass('Measure')[0:7].show()  

Alternatively, this type of annotation can be applied to a Stream using the labelBeatDepth() function.

Configuring Accent

The TimeSignature accentSequence MeterSequence defines one or more levels of hierarchical accent levels, where quantitative accent value is encoded in MeterTerminal or MeterSequence with a number assigned to the weight attribute.

Applying Articulations Based on Accent

The getAccentWeight() method returns the currently active accent weight given a quarter length position into the TimeSignature. Combined with the getBeatProgress() method, Notes that start on particular beat can be isolated and examined.

The following example extracts the Bass line of a Bach chorale in 3/4 and, after repartitioning the beat and accent attributes, applies accents to reflect a meter of 6/8.

>>> from music21 import corpus, meter, articulations
>>> score = corpus.parse('bach/bwv366.xml')
>>> partBass = score.getElementById('Bass')
>>> ts = partBass.flat.getElementsByClass(meter.TimeSignature)[0]
>>> ts.beatSequence.partition(['3/8', '3/8'])
>>> ts.accentSequence.partition(['3/8', '3/8'])
>>> ts.setAccentWeight([1, .5])
>>> for m in partBass.getElementsByClass('Measure'):
...     lastBeat = None
...     for n in m.notesAndRests:
...         beat, progress = ts.getBeatProgress(n.offset)
...         if beat != lastBeat and progress == 0:
...             if n.tie != None and n.tie.type == 'stop':
...                 continue
...             if ts.getAccentWeight(n.offset) == 1:
...                 mark = articulations.StrongAccent()
...             elif ts.getAccentWeight(n.offset) == .5:
...                 mark = articulations.Accent()
...             n.articulations.append(mark)
...             lastBeat = beat
...         m = m.sorted
>>> partBass.getElementsByClass('Measure')[0:8].show()