mutwo.core_events §

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)[source]§

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:

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()[source]§

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)[source]§

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)[source]§

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)[source]§

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:

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:

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)[source]§

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:

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 duration: Duration§

The duration of an event.

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

parameter_to_exclude_from_representation_tuple = ('tempo_envelope',)§

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.

class SequentialEvent(iterable=[], tempo_envelope=None)[source]§

Event-Object which contains other Events which happen in a linear order.

Public Data Attributes:

`duration`	The duration of an event.
`absolute_time_tuple`	Return absolute point in time for each event.
`start_and_end_time_per_event`	Return start and end time for each event.

Inherited from ComplexEvent

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:

`get_event_index_at`(absolute_time)	Get index of event which is active at the passed absolute_time.
`get_event_at`(absolute_time)	Get event which is active at the passed absolute_time.
`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from ComplexEvent

`__init__`([iterable, tempo_envelope])
`__init_subclass__`([...])	This method is called when a class is subclassed.
`__repr__`()	Return repr(self).
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the ComplexEvent without any child events.
`get_event_from_index_sequence`(index_sequence)	Get nested `Event` from a sequence of indices.
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets parameter to new value for all children events.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`filter`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`([mutate])	Apply tempo envelope of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from Event

`__init__`([iterable, tempo_envelope])
`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 parameter to new value for all children events.
`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`.

Inherited from list

`__repr__`()	Return repr(self).
`__getattribute__`(name, /)	Return getattr(self, name).
`__lt__`(value, /)	Return self<value.
`__le__`(value, /)	Return self<=value.
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`__gt__`(value, /)	Return self>value.
`__ge__`(value, /)	Return self>=value.
`__iter__`()	Implement iter(self).
`__init__`([iterable, tempo_envelope])
`__len__`()	Return len(self).
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__setitem__`(key, value, /)	Set self[key] to value.
`__delitem__`(key, /)	Delete self[key].
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__rmul__`(value, /)	Return value*self.
`__contains__`(key, /)	Return key in self.
`__iadd__`(value, /)	Implement self+=value.
`__imul__`(value, /)	Implement self*=value.
`__reversed__`()	Return a reverse iterator over the list.
`__sizeof__`()	Return the size of the list in memory, in bytes.
`clear`()	Remove all items from list.
`copy`()	Return a deep copy of the given Event.
`append`(object, /)	Append object to the end of the list.
`insert`(index, object, /)	Insert object before index.
`extend`(iterable, /)	Extend list by appending elements from the iterable.
`pop`([index])	Remove and return item at index (default last).
`remove`(value, /)	Remove first occurrence of value.
`index`(value[, start, stop])	Return first index of value.
`count`(value, /)	Return number of occurrences of value.
`reverse`()	Reverse IN PLACE.
`sort`(*[, key, reverse])	Sort the list in ascending order and return None.
`__class_getitem__`	See PEP 585

Inherited from Generic

`__class_getitem__`	See PEP 585
`__init_subclass__`([...])	This method is called when a class is subclassed.

Private Data Attributes:

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from ComplexEvent

_abc_impl

Inherited from Event

_abc_impl

Inherited from ABC

_abc_impl

Inherited from Generic

_is_protocol

Parameters:

iterable (Iterable[T]) –
tempo_envelope (Optional[core_events.TempoEnvelope]) –

append(object, /)§: Append object to the end of the list.

clear()§: Remove all items from list.

copy()§

Return a deep copy of the given Event.

Return type:: Event

count(value, /)§: Return number of occurrences of value.

cut_off(start, end)[source]§

Time-based deletion / shortening of the respective event.

Parameters:

start (Union[float, Fraction, int]) – Duration when the cut off shall start.
end (Union[float, Fraction, int]) – Duration when the cut off shall end.

Return type:

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)[source]§

Time-based slicing of the respective event.

Parameters:

start (Union[float, Fraction, int]) – Duration when the cut out shall start.
end (Union[float, Fraction, int]) – Duration when the cut up shall end.

Return type:

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:: ComplexEvent[T]

empty_copy()§

Make a copy of the ComplexEvent without any child events.

This method is useful if one wants to copy an instance of ComplexEvent and make sure that all side attributes (e.g. any assigned properties specific to the respective subclass) get saved.

Example:

>>> from mutwo import core_events
>>> piano_voice_0 = core_events.TaggedSequentialEvent([core_events.SimpleEvent(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
TaggedSequentialEvent([])

Return type:: ComplexEvent[T]

extend(iterable, /)§: Extend list by appending elements from the iterable.

filter(condition)§

Condition-based deletion of child events.

Parameters:

condition (Callable[[Event], bool]) – Function which takes a Event and returns True or False. If the return value of the function is False the respective Event will be deleted.
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:

Example:

>>> from mutwo import core_events
>>> simultaneous_event = core_events.SimultaneousEvent(
    [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
)
>>> simultaneous_event.filter(lambda event: event.duration > 2)
>>> simultaneous_event
SimultaneousEvent([SimpleEvent(duration = 3)])

get_event_at(absolute_time)[source]§

Get event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[T]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_at(1)
SimpleEvent(duration = 2)
>>> sequential_event.get_event_at(3)
SimpleEvent(duration = 3)
>>> sequential_event.get_event_at(100)
None

Warning:

This method ignores events with duration == 0.

get_event_from_index_sequence(index_sequence)§

Get nested Event from a sequence of indices.

Parameters:: index_sequence (Sequence[int]) – The indices of the nested Event.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> nested_sequential_event = core_events.SequentialEvent(
>>>     [core_events.SequentialEvent([core_events.SimpleEvent(2)])]
>>> )
>>> nested_sequential_event.get_event_from_index_sequence((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

get_event_index_at(absolute_time)[source]§

Get index of event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Index of event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[int]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_index_at(1)
0
>>> sequential_event.get_event_index_at(3)
1
>>> sequential_event.get_event_index_at(100)
None

Warning:

This method ignores events with duration == 0.

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:

tuple[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

index(value, start=0, stop=9223372036854775807, /)§

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)§: Insert object before index.

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

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:

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)],)

pop(index=-1, /)§

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)§

Remove first occurrence of value.

Raises ValueError if the value is not present.

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)])

reverse()§: Reverse IN PLACE.

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:

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 parameter to new value for all children events.

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.

Returns:

The event.

Return type:

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

sort(*, key=None, reverse=False)§

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

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

split_child_at(absolute_time)[source]§

Split child event in two events at absolute_time.

Parameters:

absolute_time (Union[Duration, Any]) – where child event shall be split
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:

Example:

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

squash_in(start, event_to_squash_in)[source]§

Time-based insert of a new event into the present event.

Parameters:

start (Union[Duration, Any]) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.
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:

Squash in a new event to the present event.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.squash_in(1, core_events.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.core_events.abc.Event'>, event_to_remove=True)§

Condition-based deletion of neighboring child events.

Parameters:

condition (Callable[[Event, Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.
process_surviving_event (Callable[[Event, Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.
event_type_to_examine (Type[Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.core_events.SimpleEvent.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.
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:

property absolute_time_tuple: tuple[Union[float, fractions.Fraction, int], ...]§: Return absolute point in time for each event.

property duration: Duration§

The duration of an event.

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

property start_and_end_time_per_event: tuple[ranges.Range.Range, ...]§: Return start and end time for each 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.

class SimultaneousEvent(iterable=[], tempo_envelope=None)[source]§

Event-Object which contains other Event-Objects which happen at the same time.

Public Data Attributes:

The duration of an event.

Inherited from ComplexEvent

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:

`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from ComplexEvent

`__init__`([iterable, tempo_envelope])
`__init_subclass__`([...])	This method is called when a class is subclassed.
`__repr__`()	Return repr(self).
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the ComplexEvent without any child events.
`get_event_from_index_sequence`(index_sequence)	Get nested `Event` from a sequence of indices.
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets parameter to new value for all children events.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`filter`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`([mutate])	Apply tempo envelope of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from Event

`__init__`([iterable, tempo_envelope])
`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 parameter to new value for all children events.
`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`.

Inherited from list

`__repr__`()	Return repr(self).
`__getattribute__`(name, /)	Return getattr(self, name).
`__lt__`(value, /)	Return self<value.
`__le__`(value, /)	Return self<=value.
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`__gt__`(value, /)	Return self>value.
`__ge__`(value, /)	Return self>=value.
`__iter__`()	Implement iter(self).
`__init__`([iterable, tempo_envelope])
`__len__`()	Return len(self).
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__setitem__`(key, value, /)	Set self[key] to value.
`__delitem__`(key, /)	Delete self[key].
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__rmul__`(value, /)	Return value*self.
`__contains__`(key, /)	Return key in self.
`__iadd__`(value, /)	Implement self+=value.
`__imul__`(value, /)	Implement self*=value.
`__reversed__`()	Return a reverse iterator over the list.
`__sizeof__`()	Return the size of the list in memory, in bytes.
`clear`()	Remove all items from list.
`copy`()	Return a deep copy of the given Event.
`append`(object, /)	Append object to the end of the list.
`insert`(index, object, /)	Insert object before index.
`extend`(iterable, /)	Extend list by appending elements from the iterable.
`pop`([index])	Remove and return item at index (default last).
`remove`(value, /)	Remove first occurrence of value.
`index`(value[, start, stop])	Return first index of value.
`count`(value, /)	Return number of occurrences of value.
`reverse`()	Reverse IN PLACE.
`sort`(*[, key, reverse])	Sort the list in ascending order and return None.
`__class_getitem__`	See PEP 585

Inherited from Generic

`__class_getitem__`	See PEP 585
`__init_subclass__`([...])	This method is called when a class is subclassed.

Private Data Attributes:

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from ComplexEvent

_abc_impl

Inherited from Event

_abc_impl

Inherited from ABC

_abc_impl

Inherited from Generic

_is_protocol

Parameters:

iterable (Iterable[T]) –
tempo_envelope (Optional[core_events.TempoEnvelope]) –

append(object, /)§: Append object to the end of the list.

clear()§: Remove all items from list.

copy()§

Return a deep copy of the given Event.

Return type:: Event

count(value, /)§: Return number of occurrences of value.

cut_off(start, end)[source]§

Time-based deletion / shortening of the respective event.

Parameters:

start (Union[float, Fraction, int]) – Duration when the cut off shall start.
end (Union[float, Fraction, int]) – Duration when the cut off shall end.

Return type:

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)[source]§

Time-based slicing of the respective event.

Parameters:

start (Union[Duration, Any]) – Duration when the cut out shall start.
end (Union[Duration, Any]) – Duration when the cut up shall end.

Return type:

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:: ComplexEvent[T]

empty_copy()§

Make a copy of the ComplexEvent without any child events.

This method is useful if one wants to copy an instance of ComplexEvent and make sure that all side attributes (e.g. any assigned properties specific to the respective subclass) get saved.

Example:

>>> from mutwo import core_events
>>> piano_voice_0 = core_events.TaggedSequentialEvent([core_events.SimpleEvent(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
TaggedSequentialEvent([])

Return type:: ComplexEvent[T]

extend(iterable, /)§: Extend list by appending elements from the iterable.

filter(condition)§

Condition-based deletion of child events.

Parameters:

condition (Callable[[Event], bool]) – Function which takes a Event and returns True or False. If the return value of the function is False the respective Event will be deleted.
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:

Example:

>>> from mutwo import core_events
>>> simultaneous_event = core_events.SimultaneousEvent(
    [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
)
>>> simultaneous_event.filter(lambda event: event.duration > 2)
>>> simultaneous_event
SimultaneousEvent([SimpleEvent(duration = 3)])

get_event_from_index_sequence(index_sequence)§

Get nested Event from a sequence of indices.

Parameters:: index_sequence (Sequence[int]) – The indices of the nested Event.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> nested_sequential_event = core_events.SequentialEvent(
>>>     [core_events.SequentialEvent([core_events.SimpleEvent(2)])]
>>> )
>>> nested_sequential_event.get_event_from_index_sequence((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

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:

tuple[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

index(value, start=0, stop=9223372036854775807, /)§

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)§: Insert object before index.

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

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:

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)],)

pop(index=-1, /)§

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)§

Remove first occurrence of value.

Raises ValueError if the value is not present.

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)])

reverse()§: Reverse IN PLACE.

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:

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 parameter to new value for all children events.

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.

Returns:

The event.

Return type:

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

sort(*, key=None, reverse=False)§

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

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

split_child_at(absolute_time)[source]§

Split child event in two events at absolute_time.

Parameters:

absolute_time (Union[float, Fraction, int]) – where child event shall be split
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:

Example:

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

squash_in(start, event_to_squash_in)[source]§

Time-based insert of a new event into the present event.

Parameters:

start (Union[Duration, Any]) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.
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:

Squash in a new event to the present event.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.squash_in(1, core_events.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.core_events.abc.Event'>, event_to_remove=True)§

Condition-based deletion of neighboring child events.

Parameters:

condition (Callable[[Event, Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.
process_surviving_event (Callable[[Event, Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.
event_type_to_examine (Type[Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.core_events.SimpleEvent.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.
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:

property duration: Union[float, Fraction, int]§

The duration of an event.

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

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.

class TaggedSimpleEvent(*args, tag=None, **kwargs)[source]§

SimpleEvent with tag.

Public Data Attributes:

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__(*args[, tag])

Inherited from SimpleEvent

`__init__`(*args[, tag])
`__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__`(*args[, tag])
`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:

_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

Parameters:: tag (Optional[str]) –

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:

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:

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:

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:

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:

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 duration: Duration§

The duration of an event.

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

parameter_to_exclude_from_representation_tuple = ('tempo_envelope',)§

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.

class TaggedSequentialEvent(*args, tag=None, **kwargs)[source]§

SequentialEvent with tag.

Public Data Attributes:

Inherited from SequentialEvent

`duration`	The duration of an event.
`absolute_time_tuple`	Return absolute point in time for each event.
`start_and_end_time_per_event`	Return start and end time for each event.

Inherited from ComplexEvent

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__(*args[, tag])

Inherited from SequentialEvent

`get_event_index_at`(absolute_time)	Get index of event which is active at the passed absolute_time.
`get_event_at`(absolute_time)	Get event which is active at the passed absolute_time.
`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from ComplexEvent

`__init__`(*args[, tag])
`__init_subclass__`([...])	This method is called when a class is subclassed.
`__repr__`()	Return repr(self).
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the ComplexEvent without any child events.
`get_event_from_index_sequence`(index_sequence)	Get nested `Event` from a sequence of indices.
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets parameter to new value for all children events.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`filter`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`([mutate])	Apply tempo envelope of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from Event

`__init__`(*args[, tag])
`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 parameter to new value for all children events.
`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`.

Inherited from list

`__repr__`()	Return repr(self).
`__getattribute__`(name, /)	Return getattr(self, name).
`__lt__`(value, /)	Return self<value.
`__le__`(value, /)	Return self<=value.
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`__gt__`(value, /)	Return self>value.
`__ge__`(value, /)	Return self>=value.
`__iter__`()	Implement iter(self).
`__init__`(*args[, tag])
`__len__`()	Return len(self).
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__setitem__`(key, value, /)	Set self[key] to value.
`__delitem__`(key, /)	Delete self[key].
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__rmul__`(value, /)	Return value*self.
`__contains__`(key, /)	Return key in self.
`__iadd__`(value, /)	Implement self+=value.
`__imul__`(value, /)	Implement self*=value.
`__reversed__`()	Return a reverse iterator over the list.
`__sizeof__`()	Return the size of the list in memory, in bytes.
`clear`()	Remove all items from list.
`copy`()	Return a deep copy of the given Event.
`append`(object, /)	Append object to the end of the list.
`insert`(index, object, /)	Insert object before index.
`extend`(iterable, /)	Extend list by appending elements from the iterable.
`pop`([index])	Remove and return item at index (default last).
`remove`(value, /)	Remove first occurrence of value.
`index`(value[, start, stop])	Return first index of value.
`count`(value, /)	Return number of occurrences of value.
`reverse`()	Reverse IN PLACE.
`sort`(*[, key, reverse])	Sort the list in ascending order and return None.
`__class_getitem__`	See PEP 585

Inherited from Generic

`__class_getitem__`	See PEP 585
`__init_subclass__`([...])	This method is called when a class is subclassed.

Private Data Attributes:

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from SequentialEvent

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from ComplexEvent

_abc_impl

Inherited from Event

_abc_impl

Inherited from ABC

_abc_impl

Inherited from Generic

_is_protocol

Parameters:: tag (Optional[str]) –

append(object, /)§: Append object to the end of the list.

clear()§: Remove all items from list.

copy()§

Return a deep copy of the given Event.

Return type:: Event

count(value, /)§: Return number of occurrences of value.

cut_off(start, end)§

Time-based deletion / shortening of the respective event.

Parameters:

start (Union[float, Fraction, int]) – Duration when the cut off shall start.
end (Union[float, Fraction, int]) – Duration when the cut off shall end.

Return type:

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 (Union[float, Fraction, int]) – Duration when the cut out shall start.
end (Union[float, Fraction, int]) – Duration when the cut up shall end.

Return type:

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:: ComplexEvent[T]

empty_copy()§

Make a copy of the ComplexEvent without any child events.

This method is useful if one wants to copy an instance of ComplexEvent and make sure that all side attributes (e.g. any assigned properties specific to the respective subclass) get saved.

Example:

>>> from mutwo import core_events
>>> piano_voice_0 = core_events.TaggedSequentialEvent([core_events.SimpleEvent(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
TaggedSequentialEvent([])

Return type:: ComplexEvent[T]

extend(iterable, /)§: Extend list by appending elements from the iterable.

filter(condition)§

Condition-based deletion of child events.

Parameters:

condition (Callable[[Event], bool]) – Function which takes a Event and returns True or False. If the return value of the function is False the respective Event will be deleted.
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:

Example:

>>> from mutwo import core_events
>>> simultaneous_event = core_events.SimultaneousEvent(
    [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
)
>>> simultaneous_event.filter(lambda event: event.duration > 2)
>>> simultaneous_event
SimultaneousEvent([SimpleEvent(duration = 3)])

get_event_at(absolute_time)§

Get event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[T]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_at(1)
SimpleEvent(duration = 2)
>>> sequential_event.get_event_at(3)
SimpleEvent(duration = 3)
>>> sequential_event.get_event_at(100)
None

Warning:

This method ignores events with duration == 0.

get_event_from_index_sequence(index_sequence)§

Get nested Event from a sequence of indices.

Parameters:: index_sequence (Sequence[int]) – The indices of the nested Event.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> nested_sequential_event = core_events.SequentialEvent(
>>>     [core_events.SequentialEvent([core_events.SimpleEvent(2)])]
>>> )
>>> nested_sequential_event.get_event_from_index_sequence((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

get_event_index_at(absolute_time)§

Get index of event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Index of event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[int]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_index_at(1)
0
>>> sequential_event.get_event_index_at(3)
1
>>> sequential_event.get_event_index_at(100)
None

Warning:

This method ignores events with duration == 0.

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:

tuple[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

index(value, start=0, stop=9223372036854775807, /)§

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)§: Insert object before index.

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

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:

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)],)

pop(index=-1, /)§

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)§

Remove first occurrence of value.

Raises ValueError if the value is not present.

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)])

reverse()§: Reverse IN PLACE.

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:

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 parameter to new value for all children events.

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.

Returns:

The event.

Return type:

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

sort(*, key=None, reverse=False)§

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

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

split_child_at(absolute_time)§

Split child event in two events at absolute_time.

Parameters:

absolute_time (Union[Duration, Any]) – where child event shall be split
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:

Example:

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

squash_in(start, event_to_squash_in)§

Time-based insert of a new event into the present event.

Parameters:

start (Union[Duration, Any]) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.
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:

Squash in a new event to the present event.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.squash_in(1, core_events.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.core_events.abc.Event'>, event_to_remove=True)§

Condition-based deletion of neighboring child events.

Parameters:

condition (Callable[[Event, Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.
process_surviving_event (Callable[[Event, Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.
event_type_to_examine (Type[Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.core_events.SimpleEvent.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.
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:

property absolute_time_tuple: tuple[Union[float, fractions.Fraction, int], ...]§: Return absolute point in time for each event.

property duration: Duration§

The duration of an event.

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

property start_and_end_time_per_event: tuple[ranges.Range.Range, ...]§: Return start and end time for each 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.

class TaggedSimultaneousEvent(*args, tag=None, **kwargs)[source]§

SimultaneousEvent with tag.

Public Data Attributes:

Inherited from SimultaneousEvent

The duration of an event.

Inherited from ComplexEvent

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__(*args[, tag])

Inherited from SimultaneousEvent

`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from ComplexEvent

`__init__`(*args[, tag])
`__init_subclass__`([...])	This method is called when a class is subclassed.
`__repr__`()	Return repr(self).
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the ComplexEvent without any child events.
`get_event_from_index_sequence`(index_sequence)	Get nested `Event` from a sequence of indices.
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets parameter to new value for all children events.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`filter`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`([mutate])	Apply tempo envelope of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from Event

`__init__`(*args[, tag])
`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 parameter to new value for all children events.
`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`.

Inherited from list

`__repr__`()	Return repr(self).
`__getattribute__`(name, /)	Return getattr(self, name).
`__lt__`(value, /)	Return self<value.
`__le__`(value, /)	Return self<=value.
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`__gt__`(value, /)	Return self>value.
`__ge__`(value, /)	Return self>=value.
`__iter__`()	Implement iter(self).
`__init__`(*args[, tag])
`__len__`()	Return len(self).
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__setitem__`(key, value, /)	Set self[key] to value.
`__delitem__`(key, /)	Delete self[key].
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__rmul__`(value, /)	Return value*self.
`__contains__`(key, /)	Return key in self.
`__iadd__`(value, /)	Implement self+=value.
`__imul__`(value, /)	Implement self*=value.
`__reversed__`()	Return a reverse iterator over the list.
`__sizeof__`()	Return the size of the list in memory, in bytes.
`clear`()	Remove all items from list.
`copy`()	Return a deep copy of the given Event.
`append`(object, /)	Append object to the end of the list.
`insert`(index, object, /)	Insert object before index.
`extend`(iterable, /)	Extend list by appending elements from the iterable.
`pop`([index])	Remove and return item at index (default last).
`remove`(value, /)	Remove first occurrence of value.
`index`(value[, start, stop])	Return first index of value.
`count`(value, /)	Return number of occurrences of value.
`reverse`()	Reverse IN PLACE.
`sort`(*[, key, reverse])	Sort the list in ascending order and return None.
`__class_getitem__`	See PEP 585

Inherited from Generic

`__class_getitem__`	See PEP 585
`__init_subclass__`([...])	This method is called when a class is subclassed.

Private Data Attributes:

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from SimultaneousEvent

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from ComplexEvent

_abc_impl

Inherited from Event

_abc_impl

Inherited from ABC

_abc_impl

Inherited from Generic

_is_protocol

Parameters:: tag (Optional[str]) –

append(object, /)§: Append object to the end of the list.

clear()§: Remove all items from list.

copy()§

Return a deep copy of the given Event.

Return type:: Event

count(value, /)§: Return number of occurrences of value.

cut_off(start, end)§

Time-based deletion / shortening of the respective event.

Parameters:

start (Union[float, Fraction, int]) – Duration when the cut off shall start.
end (Union[float, Fraction, int]) – Duration when the cut off shall end.

Return type:

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 (Union[Duration, Any]) – Duration when the cut out shall start.
end (Union[Duration, Any]) – Duration when the cut up shall end.

Return type:

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:: ComplexEvent[T]

empty_copy()§

Make a copy of the ComplexEvent without any child events.

This method is useful if one wants to copy an instance of ComplexEvent and make sure that all side attributes (e.g. any assigned properties specific to the respective subclass) get saved.

Example:

>>> from mutwo import core_events
>>> piano_voice_0 = core_events.TaggedSequentialEvent([core_events.SimpleEvent(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
TaggedSequentialEvent([])

Return type:: ComplexEvent[T]

extend(iterable, /)§: Extend list by appending elements from the iterable.

filter(condition)§

Condition-based deletion of child events.

Parameters:

condition (Callable[[Event], bool]) – Function which takes a Event and returns True or False. If the return value of the function is False the respective Event will be deleted.
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:

Example:

>>> from mutwo import core_events
>>> simultaneous_event = core_events.SimultaneousEvent(
    [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
)
>>> simultaneous_event.filter(lambda event: event.duration > 2)
>>> simultaneous_event
SimultaneousEvent([SimpleEvent(duration = 3)])

get_event_from_index_sequence(index_sequence)§

Get nested Event from a sequence of indices.

Parameters:: index_sequence (Sequence[int]) – The indices of the nested Event.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> nested_sequential_event = core_events.SequentialEvent(
>>>     [core_events.SequentialEvent([core_events.SimpleEvent(2)])]
>>> )
>>> nested_sequential_event.get_event_from_index_sequence((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

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:

tuple[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

index(value, start=0, stop=9223372036854775807, /)§

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)§: Insert object before index.

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

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:

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)],)

pop(index=-1, /)§

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)§

Remove first occurrence of value.

Raises ValueError if the value is not present.

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)])

reverse()§: Reverse IN PLACE.

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:

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 parameter to new value for all children events.

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.

Returns:

The event.

Return type:

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

sort(*, key=None, reverse=False)§

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

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

split_child_at(absolute_time)§

Split child event in two events at absolute_time.

Parameters:

absolute_time (Union[float, Fraction, int]) – where child event shall be split
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:

Example:

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

squash_in(start, event_to_squash_in)§

Time-based insert of a new event into the present event.

Parameters:

start (Union[Duration, Any]) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.
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:

Squash in a new event to the present event.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.squash_in(1, core_events.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.core_events.abc.Event'>, event_to_remove=True)§

Condition-based deletion of neighboring child events.

Parameters:

condition (Callable[[Event, Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.
process_surviving_event (Callable[[Event, Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.
event_type_to_examine (Type[Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.core_events.SimpleEvent.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.
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:

property duration: Union[float, Fraction, int]§

The duration of an event.

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

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.

class Envelope(event_iterable_or_point_sequence, tempo_envelope=None, event_to_parameter=<function Envelope.<lambda>>, event_to_curve_shape=<function Envelope.<lambda>>, parameter_to_value=<function Envelope.<lambda>>, value_to_parameter=<function Envelope.<lambda>>, apply_parameter_on_event=<function Envelope.<lambda>>, apply_curve_shape_on_event=<function Envelope.<lambda>>, default_event_class=<class 'mutwo.core_events.basic.SimpleEvent'>, initialise_default_event_class=<function Envelope.<lambda>>)[source]§

Model continuous changing values (e.g. glissandi, crescendo).

Parameters:

event_iterable_or_point_sequence (Iterable[T]) – An iterable filled with events or with points. If the sequence is filled with points, the points will be converted to events. Each event represents a point in a two dimensional graph where the x-axis presents time and the y-axis a changing value. Any event class can be used. It is more important that the used event classes fit with the functions passed in the following parameters.
event_to_parameter (Callable[[core_events.abc.Event], core_constants.ParameterType]) – A function which receives an event and has to return a parameter object (any object). By default the function will ask the event for its value property. If the property can’t be found it will return 0.
event_to_curve_shape (Callable[[core_events.abc.Event], CurveShape]) – A function which receives an event and has to return a curve_shape. A curve_shape is either a float, an integer or a fraction. For a curve_shape = 0 a linear transition between two points is created. For a curve_shape > 0 the envelope changes slower at the beginning and faster at the end, for a curve_shape < 0 it is the inverse behaviour. The default function will ask the event for its curve_shape property. If the property can’t be found it will return 0.
parameter_to_value (Callable[[Value], core_constants.ParameterType]) – Convert a parameter to a value. A value is any object which supports mathematical operations.
value_to_parameter (Callable[[Value], core_constants.ParameterType]) – A callable object which converts a value to a parameter.
apply_parameter_on_event (Callable[[core_events.abc.Event, core_constants.ParameterType], None]) – A callable object which applies a parameter on an event.
apply_curve_shape_on_event (Callable[[core_events.abc.Event, CurveShape], None]) – A callable object which applies a curve shape on an event.
default_event_class (type[core_events.abc.Event]) – The default event class which describes a point.
initialise_default_event_class (Callable[[type[core_events.abc.Event], core_constants.DurationType], core_events.abc.Event]) –
tempo_envelope (Optional[core_events.TempoEnvelope]) –

This class is inspired by Marc Evansteins Envelope class in his expenvelope python package and is made to fit better into the mutwo ecosystem.

Example:

>>> from mutwo import core_events
>>> core_events.Envelope([[0, 0, 1], [0.5, 1]])
Envelope([SimpleEvent(curve_shape = 1, duration = 0.5, value = 0), SimpleEvent(curve_shape = 0, duration = 0.0, value = 1)])

Public Data Attributes:

`Value`	alias of `Union`[`float`, `Fraction`, `int`]
`CurveShape`	alias of `Union`[`float`, `Fraction`, `int`]
`Point`	alias of `Union`[`tuple`[`Union`[`float`, `Fraction`, `int`], `Any`, `Union`[`float`, `Fraction`, `int`]], `tuple`[`Union`[`float`, `Fraction`, `int`], `Any`]]
`parameter_tuple`
`value_tuple`
`curve_shape_tuple`
`is_static`	Return True if `Envelope` only has one static value.

Inherited from SequentialEvent

`duration`	The duration of an event.
`absolute_time_tuple`	Return absolute point in time for each event.
`start_and_end_time_per_event`	Return start and end time for each event.

Inherited from ComplexEvent

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__`(event_iterable_or_point_sequence[, ...])
`from_points`(point, *kwargs)
`__setitem__`()	Set self[key] to value.
`value_at`(absolute_time)
`parameter_at`(absolute_time)
`sample_at`(absolute_time[, append_duration])	Discretize envelope at given time
`integrate_interval`(start, end)
`get_average_value`([start, end])
`get_average_parameter`([start, end])
`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 SequentialEvent

`get_event_index_at`(absolute_time)	Get index of event which is active at the passed absolute_time.
`get_event_at`(absolute_time)	Get event which is active at the passed absolute_time.
`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from ComplexEvent

`__init__`(event_iterable_or_point_sequence[, ...])
`__init_subclass__`([...])	This method is called when a class is subclassed.
`__repr__`()	Return repr(self).
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the ComplexEvent without any child events.
`get_event_from_index_sequence`(index_sequence)	Get nested `Event` from a sequence of indices.
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets parameter to new value for all children events.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`filter`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`([mutate])	Apply tempo envelope of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from Event

`__init__`(event_iterable_or_point_sequence[, ...])
`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 parameter to new value for all children events.
`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`.

Inherited from list

`__repr__`()	Return repr(self).
`__getattribute__`(name, /)	Return getattr(self, name).
`__lt__`(value, /)	Return self<value.
`__le__`(value, /)	Return self<=value.
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`__gt__`(value, /)	Return self>value.
`__ge__`(value, /)	Return self>=value.
`__iter__`()	Implement iter(self).
`__init__`(event_iterable_or_point_sequence[, ...])
`__len__`()	Return len(self).
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__setitem__`()	Set self[key] to value.
`__delitem__`(key, /)	Delete self[key].
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__rmul__`(value, /)	Return value*self.
`__contains__`(key, /)	Return key in self.
`__iadd__`(value, /)	Implement self+=value.
`__imul__`(value, /)	Implement self*=value.
`__reversed__`()	Return a reverse iterator over the list.
`__sizeof__`()	Return the size of the list in memory, in bytes.
`clear`()	Remove all items from list.
`copy`()	Return a deep copy of the given Event.
`append`(object, /)	Append object to the end of the list.
`insert`(index, object, /)	Insert object before index.
`extend`(iterable, /)	Extend list by appending elements from the iterable.
`pop`([index])	Remove and return item at index (default last).
`remove`(value, /)	Remove first occurrence of value.
`index`(value[, start, stop])	Return first index of value.
`count`(value, /)	Return number of occurrences of value.
`reverse`()	Reverse IN PLACE.
`sort`(*[, key, reverse])	Sort the list in ascending order and return None.
`__class_getitem__`	See PEP 585

Inherited from Generic

`__class_getitem__`	See PEP 585
`__init_subclass__`([...])	This method is called when a class is subclassed.

Private Data Attributes:

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from SequentialEvent

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from ComplexEvent

_abc_impl

Inherited from Event

_abc_impl

Inherited from ABC

_abc_impl

Inherited from Generic

_is_protocol

CompletePoint§: alias of tuple[Union[float, Fraction, int], Any, Union[float, Fraction, int]]

IncompletePoint§: alias of tuple[Union[float, Fraction, int], Any]

append(object, /)§: Append object to the end of the list.

clear()§: Remove all items from list.

copy()§

Return a deep copy of the given Event.

Return type:: Event

count(value, /)§: Return number of occurrences of value.

cut_off(start, end)[source]§

Time-based deletion / shortening of the respective event.

Parameters:

start (Union[Duration, Any]) – Duration when the cut off shall start.
end (Union[Duration, Any]) – Duration when the cut off shall end.

Return type:

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)[source]§

Time-based slicing of the respective event.

Parameters:

start (Union[Duration, Any]) – Duration when the cut out shall start.
end (Union[Duration, Any]) – Duration when the cut up shall end.

Return type:

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:: ComplexEvent[T]

empty_copy()§

Make a copy of the ComplexEvent without any child events.

This method is useful if one wants to copy an instance of ComplexEvent and make sure that all side attributes (e.g. any assigned properties specific to the respective subclass) get saved.

Example:

>>> from mutwo import core_events
>>> piano_voice_0 = core_events.TaggedSequentialEvent([core_events.SimpleEvent(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
TaggedSequentialEvent([])

Return type:: ComplexEvent[T]

extend(iterable, /)§: Extend list by appending elements from the iterable.

filter(condition)§

Condition-based deletion of child events.

Parameters:

condition (Callable[[Event], bool]) – Function which takes a Event and returns True or False. If the return value of the function is False the respective Event will be deleted.
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:

Example:

>>> from mutwo import core_events
>>> simultaneous_event = core_events.SimultaneousEvent(
    [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
)
>>> simultaneous_event.filter(lambda event: event.duration > 2)
>>> simultaneous_event
SimultaneousEvent([SimpleEvent(duration = 3)])

classmethod from_points(*point, **kwargs)[source]§

Parameters:: point (Point) –
Return type:: Envelope

get_average_parameter(start=None, end=None)[source]§

Parameters:

start (Optional[Union[float, Fraction, int]]) –
end (Optional[Union[float, Fraction, int]]) –

Return type:

Any

get_average_value(start=None, end=None)[source]§

Parameters:

start (Optional[Union[core_parameters.abc.Duration, Any]]) –
end (Optional[Union[core_parameters.abc.Duration, Any]]) –

Return type:

Value

get_event_at(absolute_time)§

Get event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[T]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_at(1)
SimpleEvent(duration = 2)
>>> sequential_event.get_event_at(3)
SimpleEvent(duration = 3)
>>> sequential_event.get_event_at(100)
None

Warning:

This method ignores events with duration == 0.

get_event_from_index_sequence(index_sequence)§

Get nested Event from a sequence of indices.

Parameters:: index_sequence (Sequence[int]) – The indices of the nested Event.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> nested_sequential_event = core_events.SequentialEvent(
>>>     [core_events.SequentialEvent([core_events.SimpleEvent(2)])]
>>> )
>>> nested_sequential_event.get_event_from_index_sequence((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

get_event_index_at(absolute_time)§

Get index of event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Index of event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[int]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_index_at(1)
0
>>> sequential_event.get_event_index_at(3)
1
>>> sequential_event.get_event_index_at(100)
None

Warning:

This method ignores events with duration == 0.

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:

tuple[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

index(value, start=0, stop=9223372036854775807, /)§

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)§: Insert object before index.

integrate_interval(start, end)[source]§

Parameters:

start (Union[float, Fraction, int]) –
end (Union[float, Fraction, int]) –

Return type:

float

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

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:

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)],)

parameter_at(absolute_time)[source]§

Parameters:: absolute_time (Union[Duration, Any]) –
Return type:: Any

pop(index=-1, /)§

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)§

Remove first occurrence of value.

Raises ValueError if the value is not present.

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)])

reverse()§: Reverse IN PLACE.

sample_at(absolute_time, append_duration=DirectDuration(0))[source]§

Discretize envelope at given time

Parameters:

absolute_time (Union[core_parameters.abc.Duration, Any]) – Position in time where the envelope should define a new event.
append_duration (Union[Duration, Any]) – In case we add a new control point after any already defined point, the duration of this control point will be equal to “append_duration”. Default to core_parameters.DirectDuration(0)

Return type:

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:

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 parameter to new value for all children events.

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.

Returns:

The event.

Return type:

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

sort(*, key=None, reverse=False)§

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

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

split_child_at(absolute_time)§

Split child event in two events at absolute_time.

Parameters:

absolute_time (Union[Duration, Any]) – where child event shall be split
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:

Example:

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

squash_in(start, event_to_squash_in)§

Time-based insert of a new event into the present event.

Parameters:

start (Union[Duration, Any]) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.
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:

Squash in a new event to the present event.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.squash_in(1, core_events.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.core_events.abc.Event'>, event_to_remove=True)§

Condition-based deletion of neighboring child events.

Parameters:

condition (Callable[[Event, Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.
process_surviving_event (Callable[[Event, Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.
event_type_to_examine (Type[Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.core_events.SimpleEvent.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.
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:

value_at(absolute_time)[source]§

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) –
Return type:: Value

CurveShape§: alias of Union[float, Fraction, int]

Point§: alias of Union[tuple[Union[float, Fraction, int], Any, Union[float, Fraction, int]], tuple[Union[float, Fraction, int], Any]]

Value§: alias of Union[float, Fraction, int]

property absolute_time_tuple: tuple[Union[float, fractions.Fraction, int], ...]§: Return absolute point in time for each event.

property curve_shape_tuple: tuple[CurveShape, ...]§

property duration: Duration§

The duration of an event.

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

property is_static: bool§: Return True if Envelope only has one static value.

property parameter_tuple: tuple[Any, ...]§

property start_and_end_time_per_event: tuple[ranges.Range.Range, ...]§: Return start and end time for each 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 value_tuple: tuple[Value, ...]§

class RelativeEnvelope(*args, base_parameter_and_relative_parameter_to_absolute_parameter, **kwargs)[source]§

Envelope with relative durations and values / parameters.

Parameters:

event_iterable_or_point_sequence (Iterable[T]) – An iterable filled with events or with points. If the sequence is filled with points, the points will be converted to events. Each event represents a point in a two dimensional graph where the x-axis presents time and the y-axis a changing value. Any event class can be used. It is more important that the used event classes fit with the functions passed in the following parameters.
event_to_parameter (Callable[[core_events.abc.Event], core_constants.ParameterType]) – A function which receives an event and has to return a parameter object (any object). By default the function will ask the event for its value property. If the property can’t be found it will return 0.
event_to_curve_shape (Callable[[core_events.abc.Event], CurveShape]) – A function which receives an event and has to return a curve_shape. A curve_shape is either a float, an integer or a fraction. For a curve_shape = 0 a linear transition between two points is created. For a curve_shape > 0 the envelope changes slower at the beginning and faster at the end, for a curve_shape < 0 it is the inverse behaviour. The default function will ask the event for its curve_shape property. If the property can’t be found it will return 0.
parameter_to_value (Callable[[Value], core_constants.ParameterType]) – Convert a parameter to a value. A value is any object which supports mathematical operations.
value_to_parameter (Callable[[Value], core_constants.ParameterType]) – A callable object which converts a value to a parameter.
apply_parameter_on_event (Callable[[core_events.abc.Event, core_constants.ParameterType], None]) – A callable object which applies a parameter on an event.
apply_curve_shape_on_event (Callable[[core_events.abc.Event, CurveShape], None]) – A callable object which applies a curve shape on an event.
default_event_class (type[core_events.abc.Event]) – The default event class which describes a point.
initialise_default_event_class (Callable[[type[core_events.abc.Event], core_constants.DurationType], core_events.abc.Event]) –
base_parameter_and_relative_parameter_to_absolute_parameter (Callable[[core_constants.ParameterType, core_constants.ParameterType], core_constants.ParameterType]) – A function which runs when the resolve() is called. It expects the base parameter and the relative parameter (which is extracted from the envelope events) and should return an absolute parameter.

This class is inspired by Marc Evansteins Envelope class in his expenvelope python package and is made to fit better into the mutwo ecosystem.

Example:

>>> from mutwo import core_events
>>> core_events.Envelope([[0, 0, 1], [0.5, 1]])
Envelope([SimpleEvent(curve_shape = 1, duration = 0.5, value = 0), SimpleEvent(curve_shape = 0, duration = 0.0, value = 1)])

The RelativeEnvelope adds the resolve() method to the base class Envelope.

Public Data Attributes:

Inherited from Envelope

`Value`	alias of `Union`[`float`, `Fraction`, `int`]
`CurveShape`	alias of `Union`[`float`, `Fraction`, `int`]
`Point`	alias of `Union`[`tuple`[`Union`[`float`, `Fraction`, `int`], `Any`, `Union`[`float`, `Fraction`, `int`]], `tuple`[`Union`[`float`, `Fraction`, `int`], `Any`]]
`parameter_tuple`
`value_tuple`
`curve_shape_tuple`
`is_static`	Return True if `Envelope` only has one static value.

Inherited from SequentialEvent

`duration`	The duration of an event.
`absolute_time_tuple`	Return absolute point in time for each event.
`start_and_end_time_per_event`	Return start and end time for each event.

Inherited from ComplexEvent

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__`(*args, ...)
`resolve`(duration, base_parameter[, ...])

Inherited from Envelope

`__init__`(*args, ...)
`from_points`(point, *kwargs)
`__setitem__`(index_or_slice, event_or_sequence)	Set self[key] to value.
`value_at`(absolute_time)
`parameter_at`(absolute_time)
`sample_at`(absolute_time[, append_duration])	Discretize envelope at given time
`integrate_interval`(start, end)
`get_average_value`([start, end])
`get_average_parameter`([start, end])
`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 SequentialEvent

`get_event_index_at`(absolute_time)	Get index of event which is active at the passed absolute_time.
`get_event_at`(absolute_time)	Get event which is active at the passed absolute_time.
`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from ComplexEvent

`__init__`(*args, ...)
`__init_subclass__`([...])	This method is called when a class is subclassed.
`__repr__`()	Return repr(self).
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the ComplexEvent without any child events.
`get_event_from_index_sequence`(index_sequence)	Get nested `Event` from a sequence of indices.
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets parameter to new value for all children events.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`filter`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`([mutate])	Apply tempo envelope of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from Event

`__init__`(*args, ...)
`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 parameter to new value for all children events.
`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`.

Inherited from list

`__repr__`()	Return repr(self).
`__getattribute__`(name, /)	Return getattr(self, name).
`__lt__`(value, /)	Return self<value.
`__le__`(value, /)	Return self<=value.
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`__gt__`(value, /)	Return self>value.
`__ge__`(value, /)	Return self>=value.
`__iter__`()	Implement iter(self).
`__init__`(*args, ...)
`__len__`()	Return len(self).
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__setitem__`(index_or_slice, event_or_sequence)	Set self[key] to value.
`__delitem__`(key, /)	Delete self[key].
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__rmul__`(value, /)	Return value*self.
`__contains__`(key, /)	Return key in self.
`__iadd__`(value, /)	Implement self+=value.
`__imul__`(value, /)	Implement self*=value.
`__reversed__`()	Return a reverse iterator over the list.
`__sizeof__`()	Return the size of the list in memory, in bytes.
`clear`()	Remove all items from list.
`copy`()	Return a deep copy of the given Event.
`append`(object, /)	Append object to the end of the list.
`insert`(index, object, /)	Insert object before index.
`extend`(iterable, /)	Extend list by appending elements from the iterable.
`pop`([index])	Remove and return item at index (default last).
`remove`(value, /)	Remove first occurrence of value.
`index`(value[, start, stop])	Return first index of value.
`count`(value, /)	Return number of occurrences of value.
`reverse`()	Reverse IN PLACE.
`sort`(*[, key, reverse])	Sort the list in ascending order and return None.
`__class_getitem__`	See PEP 585

Inherited from Generic

`__class_getitem__`	See PEP 585
`__init_subclass__`([...])	This method is called when a class is subclassed.

Private Data Attributes:

`_RelativeEnvelope__parent_doc_string`
`_RelativeEnvelope__after_parameter_text_index`
`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from Envelope

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from SequentialEvent

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from ComplexEvent

_abc_impl

Inherited from Event

_abc_impl

Inherited from ABC

_abc_impl

Inherited from Generic

_is_protocol

CompletePoint§: alias of tuple[Union[float, Fraction, int], Any, Union[float, Fraction, int]]

IncompletePoint§: alias of tuple[Union[float, Fraction, int], Any]

append(object, /)§: Append object to the end of the list.

clear()§: Remove all items from list.

copy()§

Return a deep copy of the given Event.

Return type:: Event

count(value, /)§: Return number of occurrences of value.

cut_off(start, end)§

Time-based deletion / shortening of the respective event.

Parameters:

start (Union[Duration, Any]) – Duration when the cut off shall start.
end (Union[Duration, Any]) – Duration when the cut off shall end.

Return type:

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 (Union[Duration, Any]) – Duration when the cut out shall start.
end (Union[Duration, Any]) – Duration when the cut up shall end.

Return type:

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:: ComplexEvent[T]

empty_copy()§

Make a copy of the ComplexEvent without any child events.

This method is useful if one wants to copy an instance of ComplexEvent and make sure that all side attributes (e.g. any assigned properties specific to the respective subclass) get saved.

Example:

>>> from mutwo import core_events
>>> piano_voice_0 = core_events.TaggedSequentialEvent([core_events.SimpleEvent(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
TaggedSequentialEvent([])

Return type:: ComplexEvent[T]

extend(iterable, /)§: Extend list by appending elements from the iterable.

filter(condition)§

Condition-based deletion of child events.

Parameters:

condition (Callable[[Event], bool]) – Function which takes a Event and returns True or False. If the return value of the function is False the respective Event will be deleted.
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:

Example:

>>> from mutwo import core_events
>>> simultaneous_event = core_events.SimultaneousEvent(
    [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
)
>>> simultaneous_event.filter(lambda event: event.duration > 2)
>>> simultaneous_event
SimultaneousEvent([SimpleEvent(duration = 3)])

classmethod from_points(*point, **kwargs)§

Parameters:: point (Point) –
Return type:: Envelope

get_average_parameter(start=None, end=None)§

Parameters:

start (Optional[Union[float, Fraction, int]]) –
end (Optional[Union[float, Fraction, int]]) –

Return type:

Any

get_average_value(start=None, end=None)§

Parameters:

start (Optional[Union[core_parameters.abc.Duration, Any]]) –
end (Optional[Union[core_parameters.abc.Duration, Any]]) –

Return type:

Value

get_event_at(absolute_time)§

Get event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[T]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_at(1)
SimpleEvent(duration = 2)
>>> sequential_event.get_event_at(3)
SimpleEvent(duration = 3)
>>> sequential_event.get_event_at(100)
None

Warning:

This method ignores events with duration == 0.

get_event_from_index_sequence(index_sequence)§

Get nested Event from a sequence of indices.

Parameters:: index_sequence (Sequence[int]) – The indices of the nested Event.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> nested_sequential_event = core_events.SequentialEvent(
>>>     [core_events.SequentialEvent([core_events.SimpleEvent(2)])]
>>> )
>>> nested_sequential_event.get_event_from_index_sequence((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

get_event_index_at(absolute_time)§

Get index of event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Index of event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[int]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_index_at(1)
0
>>> sequential_event.get_event_index_at(3)
1
>>> sequential_event.get_event_index_at(100)
None

Warning:

This method ignores events with duration == 0.

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:

tuple[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

index(value, start=0, stop=9223372036854775807, /)§

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)§: Insert object before index.

integrate_interval(start, end)§

Parameters:

start (Union[float, Fraction, int]) –
end (Union[float, Fraction, int]) –

Return type:

float

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

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:

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)],)

parameter_at(absolute_time)§

Parameters:: absolute_time (Union[Duration, Any]) –
Return type:: Any

pop(index=-1, /)§

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)§

Remove first occurrence of value.

Raises ValueError if the value is not present.

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)])

resolve(duration, base_parameter, resolve_envelope_class=<class 'mutwo.core_events.envelopes.Envelope'>)[source]§

Parameters:

duration (Union[Duration, Any]) –
base_parameter (Any) –
resolve_envelope_class (type[mutwo.core_events.envelopes.Envelope]) –

Return type:

reverse()§: Reverse IN PLACE.

sample_at(absolute_time, append_duration=DirectDuration(0))§

Discretize envelope at given time

Parameters:

absolute_time (Union[core_parameters.abc.Duration, Any]) – Position in time where the envelope should define a new event.
append_duration (Union[Duration, Any]) – In case we add a new control point after any already defined point, the duration of this control point will be equal to “append_duration”. Default to core_parameters.DirectDuration(0)

Return type:

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:

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 parameter to new value for all children events.

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.

Returns:

The event.

Return type:

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

sort(*, key=None, reverse=False)§

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

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

split_child_at(absolute_time)§

Split child event in two events at absolute_time.

Parameters:

absolute_time (Union[Duration, Any]) – where child event shall be split
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:

Example:

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

squash_in(start, event_to_squash_in)§

Time-based insert of a new event into the present event.

Parameters:

start (Union[Duration, Any]) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.
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:

Squash in a new event to the present event.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.squash_in(1, core_events.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.core_events.abc.Event'>, event_to_remove=True)§

Condition-based deletion of neighboring child events.

Parameters:

condition (Callable[[Event, Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.
process_surviving_event (Callable[[Event, Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.
event_type_to_examine (Type[Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.core_events.SimpleEvent.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.
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:

value_at(absolute_time)§

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) –
Return type:: Value

CurveShape§: alias of Union[float, Fraction, int]

Point§: alias of Union[tuple[Union[float, Fraction, int], Any, Union[float, Fraction, int]], tuple[Union[float, Fraction, int], Any]]

Value§: alias of Union[float, Fraction, int]

property absolute_time_tuple: tuple[Union[float, fractions.Fraction, int], ...]§: Return absolute point in time for each event.

property curve_shape_tuple: tuple[CurveShape, ...]§

property duration: Duration§

The duration of an event.

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

property is_static: bool§: Return True if Envelope only has one static value.

property parameter_tuple: tuple[Any, ...]§

property start_and_end_time_per_event: tuple[ranges.Range.Range, ...]§: Return start and end time for each 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 value_tuple: tuple[Value, ...]§

class TempoEnvelope(event_iterable_or_point_sequence, tempo_envelope=None, event_to_parameter=<function Envelope.<lambda>>, event_to_curve_shape=<function Envelope.<lambda>>, parameter_to_value=<function Envelope.<lambda>>, value_to_parameter=<function Envelope.<lambda>>, apply_parameter_on_event=<function Envelope.<lambda>>, apply_curve_shape_on_event=<function Envelope.<lambda>>, default_event_class=<class 'mutwo.core_events.basic.SimpleEvent'>, initialise_default_event_class=<function Envelope.<lambda>>)[source]§

Public Data Attributes:

Inherited from Envelope

`Value`	alias of `Union`[`float`, `Fraction`, `int`]
`CurveShape`	alias of `Union`[`float`, `Fraction`, `int`]
`Point`	alias of `Union`[`tuple`[`Union`[`float`, `Fraction`, `int`], `Any`, `Union`[`float`, `Fraction`, `int`]], `tuple`[`Union`[`float`, `Fraction`, `int`], `Any`]]
`parameter_tuple`
`value_tuple`
`curve_shape_tuple`
`is_static`	Return True if `Envelope` only has one static value.

Inherited from SequentialEvent

`duration`	The duration of an event.
`absolute_time_tuple`	Return absolute point in time for each event.
`start_and_end_time_per_event`	Return start and end time for each event.

Inherited from ComplexEvent

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:

__eq__(other)

Test for checking if two objects are equal.

Inherited from Envelope

`__init__`(event_iterable_or_point_sequence[, ...])
`from_points`(point, *kwargs)
`__setitem__`(index_or_slice, event_or_sequence)	Set self[key] to value.
`value_at`(absolute_time)
`parameter_at`(absolute_time)
`sample_at`(absolute_time[, append_duration])	Discretize envelope at given time
`integrate_interval`(start, end)
`get_average_value`([start, end])
`get_average_parameter`([start, end])
`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 SequentialEvent

`get_event_index_at`(absolute_time)	Get index of event which is active at the passed absolute_time.
`get_event_at`(absolute_time)	Get event which is active at the passed absolute_time.
`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from ComplexEvent

`__init__`(event_iterable_or_point_sequence[, ...])
`__init_subclass__`([...])	This method is called when a class is subclassed.
`__repr__`()	Return repr(self).
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the ComplexEvent without any child events.
`get_event_from_index_sequence`(index_sequence)	Get nested `Event` from a sequence of indices.
`get_parameter`(parameter_name[, flat, ...])	Return event attribute with the entered name.
`set_parameter`(parameter_name, object_or_function)	Sets parameter to new value for all children events.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`filter`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`([mutate])	Apply tempo envelope of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event into the present event.
`split_child_at`(absolute_time)	Split child event in two events at `absolute_time`.

Inherited from Event

`__init__`(event_iterable_or_point_sequence[, ...])
`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 parameter to new value for all children events.
`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`.

Inherited from list

`__repr__`()	Return repr(self).
`__getattribute__`(name, /)	Return getattr(self, name).
`__lt__`(value, /)	Return self<value.
`__le__`(value, /)	Return self<=value.
`__eq__`(other)	Test for checking if two objects are equal.
`__ne__`(other)	Return self!=value.
`__gt__`(value, /)	Return self>value.
`__ge__`(value, /)	Return self>=value.
`__iter__`()	Implement iter(self).
`__init__`(event_iterable_or_point_sequence[, ...])
`__len__`()	Return len(self).
`__getitem__`(index_or_slice)	x.__getitem__(y) <==> x[y]
`__setitem__`(index_or_slice, event_or_sequence)	Set self[key] to value.
`__delitem__`(key, /)	Delete self[key].
`__add__`(event)	Return self+value.
`__mul__`(factor)	Return self*value.
`__rmul__`(value, /)	Return value*self.
`__contains__`(key, /)	Return key in self.
`__iadd__`(value, /)	Implement self+=value.
`__imul__`(value, /)	Implement self*=value.
`__reversed__`()	Return a reverse iterator over the list.
`__sizeof__`()	Return the size of the list in memory, in bytes.
`clear`()	Remove all items from list.
`copy`()	Return a deep copy of the given Event.
`append`(object, /)	Append object to the end of the list.
`insert`(index, object, /)	Insert object before index.
`extend`(iterable, /)	Extend list by appending elements from the iterable.
`pop`([index])	Remove and return item at index (default last).
`remove`(value, /)	Remove first occurrence of value.
`index`(value[, start, stop])	Return first index of value.
`count`(value, /)	Return number of occurrences of value.
`reverse`()	Reverse IN PLACE.
`sort`(*[, key, reverse])	Sort the list in ascending order and return None.
`__class_getitem__`	See PEP 585

Inherited from Generic

`__class_getitem__`	See PEP 585
`__init_subclass__`([...])	This method is called when a class is subclassed.

Private Data Attributes:

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from Envelope

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from SequentialEvent

`_class_specific_side_attribute_tuple`
`_abc_impl`

Inherited from ComplexEvent

_abc_impl

Inherited from Event

_abc_impl

Inherited from ABC

_abc_impl

Inherited from Generic

_is_protocol

Parameters:

event_iterable_or_point_sequence (Union[Iterable[T], Sequence[Point]]) –
tempo_envelope (Optional[core_events.TempoEnvelope]) –
event_to_parameter (Callable[[core_events.abc.Event], core_constants.ParameterType]) –
event_to_curve_shape (Callable[[core_events.abc.Event], CurveShape]) –
parameter_to_value (Callable[[Value], core_constants.ParameterType]) –
value_to_parameter (Callable[[Value], core_constants.ParameterType]) –
apply_parameter_on_event (Callable[[core_events.abc.Event, core_constants.ParameterType], None]) –
apply_curve_shape_on_event (Callable[[core_events.abc.Event, CurveShape], None]) –
default_event_class (type[core_events.abc.Event]) –
initialise_default_event_class (Callable[[type[core_events.abc.Event], core_constants.DurationType], core_events.abc.Event]) –

CompletePoint§: alias of tuple[Union[float, Fraction, int], Any, Union[float, Fraction, int]]

IncompletePoint§: alias of tuple[Union[float, Fraction, int], Any]

append(object, /)§: Append object to the end of the list.

clear()§: Remove all items from list.

copy()§

Return a deep copy of the given Event.

Return type:: Event

count(value, /)§: Return number of occurrences of value.

cut_off(start, end)§

Time-based deletion / shortening of the respective event.

Parameters:

start (Union[Duration, Any]) – Duration when the cut off shall start.
end (Union[Duration, Any]) – Duration when the cut off shall end.

Return type:

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 (Union[Duration, Any]) – Duration when the cut out shall start.
end (Union[Duration, Any]) – Duration when the cut up shall end.

Return type:

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:: ComplexEvent[T]

empty_copy()§

Make a copy of the ComplexEvent without any child events.

This method is useful if one wants to copy an instance of ComplexEvent and make sure that all side attributes (e.g. any assigned properties specific to the respective subclass) get saved.

Example:

>>> from mutwo import core_events
>>> piano_voice_0 = core_events.TaggedSequentialEvent([core_events.SimpleEvent(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
TaggedSequentialEvent([])

Return type:: ComplexEvent[T]

extend(iterable, /)§: Extend list by appending elements from the iterable.

filter(condition)§

Condition-based deletion of child events.

Parameters:

condition (Callable[[Event], bool]) – Function which takes a Event and returns True or False. If the return value of the function is False the respective Event will be deleted.
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:

Example:

>>> from mutwo import core_events
>>> simultaneous_event = core_events.SimultaneousEvent(
    [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
)
>>> simultaneous_event.filter(lambda event: event.duration > 2)
>>> simultaneous_event
SimultaneousEvent([SimpleEvent(duration = 3)])

classmethod from_points(*point, **kwargs)§

Parameters:: point (Point) –
Return type:: Envelope

get_average_parameter(start=None, end=None)§

Parameters:

start (Optional[Union[float, Fraction, int]]) –
end (Optional[Union[float, Fraction, int]]) –

Return type:

Any

get_average_value(start=None, end=None)§

Parameters:

start (Optional[Union[core_parameters.abc.Duration, Any]]) –
end (Optional[Union[core_parameters.abc.Duration, Any]]) –

Return type:

Value

get_event_at(absolute_time)§

Get event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[T]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_at(1)
SimpleEvent(duration = 2)
>>> sequential_event.get_event_at(3)
SimpleEvent(duration = 3)
>>> sequential_event.get_event_at(100)
None

Warning:

This method ignores events with duration == 0.

get_event_from_index_sequence(index_sequence)§

Get nested Event from a sequence of indices.

Parameters:: index_sequence (Sequence[int]) – The indices of the nested Event.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> nested_sequential_event = core_events.SequentialEvent(
>>>     [core_events.SequentialEvent([core_events.SimpleEvent(2)])]
>>> )
>>> nested_sequential_event.get_event_from_index_sequence((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

get_event_index_at(absolute_time)§

Get index of event which is active at the passed absolute_time.

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) – The absolute time where the method shall search for the active event.
Returns:: Index of event if there is any event at the requested absolute time and None if there isn’t any event.
Return type:: Optional[int]

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(2), core_events.SimpleEvent(3)])
>>> sequential_event.get_event_index_at(1)
0
>>> sequential_event.get_event_index_at(3)
1
>>> sequential_event.get_event_index_at(100)
None

Warning:

This method ignores events with duration == 0.

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:

tuple[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

index(value, start=0, stop=9223372036854775807, /)§

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)§: Insert object before index.

integrate_interval(start, end)§

Parameters:

start (Union[float, Fraction, int]) –
end (Union[float, Fraction, int]) –

Return type:

float

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

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:

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)],)

parameter_at(absolute_time)§

Parameters:: absolute_time (Union[Duration, Any]) –
Return type:: Any

pop(index=-1, /)§

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)§

Remove first occurrence of value.

Raises ValueError if the value is not present.

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)])

reverse()§: Reverse IN PLACE.

sample_at(absolute_time, append_duration=DirectDuration(0))§

Discretize envelope at given time

Parameters:

absolute_time (Union[core_parameters.abc.Duration, Any]) – Position in time where the envelope should define a new event.
append_duration (Union[Duration, Any]) – In case we add a new control point after any already defined point, the duration of this control point will be equal to “append_duration”. Default to core_parameters.DirectDuration(0)

Return type:

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:

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 parameter to new value for all children events.

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.

Returns:

The event.

Return type:

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

sort(*, key=None, reverse=False)§

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

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

split_child_at(absolute_time)§

Split child event in two events at absolute_time.

Parameters:

absolute_time (Union[Duration, Any]) – where child event shall be split
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:

Example:

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

squash_in(start, event_to_squash_in)§

Time-based insert of a new event into the present event.

Parameters:

start (Union[Duration, Any]) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.
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:

Squash in a new event to the present event.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.squash_in(1, core_events.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.core_events.abc.Event'>, event_to_remove=True)§

Condition-based deletion of neighboring child events.

Parameters:

condition (Callable[[Event, Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.
process_surviving_event (Callable[[Event, Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.
event_type_to_examine (Type[Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.core_events.SimpleEvent.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.
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:

value_at(absolute_time)§

Parameters:: absolute_time (Union[core_parameters.abc.Duration, Any]) –
Return type:: Value

CurveShape§: alias of Union[float, Fraction, int]

Point§: alias of Union[tuple[Union[float, Fraction, int], Any, Union[float, Fraction, int]], tuple[Union[float, Fraction, int], Any]]

Value§: alias of Union[float, Fraction, int]

property absolute_time_tuple: tuple[Union[float, fractions.Fraction, int], ...]§: Return absolute point in time for each event.

property curve_shape_tuple: tuple[CurveShape, ...]§

property duration: Duration§

The duration of an event.

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

property is_static: bool§: Return True if Envelope only has one static value.

property parameter_tuple: tuple[Any, ...]§

property start_and_end_time_per_event: tuple[ranges.Range.Range, ...]§: Return start and end time for each 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 value_tuple: tuple[Value, ...]§

mutwo.core_events.abc §

Abstract base classes for events (definition of public API).

class ComplexEvent(iterable=[], tempo_envelope=None)[source]§

Abstract Event-Object, which contains other Event-Objects.

Parameters:

iterable (Iterable[T]) –
tempo_envelope (Optional[core_events.TempoEnvelope]) –

append(object, /)§: Append object to the end of the list.

clear()§: Remove all items from list.

copy()§

Return a deep copy of the given Event.

Return type:: Event

count(value, /)§: Return number of occurrences of value.

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

Optional[Event]

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)])

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

Optional[Event]

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()[source]§

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:: ComplexEvent[T]

empty_copy()[source]§

Make a copy of the ComplexEvent without any child events.

This method is useful if one wants to copy an instance of ComplexEvent and make sure that all side attributes (e.g. any assigned properties specific to the respective subclass) get saved.

Example:

>>> from mutwo import core_events
>>> piano_voice_0 = core_events.TaggedSequentialEvent([core_events.SimpleEvent(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
TaggedSequentialEvent([])

Return type:: ComplexEvent[T]

extend(iterable, /)§: Extend list by appending elements from the iterable.

filter(condition)[source]§

Condition-based deletion of child events.

Parameters:

condition (Callable[[Event], bool]) – Function which takes a Event and returns True or False. If the return value of the function is False the respective Event will be deleted.
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:

Example:

>>> from mutwo import core_events
>>> simultaneous_event = core_events.SimultaneousEvent(
    [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)]
)
>>> simultaneous_event.filter(lambda event: event.duration > 2)
>>> simultaneous_event
SimultaneousEvent([SimpleEvent(duration = 3)])

get_event_from_index_sequence(index_sequence)[source]§

Get nested Event from a sequence of indices.

Parameters:: index_sequence (Sequence[int]) – The indices of the nested Event.
Return type:: Event

Example:

>>> from mutwo import core_events
>>> nested_sequential_event = core_events.SequentialEvent(
>>>     [core_events.SequentialEvent([core_events.SimpleEvent(2)])]
>>> )
>>> nested_sequential_event.get_event_from_index_sequence((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

get_parameter(parameter_name, flat=False, filter_undefined=False)[source]§

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:

tuple[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

index(value, start=0, stop=9223372036854775807, /)§

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)§: Insert object before index.

metrize(mutate=True)[source]§

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

mutate_parameter(parameter_name, function)[source]§

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:

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)],)

pop(index=-1, /)§

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)§

Remove first occurrence of value.

Raises ValueError if the value is not present.

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)])

reverse()§: Reverse IN PLACE.

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:

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)[source]§

Sets parameter to new value for all children events.

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.

Returns:

The event.

Return type:

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent(
>>>     [core_events.SimpleEvent(2), core_events.SimpleEvent(3)]
>>> )
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

sort(*, key=None, reverse=False)§

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

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

abstract split_child_at(absolute_time)[source]§

Split child event in two events at absolute_time.

Parameters:

absolute_time (Duration) – where child event shall be split
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:

Optional[ComplexEvent[T]]

Example:

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

abstract squash_in(start, event_to_squash_in)[source]§

Time-based insert of a new event into the present event.

Parameters:

start (Duration) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.
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:

Optional[ComplexEvent[T]]

Squash in a new event to the present event.

Example:

>>> from mutwo import core_events
>>> sequential_event = core_events.SequentialEvent([core_events.SimpleEvent(3)])
>>> sequential_event.squash_in(1, core_events.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.core_events.abc.Event'>, event_to_remove=True)[source]§

Condition-based deletion of neighboring child events.

Parameters:

condition (Callable[[Event, Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.
process_surviving_event (Callable[[Event, Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.
event_type_to_examine (Type[Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.core_events.SimpleEvent.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.
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:

abstract property duration: Duration§

The duration of an event.

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

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.

class Event(tempo_envelope=None)[source]§

Abstract Event-Object

Parameters:: tempo_envelope (Optional[core_events.TempoEnvelope]) – An envelope which describes the dynamic tempo of an event.

copy()[source]§

Return a deep copy of the given Event.

Return type:: Event

abstract cut_off(start, end)[source]§

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:

Optional[Event]

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)])

abstract cut_out(start, end)[source]§

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:

Optional[Event]

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)])

abstract destructive_copy()[source]§

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

abstract get_parameter(parameter_name, flat=False, filter_undefined=False)[source]§

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:

Union[tuple[Any, …], 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

abstract metrize()[source]§

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

Return type:: Optional[Event]

abstract mutate_parameter(parameter_name, function)[source]§

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:

Optional[Event]

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()[source]§

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)[source]§

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: