.. _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:: chordToMx(c)

    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 = a.mx
    >>> len(mxNoteList) # get three mxNotes
    3 
    >>> mxNoteList[0].get('chord')
    False 
    >>> mxNoteList[1].get('chord')
    True 
    >>> mxNoteList[2].get('chord')
    True 

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

.. function:: dynamicToMx(d)

    Return an mx direction returns a musicxml.Direction object 

    >>> from music21 import *
    >>> a = dynamics.Dynamic('ppp')
    >>> a._positionRelativeY = -10
    >>> b = a.mx
    >>> 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)
    >>> post[-100:].replace('\n', '')
    '/type>        <dot/>        <notations/>      </note>    </measure>  </part></score-partwise>' 

.. function:: instrumentToMx(i)

    

    >>> from music21 import *
    >>> i = instrument.Celesta()
    >>> mxScorePart = i.mx
    >>> len(mxScorePart.scoreInstrumentList)
    1 
    >>> mxScorePart.scoreInstrumentList[0].instrumentName
    'Celesta' 
    >>> mxScorePart.midiInstrumentList[0].midiProgram
    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)
    >>> post[-100:].replace('\n', '')
    ' <type>quarter</type>        <notations/>      </note>    </measure>  </part></score-partwise>' 

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

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

.. function:: mxToChord(mxNoteList, inputM21=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 

.. function:: mxToDuration(mxNote, inputM21)

    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:: mxToDynamic(mxDirection, inputM21=None)

    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.mx = mxDirection
    >>> a.value
    'ff' 
    >>> 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. 

.. 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:: 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:: mxToStream(mxScore, spannerBundle=None, inputM21=None)

    Translate an mxScore into a music21 Score 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. 

.. function:: mxToTextExpression(mxDirection)

    Given an mxDirection, create on 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()
    >>> c.mx = b.timeList
    >>> c.numerator
    4 

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

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

.. 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:: restToMxNotes(r)

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

.. function:: streamPartToMx(s, instObj=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 provides a template of meters. 

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

    Create and return a musicxml Score object. 

    >>> 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:: textExpressionToMx(te)

    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` and :class:`~music21.musicxml.Tied` 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 = a.mx
    >>> a = meter.TimeSignature('3/4+2/4')
    >>> b = a.mx

