mutwo.core_parameters¶
Abstractions for attributes that can be assigned to Event objects.
Object |
Documentation |
---|---|
Simple Duration which is directly initialised by its value. |
|
Duration defined by a ratio (= a fraction). |
|
Simple Tempo that is directly initialised by its tempo. |
|
A tempo useful for western notation. |
|
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
Duration.Type hosts all types that are supported by the duration parser
Duration.from_any()
.Public Methods:
Inherited from
Duration
add
(other)subtract
(other)multiply
(other)divide
(other)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
Duration.Type hosts all types that are supported by the duration parser
Duration.from_any()
.Public Methods:
Inherited from
Duration
add
(other)subtract
(other)multiply
(other)divide
(other)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
Tempo.Type hosts all types that are supported by the tempo parser
Tempo.from_any()
.How many seconds one beat lasts with current BPM.
Public Methods:
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 thereference
.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
Tempo.Type hosts all types that are supported by the tempo parser
Tempo.from_any()
.How many seconds one beat lasts with current BPM.
Public Methods:
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
Tempo.Type hosts all types that are supported by the tempo parser
Tempo.from_any()
.How many seconds one beat lasts with current BPM.
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.
Public Methods:
parameter_name
default_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
Adapted deep copy method that returns a new object for every leaf.
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
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.
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
ofmutwo
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:
- divide(other)[source]¶
- Parameters:
other (mutwo.core_parameters.abc.Duration | float | fractions.Fraction | int | quicktions.Fraction) –
- Return type:
- 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:
- subtract(other)[source]¶
- Parameters:
other (mutwo.core_parameters.abc.Duration | float | fractions.Fraction | int | quicktions.Fraction) –
- Return type:
- 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.
- 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’ inWesternTempo
is by default 4 times slower than a tempo of ‘60’ inDirectTempo
.
- ROUND_DURATION_TO_N_DIGITS = 10¶
Set floating point precision for the duration property of all
Duration
classes in themutwo.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 themutwo.core_events.abc.Event.cut_off()
method).