mutwo.events.music¶

Event classes which are designated for musical usage.

Classes:

NoteLike([pitch_or_pitches, duration, ...])

NoteLike represents traditional discreet musical objects.

class NoteLike(pitch_or_pitches='c', duration=1, volume='mf', playing_indicators=None, notation_indicators=None)[source]¶

Bases: mutwo.events.basic.SimpleEvent

NoteLike represents traditional discreet musical objects.

Parameters

pitch_or_pitches (Optional[Union[mutwo.parameters.abc.Pitch, Iterable, float, fractions.Fraction]]) – The pitch or pitches of the event. This can be a pitch object (any class that inherits from mutwo.parameters.abc.Pitch) or a list of pitch objects. Furthermore mutwo supports syntactic sugar to convert other objects on the fly to pitch objects: Atring can be read as pitch class names to build mutwo.parameters.pitches.WesternPitch objects or as ratios to build mutwo.parameters.pitches.JustIntonationPitch objects. Fraction will also build mutwo.parameters.pitches.JustIntonationPitch objects. Other numbers (integer and float) will be read as pitch class numbers to make mutwo.parameters.pitches.WesternPitch objects.
new_duration – The duration of NoteLike. This can be any number. The unit of the duration is up to the interpretation of the user and the respective converter routine that will be used.
volume (Union[mutwo.parameters.abc.Volume, float, fractions.Fraction, str]) – The volume of the event. Can either be a object of mutwo.parameters.volumes, a number or a string. If the number ranges from 0 to 1, mutwo automatically generates a mutwo.parameters.volumes.DirectVolume object (and the number will be interpreted as the amplitude). If the number is smaller than 0, automatically generates a mutwo.parameters.volumes.DecibelVolume object (and the number will be interpreted as decibel). If the argument is a string, mutwo will try to initialise a mutwo.parameters.volumes.WesternVolume object.
playing_indicators (mutwo.parameters.playing_indicators.PlayingIndicatorCollection) –
notation_indicators (mutwo.parameters.notation_indicators.NotationIndicatorCollection) –
duration (Union[float, fractions.Fraction]) –

By default mutwo doesn’t differentiate between Tones, Chords and Rests, but rather simply implements one general class which can represent any of the mentioned definitions (e.g. a NoteLike object with several pitches may be called a ‘Chord’ and a NoteLike object with only one pitch may be called a ‘Tone’).

Example:

>>> from mutwo.parameters import pitches
>>> from mutwo.events import music
>>> tone = music.NoteLike(pitches.WesternPitch('a'), 1, 1)
>>> other_tone = music.NoteLike('3/2', 1, 0.5)
>>> chord = music.NoteLike(
    [pitches.WesternPitch('a'), pitches.JustIntonationPitch('3/2')], 1, 1
)
>>> other_chord = music.NoteLike('c4 dqs3 10/7', 1, 3)

Methods:

`cut_off`(start, end)	Time-based deletion / shortening of the respective event.
`cut_out`(start, end)	Time-based slicing of the respective event.
`destructive_copy`()	Adapted deep copy method that returns a new object for every leaf.
`get_parameter`(parameter_name)	Return event attribute with the entered name.
`mutate_parameter`(parameter_name, function)	Mutate parameter with a function.
`set_parameter`(parameter_name, object_or_function)	Sets event parameter to new value.
`split_at`(absolute_time)	Split event in two events at `absolute_time`.

Attributes:

`duration`	The duration of an event (which can be any number).
`pitch_or_pitches`	The pitch or pitches of the event.
`volume`	The volume of the event.

cut_off(start, end)¶

Time-based deletion / shortening of the respective event.

Parameters

start (Union[float, fractions.Fraction]) – number that indicates absolute time when the cut off shall start.
end (Union[float, fractions.Fraction]) – number that indicates the absolute time when the cut off shall end.

Return type

Optional[mutwo.events.basic.SimpleEvent]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(3), basic.SimpleEvent(2)])
>>> sequential_event.cut_off(1, 3)
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1)])

cut_out(start, end)¶

Time-based slicing of the respective event.

Parameters

start (Union[float, fractions.Fraction]) – number that indicates the point when the cut out shall start.
end (Union[float, fractions.Fraction]) – number that indicates the point when the cut up shall end.

Return type

Optional[mutwo.events.basic.SimpleEvent]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(3), basic.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.events import basic
>>> my_simple_event_0 = basic.SimpleEvent(2)
>>> my_simple_event_1 = basic.SimpleEvent(3)
>>> my_sequential_event = basic.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: mutwo.events.basic.SimpleEvent

get_parameter(parameter_name)¶

Return event attribute with the entered name.

Parameter_name: The name of the attribute that shall be returned.
Returns: Return the value that has been assigned to the passed parameter_name. If an event doesn’t posses the asked parameter, the method will simply return None.
Parameters: parameter_name (str) –
Return type: Any

Example:

>>> from mutwo.events import basic
>>> simple_event = basic.SimpleEvent(2)
>>> simple_event.pitch = 200
>>> simple_event.get_parameter('pitch')
200
>>> simple_event.get_parameter('pitches')
None

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[[mutwo.parameters.abc.Parameter], None], Any]) – The function which mutates the parameter. The function gets as an input the assigned value for the passed parameter_name of the respective object. The function shouldn’t return anything, but simply calls a method of the parameter value.

Return type

Optional[mutwo.events.basic.SimpleEvent]

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.events import basic, music
>>> from mutwo.parameters import pitches
>>> sequential_event = basic.SequentialEvent([music.NoteLike([pitches.WesternPitch('c', 4), pitches.WesternPitch('e', 4)], 2, 1)])
>>> sequential_event.mutate_parameter('pitch_or_pitches', lambda pitch_or_pitches: [pitch.add(12) for pitch in pitch_or_pitches])
>>> # now all pitches should be one octave higher (from 4 to 5)
>>> sequential_event.get_parameter('pitch_or_pitches')
([WesternPitch(c5), WesternPitch(e5)],)

set_parameter(parameter_name, object_or_function, set_unassigned_parameter=True)¶

Sets event parameter to new value.

Parameters

parameter_name (str) – The name of the parameter which values shall be changed.
object_or_function (Union[Callable[[mutwo.parameters.abc.Parameter], mutwo.parameters.abc.Parameter], 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.

Return type

Optional[mutwo.events.basic.SimpleEvent]

Example:

>>> from mutwo.events import basic
>>> simple_event = basic.SimpleEvent(2)
>>> simple_event.set_parameter('duration', lambda old_duration: old_duration * 2)
>>> simple_event.duration
4
>>> simple_event.set_parameter('duration', 3)
>>> simple_event.duration
3
>>> simple_event.set_parameter('unknown_parameter', 10, set_unassigned_parameter=False)  # this will be ignored
>>> simple_event.unknown_parameter
AttributeError: 'SimpleEvent' object has no attribute 'unknown_parameter'
>>> simple_event.set_parameter('unknown_parameter', 10, set_unassigned_parameter=True)  # this will be written
>>> simple_event.unknown_parameter
10

split_at(absolute_time)¶

Split event in two events at absolute_time.

Parameters: absolute_time (Union[float, fractions.Fraction]) – where event shall be split
Returns: Two events that result from splitting the present event.
Return type: Tuple[mutwo.events.abc.Event, mutwo.events.abc.Event]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.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))

property duration: Union[float, fractions.Fraction]¶

The duration of an event (which can be any number).

The unit of the duration is up to the interpretation of the user and the respective conversion routine that will be used. For instance when using CsoundScoreConverter, the duration will be understood as seconds, while MidiFileConverter will read duration as beats.

property pitch_or_pitches: Any¶: The pitch or pitches of the event.

property volume: Any¶: The volume of the event.

mutwo.events.music¶

Previous topic

Next topic

This Page