mutwo.music_parameters <a class="headerlink" href="#mutwo-music-parameters" title="Permalink to this heading">§

Public Methods:

`__init__`(frequency, args, *kwargs)
`__repr__`()	Return repr(self).
`add`(pitch_interval[, mutate])

Inherited from Pitch

`__init__`(frequency, args, *kwargs)
`hertz_to_cents`(frequency0, frequency1)	Calculates the difference in cents between two frequencies.
`ratio_to_cents`(ratio)	Converts a frequency ratio to its respective cent value.
`cents_to_ratio`(cents)	Converts a cent value to its respective frequency ratio.
`hertz_to_midi_pitch_number`(frequency)	Converts a frequency in hertz to its respective midi pitch.
`add`(pitch_interval[, mutate])
`subtract`(pitch_interval)
`__add__`(pitch_interval)
`__sub__`(pitch_interval)
`resolve_envelope`(duration[, ...])
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch

Inherited from SingleNumberParameter

`__float__`()
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Inherited from ParameterWithEnvelope

`__init__`(frequency, args, *kwargs)
`resolve_envelope`(duration[, ...])

Private Data Attributes:

_abc_impl

Inherited from Pitch

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ParameterWithEnvelope

_abc_impl

Inherited from ABC

_abc_impl

class PitchEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=None, apply_parameter_on_event=None, **kwargs)§

Default resolution envelope class for Pitch

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Optional[Callable[[core_constants.ParameterType], core_events.Envelope.Value]]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –

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 frequency_and_envelope_to_pitch(frequency, envelope=None)§

Parameters:

frequency (Union[float, Fraction, int]) –
envelope (Optional[Union[PitchIntervalEnvelope, Sequence]]) –

Return type:

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, ...]§

class PitchIntervalEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=<function Pitch.PitchIntervalEnvelope.<lambda>>, apply_parameter_on_event=None, base_parameter_and_relative_parameter_to_absolute_parameter=None, **kwargs)§

Default envelope class for Pitch

Resolves into Pitch.PitchEnvelope.

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Callable[[core_constants.ParameterType], core_events.Envelope.Value]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –
base_parameter_and_relative_parameter_to_absolute_parameter (Optional[Callable[[core_constants.ParameterType, core_constants.ParameterType], core_constants.ParameterType]]) –

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.

classmethod cents_to_pitch_interval(cents)§

Parameters:: cents (Union[float, Fraction, int]) –
Return type:: PitchInterval

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

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, ...]§

add(pitch_interval, mutate=False)[source]§

Parameters:

pitch_interval (PitchInterval) –
mutate (bool) –

Return type:

DirectPitch

static cents_to_ratio(cents)§

Converts a cent value to its respective frequency ratio.

Parameters:: cents (Union[float, Fraction, int]) – Cents that shall be converted to a frequency ratio.
Return type:: Fraction

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.cents_to_ratio(1200)
Fraction(2, 1)

get_pitch_interval(pitch_to_compare)§

Get PitchInterval between itself and other pitch

Parameters:: pitch_to_compare (Pitch) – The pitch which shall be compared to the active pitch.
Returns:: PitchInterval between
Return type:: PitchInterval

Example:

>>> from mutwo import music_parameters
>>> a4 = music_parameters.DirectPitch(frequency=440)
>>> a5 = music_parameters.DirectPitch(frequency=880)
>>> a4.get_pitch_interval(a5)
DirectPitchInterval(cents = 1200)

static hertz_to_cents(frequency0, frequency1)§

Calculates the difference in cents between two frequencies.

Parameters:

frequency0 (Union[float, Fraction, int]) – The first frequency in Hertz.
frequency1 (Union[float, Fraction, int]) – The second frequency in Hertz.

Returns:

The difference in cents between the first and the second frequency.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_cents(200, 400)
1200.0

static hertz_to_midi_pitch_number(frequency)§

Converts a frequency in hertz to its respective midi pitch.

Parameters:: frequency (Union[float, Fraction, int]) – The frequency that shall be translated to a midi pitch number.
Returns:: The midi pitch number (potentially a floating point number if the entered frequency isn’t on the grid of the equal divided octave tuning with a = 440 Hertz).
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_midi_pitch_number(440)
69.0
>>> abc.Pitch.hertz_to_midi_pitch_number(440 * 3 / 2)
75.98044999134612

static ratio_to_cents(ratio)§

Converts a frequency ratio to its respective cent value.

Parameters:: ratio (Fraction) – The frequency ratio which cent value shall be calculated.
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.ratio_to_cents(fractions.Fraction(3, 2))
701.9550008653874

resolve_envelope(duration, resolve_envelope_class=None)§

Parameters:

duration (Union[float, Fraction, int]) –
resolve_envelope_class (Optional[type[mutwo.core_events.envelopes.Envelope]]) –

Return type:

subtract(pitch_interval)§

Parameters:: pitch_interval (PitchInterval) –
Return type:: Pitch

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property envelope: RelativeEnvelope§

property frequency: float§: The frequency of the pitch.

property midi_pitch_number: float§: The midi pitch number (from 0 to 127) of the pitch.

property value_name§

class JustIntonationPitch(ratio_or_exponent_tuple='1/1', concert_pitch=None, *args, **kwargs)[source]§

Pitch that is defined by a frequency ratio and a reference pitch.

Parameters:

ratio_or_exponent_tuple (Union[str, fractions.Fraction, Iterable[int]]) – The frequency ratio of the JustIntonationPitch. This can either be a string that indicates the frequency ratio (for instance: “1/1”, “3/2”, “9/2”, etc.), or a fractions.Fraction object that indicates the frequency ratio (for instance: fractions.Fraction(3, 2), fractions.Fraction(7, 4)) or an Iterable that is filled with integer that represents the exponent_tuple of the respective prime numbers of the decomposed frequency ratio. The prime numbers are rising and start with 2. Therefore the tuple (2, 0, -1) would return the frequency ratio 4/5 because (2 ** 2) * (3 ** 0) * (5 ** -1) = 4/5.
concert_pitch (ConcertPitch) – The reference pitch of the tuning system (the pitch for a frequency ratio of 1/1). Can either be another Pitch object or any number to indicate a particular frequency in Hertz.

The resulting frequency is calculated by multiplying the frequency ratio with the respective reference pitch.

Example:

>>> from mutwo.music_parameters import pitches
>>> # 3 different variations of initialising the same pitch
>>> pitches.JustIntonationPitch('3/2')
>>> import fractions
>>> pitches.JustIntonationPitch(fractions.Fraction(3, 2))
>>> pitches.JustIntonationPitch((-1, 1))
>>> # using a different concert pitch
>>> pitches.JustIntonationPitch('7/5', concert_pitch=432)

Public Data Attributes:

`exponent_tuple`
`prime_tuple`	Return ascending list of primes, until the highest contained Prime.
`occupied_primes`	Return all occurring prime numbers of a JustIntonationPitch object.
`concert_pitch`
`frequency`
`ratio`	Return the JustIntonationPitch transformed to a Ratio.
`numerator`	Return the numerator of a JustIntonationPitch - object.
`denominator`	Return the denominator of `JustIntonationPitch`.
`interval`
`factorised`	Return factorised / decomposed version of itsef.
`factorised_numerator_and_denominator`
`octave`
`helmholtz_ellis_just_intonation_notation_commas`	Commas of JustIntonationPitch.
`closest_pythagorean_interval`
`cent_deviation_from_closest_western_pitch_class`
`blueprint`
`tonality`	Return the tonality (bool) of a JustIntonationPitch - object.
`harmonic`	Return the nth - harmonic / subharmonic the pitch may represent.
`primes_for_numerator_and_denominator`
`harmonicity_wilson`
`harmonicity_vogel`
`harmonicity_euler`	Return the 'gradus suavitatis' of euler.
`harmonicity_barlow`	Calculate the barlow-harmonicity of an interval.
`harmonicity_simplified_barlow`	Calculate a simplified barlow-harmonicity of an interval.
`harmonicity_tenney`	Calculate Tenneys harmonic distance of an interval

Inherited from Pitch

`midi_pitch_number`	The midi pitch number (from 0 to 127) of the pitch.
`envelope`
`frequency`
`value_name`

Inherited from PitchInterval

`interval`
`value_name`

Inherited from SingleNumberParameter

`direct_comparison_type_tuple`
`digit_to_round_to_count`

Inherited from ParameterWithEnvelope

Public Methods:

`__init__`([ratio_or_exponent_tuple, ...])
`__eq__`(other)	Return self==value.
`__float__`()	Return the float of a JustIntonationPitch - object.
`__repr__`()	Return repr(self).
`__abs__`()
`get_closest_pythagorean_pitch_name`([reference])
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch
`register`(octave)	Move `JustIntonationPitch` to the given octave.
`move_to_closest_register`(reference)
`normalize`([prime])	Normalize `JustIntonationPitch`.
`inverse`([axis])	Inverse current pitch on given axis.
`add`(pitch_interval)	Add `JustIntonationPitch` to current pitch.
`subtract`(pitch_interval)	Subtract `JustIntonationPitch` from current pitch.
`intersection`(other[, strict])	Make intersection with other `JustIntonationPitch`.

Inherited from Pitch

`__init__`([ratio_or_exponent_tuple, ...])
`hertz_to_cents`(frequency0, frequency1)	Calculates the difference in cents between two frequencies.
`ratio_to_cents`(ratio)	Converts a frequency ratio to its respective cent value.
`cents_to_ratio`(cents)	Converts a cent value to its respective frequency ratio.
`hertz_to_midi_pitch_number`(frequency)	Converts a frequency in hertz to its respective midi pitch.
`add`(pitch_interval)	Add `JustIntonationPitch` to current pitch.
`subtract`(pitch_interval)	Subtract `JustIntonationPitch` from current pitch.
`__add__`(pitch_interval)
`__sub__`(pitch_interval)
`resolve_envelope`(duration[, ...])
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch

Inherited from SingleNumberParameter

`__float__`()	Return the float of a JustIntonationPitch - object.
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Inherited from ParameterWithEnvelope

`__init__`([ratio_or_exponent_tuple, ...])
`resolve_envelope`(duration[, ...])

Private Data Attributes:

_abc_impl

Inherited from Pitch

_abc_impl

Inherited from PitchInterval

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ParameterWithEnvelope

_abc_impl

Inherited from ABC

_abc_impl

class PitchEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=None, apply_parameter_on_event=None, **kwargs)§

Default resolution envelope class for Pitch

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Optional[Callable[[core_constants.ParameterType], core_events.Envelope.Value]]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –

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 frequency_and_envelope_to_pitch(frequency, envelope=None)§

Parameters:

frequency (Union[float, Fraction, int]) –
envelope (Optional[Union[PitchIntervalEnvelope, Sequence]]) –

Return type:

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, ...]§

class PitchIntervalEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=<function Pitch.PitchIntervalEnvelope.<lambda>>, apply_parameter_on_event=None, base_parameter_and_relative_parameter_to_absolute_parameter=None, **kwargs)§

Default envelope class for Pitch

Resolves into Pitch.PitchEnvelope.

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Callable[[core_constants.ParameterType], core_events.Envelope.Value]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –
base_parameter_and_relative_parameter_to_absolute_parameter (Optional[Callable[[core_constants.ParameterType, core_constants.ParameterType], core_constants.ParameterType]]) –

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.

classmethod cents_to_pitch_interval(cents)§

Parameters:: cents (Union[float, Fraction, int]) –
Return type:: PitchInterval

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

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, ...]§

add(pitch_interval)[source]§

Add JustIntonationPitch to current pitch.

Parameters:

other – The JustIntonationPitch to add to the current pitch.
pitch_interval (PitchInterval) –

Return type:

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('3/2')
>>> p.add(pitches.JustIntonationPitch('3/2'))
>>> p
JustIntonationPitch(9/4)

static cents_to_ratio(cents)§

Converts a cent value to its respective frequency ratio.

Parameters:: cents (Union[float, Fraction, int]) – Cents that shall be converted to a frequency ratio.
Return type:: Fraction

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.cents_to_ratio(1200)
Fraction(2, 1)

get_closest_pythagorean_pitch_name(reference='a')[source]§

Parameters:: reference (str) –
Return type:: str

get_pitch_interval(pitch_to_compare)[source]§

Get PitchInterval between itself and other pitch

Parameters:: pitch_to_compare (Pitch) – The pitch which shall be compared to the active pitch.
Returns:: PitchInterval between
Return type:: PitchInterval

Example:

>>> from mutwo import music_parameters
>>> a4 = music_parameters.DirectPitch(frequency=440)
>>> a5 = music_parameters.DirectPitch(frequency=880)
>>> a4.get_pitch_interval(a5)
DirectPitchInterval(cents = 1200)

static hertz_to_cents(frequency0, frequency1)§

Calculates the difference in cents between two frequencies.

Parameters:

frequency0 (Union[float, Fraction, int]) – The first frequency in Hertz.
frequency1 (Union[float, Fraction, int]) – The second frequency in Hertz.

Returns:

The difference in cents between the first and the second frequency.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_cents(200, 400)
1200.0

static hertz_to_midi_pitch_number(frequency)§

Converts a frequency in hertz to its respective midi pitch.

Parameters:: frequency (Union[float, Fraction, int]) – The frequency that shall be translated to a midi pitch number.
Returns:: The midi pitch number (potentially a floating point number if the entered frequency isn’t on the grid of the equal divided octave tuning with a = 440 Hertz).
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_midi_pitch_number(440)
69.0
>>> abc.Pitch.hertz_to_midi_pitch_number(440 * 3 / 2)
75.98044999134612

intersection(other, strict=False)[source]§

Make intersection with other JustIntonationPitch.

Parameters:

other (JustIntonationPitch) – The JustIntonationPitch to build the intersection with.
strict (bool) – If set to True only exponent_tuple are included into the intersection if their value is equal. If set to False the method will also include exponent_tuple if both pitches own them on the same axis but with different values (the method will take the smaller exponent).

Return type:

Example:

>>> from mutwo.music_parameters import pitches
>>> p0 = pitches.JustIntonationPitch('5/3')
>>> p0.intersection(pitches.JustIntonationPitch('7/6'))
>>> p0
JustIntonationPitch(1/3)
>>> p1 = pitches.JustIntonationPitch('9/7')
>>> p1.intersection(pitches.JustIntonationPitch('3/2'))
>>> p1
JustIntonationPitch(3/1)
>>> p2 = pitches.JustIntonationPitch('9/7')
>>> p2.intersection(pitches.JustIntonationPitch('3/2'), strict=True)
>>> p2
JustIntonationPitch(1/1)

inverse(axis=None)[source]§

Inverse current pitch on given axis.

Parameters:: axis (JustIntonationPitch, optional) – The JustIntonationPitch from which the pitch shall be inversed.
Return type:: JustIntonationPitch

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('3/2')
>>> p.inverse()
>>> p
JustIntonationPitch(2/3)

move_to_closest_register(reference)[source]§

Parameters:: reference (JustIntonationPitch) –
Return type:: JustIntonationPitch

normalize(prime=2)[source]§

Normalize JustIntonationPitch.

Parameters:: prime (int) – The normalization period (2 for octave, 3 for twelfth, …). Default to 2.
Return type:: JustIntonationPitch

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('12/2')
>>> p.normalize()
>>> p
JustIntonationPitch(3/2)

static ratio_to_cents(ratio)§

Converts a frequency ratio to its respective cent value.

Parameters:: ratio (Fraction) – The frequency ratio which cent value shall be calculated.
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.ratio_to_cents(fractions.Fraction(3, 2))
701.9550008653874

register(octave)[source]§

Move JustIntonationPitch to the given octave.

Parameters:: octave (int) – 0 for the octave from 1/1 to 2/1, negative values for octaves below 1/1 and positive values for octaves above 2/1.
Return type:: JustIntonationPitch

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('3/2')
>>> p.register(1)
>>> p
JustIntonationPitch(6/2)
>>> p.register(-1)
>>> p
JustIntonationPitch(3/4)
>>> p.register(0)
>>> p
JustIntonationPitch(3/2)

resolve_envelope(duration, resolve_envelope_class=None)§

Parameters:

duration (Union[float, Fraction, int]) –
resolve_envelope_class (Optional[type[mutwo.core_events.envelopes.Envelope]]) –

Return type:

subtract(pitch_interval)[source]§

Subtract JustIntonationPitch from current pitch.

Parameters:

other – The JustIntonationPitch to subtract from the current pitch.
pitch_interval (PitchInterval) –

Return type:

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('9/4')
>>> p.subtract(pitches.JustIntonationPitch('3/2'))
>>> p
JustIntonationPitch(3/2)

property blueprint: tuple[tuple[int, ...], ...]§

property cent_deviation_from_closest_western_pitch_class: float§

property closest_pythagorean_interval: JustIntonationPitch§

property concert_pitch: Pitch§

property denominator: int§

Return the denominator of JustIntonationPitch.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch0.denominator
1

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property envelope: RelativeEnvelope§

property exponent_tuple: tuple§

property factorised: tuple§

Return factorised / decomposed version of itsef.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch0.factorised
(2, 2, 5)
>>> just_intonation_pitch1 = JustIntonationPitch("7/6")
>>> just_intonation_pitch1.factorised
(2, 3, 7)

property factorised_numerator_and_denominator: tuple§

property frequency: float§

property harmonic: int§

Return the nth - harmonic / subharmonic the pitch may represent.

Returns:: May be positive for harmonic and negative for subharmonic pitches. If the return - value is 0, the interval may occur neither between the first harmonic and any other pitch of the harmonic scale nor between the first subharmonic in the and any other pitch of the subharmonic scale.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1))
>>> just_intonation_pitch0.ratio
fractions.Fraction(3, 2)
>>> just_intonation_pitch0.harmonic
3
>>> just_intonation_pitch1 = JustIntonationPitch((-1,), 2)
>>> just_intonation_pitch1.harmonic
-3

property harmonicity_barlow: float§

Calculate the barlow-harmonicity of an interval.

This implementation follows Clarence Barlows definition, given in ‘The Ratio Book’ (1992).

A higher number means a more harmonic interval / a less complex harmony.

barlow(1/1) is definied as infinite.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch1 = JustIntonationPitch()
>>> just_intonation_pitch2 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch3 = JustIntonationPitch((0, 0, -1,))
>>> just_intonation_pitch0.harmonicity_barlow
0.27272727272727276
>>> just_intonation_pitch1.harmonicity_barlow # 1/1 is infinite harmonic
inf
>>> just_intonation_pitch2.harmonicity_barlow
0.11904761904761904
>>> just_intonation_pitch3.harmonicity_barlow
-0.10638297872340426

property harmonicity_euler: int§

Return the ‘gradus suavitatis’ of euler.

A higher number means a less consonant interval / a more complicated harmony. euler(1/1) is definied as 1.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch1 = JustIntonationPitch()
>>> just_intonation_pitch2 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch3 = JustIntonationPitch((0, 0, -1,))
>>> just_intonation_pitch0.harmonicity_euler
4
>>> just_intonation_pitch1.harmonicity_euler
1
>>> just_intonation_pitch2.harmonicity_euler
7
>>> just_intonation_pitch3.harmonicity_euler
8

property harmonicity_simplified_barlow: float§

Calculate a simplified barlow-harmonicity of an interval.

This implementation follows Clarence Barlows definition, given in ‘The Ratio Book’ (1992), with the difference that only positive numbers are returned and that (1/1) is defined as 1 instead of infinite.

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch1 = JustIntonationPitch()
>>> just_intonation_pitch2 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch3 = JustIntonationPitch((0, 0, -1,))
>>> just_intonation_pitch0.harmonicity_simplified_barlow
0.27272727272727276
>>> just_intonation_pitch1.harmonicity_simplified_barlow # 1/1 is not infinite but 1
1
>>> just_intonation_pitch2.harmonicity_simplified_barlow
0.11904761904761904
>>> just_intonation_pitch3.harmonicity_simplified_barlow # positive return value
0.10638297872340426

property harmonicity_tenney: float§

Calculate Tenneys harmonic distance of an interval

A higher number means a more consonant interval / a less complicated harmony.

tenney(1/1) is definied as 0.

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch1 = JustIntonationPitch()
>>> just_intonation_pitch2 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch3 = JustIntonationPitch((0, 0, -1,))
>>> just_intonation_pitch0.harmonicity_tenney
2.584962500721156
>>> just_intonation_pitch1.harmonicity_tenney
0.0
>>> just_intonation_pitch2.harmonicity_tenney
4.321928094887363
>>> just_intonation_pitch3.harmonicity_tenney
-0.10638297872340426

property harmonicity_vogel: int§

property harmonicity_wilson: int§

property helmholtz_ellis_just_intonation_notation_commas: CommaCompound§: Commas of JustIntonationPitch.

property interval: float§

property midi_pitch_number: float§: The midi pitch number (from 0 to 127) of the pitch.

property numerator: int§

Return the numerator of a JustIntonationPitch - object.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, -1,))
>>> just_intonation_pitch0.numerator
1

property occupied_primes: tuple§: Return all occurring prime numbers of a JustIntonationPitch object.

property octave: int§

property prime_tuple: tuple§

Return ascending list of primes, until the highest contained Prime.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1, 2))
>>> just_intonation_pitch0.exponent_tuple
(2, 3, 5)
>>> just_intonation_pitch1 = JustIntonationPitch((0, -1, 0, 0, 1), 1)
>>> just_intonation_pitch1.exponent_tuple
(2, 3, 5, 7, 11)

property primes_for_numerator_and_denominator: tuple§

property ratio: Fraction§

Return the JustIntonationPitch transformed to a Ratio.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch0.ratio
fractions.Fraction(5, 4)
>>> just_intonation_pitch0 = JustIntonationPitch("3/2")
>>> just_intonation_pitch0.ratio
fractions.Fraction(3, 2)

property tonality: bool§

Return the tonality (bool) of a JustIntonationPitch - object.

The tonality of a JustIntonationPitch - may be True (otonality) if the exponent of the highest occurring prime number is a positive number and False if the exponent is a negative number (utonality).

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((-2. 1))
>>> just_intonation_pitch0.tonality
True
>>> just_intonation_pitch1 = JustIntonationPitch((-2, -1))
>>> just_intonation_pitch1.tonality
False
>>> just_intonation_pitch2 = JustIntonationPitch([])
>>> just_intonation_pitch2.tonality
True

property value_name§

class Partial(nth_partial, tonality)[source]§

Abstract representation of a harmonic spectrum partial.

Parameters:

nth_partial (int) – The number of the partial (starting with 1 for the root note).
tonality (bool) – True for overtone and False for a (theoretical) undertone. Default to True.

Example:

>>> from mutwo.music_parameters import pitches
>>> strong_clarinet_partials = (
    pitches.Partial(1),
    pitches.Partial(3),
    pitches.Partial(5),
    pitches.Partial(7),
)

Public Methods:

`__init__`(nth_partial, tonality)
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.
`__setattr__`(name, value)	Implement setattr(self, name, value).
`__delattr__`(name)	Implement delattr(self, name).
`__hash__`()	Return hash(self).

nth_partial: int§

tonality: bool§

class EqualDividedOctavePitch(n_pitch_classes_per_octave, pitch_class, octave, concert_pitch_pitch_class, concert_pitch_octave, concert_pitch=None, *args, **kwargs)[source]§

Pitch that is tuned to an Equal divided octave tuning system.

Parameters:

n_pitch_classes_per_octave (int) – how many pitch classes in each octave occur (for instance 12 for a chromatic system, 24 for quartertones, etc.)
pitch_class (core_constants.Real) – The pitch class of the new EqualDividedOctavePitch object.
octave (int) – The octave of the new EqualDividedOctavePitch object (where 0 is the middle octave, 1 is one octave higher and -1 is one octave lower).
concert_pitch_pitch_class (core_constants.Real) – The pitch class of the reference pitch (for instance 9 in a chromatic 12 tone system where a should be the reference pitch).
concert_pitch_octave (int) – The octave of the reference pitch.
concert_pitch (ConcertPitch) – The frequency of the reference pitch (for instance 440 for a).

>>> from mutwo.music_parameters import pitches
>>> # making a middle `a`
>>> pitches.EqualDividedOctavePitch(12, 9, 4, 9, 4, 440)

Public Data Attributes:

`n_pitch_classes_per_octave`	Defines in how many different pitch classes one octave get divided.
`concert_pitch`	The referential concert pitch for the respective pitch object.
`concert_pitch_pitch_class`	The pitch class of the referential concert pitch.
`pitch_class`	The pitch class of the pitch.
`step_factor`	The factor with which to multiply a frequency to reach the next pitch.
`n_cents_per_step`	This property describes how many cents are between two adjacent pitches.
`frequency`

Inherited from Pitch

`midi_pitch_number`	The midi pitch number (from 0 to 127) of the pitch.
`envelope`
`frequency`
`value_name`

Inherited from SingleNumberParameter

`direct_comparison_type_tuple`
`digit_to_round_to_count`

Inherited from ParameterWithEnvelope

Public Methods:

`__init__`(n_pitch_classes_per_octave, ...[, ...])
`__sub__`(other)	Calculates the interval between two `EqualDividedOctave` pitches.
`add`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.
`subtract`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.

Inherited from Pitch

`__init__`(n_pitch_classes_per_octave, ...[, ...])
`hertz_to_cents`(frequency0, frequency1)	Calculates the difference in cents between two frequencies.
`ratio_to_cents`(ratio)	Converts a frequency ratio to its respective cent value.
`cents_to_ratio`(cents)	Converts a cent value to its respective frequency ratio.
`hertz_to_midi_pitch_number`(frequency)	Converts a frequency in hertz to its respective midi pitch.
`add`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.
`subtract`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.
`__add__`(pitch_interval)
`__sub__`(other)	Calculates the interval between two `EqualDividedOctave` pitches.
`resolve_envelope`(duration[, ...])
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch

Inherited from SingleNumberParameter

`__float__`()
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Inherited from ParameterWithEnvelope

`__init__`(n_pitch_classes_per_octave, ...[, ...])
`resolve_envelope`(duration[, ...])

Private Data Attributes:

_abc_impl

Inherited from Pitch

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ParameterWithEnvelope

_abc_impl

Inherited from ABC

_abc_impl

class PitchEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=None, apply_parameter_on_event=None, **kwargs)§

Default resolution envelope class for Pitch

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Optional[Callable[[core_constants.ParameterType], core_events.Envelope.Value]]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –

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 frequency_and_envelope_to_pitch(frequency, envelope=None)§

Parameters:

frequency (Union[float, Fraction, int]) –
envelope (Optional[Union[PitchIntervalEnvelope, Sequence]]) –

Return type:

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, ...]§

class PitchIntervalEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=<function Pitch.PitchIntervalEnvelope.<lambda>>, apply_parameter_on_event=None, base_parameter_and_relative_parameter_to_absolute_parameter=None, **kwargs)§

Default envelope class for Pitch

Resolves into Pitch.PitchEnvelope.

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Callable[[core_constants.ParameterType], core_events.Envelope.Value]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –
base_parameter_and_relative_parameter_to_absolute_parameter (Optional[Callable[[core_constants.ParameterType, core_constants.ParameterType], core_constants.ParameterType]]) –

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.

classmethod cents_to_pitch_interval(cents)§

Parameters:: cents (Union[float, Fraction, int]) –
Return type:: PitchInterval

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

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, ...]§

add(pitch_interval)[source]§

Transposes the EqualDividedOctavePitch by n_pitch_classes_difference.

Parameters:: pitch_interval (Union[PitchInterval, float, Fraction, int]) –
Return type:: EqualDividedOctavePitch

static cents_to_ratio(cents)§

Converts a cent value to its respective frequency ratio.

Parameters:: cents (Union[float, Fraction, int]) – Cents that shall be converted to a frequency ratio.
Return type:: Fraction

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.cents_to_ratio(1200)
Fraction(2, 1)

get_pitch_interval(pitch_to_compare)§

Get PitchInterval between itself and other pitch

Parameters:: pitch_to_compare (Pitch) – The pitch which shall be compared to the active pitch.
Returns:: PitchInterval between
Return type:: PitchInterval

Example:

>>> from mutwo import music_parameters
>>> a4 = music_parameters.DirectPitch(frequency=440)
>>> a5 = music_parameters.DirectPitch(frequency=880)
>>> a4.get_pitch_interval(a5)
DirectPitchInterval(cents = 1200)

static hertz_to_cents(frequency0, frequency1)§

Calculates the difference in cents between two frequencies.

Parameters:

frequency0 (Union[float, Fraction, int]) – The first frequency in Hertz.
frequency1 (Union[float, Fraction, int]) – The second frequency in Hertz.

Returns:

The difference in cents between the first and the second frequency.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_cents(200, 400)
1200.0

static hertz_to_midi_pitch_number(frequency)§

Converts a frequency in hertz to its respective midi pitch.

Parameters:: frequency (Union[float, Fraction, int]) – The frequency that shall be translated to a midi pitch number.
Returns:: The midi pitch number (potentially a floating point number if the entered frequency isn’t on the grid of the equal divided octave tuning with a = 440 Hertz).
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_midi_pitch_number(440)
69.0
>>> abc.Pitch.hertz_to_midi_pitch_number(440 * 3 / 2)
75.98044999134612

static ratio_to_cents(ratio)§

Converts a frequency ratio to its respective cent value.

Parameters:: ratio (Fraction) – The frequency ratio which cent value shall be calculated.
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.ratio_to_cents(fractions.Fraction(3, 2))
701.9550008653874

resolve_envelope(duration, resolve_envelope_class=None)§

Parameters:

duration (Union[float, Fraction, int]) –
resolve_envelope_class (Optional[type[mutwo.core_events.envelopes.Envelope]]) –

Return type:

subtract(pitch_interval)[source]§

Transposes the EqualDividedOctavePitch by n_pitch_classes_difference.

Parameters:: pitch_interval (Union[PitchInterval, float, Fraction, int]) –
Return type:: EqualDividedOctavePitch

property concert_pitch: Pitch§: The referential concert pitch for the respective pitch object.

property concert_pitch_pitch_class: Union[float, Fraction, int]§: The pitch class of the referential concert pitch.

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property envelope: RelativeEnvelope§

property frequency: float§

property midi_pitch_number: float§: The midi pitch number (from 0 to 127) of the pitch.

property n_cents_per_step: float§: This property describes how many cents are between two adjacent pitches.

property n_pitch_classes_per_octave: int§: Defines in how many different pitch classes one octave get divided.

property pitch_class: Union[float, Fraction, int]§: The pitch class of the pitch.

property step_factor§: The factor with which to multiply a frequency to reach the next pitch.

property value_name§

class WesternPitch(pitch_class_or_pitch_class_name=0, octave=4, concert_pitch_pitch_class=None, concert_pitch_octave=None, concert_pitch=None, *args, **kwargs)[source]§

Pitch with a traditional Western nomenclature.

Parameters:

pitch_class_or_pitch_class_name (PitchClassOrPitchClassName) – Name or number of the pitch class of the new WesternPitch object. The nomenclature is English (c, d, e, f, g, a, b). It uses an equal divided octave system in 12 chromatic steps. Accidentals are indicated by (s = sharp) and (f = flat). Further microtonal accidentals are supported (see mutwo.music_parameters.constants.ACCIDENTAL_NAME_TO_PITCH_CLASS_MODIFICATION_DICT for all supported accidentals).
octave (int) – The octave of the new WesternPitch object. Indications for the specific octave follow the MIDI Standard where 4 is defined as one line.
concert_pitch_pitch_class (core_constants.Real) –
concert_pitch_octave (int) –
concert_pitch (ConcertPitch) –

Example:

>>> from mutwo.music_parameters import pitches
>>> pitches.WesternPitch('cs', 4)  # c-sharp 4
>>> pitches.WesternPitch('aqs', 2)  # a-quarter-sharp 2

Public Data Attributes:

`name`	The name of the pitch in Western nomenclature.
`pitch_class_name`	The name of the pitch class in Western nomenclature.
`pitch_class`	The pitch class of the pitch.
`diatonic_pitch_class_name`	Only get the diatonic part of the pitch name
`accidental_name`	Only get accidental part of pitch name
`is_microtonal`	Return True if accidental isn't on chromatic grid.
`enharmonic_pitch_tuple`	Return pitches with equal frequency but different name.

Inherited from EqualDividedOctavePitch

`n_pitch_classes_per_octave`	Defines in how many different pitch classes one octave get divided.
`concert_pitch`	The referential concert pitch for the respective pitch object.
`concert_pitch_pitch_class`	The pitch class of the referential concert pitch.
`pitch_class`	The pitch class of the pitch.
`step_factor`	The factor with which to multiply a frequency to reach the next pitch.
`n_cents_per_step`	This property describes how many cents are between two adjacent pitches.
`frequency`

Inherited from Pitch

`midi_pitch_number`	The midi pitch number (from 0 to 127) of the pitch.
`envelope`
`frequency`
`value_name`

Inherited from SingleNumberParameter

`direct_comparison_type_tuple`
`digit_to_round_to_count`

Inherited from ParameterWithEnvelope

Public Methods:

`__init__`([pitch_class_or_pitch_class_name, ...])
`from_midi_pitch_number`(midi_pitch_number)
`__repr__`()	Return repr(self).
`__str__`()	Return str(self).
`add`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.
`subtract`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch

Inherited from EqualDividedOctavePitch

`__init__`([pitch_class_or_pitch_class_name, ...])
`__sub__`(other)	Calculates the interval between two `EqualDividedOctave` pitches.
`add`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.
`subtract`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.

Inherited from Pitch

`__init__`([pitch_class_or_pitch_class_name, ...])
`hertz_to_cents`(frequency0, frequency1)	Calculates the difference in cents between two frequencies.
`ratio_to_cents`(ratio)	Converts a frequency ratio to its respective cent value.
`cents_to_ratio`(cents)	Converts a cent value to its respective frequency ratio.
`hertz_to_midi_pitch_number`(frequency)	Converts a frequency in hertz to its respective midi pitch.
`add`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.
`subtract`(pitch_interval)	Transposes the `EqualDividedOctavePitch` by n_pitch_classes_difference.
`__add__`(pitch_interval)
`__sub__`(other)	Calculates the interval between two `EqualDividedOctave` pitches.
`resolve_envelope`(duration[, ...])
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch

Inherited from SingleNumberParameter

`__float__`()
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Inherited from ParameterWithEnvelope

`__init__`([pitch_class_or_pitch_class_name, ...])
`resolve_envelope`(duration[, ...])

Private Data Attributes:

_abc_impl

Inherited from EqualDividedOctavePitch

_abc_impl

Inherited from Pitch

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ParameterWithEnvelope

_abc_impl

Inherited from ABC

_abc_impl

class PitchEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=None, apply_parameter_on_event=None, **kwargs)§

Default resolution envelope class for Pitch

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Optional[Callable[[core_constants.ParameterType], core_events.Envelope.Value]]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –

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 frequency_and_envelope_to_pitch(frequency, envelope=None)§

Parameters:

frequency (Union[float, Fraction, int]) –
envelope (Optional[Union[PitchIntervalEnvelope, Sequence]]) –

Return type:

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, ...]§

class PitchIntervalEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=<function Pitch.PitchIntervalEnvelope.<lambda>>, apply_parameter_on_event=None, base_parameter_and_relative_parameter_to_absolute_parameter=None, **kwargs)§

Default envelope class for Pitch

Resolves into Pitch.PitchEnvelope.

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Callable[[core_constants.ParameterType], core_events.Envelope.Value]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –
base_parameter_and_relative_parameter_to_absolute_parameter (Optional[Callable[[core_constants.ParameterType, core_constants.ParameterType], core_constants.ParameterType]]) –

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.

classmethod cents_to_pitch_interval(cents)§

Parameters:: cents (Union[float, Fraction, int]) –
Return type:: PitchInterval

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

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, ...]§

add(pitch_interval)[source]§

Transposes the EqualDividedOctavePitch by n_pitch_classes_difference.

Parameters:: pitch_interval (Union[str, PitchInterval, float, Fraction, int]) –
Return type:: WesternPitch

static cents_to_ratio(cents)§

Converts a cent value to its respective frequency ratio.

Parameters:: cents (Union[float, Fraction, int]) – Cents that shall be converted to a frequency ratio.
Return type:: Fraction

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.cents_to_ratio(1200)
Fraction(2, 1)

classmethod from_midi_pitch_number(midi_pitch_number)[source]§

Parameters:: midi_pitch_number (float) –
Return type:: WesternPitch

get_pitch_interval(pitch_to_compare)[source]§

Get PitchInterval between itself and other pitch

Parameters:: pitch_to_compare (Pitch) – The pitch which shall be compared to the active pitch.
Returns:: PitchInterval between
Return type:: PitchInterval

Example:

>>> from mutwo import music_parameters
>>> a4 = music_parameters.DirectPitch(frequency=440)
>>> a5 = music_parameters.DirectPitch(frequency=880)
>>> a4.get_pitch_interval(a5)
DirectPitchInterval(cents = 1200)

static hertz_to_cents(frequency0, frequency1)§

Calculates the difference in cents between two frequencies.

Parameters:

frequency0 (Union[float, Fraction, int]) – The first frequency in Hertz.
frequency1 (Union[float, Fraction, int]) – The second frequency in Hertz.

Returns:

The difference in cents between the first and the second frequency.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_cents(200, 400)
1200.0

static hertz_to_midi_pitch_number(frequency)§

Converts a frequency in hertz to its respective midi pitch.

Parameters:: frequency (Union[float, Fraction, int]) – The frequency that shall be translated to a midi pitch number.
Returns:: The midi pitch number (potentially a floating point number if the entered frequency isn’t on the grid of the equal divided octave tuning with a = 440 Hertz).
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_midi_pitch_number(440)
69.0
>>> abc.Pitch.hertz_to_midi_pitch_number(440 * 3 / 2)
75.98044999134612

static ratio_to_cents(ratio)§

Converts a frequency ratio to its respective cent value.

Parameters:: ratio (Fraction) – The frequency ratio which cent value shall be calculated.
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.ratio_to_cents(fractions.Fraction(3, 2))
701.9550008653874

resolve_envelope(duration, resolve_envelope_class=None)§

Parameters:

duration (Union[float, Fraction, int]) –
resolve_envelope_class (Optional[type[mutwo.core_events.envelopes.Envelope]]) –

Return type:

subtract(pitch_interval)[source]§

Transposes the EqualDividedOctavePitch by n_pitch_classes_difference.

Parameters:: pitch_interval (Union[str, PitchInterval, float, Fraction, int]) –
Return type:: WesternPitch

property accidental_name: str§: Only get accidental part of pitch name

property concert_pitch: Pitch§: The referential concert pitch for the respective pitch object.

property concert_pitch_pitch_class: Union[float, Fraction, int]§: The pitch class of the referential concert pitch.

property diatonic_pitch_class_name: str§: Only get the diatonic part of the pitch name

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property enharmonic_pitch_tuple: tuple[mutwo.music_parameters.pitches.WesternPitch.WesternPitch, ...]§

Return pitches with equal frequency but different name.

Disclaimer:

This doesn’t work in some corner cases yet (e.g. it won’t find “css” for “eff”)

property envelope: RelativeEnvelope§

property frequency: float§

property is_microtonal: bool§: Return True if accidental isn’t on chromatic grid.

property midi_pitch_number: float§: The midi pitch number (from 0 to 127) of the pitch.

property n_cents_per_step: float§: This property describes how many cents are between two adjacent pitches.

property n_pitch_classes_per_octave: int§: Defines in how many different pitch classes one octave get divided.

property name: str§: The name of the pitch in Western nomenclature.

property pitch_class: Union[float, Fraction, int]§: The pitch class of the pitch.

property pitch_class_name: str§

The name of the pitch class in Western nomenclature.

Mutwo uses the English nomenclature for pitch class names:: (c, d, e, f, g, a, b)

property step_factor§: The factor with which to multiply a frequency to reach the next pitch.

property value_name§

class MidiPitch(midi_pitch_number, *args, **kwargs)[source]§

Pitch that is defined by its midi pitch number.

Parameters:: midi_pitch_number (float) – The midi pitch number of the pitch. Floating point numbers are possible for microtonal deviations from the chromatic scale.

Example:

>>> from mutwo.music_parameters import pitches
>>> middle_c = pitches.MidiPitch(60)
>>> middle_c_quarter_tone_high = pitches.MidiPitch(60.5)

Public Data Attributes:

`frequency`
`midi_pitch_number`	The midi pitch number (from 0 to 127) of the pitch.

Inherited from Pitch

`midi_pitch_number`	The midi pitch number (from 0 to 127) of the pitch.
`envelope`
`frequency`
`value_name`

Inherited from SingleNumberParameter

`direct_comparison_type_tuple`
`digit_to_round_to_count`

Inherited from ParameterWithEnvelope

Public Methods:

`__init__`(midi_pitch_number, args, *kwargs)
`__repr__`()	Return repr(self).
`add`(pitch_interval[, mutate])

Inherited from Pitch

`__init__`(midi_pitch_number, args, *kwargs)
`hertz_to_cents`(frequency0, frequency1)	Calculates the difference in cents between two frequencies.
`ratio_to_cents`(ratio)	Converts a frequency ratio to its respective cent value.
`cents_to_ratio`(cents)	Converts a cent value to its respective frequency ratio.
`hertz_to_midi_pitch_number`(frequency)	Converts a frequency in hertz to its respective midi pitch.
`add`(pitch_interval[, mutate])
`subtract`(pitch_interval)
`__add__`(pitch_interval)
`__sub__`(pitch_interval)
`resolve_envelope`(duration[, ...])
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch

Inherited from SingleNumberParameter

`__float__`()
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Inherited from ParameterWithEnvelope

`__init__`(midi_pitch_number, args, *kwargs)
`resolve_envelope`(duration[, ...])

Private Data Attributes:

_abc_impl

Inherited from Pitch

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ParameterWithEnvelope

_abc_impl

Inherited from ABC

_abc_impl

class PitchEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=None, apply_parameter_on_event=None, **kwargs)§

Default resolution envelope class for Pitch

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Optional[Callable[[core_constants.ParameterType], core_events.Envelope.Value]]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –

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 frequency_and_envelope_to_pitch(frequency, envelope=None)§

Parameters:

frequency (Union[float, Fraction, int]) –
envelope (Optional[Union[PitchIntervalEnvelope, Sequence]]) –

Return type:

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, ...]§

class PitchIntervalEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=<function Pitch.PitchIntervalEnvelope.<lambda>>, apply_parameter_on_event=None, base_parameter_and_relative_parameter_to_absolute_parameter=None, **kwargs)§

Default envelope class for Pitch

Resolves into Pitch.PitchEnvelope.

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Callable[[core_constants.ParameterType], core_events.Envelope.Value]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –
base_parameter_and_relative_parameter_to_absolute_parameter (Optional[Callable[[core_constants.ParameterType, core_constants.ParameterType], core_constants.ParameterType]]) –

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.

classmethod cents_to_pitch_interval(cents)§

Parameters:: cents (Union[float, Fraction, int]) –
Return type:: PitchInterval

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

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, ...]§

add(pitch_interval, mutate=False)[source]§

Parameters:

pitch_interval (PitchInterval) –
mutate (bool) –

Return type:

MidiPitch

static cents_to_ratio(cents)§

Converts a cent value to its respective frequency ratio.

Parameters:: cents (Union[float, Fraction, int]) – Cents that shall be converted to a frequency ratio.
Return type:: Fraction

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.cents_to_ratio(1200)
Fraction(2, 1)

get_pitch_interval(pitch_to_compare)§

Get PitchInterval between itself and other pitch

Parameters:: pitch_to_compare (Pitch) – The pitch which shall be compared to the active pitch.
Returns:: PitchInterval between
Return type:: PitchInterval

Example:

>>> from mutwo import music_parameters
>>> a4 = music_parameters.DirectPitch(frequency=440)
>>> a5 = music_parameters.DirectPitch(frequency=880)
>>> a4.get_pitch_interval(a5)
DirectPitchInterval(cents = 1200)

static hertz_to_cents(frequency0, frequency1)§

Calculates the difference in cents between two frequencies.

Parameters:

frequency0 (Union[float, Fraction, int]) – The first frequency in Hertz.
frequency1 (Union[float, Fraction, int]) – The second frequency in Hertz.

Returns:

The difference in cents between the first and the second frequency.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_cents(200, 400)
1200.0

static hertz_to_midi_pitch_number(frequency)§

Converts a frequency in hertz to its respective midi pitch.

Parameters:: frequency (Union[float, Fraction, int]) – The frequency that shall be translated to a midi pitch number.
Returns:: The midi pitch number (potentially a floating point number if the entered frequency isn’t on the grid of the equal divided octave tuning with a = 440 Hertz).
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_midi_pitch_number(440)
69.0
>>> abc.Pitch.hertz_to_midi_pitch_number(440 * 3 / 2)
75.98044999134612

static ratio_to_cents(ratio)§

Converts a frequency ratio to its respective cent value.

Parameters:: ratio (Fraction) – The frequency ratio which cent value shall be calculated.
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.ratio_to_cents(fractions.Fraction(3, 2))
701.9550008653874

resolve_envelope(duration, resolve_envelope_class=None)§

Parameters:

duration (Union[float, Fraction, int]) –
resolve_envelope_class (Optional[type[mutwo.core_events.envelopes.Envelope]]) –

Return type:

subtract(pitch_interval)§

Parameters:: pitch_interval (PitchInterval) –
Return type:: Pitch

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property envelope: RelativeEnvelope§

property frequency: float§

property midi_pitch_number: float§: The midi pitch number (from 0 to 127) of the pitch.

property value_name§

class CommonHarmonic(partial_tuple, ratio_or_exponent_tuple='1/1', concert_pitch=None, *args, **kwargs)[source]§

JustIntonationPitch which is the common harmonic between two or more other pitches.

Parameters:

partials (tuple[Partial, ...]) – Tuple which contains partial numbers.
ratio_or_exponent_tuple (Union[str, fractions.Fraction, Iterable[int]]) – see the documentation of JustIntonationPitch
concert_pitch (Union[core_constants.Real, music_parameters.abc.Pitch]) – see the documentation of JustIntonationPitch
partial_tuple (tuple[Partial, ...]) –

Public Data Attributes:

Inherited from JustIntonationPitch

`exponent_tuple`
`prime_tuple`	Return ascending list of primes, until the highest contained Prime.
`occupied_primes`	Return all occurring prime numbers of a JustIntonationPitch object.
`concert_pitch`
`frequency`
`ratio`	Return the JustIntonationPitch transformed to a Ratio.
`numerator`	Return the numerator of a JustIntonationPitch - object.
`denominator`	Return the denominator of `JustIntonationPitch`.
`interval`
`factorised`	Return factorised / decomposed version of itsef.
`factorised_numerator_and_denominator`
`octave`
`helmholtz_ellis_just_intonation_notation_commas`	Commas of JustIntonationPitch.
`closest_pythagorean_interval`
`cent_deviation_from_closest_western_pitch_class`
`blueprint`
`tonality`	Return the tonality (bool) of a JustIntonationPitch - object.
`harmonic`	Return the nth - harmonic / subharmonic the pitch may represent.
`primes_for_numerator_and_denominator`
`harmonicity_wilson`
`harmonicity_vogel`
`harmonicity_euler`	Return the 'gradus suavitatis' of euler.
`harmonicity_barlow`	Calculate the barlow-harmonicity of an interval.
`harmonicity_simplified_barlow`	Calculate a simplified barlow-harmonicity of an interval.
`harmonicity_tenney`	Calculate Tenneys harmonic distance of an interval

Inherited from Pitch

`midi_pitch_number`	The midi pitch number (from 0 to 127) of the pitch.
`envelope`
`frequency`
`value_name`

Inherited from PitchInterval

`interval`
`value_name`

Inherited from SingleNumberParameter

`direct_comparison_type_tuple`
`digit_to_round_to_count`

Inherited from ParameterWithEnvelope

Public Methods:

`__init__`(partial_tuple[, ...])
`__repr__`()	Return repr(self).

Inherited from JustIntonationPitch

`__init__`(partial_tuple[, ...])
`__eq__`(other)	Return self==value.
`__float__`()	Return the float of a JustIntonationPitch - object.
`__repr__`()	Return repr(self).
`__abs__`()
`get_closest_pythagorean_pitch_name`([reference])
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch
`register`(octave)	Move `JustIntonationPitch` to the given octave.
`move_to_closest_register`(reference)
`normalize`([prime])	Normalize `JustIntonationPitch`.
`inverse`([axis])	Inverse current pitch on given axis.
`add`(pitch_interval)	Add `JustIntonationPitch` to current pitch.
`subtract`(pitch_interval)	Subtract `JustIntonationPitch` from current pitch.
`intersection`(other[, strict])	Make intersection with other `JustIntonationPitch`.

Inherited from Pitch

`__init__`(partial_tuple[, ...])
`hertz_to_cents`(frequency0, frequency1)	Calculates the difference in cents between two frequencies.
`ratio_to_cents`(ratio)	Converts a frequency ratio to its respective cent value.
`cents_to_ratio`(cents)	Converts a cent value to its respective frequency ratio.
`hertz_to_midi_pitch_number`(frequency)	Converts a frequency in hertz to its respective midi pitch.
`add`(pitch_interval)	Add `JustIntonationPitch` to current pitch.
`subtract`(pitch_interval)	Subtract `JustIntonationPitch` from current pitch.
`__add__`(pitch_interval)
`__sub__`(pitch_interval)
`resolve_envelope`(duration[, ...])
`get_pitch_interval`(pitch_to_compare)	Get `PitchInterval` between itself and other pitch

Inherited from SingleNumberParameter

`__float__`()	Return the float of a JustIntonationPitch - object.
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Inherited from ParameterWithEnvelope

`__init__`(partial_tuple[, ...])
`resolve_envelope`(duration[, ...])

Private Data Attributes:

_abc_impl

Inherited from JustIntonationPitch

_abc_impl

Inherited from Pitch

_abc_impl

Inherited from PitchInterval

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ParameterWithEnvelope

_abc_impl

Inherited from ABC

_abc_impl

class PitchEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=None, apply_parameter_on_event=None, **kwargs)§

Default resolution envelope class for Pitch

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Optional[Callable[[core_constants.ParameterType], core_events.Envelope.Value]]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –

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 frequency_and_envelope_to_pitch(frequency, envelope=None)§

Parameters:

frequency (Union[float, Fraction, int]) –
envelope (Optional[Union[PitchIntervalEnvelope, Sequence]]) –

Return type:

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, ...]§

class PitchIntervalEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=<function Pitch.PitchIntervalEnvelope.<lambda>>, apply_parameter_on_event=None, base_parameter_and_relative_parameter_to_absolute_parameter=None, **kwargs)§

Default envelope class for Pitch

Resolves into Pitch.PitchEnvelope.

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Callable[[core_constants.ParameterType], core_events.Envelope.Value]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –
base_parameter_and_relative_parameter_to_absolute_parameter (Optional[Callable[[core_constants.ParameterType, core_constants.ParameterType], core_constants.ParameterType]]) –

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.

classmethod cents_to_pitch_interval(cents)§

Parameters:: cents (Union[float, Fraction, int]) –
Return type:: PitchInterval

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

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, ...]§

add(pitch_interval)§

Add JustIntonationPitch to current pitch.

Parameters:

other – The JustIntonationPitch to add to the current pitch.
pitch_interval (PitchInterval) –

Return type:

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('3/2')
>>> p.add(pitches.JustIntonationPitch('3/2'))
>>> p
JustIntonationPitch(9/4)

static cents_to_ratio(cents)§

Converts a cent value to its respective frequency ratio.

Parameters:: cents (Union[float, Fraction, int]) – Cents that shall be converted to a frequency ratio.
Return type:: Fraction

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.cents_to_ratio(1200)
Fraction(2, 1)

get_closest_pythagorean_pitch_name(reference='a')§

Parameters:: reference (str) –
Return type:: str

get_pitch_interval(pitch_to_compare)§

Get PitchInterval between itself and other pitch

Parameters:: pitch_to_compare (Pitch) – The pitch which shall be compared to the active pitch.
Returns:: PitchInterval between
Return type:: PitchInterval

Example:

>>> from mutwo import music_parameters
>>> a4 = music_parameters.DirectPitch(frequency=440)
>>> a5 = music_parameters.DirectPitch(frequency=880)
>>> a4.get_pitch_interval(a5)
DirectPitchInterval(cents = 1200)

static hertz_to_cents(frequency0, frequency1)§

Calculates the difference in cents between two frequencies.

Parameters:

frequency0 (Union[float, Fraction, int]) – The first frequency in Hertz.
frequency1 (Union[float, Fraction, int]) – The second frequency in Hertz.

Returns:

The difference in cents between the first and the second frequency.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_cents(200, 400)
1200.0

static hertz_to_midi_pitch_number(frequency)§

Converts a frequency in hertz to its respective midi pitch.

Parameters:: frequency (Union[float, Fraction, int]) – The frequency that shall be translated to a midi pitch number.
Returns:: The midi pitch number (potentially a floating point number if the entered frequency isn’t on the grid of the equal divided octave tuning with a = 440 Hertz).
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_midi_pitch_number(440)
69.0
>>> abc.Pitch.hertz_to_midi_pitch_number(440 * 3 / 2)
75.98044999134612

intersection(other, strict=False)§

Make intersection with other JustIntonationPitch.

Parameters:

other (JustIntonationPitch) – The JustIntonationPitch to build the intersection with.
strict (bool) – If set to True only exponent_tuple are included into the intersection if their value is equal. If set to False the method will also include exponent_tuple if both pitches own them on the same axis but with different values (the method will take the smaller exponent).

Return type:

Example:

>>> from mutwo.music_parameters import pitches
>>> p0 = pitches.JustIntonationPitch('5/3')
>>> p0.intersection(pitches.JustIntonationPitch('7/6'))
>>> p0
JustIntonationPitch(1/3)
>>> p1 = pitches.JustIntonationPitch('9/7')
>>> p1.intersection(pitches.JustIntonationPitch('3/2'))
>>> p1
JustIntonationPitch(3/1)
>>> p2 = pitches.JustIntonationPitch('9/7')
>>> p2.intersection(pitches.JustIntonationPitch('3/2'), strict=True)
>>> p2
JustIntonationPitch(1/1)

inverse(axis=None)§

Inverse current pitch on given axis.

Parameters:: axis (JustIntonationPitch, optional) – The JustIntonationPitch from which the pitch shall be inversed.
Return type:: JustIntonationPitch

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('3/2')
>>> p.inverse()
>>> p
JustIntonationPitch(2/3)

move_to_closest_register(reference)§

Parameters:: reference (JustIntonationPitch) –
Return type:: JustIntonationPitch

normalize(prime=2)§

Normalize JustIntonationPitch.

Parameters:: prime (int) – The normalization period (2 for octave, 3 for twelfth, …). Default to 2.
Return type:: JustIntonationPitch

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('12/2')
>>> p.normalize()
>>> p
JustIntonationPitch(3/2)

static ratio_to_cents(ratio)§

Converts a frequency ratio to its respective cent value.

Parameters:: ratio (Fraction) – The frequency ratio which cent value shall be calculated.
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.ratio_to_cents(fractions.Fraction(3, 2))
701.9550008653874

register(octave)§

Move JustIntonationPitch to the given octave.

Parameters:: octave (int) – 0 for the octave from 1/1 to 2/1, negative values for octaves below 1/1 and positive values for octaves above 2/1.
Return type:: JustIntonationPitch

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('3/2')
>>> p.register(1)
>>> p
JustIntonationPitch(6/2)
>>> p.register(-1)
>>> p
JustIntonationPitch(3/4)
>>> p.register(0)
>>> p
JustIntonationPitch(3/2)

resolve_envelope(duration, resolve_envelope_class=None)§

Parameters:

duration (Union[float, Fraction, int]) –
resolve_envelope_class (Optional[type[mutwo.core_events.envelopes.Envelope]]) –

Return type:

subtract(pitch_interval)§

Subtract JustIntonationPitch from current pitch.

Parameters:

other – The JustIntonationPitch to subtract from the current pitch.
pitch_interval (PitchInterval) –

Return type:

Example:

>>> from mutwo.music_parameters import pitches
>>> p = pitches.JustIntonationPitch('9/4')
>>> p.subtract(pitches.JustIntonationPitch('3/2'))
>>> p
JustIntonationPitch(3/2)

property blueprint: tuple[tuple[int, ...], ...]§

property cent_deviation_from_closest_western_pitch_class: float§

property closest_pythagorean_interval: JustIntonationPitch§

property concert_pitch: Pitch§

property denominator: int§

Return the denominator of JustIntonationPitch.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch0.denominator
1

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property envelope: RelativeEnvelope§

property exponent_tuple: tuple§

property factorised: tuple§

Return factorised / decomposed version of itsef.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch0.factorised
(2, 2, 5)
>>> just_intonation_pitch1 = JustIntonationPitch("7/6")
>>> just_intonation_pitch1.factorised
(2, 3, 7)

property factorised_numerator_and_denominator: tuple§

property frequency: float§

property harmonic: int§

Return the nth - harmonic / subharmonic the pitch may represent.

Returns:: May be positive for harmonic and negative for subharmonic pitches. If the return - value is 0, the interval may occur neither between the first harmonic and any other pitch of the harmonic scale nor between the first subharmonic in the and any other pitch of the subharmonic scale.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1))
>>> just_intonation_pitch0.ratio
fractions.Fraction(3, 2)
>>> just_intonation_pitch0.harmonic
3
>>> just_intonation_pitch1 = JustIntonationPitch((-1,), 2)
>>> just_intonation_pitch1.harmonic
-3

property harmonicity_barlow: float§

Calculate the barlow-harmonicity of an interval.

This implementation follows Clarence Barlows definition, given in ‘The Ratio Book’ (1992).

A higher number means a more harmonic interval / a less complex harmony.

barlow(1/1) is definied as infinite.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch1 = JustIntonationPitch()
>>> just_intonation_pitch2 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch3 = JustIntonationPitch((0, 0, -1,))
>>> just_intonation_pitch0.harmonicity_barlow
0.27272727272727276
>>> just_intonation_pitch1.harmonicity_barlow # 1/1 is infinite harmonic
inf
>>> just_intonation_pitch2.harmonicity_barlow
0.11904761904761904
>>> just_intonation_pitch3.harmonicity_barlow
-0.10638297872340426

property harmonicity_euler: int§

Return the ‘gradus suavitatis’ of euler.

A higher number means a less consonant interval / a more complicated harmony. euler(1/1) is definied as 1.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch1 = JustIntonationPitch()
>>> just_intonation_pitch2 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch3 = JustIntonationPitch((0, 0, -1,))
>>> just_intonation_pitch0.harmonicity_euler
4
>>> just_intonation_pitch1.harmonicity_euler
1
>>> just_intonation_pitch2.harmonicity_euler
7
>>> just_intonation_pitch3.harmonicity_euler
8

property harmonicity_simplified_barlow: float§

Calculate a simplified barlow-harmonicity of an interval.

This implementation follows Clarence Barlows definition, given in ‘The Ratio Book’ (1992), with the difference that only positive numbers are returned and that (1/1) is defined as 1 instead of infinite.

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch1 = JustIntonationPitch()
>>> just_intonation_pitch2 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch3 = JustIntonationPitch((0, 0, -1,))
>>> just_intonation_pitch0.harmonicity_simplified_barlow
0.27272727272727276
>>> just_intonation_pitch1.harmonicity_simplified_barlow # 1/1 is not infinite but 1
1
>>> just_intonation_pitch2.harmonicity_simplified_barlow
0.11904761904761904
>>> just_intonation_pitch3.harmonicity_simplified_barlow # positive return value
0.10638297872340426

property harmonicity_tenney: float§

Calculate Tenneys harmonic distance of an interval

A higher number means a more consonant interval / a less complicated harmony.

tenney(1/1) is definied as 0.

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1,))
>>> just_intonation_pitch1 = JustIntonationPitch()
>>> just_intonation_pitch2 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch3 = JustIntonationPitch((0, 0, -1,))
>>> just_intonation_pitch0.harmonicity_tenney
2.584962500721156
>>> just_intonation_pitch1.harmonicity_tenney
0.0
>>> just_intonation_pitch2.harmonicity_tenney
4.321928094887363
>>> just_intonation_pitch3.harmonicity_tenney
-0.10638297872340426

property harmonicity_vogel: int§

property harmonicity_wilson: int§

property helmholtz_ellis_just_intonation_notation_commas: CommaCompound§: Commas of JustIntonationPitch.

property interval: float§

property midi_pitch_number: float§: The midi pitch number (from 0 to 127) of the pitch.

property numerator: int§

Return the numerator of a JustIntonationPitch - object.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, -1,))
>>> just_intonation_pitch0.numerator
1

property occupied_primes: tuple§: Return all occurring prime numbers of a JustIntonationPitch object.

property octave: int§

property prime_tuple: tuple§

Return ascending list of primes, until the highest contained Prime.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 1, 2))
>>> just_intonation_pitch0.exponent_tuple
(2, 3, 5)
>>> just_intonation_pitch1 = JustIntonationPitch((0, -1, 0, 0, 1), 1)
>>> just_intonation_pitch1.exponent_tuple
(2, 3, 5, 7, 11)

property primes_for_numerator_and_denominator: tuple§

property ratio: Fraction§

Return the JustIntonationPitch transformed to a Ratio.

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((0, 0, 1,))
>>> just_intonation_pitch0.ratio
fractions.Fraction(5, 4)
>>> just_intonation_pitch0 = JustIntonationPitch("3/2")
>>> just_intonation_pitch0.ratio
fractions.Fraction(3, 2)

property tonality: bool§

Return the tonality (bool) of a JustIntonationPitch - object.

The tonality of a JustIntonationPitch - may be True (otonality) if the exponent of the highest occurring prime number is a positive number and False if the exponent is a negative number (utonality).

Example:

>>> just_intonation_pitch0 = JustIntonationPitch((-2. 1))
>>> just_intonation_pitch0.tonality
True
>>> just_intonation_pitch1 = JustIntonationPitch((-2, -1))
>>> just_intonation_pitch1.tonality
False
>>> just_intonation_pitch2 = JustIntonationPitch([])
>>> just_intonation_pitch2.tonality
True

property value_name§

class DirectVolume(amplitude)[source]§

A simple volume class that gets directly initialised by its amplitude.

Parameters:: amplitude (Union[float, Fraction, int]) – The amplitude of the DirectVolume object.

May be used when a converter class needs a volume object, but there is no need or desire for a complex abstraction of the respective volume.

Public Data Attributes:

amplitude

Inherited from Volume

`decibel`	The decibel of the volume (from -120 to 0)
`midi_velocity`	The velocity of the volume (from 0 to 127).
`amplitude`
`value_name`

Inherited from SingleNumberParameter

`direct_comparison_type_tuple`
`digit_to_round_to_count`

Public Methods:

`__init__`(amplitude)
`__repr__`()	Return repr(self).

Inherited from Volume

`decibel_to_amplitude_ratio`(decibel[, ...])	Convert decibel to amplitude ratio.
`decibel_to_power_ratio`(decibel[, ...])	Convert decibel to power ratio.
`amplitude_ratio_to_decibel`(amplitude[, ...])	Convert amplitude ratio to decibel.
`power_ratio_to_decibel`(amplitude[, ...])	Convert power ratio to decibel.
`amplitude_ratio_to_midi_velocity`(amplitude)	Convert amplitude ratio to midi velocity.
`decibel_to_midi_velocity`(decibel_to_convert)	Convert decibel to midi velocity (0 to 127).

Inherited from SingleNumberParameter

`__float__`()
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from Volume

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ABC

_abc_impl

static amplitude_ratio_to_decibel(amplitude, reference_amplitude=1)§

Convert amplitude ratio to decibel.

Parameters:

amplitude (Union[float, Fraction, int]) – The amplitude that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.amplitude_ratio_to_decibel(1)
0
>>> abc.Volume.amplitude_ratio_to_decibel(0)
inf
>>> abc.Volume.amplitude_ratio_to_decibel(0.5)
-6.020599913279624

static amplitude_ratio_to_midi_velocity(amplitude, reference_amplitude=1)§

Convert amplitude ratio to midi velocity.

Parameters:

amplitude (core_constants.Real) – The amplitude which shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Returns:

The midi velocity.

Return type:

int

The method clips values that are higher than 1 / lower than 0.

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.amplitude_ratio_to_midi_velocity(1)
127
>>> abc.Volume.amplitude_ratio_to_midi_velocity(0)
0

static decibel_to_amplitude_ratio(decibel, reference_amplitude=1)§

Convert decibel to amplitude ratio.

Parameters:

decibel (Union[float, Fraction, int]) – The decibel number that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_amplitude_ratio(0)
1
>>> abc.Volume.decibel_to_amplitude_ratio(-6)
0.5011872336272722
>>> abc.Volume.decibel_to_amplitude_ratio(0, reference_amplitude=0.25)
0.25

static decibel_to_midi_velocity(decibel_to_convert, minimum_decibel=None, maximum_decibel=None)§

Convert decibel to midi velocity (0 to 127).

Parameters:

decibel (core_constants.Real) – The decibel value which shall be converted..
minimum_decibel (core_constants.Real, optional) – The decibel value which is equal to the lowest midi velocity (0).
maximum_decibel (core_constants.Real, optional) – The decibel value which is equal to the highest midi velocity (127).
decibel_to_convert (Union[float, Fraction, int]) –

Returns:

The midi velocity.

Return type:

int

The method clips values which are higher than ‘maximum_decibel’ and lower than ‘minimum_decibel’.

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_midi_velocity(0)
127
>>> abc.Volume.decibel_to_midi_velocity(-40)
0

static decibel_to_power_ratio(decibel, reference_amplitude=1)§

Convert decibel to power ratio.

Parameters:

decibel (Union[float, Fraction, int]) – The decibel number that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_power_ratio(0)
1
>>> abc.Volume.decibel_to_power_ratio(-6)
0.251188643150958
>>> abc.Volume.decibel_to_power_ratio(0, reference_amplitude=0.25)
0.25

static power_ratio_to_decibel(amplitude, reference_amplitude=1)§

Convert power ratio to decibel.

Parameters:

amplitude (Union[float, Fraction, int]) – The amplitude that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.power_ratio_to_decibel(1)
0
>>> abc.Volume.power_ratio_to_decibel(0)
inf
>>> abc.Volume.power_ratio_to_decibel(0.5)
-3.010299956639812

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

property decibel: Union[float, Fraction, int]§: The decibel of the volume (from -120 to 0)

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property midi_velocity: int§: The velocity of the volume (from 0 to 127).

property value_name§

class DecibelVolume(decibel)[source]§

A simple volume class that gets directly initialised by decibel.

Parameters:: decibel (Union[float, Fraction, int]) – The decibel of the DecibelVolume object (should be from -120 to 0).

May be used when a converter class needs a volume object, but there is no need or desire for a complex abstraction of the respective volume.

Public Data Attributes:

`decibel`	The decibel of the volume (from -120 to 0)
`amplitude`

Inherited from Volume

`decibel`	The decibel of the volume (from -120 to 0)
`midi_velocity`	The velocity of the volume (from 0 to 127).
`amplitude`
`value_name`

Inherited from SingleNumberParameter

`direct_comparison_type_tuple`
`digit_to_round_to_count`

Public Methods:

`__init__`(decibel)
`__repr__`()	Return repr(self).

Inherited from Volume

`decibel_to_amplitude_ratio`(decibel[, ...])	Convert decibel to amplitude ratio.
`decibel_to_power_ratio`(decibel[, ...])	Convert decibel to power ratio.
`amplitude_ratio_to_decibel`(amplitude[, ...])	Convert amplitude ratio to decibel.
`power_ratio_to_decibel`(amplitude[, ...])	Convert power ratio to decibel.
`amplitude_ratio_to_midi_velocity`(amplitude)	Convert amplitude ratio to midi velocity.
`decibel_to_midi_velocity`(decibel_to_convert)	Convert decibel to midi velocity (0 to 127).

Inherited from SingleNumberParameter

`__float__`()
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from Volume

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ABC

_abc_impl

static amplitude_ratio_to_decibel(amplitude, reference_amplitude=1)§

Convert amplitude ratio to decibel.

Parameters:

amplitude (Union[float, Fraction, int]) – The amplitude that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.amplitude_ratio_to_decibel(1)
0
>>> abc.Volume.amplitude_ratio_to_decibel(0)
inf
>>> abc.Volume.amplitude_ratio_to_decibel(0.5)
-6.020599913279624

static amplitude_ratio_to_midi_velocity(amplitude, reference_amplitude=1)§

Convert amplitude ratio to midi velocity.

Parameters:

amplitude (core_constants.Real) – The amplitude which shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Returns:

The midi velocity.

Return type:

int

The method clips values that are higher than 1 / lower than 0.

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.amplitude_ratio_to_midi_velocity(1)
127
>>> abc.Volume.amplitude_ratio_to_midi_velocity(0)
0

static decibel_to_amplitude_ratio(decibel, reference_amplitude=1)§

Convert decibel to amplitude ratio.

Parameters:

decibel (Union[float, Fraction, int]) – The decibel number that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_amplitude_ratio(0)
1
>>> abc.Volume.decibel_to_amplitude_ratio(-6)
0.5011872336272722
>>> abc.Volume.decibel_to_amplitude_ratio(0, reference_amplitude=0.25)
0.25

static decibel_to_midi_velocity(decibel_to_convert, minimum_decibel=None, maximum_decibel=None)§

Convert decibel to midi velocity (0 to 127).

Parameters:

decibel (core_constants.Real) – The decibel value which shall be converted..
minimum_decibel (core_constants.Real, optional) – The decibel value which is equal to the lowest midi velocity (0).
maximum_decibel (core_constants.Real, optional) – The decibel value which is equal to the highest midi velocity (127).
decibel_to_convert (Union[float, Fraction, int]) –

Returns:

The midi velocity.

Return type:

int

The method clips values which are higher than ‘maximum_decibel’ and lower than ‘minimum_decibel’.

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_midi_velocity(0)
127
>>> abc.Volume.decibel_to_midi_velocity(-40)
0

static decibel_to_power_ratio(decibel, reference_amplitude=1)§

Convert decibel to power ratio.

Parameters:

decibel (Union[float, Fraction, int]) – The decibel number that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_power_ratio(0)
1
>>> abc.Volume.decibel_to_power_ratio(-6)
0.251188643150958
>>> abc.Volume.decibel_to_power_ratio(0, reference_amplitude=0.25)
0.25

static power_ratio_to_decibel(amplitude, reference_amplitude=1)§

Convert power ratio to decibel.

Parameters:

amplitude (Union[float, Fraction, int]) – The amplitude that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.power_ratio_to_decibel(1)
0
>>> abc.Volume.power_ratio_to_decibel(0)
inf
>>> abc.Volume.power_ratio_to_decibel(0.5)
-3.010299956639812

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

property decibel: Union[float, Fraction, int]§: The decibel of the volume (from -120 to 0)

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property midi_velocity: int§: The velocity of the volume (from 0 to 127).

property value_name§

class WesternVolume(name, minimum_decibel=None, maximum_decibel=None)[source]§

Volume with a traditional Western nomenclature.

Parameters:

name (str) – Dynamic indicator in traditional Western nomenclature (‘f’, ‘pp’, ‘mf’, ‘sfz’, etc.). For a list of all supported indicators, see mutwo.music_parameters.constants.DYNAMIC_INDICATOR_TUPLE.
minimum_decibel (core_constants.Real, optional) – The decibel value which is equal to the lowest dynamic indicator (ppppp).
maximum_decibel (core_constants.Real, optional) – The decibel value which is equal to the highest dynamic indicator (fffff).

Example:

>>> from mutwo.music_parameters import volumes
>>> volumes.WesternVolume('fff')
WesternVolume(fff)

Public Data Attributes:

`name`	The western nomenclature name for dynamic.
`decibel`	The decibel of the volume (from -120 to 0)
`amplitude`

Inherited from Volume

`decibel`	The decibel of the volume (from -120 to 0)
`midi_velocity`	The velocity of the volume (from 0 to 127).
`amplitude`
`value_name`

Inherited from SingleNumberParameter

`direct_comparison_type_tuple`
`digit_to_round_to_count`

Public Methods:

`__init__`(name[, minimum_decibel, ...])
`__repr__`()	Return repr(self).
`from_amplitude`(amplitude)	Initialise WesternVolume from amplitude ratio.
`from_decibel`(decibel)	Initialise WesternVolume from decibel.

Inherited from Volume

`decibel_to_amplitude_ratio`(decibel[, ...])	Convert decibel to amplitude ratio.
`decibel_to_power_ratio`(decibel[, ...])	Convert decibel to power ratio.
`amplitude_ratio_to_decibel`(amplitude[, ...])	Convert amplitude ratio to decibel.
`power_ratio_to_decibel`(amplitude[, ...])	Convert power ratio to decibel.
`amplitude_ratio_to_midi_velocity`(amplitude)	Convert amplitude ratio to midi velocity.
`decibel_to_midi_velocity`(decibel_to_convert)	Convert decibel to midi velocity (0 to 127).

Inherited from SingleNumberParameter

`__float__`()
`__int__`()
`__eq__`(other)	Return self==value.
`__lt__`(other)	Return self<value.
`__gt__`(other[, NotImplemented])	Return a > b.
`__le__`(other[, NotImplemented])	Return a <= b.
`__ge__`(other[, NotImplemented])	Return a >= b.

Inherited from SingleValueParameter

`__init_subclass__`([value_name, ...])	This method is called when a class is subclassed.
`__str__`()	Return str(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from Volume

_abc_impl

Inherited from SingleNumberParameter

_abc_impl

Inherited from SingleValueParameter

_abc_impl

Inherited from ABC

_abc_impl

static amplitude_ratio_to_decibel(amplitude, reference_amplitude=1)§

Convert amplitude ratio to decibel.

Parameters:

amplitude (Union[float, Fraction, int]) – The amplitude that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.amplitude_ratio_to_decibel(1)
0
>>> abc.Volume.amplitude_ratio_to_decibel(0)
inf
>>> abc.Volume.amplitude_ratio_to_decibel(0.5)
-6.020599913279624

static amplitude_ratio_to_midi_velocity(amplitude, reference_amplitude=1)§

Convert amplitude ratio to midi velocity.

Parameters:

amplitude (core_constants.Real) – The amplitude which shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Returns:

The midi velocity.

Return type:

int

The method clips values that are higher than 1 / lower than 0.

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.amplitude_ratio_to_midi_velocity(1)
127
>>> abc.Volume.amplitude_ratio_to_midi_velocity(0)
0

static decibel_to_amplitude_ratio(decibel, reference_amplitude=1)§

Convert decibel to amplitude ratio.

Parameters:

decibel (Union[float, Fraction, int]) – The decibel number that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_amplitude_ratio(0)
1
>>> abc.Volume.decibel_to_amplitude_ratio(-6)
0.5011872336272722
>>> abc.Volume.decibel_to_amplitude_ratio(0, reference_amplitude=0.25)
0.25

static decibel_to_midi_velocity(decibel_to_convert, minimum_decibel=None, maximum_decibel=None)§

Convert decibel to midi velocity (0 to 127).

Parameters:

decibel (core_constants.Real) – The decibel value which shall be converted..
minimum_decibel (core_constants.Real, optional) – The decibel value which is equal to the lowest midi velocity (0).
maximum_decibel (core_constants.Real, optional) – The decibel value which is equal to the highest midi velocity (127).
decibel_to_convert (Union[float, Fraction, int]) –

Returns:

The midi velocity.

Return type:

int

The method clips values which are higher than ‘maximum_decibel’ and lower than ‘minimum_decibel’.

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_midi_velocity(0)
127
>>> abc.Volume.decibel_to_midi_velocity(-40)
0

static decibel_to_power_ratio(decibel, reference_amplitude=1)§

Convert decibel to power ratio.

Parameters:

decibel (Union[float, Fraction, int]) – The decibel number that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.decibel_to_power_ratio(0)
1
>>> abc.Volume.decibel_to_power_ratio(-6)
0.251188643150958
>>> abc.Volume.decibel_to_power_ratio(0, reference_amplitude=0.25)
0.25

classmethod from_amplitude(amplitude)[source]§

Initialise WesternVolume from amplitude ratio.

Parameters:: amplitude (Union[float, Fraction, int]) – The amplitude which shall be converted to a WesternVolume object.
Return type:: WesternVolume

>>> from mutwo.music_parameters import volumes
>>> volumes.WesternVolume.from_amplitude(0.05)
WesternVolume(mp)

classmethod from_decibel(decibel)[source]§

Initialise WesternVolume from decibel.

Parameters:: decibel (Union[float, Fraction, int]) – The decibel which shall be converted to a WesternVolume object.
Return type:: WesternVolume

>>> from mutwo.music_parameters import volumes
>>> volumes.WesternVolume.from_decibel(-24)
WesternVolume(mf)

static power_ratio_to_decibel(amplitude, reference_amplitude=1)§

Convert power ratio to decibel.

Parameters:

amplitude (Union[float, Fraction, int]) – The amplitude that shall be converted.
reference_amplitude (Union[float, Fraction, int]) – The amplitude for decibel == 0.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Volume.power_ratio_to_decibel(1)
0
>>> abc.Volume.power_ratio_to_decibel(0)
inf
>>> abc.Volume.power_ratio_to_decibel(0.5)
-3.010299956639812

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

property decibel: Union[float, Fraction, int]§: The decibel of the volume (from -120 to 0)

property digit_to_round_to_count: Optional[int]§

direct_comparison_type_tuple = ()§

property midi_velocity: int§: The velocity of the volume (from 0 to 127).

property name: str§

The western nomenclature name for dynamic.

For a list of all supported indicators, see mutwo.music_parameters.constants.DYNAMIC_INDICATOR_TUPLE.

property value_name§

class BarLine(abbreviation: Optional[str] = None)[source]§

Public Data Attributes:

abbreviation

Inherited from NotationIndicator

Inherited from Indicator

Public Methods:

`__init__`([abbreviation])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([abbreviation])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from NotationIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: abbreviation (Optional[str]) –

get_arguments_dict()§

Return type:: dict[str, Any]

abbreviation: Optional[str] = None§

property is_active: bool§

class Clef(name: Optional[str] = None)[source]§

Public Data Attributes:

name

Inherited from NotationIndicator

Inherited from Indicator

Public Methods:

`__init__`([name])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([name])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from NotationIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: name (Optional[str]) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

name: Optional[str] = None§

class Ottava(n_octaves: Optional[int] = 0)[source]§

Public Data Attributes:

n_octaves

Inherited from NotationIndicator

Inherited from Indicator

Public Methods:

`__init__`([n_octaves])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([n_octaves])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from NotationIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: n_octaves (Optional[int]) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

n_octaves: Optional[int] = 0§

class MarginMarkup(content: Optional[str] = None, context: Optional[str] = 'Staff')[source]§

Public Data Attributes:

`content`
`context`

Inherited from NotationIndicator

Inherited from Indicator

Public Methods:

`__init__`([content, context])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([content, context])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from NotationIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:

content (Optional[str]) –
context (Optional[str]) –

get_arguments_dict()§

Return type:: dict[str, Any]

content: Optional[str] = None§

context: Optional[str] = 'Staff'§

property is_active: bool§

class Markup(content: Optional[str] = None, direction: Optional[str] = None)[source]§

Public Data Attributes:

`content`
`direction`

Inherited from NotationIndicator

Inherited from Indicator

Public Methods:

`__init__`([content, direction])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([content, direction])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from NotationIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:

content (Optional[str]) –
direction (Optional[str]) –

get_arguments_dict()§

Return type:: dict[str, Any]

content: Optional[str] = None§

direction: Optional[str] = None§

property is_active: bool§

class RehearsalMark(markup: Optional[str] = None)[source]§

Public Data Attributes:

markup

Inherited from NotationIndicator

Inherited from Indicator

Public Methods:

`__init__`([markup])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([markup])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from NotationIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: markup (Optional[str]) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

markup: Optional[str] = None§

class NotationIndicatorCollection(bar_line: mutwo.music_parameters.notation_indicators.BarLine = <factory>, clef: mutwo.music_parameters.notation_indicators.Clef = <factory>, ottava: mutwo.music_parameters.notation_indicators.Ottava = <factory>, margin_markup: mutwo.music_parameters.notation_indicators.MarginMarkup = <factory>, markup: mutwo.music_parameters.notation_indicators.Markup = <factory>, rehearsal_mark: mutwo.music_parameters.notation_indicators.RehearsalMark = <factory>)[source]§

Public Methods:

`__setattr__`(parameter_name, value)	Implement setattr(self, name, value).
`__init__`([bar_line, clef, ottava, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from IndicatorCollection

`get_all_indicator`()
`get_indicator_dict`()
`__init__`([bar_line, clef, ottava, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Generic

`__class_getitem__`(params)
`__init_subclass__`(args, *kwargs)	This method is called when a class is subclassed.

Private Data Attributes:

Inherited from Generic

_is_protocol

Parameters:

bar_line (BarLine) –
clef (Clef) –
ottava (Ottava) –
margin_markup (MarginMarkup) –
markup (Markup) –
rehearsal_mark (RehearsalMark) –

get_all_indicator()§

Return type:: tuple[~T, …]

get_indicator_dict()§

Return type:: dict[str, mutwo.music_parameters.abc.Indicator]

bar_line: BarLine§

clef: Clef§

margin_markup: MarginMarkup§

markup: Markup§

ottava: Ottava§

rehearsal_mark: RehearsalMark§

class Tremolo(n_flags: Optional[int] = None)[source]§

Public Data Attributes:

n_flags

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([n_flags])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([n_flags])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([n_flags])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: n_flags (Optional[int]) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

n_flags: Optional[int] = None§

class Articulation(name: Optional[Literal['accent', 'marcato', 'staccatissimo', 'espressivo', 'staccato', 'tenuto', 'portato', 'upbow', 'downbow', 'flageolet', 'thumb', 'lheel', 'rheel', 'ltoe', 'rtoe', 'open', 'halfopen', 'snappizzicato', 'stopped', 'turn', 'reverseturn', 'trill', 'prall', 'mordent', 'prallprall', 'prallmordent', 'upprall', 'downprall', 'upmordent', 'downmordent', 'pralldown', 'prallup', 'lineprall', 'signumcongruentiae', 'shortfermata', 'fermata', 'longfermata', 'verylongfermata', 'segno', 'coda', 'varcoda', '^', '+', '-', '|', '>', '.', '_']] = None)[source]§

Public Data Attributes:

name

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([name])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([name])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([name])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: name (Optional[Literal['accent', 'marcato', 'staccatissimo', 'espressivo', 'staccato', 'tenuto', 'portato', 'upbow', 'downbow', 'flageolet', 'thumb', 'lheel', 'rheel', 'ltoe', 'rtoe', 'open', 'halfopen', 'snappizzicato', 'stopped', 'turn', 'reverseturn', 'trill', 'prall', 'mordent', 'prallprall', 'prallmordent', 'upprall', 'downprall', 'upmordent', 'downmordent', 'pralldown', 'prallup', 'lineprall', 'signumcongruentiae', 'shortfermata', 'fermata', 'longfermata', 'verylongfermata', 'segno', 'coda', 'varcoda', '^', '+', '-', '|', '>', '.', '_']]) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

name: Optional[Literal['accent', 'marcato', 'staccatissimo', 'espressivo', 'staccato', 'tenuto', 'portato', 'upbow', 'downbow', 'flageolet', 'thumb', 'lheel', 'rheel', 'ltoe', 'rtoe', 'open', 'halfopen', 'snappizzicato', 'stopped', 'turn', 'reverseturn', 'trill', 'prall', 'mordent', 'prallprall', 'prallmordent', 'upprall', 'downprall', 'upmordent', 'downmordent', 'pralldown', 'prallup', 'lineprall', 'signumcongruentiae', 'shortfermata', 'fermata', 'longfermata', 'verylongfermata', 'segno', 'coda', 'varcoda', '^', '+', '-', '|', '>', '.', '_']] = None§

class Arpeggio(direction: Optional[Literal['up', 'down']] = None)[source]§

Public Data Attributes:

direction

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([direction])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([direction])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([direction])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: direction (Optional[Literal['up', 'down']]) –

get_arguments_dict()§

Return type:: dict[str, Any]

direction: Optional[Literal['up', 'down']] = None§

property is_active: bool§

class Pedal(pedal_type: Optional[Literal['sustain', 'sostenuto', 'corda']] = None, pedal_activity: Optional[bool] = True)[source]§

Public Data Attributes:

`pedal_type`
`pedal_activity`

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([pedal_type, pedal_activity])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([pedal_type, pedal_activity])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([pedal_type, pedal_activity])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:

pedal_type (Optional[Literal['sustain', 'sostenuto', 'corda']]) –
pedal_activity (Optional[bool]) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

pedal_activity: Optional[bool] = True§

pedal_type: Optional[Literal['sustain', 'sostenuto', 'corda']] = None§

class StringContactPoint(contact_point: Optional[Literal['dietro ponticello', 'molto sul ponticello', 'molto sul tasto', 'ordinario', 'pizzicato', 'ponticello', 'sul ponticello', 'sul tasto', 'col legno tratto', 'd.p.', 'm.s.p', 'm.s.t.', 'ord.', 'pizz.', 'p.', 's.p.', 's.t.', 'c.l.t.']] = None)[source]§

Public Data Attributes:

contact_point

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([contact_point])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([contact_point])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([contact_point])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: contact_point (Optional[Literal['dietro ponticello', 'molto sul ponticello', 'molto sul tasto', 'ordinario', 'pizzicato', 'ponticello', 'sul ponticello', 'sul tasto', 'col legno tratto', 'd.p.', 'm.s.p', 'm.s.t.', 'ord.', 'pizz.', 'p.', 's.p.', 's.t.', 'c.l.t.']]) –

get_arguments_dict()§

Return type:: dict[str, Any]

contact_point: Optional[Literal['dietro ponticello', 'molto sul ponticello', 'molto sul tasto', 'ordinario', 'pizzicato', 'ponticello', 'sul ponticello', 'sul tasto', 'col legno tratto', 'd.p.', 'm.s.p', 'm.s.t.', 'ord.', 'pizz.', 'p.', 's.p.', 's.t.', 'c.l.t.']] = None§

property is_active: bool§

class Ornamentation(direction: Optional[Literal['up', 'down']] = None, n_times: int = 1)[source]§

Public Data Attributes:

`direction`
`n_times`

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([direction, n_times])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([direction, n_times])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([direction, n_times])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:

direction (Optional[Literal['up', 'down']]) –
n_times (int) –

get_arguments_dict()§

Return type:: dict[str, Any]

direction: Optional[Literal['up', 'down']] = None§

property is_active: bool§

n_times: int = 1§

class BendAfter(bend_amount: Optional[float] = None, minimum_length: Optional[float] = 3, thickness: Optional[float] = 3)[source]§

Public Data Attributes:

`bend_amount`
`minimum_length`
`thickness`

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([bend_amount, minimum_length, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([bend_amount, minimum_length, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([bend_amount, minimum_length, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:

bend_amount (Optional[float]) –
minimum_length (Optional[float]) –
thickness (Optional[float]) –

get_arguments_dict()§

Return type:: dict[str, Any]

bend_amount: Optional[float] = None§

property is_active: bool§

minimum_length: Optional[float] = 3§

thickness: Optional[float] = 3§

class ArtificalHarmonic(n_semitones: Optional[int] = None)[source]§

Public Data Attributes:

n_semitones

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([n_semitones])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([n_semitones])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([n_semitones])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: n_semitones (Optional[int]) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

n_semitones: Optional[int] = None§

class PreciseNaturalHarmonic(string_pitch: Optional[mutwo.music_parameters.pitches.WesternPitch.WesternPitch] = None, played_pitch: Optional[mutwo.music_parameters.pitches.WesternPitch.WesternPitch] = None, harmonic_note_head_style: bool = True, parenthesize_lower_note_head: bool = False)[source]§

Public Data Attributes:

`string_pitch`
`played_pitch`
`harmonic_note_head_style`
`parenthesize_lower_note_head`

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([string_pitch, played_pitch, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([string_pitch, played_pitch, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([string_pitch, played_pitch, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:

string_pitch (Optional[WesternPitch]) –
played_pitch (Optional[WesternPitch]) –
harmonic_note_head_style (bool) –
parenthesize_lower_note_head (bool) –

get_arguments_dict()§

Return type:: dict[str, Any]

harmonic_note_head_style: bool = True§

property is_active: bool§

parenthesize_lower_note_head: bool = False§

played_pitch: Optional[WesternPitch] = None§

string_pitch: Optional[WesternPitch] = None§

class Fermata(fermata_type: Optional[Literal['shortfermata', 'fermata', 'longfermata', 'verylongfermata']] = None)[source]§

Public Data Attributes:

fermata_type

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([fermata_type])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([fermata_type])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([fermata_type])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: fermata_type (Optional[Literal['shortfermata', 'fermata', 'longfermata', 'verylongfermata']]) –

get_arguments_dict()§

Return type:: dict[str, Any]

fermata_type: Optional[Literal['shortfermata', 'fermata', 'longfermata', 'verylongfermata']] = None§

property is_active: bool§

class Hairpin(symbol: Optional[Literal['<', '>', '<>', '!']] = None, niente: bool = False)[source]§

Public Data Attributes:

`symbol`
`niente`

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([symbol, niente])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([symbol, niente])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([symbol, niente])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:

symbol (Optional[Literal['<', '>', '<>', '!']]) –
niente (bool) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

niente: bool = False§

symbol: Optional[Literal['<', '>', '<>', '!']] = None§

class Trill(pitch: Optional[mutwo.music_parameters.abc.Pitch] = None)[source]§

Public Data Attributes:

pitch

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([pitch])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([pitch])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([pitch])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: pitch (Optional[Pitch]) –

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

pitch: Optional[Pitch] = None§

class WoodwindFingering(cc: Optional[Tuple[str, ...]] = None, left_hand: Optional[Tuple[str, ...]] = None, right_hand: Optional[Tuple[str, ...]] = None, instrument: str = 'clarinet')[source]§

Public Data Attributes:

`cc`
`left_hand`
`right_hand`
`instrument`

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([cc, left_hand, right_hand, instrument])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([cc, left_hand, right_hand, instrument])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([cc, left_hand, right_hand, instrument])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:

cc (Optional[Tuple[str, ...]]) –
left_hand (Optional[Tuple[str, ...]]) –
right_hand (Optional[Tuple[str, ...]]) –
instrument (str) –

get_arguments_dict()§

Return type:: dict[str, Any]

cc: Optional[Tuple[str, ...]] = None§

instrument: str = 'clarinet'§

property is_active: bool§

left_hand: Optional[Tuple[str, ...]] = None§

right_hand: Optional[Tuple[str, ...]] = None§

class Cue(cue_count=None)[source]§

Cue for electronics etc.

Public Data Attributes:

cue_count

Inherited from ImplicitPlayingIndicator

Inherited from Indicator

Public Methods:

`__init__`([cue_count])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from ImplicitPlayingIndicator

`__init__`([cue_count])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Indicator

`get_arguments_dict`()
`__init__`([cue_count])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Private Data Attributes:

_abc_impl

Inherited from ImplicitPlayingIndicator

_abc_impl

Inherited from PlayingIndicator

_abc_impl

Inherited from Indicator

_abc_impl

Inherited from ABC

_abc_impl

Parameters:: cue_count (Optional[int]) –

get_arguments_dict()§

Return type:: dict[str, Any]

cue_count: Optional[int] = None§

property is_active: bool§

class PlayingIndicatorCollection(articulation: mutwo.music_parameters.playing_indicators.Articulation = <factory>, artifical_harmonic: mutwo.music_parameters.playing_indicators.ArtificalHarmonic = <factory>, arpeggio: mutwo.music_parameters.playing_indicators.Arpeggio = <factory>, bartok_pizzicato: mutwo.music_parameters.abc.PlayingIndicator = <factory>, bend_after: mutwo.music_parameters.playing_indicators.BendAfter = <factory>, breath_mark: mutwo.music_parameters.abc.PlayingIndicator = <factory>, cue: mutwo.music_parameters.playing_indicators.Cue = <factory>, duration_line_dashed: mutwo.music_parameters.abc.PlayingIndicator = <factory>, duration_line_triller: mutwo.music_parameters.abc.PlayingIndicator = <factory>, fermata: mutwo.music_parameters.playing_indicators.Fermata = <factory>, glissando: mutwo.music_parameters.abc.PlayingIndicator = <factory>, hairpin: mutwo.music_parameters.playing_indicators.Hairpin = <factory>, natural_harmonic: mutwo.music_parameters.abc.PlayingIndicator = <factory>, laissez_vibrer: mutwo.music_parameters.abc.PlayingIndicator = <factory>, ornamentation: mutwo.music_parameters.playing_indicators.Ornamentation = <factory>, pedal: mutwo.music_parameters.playing_indicators.Pedal = <factory>, prall: mutwo.music_parameters.abc.PlayingIndicator = <factory>, precise_natural_harmonic: mutwo.music_parameters.playing_indicators.PreciseNaturalHarmonic = <factory>, string_contact_point: mutwo.music_parameters.playing_indicators.StringContactPoint = <factory>, tie: mutwo.music_parameters.abc.PlayingIndicator = <factory>, tremolo: mutwo.music_parameters.playing_indicators.Tremolo = <factory>, trill: mutwo.music_parameters.playing_indicators.Trill = <factory>, woodwind_fingering: mutwo.music_parameters.playing_indicators.WoodwindFingering = <factory>)[source]§

Public Methods:

`__setattr__`(parameter_name, value)	Overriding default behaviour to allow syntactic sugar.
`__init__`([articulation, artifical_harmonic, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from IndicatorCollection

`get_all_indicator`()
`get_indicator_dict`()
`__init__`([articulation, artifical_harmonic, ...])
`__repr__`()	Return repr(self).
`__eq__`(other)	Return self==value.

Inherited from Generic

`__class_getitem__`(params)
`__init_subclass__`(args, *kwargs)	This method is called when a class is subclassed.

Private Data Attributes:

Inherited from Generic

_is_protocol

Parameters:

articulation (Articulation) –
artifical_harmonic (ArtificalHarmonic) –
arpeggio (Arpeggio) –
bartok_pizzicato (PlayingIndicator) –
bend_after (BendAfter) –
breath_mark (PlayingIndicator) –
cue (Cue) –
duration_line_dashed (PlayingIndicator) –
duration_line_triller (PlayingIndicator) –
fermata (Fermata) –
glissando (PlayingIndicator) –
hairpin (Hairpin) –
natural_harmonic (PlayingIndicator) –
laissez_vibrer (PlayingIndicator) –
ornamentation (Ornamentation) –
pedal (Pedal) –
prall (PlayingIndicator) –
precise_natural_harmonic (PreciseNaturalHarmonic) –
string_contact_point (StringContactPoint) –
tie (PlayingIndicator) –
tremolo (Tremolo) –
trill (Trill) –
woodwind_fingering (WoodwindFingering) –

get_all_indicator()§

Return type:: tuple[~T, …]

get_indicator_dict()§

Return type:: dict[str, mutwo.music_parameters.abc.Indicator]

arpeggio: Arpeggio§

articulation: Articulation§

artifical_harmonic: ArtificalHarmonic§

bartok_pizzicato: PlayingIndicator§

bend_after: BendAfter§

breath_mark: PlayingIndicator§

cue: Cue§

duration_line_dashed: PlayingIndicator§

duration_line_triller: PlayingIndicator§

fermata: Fermata§

glissando: PlayingIndicator§

hairpin: Hairpin§

laissez_vibrer: PlayingIndicator§

natural_harmonic: PlayingIndicator§

ornamentation: Ornamentation§

pedal: Pedal§

prall: PlayingIndicator§

precise_natural_harmonic: PreciseNaturalHarmonic§

string_contact_point: StringContactPoint§

tie: PlayingIndicator§

tremolo: Tremolo§

trill: Trill§

woodwind_fingering: WoodwindFingering§

mutwo.music_parameters.abc §

Abstract base classes for different parameters.

This module defines the public API of parameters. Most other mutwo classes rely on this API. This means when someone creates a new class inheriting from any of the abstract parameter classes which are defined in this module, she or he can make use of all other mutwo modules with this newly created parameter class.

class ExplicitPlayingIndicator(is_active=False)[source]§

Parameters:: is_active (bool) –

get_arguments_dict()[source]§

Return type:: dict[str, Any]

property is_active: bool§

class ImplicitPlayingIndicator[source]§

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

class Indicator[source]§

get_arguments_dict()[source]§

Return type:: dict[str, Any]

abstract property is_active: bool§

class IndicatorCollection[source]§

get_all_indicator()[source]§

Return type:: tuple[~T, …]

get_indicator_dict()[source]§

Return type:: dict[str, mutwo.music_parameters.abc.Indicator]

class Lyric[source]§

Abstract base class for any spoken, sung or written text.

If the user wants to define a new lyric class, the abstract properties phonetic_representation and written_representation have to be overridden.

The phonetic_representation should return a string of X-SAMPA format phonemes, separated by space to indicate new words. Consult wikipedia entry for detailed information regarding X-SAMPA.

The written_representation should return a string of normal written text, separated by space to indicate new words.

abstract property phonetic_representation: value_return_type§

property value_name§

property written_representation: str§: Get text as it would be written in natural language

class NotationIndicator[source]§

Abstract base class for any notation indicator.

get_arguments_dict()§

Return type:: dict[str, Any]

property is_active: bool§

class Pitch(envelope=None)[source]§

Abstract base class for any pitch class.

If the user wants to define a new pitch class, the abstract property frequency has to be overridden. Starting from mutwo version = 0.46.0 the user will furthermore have to define an add() method.

Parameters:: envelope (Optional[Union[Pitch.PitchIntervalEnvelope, Sequence]]) –

class PitchEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=None, apply_parameter_on_event=None, **kwargs)[source]§

Default resolution envelope class for Pitch

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Optional[Callable[[core_constants.ParameterType], core_events.Envelope.Value]]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –

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 frequency_and_envelope_to_pitch(frequency, envelope=None)[source]§

Parameters:

frequency (Union[float, Fraction, int]) –
envelope (Optional[Union[PitchIntervalEnvelope, Sequence]]) –

Return type:

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, ...]§

class PitchIntervalEnvelope(*args, event_to_parameter=None, value_to_parameter=None, parameter_to_value=<function Pitch.PitchIntervalEnvelope.<lambda>>, apply_parameter_on_event=None, base_parameter_and_relative_parameter_to_absolute_parameter=None, **kwargs)[source]§

Default envelope class for Pitch

Resolves into Pitch.PitchEnvelope.

Parameters:

event_to_parameter (Optional[Callable[[core_events.abc.Event], core_constants.ParameterType]]) –
value_to_parameter (Optional[Callable[[core_events.Envelope.Value], core_constants.ParameterType]]) –
parameter_to_value (Callable[[core_constants.ParameterType], core_events.Envelope.Value]) –
apply_parameter_on_event (Optional[Callable[[core_events.abc.Event, core_constants.ParameterType], None]]) –
base_parameter_and_relative_parameter_to_absolute_parameter (Optional[Callable[[core_constants.ParameterType, core_constants.ParameterType], core_constants.ParameterType]]) –

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.

classmethod cents_to_pitch_interval(cents)[source]§

Parameters:: cents (Union[float, Fraction, int]) –
Return type:: PitchInterval

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

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, ...]§

abstract add(pitch_interval, mutate=True)[source]§

Parameters:

pitch_interval (PitchInterval) –
mutate (bool) –

Return type:

static cents_to_ratio(cents)[source]§

Converts a cent value to its respective frequency ratio.

Parameters:: cents (Union[float, Fraction, int]) – Cents that shall be converted to a frequency ratio.
Return type:: Fraction

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.cents_to_ratio(1200)
Fraction(2, 1)

get_pitch_interval(pitch_to_compare)[source]§

Get PitchInterval between itself and other pitch

Parameters:: pitch_to_compare (Pitch) – The pitch which shall be compared to the active pitch.
Returns:: PitchInterval between
Return type:: PitchInterval

Example:

>>> from mutwo import music_parameters
>>> a4 = music_parameters.DirectPitch(frequency=440)
>>> a5 = music_parameters.DirectPitch(frequency=880)
>>> a4.get_pitch_interval(a5)
DirectPitchInterval(cents = 1200)

static hertz_to_cents(frequency0, frequency1)[source]§

Calculates the difference in cents between two frequencies.

Parameters:

frequency0 (Union[float, Fraction, int]) – The first frequency in Hertz.
frequency1 (Union[float, Fraction, int]) – The second frequency in Hertz.

Returns:

The difference in cents between the first and the second frequency.

Return type:

float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_cents(200, 400)
1200.0

static hertz_to_midi_pitch_number(frequency)[source]§

Converts a frequency in hertz to its respective midi pitch.

Parameters:: frequency (Union[float, Fraction, int]) – The frequency that shall be translated to a midi pitch number.
Returns:: The midi pitch number (potentially a floating point number if the entered frequency isn’t on the grid of the equal divided octave tuning with a = 440 Hertz).
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.hertz_to_midi_pitch_number(440)
69.0
>>> abc.Pitch.hertz_to_midi_pitch_number(440 * 3 / 2)
75.98044999134612

static ratio_to_cents(ratio)[source]§

Converts a frequency ratio to its respective cent value.

Parameters:: ratio (Fraction) – The frequency ratio which cent value shall be calculated.
Return type:: float

Example:

>>> from mutwo.parameters import abc
>>> abc.Pitch.ratio_to_cents(fractions.Fraction(3, 2))
701.9550008653874

resolve_envelope(duration, resolve_envelope_class=None)[source]§

Parameters:

duration (Union[float, Fraction, int]) –
resolve_envelope_class (Optional[type[mutwo.core_events.envelopes.Envelope]]) –

Return type: