Import and export of figured bass elements from MEI and musicxml file formats

music21/figuredBass/notation.py

@@ -30,6 +30,27 @@
                      (2,): (6, 4, 2),
                      }
 
+prefixes = ['+', '#', '++', '##']
+suffixes = ['\\']
+
+modifiersDictXmlToM21 = {'sharp': '#',
+                 'flat': 'b',
+                 'natural': '\u266e',
+                 'double-sharp': '##',
+                 'flat-flat': 'bb',
+                 'backslash': '\\',
+                 'slash': '/'}
+
+modifiersDictM21ToXml = {'#': 'sharp',
+                     'b': 'flat',
+                     '##': 'double-sharp',
+                     'bb': 'flat-flat',
+                     '\\': 'backslash',
+                     '+': 'sharp',
+                     '\u266f': 'sharp',
+                     '\u266e': 'natural',
+                     '\u266d': 'flat',
+                     '\u20e5': 'sharp'}
 
 class Notation(prebase.ProtoM21Object):
     '''
@@ -79,6 +100,7 @@ class Notation(prebase.ProtoM21Object):
 
     * '13' -> '13,11,9,7,5,3'
 
+    * '_' -> treated as an extender
 
     Figures are saved in order from left to right as found in the notationColumn.
 
@@ -104,11 +126,11 @@ class Notation(prebase.ProtoM21Object):
      <music21.figuredBass.notation.Modifier + sharp>,
      <music21.figuredBass.notation.Modifier None None>)
     >>> n1.figures[0]
-    <music21.figuredBass.notation.Figure 6 <Modifier None None>>
+    <music21.figuredBass.notation.Figure 6 Mods: <Modifier None None> hasExt: False>
     >>> n1.figures[1]
-    <music21.figuredBass.notation.Figure 4 <Modifier + sharp>>
+    <music21.figuredBass.notation.Figure 4 Mods: <Modifier + sharp> hasExt: False>
     >>> n1.figures[2]
-    <music21.figuredBass.notation.Figure 2 <Modifier None None>>
+    <music21.figuredBass.notation.Figure 2 Mods: <Modifier None None> hasExt: False>
 
 
     Here, a stand-alone '#' is being passed to Notation.
@@ -121,9 +143,9 @@ class Notation(prebase.ProtoM21Object):
     (<music21.figuredBass.notation.Modifier None None>,
      <music21.figuredBass.notation.Modifier # sharp>)
     >>> n2.figures[0]
-    <music21.figuredBass.notation.Figure 5 <Modifier None None>>
+    <music21.figuredBass.notation.Figure 5 Mods: <Modifier None None> hasExt: False>
     >>> n2.figures[1]
-    <music21.figuredBass.notation.Figure 3 <Modifier # sharp>>
+    <music21.figuredBass.notation.Figure 3 Mods: <Modifier # sharp> hasExt: False>
 
 
     Now, a stand-alone b is being passed to Notation as part of a larger notationColumn.
@@ -136,9 +158,9 @@ class Notation(prebase.ProtoM21Object):
     (<music21.figuredBass.notation.Modifier b flat>,
      <music21.figuredBass.notation.Modifier b flat>)
     >>> n3.figures[0]
-    <music21.figuredBass.notation.Figure 6 <Modifier b flat>>
+    <music21.figuredBass.notation.Figure 6 Mods: <Modifier b flat> hasExt: False>
     >>> n3.figures[1]
-    <music21.figuredBass.notation.Figure 3 <Modifier b flat>>
+    <music21.figuredBass.notation.Figure 3 Mods: <Modifier b flat> hasExt: False>
     '''
     _DOC_ORDER = ['notationColumn', 'figureStrings', 'numbers', 'modifiers',
                   'figures', 'origNumbers', 'origModStrings', 'modifierStrings']
@@ -189,12 +211,14 @@ def __init__(self, notationColumn=None):
         self.origModStrings = None
         self.numbers = None
         self.modifierStrings = None
+        self.hasExtenders = False
         self._parseNotationColumn()
         self._translateToLonghand()
 
         # Convert to convenient notation
         self.modifiers = None
         self.figures = None
+        self.figuresFromNotationColumn = None
         self._getModifiers()
         self._getFigures()
 
@@ -227,8 +251,8 @@ def _parseNotationColumn(self):
         '''
         delimiter = '[,]'
         figures = re.split(delimiter, self.notationColumn)
-        patternA1 = '([0-9]*)'
-        patternA2 = '([^0-9]*)'
+        patternA1 = '([0-9_]*)'
+        patternA2 = '([^0-9_]*)'
         numbers = []
         modifierStrings = []
         figureStrings = []
@@ -248,7 +272,11 @@ def _parseNotationColumn(self):
             number = None
             modifierString = None
             if m1:
-                number = int(m1[0].strip())
+                if '_' in m1:
+                    self.hasExtenders = True
+                    number = '_'
+                else:
+                    number = int(m1[0].strip())
             if m2:
                 modifierString = m2[0].strip()
 
@@ -357,9 +385,9 @@ def _getFigures(self):
         >>> from music21.figuredBass import notation as n
         >>> notation2 = n.Notation('-6,-')  #__init__ method calls _getFigures()
         >>> notation2.figures[0]
-        <music21.figuredBass.notation.Figure 6 <Modifier - flat>>
+        <music21.figuredBass.notation.Figure 6 Mods: <Modifier - flat> hasExt: False>
         >>> notation2.figures[1]
-        <music21.figuredBass.notation.Figure 3 <Modifier - flat>>
+        <music21.figuredBass.notation.Figure 3 Mods: <Modifier - flat> hasExt: False>
         '''
         figures = []
 
@@ -371,6 +399,14 @@ def _getFigures(self):
 
         self.figures = figures
 
+        figuresFromNotaCol = []
+
+        for i, number in enumerate(self.origNumbers):
+            modifierString = self.origModStrings[i]
+            figure = Figure(number, modifierString)
+            figuresFromNotaCol.append(figure)
+
+        self.figuresFromNotationColumn = figuresFromNotaCol
 
 class NotationException(exceptions21.Music21Exception):
     pass
@@ -387,7 +423,7 @@ class Figure(prebase.ProtoM21Object):
     >>> from music21.figuredBass import notation
     >>> f1 = notation.Figure(4, '+')
     >>> f1
-    <music21.figuredBass.notation.Figure 4 <Modifier + sharp>>
+    <music21.figuredBass.notation.Figure 4 Mods: <Modifier + sharp> hasExt: False>
 
     >>> f1.number
     4
@@ -416,10 +452,12 @@ def __init__(self, number=1, modifierString=None):
         self.number = number
         self.modifierString = modifierString
         self.modifier = Modifier(modifierString)
+        # look for extenders underscore
+        self.isExtender: bool = (self.number == '_')
 
     def _reprInternal(self):
         mod = repr(self.modifier).replace('music21.figuredBass.notation.', '')
-        return f'{self.number} {mod}'
+        return f'{self.number} Mods: {mod} hasExt: {self.isExtender}'
 
 
 # ------------------------------------------------------------------------------
@@ -433,6 +471,10 @@ def _reprInternal(self):
                     '++': '##',
                     '+++': '###',
                     '++++': '####',
+                    '\u266f': '#',
+                    '\u266e': 'n',
+                    '\u266d': 'b',
+                    '\u20e5': '#'
                     }
 
 

music21/harmony.py

@@ -31,6 +31,7 @@
 from music21 import environment
 from music21 import exceptions21
 from music21.figuredBass import realizerScale
+from music21.figuredBass import notation
 from music21 import interval
 from music21 import key
 from music21 import pitch
@@ -2492,6 +2493,33 @@ def transpose(self: NCT, _value, *, inPlace=False) -> NCT | None:
 
 # ------------------------------------------------------------------------------
 
+class FiguredBassIndication(Harmony):
+    isFigure = True
+    tstamp = 1
+    def __init__(self, figs: str | list | None = None, **keywords):
+        super().__init__(**keywords)
+        if figs:
+            if isinstance(figs, list):
+                _figs: str = ','.join(figs)
+            elif isinstance(figs, str):
+                if ',' in figs:
+                    _figs = figs
+                else:
+                    _figs = ','.join(figs)
+        else:
+            _figs = ''
+        self._fig_notation = notation.Notation(_figs)
+
+    @property
+    def fig_notation(self) -> notation.Notation:
+        return self._fig_notation
+
+    @fig_notation.setter
+    def fig_notation(self, figs):
+        self._fig_notation = notation.Notation(figs)
+
+    def __repr__(self):
+        return f'<{self.__class__.__name__} figures: {self.fig_notation.notationColumn}>'
 
 def realizeChordSymbolDurations(piece):
     '''

music21/mei/base.py

@@ -199,6 +199,7 @@
 from music21 import stream
 from music21 import spanner
 from music21 import tie
+from music21 import harmony
 
 
 if t.TYPE_CHECKING:
@@ -466,6 +467,17 @@ def allPartsPresent(scoreElem) -> tuple[str, ...]:
             partNs.append(staffDef.get('n'))
     if not partNs:
         raise MeiValidityError(_SEEMINGLY_NO_PARTS)
+
+    # Get information of possible <harm> tags in the score. If there are tags prepare a list to
+    # store them and process them later.
+    # TODO: Maybe to be put in a separate function e.g. like allPartsPresent
+    figuredBassQuery = f'.//{MEI_NS}fb'
+    if scoreElem.findall(figuredBassQuery):
+        environLocal.printDebug('harm tag found!')
+        partNs.append('fb')
+    # here other <harm> elements (e.g. chordsymbols) can be added.
+    # … 'if …'
+
     return tuple(partNs)
 
 
@@ -2493,6 +2505,48 @@ def chordFromElement(elem, slurBundle=None):
 
     return theChord
 
+def harmFromElement(elem, slurBundle=None) -> tuple:
+    # other tags than <fb> to be added…
+    tagToFunction = {f'{MEI_NS}fb': figuredbassFromElement}
+
+    fb_harmony_tag: tuple = ()
+
+    # Collect all elements in a measure and go throug extenders
+    # tstamp has to be used as a duration marker between two elements
+
+    for subElement in _processEmbeddedElements(elem.findall('*'),
+                                               tagToFunction,
+                                               elem.tag, slurBundle):
+        subElement.tstamp = float(elem.get('tstamp'))
+        subElement.offset = subElement.tstamp - 1
+        fb_harmony_tag = (subElement.tstamp - 1, subElement)
+
+    return fb_harmony_tag
+
+def figuredbassFromElement(elem, slurBundle=None) -> harmony.FiguredBassIndication:
+    if elem.get(_XMLID):
+        fb_id = elem.get(_XMLID)
+    fb_notation: str = ''
+    fb_notation_list: list[str] = []
+    dauer: float = 0
+    # loop through all child elements and collect <f> tags
+    for subElement in elem.findall('*'):
+        if subElement.tag == f'{MEI_NS}f':
+            if subElement.text is not None:
+                fb_notation_list.append(subElement.text)
+            else:
+                if 'extender' in subElement.attrib.keys():
+                    fb_notation_list.append('_')
+            if 'dur.metrical' in subElement.attrib.keys():
+                dauer = float(subElement.attrib['dur.metrical'])
+
+    # Generate a FiguredBassIndication object and set the collected information
+    fb_notation = ','.join(fb_notation_list)
+    theFbNotation = harmony.FiguredBassIndication(fb_notation)
+    theFbNotation.id = fb_id
+    theFbNotation.duration = duration.Duration(quarterLength=dauer)
+
+    return theFbNotation
 
 def clefFromElement(elem, slurBundle=None):  # pylint: disable=unused-argument
     '''
@@ -3131,10 +3185,12 @@ def measureFromElement(elem, backupNum, expectedNs, slurBundle=None, activeMeter
     '''
     staves = {}
     stavesWaiting = {}  # for staff-specific objects processed before the corresponding staff
+    harmElements: dict = {'fb': []}
 
     # mapping from tag name to our converter function
     staffTag = f'{MEI_NS}staff'
     staffDefTag = f'{MEI_NS}staffDef'
+    harmTag = f'{MEI_NS}harm'
 
     # track the bar's duration
     maxBarDuration = None
@@ -3154,6 +3210,10 @@ def measureFromElement(elem, backupNum, expectedNs, slurBundle=None, activeMeter
                 environLocal.warn(_UNIMPLEMENTED_IMPORT.format('<staffDef>', '@n'))
             else:
                 stavesWaiting[whichN] = staffDefFromElement(eachElem, slurBundle)
+        elif harmTag == eachElem.tag:
+            # get all information stored in <harm> tags
+            harmElements['fb'].append(harmFromElement(eachElem))
+
         elif eachElem.tag not in _IGNORE_UNPROCESSED:
             environLocal.printDebug(_UNPROCESSED_SUBELEMENT.format(eachElem.tag, elem.tag))
 
@@ -3166,6 +3226,10 @@ def measureFromElement(elem, backupNum, expectedNs, slurBundle=None, activeMeter
             # *start* of the <measure> in which it appears.
             staves[whichN].insert(0, eachObj)
 
+    # Add <harm> objects to the staves dict
+    staves['fb'] = harmElements
+    # other childs of <harm> tags can be added here…
+
     # create rest-filled measures for expected parts that had no <staff> tag in this <measure>
     for eachN in expectedNs:
         if eachN not in staves:
@@ -3485,6 +3549,9 @@ def scoreFromElement(elem, slurBundle):
 
     # Get a tuple of all the @n attributes for the <staff> tags in this score. Each <staff> tag
     # corresponds to what will be a music21 Part.
+
+    # UPDATE: If <harm> tags are found, they will also be collected as a separate 'part'
+    # to process them later.
     allPartNs = allPartsPresent(elem)
 
     # This is the actual processing.
@@ -3494,6 +3561,14 @@ def scoreFromElement(elem, slurBundle):
     # We must iterate here over "allPartNs," which preserves the part-order found in the MEI
     # document. Iterating the keys in "parsed" would not preserve the order.
     environLocal.printDebug('*** making the Score')
+
+    # Extract collected <harm> information stored in the dict unter the 'fb' key
+    harms: list[dict] | None = None
+    if 'fb' in parsed.keys():
+        harms = parsed['fb'][0]
+        del parsed['fb']
+        allPartNs = allPartNs[0:-1]
+
     theScore = [stream.Part() for _ in range(len(allPartNs))]
     for i, eachN in enumerate(allPartNs):
         # set "atSoundingPitch" so transposition works
@@ -3502,6 +3577,13 @@ def scoreFromElement(elem, slurBundle):
             theScore[i].append(eachObj)
     theScore = stream.Score(theScore)
 
+    # loop through measures to insert harm elements from harms list at the right offsets
+    if harms:
+        for index, measureOffset in enumerate(theScore.measureOffsetMap().keys()):
+            hms = harms[index]['fb']
+            for h in hms:
+                theScore.insert(measureOffset + h[0], h[1])
+
     # put slurs in the Score
     theScore.append(list(slurBundle))
     # TODO: when all the Slur objects are at the end, they'll only be outputted properly if the