.. _moduleMidi.translate:

music21.midi.translate
======================

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

.. module:: music21.midi.translate


Module to translate MIDI data to music21 Streams.  Note that quantization of
notes takes place in the :meth:`~music21.stream.Stream.quantize` method not here.




.. function:: streamToMidiFile(inputM21)


    Converts a Stream to a :class:`~music21.midi.base.MidiFile` object.



    >>> from music21 import *
    >>> s = stream.Stream()
    >>> n = note.Note('g#')
    >>> n.quarterLength = .5
    >>> s.repeatAppend(n, 4)
    >>> mf = midi.translate.streamToMidiFile(s)
    >>> len(mf.tracks)
    1
    >>> len(mf.tracks[0].events)
    22



.. function:: midiFileToStream(mf, inputM21=None)


    Main routine to convert a :class:`~music21.midi.base.MidiFile` object to a
    :class:`~music21.stream.Stream` object.

    The `inputM21` object can specify an existing Stream (or Stream subclass) to fill.



    >>> from music21 import *
    >>> import os
    >>> fp = os.path.join(common.getSourceFilePath(), 'midi', 'testPrimitive',  'test05.mid')
    >>> mf = midi.MidiFile()
    >>> mf.open(fp)
    >>> mf.read()
    >>> mf.close()
    >>> len(mf.tracks)
    1
    >>> s = midi.translate.midiFileToStream(mf)
    >>> s
    <music21.stream.Stream ...>
    >>> len(s.flat.notesAndRests)
    11



.. function:: chordToMidiEvents(inputM21, includeDeltaTime=True)


    Translates a :class:`~music21.chord.Chord` object to a list of midi events (like noteToMidiEvents above)



    >>> from music21 import *
    >>> c = chord.Chord(['c3','g#4', 'b5'])
    >>> eventList = midi.translate.chordToMidiEvents(c)
    >>> eventList
    [<MidiEvent DeltaTime, t=0, track=None, channel=None>, <MidiEvent NOTE_ON, t=None, track=None, channel=1, pitch=48, velocity=90>, <MidiEvent DeltaTime, t=0, track=None, channel=None>, <MidiEvent NOTE_ON, t=None, track=None, channel=1, pitch=68, velocity=90>, <MidiEvent DeltaTime, t=0, track=None, channel=None>, <MidiEvent NOTE_ON, t=None, track=None, channel=1, pitch=83, velocity=90>, <MidiEvent DeltaTime, t=1024, track=None, channel=None>, <MidiEvent NOTE_OFF, t=None, track=None, channel=1, pitch=48, velocity=0>, <MidiEvent DeltaTime, t=0, track=None, channel=None>, <MidiEvent NOTE_OFF, t=None, track=None, channel=1, pitch=68, velocity=0>, <MidiEvent DeltaTime, t=0, track=None, channel=None>, <MidiEvent NOTE_OFF, t=None, track=None, channel=1, pitch=83, velocity=0>]




.. function:: chordToMidiFile(inputM21)


    Similar to `noteToMidiFile`, translates a Chord to a fully-formed MidiFile object.



.. function:: durationToMidi(d)


    Helper function to converts a :class:`~music21.duration.Duration` object to midi ticks.

    Depends on *defaults.ticksPerQuarter*, Returns an int.



    >>> from music21 import *
    >>> n = note.Note()
    >>> n.duration.type = 'half'
    >>> midi.translate.durationToMidi(n.duration)
    2048



.. function:: getEndEvents(mt=None, channel=1)

    Provide a list of events found at the end of a track.



.. function:: instrumentToMidiEvents(inputM21, includeDeltaTime=True, midiTrack=None, channel=1)


    Converts a :class:`~music21.instrument.Instrument` object to a list of MidiEvents

    TODO: DOCS and TESTS



.. function:: keySignatureToMidiEvents(ks, includeDeltaTime=True)

    Convert a single :class:`~music21.key.KeySignature` object to a two-element list of midi events,
    where the first is an empty DeltaTime (unless includeDeltaTime is False) and the second
    is a KEY_SIGNATURE :class:`~music21.midi.base.MidiEvent`



    >>> from music21 import *
    >>> ks = key.KeySignature(2)
    >>> ks
    <music21.key.KeySignature of 2 sharps>
    >>> eventList = midi.translate.keySignatureToMidiEvents(ks)
    >>> eventList[1]
    <MidiEvent KEY_SIGNATURE, t=None, track=None, channel=1, data='\x02\x00'>
    ⁠ 
    >>> ks = key.KeySignature(-5)
    >>> ks.mode = 'minor'
    >>> ks
    <music21.key.KeySignature of 5 flats>
    >>> eventList = midi.translate.keySignatureToMidiEvents(ks)
    >>> eventList[1]
    <MidiEvent KEY_SIGNATURE, t=None, track=None, channel=1, data='\xfb\x01'>



.. function:: midiEventsToChord(eventList, ticksPerQuarter=None, inputM21=None)


    Creates a Chord from a list of :class:`~music21.midi.base.MidiEvent` and :class:`~music21.midi.base.DeltaTime` objects.



    >>> from music21 import *
    >>> mt = midi.MidiTrack(1)
    ⁠ 
    >>> dt1 = midi.DeltaTime(mt)
    >>> dt1.time = 0



    >>> me1 = midi.MidiEvent(mt)
    >>> me1.type = "NOTE_ON"
    >>> me1.pitch = 45
    >>> me1.velocity = 94
    ⁠ 
    >>> dt2 = midi.DeltaTime(mt)
    >>> dt2.time = 0



    >>> me2 = midi.MidiEvent(mt)
    >>> me2.type = "NOTE_ON"
    >>> me2.pitch = 46
    >>> me2.velocity = 94




    >>> dt3 = midi.DeltaTime(mt)
    >>> dt3.time = 2048
    ⁠ 
    >>> me3 = midi.MidiEvent(mt)
    >>> me3.type = "NOTE_OFF"
    >>> me3.pitch = 45
    >>> me3.velocity = 0



    >>> dt4 = midi.DeltaTime(mt)
    >>> dt4.time = 0
    ⁠ 
    >>> me4 = midi.MidiEvent(mt)
    >>> me4.type = "NOTE_OFF"
    >>> me4.pitch = 46
    >>> me4.velocity = 0



    >>> c = midi.translate.midiEventsToChord([dt1, me1, dt2, me2, dt3, me3, dt4, me4])
    >>> c
    <music21.chord.Chord A2 B-2>
    >>> c.duration.quarterLength
    2.0



.. function:: midiEventsToKeySignature(eventList)


    Convert a single MIDI event into a :class:`~music21.key.KeySignature` object.



    >>> from music21 import *
    >>> mt = midi.MidiTrack(1)
    >>> me1 = midi.MidiEvent(mt)
    >>> me1.type = "KEY_SIGNATURE"
    >>> me1.data = midi.putNumbersAsList([2, 0]) # d major
    >>> ks = midi.translate.midiEventsToKeySignature(me1)
    >>> ks
    <music21.key.KeySignature of 2 sharps>
    >>> ks.mode
    'major'
    ⁠ 
    >>> me2 = midi.MidiEvent(mt)
    >>> me2.type = "KEY_SIGNATURE"
    >>> me2.data = midi.putNumbersAsList([-2, 1]) # g minor
    >>> me2.data
    '\xfe\x01'
    >>> midi.getNumbersAsList(me2.data)
    [254, 1]
    >>> ks = midi.translate.midiEventsToKeySignature(me2)
    >>> ks
    <music21.key.KeySignature of 2 flats>
    >>> ks.mode
    'minor'




.. function:: midiEventsToNote(eventList, ticksPerQuarter=None, inputM21=None)

    Convert from a list of MIDI message to a music21 note

    The `inputM21` parameter can be a Note or None; in the case of None, a Note object is created.

    In this example, we start a NOTE_ON event at offset 1.0 that lasts for 2.0 quarter notes until we
    send a zero-velocity NOTE_ON (=NOTE_OFF) event for the same pitch.




    >>> from music21 import *
    ⁠ 
    >>> mt = midi.MidiTrack(1)
    >>> dt1 = midi.DeltaTime(mt)
    >>> dt1.time = 1024



    >>> me1 = midi.MidiEvent(mt)
    >>> me1.type = "NOTE_ON"
    >>> me1.pitch = 45
    >>> me1.velocity = 94
    ⁠ 
    >>> dt2 = midi.DeltaTime(mt)
    >>> dt2.time = 2048



    >>> me2 = midi.MidiEvent(mt)
    >>> me2.type = "NOTE_ON"
    >>> me2.pitch = 45
    >>> me2.velocity = 0
    ⁠ 
    >>> n = midiEventsToNote([dt1, me1, dt2, me2])
    >>> n.pitch
    A2
    >>> n.duration.quarterLength
    1.0
    >>> n.volume.velocity
    94

    An `inputM21` object can be given in which case it's set.



    >>> m = note.Note()
    >>> dummy = midiEventsToNote([dt1, me1, dt2, me2], inputM21=m)
    >>> m.pitch
    A2
    >>> m.duration.quarterLength
    1.0
    >>> m.volume.velocity
    94




.. function:: midiEventsToTempo(eventList)


    Convert a single MIDI event into a music21 Tempo object.

    TODO: Need Tests



.. function:: midiEventsToTimeSignature(eventList)


    Convert a single MIDI event into a music21 TimeSignature object.



    >>> from music21 import *
    >>> mt = midi.MidiTrack(1)
    >>> me1 = midi.MidiEvent(mt)
    >>> me1.type = "TIME_SIGNATURE"
    >>> me1.data = midi.putNumbersAsList([3, 1, 24, 8]) # 3/2 time
    >>> ts = midi.translate.midiEventsToTimeSignature(me1)
    >>> ts
    <music21.meter.TimeSignature 3/2>
    ⁠ 
    >>> me2 = midi.MidiEvent(mt)
    >>> me2.type = "TIME_SIGNATURE"
    >>> me2.data = midi.putNumbersAsList([3, 4]) # 3/16 time
    >>> ts = midi.translate.midiEventsToTimeSignature(me2)
    >>> ts
    <music21.meter.TimeSignature 3/16>




.. function:: midiToDuration(ticks, ticksPerQuarter=None, inputM21DurationObject=None)


    Converts a number of MIDI Ticks to a music21 duration.Duration() object.

    Optional parameters include ticksPerQuarter -- in case something other
    than the default.ticksPerQuarter (1024) is used in this file.  And
    it can take a :class:`~music21.duration.Duration` object to modify, specified
    as *inputM21DurationObject*




    >>> from music21 import *
    >>> d = midi.translate.midiToDuration(1024)
    >>> d
    <music21.duration.Duration 1.0>
    >>> d.type
    'quarter'
    ⁠ 
    >>> n = note.Note()
    >>> midi.translate.midiToDuration(3072, inputM21DurationObject=n.duration)
    <music21.duration.Duration 3.0>
    >>> n.duration.type
    'half'
    >>> n.duration.dots
    1



.. function:: midiTrackToStream(mt, ticksPerQuarter=None, quantizePost=True, inputM21=None)


    Note that quantization takes place in stream.py since it's useful not just for MIDI.



    >>> from music21 import *
    >>> import os
    >>> fp = os.path.join(common.getSourceFilePath(), 'midi', 'testPrimitive',  'test05.mid')
    >>> mf = midi.MidiFile()
    >>> mf.open(fp)
    >>> mf.read()
    >>> mf.close()
    >>> len(mf.tracks)
    1
    >>> mt = mf.tracks[0]
    >>> s = midi.translate.midiTrackToStream(mt)
    >>> s
    <music21.stream.Stream ...>
    >>> len(s.notesAndRests)
    11



.. function:: midiTracksToStreams(midiTracks, ticksPerQuarter=None, quantizePost=True, inputM21=None)


    Given a list of midiTracks, populate this Stream with sub-streams for each part.



.. function:: noteToMidiEvents(inputM21, includeDeltaTime=True, channel=1)


    Translate Note to four MIDI events -- the DeltaTime for the start of the note (0), the NOTE_ON event, the
    DeltaTime to the end of the note, and the NOTE_OFF event.

    If `includeDeltaTime` is not True then the DeltaTime events aren't returned, thus only two events are returned.

    The `channel` can be specified, otherwise channel 1 is assumed.



    >>> from music21 import *
    >>> n1 = note.Note('C#4')
    >>> eventList = midi.translate.noteToMidiEvents(n1)
    >>> eventList
    [<MidiEvent DeltaTime, t=0, track=None, channel=1>, <MidiEvent NOTE_ON, t=None, track=None, channel=1, pitch=61, velocity=90>, <MidiEvent DeltaTime, t=1024, track=None, channel=1>, <MidiEvent NOTE_OFF, t=None, track=None, channel=1, pitch=61, velocity=0>]
    ⁠ 
    >>> n1.duration.quarterLength = 2.5
    >>> eventList = noteToMidiEvents(n1)
    >>> eventList
    [<MidiEvent DeltaTime, t=0, track=None, channel=1>, <MidiEvent NOTE_ON, t=None, track=None, channel=1, pitch=61, velocity=90>, <MidiEvent DeltaTime, t=2560, track=None, channel=1>, <MidiEvent NOTE_OFF, t=None, track=None, channel=1, pitch=61, velocity=0>]

    Omitting initial DeltaTime:



    >>> eventList2 = noteToMidiEvents(n1, includeDeltaTime=False, channel=9)
    >>> eventList2
    [<MidiEvent NOTE_ON, t=None, track=None, channel=9, pitch=61, velocity=90>, <MidiEvent NOTE_OFF, t=None, track=None, channel=9, pitch=61, velocity=0>]



.. function:: noteToMidiFile(inputM21)


    Converts a single Music21 Note to an entire :class:`~music21.midi.base.MidiFile` object.



    >>> from music21 import *
    >>> n1 = note.Note()
    >>> n1.quarterLength = 6
    >>> mf = midi.translate.noteToMidiFile(n1)
    >>> mf.tracks[0].events
    [<MidiEvent DeltaTime, t=0, track=1, channel=1>, <MidiEvent SEQUENCE_TRACK_NAME, t=0, track=1, channel=1, data=''>, <MidiEvent DeltaTime, t=0, track=1, channel=1>, <MidiEvent NOTE_ON, t=None, track=1, channel=1, pitch=60, velocity=90>, <MidiEvent DeltaTime, t=6144, track=1, channel=1>, <MidiEvent NOTE_OFF, t=None, track=1, channel=1, pitch=60, velocity=0>, <MidiEvent DeltaTime, t=0, track=1, channel=1>, <MidiEvent END_OF_TRACK, t=None, track=1, channel=1, data=''>]



.. function:: offsetToMidi(o)


    Helper function to convert a music21 offset value to MIDI ticks, depends on *defaults.ticksPerQuarter*

    Returns an int



    >>> from music21 import *
    >>> print defaults.ticksPerQuarter
    1024
    >>> midi.translate.offsetToMidi(20.5)
    20992



.. function:: packetsToMidiTrack(packets, trackId=1, channels=None)


    Given packets already allocated with channel
    and/or instrument assignments, place these in a MidiTrack.

    Note that all packets can be sent; only those with
    matching trackIds will be collected into the resulting track

    The `channels` defines a collection of channels available for this Track

    Use _streamToPackets to convert the Stream to the packets



.. function:: streamsToMidiTracks(inputM21)


    Given a multipart stream, return a list of MIDI tracks.

    Note: will make a deepcopy() of the stream. (QUESTION: Could this
    be done with a shallow copy?)



.. function:: tempoToMidiEvents(tempoIndication, includeDeltaTime=True)

    Given any TempoIndication, convert it to a MIDI tempo indication.



    >>> from music21 import *
    >>> mm = tempo.MetronomeMark(number=90)
    >>> events = midi.translate.tempoToMidiEvents(mm)
    >>> midi.translate.midiEventsToTempo(events)
    <music21.tempo.MetronomeMark maestoso Quarter=90.0>



.. function:: timeSignatureToMidiEvents(ts, includeDeltaTime=True)


    Translate a :class:`~music21.meter.TimeSignature` to a pair of events, including a DeltaTime.

    Returns a two-element list



    >>> from music21 import *
    >>> ts = meter.TimeSignature('5/4')
    >>> eventList = midi.translate.timeSignatureToMidiEvents(ts)
    >>> eventList[0]
    <MidiEvent DeltaTime, t=0, track=None, channel=None>
    >>> eventList[1]
    <MidiEvent TIME_SIGNATURE, t=None, track=None, channel=1, data='\x05\x02\x18\x08'>



