Objects and resources for processing ABC data.
ABC conversion from a file or URL to a Stream is available through the music21 converter module’s parse() function.
>>> from music21 import *
>>> abcScore = converter.parse('/users/ariza/myScore.abc')
Low level ABC conversion is facilitated by the objects in this module and music21.abc.translate.abcToStreamScore().
Given a list of ABCHandlerBar, ruturn a list of ABCHandlerBar objects, where leading metadata is merged, if possible, with the bar data following.
This consolidates all metadata in bar-like entities.
ABC File access
ABCFile methods
- close()¶
No documentation.
- extractReferenceNumber(strSrc, number)¶
Extract a single reference number from many defined in a file. This permits loading a single work from a collection/opus without parsing the entire file.
- open(filename)¶
Open a file for reading
- openFileLike(fileLike)¶
Assign a file-like object, such as those provided by StringIO, as an open file object.
>>> fileLikeOpen = StringIO.StringIO()
- read(number=None)¶
Read a file. Note that this calls readstring, which processes all tokens.
If number is given, a work number will be extracted if possible.
- readstr(strSrc, number=None)¶
Read a string and process all Tokens. Returns a ABCHandler instance.
ABCHandler properties
- tokens¶
Get or set tokens for this Handler
ABCHandler methods
- definesMeasures()¶
Return True if this token structure defines Measures in a normal Measure form.
>>> from music21 import * >>> abcStr = 'M:6/8\nL:1/8\nK:G\nV:1 name="Whistle" snm="wh"\nB3 A3 | G6 | B3 A3 | G6 ||\nV:2 name="violin" snm="v"\nBdB AcA | GAG D3 | BdB AcA | GAG D6 ||\nV:3 name="Bass" snm="b" clef=bass\nD3 D3 | D6 | D3 D3 | D6 ||' >>> ah = abc.ABCHandler() >>> junk = ah.process(abcStr) >>> True == ah.definesMeasures() True >>> abcStr = 'M:6/8\nL:1/8\nK:G\nB3 A3 G6 B3 A3 G6' >>> ah = abc.ABCHandler() >>> junk = ah.process(abcStr) >>> False == ah.definesMeasures() True
- definesReferenceNumbers()¶
Return True if this token structure defines more than 1 reference number.
>>> from music21 import * >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||' >>> ah = abc.ABCHandler() >>> junk = ah.process(abcStr) >>> ah.definesReferenceNumbers() # only one returns false False >>> from music21 import * >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||\nX:6\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||' >>> ah = abc.ABCHandler() >>> junk = ah.process(abcStr) >>> ah.definesReferenceNumbers() # only one returns false True
- getReferenceNumber()¶
If tokens are processed, get the first reference number defined.
>>> from music21 import * >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||' >>> ah = abc.ABCHandler() >>> junk = ah.process(abcStr) >>> ah.getReferenceNumber() '5'
- getTitle()¶
If tokens are processed, get the first title tag. Used for testing.
- hasNotes()¶
If tokens are processed, return True of ABCNote or ABCChord classes are defined
>>> from music21 import * >>> abcStr = 'M:6/8\nL:1/8\nK:G\n' >>> ah1 = abc.ABCHandler() >>> junk = ah1.process(abcStr) >>> ah1.hasNotes() False >>> abcStr = 'M:6/8\nL:1/8\nK:G\nc1D2' >>> ah2 = abc.ABCHandler() >>> junk = ah2.process(abcStr) >>> ah2.hasNotes() True
- process(strSrc)¶
No documentation.
- splitByMeasure()¶
Divide a token list by Measures, also defining start and end bars of each Measure.
If a component does not have notes, leave as an empty bar. This is often done with leading metadata.
Returns a list of ABCHandlerBar instances. The first usually defines only Metadata
- splitByReferenceNumber()¶
Split tokens by reference numbers.
Returns a dictionary of ABCHandler instances, where the reference number is used to access the music. If no reference numbers are defined, the tune is available under the dictionary entry None.
>>> from music21 import * >>> abcStr = 'X:5\nM:6/8\nL:1/8\nK:G\nB3 A3 | G6 | B3 A3 | G6 ||' >>> ah = abc.ABCHandler() >>> junk = ah.process(abcStr) >>> len(ah) 14 >>> ahDict = ah.splitByReferenceNumber() >>> len(ahDict[5].tokens) 14
- splitByVoice()¶
Given a processed token list, look for voices. If voices exist, split into parts: common metadata, then next voice, next voice, etc.
Each part is returned as a ABCHandler instance.
>>> from music21 import * >>> abcStr = 'M:6/8\nL:1/8\nK:G\nV:1 name="Whistle" snm="wh"\nB3 A3 | G6 | B3 A3 | G6 ||\nV:2 name="violin" snm="v"\nBdB AcA | GAG D3 | BdB AcA | GAG D6 ||\nV:3 name="Bass" snm="b" clef=bass\nD3 D3 | D6 | D3 D3 | D6 ||' >>> ah = abc.ABCHandler() >>> junk = ah.process(abcStr) >>> tokenColls = ah.splitByVoice() >>> tokenColls[0] <music21.abc.base.ABCHandler object at 0x...> >>> [t.src for t in tokenColls[0].tokens] # common headers are first ['M:6/8', 'L:1/8', 'K:G'] >>> # then each voice >>> [t.src for t in tokenColls[1].tokens] ['V:1 name="Whistle" snm="wh"', 'B3', 'A3', '|', 'G6', '|', 'B3', 'A3', '|', 'G6', '||'] >>> [t.src for t in tokenColls[2].tokens] ['V:2 name="violin" snm="v"', 'B', 'd', 'B', 'A', 'c', 'A', '|', 'G', 'A', 'G', 'D3', '|', 'B', 'd', 'B', 'A', 'c', 'A', '|', 'G', 'A', 'G', 'D6', '||'] >>> [t.src for t in tokenColls[3].tokens] ['V:3 name="Bass" snm="b" clef=bass', 'D3', 'D3', '|', 'D6', '|', 'D3', 'D3', '|', 'D6', '||']Then later the metadata can be merged at the start of each voice...
>>> mergedTokens = tokenColls[0] + tokenColls[1] >>> mergedTokens <music21.abc.base.ABCHandler object at 0x...> >>> [t.src for t in mergedTokens.tokens] ['M:6/8', 'L:1/8', 'K:G', 'V:1 name="Whistle" snm="wh"', 'B3', 'A3', '|', 'G6', '|', 'B3', 'A3', '|', 'G6', '||']
- tokenProcess()¶
Process all token objects. First, call preParse(), then do cointext assignments, then call parse().
- tokenize(strSrc)¶
Walk the abc string, creating ABC objects along the way.
This may be called separately from process(), in the case that pre/post parse processing is not needed.
Inherits from: ABCHandler
A Handler specialized for storing bars. All left and right bars are collected and assigned to attributes.
ABCHandlerBar attributes
Attributes without Documentation: leftBarToken, rightBarToken
ABCHandlerBar properties
Properties inherited from ABCHandler: tokens
ABCHandlerBar methods
Methods inherited from ABCHandler: definesMeasures(), definesReferenceNumbers(), getReferenceNumber(), getTitle(), hasNotes(), process(), splitByMeasure(), splitByReferenceNumber(), splitByVoice(), tokenProcess(), tokenize()
Inherits from: ABCToken
ABCBar methods
- getBarObject()¶
Return a music21 bar object
>>> from music21 import * >>> ab = abc.ABCBar('|:') >>> ab.parse() >>> post = ab.getBarObject()
- isRegular()¶
Return True if this is a regular, single, light bar line.
>>> from music21 import * >>> ab = abc.ABCBar('|') >>> ab.parse() >>> ab.isRegular() True
- isRepeat()¶
No documentation.
- isRepeatBracket()¶
Return true if this defines a repeat bracket for an alternate ending
>>> from music21 import * >>> ab = abc.ABCBar('[2') >>> ab.parse() >>> ab.isRepeat() False >>> ab.isRepeatBracket() 2
- parse()¶
Assign the bar-type based on the source string.
>>> from music21 import * >>> ab = abc.ABCBar('|') >>> ab.parse() >>> ab.barType 'barline' >>> ab.barStyle 'regular'>>> ab = abc.ABCBar('||') >>> ab.parse() >>> ab.barType 'barline' >>> ab.barStyle 'light-light' >>> ab = abc.ABCBar('|:') >>> ab.parse() >>> ab.barType 'repeat' >>> ab.barStyle 'heavy-light' >>> ab.repeatForm 'start'Methods inherited from ABCToken: preParse(), stripComment()
Inherits from: ABCNote, ABCToken
A representation of an ABC Chord, which contains within its delimiters individual notes.
A subclass of ABCNote.
Inherits from: ABCToken
ABCMetadata attributes
Attributes without Documentation: tag, data
Attributes inherited from ABCToken: src
ABCMetadata methods
- getClefObject()¶
Extract any clef parameters stored in the key metadata token. Assume that a clef definition suggests a transposition. Return both the Clef and the transposition.
>>> from music21 import * >>> am = abc.ABCMetadata('K:Eb Lydian') >>> am.preParse() >>> am._getKeySignatureParameters() (-2, 'lydian')
- getDefaultQuarterLength()¶
If there is a quarter length representation available, return it as a floating point value
>>> from music21 import * >>> am = abc.ABCMetadata('L:1/2') >>> am.preParse() >>> am.getDefaultQuarterLength() 2.0 >>> am = abc.ABCMetadata('L:1/8') >>> am.preParse() >>> am.getDefaultQuarterLength() 0.5>>> am = abc.ABCMetadata('M:C|') >>> am.preParse() >>> am.getDefaultQuarterLength() 0.5 >>> am = abc.ABCMetadata('M:2/4') >>> am.preParse() >>> am.getDefaultQuarterLength() 0.25>>> am = abc.ABCMetadata('M:6/8') >>> am.preParse() >>> am.getDefaultQuarterLength() 0.5
- getKeySignatureObject()¶
Return a music21 KeySignature object for this metadata tag.
>>> from music21 import * >>> am = abc.ABCMetadata('K:G') >>> am.preParse() >>> ks = am.getKeySignatureObject() >>> ks <music21.key.KeySignature of 1 sharp>
- getMetronomeMarkObject()¶
Extract any tempo parameters stored in a tmepo metadata token.
>>> from music21 import * >>> am = abc.ABCMetadata('Q: "Allegro" 1/4=120') >>> am.preParse() >>> am.getMetronomeMarkObject() <music21.tempo.MetronomeMark Allegro Quarter=120.0> >>> am = abc.ABCMetadata('Q: 3/8=50 "Slowly"') >>> am.preParse() >>> am.getMetronomeMarkObject() <music21.tempo.MetronomeMark Slowly Dotted Quarter=50.0>>>> am = abc.ABCMetadata('Q:1/2=120') >>> am.preParse() >>> am.getMetronomeMarkObject() <music21.tempo.MetronomeMark animato Half=120.0> >>> am = abc.ABCMetadata('Q:1/4 3/8 1/4 3/8=40') >>> am.preParse() >>> am.getMetronomeMarkObject() <music21.tempo.MetronomeMark grave Whole tied to Quarter (5.0 total QL)=40.0>>>> am = abc.ABCMetadata('Q:90') >>> am.preParse() >>> am.getMetronomeMarkObject() <music21.tempo.MetronomeMark maestoso Quarter=90.0>
- getTimeSignatureObject()¶
Return a music21 TimeSignature object for this metadata tag.
>>> from music21 import * >>> am = abc.ABCMetadata('M:2/2') >>> am.preParse() >>> ts = am.getTimeSignatureObject() >>> ts <music21.meter.TimeSignature 2/2>
- isComposer()¶
Returns True if the tag is “C” for composer, False otherwise.
- isDefaultNoteLength()¶
Returns True if the tag is “L”, False otherwise.
- isKey()¶
Returns True if the tag is “K”, False otherwise. Note that in some cases a Key will encode clef information.
- isMeter()¶
Returns True if the tag is “M” for meter, False otherwise.
- isOrigin()¶
Returns True if the tag is “O” for origin, False otherwise. This value is set in the Metadata localOfComposition of field.
- isReferenceNumber()¶
Returns True if the tag is “X”, False otherwise.
>>> from music21 import * >>> x = abc.ABCMetadata('X:5') >>> x.preParse() >>> x.tag 'X' >>> x.isReferenceNumber() True
- isTempo()¶
Returns True if the tag is “Q” for tempo, False otherwise.
- isTitle()¶
Returns True if the tag is “T” for title, False otherwise.
- isVoice()¶
Returns True if the tag is “V”, False otherwise.
- parse()¶
No documentation.
- preParse()¶
Called before contextual adjustments and needs to have access to data. Divides a token into .tag (a single capital letter or w) and .data representations.
>>> from music21 import * >>> x = abc.ABCMetadata('T:tagData') >>> x.preParse() >>> x.tag 'T' >>> x.data 'tagData'Methods inherited from ABCToken: stripComment()
Inherits from: ABCToken
A model of an ABCNote.
General usage requires multi-pass processing. After being tokenized, each ABCNote needs a number of attributes updates. Attributes to be updated after tokenizing, and based on the linear sequence of tokens: inBar, inBeam (not used), inSlur (not used), inGrace (not used), activeDefaultQuarterLength, brokenRhythmMarker, and activeKeySignature.
The chordSymbols list stores one or more chord symbols (ABC calls these guitar chords) associated with this note. This attribute is updated when parse() is called.
ABCNote attributes
Attributes without Documentation: brokenRhythmMarker, quarterLength, activeKeySignature, inGrace, chordSymbols, inBeam, pitchName, inSlur, activeTuplet, inBar, isRest, accidentalDisplayStatus, activeDefaultQuarterLength
Attributes inherited from ABCToken: src
ABCNote methods
- parse(forceDefaultQuarterLength=None, forceKeySignature=None)¶
No documentation.
Methods inherited from ABCToken: preParse(), stripComment()
ABC processing works with a multi-pass procedure. The first pass breaks the data stream into a list of ABCToken objects. ABCToken objects are specialized in subclasses.
The multi-pass procedure is conducted by an ABCHandler object. The ABCHandler.tokenize() method breaks the data stream into ABCToken objects. The tokenProcess() method first calls the preParse() method on each token, then does contextual adjustments to all tokens, then calls parse() on all tokens.
The source ABC string itself is stored in self.src
ABCToken attributes
Attributes without Documentation: src
ABCToken methods
- parse()¶
Dummy method that reads self.src and loads attributes. It is called after contextual adjustments.
It is designed to be subclassed or overridden.
- preParse()¶
Dummy method that is called before contextual adjustments. Designed to be subclassed or overridden.
- stripComment(strSrc)¶
removes ABC-style comments from a string:
>>> from music21 import * >>> ao = abc.ABCToken() >>> ao.stripComment('asdf') 'asdf' >>> ao.stripComment('asdf%234') 'asdf' >>> ao.stripComment('asdf % 234') 'asdf ' >>> ao.stripComment('[ceg]% this chord appears 50% more often than other chords do') '[ceg]'
Inherits from: ABCToken
ABCTuplet tokens always precede the notes they describe.
In ABCHandler.tokenProcess(), rhythms are adjusted.
ABCTuplet methods
- updateNoteCount(durationActual=None, durationNormal=None)¶
Update the note count of notes that are affected by this tuplet.
- updateRatio(keySignatureObj=None)¶
Cannot be called until local meter context is established
>>> from music21 import * >>> at = abc.ABCTuplet('(3') >>> at.updateRatio() >>> at.numberNotesActual, at.numberNotesNormal (3, 2) >>> at = abc.ABCTuplet('(5') >>> at.updateRatio() >>> at.numberNotesActual, at.numberNotesNormal (5, 2)>>> at = abc.ABCTuplet('(5') >>> at.updateRatio(meter.TimeSignature('6/8')) >>> at.numberNotesActual, at.numberNotesNormal (5, 3)Methods inherited from ABCToken: parse(), preParse(), stripComment()