mutwo.midi_converters ¶

Object	Documentation
`mutwo.midi_converters.PitchBendingNumberToPitchInterval`	Convert midi pitch bend number to `mutwo.music_parameters.abc.PitchInterval`.
`mutwo.midi_converters.PitchBendingNumberToDirectPitchInterval`	Convert midi pitch bend number to `mutwo.music_parameters.DirectPitchInterval`.
`mutwo.midi_converters.MidiPitchToMutwoPitch`	Convert midi pitch to `mutwo.music_parameters.abc.Pitch`.
`mutwo.midi_converters.MidiPitchToDirectPitch`
`mutwo.midi_converters.MidiPitchToMutwoMidiPitch`
`mutwo.midi_converters.MidiVelocityToMutwoVolume`	Convert midi velocity (integer) to `mutwo.music_parameters.abc.Volume`.
`mutwo.midi_converters.MidiVelocityToWesternVolume`
`mutwo.midi_converters.MidiFileToEvent`	Convert a midi file to a mutwo event.
`mutwo.midi_converters.ChrononToControlMessageTuple`	Convert `mutwo.core_events.Chronon` to a tuple of control messages
`mutwo.midi_converters.CentDeviationToPitchBendingNumber`	Convert cent deviation to midi pitch bend number.
`mutwo.midi_converters.MutwoPitchToMidiPitch`	Convert mutwo pitch to midi pitch number and midi pitch bend number.
`mutwo.midi_converters.EventToMidiFile`	Class for rendering standard midi files (SMF) from mutwo data.

class PitchBendingNumberToPitchInterval(maximum_pitch_bend_deviation=None)[source]¶

Bases: Converter

Convert midi pitch bend number to mutwo.music_parameters.abc.PitchInterval.

Parameters:: maximum_pitch_bend_deviation (int) – 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.

Public Methods:

convert(pitch_bending_number_to_convert)

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

abstract convert(pitch_bending_number_to_convert)[source]¶

Parameters:: pitch_bending_number_to_convert (int) –
Return type:: PitchInterval

class PitchBendingNumberToDirectPitchInterval(maximum_pitch_bend_deviation=None)[source]¶

Bases: PitchBendingNumberToPitchInterval

Convert midi pitch bend number to mutwo.music_parameters.DirectPitchInterval.

Public Methods:

convert(pitch_bending_number_to_convert)

Convert pitch bending number to mutwo.music_parameters.DirectPitchInterval

Inherited from PitchBendingNumberToPitchInterval

convert(pitch_bending_number_to_convert)

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

Parameters:: maximum_pitch_bend_deviation (Optional[float]) –

convert(pitch_bending_number_to_convert)[source]¶

Convert pitch bending number to mutwo.music_parameters.DirectPitchInterval

Parameters:: pitch_bending_number_to_convert (midi_converters.constants.PitchBend) – The pitch bending number which shall be converted.
Return type:: DirectPitchInterval

class MidiPitchToMutwoPitch(pitch_bending_number_to_pitch_interval=PitchBendingNumberToDirectPitchInterval())[source]¶

Bases: Converter

Convert midi pitch to mutwo.music_parameters.abc.Pitch.

Parameters:: pitch_bending_number_to_pitch_interval (Callable[[midi_converters.constants.PitchBend], music_parameters.abc.PitchInterval]) – A callable object which transforms a pitch bending number (integer) to a mutwo.music_parameters.abc.PitchInterval. Default to PitchBendingNumberToDirectPitchInterval.

Public Methods:

convert(midi_pitch_to_convert)

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

abstract convert(midi_pitch_to_convert)[source]¶

Parameters:: midi_pitch_to_convert (tuple[int, int]) –
Return type:: Pitch

class MidiPitchToDirectPitch(pitch_bending_number_to_pitch_interval=PitchBendingNumberToDirectPitchInterval())[source]¶

Bases: MidiPitchToMutwoPitch

Public Methods:

convert(midi_pitch_to_convert)

Inherited from MidiPitchToMutwoPitch

convert(midi_pitch_to_convert)

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

Parameters:: pitch_bending_number_to_pitch_interval (Callable[[int], PitchInterval]) –

convert(midi_pitch_to_convert)[source]¶

Parameters:: midi_pitch_to_convert (tuple[int, int]) –
Return type:: DirectPitch

class MidiPitchToMutwoMidiPitch(pitch_bending_number_to_pitch_interval=PitchBendingNumberToDirectPitchInterval())[source]¶

Bases: MidiPitchToMutwoPitch

Public Methods:

convert(midi_pitch_to_convert)

Inherited from MidiPitchToMutwoPitch

convert(midi_pitch_to_convert)

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

Parameters:: pitch_bending_number_to_pitch_interval (Callable[[int], PitchInterval]) –

convert(midi_pitch_to_convert)[source]¶

Parameters:: midi_pitch_to_convert (tuple[int, int]) –
Return type:: MidiPitch

class MidiVelocityToMutwoVolume[source]¶

Bases: Converter

Convert midi velocity (integer) to mutwo.music_parameters.abc.Volume.

Public Methods:

convert(midi_velocity)

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

abstract convert(midi_velocity)[source]¶

Parameters:: midi_velocity (int) –
Return type:: Volume

class MidiVelocityToWesternVolume[source]¶

Bases: MidiVelocityToMutwoVolume

Public Methods:

convert(midi_velocity_to_convert)

Convert midi velocity to mutwo.music_parameters.WesternVolume

Inherited from MidiVelocityToMutwoVolume

convert(midi_velocity)

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

convert(midi_velocity_to_convert)[source]¶

Convert midi velocity to mutwo.music_parameters.WesternVolume

Parameters:: midi_velocity_to_convert (midi_converters.constants.MidiVelocity) – The velocity which shall be converted.
Return type:: Volume

Example:

>>> from mutwo import midi_converters
>>> midi_converters.MidiVelocityToWesternVolume().convert(127)
WesternVolume(fffff)
>>> midi_converters.MidiVelocityToWesternVolume().convert(0)
WesternVolume(ppppp)

class MidiFileToEvent(mutwo_parameter_dict_to_chronon=MutwoParameterDictToNoteLike(), midi_pitch_to_mutwo_pitch=MidiPitchToMutwoMidiPitch(), midi_velocity_to_mutwo_volume=MidiVelocityToWesternVolume())[source]¶

Bases: Converter

Convert a midi file to a mutwo event.

Parameters:

mutwo_parameter_tuple_to_chronon (Callable[[tuple[core_parameters.abc.Duration.Type, music_parameters.abc.Pitch, music_parameters.abc.Volume]], core_events.Chronon]) –
A callable which converts a tuple of mutwo parameters (duration, pitch list, volume) to a mutwo.core_events.Chronon. In default state mutwo

generates a mutwo.music_events.NoteLike.
midi_pitch_to_mutwo_pitch (Callable[[midi_converters.constants.MidiPitch], music_parameters.abc.Pitch]) – Callable object which converts midi pitch (integer) to a mutwo.music_parameters.abc.Pitch. Default to MidiPitchToMutwoMidiPitch.
midi_velocity_to_mutwo_volume (Callable[[midi_converters.constants.MidiVelocity], music_parameters.abc.Volume]) – Callable object which converts midi velocity (integer) to a mutwo.music_parameters.abc.Voume. Default to MidiPitchToWesternVolume.
mutwo_parameter_dict_to_chronon (Callable[[dict[str, Any]], Chronon]) –

Warning:

This is an unstable early version of the converter. Expect bugs when using it!

Disclaimer:

This conversion is incomplete: Not all information from a midi file will be used. In its current state the converter only takes into account midi notes (pitch, velocity and duration) and ignores all other midi messages.

Public Methods:

convert(midi_file_path_or_mido_midi_file)

Convert midi file to mutwo event.

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

convert(midi_file_path_or_mido_midi_file)[source]¶

Convert midi file to mutwo event.

Parameters:: midi_file_path_or_mido_midi_file (str | mido.MidiFile) – The midi file which shall be converted. Can either be a file path or a MidiFile object from the mido package.
Return type:: Event

class ChrononToControlMessageTuple(attribute_name=None, exception_value=())[source]¶

Bases: ChrononToAttribute

Convert mutwo.core_events.Chronon to a tuple of control messages

Public Methods:

Inherited from ChrononToAttribute

convert(chronon_to_convert)

Extract from a mutwo.core_events.Chronon an attribute.

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

Parameters:

attribute_name (Optional[str]) –
exception_value (tuple[mido.messages.messages.Message, ...]) –

class CentDeviationToPitchBendingNumber(maximum_pitch_bend_deviation=None)[source]¶

Bases: Converter

Convert cent deviation to midi pitch bend number.

Parameters:: maximum_pitch_bend_deviation (int) – 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.

Public Methods:

convert(cent_deviation)

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

convert(cent_deviation)[source]¶

Parameters:: cent_deviation (float | fractions.Fraction | int | quicktions.Fraction) –
Return type:: int

class MutwoPitchToMidiPitch(cent_deviation_to_pitch_bending_number=CentDeviationToPitchBendingNumber())[source]¶

Bases: Converter

Convert mutwo pitch to midi pitch number and midi pitch bend number.

Parameters:

maximum_pitch_bend_deviation (int) – 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.
cent_deviation_to_pitch_bending_number (CentDeviationToPitchBendingNumber) –

Public Methods:

convert(mutwo_pitch_to_convert[, midi_note])

Find midi note and pitch bending for given mutwo pitch

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

convert(mutwo_pitch_to_convert, midi_note=None)[source]¶

Find midi note and pitch bending for given mutwo pitch

Parameters:

mutwo_pitch_to_convert (music_parameters.abc.Pitch) – The mutwo pitch which shall be converted.
midi_note (Optional[int]) – Can be set to a midi note value if one wants to force the converter to calculate the pitch bending deviation for the passed midi note. If this argument is None the converter will simply use the closest midi pitch number to the passed mutwo pitch. Default to None.

Return type:

tuple[int, int]

class EventToMidiFile(chronon_to_pitch_list=ChrononToPitchList(), chronon_to_volume=ChrononToVolume(), chronon_to_control_message_tuple=ChrononToControlMessageTuple(), midi_file_type=None, available_midi_channel_tuple=None, distribute_midi_channels=False, midi_channel_count_per_track=None, mutwo_pitch_to_midi_pitch=MutwoPitchToMidiPitch(), ticks_per_beat=None, instrument_name=None, tempo=None)[source]¶

Bases: 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:

chronon_to_pitch_list (Callable[ [core_events.Chronon], tuple[music_parameters.abc.Pitch, ...]]) – Function to extract from a mutwo.core_events.Chronon a tuple that contains pitch objects (objects that inherit from mutwo.music_parameters.abc.Pitch). By default it asks the Event for its pitch_list attribute (because by default mutwo.music_events.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.
chronon_to_volume (Callable[ [core_events.Chronon], music_parameters.abc.Volume]) – Function to extract the volume from a mutwo.core_events.Chronon in the purpose of generating midi notes. The function should return an object that inhertis from mutwo.music_parameters.abc.Volume. By default it asks the Event for its volume attribute (because by default mutwo.music_events.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.
chronon_to_control_message_tuple (Callable[ [core_events.Chronon], tuple[mido.Message, ...]]) – Function to generate midi control messages from a chronon. 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_channel_tuple (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_channel_tuple (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 Consecution is passed to the convert method. If set to True each Consecution only makes use of exactly n_midi_channel (see next parameter). If set to False each converted Consecution 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.
midi_channel_count_per_track (int) – This parameter is only relevant for distribute_midi_channels == True. It sets how many midi channels are assigned to one Consecution. If microtonal chords shall be played by one Consecution (via pitch bending messages) a higher number than 1 is recommended. Defaults to 1.
mutwo_pitch_to_midi_pitch (MutwoPitchToMidiPitch) – class to convert from mutwo pitches to midi pitches. Default to MutwoPitchToMidiPitch.
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 (core_parameters.abc.Tempo) – 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 import midi_converters
>>> from mutwo import music_parameters
>>> # midi file converter that assign a middle c to all events
>>> midi_converter = midi_converters.EventToMidiFile(
...     chronon_to_pitch_list=lambda event: (music_parameters.WesternPitch('c'),)
... )

Disclaimer:: The current implementation doesn’t support time-signatures (the written time signature is always 4/4 for now).

Public Methods:

convert(event_to_convert[, path])

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

Inherited from Converter

convert(...)

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

convert(event_to_convert, path=None)[source]¶

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

Parameters:

event_to_convert (core_events.Chronon | core_events.Consecution[core_events.Chronon] | core_events.Concurrence[core_events.Consecution[core_events.Chronon]]) – The given event that shall be translated to a Midi file.
path (Optional[str]) – If this is a string the method will write a midi file to the given path. The typical file type extension ‘.mid’ is recommended, but not mandatory. If set to None the method won’t write a midi file to the disk, but it will simply return a mido.MidiFile object. Default to None.

Return type:

MidiFile

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

>>> from mutwo import core_events
>>> from mutwo import music_events
>>> from mutwo import music_parameters
>>> from mutwo import midi_converters
>>> ascending_scale = core_events.Consecution(
...     [
...         music_events.NoteLike(music_parameters.WesternPitch(pitch), duration=1, volume=0.5)
...         for pitch in 'c d e g a'.split(' ')
...     ]
... )
>>> midi_converter = midi_converters.EventToMidiFile(
...     available_midi_channel_tuple=(0,)
... )
>>> # '.convert' creates a file, but also returns the
>>> # respective 'mido.MidiFile' object
>>> midifile = midi_converter.convert(ascending_scale, 'ascending_scale.mid')

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

mutwo.midi_converters.configurations ¶

Configure the midi converters behaviour

DEFAULT_AVAILABLE_MIDI_CHANNEL_TUPLE = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15)¶: default value for available_midi_channel_tuple in mutwo.midi_converters.EventToMidiFile

DEFAULT_CONTROL_MESSAGE_TUPLE_ATTRIBUTE_NAME = 'control_message_tuple'¶: The expected attribute name of a mutwo.core_events.Chronon for control messages.

DEFAULT_MAXIMUM_PITCH_BEND_DEVIATION_IN_CENTS = 200¶: default value for maximum_pitch_bend_deviation_in_cents in mutwo.midi_converters.EventToMidiFile

DEFAULT_MIDI_CHANNEL_COUNT_PER_TRACK = 1¶: default value for midi_channel_count_per_track in mutwo.midi_converters.EventToMidiFile

DEFAULT_MIDI_FILE_TYPE = 1¶: default value for midi_file_type in mutwo.midi_converters.EventToMidiFile

DEFAULT_MIDI_INSTRUMENT_NAME = 'Acoustic Grand Piano'¶: default value for midi_instrument_name in mutwo.midi_converters.EventToMidiFile

DEFAULT_TEMPO: Tempo = DirectTempo(120.0)¶: default value for tempo in mutwo.midi_converters.EventToMidiFile

DEFAULT_TICKS_PER_BEAT = 480¶: default value for ticks_per_beat in mutwo.midi_converters.EventToMidiFile

mutwo.midi_converters.constants ¶

Values that are defined by the midi file standard.

MidiNote¶: MidiNote type alias

MidiPitch¶: MidiPitch type alias

MidiVelocity¶: MidiVelocity type alias

PitchBend¶: PitchBend type alias

ALLOWED_MIDI_CHANNEL_TUPLE = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15)¶: midi channels that are allowed (following the standard midi file definition).

MAXIMUM_PITCH_BEND = 16382¶: the highest allowed value for midi pitch bend

MIDI_TEMPO_FACTOR = 1000000¶: factor to multiply beats-in-seconds to get beats-in-microseconds (which is the tempo unit for midi)

NEUTRAL_PITCH_BEND = 8191¶: the value for midi pitch bend when the resulting pitch doesn’t change

mutwo.midi_converters¶

mutwo.midi_converters.configurations¶

mutwo.midi_converters.constants¶

mutwo.midi_converters ¶

mutwo.midi_converters.configurations ¶

mutwo.midi_converters.constants ¶