.. _moduleMusicxml.translate:

music21.musicxml.translate
==========================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.musicxml.translate

Low-level conversion routines between MusicXML and music21.




.. function:: mxToStream(mxScore, spannerBundle=None, inputM21=None)

    Translate an mxScore into a music21 Score object.

    All spannerBundles accumulated at all lower levels are inserted here.



.. function:: streamToMx(s, spannerBundle=None)


    Create and return a musicxml Score object from a Stream or Score

    This is the most common entry point for
    conversion of a Stream to MusicXML. This method is
    called on Stream from the musicxml property.




    >>> from music21 import *
    >>> n1 = note.Note()
    >>> measure1 = stream.Measure()
    >>> measure1.insert(n1)
    >>> s1 = stream.Stream()
    >>> s1.insert(measure1)
    >>> mxScore = musicxml.translate.streamToMx(s1)
    >>> mxPartList = mxScore.get('partList')



.. function:: articulationsAndExpressionsToMx(target, mxNoteList)

    The `target` parameter is the music21 object.



.. function:: chordSymbolToMx(cs)




    >>> from music21 import *
    >>> cs = harmony.ChordSymbol()
    >>> cs.XMLroot = 'E-'
    >>> cs.XMLbass = 'B-'
    >>> cs.XMLinversion = 2
    >>> cs.romanNumeral = 'I64'
    >>> cs.XMLkind = 'major'
    >>> cs.XMLkindStr = 'M'
    >>> cs
    <music21.harmony.ChordSymbol E-/B->
    >>> mxHarmony = musicxml.translate.chordSymbolToMx(cs)
    >>> mxHarmony
    <harmony <root root-step=E root-alter=-1> function=I64 <kind text=M charData=major> inversion=2 <bass bass-step=B bass-alter=-1>>
    ⁠ 
    >>> hd = harmony.ChordStepModification()
    >>> hd.type = 'alter'
    >>> hd.interval = -1
    >>> hd.degree = 3
    >>> cs.addChordStepModification(hd)



    >>> mxHarmony = musicxml.translate.chordSymbolToMx(cs)
    >>> mxHarmony
    <harmony <root root-step=E root-alter=-1> function=I64 <kind text=M charData=major> inversion=2 <bass bass-step=B bass-alter=-1> <degree <degree-value charData=3> <degree-alter charData=-1> <degree-type charData=alter>>>



.. function:: chordToMx(c, spannerBundle=None)


    Returns a List of mxNotes
    Attributes of notes are merged from different locations: first from the
    duration objects, then from the pitch objects. Finally, GeneralNote
    attributes are added



    >>> from music21 import *
    >>> a = chord.Chord()
    >>> a.quarterLength = 2
    >>> b = pitch.Pitch('A-')
    >>> c = pitch.Pitch('D-')
    >>> d = pitch.Pitch('E-')
    >>> e = a.pitches = [b, c, d]
    >>> len(e)
    3
    >>> mxNoteList = musicxml.translate.chordToMx(a)
    >>> len(mxNoteList) # get three mxNotes
    3
    >>> mxNoteList[0].get('chord')
    False
    >>> mxNoteList[1].get('chord')
    True
    >>> mxNoteList[2].get('chord')
    True
    ⁠ 
    >>> g = note.Note('c4')
    >>> g.notehead = 'diamond'
    >>> h = pitch.Pitch('g3')
    >>> i = chord.Chord([h, g])
    >>> i.quarterLength = 2
    >>> listOfMxNotes = musicxml.translate.chordToMx(i)
    >>> listOfMxNotes[0].get('chord')
    False
    >>> listOfMxNotes[1].noteheadObj.get('charData')
    'diamond'




    >>> rn = roman.RomanNumeral('V', key.Key('A-'))
    >>> rn.pitches
    [E-5, G5, B-5]



.. function:: codaToMx(rm)

    Returns a musicxml.Direction object



    >>> from music21 import *



.. function:: configureMxPartGroupFromStaffGroup(staffGroup)

    Create and configure an mxPartGroup object from a staff group spanner. Note that this object is not completely formed by this procedure.



.. function:: configureStaffGroupFromMxPartGroup(staffGroup, mxPartGroup)

    Given an already instantiated spanner.StaffGroup, configure it with parameters from an mxPartGroup.



.. function:: durationToMusicXML(d)

    Translate a music21 :class:`~music21.duration.Duration` into a complete MusicXML representation.



.. function:: durationToMx(d)


    Translate a music21 :class:`~music21.duration.Duration` object to a list
    of one or more MusicXML :class:`~music21.musicxml.Note` objects.


    All rhythms and ties necessary in the MusicXML Notes are configured. The returned mxNote objects are incompletely specified, lacking full representation and information on pitch, etc.




    >>> from music21 import *
    >>> a = duration.Duration()
    >>> a.quarterLength = 3
    >>> b = musicxml.translate.durationToMx(a)
    >>> len(b) == 1
    True
    >>> isinstance(b[0], musicxmlMod.Note)
    True




    >>> a = duration.Duration()
    >>> a.quarterLength = .33333333
    >>> b = musicxml.translate.durationToMx(a)
    >>> len(b) == 1
    True
    >>> isinstance(b[0], musicxmlMod.Note)
    True





    >>> a = duration.Duration()
    >>> a.quarterLength = .625
    >>> b = musicxml.translate.durationToMx(a)
    >>> len(b) == 2
    True
    >>> isinstance(b[0], musicxmlMod.Note)
    True





    >>> a = duration.Duration()
    >>> a.type = 'half'
    >>> a.dotGroups = [1,1]
    >>> b = musicxml.translate.durationToMx(a)
    >>> len(b) == 2
    True
    >>> isinstance(b[0], musicxmlMod.Note)
    True




.. function:: durationToMxGrace(d, mxNoteList)

    Given a music21 duration and a list of mxNotes, edit the mxNotes in place if the duration is a GraceDuration



.. function:: dynamicToMx(d)


    Return an mx direction
    returns a musicxml.Direction object



    >>> from music21 import *
    >>> a = dynamics.Dynamic('ppp')
    >>> a.volumeScalar
    0.15
    >>> a._positionRelativeY = -10
    >>> b = musicxml.translate.dynamicToMx(a)
    >>> b[0][0][0].get('tag')
    'ppp'
    >>> b[1].get('tag')
    'sound'
    >>> b[1].get('dynamics')
    '19'




.. function:: generalNoteToMusicXML(n)

    Translate a music21 :class:`~music21.note.Note` into a complete MusicXML representation.



    >>> from music21 import *
    >>> n = note.Note('c3')
    >>> n.quarterLength = 3
    >>> post = musicxml.translate.generalNoteToMusicXML(n)



.. function:: instrumentToMx(i)




    >>> from music21 import *
    >>> i = instrument.Celesta()
    >>> mxScorePart = musicxml.translate.instrumentToMx(i)
    >>> len(mxScorePart.scoreInstrumentList)
    1
    >>> mxScorePart.scoreInstrumentList[0].instrumentName
    'Celesta'
    >>> mxScorePart.midiInstrumentList[0].midiProgram
    9



.. function:: intervalToMXTranspose(int)

    Convert a music21 Interval into a musicxml transposition specification



    >>> from music21 import *
    >>> musicxml.translate.intervalToMXTranspose(interval.Interval('m6'))
    <transpose diatonic=5 chromatic=8>
    >>> musicxml.translate.intervalToMXTranspose(interval.Interval('-M6'))
    <transpose diatonic=-5 chromatic=-9>



.. function:: lyricToMx(l)

    Translate a music21 :class:`~music21.note.Lyric` object to a MusicXML :class:`~music21.musicxml.Lyric` object.



.. function:: measureToMusicXML(m)

    Translate a music21 Measure into a complete MusicXML string representation.

    Note: this method is called for complete MusicXML representation of a Measure, not for partial solutions in Part or Stream production.



    >>> from music21 import *
    >>> m = stream.Measure()
    >>> m.repeatAppend(note.Note('g3'), 4)
    >>> post = musicxml.translate.measureToMusicXML(m)



.. function:: measureToMx(m, spannerBundle=None, mxTranspose=None)

    Translate a :class:`~music21.stream.Measure` to a MusicXML :class:`~music21.musicxml.Measure` object.



.. function:: mxCreditToTextBox(mxCredit)

    Convert a MusicXML credit to a music21 TextBox



    >>> from music21 import *
    >>> c = musicxml.Credit()
    >>> c.append(musicxml.CreditWords('testing'))
    >>> c.set('page', 2)
    >>> tb = musicxml.translate.mxCreditToTextBox(c)
    >>> tb.page
    2
    >>> tb.content
    'testing'



.. function:: mxDirectionToSpanners(targetLast, mxDirection, spannerBundle)

    Some spanners, such as MusicXML octave-shift, are encoded as MusicXML directions.



.. function:: mxGraceToGrace(noteOrChord, mxGrace=None)

    Given a completely formed, non-grace Note or Chord, create and return a m21 grace version of the same.

    If mxGrace is None, no change is made and the same object is returned.



.. function:: mxNotationsToSpanners(target, mxNotations, spannerBundle)

    General routines for gathering spanners from notes via mxNotations objects and placing them in a spanner bundle.

    Spanners may be found in musicXML notations and directions objects.

    The passed-in spannerBundle will be edited in-place; existing spanners may be completed, or new spanners may be added.

    The `target` object is a reference to the relevant music21 object this spanner is associated with.



.. function:: mxOrnamentToOrnament(mxOrnament)

    Convert mxOrnament into a music21 ornament. This only processes non-spanner ornaments. Many mxOrnaments are spanners: these are handled elsewhere.

    Returns None if cannot be converted or not defined.



.. function:: mxToChord(mxNoteList, inputM21=None, spannerBundle=None)


    Given an a list of mxNotes, fill the necessary parameters




    >>> from music21 import *
    >>> a = musicxml.Note()
    >>> a.setDefaults()
    >>> b = musicxml.Note()
    >>> b.setDefaults()
    >>> b.set('chord', True)
    >>> m = musicxml.Measure()
    >>> m.setDefaults()
    >>> a.external['measure'] = m # assign measure for divisions ref
    >>> a.external['divisions'] = m.external['divisions']
    >>> b.external['measure'] = m # assign measure for divisions ref
    >>> b.external['divisions'] = m.external['divisions']
    >>> c = chord.Chord()
    >>> c.mx = [a, b]
    >>> len(c.pitches)
    2
    ⁠ 
    >>> from music21 import *
    >>> a = musicxml.Note()
    >>> a.setDefaults()
    >>> nh1 = musicxml.Notehead()
    >>> nh1.set('charData', 'diamond')
    >>> a.noteheadObj = nh1
    >>> b = musicxml.Note()
    >>> b.setDefaults()
    >>> b.set('chord', True)
    >>> m = musicxml.Measure()
    >>> m.setDefaults()
    >>> a.external['measure'] = m # assign measure for divisions ref
    >>> a.external['divisions'] = m.external['divisions']
    >>> b.external['measure'] = m # assign measure for divisions ref
    >>> b.external['divisions'] = m.external['divisions']
    >>> c = musicxml.translate.mxToChord([a, b])
    >>> c.getNotehead(c.pitches[0])
    'diamond'




.. function:: mxToChordSymbol(mxHarmony)


.. function:: mxToCoda(mxCoda)

    Translate a MusicXML :class:`~music21.musicxml.Coda` object to a music21 :class:`~music21.repeat.Coda` object.



.. function:: mxToDuration(mxNote, inputM21=None)

    Translate a MusicXML :class:`~music21.musicxml.Note` object to a music21 :class:`~music21.duration.Duration` object.



    >>> from music21 import *
    >>> a = musicxml.Note()
    >>> a.setDefaults()
    >>> m = musicxml.Measure()
    >>> m.setDefaults()
    >>> a.external['measure'] = m # assign measure for divisions ref
    >>> a.external['divisions'] = m.external['divisions']
    >>> c = duration.Duration()
    >>> musicxml.translate.mxToDuration(a, c)
    <music21.duration.Duration 1.0>
    >>> c.quarterLength
    1.0




.. function:: mxToDynamicList(mxDirection)


    Given an mxDirection, load instance



    >>> from music21 import *
    >>> mxDirection = musicxml.Direction()
    >>> mxDirectionType = musicxml.DirectionType()
    >>> mxDynamicMark = musicxml.DynamicMark('ff')
    >>> mxDynamics = musicxml.Dynamics()
    >>> mxDynamics.set('default-y', -20)
    >>> mxDynamics.append(mxDynamicMark)
    >>> mxDirectionType.append(mxDynamics)
    >>> mxDirection.append(mxDirectionType)
    ⁠ 
    >>> a = dynamics.Dynamic()
    >>> a = musicxml.translate.mxToDynamicList(mxDirection)[0]
    >>> a.value
    'ff'
    >>> a.englishName
    'very loud'
    >>> a._positionDefaultY
    -20



.. function:: mxToInstrument(mxScorePart, inputM21=None)


.. function:: mxToLyric(mxLyric, inputM21=None)

    Translate a MusicXML :class:`~music21.musicxml.Lyric` object to a music21 :class:`~music21.note.Lyric` object.



.. function:: mxToMeasure(mxMeasure, spannerBundle=None, inputM21=None)

    Translate an mxMeasure (a MusicXML :class:`~music21.musicxml.Measure` object)
    into a music21 :class:`~music21.stream.Measure`.

    If an `inputM21` object reference is provided, this object will be
    configured and returned; otherwise, a new :class:`~music21.stream.Measure` object is created.

    The `spannerBundle` that is passed in is used to accumulate any created Spanners.
    This Spanners are not inserted into the Stream here.




.. function:: mxToNote(mxNote, spannerBundle=None, inputM21=None)

    Translate a MusicXML :class:`~music21.musicxml.Note` to a :class:`~music21.note.Note`.

    The `spanners` parameter can be a list or a Stream for storing and processing Spanner objects.



.. function:: mxToOffset(mxDirection, mxDivisions)

    Translate a MusicXML :class:`~music21.musicxml.Direction` with an offset value to an offset in music21.



.. function:: mxToPitch(mxNote, inputM21=None)


    Given a MusicXML Note object, set this Pitch object to its values.



    >>> from music21 import *
    >>> b = musicxml.Pitch()
    >>> b.set('octave', 3)
    >>> b.set('step', 'E')
    >>> b.set('alter', -1)
    >>> c = musicxml.Note()
    >>> c.set('pitch', b)
    >>> a = pitch.Pitch('g#4')
    >>> a = musicxml.translate.mxToPitch(c)
    >>> print(a)
    E-3



.. function:: mxToRepeat(mxBarline, inputM21=None)

    Given an mxBarline, file the necessary parameters



    >>> from music21 import *
    >>> mxRepeat = musicxml.Repeat()
    >>> mxRepeat.set('direction', 'backward')
    >>> mxRepeat.get('times') == None
    True
    >>> mxBarline = musicxml.Barline()
    >>> mxBarline.set('barStyle', 'light-heavy')
    >>> mxBarline.set('repeatObj', mxRepeat)
    >>> b = bar.Repeat()
    >>> b.mx = mxBarline

    Test that the music21 style for a backwards repeat is called "final"
    (because it resembles a final barline) but that the musicxml style
    is called light-heavy.



    >>> b.style
    'final'
    >>> b.direction
    'end'
    >>> b.mx.get('barStyle')
    'light-heavy'



.. function:: mxToRepeatExpression(mxDirection)

    Given an mxDirection that may define a coda, segno, or other repeat expression statement, realize the appropriate music21 object.



.. function:: mxToRest(mxNote, inputM21=None)

    Translate a MusicXML :class:`~music21.musicxml.Note` object to a :class:`~music21.note.Rest`.

    If an `inputM21` object reference is provided, this object will be configured; otherwise, a new :class:`~music21.note.Rest` object is created and returned.



.. function:: mxToSegno(mxCoda)

    Translate a MusicXML :class:`~music21.musicxml.Coda` object to a music21 :class:`~music21.repeat.Coda` object.



.. function:: mxToStreamPart(mxScore, partId, spannerBundle=None, inputM21=None)

    Load a part into a new Stream or one provided by `inputM21` given an mxScore and a part name.

    The `spannerBundle` reference, when passed in, is used to accumulate Spanners. These are not inserted here.

    Though it is incorrect MusicXML, PDFtoMusic creates empty measures when it should create full
    measures of rests (possibly hidden).  This routine fixes that bug.  See http://musescore.org/en/node/15129



.. function:: mxToTempoIndication(mxMetronome, mxWords=None)

    Given an mxMetronome, convert to either a TempoIndication subclass, either a tempo.MetronomeMark or tempo.MetricModulation.



    >>> from music21 import *
    >>> m = musicxml.Metronome()
    >>> bu = musicxml.BeatUnit('half')
    >>> pm = musicxml.PerMinute(125)
    >>> m.append(bu)
    >>> m.append(pm)
    >>> musicxml.translate.mxToTempoIndication(m)
    <music21.tempo.MetronomeMark Half=125.0>



.. function:: mxToTextExpression(mxDirection)


    Given an mxDirection, create one or more TextExpressions



.. function:: mxToTie(mxNote, inputM21=None)

    Translate a MusicXML :class:`~music21.musicxml.Note` to a music21 :class:`~music21.tie.Tie` object.



.. function:: mxToTimeSignature(mxTimeList, inputM21=None)

    Given an mxTimeList, load this object



    >>> from music21 import *
    >>> a = musicxml.Time()
    >>> a.setDefaults()
    >>> b = musicxml.Attributes()
    >>> b.timeList.append(a)
    >>> c = meter.TimeSignature()
    >>> mxToTimeSignature(b.timeList, c)
    >>> c.numerator
    4



.. function:: mxTransposeToInterval(mxTranspose)

    Convert a MusicXML Transpose object to a music21 Interval object.



    >>> from music21 import *
    >>> t = musicxml.Transpose()
    >>> t.diatonic = -1
    >>> t.chromatic = -2
    >>> musicxml.translate.mxTransposeToInterval(t)
    <music21.interval.Interval M-2>
    ⁠ 
    >>> t = musicxml.Transpose()
    >>> t.diatonic = -5
    >>> t.chromatic = -9
    >>> musicxml.translate.mxTransposeToInterval(t)
    <music21.interval.Interval M-6>



    >>> t = musicxml.Transpose()
    >>> t.diatonic = 3 # a type of 4th
    >>> t.chromatic = 6
    >>> musicxml.translate.mxTransposeToInterval(t)
    <music21.interval.Interval A4>




.. function:: noteToMxNotes(n, spannerBundle=None)


    Translate a music21 :class:`~music21.note.Note` into a
    list of :class:`~music21.musicxml.Note` objects.

    Note that, some note-attached spanners, such as octave shifts, produce direction (and direction types) in this method.



.. function:: noteheadToMxNotehead(obj, defaultColor=None)


    Translate a music21 :class:`~music21.note.Note` object or :class:`~music21.pitch.Pitch` object to a
    into a musicxml.Notehead object.



    >>> from music21 import *
    >>> n = note.Note('C#4')
    >>> n.notehead = 'diamond'
    >>> mxN = musicxml.translate.noteheadToMxNotehead(n)
    >>> mxN.get('charData')
    'diamond'
    ⁠ 
    >>> n1 = note.Note('c3')
    >>> n1.notehead = 'diamond'
    >>> n1.noteheadParen = 'yes'
    >>> n1.noteheadFill = 'no'
    >>> mxN4 = musicxml.translate.noteheadToMxNotehead(n1)
    >>> mxN4._attr['filled']
    'no'
    >>> mxN4._attr['parentheses']
    'yes'



.. function:: ornamentToMx(orn)

    Convert a music21 object to musicxml object; return None if no conversion is possible.



.. function:: pitchToMusicXML(p)


.. function:: pitchToMx(p)


    Returns a musicxml.Note() object



    >>> from music21 import *
    >>> a = pitch.Pitch('g#4')
    >>> c = musicxml.translate.pitchToMx(a)
    >>> c.get('pitch').get('step')
    'G'



.. function:: repeatToMx(r)




    >>> from music21 import *
    >>> b = bar.Repeat(direction='end')
    >>> mxBarline = b.mx
    >>> mxBarline.get('barStyle')
    'light-heavy'



.. function:: restToMxNotes(r)

    Translate a :class:`~music21.note.Rest` to a MusicXML :class:`~music21.musicxml.Note` object configured with a :class:`~music21.musicxml.Rest`.



.. function:: segnoToMx(rm)

    Returns a musicxml.Direction object



    >>> from music21 import *



.. function:: spannersToMx(target, mxNoteList, mxDirectionPre, mxDirectionPost, spannerBundle)

    Convenience routine to create and add MusicXML objects from music21 objects provided as a target and as a SpannerBundle.

    The `target` parameter here may be music21 Note or Chord.
    This may edit the mxNoteList and direction lists in place, and thus returns None.



.. function:: streamPartToMx(part, instStream=None, meterStream=None, refStreamOrTimeRange=None, spannerBundle=None)


    If there are Measures within this stream, use them to create and
    return an MX Part and ScorePart.

    An `instObj` may be assigned from caller; this Instrument is pre-collected
    from this Stream in order to configure id and midi-channel values.

    The `meterStream`, if given, provides a template of meters.



.. function:: tempoIndicationToMx(ti)

    Given a music21 MetronomeMark or MetricModulation, produce a musicxml Metronome tag wrapped in a <direction> tag.



    >>> from music21 import *
    >>> mm = tempo.MetronomeMark("slow", 40, note.HalfNote())
    >>> mxList = musicxml.translate.tempoIndicationToMx(mm)
    >>> mxList
    [<direction <direction-type <metronome parentheses=no <beat-unit charData=half> <per-minute charData=40>>> <sound tempo=80.0>>, <direction <direction-type <words default-y=45.0 font-weight=bold justify=left charData=slow>>>]
    ⁠ 
    >>> mm = tempo.MetronomeMark("slow", 40, duration.Duration(quarterLength=1.5))
    >>> mxList = musicxml.translate.tempoIndicationToMx(mm)
    >>> mxList
    [<direction <direction-type <metronome parentheses=no <beat-unit charData=quarter> <beat-unit-dot > <per-minute charData=40>>> <sound tempo=60.0>>, <direction <direction-type <words default-y=45.0 font-weight=bold justify=left charData=slow>>>]




.. function:: textBoxToMxCredit(textBox)

    Convert a music21 TextBox to a MusicXML Credit.



    >>> from music21 import *
    >>> tb = text.TextBox('testing')
    >>> tb.positionVertical = 500
    >>> tb.positionHorizontal = 500
    >>> tb.page = 3
    >>> mxCredit = musicxml.translate.textBoxToMxCredit(tb)
    >>> print mxCredit
    <credit page=3 <credit-words halign=center default-y=500 default-x=500 valign=top charData=testing>>




.. function:: textExpressionToMx(te)

    Convert a TextExpression to a MusicXML mxDirection type.
    returns a musicxml.Direction object



.. function:: tieToMx(t)


    Translate a music21 :class:`~music21.tie.Tie` object to
    MusicXML :class:`~music21.musicxml.Tie` (representing sound) and
    :class:`~music21.musicxml.Tied` (representing notation)
    objects as two component lists.




.. function:: timeSignatureToMusicXML(ts)


.. function:: timeSignatureToMx(ts)

    Returns a single mxTime object.

    Compound meters are represented as multiple pairs of beat
    and beat-type elements



    >>> from music21 import *
    >>> a = meter.TimeSignature('3/4')
    >>> b = timeSignatureToMx(a)
    >>> a = meter.TimeSignature('3/4+2/4')
    >>> b = timeSignatureToMx(a)



