mutwo.core_events ¶

Time-based Event abstractions.

Event objects can be understood as the core objects of the mutwo framework. They all own a duration (of type Duration), a tempo (of type Tempo) and a tag (of type str or None).

The most often used classes are:

mutwo.core_events.Chronon: the leaf or the node of a tree

mutwo.core_events.Consecution: a sequence of other events

mutwo.core_events.Concurrence: a simultaneous set of other events

Further more complex Event classes with more relevant attributes can be generated through inheriting from basic classes.

Object	Documentation
`mutwo.core_events.Chronon`	A `Chronon` is an event that cannot be further subdivided (a leaf of a tree).
`mutwo.core_events.Consecution`	A :class:`Consecution`hosts events that take place one after the other.
`mutwo.core_events.Concurrence`	A `Concurrence` hosts events that take place at the same time.
`mutwo.core_events.Envelope`	Model continuous changing values (e.g. glissandi, crescendo).

class Chronon(duration, *args, **kwargs)[source]¶

Bases: Event

A Chronon is an event that cannot be further subdivided (a leaf of a tree).

Parameters:

duration (core_parameters.abc.Duration.Type) – The duration of the Chronon. Mutwo converts the incoming object to a mutwo.core_parameters.abc.Duration object with the global core_parameters.abc.Duration.from_any callable.
*args –
Arguments parsed to mutwo.core_events.abc.Event.
**kwargs –
Keyword arguments parsed to mutwo.core_events.abc.Event.

Example:

>>> from mutwo import core_events
>>> chronon = core_events.Chronon(2)
>>> chronon
Chronon(duration=DirectDuration(2.0))
>>> print(chronon)  # pretty print for debugging
C(dur=D(2.0))

Public Data Attributes:

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

Inherited from Event

`duration`	The duration of an event.
`tempo`	The tempo of an event.

Public Methods:

`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`(args, *kwargs)	Sets event parameter to new value.
`metrize`()	Apply tempo 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

`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`()	Set events tempo so that one beat equals one second (tempo 60).
`metrize`()	Apply tempo 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 into n events at `absolute_time`.

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

cut_off(start, end)[source]¶

Time-based deletion / shortening of the respective event.

Parameters:

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

Return type:

Chronon

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_off(1, 3)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0))])

cut_out(start, end)[source]¶

Time-based slicing of the respective event.

Parameters:

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

Return type:

Chronon

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_out(1, 4)
Consecution([Chronon(duration=DirectDuration(2.0)), Chronon(duration=DirectDuration(1.0))])

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 returns 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
>>> chn0 = core_events.Chronon(2)
>>> chn1 = core_events.Chronon(3)
>>> cns = core_events.Consecution([chn0, chn1, chn0])
>>> cns_copy = copy.deepcopy(cns)
>>> cns_destr_copy = cns.destructive_copy()
>>> cns_copy[0].duration = 10  # setting the duration of the first event
>>> cns_destr_copy[0].duration = 10
>>> # return True because the first and the third objects share the same
>>> # reference (both are the same copy of 'my_chronon_0')
>>> cns_copy[0].duration == cns_copy[2].duration
True
>>> # return False because destructive_copy forgets the shared reference
>>> cns_destr_copy[0].duration == cns_destr_copy[2].duration
False

Return type:: Chronon

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 (bool) – 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.Chronon.

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
>>> cns = core_events.Consecution(
...     [core_events.Chronon(2), core_events.Chronon(3)]
... )
>>> cns.get_parameter('duration')
(DirectDuration(2.0), DirectDuration(3.0))
>>> chn = core_events.Chronon(10)
>>> chn.get_parameter('duration')
DirectDuration(10.0)
>>> chn.get_parameter('undefined_parameter')

metrize()[source]¶

Apply tempo of event on itself

Metrize is only syntactic sugar for a call of EventToMetrizedEvent:

>>> from mutwo import core_converters
>>> from mutwo import core_events
>>> chn = core_events.Chronon(1)
>>> chn.tempo = core_parameters.FlexTempo([[0, 100], [1, 40]])
>>> core_converters.EventToMetrizedEvent().convert(chn) == chn.metrize()
True

Return type:: Chronon

set_parameter(*args, **kwargs)[source]¶

Sets event parameter to new value.

Parameters:

parameter_name – The name of the parameter which values shall be changed.
object_or_function – 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 is assigned to the object.
set_unassigned_parameter – If set to False a new parameter is only 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 is simply ignored.

Return type:

Chronon

Example:

>>> from mutwo import core_events
>>> chronon = core_events.Chronon(2)
>>> chronon.set_parameter(
...     'duration', lambda old_duration: old_duration * 2
... )
Chronon(duration=DirectDuration(4.0))
>>> chronon.duration
DirectDuration(4.0)
>>> chronon.set_parameter('duration', 3)
Chronon(duration=DirectDuration(3.0))
>>> chronon.duration
DirectDuration(3.0)
>>> chronon.set_parameter(
...     'unknown_parameter', 10, set_unassigned_parameter=False
... )  # this will be ignored
Chronon(duration=DirectDuration(3.0))
>>> chronon.unknown_parameter
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'Chronon' object has no attribute 'unknown_parameter'
>>> chronon.set_parameter(
...     'unknown_parameter', 10, set_unassigned_parameter=True
... )  # this will be written
Chronon(duration=DirectDuration(3.0), unknown_parameter=10)
>>> chronon.unknown_parameter
10

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', 'tag')¶

class Consecution(iterable=[], *, tempo=None, tag=None)[source]¶

Bases: Compound, Generic[T]

A :class:`Consecution`hosts events that take place one after the other.

Public Data Attributes:

`duration`	The duration of an event.
`absolute_time_tuple`	Return start time as `core_parameters.abc.Duration` for each event.
`absolute_time_in_floats_tuple`	Return start time as float for each event.
`start_and_end_time_per_event`	Return start and end time for each event.

Inherited from Compound

duration

The duration of an event.

Inherited from Event

`duration`	The duration of an event.
`tempo`	The tempo of an event.

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 with overriding given event.
`slide_in`(start, event_to_slide_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`.
`split_at`(*absolute_time[, ...])	Split event into n events at `absolute_time`.
`extend_until`(duration[, ...])	Prolong event until at least duration by appending an empty event.

Inherited from Compound

`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the Compound 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.
`remove_by`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`()	Apply tempo of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event with overriding given event.
`slide_in`(start, event_to_slide_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`.
`extend_until`(duration[, ...])	Prolong event until at least duration by appending an empty event.

Inherited from 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`()	Set events tempo so that one beat equals one second (tempo 60).
`metrize`()	Apply tempo 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 into n events at `absolute_time`.

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

Inherited from list

`clear`()	Remove all items from list.
`copy`()	Return a shallow copy of the list.
`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.

Parameters:

iterable (Iterable[T]) –
tempo (Optional[core_parameters.abc.Tempo]) –
tag (Optional[str]) –

cut_off(start, end)[source]¶

Time-based deletion / shortening of the respective event.

Parameters:

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

Return type:

Consecution[T]

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_off(1, 3)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0))])

cut_out(start, end)[source]¶

Time-based slicing of the respective event.

Parameters:

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

Return type:

Consecution[T]

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_out(1, 4)
Consecution([Chronon(duration=DirectDuration(2.0)), Chronon(duration=DirectDuration(1.0))])

extend_until(duration, duration_to_white_space=None, prolong_chronon=True)[source]¶

Prolong event until at least duration by appending an empty event.

Parameters:

duration (core_parameters.abc.Duration.Type) – Until which duration the event shall be extended. If event is already longer than or equal to given duration, nothing will be changed. For Concurrence the default value is None which is equal to the duration of the Concurrence.
duration_to_white_space (Optional[Callable[[core_parameters.abc.Duration], Event]]) – A function which creates the ‘rest’ or ‘white space’ event from Duration. If this is None mutwo will fall back to use the default function which is mutwo.core_events.configurations.DEFAULT_DURATION_TO_WHITE_SPACE. Default to None.
prolong_chronon (bool) – If set to True mutwo will prolong a single Chronon inside a Concurrence. If set to False mutwo will raise an ImpossibleToExtendUntilError in case it finds a single Chronon inside a Concurrence. This doesn’t effect Chronon inside a Consecution, here we can simply append a new white space event.

Return type:

Consecution[T]

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(1)])
>>> cns.extend_until(10)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(9.0))])

get_event_at(absolute_time)[source]¶

Get event which is active at the passed absolute_time.

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – 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
>>> consecution = core_events.Consecution([core_events.Chronon(2), core_events.Chronon(3)])
>>> consecution.get_event_at(1)
Chronon(duration=DirectDuration(2.0))
>>> consecution.get_event_at(3)
Chronon(duration=DirectDuration(3.0))
>>> consecution.get_event_at(100)

Warning:

This method ignores events with duration == 0.

get_event_index_at(absolute_time)[source]¶

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

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – 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
>>> consecution = core_events.Consecution([core_events.Chronon(2), core_events.Chronon(3)])
>>> consecution.get_event_index_at(1)
0
>>> consecution.get_event_index_at(3)
1
>>> consecution.get_event_index_at(100)

Warning:

This method ignores events with duration == 0.

slide_in(start, event_to_slide_in)[source]¶

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

Parameters:

start (core_parameters.abc.Duration.Type) – Absolute time where the event shall be inserted.
event_to_slide_in (core_events.abc.Event) – the event that shall be slide into the present event.

Return type:

Consecution[T]

Unlike Compound.squash_in the events duration will be prolonged by the event which is added. If there is an event at start the event will be split into two parts, but it won’t be shortened or processed in any other way.

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.slide_in(1, core_events.Chronon(1.5))
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(1.5)), Chronon(duration=DirectDuration(2.0))])

split_at(*absolute_time, ignore_invalid_split_point=False)[source]¶

Split event into n events at absolute_time.

Parameters:

*absolute_time (core_parameters.abc.Duration.Type) –
where event shall be split
ignore_invalid_split_point (bool) – If set to True split_at won’t raise mutwo.core_utilities.SplitError in case a split time isn’t inside the duration range of the event. Otherwise the exception is raised. Default to False.

Raises:

mutwo.core_utilities.NoSplitTimeError if no absolute_time is given. Raises mutwo.core_utilities.InvalidAbsoluteTime if any absolute_time is smaller than 0. Raises mutwo.core_utilities.SplitError if any absolute_time is bigger than the events duration and ignore_invalid_split_point is not set.

Returns:

Tuple of events that result from splitting the present event.

Return type:

tuple[Consecution, …]

Hint:

Calling split_at once with multiple split time arguments is much more efficient than calling split_at multiple times with only one split time for mutwo.core_events.Consecution.

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(3)])
>>> cns.split_at(1)
(Consecution([Chronon(duration=DirectDuration(1.0))]), Consecution([Chronon(duration=DirectDuration(2.0))]))
>>> cns[0].split_at(1)
(Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0)))

split_child_at(absolute_time)[source]¶

Split child event in two events at absolute_time.

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – where child event shall be split
Return type:: Consecution[T]

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.split_child_at(1)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0))])

squash_in(start, event_to_squash_in)[source]¶

Time-based insert of a new event with overriding given event.

Parameters:

start (core_parameters.abc.Duration.Type) – Absolute time where the event shall be inserted.
event_to_squash_in (core_events.abc.Event) – the event that shall be squashed into the present event.

Return type:

Consecution[T]

Unlike Compound.slide_in the events duration won’t change. If there is already an event at start this event will be shortened or removed.

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.squash_in(1, core_events.Chronon(1.5))
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(1.5)), Chronon(duration=DirectDuration(0.5))])

property absolute_time_in_floats_tuple: tuple[float, ...]¶: Return start time as float for each event.

property absolute_time_tuple: tuple[mutwo.core_parameters.abc.Duration, ...]¶: Return start time as core_parameters.abc.Duration 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.

class Concurrence(iterable=[], *, tempo=None, tag=None)[source]¶

Bases: Compound, Generic[T]

A Concurrence hosts events that take place at the same time.

Public Data Attributes:

duration

The duration of an event.

Inherited from Compound

duration

The duration of an event.

Inherited from Event

`duration`	The duration of an event.
`tempo`	The tempo of an event.

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 with overriding given event.
`slide_in`(start, event_to_slide_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`.
`extend_until`([duration, ...])	Prolong event until at least duration by appending an empty event.
`concatenate_by_index`(other)	Concatenate with other `Concurrence` along their indices.
`concatenate_by_tag`(other)	Concatenate with other `Concurrence` along their tags.
`sequentialize`([slice_tuple_to_event])	Convert parallel structure to a consuential structure.
`split_at`(*absolute_time[, ...])	Split event into n events at `absolute_time`.

Inherited from Compound

`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the Compound 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.
`remove_by`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`()	Apply tempo of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event with overriding given event.
`slide_in`(start, event_to_slide_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`.
`extend_until`(duration[, ...])	Prolong event until at least duration by appending an empty event.

Inherited from 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`()	Set events tempo so that one beat equals one second (tempo 60).
`metrize`()	Apply tempo 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 into n events at `absolute_time`.

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

Inherited from list

`clear`()	Remove all items from list.
`copy`()	Return a shallow copy of the list.
`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.

Parameters:

iterable (Iterable[T]) –
tempo (Optional[core_parameters.abc.Tempo]) –
tag (Optional[str]) –

concatenate_by_index(other)[source]¶

Concatenate with other Concurrence along their indices.

Parameters:: other (Concurrence) – The other Concurrence with which to concatenate. The other Concurrence can contain more or less events.
Raises:: core_utilities.ConcatenationError – If there are any Chronon inside a Concurrence.
Return type:: Concurrence

Hint:

Similarly to Pythons list.extend the concatenation simply appends the children of the other event to the sequence without copying them. This means when changing the children in the new event, it also changes the child event in the original sequence. If you want to avoid this, call event.copy() before concatenating it to the host event.

Example:

>>> from mutwo import core_events
>>> cnc = core_events.Concurrence(
...     [core_events.Consecution([core_events.Chronon(1)])]
... )
>>> cnc.concatenate_by_index(cnc)
Concurrence([Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(1.0))])])

concatenate_by_tag(other)[source]¶

Concatenate with other Concurrence along their tags.

Parameters:

other (Concurrence) – The other Concurrence with which to concatenate. The other Concurrence can contain more or less events.

Returns:

Concatenated event.

Raises:

core_utilities.NoTagError – If any child event doesn’t have a ‘tag’ attribute.
core_utilities.ConcatenationError – If there are any Chronon inside a Concurrence.

Return type:

Concurrence

Hint:

Similarly to Pythons list.extend the concatenation simply appends the children of the other event to the sequence without copying them. This means when changing the children in the new event, it also changes the child event in the original sequence. If you want to avoid this, call event.copy() before concatenating it to the host event.

Example:

>>> from mutwo import core_events
>>> cnc = core_events.Concurrence(
...      [core_events.Consecution([core_events.Chronon(1)], tag="test")]
...  )
>>> cnc.concatenate_by_tag(cnc)
Concurrence([Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(1.0))])])

cut_off(start, end)[source]¶

Time-based deletion / shortening of the respective event.

Parameters:

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

Return type:

Concurrence[T]

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_off(1, 3)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0))])

cut_out(start, end)[source]¶

Time-based slicing of the respective event.

Parameters:

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

Return type:

Concurrence[T]

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_out(1, 4)
Consecution([Chronon(duration=DirectDuration(2.0)), Chronon(duration=DirectDuration(1.0))])

extend_until(duration=None, duration_to_white_space=None, prolong_chronon=True)[source]¶

Prolong event until at least duration by appending an empty event.

Parameters:

duration (core_parameters.abc.Duration.Type) – Until which duration the event shall be extended. If event is already longer than or equal to given duration, nothing will be changed. For Concurrence the default value is None which is equal to the duration of the Concurrence.
duration_to_white_space (Optional[Callable[[core_parameters.abc.Duration], Event]]) – A function which creates the ‘rest’ or ‘white space’ event from Duration. If this is None mutwo will fall back to use the default function which is mutwo.core_events.configurations.DEFAULT_DURATION_TO_WHITE_SPACE. Default to None.
prolong_chronon (bool) – If set to True mutwo will prolong a single Chronon inside a Concurrence. If set to False mutwo will raise an ImpossibleToExtendUntilError in case it finds a single Chronon inside a Concurrence. This doesn’t effect Chronon inside a Consecution, here we can simply append a new white space event.

Return type:

Concurrence[T]

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(1)])
>>> cns.extend_until(10)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(9.0))])

sequentialize(slice_tuple_to_event=None)[source]¶

Convert parallel structure to a consuential structure.

Parameters:: slice_tuple_to_event (Optional[Callable[[tuple[core_events.abc.Event, ...]], core_events.abc.Event]]) – In order to sequentialize the event mutwo splits each child event into small ‘event slices’. These ‘event slices’ are simply events created by the split_at method. Each of those parallel slice groups need to be bound together to one new event. These new events are consuentially ordered to result in a new consuential structure. The simplest and default way to archive this is by simply putting all event parts into a new Concurrence, so the resulting Consecution is a sequence of Concurrence. This parameter is available so that users can convert her/his parallel structure in meaningful ways (for instance to imitate the .chordify method from music21 <https://web.mit.edu/music21/doc/usersGuide/usersGuide_09_chordify.html> which transforms polyphonic music to a chord structure). If None slice_tuple_to_event is set to Concurrence. Default to None.
Return type:: Consecution

Warning:

Because the returned event is a Consecution class specific side attributes of the Concurrence aren’t persistent in the returned event.

Example:

>>> from mutwo import core_events
>>> e = core_events.Concurrence(
...     [
...         core_events.Consecution(
...             [core_events.Chronon(2), core_events.Chronon(1)]
...         ),
...         core_events.Consecution(
...             [core_events.Chronon(3)]
...         ),
...     ]
... )
>>> cns = e.sequentialize()
>>> print(cns)
Cons(Conc(Cons(C(dur=D(2.0))), Cons(C(dur=D(2.0)))), Conc(Cons(C(dur=D(1.0))), Cons(C(dur=D(1.0)))))

slide_in(start, event_to_slide_in)[source]¶

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

Parameters:

start (core_parameters.abc.Duration.Type) – Absolute time where the event shall be inserted.
event_to_slide_in (core_events.abc.Event) – the event that shall be slide into the present event.

Return type:

Concurrence[T]

Unlike Compound.squash_in the events duration will be prolonged by the event which is added. If there is an event at start the event will be split into two parts, but it won’t be shortened or processed in any other way.

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.slide_in(1, core_events.Chronon(1.5))
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(1.5)), Chronon(duration=DirectDuration(2.0))])

split_at(*absolute_time, ignore_invalid_split_point=False)[source]¶

Split event into n events at absolute_time.

Parameters:

*absolute_time (core_parameters.abc.Duration.Type) –
where event shall be split
ignore_invalid_split_point (bool) – If set to True split_at won’t raise mutwo.core_utilities.SplitError in case a split time isn’t inside the duration range of the event. Otherwise the exception is raised. Default to False.

Raises:

mutwo.core_utilities.NoSplitTimeError if no absolute_time is given. Raises mutwo.core_utilities.InvalidAbsoluteTime if any absolute_time is smaller than 0. Raises mutwo.core_utilities.SplitError if any absolute_time is bigger than the events duration and ignore_invalid_split_point is not set.

Returns:

Tuple of events that result from splitting the present event.

Return type:

tuple[Concurrence, …]

Hint:

Calling split_at once with multiple split time arguments is much more efficient than calling split_at multiple times with only one split time for mutwo.core_events.Consecution.

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(3)])
>>> cns.split_at(1)
(Consecution([Chronon(duration=DirectDuration(1.0))]), Consecution([Chronon(duration=DirectDuration(2.0))]))
>>> cns[0].split_at(1)
(Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0)))

split_child_at(absolute_time)[source]¶

Split child event in two events at absolute_time.

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – where child event shall be split
Return type:: Concurrence[T]

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.split_child_at(1)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0))])

squash_in(start, event_to_squash_in)[source]¶

Time-based insert of a new event with overriding given event.

Parameters:

start (core_parameters.abc.Duration.Type) – Absolute time where the event shall be inserted.
event_to_squash_in (core_events.abc.Event) – the event that shall be squashed into the present event.

Return type:

Concurrence[T]

Unlike Compound.slide_in the events duration won’t change. If there is already an event at start this event will be shortened or removed.

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.squash_in(1, core_events.Chronon(1.5))
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(1.5)), Chronon(duration=DirectDuration(0.5))])

property duration: Duration¶

The duration of an event.

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

class Envelope(event_iterable_or_point_sequence, *args, **kwargs)[source]¶

Bases: Consecution, Generic[T]

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 are 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.

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

Hint:

When comparing two envelopes (e.g. env0 == env1) mutwo only returns True in case all control points (= events inside the envelope) are equal between both envelopes. So mutwo won’t make the much more complicated test to check if two envelopes have the same shape (= the same value at each env0.value_at(x) == env1.value_at(x) for each possible x). Such a test is not implemented yet.

Example:

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

Public Data Attributes:

`Value`
`Parameter`
`CurveShape`
`Point`
`parameter_tuple`	Get parameter for each event inside `Envelope`.
`value_tuple`	Get value for each event inside `Envelope`.
`curve_shape_tuple`	Get curve_shape for each event inside `Envelope`.
`is_static`	Return True if `Envelope` only has one static value.

Inherited from Consecution

`duration`	The duration of an event.
`absolute_time_tuple`	Return start time as `core_parameters.abc.Duration` for each event.
`absolute_time_in_floats_tuple`	Return start time as float for each event.
`start_and_end_time_per_event`	Return start and end time for each event.

Inherited from Compound

duration

The duration of an event.

Inherited from Event

`duration`	The duration of an event.
`tempo`	The tempo of an event.

Public Methods:

`event_to_parameter`(event)	Fetch 'parameter' from event.
`event_to_curve_shape`(event)	Fetch 'curve_shape' from event.
`parameter_to_value`(parameter)	Convert from 'parameter' to 'value'.
`value_to_parameter`(value)	Convert from 'value' to 'parameter'.
`apply_parameter_on_event`(event, parameter)	Apply 'parameter' on given event
`apply_curve_shape_on_event`(event, curve_shape)	Apply 'curve_shape' on given event
`initialise_default_event_class`(duration)	Create new event object from event type.
`value_at`(absolute_time)	Get value at absolute_time.
`parameter_at`(absolute_time)	Get parameter at absolute_time.
`curve_shape_at`(absolute_time)	Get curve_shape at absolute_time.
`point_at`(absolute_time)	Get point at absolute_time.
`sample_at`(absolute_time[, append_duration])	Discretize envelope at given time
`time_range_to_point_tuple`(time_range)	Return all control points in given time range.
`integrate_interval`(start, end)	Integrate envelope above given interval.
`get_average_value`([start, end])	Find average value in given interval.
`get_average_parameter`([start, end])	Find average parameter in given interval.
`cut_out`(start, end)	Time-based slicing of the respective event.
`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`extend_until`(duration[, ...])	Prolong event until at least duration by appending an empty event.
`split_at`(*absolute_time[, ...])	Split event into n events at `absolute_time`.

Inherited from Consecution

`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 with overriding given event.
`slide_in`(start, event_to_slide_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`.
`split_at`(*absolute_time[, ...])	Split event into n events at `absolute_time`.
`extend_until`(duration[, ...])	Prolong event until at least duration by appending an empty event.

Inherited from Compound

`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`empty_copy`()	Make a copy of the Compound 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.
`remove_by`(condition)	Condition-based deletion of child events.
`tie_by`(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring child events.
`metrize`()	Apply tempo of event on itself
`squash_in`(start, event_to_squash_in)	Time-based insert of a new event with overriding given event.
`slide_in`(start, event_to_slide_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`.
`extend_until`(duration[, ...])	Prolong event until at least duration by appending an empty event.

Inherited from 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`()	Set events tempo so that one beat equals one second (tempo 60).
`metrize`()	Apply tempo 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 into n events at `absolute_time`.

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

Inherited from list

`clear`()	Remove all items from list.
`copy`()	Return a shallow copy of the list.
`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.

CompletePoint¶: alias of tuple[core_parameters.abc.Duration, Any, float | Fraction | int | Fraction]

IncompletePoint¶: alias of tuple[core_parameters.abc.Duration, Any]

default_event_class¶: alias of Chronon

apply_curve_shape_on_event(event, curve_shape)[source]¶

Apply ‘curve_shape’ on given event

Parameters:

event (Event) –
curve_shape (float | fractions.Fraction | int | quicktions.Fraction) –

apply_parameter_on_event(event, parameter)[source]¶

Apply ‘parameter’ on given event

Parameters:

event (Event) –
parameter (Any) –

curve_shape_at(absolute_time)[source]¶

Get curve_shape at absolute_time.

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – Absolute position in time at which curve shape shall be found. This is ‘x’ in the function notation ‘f(x)’.
Return type:: float

cut_off(start, end)[source]¶

Time-based deletion / shortening of the respective event.

Parameters:

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

Return type:

Envelope[T]

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_off(1, 3)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0))])

cut_out(start, end)[source]¶

Time-based slicing of the respective event.

Parameters:

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

Return type:

Envelope[T]

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_out(1, 4)
Consecution([Chronon(duration=DirectDuration(2.0)), Chronon(duration=DirectDuration(1.0))])

event_to_curve_shape(event)[source]¶

Fetch ‘curve_shape’ from event.

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

event_to_parameter(event)[source]¶

Fetch ‘parameter’ from event.

Parameters:: event (Event) –
Return type:: Any

extend_until(duration, duration_to_white_space=None, prolong_chronon=True)[source]¶

Prolong event until at least duration by appending an empty event.

Parameters:

duration (core_parameters.abc.Duration.Type) – Until which duration the event shall be extended. If event is already longer than or equal to given duration, nothing will be changed. For Concurrence the default value is None which is equal to the duration of the Concurrence.
duration_to_white_space (Optional[Callable[[core_parameters.abc.Duration], Event]]) – A function which creates the ‘rest’ or ‘white space’ event from Duration. If this is None mutwo will fall back to use the default function which is mutwo.core_events.configurations.DEFAULT_DURATION_TO_WHITE_SPACE. Default to None.
prolong_chronon (bool) – If set to True mutwo will prolong a single Chronon inside a Concurrence. If set to False mutwo will raise an ImpossibleToExtendUntilError in case it finds a single Chronon inside a Concurrence. This doesn’t effect Chronon inside a Consecution, here we can simply append a new white space event.

Return type:

Envelope[T]

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(1)])
>>> cns.extend_until(10)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(9.0))])

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

Find average parameter in given interval.

Parameters:

start (Optional[core_parameters.abc.Duration.Type]) – The beginning of the interval. If set to None this is set be 0. Default to None.
end (Optional[core_parameters.abc.Duration.Type]) – The end of the interval. If set to None this is set to the duration of the Envelope.. Default to None.

Return type:

Any

Example:

>>> from mutwo import core_events
>>> e = core_events.Envelope([[0, 1], [2, 0]])
>>> e.get_average_parameter()
0.5
>>> e.get_average_parameter(0.5)
0.375
>>> e.get_average_parameter(0.5, 1)
0.625

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

Find average value in given interval.

Parameters:

start (Optional[core_parameters.abc.Duration.Type]) – The beginning of the interval. If set to None this is set to0. Default to None.
end (Optional[core_parameters.abc.Duration.Type]) – The end of the interval. If set to None this is set to the duration of the Envelope.. Default to None.

Return type:

Value

Example:

>>> from mutwo import core_events
>>> e = core_events.Envelope([[0, 1], [2, 0]])
>>> e.get_average_value()
0.5
>>> e.get_average_value(0.5)
0.375
>>> e.get_average_value(0.5, 1)
0.625

initialise_default_event_class(duration)[source]¶

Create new event object from event type.

Parameters:: duration (Duration) –
Return type:: Event

integrate_interval(start, end)[source]¶

Integrate envelope above given interval.

Parameters:

start (core_parameters.abc.Duration.Type) – Beginning of integration interval.
end (core_parameters.abc.Duration.Type) – End of integration interval.

Return type:

float

parameter_at(absolute_time)[source]¶

Get parameter at absolute_time.

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – Absolute position in time at which parameter shall be found. This is ‘x’ in the function notation ‘f(x)’.
Return type:: Any

parameter_to_value(parameter)[source]¶

Convert from ‘parameter’ to ‘value’.

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

point_at(absolute_time)[source]¶

Get point at absolute_time.

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – Absolute position in time at which point shall be found. This is ‘x’ in the function notation ‘f(x)’.

A point is a tuple with (absolute_time, value, curve_shape).

sample_at(absolute_time, append_duration=0)[source]¶

Discretize envelope at given time

Parameters:

absolute_time (core_parameters.abc.Duration.Type) – Position in time where the envelope should define a new event.
append_duration (core_parameters.abc.Duration.Type) – 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:

Envelope

split_at(*absolute_time, ignore_invalid_split_point=False)[source]¶

Split event into n events at absolute_time.

Parameters:

*absolute_time (core_parameters.abc.Duration.Type) –
where event shall be split
ignore_invalid_split_point (bool) – If set to True split_at won’t raise mutwo.core_utilities.SplitError in case a split time isn’t inside the duration range of the event. Otherwise the exception is raised. Default to False.

Raises:

mutwo.core_utilities.NoSplitTimeError if no absolute_time is given. Raises mutwo.core_utilities.InvalidAbsoluteTime if any absolute_time is smaller than 0. Raises mutwo.core_utilities.SplitError if any absolute_time is bigger than the events duration and ignore_invalid_split_point is not set.

Returns:

Tuple of events that result from splitting the present event.

Return type:

tuple[Envelope, …]

Hint:

Calling split_at once with multiple split time arguments is much more efficient than calling split_at multiple times with only one split time for mutwo.core_events.Consecution.

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(3)])
>>> cns.split_at(1)
(Consecution([Chronon(duration=DirectDuration(1.0))]), Consecution([Chronon(duration=DirectDuration(2.0))]))
>>> cns[0].split_at(1)
(Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0)))

time_range_to_point_tuple(time_range)[source]¶

Return all control points in given time range.

Parameters:: time_range (ranges.Range) – Start and end time encapsulated in a ranges.Range object.
Return type:: tuple[CompletePoint, …]

If at start and end time aren’t any control points, the functions creates them ad-hoc via point_at.

value_at(absolute_time)[source]¶

Get value at absolute_time.

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – Absolute position in time at which value shall be found. This is ‘x’ in the function notation ‘f(x)’.
Return type:: Value

This function interpolates between the control points according to their curve_shape property.

Example:

>>> from mutwo import core_events
>>> e = core_events.Envelope([[0, 0], [1, 2]])
>>> e.value_at(0)
0
>>> e.value_at(1)
2
>>> e.value_at(0.5)
1.0

value_to_parameter(value)[source]¶

Convert from ‘value’ to ‘parameter’.

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

CurveShape: TypeAlias = float | fractions.Fraction | int | quicktions.Fraction¶

Parameter: TypeAlias = typing.Any¶

Point: TypeAlias = tuple['core_parameters.abc.Duration', typing.Any, float | fractions.Fraction | int | quicktions.Fraction] | tuple['core_parameters.abc.Duration', typing.Any]¶

Value: TypeAlias = float | fractions.Fraction | int | quicktions.Fraction¶

property curve_shape_tuple: tuple[CurveShape, ...]¶: Get curve_shape for each event inside Envelope.

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

property parameter_tuple: tuple[Any, ...]¶: Get parameter for each event inside Envelope.

property value_tuple: tuple[Value, ...]¶: Get value for each event inside Envelope.

mutwo.core_events.abc ¶

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

class Compound(iterable=[], *, tempo=None, tag=None)[source]¶

Bases: Event, ABC, list[T], Generic[T]

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

Parameters:

iterable (Iterable[T]) –
tempo (Optional[core_parameters.abc.Tempo]) –
tag (Optional[str]) –

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 returns 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
>>> chn0 = core_events.Chronon(2)
>>> chn1 = core_events.Chronon(3)
>>> cns = core_events.Consecution([chn0, chn1, chn0])
>>> cns_copy = copy.deepcopy(cns)
>>> cns_destr_copy = cns.destructive_copy()
>>> cns_copy[0].duration = 10  # setting the duration of the first event
>>> cns_destr_copy[0].duration = 10
>>> # return True because the first and the third objects share the same
>>> # reference (both are the same copy of 'my_chronon_0')
>>> cns_copy[0].duration == cns_copy[2].duration
True
>>> # return False because destructive_copy forgets the shared reference
>>> cns_destr_copy[0].duration == cns_destr_copy[2].duration
False

Return type:: Compound[T]

empty_copy()[source]¶

Make a copy of the Compound without any child events.

This method is useful if one wants to copy an instance of Compound 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.Consecution([core_events.Chronon(2)], tag="piano")
>>> piano_voice_1 = piano_voice_0.empty_copy()
>>> piano_voice_1.tag
'piano'
>>> piano_voice_1
Consecution([])

Return type:: Compound[T]

abstract extend_until(duration, duration_to_white_space=None, prolong_chronon=True)[source]¶

Prolong event until at least duration by appending an empty event.

Parameters:

duration (core_parameters.abc.Duration.Type) – Until which duration the event shall be extended. If event is already longer than or equal to given duration, nothing will be changed. For Concurrence the default value is None which is equal to the duration of the Concurrence.
duration_to_white_space (Optional[Callable[[core_parameters.abc.Duration], Event]]) – A function which creates the ‘rest’ or ‘white space’ event from Duration. If this is None mutwo will fall back to use the default function which is mutwo.core_events.configurations.DEFAULT_DURATION_TO_WHITE_SPACE. Default to None.
prolong_chronon (bool) – If set to True mutwo will prolong a single Chronon inside a Concurrence. If set to False mutwo will raise an ImpossibleToExtendUntilError in case it finds a single Chronon inside a Concurrence. This doesn’t effect Chronon inside a Consecution, here we can simply append a new white space event.

Return type:

Compound

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(1)])
>>> cns.extend_until(10)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(9.0))])

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_consecution = core_events.Consecution(
...     [core_events.Consecution([core_events.Chronon(2)])]
... )
>>> nested_consecution.get_event_from_index_sequence((0, 0))
Chronon(duration=DirectDuration(2.0))
>>> # this is equal to:
>>> nested_consecution[0][0]
Chronon(duration=DirectDuration(2.0))

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 (bool) – 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.Chronon.

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
>>> cns = core_events.Consecution(
...     [core_events.Chronon(2), core_events.Chronon(3)]
... )
>>> cns.get_parameter('duration')
(DirectDuration(2.0), DirectDuration(3.0))
>>> chn = core_events.Chronon(10)
>>> chn.get_parameter('duration')
DirectDuration(10.0)
>>> chn.get_parameter('undefined_parameter')

metrize()[source]¶

Apply tempo of event on itself

Metrize is only syntactic sugar for a call of EventToMetrizedEvent:

>>> from mutwo import core_converters
>>> from mutwo import core_events
>>> chn = core_events.Chronon(1)
>>> chn.tempo = core_parameters.FlexTempo([[0, 100], [1, 40]])
>>> core_converters.EventToMetrizedEvent().convert(chn) == chn.metrize()
True

Return type:: Compound

remove_by(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.
Return type:: Compound[T]

Example:

>>> from mutwo import core_events
>>> concurrence = core_events.Concurrence(
...     [core_events.Chronon(1), core_events.Chronon(3), core_events.Chronon(2)]
... )
>>> concurrence.remove_by(lambda event: event.duration > 2)
Concurrence([Chronon(duration=DirectDuration(3.0))])

abstract slide_in(start, event_to_slide_in)[source]¶

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

Parameters:

start (core_parameters.abc.Duration.Type) – Absolute time where the event shall be inserted.
event_to_slide_in (Event) – the event that shall be slide into the present event.

Return type:

Compound[T]

Unlike Compound.squash_in the events duration will be prolonged by the event which is added. If there is an event at start the event will be split into two parts, but it won’t be shortened or processed in any other way.

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.slide_in(1, core_events.Chronon(1.5))
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(1.5)), Chronon(duration=DirectDuration(2.0))])

abstract split_child_at(absolute_time)[source]¶

Split child event in two events at absolute_time.

Parameters:: absolute_time (core_parameters.abc.Duration.Type) – where child event shall be split
Return type:: Optional[Compound[T]]

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.split_child_at(1)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0))])

abstract squash_in(start, event_to_squash_in)[source]¶

Time-based insert of a new event with overriding given event.

Parameters:

start (core_parameters.abc.Duration.Type) – Absolute time where the event shall be inserted.
event_to_squash_in (Event) – the event that shall be squashed into the present event.

Return type:

Optional[Compound[T]]

Unlike Compound.slide_in the events duration won’t change. If there is already an event at start this event will be shortened or removed.

Example:

>>> from mutwo import core_events
>>> consecution = core_events.Consecution([core_events.Chronon(3)])
>>> consecution.squash_in(1, core_events.Chronon(1.5))
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(1.5)), Chronon(duration=DirectDuration(0.5))])

tie_by(condition, process_surviving_event=<function Compound.<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.Chronon.
event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.

Return type:

Compound[T]

abstract property duration: Duration¶

The duration of an event.

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

class Event(tempo=None, tag=None)[source]¶

Bases: MutwoObject, ABC

Abstract Event-Object

Parameters:

tempo (Optional[core_parameters.abc.Tempo]) – An envelope which describes the dynamic tempo of an event.
tag (Optional[str]) – The name of the event. This can be used to find the event inside a Compound.

abstract cut_off(start, end)[source]¶

Time-based deletion / shortening of the respective event.

Parameters:

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

Return type:

Optional[Event]

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_off(1, 3)
Consecution([Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0))])

abstract cut_out(start, end)[source]¶

Time-based slicing of the respective event.

Parameters:

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

Return type:

Optional[Event]

Example:

>>> from mutwo import core_events
>>> chn0, chn1 = (core_events.Chronon(3), core_events.Chronon(2))
>>> cns = core_events.Consecution([chn0, chn1])
>>> cns.cut_out(1, 4)
Consecution([Chronon(duration=DirectDuration(2.0)), Chronon(duration=DirectDuration(1.0))])

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 returns 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
>>> chn0 = core_events.Chronon(2)
>>> chn1 = core_events.Chronon(3)
>>> cns = core_events.Consecution([chn0, chn1, chn0])
>>> cns_copy = copy.deepcopy(cns)
>>> cns_destr_copy = cns.destructive_copy()
>>> cns_copy[0].duration = 10  # setting the duration of the first event
>>> cns_destr_copy[0].duration = 10
>>> # return True because the first and the third objects share the same
>>> # reference (both are the same copy of 'my_chronon_0')
>>> cns_copy[0].duration == cns_copy[2].duration
True
>>> # return False because destructive_copy forgets the shared reference
>>> cns_destr_copy[0].duration == cns_destr_copy[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 (bool) – 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.Chronon.

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
>>> cns = core_events.Consecution(
...     [core_events.Chronon(2), core_events.Chronon(3)]
... )
>>> cns.get_parameter('duration')
(DirectDuration(2.0), DirectDuration(3.0))
>>> chn = core_events.Chronon(10)
>>> chn.get_parameter('duration')
DirectDuration(10.0)
>>> chn.get_parameter('undefined_parameter')

abstract metrize()[source]¶

Apply tempo of event on itself

Metrize is only syntactic sugar for a call of EventToMetrizedEvent:

>>> from mutwo import core_converters
>>> from mutwo import core_events
>>> chn = core_events.Chronon(1)
>>> chn.tempo = core_parameters.FlexTempo([[0, 100], [1, 40]])
>>> core_converters.EventToMetrizedEvent().convert(chn) == chn.metrize()
True

Return type:: Optional[Event]

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.

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
>>> cons= core_events.Consecution([core_events.Chronon(1)])
>>> cons.mutate_parameter(
...     'duration', lambda duration: duration.add(1)
... )
Consecution([Chronon(duration=DirectDuration(2.0))])
>>> # now duration should be + 1
>>> cons.get_parameter('duration')
(DirectDuration(2.0),)

Warning:

If there are multiple references of the same Event inside a Consecution or a ~mutwo.core_events.Concurrence`, mutate_parameter will only be called once for each Event. So multiple references of the same event will be ignored. This behaviour ensures, that on a big scale level each item inside the mutwo.core_events.abc.Compound is treated equally (so for instance the duration of each item is doubled, and nor for some doubled and for those with references which appear twice quadrupled).

reset_tempo()[source]¶

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

Example:

>>> from mutwo import core_events
>>> chn = core_events.Chronon(duration = 1)
>>> chn.tempo.bpm = 100
>>> print(chn.tempo)
D(100.0)
>>> chn.reset_tempo()
Chronon(duration=DirectDuration(1.0))
>>> print(chn.tempo)
D(60.0)

Return type:: Event

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

Returns:

The event.

Return type:

Event

This function is merely a convenience wrapper for…

event.attribute_name = value

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

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(2)])
>>> cns.set('duration', 10).set('my_new_attribute', 'hello-world!')
Consecution([Chronon(duration=DirectDuration(10.0))])

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.

Returns:

The event.

Return type:

Optional[Event]

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution(
...     [core_events.Chronon(2), core_events.Chronon(3)]
... )
>>> cns.set_parameter('duration', lambda duration: duration * 2)
Consecution([Chronon(duration=DirectDuration(4.0)), Chronon(duration=DirectDuration(6.0))])
>>> cns.get_parameter('duration')
(DirectDuration(4.0), DirectDuration(6.0))

Warning:

If there are multiple references of the same Event inside a Consecution or a Concurrence, set_parameter is only called once for each Event. So multiple references of the same event will be ignored. This behaviour ensures, that on a big scale level each item inside the mutwo.core_events.abc.Compound is treated equally (so for instance the duration of each item is doubled, and nor for some doubled and for those with references which appear twice quadrupled).

split_at(*absolute_time, ignore_invalid_split_point=False)[source]¶

Split event into n events at absolute_time.

Parameters:

*absolute_time (core_parameters.abc.Duration.Type) –
where event shall be split
ignore_invalid_split_point (bool) – If set to True split_at won’t raise mutwo.core_utilities.SplitError in case a split time isn’t inside the duration range of the event. Otherwise the exception is raised. Default to False.

Raises:

mutwo.core_utilities.NoSplitTimeError if no absolute_time is given. Raises mutwo.core_utilities.InvalidAbsoluteTime if any absolute_time is smaller than 0. Raises mutwo.core_utilities.SplitError if any absolute_time is bigger than the events duration and ignore_invalid_split_point is not set.

Returns:

Tuple of events that result from splitting the present event.

Return type:

tuple[Event, …]

Hint:

Calling split_at once with multiple split time arguments is much more efficient than calling split_at multiple times with only one split time for mutwo.core_events.Consecution.

Example:

>>> from mutwo import core_events
>>> cns = core_events.Consecution([core_events.Chronon(3)])
>>> cns.split_at(1)
(Consecution([Chronon(duration=DirectDuration(1.0))]), Consecution([Chronon(duration=DirectDuration(2.0))]))
>>> cns[0].split_at(1)
(Chronon(duration=DirectDuration(1.0)), Chronon(duration=DirectDuration(2.0)))

abstract property duration: Duration¶

The duration of an event.

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

property tempo: Tempo¶: The tempo of an event.

mutwo.core_events.configurations ¶

Configurations which are shared for all event classes in mutwo.core_events.

DEFAULT_DURATION_TO_WHITE_SPACE(duration)¶: Default conversion for parameter duration_to_white_space in mutwo.core_events.abc.Compound.extend_until(). This simply returns a mutwo.core_events.Chronon with the given duration.

mutwo.core_events¶

mutwo.core_events.abc¶

mutwo.core_events.configurations¶

mutwo.core_events ¶

mutwo.core_events.abc ¶

mutwo.core_events.configurations ¶