.. _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.

    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
    ⁠ 
    >>> from music21 import *
    >>> 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'




.. 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:: dynamicToMx(d)


    Return an mx direction
    returns a musicxml.Direction object



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



.. 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:: 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:: 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.mx = 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', 'forward')
    >>> mxRepeat.get('times') == None
    True
    >>> mxBarline = musicxml.Barline()
    >>> mxBarline.set('barStyle', 'light-heavy')
    >>> mxBarline.set('repeatObj', mxRepeat)
    >>> b = bar.Repeat()
    >>> b.mx = mxBarline
    >>> b.style
    'final'
    >>> b.direction
    'start'
    >>> 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.



.. 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:: pitchToMusicXML(p)


.. function:: pitchToMx(p)


    Returns a musicxml.Note() object



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



.. function:: repeatToMx(r)




    >>> from music21 import *
    >>> b = bar.Repeat('light-heavy')
    >>> 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



    >>> from music21 import *



.. 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)



