music21.humdrum.spineParser

music21.humdrum.spineParser is a collection of utilities for changing native Humdrum code into music21 streams. Most music21 users will simply want to call:

>>> myFile = converter.parse('myFile.krn')
>>> myFile.show()

The methods in here are documented for developers wishing to expand music21’s ability to parse humdrum.

SpineParsing consists of several steps.

  • The data file is read in and all events are sliced horizontally (EventCollections)

    and vertically (Protospines)

  • Protospines are parsed into HumdrumSpines by following Spine Path Indicators

    (*^ and *v especially) Protospines that separate become new Protospines with their parentSpine indicated. Protospines that merge again are then followed by the same Protospine as before. This will cause problems if a voice re-merges with another staff, but in practice I have not seen a .krn file that does this and should be avoided in any case.

  • HumdrumSpines are reclassed according to their exclusive definition.

    **kern becomes KernSpines, etc.

  • All reclassed HumdrumSpines are filled with music21 objects in their .stream property.

    Measures are put into the spine but are empty containers. The resulting HumdrumSpine.stream objects look like Stream.flatten(retainContainers=True) versions in many ways.

  • For HumdrumSpines with parent spines their .stream contents are then

    inserted into their parent spines with voice tagged as a music21 Group property.

  • Lyrics and Dynamics are placed into their corresponding HumdrumSpine.stream objects.

  • Stream elements are moved into their measures within a Stream.

  • Measures are searched for elements with voice groups and Voice objects are created.

  • Changed in v10: flag attributes isSpineLine, isComment, isGlobal, isReference have been

    removed from HumdrumLine and all subclasses. isinstance(...) is a bit slower than checking these, but adds correct typing. Nothing is stored with weakrefs. .iterIndex and hand rolled iterator/generators are gone now (could’ve gone when Python 2.4 became the minimum version). HumdrumDataCollection.parsePositionInStream is gone (was duplicating numLines); HumdrumDataCollection.fileLength is now the read-only property numLines (= len(self.dataStream)); HumdrumLine.position and SpineEvent.position were both renamed to lineNumber and now hold the 1-based source line number (was eventList index for SpineEvent), advancing on blank lines too. Blank lines now produce BlankLine HumdrumLine entries rather than being skipped, so eventList[lineNumber - 1] always resolves to the line at that source position.

BlankLine

class music21.humdrum.spineParser.BlankLine(lineNumber: int = 0)[source]

A blank line in a Humdrum source. Humdrum forbids blank lines, but they appear in the wild. Storing them as BlankLine objects keeps eventList aligned with the source: eventList[lineNumber - 1] is always the HumdrumLine at that 1-based source line.

Treated as a global event by parseProtoSpinesAndEventCollections (no SpineEvent is created at this line for any spine).

>>> b = humdrum.spineParser.BlankLine(lineNumber=12)
>>> b
<music21.humdrum.spineParser.BlankLine line 12>
>>> b.lineNumber
12

BlankLine bases

BlankLine read-only properties

Read-only properties inherited from ProtoM21Object:

DynamSpine

class music21.humdrum.spineParser.DynamSpine(spineId: int = 0, eventList: list[SpineEvent] | None = None, streamClass: type[Stream] = <class 'music21.stream.base.Stream'>, parentSpineCollection: SpineCollection | None = None)[source]

A DynamSpine is a type of Humdrum spine with the **dynam attribute set and thus events are processed as if they are dynamics.

DynamSpine bases

DynamSpine read-only properties

Read-only properties inherited from ProtoM21Object:

DynamSpine read/write properties

Read/write properties inherited from HumdrumSpine:

DynamSpine methods

DynamSpine.parse() → None[source]

Dummy method that pushes all these objects to HumdrumSpine.stream as ElementWrappers. Should be overridden in specific Spine subclasses.

Methods inherited from HumdrumSpine:

EventCollection

class music21.humdrum.spineParser.EventCollection(maxSpines: int = 0, lineNumber: int = 0)[source]

An EventCollection holds every event that appears on a single source line of a Humdrum file – one cell per spine, in their events array.

If a spine’s cell on this line is ‘.’ or a comment (no new event), use lastEvents[spineNum] to retrieve the previous event still sounding. getSpineOccurring returns either the current event or the last event that’s still active.

These events should happen at the same time (offset) but they are not necessarily the only events to happen at that same time. E.g. a clef change and the note that follows it on the next line take place at the same musical time but live in different EventCollections.

These objects normally get created by parseProtoSpinesAndEventCollections() so you won’t need to do all the setup.

Assume that ec1 is

C4 pp

on source line 4, and ec2 is

D4 .

on source line 5:

>>> SE = humdrum.spineParser.SpineEvent
>>> eventList1 = [SE('C4', lineNumber=4), SE('pp', lineNumber=4)]
>>> eventList2 = [SE('D4', lineNumber=5), SE('.', lineNumber=5)]
>>> ec1 = humdrum.spineParser.EventCollection(maxSpines=2, lineNumber=4)
>>> ec1.events = eventList1
>>> ec2 = humdrum.spineParser.EventCollection(maxSpines=2, lineNumber=5)
>>> ec2.events = eventList2
>>> ec2.lastEvents[1] = eventList1[1]
>>> ec2.maxSpines
2
>>> ec2.lineNumber
5
>>> ec2.getAllOccurring()
[<music21.humdrum.spineParser.SpineEvent D4>, <music21.humdrum.spineParser.SpineEvent pp>]

If there were spine path markers this next boolean would be true:

>>> ec2.spinePathData
False

In the future, EventCollection may enforce that all events have the same lineNumber

  • New in v10: lineNumber.

EventCollection bases

EventCollection read-only properties

Read-only properties inherited from ProtoM21Object:

EventCollection methods

EventCollection.addGlobalEvent(globalEvent: HumdrumLine) → None[source]
EventCollection.addLastSpineEvent(spineNum: int, spineEvent: SpineEvent) → None[source]
EventCollection.addSpineEvent(spineNum: int, spineEvent: SpineEvent) → None[source]
EventCollection.getAllOccurring() → list[SpineEvent | None][source]
EventCollection.getSpineEvent(spineNum: int) → SpineEvent | None[source]
EventCollection.getSpineOccurring(spineNum: int) → SpineEvent | None[source]

GlobalComment

class music21.humdrum.spineParser.GlobalComment(comment: str = '', **keywords)[source]

A Music21Object that represents a comment for the whole score.

>>> sc = humdrum.spineParser.GlobalComment('!! this is a global comment')
>>> sc
<music21.humdrum.spineParser.GlobalComment 'this is a global comment'>
>>> sc.comment
'this is a global comment'

GlobalComment bases

GlobalComment read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

GlobalComment read/write properties

Read/write properties inherited from Music21Object:

GlobalComment methods

Methods inherited from Music21Object:

GlobalComment instance variables

Instance variables inherited from Music21Object:

GlobalCommentLine

class music21.humdrum.spineParser.GlobalCommentLine(lineNumber: int = 0, contents: str = '')[source]

A GlobalCommentLine is a Humdrum comment that pertains to all spines. In Humdrum it is represented by two exclamation points (and usually one space).

The GlobalComment object takes two inputs and stores them as attributes:

lineNumber (1-based line number in the Humdrum file)
contents   (string of contents)
value      (contents minus !!)

The constructor can be passed (lineNumber, contents); if contents begins with bangs, they are removed along with up to one space directly afterwards.

>>> com1 = humdrum.spineParser.GlobalCommentLine(
...          lineNumber=4, contents='!! this comment is global')
>>> com1
<music21.humdrum.spineParser.GlobalCommentLine 'this comment is global'>
>>> com1.lineNumber
4
>>> com1.contents
'!! this comment is global'
>>> com1.value
'this comment is global'

GlobalCommentLine bases

GlobalCommentLine read-only properties

Read-only properties inherited from ProtoM21Object:

GlobalReference

class music21.humdrum.spineParser.GlobalReference(codeOrAll: str = '', valueOrNone: str | None = None, **keywords)[source]

A Music21Object that represents a reference in the score, called a “reference record” in Humdrum. See Humdrum User’s Guide Chapter 2.

>>> sc = humdrum.spineParser.GlobalReference('!!!REF:this is a global reference')
>>> sc
<music21.humdrum.spineParser.GlobalReference REF 'this is a global reference'>
>>> sc.code
'REF'
>>> sc.value
'this is a global reference'

Alternate form:

>>> sc = humdrum.spineParser.GlobalReference('REF', 'this is a global reference')
>>> sc
<music21.humdrum.spineParser.GlobalReference REF 'this is a global reference'>
>>> sc.code
'REF'
>>> sc.value
'this is a global reference'

Language codes are parsed:

>>> sc = humdrum.spineParser.GlobalReference('!!!OPT@@RUS: Vesna svyashchennaya')
>>> sc.code
'OPT'
>>> sc.language
'RUS'
>>> sc.isPrimary
True

>>> sc = humdrum.spineParser.GlobalReference('!!!OPT@FRE: Le sacre du printemps')
>>> sc.code
'OPT'
>>> sc.language
'FRE'
>>> sc.isPrimary
False

GlobalReference bases

GlobalReference read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

GlobalReference read/write properties

Read/write properties inherited from Music21Object:

GlobalReference methods

GlobalReference.updateMetadata(md: Metadata) → None[source]

update a metadata object according to information in this GlobalReference

See Humdrum guide Appendix I for information

Methods inherited from Music21Object:

GlobalReference instance variables

Instance variables inherited from Music21Object:

GlobalReferenceLine

class music21.humdrum.spineParser.GlobalReferenceLine(lineNumber: int = 0, contents: str = '!!! NUL: None')[source]

A GlobalReferenceLine is a type of HumdrumLine that contains information/metadata about the Humdrum document.

In Humdrum it is represented by three exclamation points followed by non-whitespace followed by a colon. Examples:

!!!COM: Stravinsky, Igor Fyodorovich
!!!CDT: 1882/6/17/-1971/4/6
!!!ODT: 1911//-1913//; 1947//
!!!OPT@@RUS: Vesna svyashchennaya
!!!OPT@FRE: Le sacre du printemps

The GlobalReferenceLine object takes two inputs:

lineNumber   1-based line number in the Humdrum file
contents     string of contents

And stores them as three attributes:

lineNumber: as above
code:       non-whitespace code (usually three letters)
value:      its value

>>> gr = humdrum.spineParser.GlobalReferenceLine(
...        lineNumber=20, contents='!!!COM: Stravinsky, Igor Fyodorovich\n')
>>> gr
<music21.humdrum.spineParser.GlobalReferenceLine COM: 'Stravinsky, Igor Fyodorovich'>
>>> gr.lineNumber
20
>>> gr.code
'COM'
>>> gr.value
'Stravinsky, Igor Fyodorovich'

TODO: add parsing of three-digit Kern comment codes into fuller metadata TODO: parse @/@@ language tags here (e.g. !!!OPT@@RUS:, !!!OPT@FRE:) and propagate language/isPrimary so that GlobalReference.updateMetadata can attach metadata.Text(value, language=...) instead of bare strings.

GlobalReferenceLine bases

GlobalReferenceLine read-only properties

Read-only properties inherited from ProtoM21Object:

HarmSpine

class music21.humdrum.spineParser.HarmSpine(spineId: int = 0, eventList: list[SpineEvent] | None = None, streamClass: type[Stream] = <class 'music21.stream.base.Stream'>, parentSpineCollection: SpineCollection | None = None)[source]

A HarmSpine is a type of Humdrum spine with the **harm attribute set and thus events are processed as if they are harmonic analysis annotations in the “harm” syntax.

The harm roman numeral annotations are parsed using a superset of the original **harm Humdrum representation, written for python and extending the syntax based on other projects like the RomanText and the MuseScore roman numeral notations.

HarmSpine bases

HarmSpine read-only properties

Read-only properties inherited from ProtoM21Object:

HarmSpine read/write properties

Read/write properties inherited from HumdrumSpine:

HarmSpine methods

HarmSpine.parse() → None[source]

Dummy method that pushes all these objects to HumdrumSpine.stream as ElementWrappers. Should be overridden in specific Spine subclasses.

Methods inherited from HumdrumSpine:

HumdrumDataCollection

class music21.humdrum.spineParser.HumdrumDataCollection(dataStream: str | list[str])[source]

Note

Most users should not need to be here. Just run converter.parse('file.krn') and it will give you a stream.Score instead. Intermediate users who want to get into the guts of Humdrum are still probably better off running humdrum.parseFile(“filename”) which returns a humdrum.SpineCollection directly.

A HumdrumDataCollection takes in a mandatory list where each element is a line of Humdrum data. Together this list represents a collection of spines. Essentially it’s the contents of a Humdrum file.

Usually you will probably want to use HumdrumFile which can read in a file directly. This class exists in case you have your Humdrum data in another format (database, from the web, etc.) and already have it as a string.

LIMITATIONS: (1) Spines cannot change definition (**exclusive interpretations) mid-spine.

So if you start off with **kern, the rest of the spine needs to be **kern (actually, the first exclusive interpretation for a spine is used throughout).

Note that, even though changing exclusive interpretations mid-spine seems to be legal by the Humdrum definition, it looks like none of the conventional Humdrum parsing tools allow for changing definitions mid-spine, so I don’t think this limitation is a problem. (Craig Stuart Sapp confirmed this to me.)

The Aarden/Miller Palestrina dataset uses *- followed by **kern at the changes of sections thus some parsing of multiple exclusive interpretations in a protospine may be necessary. But none change definition.

  1. Split spines are assumed to be voices in a single spine staff.

HumdrumDataCollection bases

HumdrumDataCollection read-only properties

HumdrumDataCollection.numLines

The number of lines in self.dataStream, including blank lines.

Read-only properties inherited from ProtoM21Object:

HumdrumDataCollection methods

HumdrumDataCollection.createHumdrumSpines(protoSpines: list[ProtoSpine] | None = None, eventCollections: list[EventCollection] | None = None) → SpineCollection[source]

Takes the data from the object’s protoSpines and eventCollections and returns a SpineCollection object that contains HumdrumSpine() objects.

A HumdrumSpine object differs from a ProtoSpine in that it follows spinePathData – a ProtoSpine records all data in a given tab position, and thus might consist of data from several spines that move around. HumdrumSpines are smart enough not to have this limitation.

When we check for spinePathData we look for the following spine path indicators (from HumdrumDoc):

*+    add a new spine (to the right of the current spine)
*-    terminate a current spine
*^    split a spine (into two)
*v    join (two or more) spines into one
*x    exchange the position of two spines
*     do nothing
HumdrumDataCollection.determineIfDataStreamIsOpus(dataStream: list[str] | None = None) → tuple[bool, list[list[str]] | None][source]

Some Humdrum files contain multiple pieces in one file which are better represented as an Opus file containing multiple scores.

This method examines the dataStream (or self.dataStream) and if it only has a single piece then it returns (False, None).

If it has multiple pieces, it returns True and a list of dataStreams.

>>> from pprint import pprint as pp

>>> mps = humdrum.testFiles.multipartSanctus
>>> hdc = humdrum.spineParser.HumdrumDataCollection(mps)
>>> (hasOpus, dataCollections) = hdc.determineIfDataStreamIsOpus()
>>> hasOpus
True
>>> pp(dataCollections)
[['!!!COM: Palestrina, Giovanni Perluigi da',
  '**kern\t**kern\t**kern\t**kern',
  '*Ibass\t*Itenor\t*Icalto\t*Icant',
  '!Bassus\t!Tenor\t!Altus\t!Cantus',
  '*clefF4\t*clefGv2\t*clefG2\t*clefG2',
  '*M4/2\t*M4/2\t*M4/2\t*M4/2',
  '=1\t=1\t=1\t=1',
  '0r\t0r\t1g\t1r',
  '.\t.\t1a\t1cc',
  '=2\t=2\t=2\t=2',
  '0r\t0r\t1g\t1dd',
  '.\t.\t1r\t1cc',
  '*-\t*-\t*-\t*-'],
 ['!! Pleni',
  '**kern\t**kern\t**kern',
  '*Ibass\t*Itenor\t*Icalto',
  '*clefF4\t*clefGv2\t*clefG2',
  '*M4/2\t*M4/2\t*M4/2',
  '=3\t=3\t=3',
  '1G\t1r\t0r',
  '1A\t1c\t.',
  '=4\t=4\t=4',
  '1B\t1d\t1r',
  '1c\t1e\t1g',
  '*-\t*-\t*-'],
 ['!! Hosanna',
  '**kern\t**kern\t**kern\t**kern',
  '*Ibass\t*Itenor\t*Icalto\t*Icant',
  '*clefF4\t*clefGv2\t*clefG2\t*clefG2',
  '*M3/2\t*M3/2\t*M3/2\t*M3/2',
  '=5\t=5\t=5\t=5',
  '1r\t1r\t1g\t1r',
  '2r\t2r\t[2a\t[2cc',
  '=5\t=5\t=5\t=5',
  '1r\t1r\t2a]\t2cc]',
  '.\t.\t2f\t1dd',
  '2r\t2r\t2g\t.',
  '*-\t*-\t*-\t*-']]
HumdrumDataCollection.insertGlobalEvents() → None[source]

Insert the Global Events (GlobalReferenceLines and GlobalCommentLines) into an appropriate place in the outer Stream.

Run after self.spineCollection.createMusic21Streams(). Is run automatically by self.parse(). uses self.spineCollection.getOffsetsAndPrioritiesByLineNumber()

HumdrumDataCollection.parse() → Score | Opus[source]

Parse self.dataStream into music21 objects, returning the resulting Score (or Opus for multipart files like the Palestrina dataset).

The parsed stream is also stored on self.stream.

HumdrumDataCollection.parseEventListFromDataStream(dataStream: list[str] | None = None) → list[HumdrumLine][source]

Sets self.eventList from a dataStream (that is, a list of lines). It sets self.maxSpines to the largest number of spine events found on any line in the file.

The differences between the dataStream and self.eventList are the following:

Returns eventList in addition to setting it as self.eventList.

>>> eventString = ('!!! COM: Beethoven, Ludwig van\n'
...                '!! Not really a piece by Beethoven\n'
...                '**kern\t**dynam\n'
...                'C4\tpp\n'
...                'D8\t.\n')
>>> hdc = humdrum.spineParser.HumdrumDataCollection(eventString)
>>> hdc.maxSpines = 2
>>> eList = hdc.parseEventListFromDataStream()
>>> eList is hdc.eventList
True
>>> for e in eList:
...     print(e)
<music21.humdrum.spineParser.GlobalReferenceLine COM: 'Beethoven, Ludwig van'>
<music21.humdrum.spineParser.GlobalCommentLine 'Not really a piece by Beethoven'>
<music21.humdrum.spineParser.SpineLine line 3 (2 spines)>
<music21.humdrum.spineParser.SpineLine line 4 (2 spines)>
<music21.humdrum.spineParser.SpineLine line 5 (2 spines)>
>>> print(eList[0].value)
Beethoven, Ludwig van

Print line number 4 (which is eList[3] in zero indexed)

>>> print(eList[3].spineData)
['C4', 'pp']
HumdrumDataCollection.parseMetadata(s: Stream | None = None) → None[source]

Create a metadata object for the file.

HumdrumDataCollection.parseNonOpus(dataStream: list[str]) → Score[source]

The main parse function for non-opus data collections.

Populates self.stream (a Score) and returns it.

HumdrumDataCollection.parseOpusDataCollections(dataCollections: list[list[str]]) → Opus[source]

Take a dataCollection from determineIfDataStreamIsOpus and set self.stream to be an Opus instead.

>>> mps = humdrum.testFiles.multipartSanctus
>>> hdc = humdrum.spineParser.HumdrumDataCollection(mps)
>>> (hasOpus, dataCollections) = hdc.determineIfDataStreamIsOpus()
>>> if hasOpus is True:
...     op = hdc.parseOpusDataCollections(dataCollections)
...     print(len(op.scores))
...     for sc in op.scores:
...        print(sc)
3
<music21.stream.Score section_1>
<music21.stream.Score section_2>
<music21.stream.Score section_3>
HumdrumDataCollection.parseProtoSpinesAndEventCollections() → tuple[list[ProtoSpine], list[EventCollection]][source]

Run after parseEventListFromDataStream() to take self.eventList and slice it horizontally to get self.eventCollections, which is a list of EventCollection objects, or things that happen simultaneously.

And, more importantly, this method slices self.eventList vertically to get self.protoSpines which is a list of ProtoSpines, that is a vertical slice of everything that happens in a column, regardless of spine-path indicators.

EventCollection objects store global events. ProtoSpines do not.

So self.eventCollections and self.protoSpines can each be thought of as a two-dimensional sheet of cells, but where the first index of the former is the vertical index in the dataStream and the first index of the latter is the horizontal index in the dataStream. The contents of each cell is a SpineEvent object or None (if there’s no data at that point). Even ‘.’ (continuation events) get translated into SpineEvent objects.

Calls parseEventListFromDataStream() if it hasn’t already been called.

Returns a tuple of protoSpines and eventCollections in addition to setting it in the calling object.

>>> eventString = ('!!!COM: Beethoven, Ludwig van\n'
...                '!! Not really a piece by Beethoven\n'
...                '**kern\t**dynam\n'
...                'C4\tpp\n'
...                'D8\t.\n')
>>> hdc = humdrum.spineParser.HumdrumDataCollection(eventString)
>>> hdc.maxSpines = 2
>>> protoSpines, eventCollections = hdc.parseProtoSpinesAndEventCollections()
>>> protoSpines is hdc.protoSpines
True
>>> eventCollections is hdc.eventCollections
True

Looking at individual slices is unlikely to tell you much:

>>> for thisSlice in eventCollections:
...    print(thisSlice)
<music21.humdrum.spineParser.EventCollection line 1, 2 events, 2 spines>
<music21.humdrum.spineParser.EventCollection line 2, 2 events, 2 spines>
<music21.humdrum.spineParser.EventCollection line 3, 2 events, 2 spines>
<music21.humdrum.spineParser.EventCollection line 4, 2 events, 2 spines>
<music21.humdrum.spineParser.EventCollection line 5, 2 events, 2 spines>

>>> for thisSlice in protoSpines:
...    print(thisSlice)
<music21.humdrum.spineParser.ProtoSpine 5 events>
<music21.humdrum.spineParser.ProtoSpine 5 events>

But looking at the individual slices is revealing:

>>> eventCollections[4].getAllOccurring()
[<music21.humdrum.spineParser.SpineEvent D8>, <music21.humdrum.spineParser.SpineEvent pp>]

>>> for protoEvent in protoSpines[0]:
...    print(repr(protoEvent))
None
None
<music21.humdrum.spineParser.SpineEvent **kern>
<music21.humdrum.spineParser.SpineEvent C4>
<music21.humdrum.spineParser.SpineEvent D8>

HumdrumFile

class music21.humdrum.spineParser.HumdrumFile(filename: str | pathlib.Path)[source]

A HumdrumFile is a HumdrumDataCollection which takes as a mandatory argument a filename to be opened and read.

HumdrumFile bases

HumdrumFile read-only properties

Read-only properties inherited from HumdrumDataCollection:

Read-only properties inherited from ProtoM21Object:

HumdrumFile methods

HumdrumFile.parseFileHandle(fileHandle: Iterable[str]) → Score | Opus[source]

Read all lines from fileHandle into self.dataStream, then call parse() and return its result (a Score or Opus).

HumdrumFile.parseFilename(filename: str | pathlib.Path | None = None) → None[source]

Methods inherited from HumdrumDataCollection:

HumdrumLine

class music21.humdrum.spineParser.HumdrumLine[source]

HumdrumLine is a dummy class for subclassing SpineLine, GlobalCommentLine, and GlobalReferenceLine classes all of which represent one horizontal line of text in a HumdrumDataCollection that is aware of its position in the file.

See the documentation for the specific classes mentioned above for more details.

HumdrumLine bases

HumdrumLine read-only properties

Read-only properties inherited from ProtoM21Object:

HumdrumSpine

class music21.humdrum.spineParser.HumdrumSpine(spineId: int = 0, eventList: list[SpineEvent] | None = None, streamClass: type[Stream] = <class 'music21.stream.base.Stream'>, parentSpineCollection: SpineCollection | None = None)[source]

A HumdrumSpine is a representation of a generic HumdrumSpine regardless of **definition after spine path indicators have been simplified.

A subclass of HumdrumSpine should be defined for each **type. Those subclasses cannot redefine __init__()

A HumdrumSpine is a collection of events arranged vertically that have a connection to each other. Each HumdrumSpine MUST have an id (numeric or string) attached to it.

>>> SE = humdrum.spineParser.SpineEvent
>>> spineEvents = [SE('**kern'), SE('c,4'), SE('d#8')]
>>> spine1Id = 5
>>> spine1 = humdrum.spineParser.HumdrumSpine(spine1Id, spineEvents)
>>> spine1.insertPoint = 5
>>> spine1.endingPoint = 6
>>> spine1.parentSpine = 3  # spine 3 is the previous spine leading to this one
>>> spine1.childSpines = [7, 8]  # the spine ends by being split into spines 7 and 8

A spine knows the SpineCollection it belongs to:

>>> spineCollection1 = humdrum.spineParser.SpineCollection()
>>> spine1.parentSpineCollection = spineCollection1

The spineType property searches the EventList or parentSpine to figure out the spineType.

>>> spine1.spineType
'kern'

Spines can be iterated through:

>>> for e in spine1:
...    print(e)
**kern
c,4
d#8

If you’d eventually like this spine to be converted to a class other than Stream, pass its classname in as the streamClass argument:

>>> spine2 = humdrum.spineParser.HumdrumSpine(streamClass=stream.Part)
>>> spine2.stream
<music21.stream.Part ...>

HumdrumSpine bases

HumdrumSpine read-only properties

Read-only properties inherited from ProtoM21Object:

HumdrumSpine read/write properties

HumdrumSpine.spineType

searches the current and parent spineType for a search

HumdrumSpine methods

HumdrumSpine.append(event: SpineEvent) → None[source]

add an item to this Spine

HumdrumSpine.moveElementsIntoMeasures(streamIn: Stream) → Stream[source]

Takes a parsed stream and moves the elements inside the measures. Works with pickup measures, etc. Does not automatically create ties, etc.

Why not just use Stream.makeMeasures()? because Humdrum measures contain extra information about barlines etc. and pickups are explicitly defined.

>>> s1 = stream.Stream()
>>> s1.append(meter.TimeSignature('2/4'))
>>> m1 = stream.Measure()
>>> m1.number = 1
>>> s1.append(m1)
>>> s1.append(note.Note('C4', type='quarter'))
>>> m2 = stream.Measure()
>>> m2.number = 2
>>> s1.append(m2)
>>> s1.append(note.Note('D4', type='half'))
>>> s1.show('text')
{0.0} <music21.stream.Measure 1 offset=0.0>

{0.0} <music21.meter.TimeSignature 2/4>
{0.0} <music21.note.Note C>
{1.0} <music21.stream.Measure 2 offset=1.0>

{1.0} <music21.note.Note D>

>>> hds = humdrum.spineParser.HumdrumSpine()
>>> s2 = hds.moveElementsIntoMeasures(s1)
>>> s2.show('text')
{0.0} <music21.stream.Measure 1 offset=0.0>
    {0.0} <music21.meter.TimeSignature 2/4>
    {0.0} <music21.note.Note C>
{1.0} <music21.stream.Measure 2 offset=1.0>
    {0.0} <music21.note.Note D>

The first measure is correctly identified as a pickup!

>>> s2.measure(1).paddingLeft
1.0
HumdrumSpine.parse() → None[source]

Dummy method that pushes all these objects to HumdrumSpine.stream as ElementWrappers. Should be overridden in specific Spine subclasses.

KernSpine

class music21.humdrum.spineParser.KernSpine(spineId: int = 0, eventList: list[SpineEvent] | None = None, streamClass: type[Stream] = <class 'music21.stream.base.Stream'>, parentSpineCollection: SpineCollection | None = None)[source]

A KernSpine is a type of Humdrum spine with the **kern attribute set and thus events are processed as if they are kern notes.

Instances are not constructed directly; reclassSpines reassigns __class__ from HumdrumSpine to KernSpine once the spine’s exclusive interpretation is known. All KernSpine-specific state is initialized at the top of parse().

  • Changed in v10: currentTupletDuration / desiredTupletDuration

    renamed to currentTupletQL / desiredTupletQL.

KernSpine bases

KernSpine read-only properties

Read-only properties inherited from ProtoM21Object:

KernSpine read/write properties

Read/write properties inherited from HumdrumSpine:

KernSpine methods

KernSpine.parse() → None[source]

Dummy method that pushes all these objects to HumdrumSpine.stream as ElementWrappers. Should be overridden in specific Spine subclasses.

KernSpine.processChordEvent(eventC: str) → Chord[source]

Process a single chord event

Like processNoteEvent, stores information about current beam and tuplet state.

KernSpine.processNoteEvent(eventC: str) → GeneralNote[source]

similar to hdStringToNote, this method processes a string representing a single note, but stores information about current beam and tuplet state.

KernSpine.setBeamsForNote(n: GeneralNote) → None[source]

sets the beams for a Note (or Chord) given self.currentBeamNumbers and updates self.currentBeamNumbers based on stop beams.

Safe enough to use on elements such as rests that don’t have beam info.

KernSpine.setTupletTypeForNote(n: GeneralNote) → None[source]

Methods inherited from HumdrumSpine:

MiscTandem

class music21.humdrum.spineParser.MiscTandem(tandem: str = '', **keywords)[source]

MiscTandem bases

MiscTandem read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

MiscTandem read/write properties

Read/write properties inherited from Music21Object:

MiscTandem methods

Methods inherited from Music21Object:

MiscTandem instance variables

Instance variables inherited from Music21Object:

ProtoSpine

class music21.humdrum.spineParser.ProtoSpine(eventList: list[SpineEvent | None] | None = None)[source]

A ProtoSpine is a collection of events arranged vertically. It differs from a HumdrumSpine in that spine paths are not followed. So ProtoSpine(1) would be everything in the 2nd column of a Humdrum file regardless of whether the 2nd column was at some point an independent Spine or if it later became a split from the first spine.

See parseProtoSpinesAndEventCollections() for more details on how ProtoSpine objects are created.

  • Changed in v10: ProtoSpines now iterate over their eventLists and are ProtoM21Objects.

ProtoSpine bases

ProtoSpine read-only properties

Read-only properties inherited from ProtoM21Object:

SpineCollection

class music21.humdrum.spineParser.SpineCollection[source]

A SpineCollection is a set of HumdrumSpines with relationships to each other and where their position attributes indicate simultaneous onsets.

When you iterate over a SpineCollection, it goes from right to left, since that’s the order that Humdrum expects.

SpineCollection bases

SpineCollection read-only properties

Read-only properties inherited from ProtoM21Object:

SpineCollection methods

SpineCollection.addSpine(streamClass: type[Stream] = <class 'music21.stream.base.Part'>) → HumdrumSpine[source]

creates a new spine in the collection and returns it.

By default, the underlying music21 class of the spine is Part. This can be overridden by passing in a different streamClass.

Automatically sets the id of the Spine.

>>> hsc = humdrum.spineParser.SpineCollection()
>>> newSpine = hsc.addSpine()
>>> newSpine.id
0
>>> newSpine.stream
<music21.stream.Part ...>
>>> newSpine2 = hsc.addSpine(streamClass=stream.Stream)
>>> newSpine2.id
1
>>> newSpine2
<music21.humdrum.spineParser.HumdrumSpine: 1>
>>> newSpine2.stream
<music21.stream.Stream ...>
SpineCollection.appendSpine(spine: HumdrumSpine) → None[source]

appendSpine(spine) – appends an already existing HumdrumSpine to the SpineCollection. Returns void

SpineCollection.assignIds() → None[source]

Assign an ID based on the instrument, or just a string of a number if there is no instrument.

>>> hsc = humdrum.spineParser.SpineCollection()
>>> newSpineDefault = hsc.addSpine()
>>> newSpineDefault2 = hsc.addSpine()
>>> newSpineOboe1 = hsc.addSpine()
>>> newSpineOboe2 = hsc.addSpine()
>>> newSpineTrumpet = hsc.addSpine()
>>> newSpineOboe1.stream.append(instrument.Oboe())
>>> newSpineOboe2.stream.append(instrument.Oboe())
>>> newSpineTrumpet.stream.append(instrument.Trumpet())
>>> hsc.assignIds()
>>> for sp in hsc.spines:
...     print(sp.stream.id)
1
2
Oboe-1
Oboe-2
Trumpet
SpineCollection.attachNonKernEvents() → None[source]

move **dynam and **lyrics/**text information to the appropriate staff.

Assumes that *staff is consistent through the spine.

TODO: misaligned events (a **dynam or **harm whose source line has ‘.’ in the kern column) are silently dropped because the matcher only accepts exact el.priority == event.lineNumber. Desired: when no kern note sits on the same line, attach to the stream at the offset of the most recently-sounding kern note (ideal: between current and next note’s offsets). Lyrics/text continue to attach to notes only. See humdrum.tests.Test.testDynamAttachedMisaligned / testHarmAttachedMisaligned.

SpineCollection.createMusic21Streams() → None[source]

Create Music21 Stream objects from spineCollections by running:

self.reclassSpines() self.parseMusic21() self.performInsertions() self.moveObjectsToMeasures() self.attachNonKernEvents() self.makeVoices() self.assignIds()

SpineCollection.getOffsetsAndPrioritiesByLineNumber() → dict[int, tuple[OffsetQL, list[Music21Object]]][source]

Iterates through the spines by location and records the offset and priority for each element in the spines.

Returns a dictionary keyed by Humdrum line number whose values are two-element tuples: (music21 offset, list of Music21Objects at that line).

SpineCollection.getSpineById(spineId: int) → HumdrumSpine[source]

returns the HumdrumSpine with the given id.

raises a HumdrumException if the spine with a given id is not found

SpineCollection.makeVoices() → None[source]

make voices for each kernSpine – why not just run stream.makeVoices() ? because we have more information here that lets us make voices more intelligently

Should be done after measures have been made.

SpineCollection.moveObjectsToMeasures() → None[source]

run moveElementsIntoMeasures for each HumdrumSpine that is not a sub-spine.

Also fixes up the tuplets using duration.TupletFixer

SpineCollection.parseMusic21() → None[source]

runs spine.parse() for each Spine, thus populating the spine.stream for each Spine.

SpineCollection.performInsertions() → None[source]

Take a parsed spineCollection as Music21Objects and take sub-spines and put them in their proper location.

SpineCollection.performSpineInsertion(thisSpine: HumdrumSpine, newStream: Stream, insertionPoint: int) → None[source]

Insert all the spines into newStream that should be inserted into thisSpine at insertionPoint.

SpineCollection.reclassSpines() → None[source]

Changes the classes of HumdrumSpines to more specific types (KernSpine, DynamicSpine) according to their spineType (e.g., **kern, **dynam)

SpineCollection.removeSpineById(spineId: int) → None[source]

Deletes a spine from the SpineCollection (after inserting, integrating, etc.)

>>> hsc = humdrum.spineParser.SpineCollection()
>>> newSpine = hsc.addSpine()
>>> newSpine.id
0
>>> newSpine2 = hsc.addSpine()
>>> newSpine2.id
1
>>> hsc.spines
[<music21.humdrum.spineParser.HumdrumSpine: 0>,
 <music21.humdrum.spineParser.HumdrumSpine: 1>]
>>> hsc.removeSpineById(newSpine.id)
>>> hsc.spines
[<music21.humdrum.spineParser.HumdrumSpine: 1>]

raises a HumdrumException if the spine with a given id is not found

SpineComment

class music21.humdrum.spineParser.SpineComment(comment: str = '', **keywords)[source]

A Music21Object that represents a comment in a single spine.

>>> sc = humdrum.spineParser.SpineComment('! this is a spine comment')
>>> sc
<music21.humdrum.spineParser.SpineComment 'this is a spine comment'>
>>> sc.comment
'this is a spine comment'

SpineComment bases

SpineComment read-only properties

Read-only properties inherited from Music21Object:

Read-only properties inherited from ProtoM21Object:

SpineComment read/write properties

Read/write properties inherited from Music21Object:

SpineComment methods

Methods inherited from Music21Object:

SpineComment instance variables

Instance variables inherited from Music21Object:

SpineEvent

class music21.humdrum.spineParser.SpineEvent(contents: str = '', lineNumber: int = 0)[source]

A SpineEvent is an event in a HumdrumSpine or ProtoSpine.

Its .contents property contains the contents of the spine, or it could be ‘.’, in which case it means that a particular event appears after the last event in a different spine. It could also be “None” indicating that there is no event at all at this moment in the Humdrum file. Happens if no ProtoSpine exists at this point in the file in this tab position.

Should be initialized with its contents and 1-based source line number.

These attributes are optional but likely to be very helpful:

lineNumber -- 1-based source line number in the Humdrum file
protoSpineId -- ProtoSpine id (0 to N)
spineId -- id of HumdrumSpine actually attached to (after SpinePaths are parsed)

The toNote() method converts the contents into a music21 note as if it’s kern – useful to have in all spine types.

>>> se1 = humdrum.spineParser.SpineEvent('EEE-8')
>>> se1.lineNumber = 40
>>> se1.contents
'EEE-8'
>>> se1
<music21.humdrum.spineParser.SpineEvent EEE-8>
>>> n = se1.toNote()
>>> n
<music21.note.Note E->

SpineEvent bases

SpineEvent read-only properties

Read-only properties inherited from ProtoM21Object:

SpineEvent methods

SpineEvent.toNote(convertString: str | None = None) → GeneralNote[source]

parse the object as a **kern note and return a Note object (or Rest, or Chord)

>>> se = humdrum.spineParser.SpineEvent('DD#4')
>>> n = se.toNote()
>>> n
<music21.note.Note D#>
>>> n.octave
2
>>> n.duration.type
'quarter'

SpineLine

class music21.humdrum.spineParser.SpineLine(lineNumber: int = 0, contents: str = '')[source]

A SpineLine is any horizontal line of a Humdrum file that contains one or more spine elements (separated by tabs) and not Global elements.

Takes in a 1-based line number in the file and a string of contents.

>>> hsl = humdrum.spineParser.SpineLine(
...         lineNumber=7, contents='C4\t!local comment\t*M[4/4]\t.\n')
>>> hsl
<music21.humdrum.spineParser.SpineLine line 7 (4 spines)>
>>> hsl.lineNumber
7
>>> hsl.numSpines
4
>>> hsl.spineData
['C4', '!local comment', '*M[4/4]', '.']

SpineLine bases

SpineLine read-only properties

Read-only properties inherited from ProtoM21Object:

Functions

music21.humdrum.spineParser.hdStringToMeasure(contents: str, previousMeasure: Measure | None = None) → Measure[source]

kern uses an equals sign followed by processing instructions to create new measures.

  • Changed in v10: repeat dots are encoded as Repeat

    objects instead of being stuffed into a non-existent Barline.repeatDots attribute. :|: now produces an end-Repeat on the previous measure’s right barline AND a start-Repeat on the new measure’s left barline.

music21.humdrum.spineParser.hdStringToNote(contents: str, defaultDurationOrNone: Duration | None = None) → GeneralNote[source]

returns a Note (or Rest or Unpitched, etc.) matching the current SpineEvent. Does not check to see that it is sane or part of a **kern spine, etc.

If contents has no written duration, the note takes defaultDurationOrNone when one is given, otherwise a quarter note. This is used for chords whose notes after the first omit a duration, e.g. the E and G in 8C E G. (In practice, all chords with notes of the same duration, such as 16.C 16.E 16.G, will be parsed as if the subsequent notes omit their durations, e.g. as 16.C E G, since processChordEvent removes duration markers from the second and succeeding chord pitches whose durations are identical to the first.)

New rhythmic extensions formerly defined in wiki.humdrum.org/index.php/Rational_rhythms and now at https://extras.humdrum.org/man/rscale/ are fully implemented:

>>> n = humdrum.spineParser.hdStringToNote('CC3%2')
>>> n.duration.quarterLength
Fraction(8, 3)
>>> n.duration.fullName
'Whole Triplet (2 2/3 QL)'

>>> n = humdrum.spineParser.hdStringToNote('e-00.')
>>> n.pitch
<music21.pitch.Pitch E-4>
>>> n.duration.quarterLength
24.0
>>> n.duration.fullName
'Perfect Longa'

>>> n = humdrum.spineParser.hdStringToNote('F#000')
>>> n.duration.quarterLength
32.0
>>> n.duration.fullName
'Imperfect Maxima'

Note that the following example is interpreted as one note in the time of a double-dotted quarter not a double-dotted quarter-note triplet.

I believe that the latter definition, though used in https://kern.humdrum.org/cgi-bin/ksdata?l=musedata/mozart/quartet&file=k421-01.krn&f=kern and the Josquin Research Project [JRP] is incorrect, seeing as it contradicts the specification in https://web.archive.org/web/20100203144730/http://www.music-cog.ohio-state.edu/Humdrum/representations/kern.html#N-Tuplets

This is the default:

>>> humdrum.spineParser.flavors['JRP'] = False

>>> n = humdrum.spineParser.hdStringToNote('6..fff')
>>> n.duration.quarterLength
Fraction(7, 6)

>>> n.duration.dots
0

>>> n.duration.tuplets[0].durationNormal.dots
2

If you want the JRP definition, set humdrum.spineParser.flavors[‘JRP’] = True before calling converter.parse() or anything like that:

>>> humdrum.spineParser.flavors['JRP'] = True
>>> n = humdrum.spineParser.hdStringToNote('6..fff')
>>> n.duration.quarterLength
Fraction(7, 6)
>>> n.duration.dots
2
>>> n.duration.tuplets[0].durationNormal.dots
0

>>> n = humdrum.spineParser.hdStringToNote('gg#q/LL')
>>> n.duration
<music21.duration.GraceDuration unlinked type:eighth quarterLength:0.0>
>>> n.duration.isGrace
True

A grace note without duration is an eighth note. If a duration, like 16, is given, that type is preserved in the unlinked GraceDuration. A single q is a slashed grace note (acciaccatura):

>>> n = humdrum.spineParser.hdStringToNote('16ccq')
>>> n.duration
<music21.duration.GraceDuration unlinked type:16th quarterLength:0.0>
>>> n.duration.slash
True

Two qs signify a grace note without a slash (or accented grace note):

>>> n = humdrum.spineParser.hdStringToNote('16ccqq')
>>> n.duration.type
'16th'
>>> n.duration.slash
False

Note

A capital Q was the original Humdrum way of signifying these notes (gruppettos). Some post-2020 encodings use Q to mean a cue-sized note. Given no way of distinguishing these interpretations, music21 will remain with the original version; so Q and qq are synonyms.

  • Changed in v11: grace notes keep their written duration, and qq is parsed as an unslashed grace note.

music21.humdrum.spineParser.kernTandemToObject(tandem: str) → Music21Object | None[source]

Kern uses symbols such as *M5/4 and *clefG2, etc., to control processing

This method converts them to music21 objects.

>>> m = humdrum.spineParser.kernTandemToObject('*M3/1')
>>> m
<music21.meter.TimeSignature 3/1>

Unknown objects are converted to MiscTandem objects:

>>> m2 = humdrum.spineParser.kernTandemToObject('*TandyUnk')
>>> m2
<music21.humdrum.spineParser.MiscTandem *TandyUnk>