Events framework¶
Set of tools to generate sequence of events.
The purpose of the Event framework is to allow the user to generate a sequence of events with as few as possible parameters to specify.
Events
is the heart of the framework. An Events object computes
parameters, generally designed with event generator objects, builds the events
and plays the sequence.
See the Events framework examples in the documentation for different use cases.
EventScale¶
- class EventScale(root='C', scale='major', first=4, octaves=2, type=0)[source]¶
Musical scale builder.
EventScale constructs a list of pitches according to its arguments.
EventScale works similarly to list, ie. uses slicing with square brackets to access data, with the first element at index 0.
It also accept the len() function, which returns the number of elements in the scale.
- Args
- root: str, optional
The base note (fundamental) of the scale. Possible values are: ‘C’, ‘C#’, ‘Db’, ‘D’, ‘D#’, ‘Eb’, ‘E’, ‘F’, ‘F#’, ‘Gb’, ‘G’, ‘G#’, ‘Ab’, ‘A’, ‘A#’, ‘Bb’, ‘B’. Defaults to ‘C’.
- scale: str, optional
The scale name to construct. Possible scales are: ‘major’, ‘minorH’, ‘minorM’, ‘ionian’, ‘dorian’, ‘phrygian’, ‘lydian’, ‘mixolydian’, ‘aeolian’, ‘locrian’, ‘wholeTone’, ‘majorPenta’, ‘minorPenta’, ‘egyptian’, ‘majorBlues’, ‘minorBlues’, ‘minorHungarian’. Defaults to ‘major’.
- first: int, optional
The first octave of the generated scale, in multiple of 12. A value of 4, for a root of ‘C’ means the first note of the scale will be 48. Defaults to 4.
- octaves: int, optional
The number of octaves in the generated scale. Defaults to 2.
- type: int, optional
- The unit type in which the values are stored. Possible types are:
0: MIDI note 1: Hertz 2: octave.degree notation (MIDI note 48 is 4.00 in octave.degrees)
Note
Here is a table showing the relationship between the three unit types that EventScale can handle.
midi
oct.deg
Hertz
48
4.00
130.81
50
4.02
146.83
52
4.04
164.81
53
4.05
174.61
55
4.07
195.99
57
4.09
220.00
59
4.11
246.94
60
5.00
261.62
>>> s = Server().boot() >>> s.start() >>> scl = EventScale(root="C", scale="major", first=4, octaves=2, type=2) >>> e = Events(degree=EventDrunk(scl, maxStep=-2), beat=1/4., db=-6).play()
Public Methods:
__init__
([root, scale, first, octaves, type])__len__
()__getitem__
(key)__setitem__
(key, item)setRoot
(x)Replace the root attribute and reconstruct the scale.
setScale
(x)Replace the scale attribute and reconstruct the scale.
setFirst
(x)Replace the first attribute and reconstruct the scale.
setOctaves
(x)Replace the octaves attribute and reconstruct the scale.
setType
(x)Replace the type attribute and reconstruct the scale.
Private Methods:
_populate
()
- setRoot(x)[source]¶
Replace the root attribute and reconstruct the scale.
- Args
- x: string
New root attribute.
- setScale(x)[source]¶
Replace the scale attribute and reconstruct the scale.
- Args
- x: string
New scale attribute.
- setFirst(x)[source]¶
Replace the first attribute and reconstruct the scale.
- Args
- x: int
New int attribute.
- setOctaves(x)[source]¶
Replace the octaves attribute and reconstruct the scale.
- Args
- x: int
New octaves attribute.
- setType(x)[source]¶
Replace the type attribute and reconstruct the scale.
- Args
- x: int
New type attribute.
- property root¶
string. Name of the fundamental key.
- property scale¶
string. Name of scale to generate.
- property first¶
int. First octave to generate.
- property octaves¶
int. Number of octaves to generate.
- property type¶
int. Unit in which pitch values are stored.
EventGenerator¶
- class EventGenerator[source]¶
Base class for all event generators.
This class contains the common behaviours of all event generators.
Each EventGenerator contains a particular algorithm that can produce a sequence of values triggered by an Events mecanism for one of its arguments.
The EventGenerator allows very flexible control of the algorithm parameters. It can be a single value, another EventGenerator or an audio signal (PyoObject).
Arithmetic operations are allowed on EventGenerator. An EventDummy is then created to apply the operation to each value produced by the generator.
Arithmetic operators are:
- +: float, PyoObject or EventGenerator
Addition.
- -: float, PyoObject or EventGenerator
Substraction
- *: float, PyoObject or EventGenerator
Multiplication
- /: float, PyoObject or EventGenerator
Division
- %: float, PyoObject or EventGenerator
Modulo (remaining of the division)
- **: float, PyoObject or EventGenerator
Exponent
- //: float, PyoObject or EventGenerator
Quantizer (returns te nearest multiple of its argument)
EventGenerator has a number of filter methods that can be applied on any generator to modify its output values. Available filter methods are:
- floor:
Return an EventFilter computing the largest integer less than or equal to its input value.
- ceil:
Return an EventFilter computing the smallest integer greater than or equal to its input value.
- round:
Return an EventFilter computing the nearest integer to its input value.
- snap:
Return an EventFilter which choose the nearest value of its input value in a list of choices.
- deviate:
Return an EventFilter which randomly move, up or down, its input value.
- clip:
Return an EventFilter which clips its input value between predefined limits.
- scale:
Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve.
- rescale:
Return an EventFilter which maps its input value, given in an input range, to an output range with a scaling curve.
- iftrue:
Return an EventFilter which compares its input value to a comparison value and outputs it if the comparison is True.
Public Methods:
__init__
()__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
- floor()[source]¶
Return an EventFilter computing the largest integer less than or equal to its input value.
- ceil()[source]¶
Return an EventFilter computing the smallest integer greater than or equal to its input value.
- round()[source]¶
Return an EventFilter computing the nearest integer to its input value. If two values are equally close, rounding is done toward the even choice.
- snap(choice)[source]¶
Return an EventFilter which choose the nearest value of its input value in the choice list.
- Args
- choice: list of floats
Possible values to output.
- deviate(depth)[source]¶
Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
- Args
- depth: float or PyoObject
Percentage of deviation, between 0 and 100.
- clip(mini, maxi)[source]¶
Return an EventFilter which clips its input value between the limits mini and maxi.
- Args
- mini: float or PyoObject
Minimum output value.
- maxi: float or PyoObject
Maximum output value.
- scale(mini, maxi, expon)[source]¶
Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
- Args
- mini: float or PyoObject
Minimum output value.
- maxi: float or PyoObject
Maximum output value.
- expon: float or PyoObject
Exponent value, specifies the nature of the scaling curve. Values between 0 and 1 give a logarithmic curve, and values higher than 1 give an exponential curve.
- rescale(inmin, inmax, outmin, outmax, expon)[source]¶
Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
- Args
- inmin: float or PyoObject
Minimum input value.
- inmax: float or PyoObject
Maximum input value.
- outmin: float or PyoObject
Minimum output value.
- outmax: float or PyoObject
Maximum output value.
- expon: float or PyoObject
Exponent value, specifies the nature of the scaling curve. Values between 0 and 1 give a logarithmic curve, and values higher than 1 give an exponential curve.
- iftrue(op, comp)[source]¶
Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op. If the result is True, the input value is sent to the output, otherwise, the last valid value is sent again.
- Args
- op: string
The comparison operator. Valid operators are: ‘<’, ‘<=’, ‘>’, ‘>=’, ‘==’, ‘!=’.
- comp: float or PyoObject
Comparison value.
EventDummy¶
- class EventDummy(generator1, generator2, type)[source]¶
An EventGenerator created internally to handle arithmetic on Events.
Public Methods:
__init__
(generator1, generator2, type)next
()Inherited from
EventGenerator
__init__
(generator1, generator2, type)__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventFilter¶
- class EventFilter(generator, type, *args)[source]¶
An EventGenerator created internally to handle simple filter on Events.
Public Methods:
__init__
(generator, type, *args)next
()Inherited from
EventGenerator
__init__
(generator, type, *args)__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventKey¶
- class EventKey(key, master=None)[source]¶
An EventGenerator that allow to retrieve the value of another parameter.
EventKey returns the current value of another parameter of the Events object where it is used. From there, other processes can be applied (arithmetics, filters) to transform this value.
EventKey can also read parameter values from another Events object when one is passed as master argument.
- Args
- key: string
The name of the parameter to read from.
- master: Events, optional
The Events object from which to read the parameter value. If None (the default), the current Events object is used.
Public Methods:
__init__
(key[, master])getKey
()Returns the key, as a string, of the parameter to read from.
reset
()next
()Inherited from
EventGenerator
__init__
(key[, master])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventSeq¶
- class EventSeq(values, occurrences=inf, stopEventsWhenDone=True)[source]¶
Plays through an entire list of values many times.
EventSeq will loop over its list of values a number of times defined by the occurrences argument.
- Args
- values: EventScale or list
List of values to loop over. Values in list can be floats, PyoObject or other EventGenerator.
- occurrences: int, optional
Number of times the sequence is entirely played in loop. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
Note
If an Events argument receives a single value or a list, it will be automatically converted to an EventSeq.
Public Methods:
__init__
(values[, occurrences, ...])__len__
()reset
()next
()Inherited from
EventGenerator
__init__
(values[, occurrences, ...])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventSlide¶
- class EventSlide(values, segment, step, startpos=0, wraparound=True, occurrences=inf, stopEventsWhenDone=True)[source]¶
Plays overlapping segments from a list of values.
EventSlide will play a segment of length segment from startpos, then another segment with a start position incremented by step, and so on.
- Args
- values: EventScale or list
List of values to read. Values in list can be floats, PyoObject or other EventGenerator.
- segment: int, PyoObject or EventGenerator
Number of values of each segment.
- step: int, PyoObject or EventGenerator
How far to step the start of each segment from the previous. A negative value will step backward.
- startpos: int, optional
The start position of the first segment. A negative value sets the position backward starting from the end of the list. Defaults to 0.
- wraparound: bool, optional
If ‘wraparound’ if True, indexing wraps around if goes past the beginning or the end of the list. If False, the playback stops if it goes outside the list bounds. Defaults to True.
- occurrences: int, optional
Number of entire segments to play. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
>>> s = Server().boot() >>> s.start() >>> scl = [5.00, 5.02, 5.03, 5.05, 5.07, 5.08, 5.10, 6.00] >>> e = Events(degree=EventSlide(scl, 3, 1, 0), beat = 1/4., db = -6).play()
Public Methods:
__init__
(values, segment, step[, startpos, ...])__len__
()reset
()getStepValue
()getSegmentValue
()next
()Inherited from
EventGenerator
__init__
(values, segment, step[, startpos, ...])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventIndex¶
- class EventIndex(values, index, occurrences=inf, stopEventsWhenDone=True)[source]¶
Plays values from a list based on a position index.
- Args
- values: EventScale or list
List of values to read. Values in list can be floats, PyoObject or other EventGenerator.
- index: int, PyoObject or EventGenerator
Position to read in the list, starting at 0.
- occurrences: int, optional
Number of values to play. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
>>> s = Server().boot() >>> s.start() >>> scl = [5.00, 5.02, 5.03, 5.05, 5.07, 5.08, 5.10, 6.00] >>> arp = EventSeq([0, 2, 4, 2, 1, 3, 5, 3, 1, 6, 4, 1]) >>> e = Events(degree = EventIndex(scl, arp), beat = 1/4., db = -6).play()
Public Methods:
__init__
(values, index[, occurrences, ...])__len__
()reset
()getIndexValue
()next
()Inherited from
EventGenerator
__init__
(values, index[, occurrences, ...])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventMarkov¶
- class EventMarkov(values, order=2, occurrences=inf, stopEventsWhenDone=True)[source]¶
Applies a Markov algorithm to a list of values.
A Markov chain is a stochastic model describing a sequence of possible events in which the probability of each event depends only on the state attained in the previous events.
- Args
- values: EventScale or list
Original list of values.
- order: int, PyoObject or EventGenerator, optional
Order of the Markov chain, between 1 and 10. Determines how many past values will be used to build the probability table for the next note. Defaults to 2.
- occurrences: int, optional
Number of values to play. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
>>> s = Server().boot() >>> s.start() >>> jesus = [67,69,71,74,72,72,76,74,74,79,78,79,74,71,67,69,71,72,74,76,74,72,71] >>> jesus += [69,71,67,66,67,69,62,66,69,72,71,69,71,67,69,71,74,72,72,76,74,74,79] >>> jesus += [78,79,74,71,67,69,71,64,74,72,71,69,67,62,67,66,67,71,74,79,74,71,67] >>> e = Events(midinote=EventMarkov(jesus, 2), beat=1/4., db=-6).play()
Public Methods:
__init__
(values[, order, occurrences, ...])__len__
()reset
()getOrderValue
()next
()Inherited from
EventGenerator
__init__
(values[, order, occurrences, ...])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventChoice¶
- class EventChoice(values, occurrences=inf, stopEventsWhenDone=True)[source]¶
Plays values randomly chosen from a list.
- Args
- values: EventScale or list
List of possible values to read. Values in list can be floats, PyoObject or other EventGenerator.
- occurrences: int, optional
Number of values to play. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
>>> s = Server().boot() >>> s.start() >>> scl = [5.00, 5.02, 5.03, 5.05, 5.07, 5.08, 5.10, 6.00] >>> e = Events(degree = EventChoice(scl), beat = 1/4., db = -6).play()
Public Methods:
__init__
(values[, occurrences, ...])__len__
()reset
()next
()Inherited from
EventGenerator
__init__
(values[, occurrences, ...])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventDrunk¶
- class EventDrunk(values, maxStep=2, occurrences=inf, stopEventsWhenDone=True)[source]¶
Performs a random walk over a list of values.
A random walk is a stochastic process that consists of a succession of random steps, within a distance of +/- maxStep from the previous state.
- Args
- values: EventScale or list
List of values to read. Values in list can be floats, PyoObject or other EventGenerator.
- maxStep: int, PyoObject or EventGenerator, optional
Determine the larger step the walk can do between two successive events. A negative ‘maxStep’ is the same but repetition are not allowed. Defaults to 2.
- occurrences: int, optional
Number of values to play. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
>>> s = Server().boot() >>> s.start() >>> scl = [5.00, 5.02, 5.03, 5.05, 5.07, 5.08, 5.10, 6.00] >>> e = Events(degree=EventDrunk(scl, maxStep=-2), beat=1/4., db=-6).play()
Public Methods:
__init__
(values[, maxStep, occurrences, ...])__len__
()reset
()getMaxStepValue
()next
()Inherited from
EventGenerator
__init__
(values[, maxStep, occurrences, ...])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventNoise¶
- class EventNoise(type=0, occurrences=inf, stopEventsWhenDone=True)[source]¶
Return a random value between -1.0 and 1.0.
EventNoise returns a random value between -1.0 and 1.0, based on one of three common noise generators, white, pink (1/f) and brown (1/f^2).
- Args
- type: int, optional
The type of noise used to generate the random sequence. Available types are:
0: white noise (default) 1: pink noise 2:brown noise
- occurrences: int, optional
Number of values to play. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
>>> s = Server().boot() >>> s.start() >>> scl = EventScale("C", "aeolian", 4, 4) >>> note = EventNoise(1).rescale(-1,1,48,84,1).snap(scl) >>> e = Events(midinote=note, beat=1/4., db=-6).play()
Public Methods:
__init__
([type, occurrences, stopEventsWhenDone])__len__
()reset
()getTypeValue
()next
()Inherited from
EventGenerator
__init__
([type, occurrences, stopEventsWhenDone])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventCall¶
- class EventCall(function, *args, **kwargs)[source]¶
Calls a function, with any number of arguments, and uses its return value.
EventCall can call any function (built-in, from a module or user-defined) and use its return as the value for the Events’s parameter where it is used. The function must return a single number.
- Args
- function: callable
The function to call, which should return the value to use.
- args: int, PyoObject or EventGenerator, optional
Any number of arguments to pass to the function call. If given a PyoObject or an EventGenerator, these will be resolved for each event and the result passed, as number, to the function.
- occurrences: int, optional
Number of values to play. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
Public Methods:
__init__
(function, *args, **kwargs)__len__
()reset
()next
()Inherited from
EventGenerator
__init__
(function, *args, **kwargs)__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventConditional¶
- class EventConditional(condition, iftrue, iffalse, occurrences=inf, stopEventsWhenDone=True)[source]¶
Executes one generator or the other depending on the result of a condition.
EventConditional takes three values or generators as arguments and if the value of condition is True (anything that python considers True), the iftrue argument is used to produce the value for the event, otherwise th iffalse argument is used.
- Args
- condition: int, PyoObject or EventGenerator
Conditional value. True for everything python considers True.
- iftrue: int, PyoObject or EventGenerator
Output value if the condition is True.
- iffalse: int, PyoObject or EventGenerator
Output value if the condition is False.
- occurrences: int, optional
Number of values to play. Defaults to inf (infinite).
- stopEventsWhenDone: bool, optional
If True, the Events playback will stop if this generator reaches its end. If False, the Events will ignore this signal and probably get None as value for the given parameter. It’s the user responsability to handle this case correctly. Defaults to True.
>>> s = Server().boot() >>> s.start() >>> from random import randrange >>> scl = EventScale("C", "aeolian", 4, 3) >>> bit = EventChoice([0, 1, 1, 1]) >>> pittrue = EventSlide(scl, segment=3, step=1, startpos=0) >>> veltrue = EventDrunk(range(64, 127), maxStep=5) >>> pit = EventConditional(bit, pittrue, 0) >>> vel = EventConditional(bit, veltrue, 0) >>> e = Events(midinote=pit, beat=1/4., midivel=vel).play()
Public Methods:
__init__
(condition, iftrue, iffalse[, ...])__len__
()reset
()getConditionValue
()getIftrueValue
()getIffalseValue
()next
()Inherited from
EventGenerator
__init__
(condition, iftrue, iffalse[, ...])__add__
(generator)__sub__
(generator)__mul__
(generator)__div__
(generator)__truediv__
(generator)__pow__
(generator)__mod__
(generator)__floordiv__
(generator)setMaster
(master)copy
()reset
()next
()resetEmbeddedGenerator
()floor
()Return an EventFilter computing the largest integer less than or equal to its input value.
ceil
()Return an EventFilter computing the smallest integer greater than or equal to its input value.
round
()Return an EventFilter computing the nearest integer to its input value.
abs
()Return an EventFilter computing the absolute value of its input value.
snap
(choice)Return an EventFilter which choose the nearest value of its input value in the choice list.
deviate
(depth)Return an EventFilter which randomly move, up or down, its input value according to the argument depth, in percent.
clip
(mini, maxi)Return an EventFilter which clips its input value between the limits mini and maxi.
scale
(mini, maxi, expon)Return an EventFilter which maps its input value, in the range 0 to 1, to an output range, with a scaling curve deternimed bu the expon value.
rescale
(inmin, inmax, outmin, outmax, expon)Return an EventFilter which maps its input value, in the range inmin to inmax, to an output range, outmin to outmax, with a scaling curve deternimed bu the expon value.
iftrue
(op, comp)Return an EventFilter which compares its input value to the value given to comp argument, using the comparison operator op.
Private Methods:
Inherited from
EventGenerator
_inspect_generator
(generator)_inspect_values
(values)_inspect_occurrences
(occurrences)_internalGeneratorNextCall
()_checkValueTypeAndIncrementCount
(value)
EventInstrument¶
- class EventInstrument(**args)[source]¶
Base class for an Events instrument. All attributes given to the Events object can be accessed as self.attribute_name inside the instrument.
This base class constructs an envelope, named self.env, according to the value given to ‘envelope’ (ex.: a LinTable object) or to ‘attack’, ‘decay’, ‘sustain’ and ‘release’ attributes of the event. The envelope is also scaled by the value of self.amp, defined by ‘amp’, ‘db’ or ‘midivel’ arguments of the Events object.
This base class also creates a self.freq variable based on ‘freq’, ‘degree’ or ‘midinote’ arguments. This variable can be used in the instrument to control the pitch of the sound.
All resources are automatically destroyed when the lifetime of the event is over. The lifetime of the event is set as self.dur + self.tail (‘dur’ or ‘beat’ and ‘tail’ arguments of Events).
Note
The user has almost no reason to instantiate an EventInstrument object himself. Instead, he should use it as a parent class for its own instruments.
Public Methods:
__init__
(**args)clear
()
Events¶
- class Events(**args)[source]¶
Sequencing user-defined events to form musical phrases.
The Events object is the primary tool in the events framework. It uses generators (derived from EventGenerator) as value for its arguments to build a sequence of events, each of them with their own parameters.
Each time Events needs to produce a new event, it collects values from the generators given to its arguments, builds a parameter dictionary and gives it to a new instance of the audio instrument referenced to its ‘instr’ argument.
The object produces new events until one of its generators reaches the end of its sequence.
Events is a child of the dictionary class, which means that every argument given at its initialization will become a new key (with its associated value) in its memory. These keys will serve to create the parameter dictionary passed to the audio instrument instance playing this event. Inside the instrument instance, the value associated to these keys will be retrieved as instance’s attributes, with the syntax self.key_name.
The user can create as many new keys as needed to control its instrument, but there is already a number of pre-defined keys for which Events will do some processing and build useful parameters. Here is the list, grouped by themes, of pre-defined keys to overwrite:
- Instrument
- instr: class, optional
Reference to a custom class with which the events will be played. Defaults to DefaultInstrument.
- signal: string, optional
Name of the attribute in the instrument defintion retrieved as the output signal of the Events object. The sig() method returns the sum, as an audio signal, of all active instances. This can be useful to do post-processing on the signal produced by the events. Defaults to None.
- Constants
- bpm: int, optional
Beat-Per-Minute value used by the beat key to compute event’s duration. Defaults to 120.
- outs: int, optional
Number of output channels in the audio signal returned by the sig() method. This value should match the number of audio streams produced by the instrument. Defaults to 2.
- Duration keys
- dur: float, PyoObject or EventGenerator, optional
Duration, in seconds, before the next event. Defaults to 1.
- beat: float, PyoObject or EventGenerator, optional
Duration, in beat value, before the next event (1 beat = quarter note at BPM). If defined, this value will be used to compute the duration in seconds for the dur key. Defaults to None.
- durmul: float, PyoObject or EventGenerator, optional
Event duration multiplier (only affects the duration of the event’s lifetime, not the time to wait before the next event). Defaults to 1.
- tail: float, PyoObject or EventGenerator, optional
Duration, in seconds, to wait before deleting the instrument’s instance when its envelope has ended. Useful to let a reverb tail to finish before cleaning-up the instance. Defaults to 2.
- Amplitude keys
- amp: float, PyoObject or EventGenerator, optional
Linear gain for the event (1 is nominal gain). Defaults to 0.7.
- dB: float, PyoObject or EventGenerator, optional
Gain, in decibels, for the event. If defined, this value will be used to compute the linear gain for the amp key. Defaults to None.
- midivel: float, PyoObject or EventGenerator, optional
Midi velocity, between 0 and 127, for the event. If defined, this value will be used to compute the linear gain for the amp key. Defaults to None.
- Envelope keys
- envelope: PyoTableObject, optional
User-defined envelope as a PyoTableObject. If defined, this will be the envelope created for the event. Defaults to None.
- attack: float, PyoObject or EventGenerator, optional
Rising time, in seconds, of an ASR or ADSR envelope. This envelope is created if envelope is None. Defaults to 0.005.
- decay: float, PyoObject or EventGenerator, optional
If defined, its the decay time, in seconds, of an ADSR envelope, otherwise the envelope will be an ASR (Attack - Sustain - Release). Defaults to None.
- sustain: float, PyoObject or EventGenerator, optional
Sustain linear gain of an ADSR or ASR envelope. Defaults to 0.7.
- release: float, PyoObject or EventGenerator, optional
Release time, in seconds, of an ASR or ADSR envelope. This envelope is created if envelope is None. Defaults to 0.05.
- Pitch keys
- freq: float, PyoObject or EventGenerator, optional
Frequency, in cycle per seconds, for the event. Defaults to 250.
- midinote: float, PyoObject or EventGenerator, optional
Midi pitch, between 0 and 127, for the event. If defined, this value will be used to compute the frequency in cycles per second for the freq key. Defaults to None.
- degree: float, PyoObject or EventGenerator, optional
Octave.degree pitch notation (ex.: 6.00, 6.04, 6.07). If defined, this value will be used to compute the frequency in cycles per second for the freq key. Defaults to None.
- transpo: float, PyoObject or EventGenerator, optional
Transposition, in midi note value (-12 is an octave lower), automatically computed in the value of the freq key. Defaults to 0.
- Ending keys
- atend: python callable, optional
If defined, a function to call when all events are played. This can be useful to sequence multiple Events objects. Defaults to None
>>> s = Server().boot() >>> s.start() >>> env = CosTable([(0,0.0),(64,1.0),(8191,0.0)]) >>> scl = EventScale(root="C", scale="egyptian", first=4, octaves=3) >>> seg = RandInt(max=6, freq=0.5) >>> step = RandInt(max=6, freq=0.75, add=-3) >>> note = EventSlide(scl, seg, step) >>> e = Events(midinote=note, beat=1/4., db=[-3, -9, -9], envelope=env, durmul=1.25).play()
Public Methods:
__init__
(**args)events
()Return a copy of this Events object.
play
([dur, delay])Start the events playback.
stop
([wait])Stop the events playback.
getCurrentDict
()sig
()Return the audio output signal (sum of all active instances), if defined.
Inherited from
dict
__repr__
()Return repr(self).
__getattribute__
(name, /)Return getattr(self, name).
__lt__
(value, /)Return self<value.
__le__
(value, /)Return self<=value.
__eq__
(value, /)Return self==value.
__ne__
(value, /)Return self!=value.
__gt__
(value, /)Return self>value.
__ge__
(value, /)Return self>=value.
__iter__
()Implement iter(self).
__init__
(**args)__or__
(value, /)Return self|value.
__ror__
(value, /)Return value|self.
__ior__
(value, /)Return self|=value.
__len__
()Return len(self).
__getitem__
x.__getitem__(y) <==> x[y]
__setitem__
(key, value, /)Set self[key] to value.
__delitem__
(key, /)Delete self[key].
__contains__
(key, /)True if the dictionary has the specified key, else False.
__sizeof__
()get
(key[, default])Return the value for key if key is in the dictionary, else default.
setdefault
(key[, default])Insert key with a value of default if key is not in the dictionary.
pop
(k[,d])If key is not found, default is returned if given, otherwise KeyError is raised
popitem
()Remove and return a (key, value) pair as a 2-tuple.
keys
()items
()values
()update
([E, ]**F)If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
fromkeys
([value])Create a new dictionary with keys from iterable and values set to value.
clear
()copy
()__reversed__
()Return a reverse iterator over the dict keys.
__class_getitem__
See PEP 585
Private Methods:
_processEvent
()Create instrument instances and add them to the active list.
_remove
(instanceId)Removes an instrument instance from the active list.
- play(dur=0, delay=0)[source]¶
Start the events playback.
This method returns self, allowing it to be applied at the object creation.
- Args
- dur: float, optional
Duration, in seconds, of the object’s activation. The default is 0 and means infinite duration.
- delay: float, optional
Delay, in seconds, before the object’s activation. Defaults to 0.
- stop(wait=0)[source]¶
Stop the events playback.
- Args
- wait: float, optional
Delay, in seconds, before the process is actually stopped. Defaults to 0.
- sig()[source]¶
Return the audio output signal (sum of all active instances), if defined.
The audio output signal of an Events object is the sum of the active instrument instances’s attribute whose name is the same as given to the ‘signal’ key. The number of audio streams in the output signal is determined by the value for the key ‘outs’, it should match the number of audio streams produced by the instrument.