mutwo.core_parameters

Abstractions for attributes that can be assigned to Event objects.

Object

Documentation

mutwo.core_parameters.DirectDuration

Simple Duration which is directly initialised by its value.

mutwo.core_parameters.RatioDuration

Duration defined by a ratio (= a fraction).

mutwo.core_parameters.DirectTempo

Simple Tempo that is directly initialised by its tempo.

mutwo.core_parameters.WesternTempo

A tempo useful for western notation.

mutwo.core_parameters.FlexTempo

A flex tempo.
class DirectDuration(beat_count)[source]

Bases: Duration

Simple Duration which is directly initialised by its value.

Example:

>>> from mutwo import core_parameters
>>> # create duration with beat_count = 10
>>> my_duration = core_parameters.DirectDuration(10)
>>> my_duration.beat_count
10.0

Public Data Attributes:

beat_count

Inherited from Duration

direct_comparison_type_tuple

Type

Duration.Type hosts all types that are supported by the duration parser Duration.from_any().

beat_count

Inherited from SingleNumberParameter

direct_comparison_type_tuple

digit_to_round_to_count

Public Methods:

Inherited from Duration

add(other)

subtract(other)

multiply(other)

divide(other)

from_any(object)

Parse any object to Parameter.

value_name

Inherited from Parameter

from_any(object)

Parse any object to Parameter.
Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.
Parameters:

beat_count (float | fractions.Fraction | int | quicktions.Fraction) –

property beat_count: float
class RatioDuration(ratio)[source]

Bases: Duration

Duration defined by a ratio (= a fraction).

Example:

>>> from mutwo import core_parameters
>>> # create duration with duration = 10 beats
>>> d = core_parameters.RatioDuration('2/3')
>>> d
RatioDuration(0.6666666667)
>>> print(d)
R(2/3)
>>> d.ratio
Fraction(2, 3)
>>> d.beat_count
0.6666666667

Public Data Attributes:

ratio

beat_count

Inherited from Duration

direct_comparison_type_tuple

Type

Duration.Type hosts all types that are supported by the duration parser Duration.from_any().

beat_count

Inherited from SingleNumberParameter

direct_comparison_type_tuple

digit_to_round_to_count

Public Methods:

Inherited from Duration

add(other)

subtract(other)

multiply(other)

divide(other)

from_any(object)

Parse any object to Parameter.

value_name

Inherited from Parameter

from_any(object)

Parse any object to Parameter.
Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.
Parameters:

ratio (float | fractions.Fraction | int | quicktions.Fraction | str) –

property beat_count: float
property ratio: Fraction
class DirectTempo(bpm)[source]

Bases: Tempo

Simple Tempo that is directly initialised by its tempo.

Parameters:

  • tempo – Specify a tempo in beats per minute.

  • bpm (float | fractions.Fraction | int | quicktions.Fraction | str) –

Example:

>>> from mutwo import core_parameters
>>> core_parameters.DirectTempo(60)
DirectTempo(60.0)

Public Data Attributes:

bpm

Inherited from Tempo

Type

Tempo.Type hosts all types that are supported by the tempo parser Tempo.from_any().

seconds

How many seconds one beat lasts with current BPM.

bpm

Inherited from SingleNumberParameter

direct_comparison_type_tuple

digit_to_round_to_count

Public Methods:

Inherited from Tempo

from_any(object)

Parse any object to Parameter.

value_name

Inherited from Parameter

from_any(object)

Parse any object to Parameter.
Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.
property bpm: float
class WesternTempo(bpm_range, reference=None, textual_indication=None)[source]

Bases: Tempo

A tempo useful for western notation.

Parameters:

  • bpm_range (ranges.Range.Range | float | fractions.Fraction | int | quicktions.Fraction | str) –

    Specify a tempo range in beats per minute. In western notation tempo is often indicated as a range from the minimal accepted tempo to the fastest accepted tempo. Therefore a WesternTempo is initialized by a range. In internal calculations the minimal (slowest) tempo is used. The tempo in the tempo range is relative as the absolute tempo depends on the reference.

  • reference (float) – The reference with which the tempo is multiplied. In terms of Western notation a reference = 1 equals a 1/4 beat, a reference of 2 equals a 1/2 beat, etc. Default to 1.

  • textual_indication (Optional[str]) – Sometimes it is desired to specify an extra text indication how fast or slow the music should be (for instance “Adagio” in Western music). Default to None.

Example:

>>> from mutwo import core_parameters
>>> core_parameters.WesternTempo(60, reference=2)
WesternTempo(120.0)

Public Data Attributes:

bpm

bpm_range

A range from the slowest to the fastest accepted tempo.

reference

The reference with which the tempo is multiplied.
Inherited from Tempo

Type

Tempo.Type hosts all types that are supported by the tempo parser Tempo.from_any().

seconds

How many seconds one beat lasts with current BPM.

bpm

Inherited from SingleNumberParameter

direct_comparison_type_tuple

digit_to_round_to_count

Public Methods:

Inherited from Tempo

from_any(object)

Parse any object to Parameter.

value_name

Inherited from Parameter

from_any(object)

Parse any object to Parameter.
Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.
property bpm: float
property bpm_range: Range

A range from the slowest to the fastest accepted tempo.

In internal calculations the minimal (slowest) tempo is used. The tempo in the tempo range is relative as the absolute tempo depends on the reference.

property reference: Fraction

The reference with which the tempo is multiplied.

In terms of Western notation a reference = 1 equals a 1/4 beat, a reference of 2 equals a 1/2 beat, etc. Default to 1.

class FlexTempo(event_iterable_or_point_sequence=[], *args, **kwargs)[source]

Bases: Tempo, FlexParameterMixin

A flex tempo.

Public Data Attributes:

bpm

Inherited from Tempo

Type

Tempo.Type hosts all types that are supported by the tempo parser Tempo.from_any().

seconds

How many seconds one beat lasts with current BPM.

bpm

Inherited from SingleNumberParameter

direct_comparison_type_tuple

digit_to_round_to_count

Inherited from FlexParameterMixin

parameter_name

default_parameter

Inherited from Envelope

Value

Parameter

CurveShape

Point

parameter_tuple

Get parameter for each event inside Envelope.

value_tuple

Get value for each event inside Envelope.

curve_shape_tuple

Get curve_shape for each event inside Envelope.

is_static

Return True if Envelope only has one static value.
Inherited from Consecution

duration

The duration of an event.

absolute_time_tuple

Return start time as core_parameters.abc.Duration for each event.

absolute_time_in_floats_tuple

Return start time as float for each event.

start_and_end_time_per_event

Return start and end time for each event.
Inherited from Compound

duration

The duration of an event.
Inherited from Event

duration

The duration of an event.

tempo

The tempo of an event.

Public Methods:

parameter_name

default_parameter

Inherited from Tempo

from_any(object)

Parse any object to Parameter.

value_name

Inherited from Parameter

from_any(object)

Parse any object to Parameter.
Inherited from FlexParameterMixin

from_parameter(parameter)

value_to_parameter(value)

Convert from 'value' to 'parameter'.

parameter_to_value(parameter)

Convert from 'parameter' to 'value'.

apply_parameter_on_event(event, parameter)

Apply 'parameter' on given event

event_to_parameter(event)

Fetch 'parameter' from event.
Inherited from Envelope

event_to_parameter(event)

Fetch 'parameter' from event.

event_to_curve_shape(event)

Fetch 'curve_shape' from event.

parameter_to_value(parameter)

Convert from 'parameter' to 'value'.

value_to_parameter(value)

Convert from 'value' to 'parameter'.

apply_parameter_on_event(event, parameter)

Apply 'parameter' on given event

apply_curve_shape_on_event(event, curve_shape)

Apply 'curve_shape' on given event

initialise_default_event_class(duration)

Create new event object from event type.

value_at(absolute_time)

Get value at absolute_time.

parameter_at(absolute_time)

Get parameter at absolute_time.

curve_shape_at(absolute_time)

Get curve_shape at absolute_time.

point_at(absolute_time)

Get point at absolute_time.

sample_at(absolute_time[, append_duration])

Discretize envelope at given time

time_range_to_point_tuple(time_range)

Return all control points in given time range.

integrate_interval(start, end)

Integrate envelope above given interval.

get_average_value([start, end])

Find average value in given interval.

get_average_parameter([start, end])

Find average parameter in given interval.

cut_out(start, end)

Time-based slicing of the respective event.

cut_off(start, end)

Time-based deletion / shortening of the respective event.

extend_until(duration[, ...])

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

split_at(*absolute_time[, ...])

Split event into n events at absolute_time.
Inherited from Consecution

get_event_index_at(absolute_time)

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

get_event_at(absolute_time)

Get event which is active at the passed absolute_time.

cut_out(start, end)

Time-based slicing of the respective event.

cut_off(start, end)

Time-based deletion / shortening of the respective event.

squash_in(start, event_to_squash_in)

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

slide_in(start, event_to_slide_in)

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

split_child_at(absolute_time)

Split child event in two events at absolute_time.

split_at(*absolute_time[, ...])

Split event into n events at absolute_time.

extend_until(duration[, ...])

Prolong event until at least duration by appending an empty event.
Inherited from Compound

destructive_copy()

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

empty_copy()

Make a copy of the Compound without any child events.

get_event_from_index_sequence(index_sequence)

Get nested Event from a sequence of indices.

get_parameter(parameter_name[, flat, ...])

Return event attribute with the entered name.

remove_by(condition)

Condition-based deletion of child events.

tie_by(condition[, process_surviving_event, ...])

Condition-based deletion of neighboring child events.

metrize()

Apply tempo of event on itself

squash_in(start, event_to_squash_in)

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

slide_in(start, event_to_slide_in)

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

split_child_at(absolute_time)

Split child event in two events at absolute_time.

extend_until(duration[, ...])

Prolong event until at least duration by appending an empty event.
Inherited from Event

destructive_copy()

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

set(attribute_name, value)

Set an attribute of the object to a specific value

get_parameter(parameter_name[, flat, ...])

Return event attribute with the entered name.

set_parameter(parameter_name, object_or_function)

Sets parameter to new value for all children events.

mutate_parameter(parameter_name, function)

Mutate parameter with a function.

reset_tempo()

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

metrize()

Apply tempo of event on itself

cut_out(start, end)

Time-based slicing of the respective event.

cut_off(start, end)

Time-based deletion / shortening of the respective event.

split_at(*absolute_time[, ...])

Split event into n events at absolute_time.
Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.
Inherited from list

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

append(object, /)

Append object to the end of the list.

insert(index, object, /)

Insert object before index.

extend(iterable, /)

Extend list by appending elements from the iterable.

pop([index])

Remove and return item at index (default last).

remove(value, /)

Remove first occurrence of value.

index(value[, start, stop])

Return first index of value.

count(value, /)

Return number of occurrences of value.

reverse()

Reverse IN PLACE.

sort(*[, key, reverse])

Sort the list in ascending order and return None.
property bpm
class property default_parameter: Tempo

Simple Tempo that is directly initialised by its tempo.

Parameters:

tempo –

Specify a tempo in beats per minute.

Example:

>>> from mutwo import core_parameters
>>> core_parameters.DirectTempo(60)
DirectTempo(60.0)
class property parameter_name: str

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

mutwo.core_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 Duration[source]

Bases: SingleNumberParameter

Abstract base class for any duration.

If the user wants to define a Duration class, the abstract property beat_count has to be overridden.

The duration of mutwo events are not related to a clear physical unit as for instance seconds. The reason for this decision is to simplify musical usage.

add(other)[source]
Parameters:

other (mutwo.core_parameters.abc.Duration | float | fractions.Fraction | int | quicktions.Fraction) –

Return type:

Duration

divide(other)[source]
Parameters:

other (mutwo.core_parameters.abc.Duration | float | fractions.Fraction | int | quicktions.Fraction) –

Return type:

Duration

classmethod from_any(object)[source]

Parse any object to Parameter.

Parameters:

object (Union[float, Fraction, int, Fraction, str, Duration]) – Object that is parsed to the parameter.

Raises:

core_utilities.CannotParseError in case the object can’t be parsed to the parameter type.

Return type:

T

This method is useful for allowing syntactic sugar.

multiply(other)[source]
Parameters:

other (mutwo.core_parameters.abc.Duration | float | fractions.Fraction | int | quicktions.Fraction) –

Return type:

Duration

subtract(other)[source]
Parameters:

other (mutwo.core_parameters.abc.Duration | float | fractions.Fraction | int | quicktions.Fraction) –

Return type:

Duration

Type

Duration.Type hosts all types that are supported by the duration parser Duration.from_any().

alias of Union[float, Fraction, int, Fraction, str, Duration]

abstract property beat_count: float
direct_comparison_type_tuple = (<class 'float'>, <class 'int'>, <class 'quicktions.Fraction'>, <class 'fractions.Fraction'>)
class property value_name

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

class Parameter[source]

Bases: MutwoObject, ABC

A Parameter is the base class for all mutwo parameters

It can be useful as a type hint for any code where a parameter object is expected. This isn’t necessarily at many places, as mostly any object can be assigned as a parameter to an event.

classmethod from_any(object)[source]

Parse any object to Parameter.

Parameters:

object – Object that is parsed to the parameter.

Raises:

core_utilities.CannotParseError in case the object can’t be parsed to the parameter type.

Return type:

T

This method is useful for allowing syntactic sugar.

class SingleNumberParameter[source]

Bases: SingleValueParameter

Abstract base class for all parameters which are defined by one number.

Classes which inherit from this base class have to override the same methods and properties as one have to override when inheriting from SingleValueParameter.

Furthermore the property digit_to_round_to_count can be overridden. This should return an integer or None. If it returns an integer it will first round two numbers before comparing them with the == or < or <= or > or >= operators. The default implementation always returns `None.

Example:

>>> from mutwo import core_parameters
>>> class Speed(
...     core_parameters.abc.SingleNumberParameter,
...     value_name="meter_per_seconds",
...     value_return_type=float
... ):
...     def __init__(self, meter_per_seconds: float):
...         self._meter_per_seconds = meter_per_seconds
...     @property
...     def meter_per_seconds(self) -> float:
...         return self._meter_per_seconds
>>> light_speed = Speed(299792458)
>>> sound_speed = Speed(343)
>>> light_speed > sound_speed
True
property digit_to_round_to_count: Optional[int]
direct_comparison_type_tuple = ()
class SingleValueParameter[source]

Bases: Parameter

Abstract base class for all parameters which are defined by one value.

Classes which inherit from this base class have to provide an additional keyword argument value_name. Furthermore they can provide the optional keyword argument value_return_type.

Example:

>>> from mutwo import core_parameters
>>> class Color(
...     core_parameters.abc.SingleValueParameter,
...     value_name="color",
...     value_return_type=str
... ):
...     def __init__(self, color: str):
...         self._color = color
...     @property
...     def color(self) -> str:
...         return self._color
>>> red = Color('red')
>>> red.color
'red'
>>> orange = Color('orange')
>>> red2 = Color('red')
>>> red == orange
False
>>> red == red2
True
class Tempo[source]

Bases: SingleNumberParameter

Represent the active tempo at a specific moment in time.

If the user wants to define a Tempo class, the abstract property bpm needs to be overridden. BPM is an abbreviation for ‘beats per minute’ and the unit of the parameter tempo, see more information at this wikipedia article.

classmethod from_any(object)[source]

Parse any object to Parameter.

Parameters:

object (Union[Tempo, float, Fraction, int, Fraction]) – Object that is parsed to the parameter.

Raises:

core_utilities.CannotParseError in case the object can’t be parsed to the parameter type.

Return type:

T

This method is useful for allowing syntactic sugar.

Type

Tempo.Type hosts all types that are supported by the tempo parser Tempo.from_any().

alias of Union[Tempo, float, Fraction, int, Fraction]

abstract property bpm: value_return_type
property seconds: float

How many seconds one beat lasts with current BPM.

class property value_name

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

mutwo.core_parameters.configurations

Configurations which are shared for all parameter classes in mutwo.core_parameters.

DEFAULT_REFERENCE: Fraction = Fraction(1, 4)

The default value for the ‘reference’ parameter of mutwo.core_parameters.WesternTempo. By default it is set to 1/4 because it’s most common to think that the tempo in BPM refers to a 1/4 note (so that tempo = 60 BPM means that a 1/4 beat takes one second). Therefore a tempo of ‘60’ in WesternTempo is by default 4 times slower than a tempo of ‘60’ in DirectTempo.

ROUND_DURATION_TO_N_DIGITS = 10

Set floating point precision for the duration property of all Duration classes in the mutwo.core_parameters module.

When returning the duration property all mentioned events should round their actual duration. This behaviour has been added with version 0.28.1 to avoid floating point rounding errors which could occur in all duration related methods of the different event classes (as it can happen in for instance the mutwo.core_events.abc.Compound.squash_in() method or the mutwo.core_events.abc.Event.cut_off() method).