mutwo.music_parameters§
Object |
Documentation |
---|---|
A tuning comma. |
|
Collection of tuning commas. |
|
Lyric which is directly initialised by its phonetic representation |
|
Lyric based on a natural language. |
|
Syllable based on a natural language. |
|
Simple interval class which gets directly assigned by its cents value |
|
Model intervals by using European music theory based representations |
|
A simple pitch class that gets directly initialised by its frequency. |
|
Pitch that is defined by a frequency ratio and a reference pitch. |
|
Abstract representation of a harmonic spectrum partial. |
|
Pitch that is tuned to an Equal divided octave tuning system. |
|
Pitch with a traditional Western nomenclature. |
|
Pitch that is defined by its midi pitch number. |
|
|
|
A simple volume class that gets directly initialised by its amplitude. |
|
A simple volume class that gets directly initialised by decibel. |
|
Volume with a traditional Western nomenclature. |
|
BarLine(abbreviation: Optional[str] = None) |
|
Clef(name: Optional[str] = None) |
|
Ottava(n_octaves: Optional[int] = 0) |
|
MarginMarkup(content: Optional[str] = None, context: Optional[str] = ‘Staff’) |
|
Markup(content: Optional[str] = None, direction: Optional[str] = None) |
|
RehearsalMark(markup: Optional[str] = None) |
|
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>) |
|
Tremolo(n_flags: Optional[int] = None) |
|
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) |
|
Arpeggio(direction: Optional[Literal[‘up’, ‘down’]] = None) |
|
Pedal(pedal_type: Optional[Literal[‘sustain’, ‘sostenuto’, ‘corda’]] = None, pedal_activity: Optional[bool] = True) |
|
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) |
|
Ornamentation(direction: Optional[Literal[‘up’, ‘down’]] = None, n_times: int = 1) |
|
BendAfter(bend_amount: Optional[float] = None, minimum_length: Optional[float] = 3, thickness: Optional[float] = 3) |
|
ArtificalHarmonic(n_semitones: Optional[int] = None) |
|
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) |
|
Fermata(fermata_type: Optional[Literal[‘shortfermata’, ‘fermata’, ‘longfermata’, ‘verylongfermata’]] = None) |
|
Hairpin(symbol: Optional[Literal[‘<’, ‘>’, ‘<>’, ‘!’]] = None, niente: bool = False) |
|
Trill(pitch: Optional[mutwo.music_parameters.abc.Pitch] = None) |
|
WoodwindFingering(cc: Optional[Tuple[str, …]] = None, left_hand: Optional[Tuple[str, …]] = None, right_hand: Optional[Tuple[str, …]] = None, instrument: str = ‘clarinet’) |
|
Cue for electronics etc. |
|
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>) |
- class OctaveAmbitus(minima_pitch, maxima_pitch)[source]§
Public Data Attributes:
Inherited from
PitchAmbitus
Public Methods:
pitch_to_period
(pitch)Inherited from
PitchAmbitus
__init__
(minima_pitch, maxima_pitch)pitch_to_period
(pitch)__repr__
()Return repr(self).
__str__
()Return str(self).
__iter__
()__getitem__
(index)get_pitch_variant_tuple
(pitch[, period])Find all pitch variants (in all octaves) of the given pitch
filter_pitch_sequence
(pitch_to_filter_sequence)Filter all pitches in a sequence which aren't inside the ambitus.
Private Data Attributes:
_abc_impl
Inherited from
PitchAmbitus
_abc_impl
Inherited from
ABC
_abc_impl
- filter_pitch_sequence(pitch_to_filter_sequence)§
Filter all pitches in a sequence which aren’t inside the ambitus.
- Parameters:
pitch_to_filter_sequence (Sequence[Pitch]) – A sequence with pitches which shall be filtered.
- Return type:
tuple[mutwo.music_parameters.abc.Pitch, …]
Example:
>>> from mutwo import music_parameters >>> ambitus0 = music_parameters.OctaveAmbitus( music_parameters.JustIntonationPitch('1/2'), music_parameters.JustIntonationPitch('2/1'), ) >>> ambitus0.filter_pitch_sequence( [ music_parameters.JustIntonationPitch("3/8"), music_parameters.JustIntonationPitch("3/4"), music_parameters.JustIntonationPitch("3/2"), music_parameters.JustIntonationPitch("3/1"), ] ) (JustIntonationPitch('3/4'), JustIntonationPitch('3/2'))
- get_pitch_variant_tuple(pitch, period=None)§
Find all pitch variants (in all octaves) of the given pitch
- Parameters:
pitch (Pitch) – The pitch which variants shall be found.
period (Optional[PitchInterval]) – The repeating period (usually an octave). If the period is set to None the function will fallback to them objects method :method:`pitch_to_period`. Default to None.
- Return type:
tuple[mutwo.music_parameters.abc.Pitch, …]
- property border_tuple: tuple[mutwo.music_parameters.abc.Pitch, mutwo.music_parameters.abc.Pitch]§
- property range: PitchInterval§
- class Comma(ratio)[source]§
A tuning comma.
Public Data Attributes:
Public Methods:
__init__
(ratio)__repr__
()Return repr(self).
- Parameters:
ratio (Fraction) –
- property ratio: Fraction§
- class CommaCompound(prime_to_exponent_dict, prime_to_comma_dict)[source]§
Collection of tuning commas.
Public Data Attributes:
Public Methods:
__init__
(prime_to_exponent_dict, ...)__repr__
()Return repr(self).
__len__
()__iter__
()Inherited from
Iterable
__iter__
()__subclasshook__
(C)Abstract classes can override this to customize issubclass().
__class_getitem__
Inherited from
Generic
__class_getitem__
__init_subclass__
(*args, **kwargs)This method is called when a class is subclassed.
Private Data Attributes:
_abc_impl
Inherited from
Iterable
_abc_impl
Inherited from
Generic
_is_protocol
- Parameters:
prime_to_exponent_dict (dict[int, int]) –
prime_to_comma_dict (Optional[dict[int, mutwo.music_parameters.commas.Comma]]) –
- property prime_to_exponent_dict: dict[int, int]§
- property ratio: Fraction§
- class DirectLyric(phonetic_representation)[source]§
Lyric which is directly initialised by its phonetic representation
- Parameters:
phonetic_representation (str) – The phonetic representation of the text.
In this class the written_representation is simply equal to phonetic_representation.
Public Data Attributes:
Get text as it would be written in natural language
Inherited from
Lyric
Get text as it would be written in natural language
Public Methods:
__init__
(phonetic_representation)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
Lyric
_abc_impl
Inherited from
SingleValueParameter
_abc_impl
Inherited from
ABC
_abc_impl
- property phonetic_representation: str§
- property value_name§
- property written_representation: str§
Get text as it would be written in natural language
- class LanguageBasedLyric(written_representation, language_code=None)[source]§
Lyric based on a natural language.
- Parameters:
written_representation (str) – The text.
language_code (Optional[str]) – The code for the language of the text. If this is None the constant mutwo.music_parameters.configurations.DEFAULT_LANGUAGE_CODE will be used. Default to None.
Public Data Attributes:
Get text as it would be written in natural language
Inherited from
Lyric
Get text as it would be written in natural language
Public Methods:
__init__
(written_representation[, language_code])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
Lyric
_abc_impl
Inherited from
SingleValueParameter
_abc_impl
Inherited from
ABC
_abc_impl
- property language_code: str§
- property phonetic_representation: str§
- property value_name§
- property written_representation: str§
Get text as it would be written in natural language
- class LanguageBasedSyllable(is_last_syllable, *args, **kwargs)[source]§
Syllable based on a natural language.
- Parameters:
is_last_syllable (bool) – True if it is the last syllable of a word and False if it isn’t the last syllable
written_representation (str) – The text.
language_code (Optional[str]) – The code for the language of the text. If this is None the constant mutwo.music_parameters.configurations.DEFAULT_LANGUAGE_CODE will be used. Default to None.
Warning:
It is a known bug that a split word (syllables) and the word itself will return different values for
phonetic_representation
. For instance:>>> LanguageBasedLyric('hallo').phonetic_representation "halo:" >>> # And now splitted to syllables: >>> LanguageBasedSyllable('hal').phonetic_representation "hA:l" >>> LanguageBasedSyllable('lo').phonetic_representation "lo:"
Public Data Attributes:
Inherited from
LanguageBasedLyric
Get text as it would be written in natural language
Inherited from
Lyric
Get text as it would be written in natural language
Public Methods:
__init__
(is_last_syllable, *args, **kwargs)Inherited from
Syllable
__init__
(is_last_syllable, *args, **kwargs)Inherited from
LanguageBasedLyric
__init__
(is_last_syllable, *args, **kwargs)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
Syllable
_abc_impl
Inherited from
LanguageBasedLyric
_abc_impl
Inherited from
Lyric
_abc_impl
Inherited from
SingleValueParameter
_abc_impl
Inherited from
ABC
_abc_impl
- property language_code: str§
- property phonetic_representation: str§
- property value_name§
- property written_representation: str§
Get text as it would be written in natural language
- class DirectPitchInterval(interval)[source]§
Simple interval class which gets directly assigned by its cents value
- Parameters:
interval (float) – Defines how big or small the interval is (in cents).
Example:
>>> from mutwo import music_parameters >>> rising_octave = music_parameters.DirectPitchInterval(1200) >>> falling_minor_third = music_parameters.DirectPitchInterval(-300)
Public Data Attributes:
Inherited from
PitchInterval
Inherited from
SingleNumberParameter
Public Methods:
__init__
(interval)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
PitchInterval
_abc_impl
Inherited from
SingleNumberParameter
_abc_impl
Inherited from
SingleValueParameter
_abc_impl
Inherited from
ABC
_abc_impl
- property digit_to_round_to_count: Optional[int]§
- direct_comparison_type_tuple = ()§
- property interval: float§
- property value_name§
- class WesternPitchInterval(interval_name_or_semitone_count='p1')[source]§
Model intervals by using European music theory based representations
- Parameters:
interval_name_or_semitone_count (Union[str, core_constants.Real]) – Can be either an interval name (a string) or a number for semitones. When using an interval name is should have the form: QUALITY-IS_FALLING-TYPE, e.g. for having a rising perfect fourth (where ‘fourth’ is the type and ‘perfect’ the quality) you can write “p4”. For a falling perfect fourth it would be “p-4”. The interval names are equal to the specification used in the python library music21. Please also consult the specification of the quality abbreviations at
mutwo.music_parameters.configurations.WESTERN_PITCH_INTERVAL_QUALITY_NAME_TO_ABBREVIATION_DICT
and the specification of the is-interval-falling indicatormutwo.music_parameters.configurations.FALLING_WESTERN_PITCH_INTERVAL_INDICATOR
. Both can be changed by the user. Default to ‘p1’.
This class is particularly useful in combination with
mutwo.music_parameters.WesternPitch
.Disclaimer:
Although
mutwo.music_parameters.WesternPitch
does support microtones,WesternPitchInterval
does not.Example:
>>> from mutwo import music_parameters >>> perfect_fifth = music_parameters.WesternPitchInterval('p5') >>> falling_major_third = music_parameters.WesternPitchInterval('M-3') >>> minor_third = music_parameters.WesternPitchInterval('m3') >>> falling_octave = music_parameters.WesternPitchInterval(-12) >>> augmented_octave = music_parameters.WesternPitchInterval('A8') >>> very_diminished_sixth = music_parameters.WesternPitchInterval('dddd6')
Public Data Attributes:
Return True if the interval is upwards and False if it falls
Parsed the interval_quality abbreviation to their full names.
The base interval type (e.g.
The abbreviation of its quality (e.g.
Get cent deviation defined by the interval type.
Get cent deviation defined by the interval quality.
How many diatonic pitch classes have to be moved
Full interval name
Return True if interval is perfect and otherwise False.
Return True if interval is imperfect and otherwise False.
True if interval could be written in a simpler way, False otherwise.
Inherited from
PitchInterval
Inherited from
SingleNumberParameter
Public Methods:
__init__
([interval_name_or_semitone_count])is_interval_type_perfect
(interval_type)is_interval_type_imperfect
(interval_type)__repr__
()Return repr(self).
__str__
()Return str(self).
inverse_direction
([mutate])Makes falling interval to rising and vice versa.
inverse
()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
PitchInterval
_abc_impl
Inherited from
SingleNumberParameter
_abc_impl
Inherited from
SingleValueParameter
_abc_impl
Inherited from
ABC
_abc_impl
- inverse_direction(mutate=False)[source]§
Makes falling interval to rising and vice versa.
Example:
>>> from mutwo import music_parameters >>> music_parameters.WesternPitchInterval('m3').inverse_direction() WesternPitchInterval('m-3')
- Parameters:
mutate (bool) –
- Return type:
- static is_interval_type_imperfect(interval_type)[source]§
- Parameters:
interval_type (str) –
- Return type:
bool
- static is_interval_type_perfect(interval_type)[source]§
- Parameters:
interval_type (str) –
- Return type:
bool
- property can_be_simplified: bool§
True if interval could be written in a simpler way, False otherwise.
- property diatonic_pitch_class_count: int§
How many diatonic pitch classes have to be moved
- property digit_to_round_to_count: Optional[int]§
- direct_comparison_type_tuple = ()§
- property interval: float§
- property interval_quality: str§
The abbreviation of its quality (e.g. augmented, perfect, …).
- property interval_quality_cent_deviation: float§
Get cent deviation defined by the interval quality.
- property interval_quality_tuple: tuple[str, ...]§
Parsed the interval_quality abbreviation to their full names.
- property interval_type: str§
The base interval type (e.g. octave, prime, second, …).
- property interval_type_base_type: str§
- property interval_type_cent_deviation: float§
Get cent deviation defined by the interval type.
- property is_imperfect_interval: bool§
Return True if interval is imperfect and otherwise False.
With ‘imperfect’ all intervals are included which can have the interval qualities ‘augmented’, ‘diminished’, ‘minor’ and ‘major’.
This excludes intervals as prime, fourth, … which have the ‘perfect’ quality.
- property is_interval_rising: bool§
Return True if the interval is upwards and False if it falls
- property is_perfect_interval: bool§
Return True if interval is perfect and otherwise False.
With ‘perfect’ all intervals are included which can have the interval qualities ‘augmented’, ‘diminished’ and ‘perfect’.
This excludes intervals as sixth, thirds, … which have ‘minor’ and ‘major’ qualities.
- property name: str§
Full interval name
- property semitone_count: float§
- property value_name§
- class DirectPitch(frequency, *args, **kwargs)[source]§
A simple pitch class that gets directly initialised by its frequency.
- Parameters:
frequency (core_constants.Real) – The frequency of the
DirectPitch
object.
May be used when a converter class needs a pitch object, but there is no need or desire for a complex abstraction of the respective pitch (that classes like
JustIntonationPitch
orWesternPitch
offer).Example:
>>> from mutwo.music_parameters import pitches >>> my_pitch = pitches.DirectPitch(440)
Public Data Attributes:
The frequency of the pitch.
Inherited from
Pitch
The midi pitch number (from 0 to 127) of the pitch.
The frequency of the pitch.
Inherited from
SingleNumberParameter
Inherited from
ParameterWithEnvelope
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 pitchInherited 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.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
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:
- 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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- clear()§
Remove all items from list.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
Example:
>>> from mutwo import core_events >>> simultaneous_event = core_events.SimultaneousEvent( [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)] ) >>> simultaneous_event.filter(lambda event: event.duration > 2) >>> simultaneous_event SimultaneousEvent([SimpleEvent(duration = 3)])
- get_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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- 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:
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:
- 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 afractions.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 ratio4/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:
Return ascending list of primes, until the highest contained Prime.
Return all occurring prime numbers of a JustIntonationPitch object.
Return the JustIntonationPitch transformed to a Ratio.
Return the numerator of a JustIntonationPitch - object.
Return the denominator of
JustIntonationPitch
.Return factorised / decomposed version of itsef.
Commas of JustIntonationPitch.
Return the tonality (bool) of a JustIntonationPitch - object.
Return the nth - harmonic / subharmonic the pitch may represent.
Return the 'gradus suavitatis' of euler.
Calculate the barlow-harmonicity of an interval.
Calculate a simplified barlow-harmonicity of an interval.
Calculate Tenneys harmonic distance of an interval
Inherited from
Pitch
The midi pitch number (from 0 to 127) of the pitch.
Inherited from
PitchInterval
Inherited from
SingleNumberParameter
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 pitchregister
(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 pitchInherited 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.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
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:
- 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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- clear()§
Remove all items from list.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
Example:
>>> from mutwo import core_events >>> simultaneous_event = core_events.SimultaneousEvent( [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)] ) >>> simultaneous_event.filter(lambda event: event.duration > 2) >>> simultaneous_event SimultaneousEvent([SimpleEvent(duration = 3)])
- get_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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
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 toFalse
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:
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:
- normalize(prime=2)[source]§
Normalize
JustIntonationPitch
.- Parameters:
prime (int) – The normalization period (2 for octave, 3 for twelfth, …). Default to 2.
- Return type:
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:
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 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 andFalse
for a (theoretical) undertone. Default toTrue
.
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:
Defines in how many different pitch classes one octave get divided.
The referential concert pitch for the respective pitch object.
The pitch class of the referential concert pitch.
The pitch class of the pitch.
The factor with which to multiply a frequency to reach the next pitch.
This property describes how many cents are between two adjacent pitches.
Inherited from
Pitch
The midi pitch number (from 0 to 127) of the pitch.
Inherited from
SingleNumberParameter
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 pitchInherited 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.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
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:
- 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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- clear()§
Remove all items from list.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
Example:
>>> from mutwo import core_events >>> simultaneous_event = core_events.SimultaneousEvent( [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)] ) >>> simultaneous_event.filter(lambda event: event.duration > 2) >>> simultaneous_event SimultaneousEvent([SimpleEvent(duration = 3)])
- get_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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- 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:
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:
- 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 (seemutwo.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:
The name of the pitch in Western nomenclature.
The name of the pitch class in Western nomenclature.
The pitch class of the pitch.
Only get the diatonic part of the pitch name
Only get accidental part of pitch name
Return True if accidental isn't on chromatic grid.
Return pitches with equal frequency but different name.
Inherited from
EqualDividedOctavePitch
Defines in how many different pitch classes one octave get divided.
The referential concert pitch for the respective pitch object.
The pitch class of the referential concert pitch.
The pitch class of the pitch.
The factor with which to multiply a frequency to reach the next pitch.
This property describes how many cents are between two adjacent pitches.
Inherited from
Pitch
The midi pitch number (from 0 to 127) of the pitch.
Inherited from
SingleNumberParameter
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 pitchInherited 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 pitchInherited 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.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
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:
- 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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- clear()§
Remove all items from list.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
Example:
>>> from mutwo import core_events >>> simultaneous_event = core_events.SimultaneousEvent( [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)] ) >>> simultaneous_event.filter(lambda event: event.duration > 2) >>> simultaneous_event SimultaneousEvent([SimpleEvent(duration = 3)])
- get_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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- 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:
- 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:
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:
- property accidental_name: str§
Only get accidental part of pitch name
- 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:
The midi pitch number (from 0 to 127) of the pitch.
Inherited from
Pitch
The midi pitch number (from 0 to 127) of the pitch.
Inherited from
SingleNumberParameter
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 pitchInherited 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.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
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:
- 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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- clear()§
Remove all items from list.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
Example:
>>> from mutwo import core_events >>> simultaneous_event = core_events.SimultaneousEvent( [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)] ) >>> simultaneous_event.filter(lambda event: event.duration > 2) >>> simultaneous_event SimultaneousEvent([SimpleEvent(duration = 3)])
- get_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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- 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:
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:
- 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
Return ascending list of primes, until the highest contained Prime.
Return all occurring prime numbers of a JustIntonationPitch object.
Return the JustIntonationPitch transformed to a Ratio.
Return the numerator of a JustIntonationPitch - object.
Return the denominator of
JustIntonationPitch
.Return factorised / decomposed version of itsef.
Commas of JustIntonationPitch.
Return the tonality (bool) of a JustIntonationPitch - object.
Return the nth - harmonic / subharmonic the pitch may represent.
Return the 'gradus suavitatis' of euler.
Calculate the barlow-harmonicity of an interval.
Calculate a simplified barlow-harmonicity of an interval.
Calculate Tenneys harmonic distance of an interval
Inherited from
Pitch
The midi pitch number (from 0 to 127) of the pitch.
Inherited from
PitchInterval
Inherited from
SingleNumberParameter
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 pitchregister
(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 pitchInherited 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.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
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:
- 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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- clear()§
Remove all items from list.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
Example:
>>> from mutwo import core_events >>> simultaneous_event = core_events.SimultaneousEvent( [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)] ) >>> simultaneous_event.filter(lambda event: event.duration > 2) >>> simultaneous_event SimultaneousEvent([SimpleEvent(duration = 3)])
- get_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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
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 toFalse
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:
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:
- normalize(prime=2)§
Normalize
JustIntonationPitch
.- Parameters:
prime (int) – The normalization period (2 for octave, 3 for twelfth, …). Default to 2.
- Return type:
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:
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 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:
Inherited from
Volume
The decibel of the volume (from -120 to 0)
The velocity of the volume (from 0 to 127).
Inherited from
SingleNumberParameter
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:
The decibel of the volume (from -120 to 0)
Inherited from
Volume
The decibel of the volume (from -120 to 0)
The velocity of the volume (from 0 to 127).
Inherited from
SingleNumberParameter
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:
The western nomenclature name for dynamic.
The decibel of the volume (from -120 to 0)
Inherited from
Volume
The decibel of the volume (from -120 to 0)
The velocity of the volume (from 0 to 127).
Inherited from
SingleNumberParameter
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:
>>> 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:
>>> 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:
Inherited from
NotationIndicator
Inherited from
Indicator
Public Methods:
__init__
([abbreviation])__repr__
()Return repr(self).
__eq__
(other)Return self==value.
Inherited from
Indicator
__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:
Inherited from
NotationIndicator
Inherited from
Indicator
Public Methods:
__init__
([name])__repr__
()Return repr(self).
__eq__
(other)Return self==value.
Inherited from
Indicator
__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:
Inherited from
NotationIndicator
Inherited from
Indicator
Public Methods:
__init__
([n_octaves])__repr__
()Return repr(self).
__eq__
(other)Return self==value.
Inherited from
Indicator
__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:
Inherited from
NotationIndicator
Inherited from
Indicator
Public Methods:
__init__
([content, context])__repr__
()Return repr(self).
__eq__
(other)Return self==value.
Inherited from
Indicator
__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:
Inherited from
NotationIndicator
Inherited from
Indicator
Public Methods:
__init__
([content, direction])__repr__
()Return repr(self).
__eq__
(other)Return self==value.
Inherited from
Indicator
__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:
Inherited from
NotationIndicator
Inherited from
Indicator
Public Methods:
__init__
([markup])__repr__
()Return repr(self).
__eq__
(other)Return self==value.
Inherited from
Indicator
__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
__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]
- margin_markup: MarginMarkup§
- rehearsal_mark: RehearsalMark§
- class Tremolo(n_flags: Optional[int] = None)[source]§
Public Data Attributes:
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
__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:
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
__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:
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
__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:
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
__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:
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
__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:
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
__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:
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
__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:
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
__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:
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
__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:
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
__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:
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
__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:
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
__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§
- 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:
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
__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:
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
__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
__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]
- articulation: Articulation§
- artifical_harmonic: ArtificalHarmonic§
- bartok_pizzicato: PlayingIndicator§
- breath_mark: PlayingIndicator§
- duration_line_dashed: PlayingIndicator§
- duration_line_triller: PlayingIndicator§
- glissando: PlayingIndicator§
- laissez_vibrer: PlayingIndicator§
- natural_harmonic: PlayingIndicator§
- ornamentation: Ornamentation§
- prall: PlayingIndicator§
- precise_natural_harmonic: PreciseNaturalHarmonic§
- string_contact_point: StringContactPoint§
- tie: PlayingIndicator§
- 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) –
- property is_active: bool§
- class ImplicitPlayingIndicator[source]§
- get_arguments_dict()§
- Return type:
dict[str, Any]
- property is_active: bool§
- class IndicatorCollection[source]§
- 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
andwritten_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 anadd()
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.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
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:
- 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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
- clear()§
Remove all items from list.
- count(value, /)§
Return number of occurrences of value.
- cut_off(start, end)§
Time-based deletion / shortening of the respective event.
- Parameters:
- Return type:
Envelope[T]
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:
- Return type:
Envelope[T]
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 returnsTrue
orFalse
. If the return value of the function isFalse
the respective Event will be deleted.mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
Example:
>>> from mutwo import core_events >>> simultaneous_event = core_events.SimultaneousEvent( [core_events.SimpleEvent(1), core_events.SimpleEvent(3), core_events.SimpleEvent(2)] ) >>> simultaneous_event.filter(lambda event: event.duration > 2) >>> simultaneous_event SimultaneousEvent([SimpleEvent(duration = 3)])
- get_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:
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 resultingtuple
shall repeat the nested structure of the event.filter_undefined (bool) – If set to
True
allNone
values will be filtered from the returned tuple. Default toFalse
. This flag has no effect onget_parameter()
ofmutwo.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:
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.
Example:
>>> from mutwo import core_events >>> from mutwo import music_events >>> from mutwo import music_parameters >>> sequential_event = core_events.SequentialEvent( >>> [ >>> music_events.NoteLike( >>> [ >>> music_parameters.WesternPitch('c', 4), >>> music_parameters.WesternPitch('e', 4)], >>> ], >>> 2, 1, >>> ) >>> ] >>> ) >>> sequential_event.mutate_parameter( >>> 'pitch_list', lambda pitch_list: [pitch.add(12) for pitch in pitch_list] >>> ) >>> # now all pitches should be one octave higher (from 4 to 5) >>> sequential_event.get_parameter('pitch_list') ([WesternPitch(c5), WesternPitch(e5)],)
- pop(index=-1, /)§
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(value, /)§
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reset_tempo_envelope()§
Set events tempo envelope so that one beat equals one second (tempo 60).
- Parameters:
mutate – If
False
the function will return a copy of the given object. If set toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.- Return type:
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Returns:
The event.
- Return type:
ComplexEvent[T]
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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- 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 toTrue
the object itself will be changed and the function will return the changed object. Default toTrue
.
- Return type:
ComplexEvent[T]
- 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:
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:
- subtract(pitch_interval)[source]§
- Parameters:
pitch_interval (PitchInterval) –
- Return type:
- property digit_to_round_to_count: Optional[int]§
- direct_comparison_type_tuple = ()§
- property envelope: RelativeEnvelope§
- abstract property frequency: value_return_type§
- property midi_pitch_number: float§
The midi pitch number (from 0 to 127) of the pitch.
- property value_name§
- class PitchAmbitus(minima_pitch, maxima_pitch)[source]§
Abstract base class for all pitch ambituses.
To setup a new PitchAmbitus class override the abstract method pitch_to_period.
- filter_pitch_sequence(pitch_to_filter_sequence)[source]§
Filter all pitches in a sequence which aren’t inside the ambitus.
- Parameters:
pitch_to_filter_sequence (Sequence[Pitch]) – A sequence with pitches which shall be filtered.
- Return type:
tuple[mutwo.music_parameters.abc.Pitch, …]
Example:
>>> from mutwo import music_parameters >>> ambitus0 = music_parameters.OctaveAmbitus( music_parameters.JustIntonationPitch('1/2'), music_parameters.JustIntonationPitch('2/1'), ) >>> ambitus0.filter_pitch_sequence( [ music_parameters.JustIntonationPitch("3/8"), music_parameters.JustIntonationPitch("3/4"), music_parameters.JustIntonationPitch("3/2"), music_parameters.JustIntonationPitch("3/1"), ] ) (JustIntonationPitch('3/4'), JustIntonationPitch('3/2'))
- get_pitch_variant_tuple(pitch, period=None)[source]§
Find all pitch variants (in all octaves) of the given pitch
- Parameters:
pitch (Pitch) – The pitch which variants shall be found.
period (Optional[PitchInterval]) – The repeating period (usually an octave). If the period is set to None the function will fallback to them objects method :method:`pitch_to_period`. Default to None.
- Return type:
tuple[mutwo.music_parameters.abc.Pitch, …]
- property border_tuple: tuple[mutwo.music_parameters.abc.Pitch, mutwo.music_parameters.abc.Pitch]§
- property range: PitchInterval§
- class PitchInterval[source]§
Abstract base class for any pitch interval class
If the user wants to define a new pitch interval class, the abstract property
interval
has to be overridden.interval
is stored in unit cents.See wikipedia entry for definition of ‘cents’.
- property digit_to_round_to_count: Optional[int]§
- direct_comparison_type_tuple = ()§
- abstract property interval: value_return_type§
- property value_name§
- class PlayingIndicator[source]§
Abstract base class for any playing indicator.
- get_arguments_dict()§
- Return type:
dict[str, Any]
- abstract property is_active: bool§
- class Syllable(is_last_syllable)[source]§
Syllable mixin for classes which inherit from
Lyric
.This adds the new attribute
is_last_syllable
. This should be True if it is the last syllable of a word and False if it isn’t.- Parameters:
is_last_syllable (bool) –
- 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 Volume[source]§
Abstract base class for any volume class.
If the user wants to define a new volume class, the abstract property
amplitude
has to be overridden.- static amplitude_ratio_to_decibel(amplitude, reference_amplitude=1)[source]§
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)[source]§
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)[source]§
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)[source]§
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)[source]§
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)[source]§
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
- abstract property amplitude: value_return_type§
- 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§