mutwo.converters.frontends.midi module

Render midi files (SMF) from mutwo data.

Classes:

MidiFileConverter(path[, ...])

Class for rendering standard midi files (SMF) from mutwo data.
class MidiFileConverter(path, simple_event_to_pitches=<function MidiFileConverter.<lambda>>, simple_event_to_volume=<function MidiFileConverter.<lambda>>, simple_event_to_control_messages=<function MidiFileConverter.<lambda>>, midi_file_type=None, available_midi_channels=None, distribute_midi_channels=False, n_midi_channels_per_track=None, maximum_pitch_bend_deviation=None, ticks_per_beat=None, instrument_name=None, tempo_envelope=None)[source]

Bases: mutwo.converters.abc.Converter

Class for rendering standard midi files (SMF) from mutwo data.

Mutwo offers a wide range of options how the respective midi file shall be rendered and how mutwo data shall be translated. This is necessary due to the limited and not always unambiguous nature of musical encodings in midi files. In this way the user can tweak the conversion routine to her or his individual needs.

Parameters

  • path (str) – where to write the midi file. The typical file type extension ‘.mid’ is recommended, but not mandatory.

  • simple_event_to_pitches (Callable[[mutwo.events.basic.SimpleEvent], Tuple[mutwo.parameters.abc.Pitch, ...]]) – Function to extract from a mutwo.events.basic.SimpleEvent a tuple that contains pitch objects (objects that inherit from mutwo.parameters.abc.Pitch). By default it asks the Event for its pitch_or_pitches attribute (because by default mutwo.events.music.NoteLike objects are expected). When using different Event classes than NoteLike with a different name for their pitch property, this argument should be overridden. If the function call raises an AttributeError (e.g. if no pitch can be extracted), mutwo will interpret the event as a rest.

  • simple_event_to_volume (Callable[[mutwo.events.basic.SimpleEvent], mutwo.parameters.abc.Volume]) – Function to extract the volume from a mutwo.events.basic.SimpleEvent in the purpose of generating midi notes. The function should return an object that inhertis from mutwo.parameters.abc.Volume. By default it asks the Event for its volume attribute (because by default mutwo.events.music.NoteLike objects are expected). When using different Event classes than NoteLike with a different name for their volume property, this argument should be overridden. If the function call raises an AttributeError (e.g. if no volume can be extracted), mutwo will interpret the event as a rest.

  • simple_event_to_control_messages (Callable[[mutwo.events.basic.SimpleEvent], Tuple[mido.messages.messages.Message, ...]]) – Function to generate midi control messages from a simple event. By default no control messages are generated. If the function call raises an AttributeError (e.g. if an expected control value isn’t available) mutwo will interpret the event as a rest.

  • midi_file_type (int) – Can either be 0 (for one-track midi files) or 1 (for synchronous multi-track midi files). Mutwo doesn’t offer support for generating type 2 midi files (midi files with asynchronous tracks).

  • available_midi_channels (Tuple[int, ...]) – tuple containing integer where each integer represents the number of the used midi channel. Integer can range from 0 to 15. Higher numbers of available_midi_channels (like all 16) are recommended when rendering microtonal music. It shall be remarked that midi-channel 9 (or midi channel 10 when starting to count from 1) is often ignored by several software synthesizer, because this channel is reserved for percussion instruments.

  • distribute_midi_channels (bool) – This parameter is only relevant if more than one SequentialEvent is passed to the convert method. If set to True each SequentialEvent only makes use of exactly n_midi_channel (see next parameter). If set to False each converted SequentialEvent is allowed to make use of all available channels. If set to True and the amount of necessary MidiTracks is higher than the amount of available channels, mutwo will silently cycle through the list of available midi channel.

  • n_midi_channels_per_track (int) – This parameter is only relevant for distribute_midi_channels == True. It sets how many midi channels are assigned to one SequentialEvent. If microtonal chords shall be played by one SequentialEvent (via pitch bending messages) a higher number than 1 is recommended. Defaults to 1.

  • maximum_pitch_bend_deviation (float) – sets the maximum pitch bending range in cents. This value depends on the particular used software synthesizer and its settings, because it is up to the respective synthesizer how to interpret the pitch bending messages. By default mutwo sets the value to 200 cents which seems to be the most common interpretation among different manufacturers.

  • ticks_per_beat (int) – Sets the timing precision of the midi file. From the mido documentation: “Typical values range from 96 to 480 but some use even more ticks per beat”.

  • instrument_name (str) – Sets the midi instrument of all channels.

  • tempo_envelope (expenvelope.envelope.Envelope) – All Midi files should specify their tempo. The default value of mutwo is 120 BPM (this is also the value that is assumed by any midi-file-reading-software if no tempo has been specified). Tempo changes are supported (and will be written to the resulting midi file).

Example:

>>> from mutwo.converters.frontends import midi
>>> from mutwo.parameters import pitches
>>> # midi file converter that assign a middle c to all events
>>> midi_converter = midi.MidiFileConverter(
>>>     'test.mid',
>>>     simple_event_to_pitches=lambda event: (pitches.WesternPitch('c'),)
>>> )
Disclaimer:

The current implementation doesn’t support glissandi yet (only static pitches), time-signatures (the written time signature is always 4/4 for now) and dynamically changing tempo (ritardando or accelerando).

Methods:

convert(event_to_convert)

Render a Midi file to the converters path attribute from the given event.
convert(event_to_convert)[source]

Render a Midi file to the converters path attribute from the given event.

Parameters

event_to_convert (Union[mutwo.events.basic.SimpleEvent, mutwo.events.basic.SequentialEvent[mutwo.events.basic.SimpleEvent], mutwo.events.basic.SimultaneousEvent[mutwo.events.basic.SequentialEvent[mutwo.events.basic.SimpleEvent]]]) – The given event that shall be translated to a Midi file.

Return type

None

The following example generates a midi file that contains a simple ascending pentatonic scale:

>>> from mutwo.events import basic, music
>>> from mutwo.parameters import pitches
>>> from mutwo.converters.frontends import midi
>>> ascending_scale = basic.SequentialEvent(
>>>     [
>>>         music.NoteLike(pitches.WesternPitch(pitch), duration=1, volume=0.5)
>>>         for pitch in 'c d e g a'.split(' ')
>>>     ]
>>> )
>>> midi_converter = midi.MidiFileConverter(
>>>     'ascending_scale.mid', available_midi_channels=(0,)
>>> )
>>> midi_converter.convert(ascending_scale)

Disclaimer: when passing nested structures, make sure that the nested object matches the expected type. Unlike other mutwo converter classes (like mutwo.converters.symmetrical.TempoConverter) MidiFileConverter can’t convert infinitely nested structures (due to the particular way how Midi files are defined). The deepest potential structure is a mutwo.events.basic.SimultaneousEvent (representing the complete MidiFile) that contains mutwo.events.basic.SequentialEvent (where each SequentialEvent represents one MidiTrack) that contains mutwo.events.basic.SimpleEvent (where each SimpleEvent represents one midi note). If only one SequentialEvent is send, this SequentialEvent will be read as one MidiTrack in a MidiFile. If only one SimpleEvent get passed, this SimpleEvent will be interpreted as one MidiEvent (note_on and note_off) inside one MidiTrack inside one MidiFile.