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.

Objects in this category

• EventCall : Calls a function, with any number of arguments, and uses its return value.

• EventChoice : Plays values randomly chosen from a list.

• EventConditional : Executes one generator or the other depending on the result of a condition.

• EventDrunk : Performs a random walk over a list of values.

• EventDummy : An EventGenerator created internally to handle arithmetic on Events.

• EventFilter : An EventGenerator created internally to handle simple filter on Events.

• EventGenerator : Base class for all event generators.

• EventIndex : Plays values from a list based on a position index.

• EventInstrument : Base class for an Events instrument. All attributes given to the Events

• EventKey : An EventGenerator that allow to retrieve the value of another parameter.

• EventMarkov : Applies a Markov algorithm to a list of values.

• EventNoise : Return a random value between -1.0 and 1.0.

• EventScale : Musical scale builder.

• EventSeq : Plays through an entire list of values many times.

• EventSlide : Plays overlapping segments from a list of values.

• Events : Sequencing user-defined events to form musical phrases.

EventScale

class EventScale(root='C', scale='major', first=4, octaves=2, type=0)

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 Data Attributes:

root	string.
scale	string.
first	int.
octaves	int.
type	int.

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)

Replace the root attribute and reconstruct the scale.

Args

x: string

New root attribute.

setScale(x)

Replace the scale attribute and reconstruct the scale.

Args

x: string

New scale attribute.

setFirst(x)

Replace the first attribute and reconstruct the scale.

Args

x: int

New int attribute.

setOctaves(x)

Replace the octaves attribute and reconstruct the scale.

Args

x: int

New octaves attribute.

setType(x)

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

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()

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. If two values are equally close, rounding is done toward the even choice.

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.

Args

choice: list of floats

Possible values to output.

deviate(depth)

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)

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)

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)

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)

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)

An EventGenerator created internally to handle arithmetic on Events.

Public Methods:

__init__(generator1, generator2, type)
next()

Inherited from EventGenerator

__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:

Inherited from EventGenerator

_inspect_generator(generator)
_inspect_values(values)
_inspect_occurrences(occurrences)
_internalGeneratorNextCall()
_checkValueTypeAndIncrementCount(value)

---

EventFilter

class EventFilter(generator, type, *args)

An EventGenerator created internally to handle simple filter on Events.

Public Methods:

__init__(generator, type, *args)
next()

Inherited from EventGenerator

__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:

Inherited from EventGenerator

_inspect_generator(generator)
_inspect_values(values)
_inspect_occurrences(occurrences)
_internalGeneratorNextCall()
_checkValueTypeAndIncrementCount(value)

---

EventKey

class EventKey(key, master=None)

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.

>>> s = Server().boot()
>>> s.start()
>>> # The lower the pitch value, the louder is the note.
>>> dbkey = EventKey("midinote").rescale(48,84,-3,-32,1)
>>> e = Events(midinote=list(range(48,84,2)), beat=1/4., db=dbkey).play()

Public Methods:

__init__(key[, master])
getKey()	Returns the key, as a string, of the parameter to read from.
reset()
next()

Inherited from EventGenerator

__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:

Inherited from EventGenerator

_inspect_generator(generator)
_inspect_values(values)
_inspect_occurrences(occurrences)
_internalGeneratorNextCall()
_checkValueTypeAndIncrementCount(value)

---

getKey()

Returns the key, as a string, of the parameter to read from.

EventSeq

class EventSeq(values, occurrences=inf, stopEventsWhenDone=True)

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.

>>> s = Server().boot()
>>> s.start()
>>> e = Events(freq=EventSeq(midiToHz([60, 64, 67, 72])), beat=1/4.).play()

Public Methods:

__init__(values[, occurrences, ...])
__len__()
reset()
next()

Inherited from EventGenerator

__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:

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)

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__()
__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)

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__()
__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)

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__()
__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)

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__()
__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)

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__()
__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)

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__()
__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)

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.

>>> s = Server().boot()
>>> s.start()
>>> from random import randrange
>>> e = Events(midinote=EventCall(randrange, 48, 72, 3), beat=1/4., db=-6).play()

Public Methods:

__init__(function, *args, **kwargs)
__len__()
reset()
next()

Inherited from EventGenerator

__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:

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)

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__()
__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)

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)

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.

---

events()

Return a copy of this Events object.

play(dur=0, delay=0)

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)

Stop the events playback.

Args

wait: float, optional

Delay, in seconds, before the process is actually stopped. Defaults to 0.

sig()

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.