mutwo.music_events §

Object	Documentation
`mutwo.music_events.NoteLike`	NoteLike represents traditional discreet musical objects.

class NoteLike(pitch_list='c', duration=1, volume='mf', grace_note_sequential_event=None, after_grace_note_sequential_event=None, playing_indicator_collection=None, notation_indicator_collection=None, lyric=<mutwo.music_parameters.lyrics.DirectLyric object>)[source]§

NoteLike represents traditional discreet musical objects.

Parameters:

pitch_list (Optional[Union[Pitch, Sequence, float, Fraction, int]]) – The pitch or pitches of the event. This can be a pitch object (any class that inherits from mutwo.music_parameters.abc.Pitch) or a list of pitch objects. Furthermore mutwo supports syntactic sugar to convert other objects on the fly to pitch objects: Atring can be read as pitch class names to build mutwo.music_parameters.WesternPitch objects or as ratios to build mutwo.music_parameters.JustIntonationPitch objects. Fraction will also build mutwo.music_parameters.JustIntonationPitch objects. Other numbers (integer and float) will be read as pitch class numbers to make mutwo.music_parameters.WesternPitch objects.
duration (Union[float, Fraction, int]) – The duration of NoteLike. This can be any number. The unit of the duration is up to the interpretation of the user and the respective converter routine that will be used.
volume (Union[Volume, float, Fraction, int, str]) – The volume of the event. Can either be a object of mutwo.music_parameters.abc.Volume, a number or a string. If the number ranges from 0 to 1, mutwo automatically generates a mutwo.music_parameters.DirectVolume object (and the number will be interpreted as the amplitude). If the number is smaller than 0, automatically generates a mutwo.music_parameters.volumes.DecibelVolume object (and the number will be interpreted as decibel). If the argument is a string, mutwo will try to initialise a mutwo.music_parameters.volumes.WesternVolume object.
grace_note_sequential_event (core_events.SequentialEvent[NoteLike]) –
after_grace_note_sequential_event (core_events.SequentialEvent[NoteLike]) –
playing_indicator_collection (music_parameters.playing_indicator_collection.PlayingIndicatorCollection) – A PlayingIndicatorCollection. Playing indicators alter the sound of NoteLike (e.g. tremolo, fermata, pizzicato).
notation_indicator_collection (music_parameters.notation_indicator_collection.NotationIndicatorCollection) – A NotationIndicatorCollection. Notation indicators alter the visual representation of NoteLike (e.g. ottava, clefs) without affecting the resulting sound.
lyric (core_parameters.abc.Lyric) –

By default mutwo doesn’t differentiate between Tones, Chords and Rests, but rather simply implements one general class which can represent any of the mentioned definitions (e.g. a NoteLike object with several pitches may be called a ‘Chord’ and a NoteLike object with only one pitch may be called a ‘Tone’).

Example:

>>> from mutwo import music_parameters
>>> from mutwo import music_events
>>> tone = music_events.NoteLike(music_parameters.WesternPitch('a'), 1, 1)
>>> other_tone = music_events.NoteLike('3/2', 1, 0.5)
>>> chord = music_events.NoteLike(
    [music_parameters.WesternPitch('a'), music_parameters.JustIntonationPitch('3/2')], 1, 1
)
>>> other_chord = music_events.NoteLike('c4 dqs3 10/7', 1, 3)

Public Data Attributes:

`pitch_list`	The pitch or pitches of the event.
`volume`	The volume of the event.
`grace_note_sequential_event`	`core_events.SequentialEvent` before `NoteLike`
`after_grace_note_sequential_event`	`core_events.SequentialEvent` after `NoteLike`

Inherited from SimpleEvent

`parameter_to_exclude_from_representation_tuple`
`duration`	The duration of an event.

Inherited from Event

`duration`	The duration of an event.
`tempo_envelope`	The dynamic tempo of an event; specified as an envelope.

Public Methods:

__init__([pitch_list, duration, volume, ...])

Inherited from SimpleEvent

`__init__`([pitch_list, duration, volume, ...])
`__eq__`(other)	Test for checking if two objects are equal.
`__repr__`()	Return repr(self).
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets event parameter to new value.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`metrize`([mutate])	Apply tempo envelope of event on itself
`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.

Inherited from Event

`__init__`([pitch_list, duration, volume, ...])
`copy`()	Return a deep copy of the given Event.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`set`(attribute_name, value)	Set an attribute of the object to a specific value
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets event parameter to new value.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`reset_tempo_envelope`()	Set events tempo envelope so that one beat equals one second (tempo 60).
`metrize`([mutate])	Apply tempo envelope of event on itself
`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`split_at`(absolute_time)	Split event in two events at `absolute_time`.

Private Data Attributes:

`_parameter_to_print_tuple`	Return tuple of attribute names which shall be printed for repr.
`_abc_impl`

Inherited from SimpleEvent

`_parameter_to_print_tuple`	Return tuple of attribute names which shall be printed for repr.
`_parameter_to_compare_tuple`	Return tuple of attribute names which values define the `SimpleEvent`.
`_abc_impl`

Inherited from Event

_abc_impl

Inherited from ABC

_abc_impl

copy()§

Return a deep copy of the given Event.

Return type:: Event

cut_off(start, end)§

Time-based deletion / shortening of the respective event.

Parameters:

start (Duration) – Duration when the cut off shall start.
end (Duration) – Duration when the cut off shall end.

Return type:

SimpleEvent

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
>>> )
>>> sequential_event.cut_off(1, 3)
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1)])

cut_out(start, end)§

Time-based slicing of the respective event.

Parameters:

start (Duration) – Duration when the cut out shall start.
end (Duration) – Duration when the cut up shall end.

Return type:

SimpleEvent

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
>>> )
>>> sequential_event.cut_out(1, 4)
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 2), SimpleEvent(duration = 1)])

destructive_copy()§

Adapted deep copy method that returns a new object for every leaf.

It’s called ‘destructive’, because it forgets potential repetitions of the same object in compound objects. Instead of reproducing the original structure of the compound object that shall be copied, every repetition of the same reference will return a new unique independent object.

The following example shall illustrate the difference between copy.deepcopy and destructive_copy:

>>> import copy
>>> from mutwo import core_events
>>> my_simple_event_0 = core_events.SimpleEvent(2)
>>> my_simple_event_1 = core_events.SimpleEvent(3)
>>> my_sequential_event = core_events.SequentialEvent(
>>>     [my_simple_event_0, my_simple_event_1, my_simple_event_0]
>>> )
>>> deepcopied_event = copy.deepcopy(my_sequential_event)
>>> destructivecopied_event = my_sequential_event.destructive_copy()
>>> deepcopied_event[0].duration = 10  # setting the duration of the first event
>>> destructivecopied_event[0].duration = 10
>>> # return True because the first and the third objects share the same
>>> # reference (both are the same copy of 'my_simple_event_0')
>>> deepcopied_event[0].duration == deepcopied_event[2].duration
True
>>> # return False because destructive_copy forgets the shared reference
>>> destructivecopied_event[0].duration == destructivecopied_event[2].duration
False

Return type:: SimpleEvent

get_parameter(parameter_name, flat=False, filter_undefined=False)§

Return event attribute with the entered name.

Parameters:

parameter_name (str) – The name of the attribute that shall be returned.
flat (filter_undefined) – True for flat sequence of parameter values, False if the resulting tuple shall repeat the nested structure of the event.
filter_undefined (bool) – If set to True all None values will be filtered from the returned tuple. Default to False. This flag has no effect on get_parameter() of mutwo.core_events.SimpleEvent.

Returns:

Return tuple containing the assigned values for each contained event. If an event doesn’t posses the asked parameter, mutwo will simply add None to the tuple for the respective event.

Return type:

Any

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.get_parameter('duration')
(2, 3)
>>> simple_event = core_events.SimpleEvent(10)
>>> simple_event.get_parameter('duration')
DirectDuration(10)
>>> simple_event.get_parameter('undefined_parameter')
None

metrize(mutate=True)§

Apply tempo envelope of event on itself

Metrize is only syntactic sugar for a call of EventToMetrizedEvent:

>>> from mutwo import core_converters
>>> core_converters.EventToMetrizedEvent().convert(
>>>     my_event
>>> ) == my_event.metrize()
True

Parameters:: mutate (bool) –
Return type:: SimpleEvent

mutate_parameter(parameter_name, function)§

Mutate parameter with a function.

Parameters:

parameter_name (str) – The name of the parameter which shall be mutated.
function (Union[Callable[[Any], None], Any]) – The function which mutates the parameter. The function gets as an input the assigned value for the passed parameter_name of the respective object. The function shouldn’t return anything, but simply calls a method of the parameter value.
mutate – If False the function will return a copy of the given object. If set to True the object itself will be changed and the function will return the changed object. Default to True.

Return type:

SimpleEvent

This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.

Example:

>>> from mutwo import core_events
>>> from mutwo import music_events
>>> from mutwo import music_parameters
>>> sequential_event = core_events.SequentialEvent(
>>>     [
>>>         music_events.NoteLike(
>>>             [
>>>                 music_parameters.WesternPitch('c', 4),
>>>                 music_parameters.WesternPitch('e', 4)],
>>>             ],
>>>             2, 1,
>>>         )
>>>     ]
>>> )
>>> sequential_event.mutate_parameter(
>>>     'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list]
>>> )
>>> # now all pitches should be one octave higher (from 4 to 5)
>>> sequential_event.get_parameter('pitch_list')
([WesternPitch(c5), WesternPitch(e5)],)

reset_tempo_envelope()§

Set events tempo envelope so that one beat equals one second (tempo 60).

Parameters:: mutate – If False the function will return a copy of the given object. If set to True the object itself will be changed and the function will return the changed object. Default to True.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> simple_event = core_events.SimpleEvent(duration = 1)
>>> simple_event.tempo_envelope[0].value = 100
>>> print(simple_event.tempo_envelope)
TempoEnvelope([SimpleEvent(curve_shape = 0, duration = DirectDuration(duration = 1), value = 100), SimpleEvent(curve_shape = 0, duration = DirectDuration(duration = 0), value = 60)])
>>> simple_event.reset_tempo_envelope()
>>> print(simple_event.tempo_envelope)
TempoEnvelope([SimpleEvent(curve_shape = 0, duration = DirectDuration(duration = 1), value = 60), SimpleEvent(curve_shape = 0, duration = DirectDuration(duration = 0), value = 60)])

set(attribute_name, value)§

Set an attribute of the object to a specific value

Parameters:

attribute_name (str) – The name of the attribute which value shall be set.
value (Any) – The value which shall be assigned to the given attribute_name
mutate – If False the function will return a copy of the given object. If set to True the object itself will be changed and the function will return the changed object. Default to True.

Returns:

The event.

Return type:

Event

This function is merely a convenience wrapper for…

>>> event.attribute_name = value

Because the function return the event itself it can be used in function composition.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2)])
>>> sequential_event.set('duration', 10).set('my_new_attribute', 'hello-world!')

set_parameter(parameter_name, object_or_function, set_unassigned_parameter=True)§

Sets event parameter to new value.

Parameters:

parameter_name (str) – The name of the parameter which values shall be changed.
object_or_function (Union[Callable[[Any], Any], Any]) – For setting the parameter either a new value can be passed directly or a function can be passed. The function gets as an argument the previous value that has had been assigned to the respective object and has to return a new value that will be assigned to the object.
set_unassigned_parameter (bool) – If set to False a new parameter will only be assigned to an Event if the Event already has a attribute with the respective parameter_name. If the Event doesn’t know the attribute yet and set_unassigned_parameter is False, the method call will simply be ignored.
mutate – If False the function will return a copy of the given object. If set to True the object itself will be changed and the function will return the changed object. Default to True.

Return type:

SimpleEvent

Example:

>>> from mutwo import core_events
>>> simple_event = core_events.SimpleEvent(2)
>>> simple_event.set_parameter(
>>>     'duration', lambda old_duration: old_duration * 2
>>> )
>>> simple_event.duration
4
>>> simple_event.set_parameter('duration', 3)
>>> simple_event.duration
3
>>> simple_event.set_parameter(
>>>     'unknown_parameter', 10, set_unassigned_parameter=False
>>> )  # this will be ignored
>>> simple_event.unknown_parameter
AttributeError: 'SimpleEvent' object has no attribute 'unknown_parameter'
>>> simple_event.set_parameter(
>>>     'unknown_parameter', 10, set_unassigned_parameter=True
>>> )  # this will be written
>>> simple_event.unknown_parameter
10

split_at(absolute_time)§

Split event in two events at absolute_time.

Parameters:: absolute_time (Duration) – where event shall be split
Returns:: Two events that result from splitting the present event.
Return type:: tuple[mutwo.core_events.abc.Event, mutwo.core_events.abc.Event]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.split_at(1)
(SequentialEvent([SimpleEvent(duration = 1)]), SequentialEvent([SimpleEvent(duration = 2)]))
>>> sequential_event[0].split_at(1)
(SimpleEvent(duration = 1), SimpleEvent(duration = 2))

property after_grace_note_sequential_event: SequentialEvent[SimpleEvent]§: core_events.SequentialEvent after NoteLike

property duration: Duration§

The duration of an event.

This has to be an instance of mutwo.core_parameters.abc.Duration.

property grace_note_sequential_event: SequentialEvent[SimpleEvent]§: core_events.SequentialEvent before NoteLike

parameter_to_exclude_from_representation_tuple = ('tempo_envelope',)§

property pitch_list: Any§: The pitch or pitches of the event.

property tempo_envelope: TempoEnvelope§

The dynamic tempo of an event; specified as an envelope.

Tempo envelopes are represented as core_events.TempoEnvelope objects. Tempo envelopes are valid for its respective event and all its children events.

property volume: Any§: The volume of the event.

mutwo.music_events.configurations §

Set default values for mutwo.music_events.NoteLike.

DEFAULT_NOTATION_INDICATORS_COLLECTION_CLASS§: Default value for notation_indicator_collection in NoteLike

DEFAULT_PLAYING_INDICATORS_COLLECTION_CLASS§: Default value for playing_indicator_collection in NoteLike

mutwo.music_events§

mutwo.music_events.configurations§

mutwo.music_events §

mutwo.music_events.configurations §