"""
This submodule contains a 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.
:py:class:`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.
"""
"""
Copyright 2019 Olivier Belanger
This file is part of pyo, a python module to help digital signal
processing script creation.
pyo is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
pyo is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with pyo. If not, see <http://www.gnu.org/licenses/>.
"""
import math
import copy
import random
from ._core import *
from .pattern import Pattern, CallAfter
from .tableprocess import TableRead
from .controls import Fader, Adsr
from .generators import RCOsc
from .effects import STRev
from .pan import Pan
inf = math.inf
PYO_EVENT_OPERATOR_ADD = 1000
PYO_EVENT_OPERATOR_SUB = 1001
PYO_EVENT_OPERATOR_MUL = 1002
PYO_EVENT_OPERATOR_DIV = 1003
PYO_EVENT_OPERATOR_POW = 1004
PYO_EVENT_OPERATOR_MOD = 1005
PYO_EVENT_OPERATOR_FLR = 1006
PYO_EVENT_FILTER_FLOOR = 1100
PYO_EVENT_FILTER_CEIL = 1101
PYO_EVENT_FILTER_ROUND = 1102
PYO_EVENT_FILTER_ABS = 1103
PYO_EVENT_FILTER_SNAP = 1104
PYO_EVENT_FILTER_DEVIATE = 1105
PYO_EVENT_FILTER_CLIP = 1106
PYO_EVENT_FILTER_SCALE = 1107
PYO_EVENT_FILTER_RESCALE = 1108
PYO_EVENT_FILTER_IFTRUE = 1109
# Utility functions
###################
def degreeToMidiNote(value):
"Converts an octave.degree notation to a MIDI note."
st = str(value)
if st.count(".") == 0:
try:
oct = int(st)
deg = 0
except:
oct = 0
deg = 0
elif st.count(".") == 1:
dotPos = st.find(".")
if len(st) >= (dotPos + 3):
st = st[: dotPos + 3]
try:
oct, deg = st.split(".")
if len(deg) == 1:
deg = "%s0" % deg
oct, deg = int(oct), int(deg)
except:
oct, deg = 0, 0
return oct * 12 + deg
def midiNoteToDegree(value):
"Converts a MIDI note to an octave.degree notation."
oct = int(value / 12)
deg = value % 12
return "%d.%02d" % (oct, deg)
def getValueFromAttribute(master, key, currentDict, valueIfNone=None):
"Retrieve the value of an Events attribute, resolving its type."
attribute = master[key]
returnValue = None
if key in currentDict:
return currentDict[key]
elif attribute is None:
returnValue = valueIfNone
elif isinstance(attribute, EventKey):
if attribute.externalMaster is None:
if attribute.getKey() in currentDict:
returnValue = currentDict[attribute.getKey()]
else:
returnValue = getValueFromAttribute(master, attribute.getKey(), currentDict)
currentDict[attribute.getKey()] = returnValue
else:
returnValue = attribute.externalMaster.getCurrentDict().get(attribute.getKey(), None)
elif isinstance(attribute, PyoObject):
returnValue = attribute.get(False)
elif isinstance(attribute, PyoTableObject):
returnValue = attribute
else:
attribute.setMaster(master)
returnValue = attribute.next()
currentDict[key] = returnValue
return returnValue
# Utility classes
#################
class MarkovGen:
def __init__(self, lst, order=2):
self.originalList = lst
self.temporaryList = []
self.playedNotes = []
self.order = order
self.startPlayback()
def startPlayback(self):
self.playedNotes = []
for val in self.originalList:
self.temporaryList.append(val)
for i in range(self.order):
self.temporaryList.append(self.originalList[i])
self.playedNotes = self.originalList[len(self.originalList) - self.order :]
def next(self):
newValue = 0
condition = False
self.probTable = []
for i in range(len(self.temporaryList) - self.order):
for iord in range(self.order):
if (
self.playedNotes[len(self.playedNotes) - (iord + 1)]
!= self.temporaryList[(self.order - 1) + i - iord]
):
condition = False
break
else:
condition = True
if condition:
self.probTable.append(self.temporaryList[i + self.order])
newValue = self.probTable[random.randint(0, (len(self.probTable) - 1))]
self.playedNotes.append(newValue)
return newValue
def setOrder(self, order):
if order != self.order:
self.order = order
self.startPlayback()
# Instruments
#############
[docs]class EventInstrument(object):
"""
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.
"""
def __init__(self, **args):
for key, val in args.items():
setattr(self, key, val)
if self.envelope is not None:
self.env = TableRead(self.envelope, 1.0 / self.dur, mul=self.amp).play()
elif self.decay is not None:
self.env = Adsr(self.attack, self.decay, self.sustain, self.release, dur=self.dur, mul=self.amp).play()
else:
self.env = Fader(fadein=self.attack, fadeout=self.release, dur=self.dur, mul=self.amp).play()
self.clearWhenDone = CallAfter(self.clear, time=0)
self.clearWhenDone.play(delay=self.dur + self.tail, dur=0.25)
def clear(self):
self.removeFunction(self.instanceId)
class DefaultInstrument(EventInstrument):
"""
The default instrument, playing a stereo RC oscillator, used when
'instr' attribute is not defined for an Events object.
"""
def __init__(self, **args):
EventInstrument.__init__(self, **args)
self.osc = RCOsc(freq=self.freq, sharp=0.5, mul=self.env)
self.sig = self.osc.mix(2).out()
# Event Scale
#############
[docs]class EventScale:
"""
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()
"""
def __init__(self, root="C", scale="major", first=4, octaves=2, type=0):
self.rootDegrees = {
"C": 0,
"C#": 1,
"Db": 1,
"D": 2,
"D#": 3,
"Eb": 3,
"E": 4,
"F": 5,
"F#": 6,
"Gb": 6,
"G": 7,
"G#": 8,
"Ab": 8,
"A": 9,
"A#": 10,
"Bb": 10,
"B": 11,
}
self.scales = {
"major": [0, 2, 4, 5, 7, 9, 11],
"minorH": [0, 2, 3, 5, 7, 8, 11],
"minorM": [0, 2, 3, 5, 7, 9, 11],
"ionian": [0, 2, 4, 5, 7, 9, 11],
"dorian": [0, 2, 3, 5, 7, 9, 10],
"phrygian": [0, 1, 3, 5, 7, 8, 10],
"lydian": [0, 2, 4, 6, 7, 9, 11],
"mixolydian": [0, 2, 4, 5, 7, 9, 10],
"aeolian": [0, 2, 3, 5, 7, 8, 10],
"locrian": [0, 1, 3, 5, 6, 8, 10],
"wholeTone": [0, 2, 4, 6, 8, 10],
"majorPenta": [0, 2, 4, 7, 9],
"minorPenta": [0, 3, 5, 7, 10],
"egyptian": [0, 2, 5, 7, 10],
"majorBlues": [0, 2, 5, 7, 9],
"minorBlues": [0, 3, 5, 8, 10],
"minorHungarian": [0, 2, 3, 6, 7, 8, 11],
}
self._init = True
self._length = 0
self._root = "c"
self._scale = "major"
self._first = first
self._octaves = octaves
self._type = type
self.setRoot(root)
self.setScale(scale)
self.data = []
self._init = False
self._populate()
def _populate(self):
if self._init:
return
del self.data[:]
degree = self.rootDegrees.get(self._root, self.rootDegrees["C"])
currentScale = self.scales.get(self._scale, self.scales["major"])
length = len(currentScale)
for i in range(length * self._octaves + 1):
octave = (self._first + int(i / length)) * 12
self.data.append(currentScale[i % length] + octave + degree)
self._length = len(self.data)
if self._type == 1:
self.data = midiToHz(self.data)
elif self._type == 2:
self.data = [midiNoteToDegree(x) for x in self.data]
def __len__(self):
return self._length
def __getitem__(self, key):
return self.data[key]
def __setitem__(self, key, item):
self.data[key] = item
[docs] def setRoot(self, x):
"""
Replace the `root` attribute and reconstruct the scale.
:Args:
x: string
New `root` attribute.
"""
if x not in self.rootDegrees:
print("EventScale: does not recognize root '%s'..." % x)
print("... Using 'C'.")
x = "C"
if x != self._root:
self._root = x
self._populate()
[docs] def setScale(self, x):
"""
Replace the `scale` attribute and reconstruct the scale.
:Args:
x: string
New `scale` attribute.
"""
if x not in self.scales:
print("EventScale: does not recognize scale '%s'..." % x)
print("... Using 'major'.")
x = "major"
if x != self._scale:
self._scale = x
self._populate()
[docs] def setFirst(self, x):
"""
Replace the `first` attribute and reconstruct the scale.
:Args:
x: int
New `int` attribute.
"""
if x != self._first:
self._first = x
self._populate()
[docs] def setOctaves(self, x):
"""
Replace the `octaves` attribute and reconstruct the scale.
:Args:
x: int
New `octaves` attribute.
"""
if x != self._octaves:
self._octaves = x
self._populate()
[docs] def setType(self, x):
"""
Replace the `type` attribute and reconstruct the scale.
:Args:
x: int
New `type` attribute.
"""
if x != self._type:
self._type = x
self._populate()
@property
def root(self):
"""string. Name of the fundamental key."""
return self._root
@root.setter
def root(self, x):
self.setRoot(x)
@property
def scale(self):
"""string. Name of scale to generate."""
return self._scale
@scale.setter
def scale(self, x):
self.setScale(x)
@property
def first(self):
"""int. First octave to generate."""
return self._first
@first.setter
def first(self, x):
self.setFirst(x)
@property
def octaves(self):
"""int. Number of octaves to generate."""
return self._octaves
@octaves.setter
def octaves(self, x):
self.setOctaves(x)
@property
def type(self):
"""int. Unit in which pitch values are stored."""
return self._type
@type.setter
def type(self, x):
self.setType(x)
# Event Generators
##################
[docs]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.
"""
def __init__(self):
self.generator = None
self.master = None
self.stopEventsWhenDone = False
def _inspect_generator(self, generator):
# Inspect the value passed as a generator argument.
if type(generator) in [type([]), type(())]:
generator = EventSeq(generator)
elif type(generator) in [type(0), type(0.0)]:
generator = EventSeq([generator])
return generator
def _inspect_values(self, values):
# Inspect the value passed as a values argument.
if not values:
values = [0]
return values
def _inspect_occurrences(self, occurrences):
# Inspect the value passed as an occurrences argument.
if occurrences < 1:
occurrences = 1
return occurrences
def _internalGeneratorNextCall(self):
# Return the next value of an internal generator.
if isinstance(self.generator, EventKey):
if self.generator.needToResetTarget:
self.generator.needToResetTarget = False
try:
self.master[self.generator.getKey()].reset()
if self.generator.getKey() in self.master.getCurrentDict():
del self.master.getCurrentDict()[self.generator.getKey()]
except:
pass
value = getValueFromAttribute(self.master, self.generator.getKey(), self.master.getCurrentDict())
else:
self.generator.setMaster(self.master)
value = self.generator.next()
if value is None:
self.generator = None
return self.next()
return value
def _checkValueTypeAndIncrementCount(self, value):
# Final check of the value produced by the generator in the next() method.
self.count += 1
if isinstance(value, EventGenerator):
self.generator = value
self.generator.reset()
value = self.next()
elif isinstance(value, PyoObject):
value = value.get(False)
return value
def __add__(self, generator):
generator = self._inspect_generator(generator)
return EventDummy(self, generator, PYO_EVENT_OPERATOR_ADD)
def __sub__(self, generator):
generator = self._inspect_generator(generator)
return EventDummy(self, generator, PYO_EVENT_OPERATOR_SUB)
def __mul__(self, generator):
generator = self._inspect_generator(generator)
return EventDummy(self, generator, PYO_EVENT_OPERATOR_MUL)
def __div__(self, generator):
generator = self._inspect_generator(generator)
return EventDummy(self, generator, PYO_EVENT_OPERATOR_DIV)
def __truediv__(self, generator):
generator = self._inspect_generator(generator)
return EventDummy(self, generator, PYO_EVENT_OPERATOR_DIV)
def __pow__(self, generator):
generator = self._inspect_generator(generator)
return EventDummy(self, generator, PYO_EVENT_OPERATOR_POW)
def __mod__(self, generator):
generator = self._inspect_generator(generator)
return EventDummy(self, generator, PYO_EVENT_OPERATOR_MOD)
def __floordiv__(self, generator):
generator = self._inspect_generator(generator)
return EventDummy(self, generator, PYO_EVENT_OPERATOR_FLR)
def setMaster(self, master):
# Keep a reference of the master player (an Events object).
self.master = master
def copy(self):
# Return a deep copy of this generator (used in Events.events()).
return copy.deepcopy(self)
def reset(self):
# Reset the generator to its init state. Implemented in child objects.
pass
def next(self):
# Internally called to produce the next value. Implemented in child objects.
pass
def resetEmbeddedGenerator(self):
# Recursively resets embedded generators. Used when starting a sequence.
if self.generator is not None:
self.generator.resetEmbeddedGenerator()
self.generator.reset()
[docs] def floor(self):
"""
Return an EventFilter computing the largest integer less than or
equal to its input value.
"""
return EventFilter(self, PYO_EVENT_FILTER_FLOOR)
[docs] def ceil(self):
"""
Return an EventFilter computing the smallest integer greater than or
equal to its input value.
"""
return EventFilter(self, PYO_EVENT_FILTER_CEIL)
[docs] def round(self):
"""
Return an EventFilter computing the nearest integer to its input value.
If two values are equally close, rounding is done toward the even choice.
"""
return EventFilter(self, PYO_EVENT_FILTER_ROUND)
[docs] def abs(self):
"""
Return an EventFilter computing the absolute value of its input value.
"""
return EventFilter(self, PYO_EVENT_FILTER_ABS)
[docs] def snap(self, 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.
"""
return EventFilter(self, PYO_EVENT_FILTER_SNAP, choice)
[docs] def deviate(self, 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.
"""
return EventFilter(self, PYO_EVENT_FILTER_DEVIATE, depth)
[docs] def clip(self, 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.
"""
return EventFilter(self, PYO_EVENT_FILTER_CLIP, mini, maxi)
[docs] def scale(self, 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.
"""
return EventFilter(self, PYO_EVENT_FILTER_SCALE, mini, maxi, expon)
[docs] def rescale(self, 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.
"""
return EventFilter(self, PYO_EVENT_FILTER_RESCALE, inmin, inmax, outmin, outmax, expon)
[docs] def iftrue(self, 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.
"""
return EventFilter(self, PYO_EVENT_FILTER_IFTRUE, op, comp)
[docs]class EventDummy(EventGenerator):
"An EventGenerator created internally to handle arithmetic on Events."
def __init__(self, generator1, generator2, type):
EventGenerator.__init__(self)
self.generator1 = generator1
self.generator2 = generator2
self.type = type
def next(self):
self.generator1.setMaster(self.master)
v1 = self.generator1.next()
if isinstance(self.generator2, PyoObject):
v2 = self.generator2.get(False)
else:
self.generator2.setMaster(self.master)
v2 = self.generator2.next()
if v1 is None or v2 is None:
return None
else:
if self.type == PYO_EVENT_OPERATOR_ADD:
return v1 + v2
elif self.type == PYO_EVENT_OPERATOR_SUB:
return v1 - v2
elif self.type == PYO_EVENT_OPERATOR_MUL:
return v1 * v2
elif self.type == PYO_EVENT_OPERATOR_DIV:
return v1 / v2
elif self.type == PYO_EVENT_OPERATOR_POW:
return v1 ** v2
elif self.type == PYO_EVENT_OPERATOR_MOD:
return v1 % v2
elif self.type == PYO_EVENT_OPERATOR_FLR:
return math.floor(v1 / v2 + 0.5) * v2
[docs]class EventFilter(EventGenerator):
"An EventGenerator created internally to handle simple filter on Events."
def __init__(self, generator, type, *args):
EventGenerator.__init__(self)
self.generator = generator
self.type = type
self.args = args
self.lastValue = 0.0
def next(self):
self.generator.setMaster(self.master)
value = self.generator.next()
if value is None:
return None
args = []
for arg in self.args:
if isinstance(arg, PyoObject):
args.append(arg.get(False))
elif isinstance(arg, EventGenerator):
arg.setMaster(self.master)
args.append(arg.next())
else:
args.append(arg)
if self.type == PYO_EVENT_FILTER_FLOOR:
return math.floor(value)
elif self.type == PYO_EVENT_FILTER_CEIL:
return math.ceil(value)
elif self.type == PYO_EVENT_FILTER_ROUND:
return round(value)
elif self.type == PYO_EVENT_FILTER_ABS:
return abs(value)
elif self.type == PYO_EVENT_FILTER_SNAP:
return min(args[0], key=lambda x: abs(x - value))
elif self.type == PYO_EVENT_FILTER_DEVIATE:
depth = args[0] * 0.01
return value * random.uniform(1.0 - depth, 1.0 + depth)
elif self.type == PYO_EVENT_FILTER_CLIP:
if value < args[0]:
value = args[0]
elif value > args[1]:
value = args[1]
return value
elif self.type == PYO_EVENT_FILTER_SCALE:
if value < 0.0:
value = 0.0
elif value > 1.0:
value = 1.0
value = value ** args[2]
return value * (args[1] - args[0]) + args[0]
elif self.type == PYO_EVENT_FILTER_RESCALE:
if value < args[0]:
value = args[0]
elif value > args[1]:
value = args[1]
value = (value - args[0]) / (args[1] - args[0])
value = value ** args[4]
return value * (args[3] - args[2]) + args[2]
elif self.type == PYO_EVENT_FILTER_IFTRUE:
if args[0] == "<":
istrue = value < args[1]
elif args[0] == "<=":
istrue = value <= args[1]
elif args[0] == ">":
istrue = value > args[1]
elif args[0] == ">=":
istrue = value >= args[1]
elif args[0] == "==":
istrue = value == args[1]
elif args[0] == "!=":
istrue = value != args[1]
if istrue:
self.lastValue = value
return value
else:
return self.lastValue
###################
[docs]class EventKey(EventGenerator):
"""
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()
"""
def __init__(self, key, master=None):
EventGenerator.__init__(self)
self.key = key
self.needToResetTarget = False
self.externalMaster = master
[docs] def getKey(self):
"""
Returns the key, as a string, of the parameter to read from.
"""
return self.key
def reset(self):
self.needToResetTarget = True
def next(self):
if self.externalMaster is None:
return getValueFromAttribute(self.master, self.getKey(), self.master.getCurrentDict())
else:
return getValueFromAttribute(self.externalMaster, self.getKey(), self.externalMaster.getCurrentDict())
###################
[docs]class EventSeq(EventGenerator):
"""
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()
"""
def __init__(self, values, occurrences=inf, stopEventsWhenDone=True):
EventGenerator.__init__(self)
self.values = self._inspect_values(values)
self.occurrences = self._inspect_occurrences(occurrences)
self.length = len(self.values)
self.stopEventsWhenDone = stopEventsWhenDone
self.reset()
def __len__(self):
return self.length * self.occurrences
def reset(self):
self.generator = None
self.count = self.completed = 0
def next(self):
if self.generator is not None:
return self._internalGeneratorNextCall()
self.length = len(self.values)
if self.count < self.length:
value = self.values[self.count]
return self._checkValueTypeAndIncrementCount(value)
else:
self.completed += 1
if self.completed >= self.occurrences:
return None
else:
self.count = 0
return self.next()
[docs]class EventSlide(EventGenerator):
"""
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()
"""
def __init__(self, values, segment, step, startpos=0, wraparound=True, occurrences=inf, stopEventsWhenDone=True):
EventGenerator.__init__(self)
self.values = self._inspect_values(values)
self.occurrences = self._inspect_occurrences(occurrences)
self.wraparound = wraparound
self.length = len(self.values)
self.stopEventsWhenDone = stopEventsWhenDone
self.segment = segment
self.lastSegment = 1
self.step = step
self.lastStep = 1
if startpos < 0:
self.startpos = self.length + startpos
else:
self.startpos = startpos
self.reset()
def __len__(self):
return self.segment * self.occurrences
def reset(self):
self.generator = None
self.count = self.completed = 0
self.start = self.startpos
if isinstance(self.segment, EventGenerator):
self.segment.reset()
if isinstance(self.step, EventGenerator):
self.step.reset()
def getStepValue(self):
if isinstance(self.step, PyoObject):
value = self.step.get(False)
elif isinstance(self.step, EventGenerator):
self.step.setMaster(self.master)
value = self.step.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastStep
else:
value = self.step
if abs(value) >= self.length:
if value < 0:
value = -(self.length - 1)
else:
value = self.length - 1
self.lastStep = int(value)
return self.lastStep
def getSegmentValue(self):
if isinstance(self.segment, PyoObject):
value = self.segment.get(False)
elif isinstance(self.segment, EventGenerator):
self.segment.setMaster(self.master)
value = self.segment.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastSegment
else:
value = self.segment
if value < 1:
value = 1
self.lastSegment = int(value)
return self.lastSegment
def next(self):
if self.generator is not None:
return self._internalGeneratorNextCall()
self.length = len(self.values)
segment = self.getSegmentValue()
step = self.getStepValue()
if segment is None or step is None:
return None
if self.count < segment:
if step < 0:
position = self.start - self.count
else:
position = self.start + self.count
if position < 0:
if self.wraparound:
position += self.length
else:
return None
elif position >= self.length:
if self.wraparound:
position -= self.length
else:
return None
value = self.values[position]
return self._checkValueTypeAndIncrementCount(value)
else:
self.completed += 1
if self.completed >= self.occurrences:
return None
else:
self.count = 0
self.start += step
if self.start < 0:
self.start += self.length
elif self.start >= self.length:
self.start -= self.length
return self.next()
[docs]class EventIndex(EventGenerator):
"""
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()
"""
def __init__(self, values, index, occurrences=inf, stopEventsWhenDone=True):
EventGenerator.__init__(self)
self.values = self._inspect_values(values)
self.occurrences = self._inspect_occurrences(occurrences)
self.index = index
self.lastIndex = 0
self.length = len(self.values)
self.stopEventsWhenDone = stopEventsWhenDone
self.reset()
def __len__(self):
return self.occurrences
def reset(self):
self.generator = None
self.count = 0
if isinstance(self.index, EventGenerator):
self.index.reset()
def getIndexValue(self):
if isinstance(self.index, PyoObject):
value = self.index.get(False)
elif isinstance(self.index, EventGenerator):
self.index.setMaster(self.master)
value = self.index.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastIndex
else:
value = self.index
if value < 0:
value = 0
elif value >= self.length:
value = self.length - 1
self.lastIndex = int(value)
return self.lastIndex
def next(self):
if self.generator is not None:
return self._internalGeneratorNextCall()
self.length = len(self.values)
index = self.getIndexValue()
if index is None:
return None
if self.count < self.occurrences:
value = self.values[index]
return self._checkValueTypeAndIncrementCount(value)
else:
return None
[docs]class EventMarkov(EventGenerator):
"""
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()
"""
def __init__(self, values, order=2, occurrences=inf, stopEventsWhenDone=True):
EventGenerator.__init__(self)
self.values = self._inspect_values(values)
self.occurrences = self._inspect_occurrences(occurrences)
self.lastOrder = self.order = order
self.length = len(self.values)
self.stopEventsWhenDone = stopEventsWhenDone
self.markov = MarkovGen(values)
self.reset()
def __len__(self):
return self.occurrences
def reset(self):
self.generator = None
self.count = 0
if isinstance(self.order, EventGenerator):
self.order.reset()
def getOrderValue(self):
if isinstance(self.order, PyoObject):
value = self.order.get(False)
elif isinstance(self.order, EventGenerator):
self.order.setMaster(self.master)
value = self.order.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastOrder
else:
value = self.order
if value < 0:
value = 0
elif value > 10:
value = 10
self.lastOrder = int(value)
return self.lastOrder
def next(self):
if self.generator is not None:
return self._internalGeneratorNextCall()
order = self.getOrderValue()
if order is None:
return None
self.markov.setOrder(order)
if self.count < self.occurrences:
value = self.markov.next()
return self._checkValueTypeAndIncrementCount(value)
else:
return None
###################
[docs]class EventChoice(EventGenerator):
"""
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()
"""
def __init__(self, values, occurrences=inf, stopEventsWhenDone=True):
EventGenerator.__init__(self)
self.values = self._inspect_values(values)
self.occurrences = self._inspect_occurrences(occurrences)
self.length = len(self.values)
self.stopEventsWhenDone = stopEventsWhenDone
self.reset()
def __len__(self):
return self.occurrences
def reset(self):
self.generator = None
self.count = 0
def next(self):
if self.generator is not None:
return self._internalGeneratorNextCall()
self.length = len(self.values)
if self.count < self.occurrences:
value = random.choice(self.values)
return self._checkValueTypeAndIncrementCount(value)
else:
return None
[docs]class EventDrunk(EventGenerator):
"""
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()
"""
def __init__(self, values, maxStep=2, occurrences=inf, stopEventsWhenDone=True):
EventGenerator.__init__(self)
self.values = self._inspect_values(values)
self.occurrences = self._inspect_occurrences(occurrences)
self.lastMaxStep = self.maxStep = maxStep
self.length = len(self.values)
self.stopEventsWhenDone = stopEventsWhenDone
self.reset()
def __len__(self):
return self.occurrences
def reset(self):
self.generator = None
self.allowRepetition = True
self.count = 0
self.index = int(self.length / 2)
if isinstance(self.maxStep, EventGenerator):
self.maxStep.reset()
def getMaxStepValue(self):
if isinstance(self.maxStep, PyoObject):
value = self.maxStep.get(False)
elif isinstance(self.maxStep, EventGenerator):
self.maxStep.setMaster(self.master)
value = self.maxStep.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastMaxStep
else:
value = self.maxStep
self.allowRepetition = True
if value < 0:
value = -value
self.allowRepetition = False
elif value >= self.length:
value = self.length - 2
self.lastMaxStep = int(value)
return self.lastMaxStep
def next(self):
if self.generator is not None:
return self._internalGeneratorNextCall()
self.length = len(self.values)
maxStep = self.getMaxStepValue()
if maxStep is None:
return None
if self.count < self.occurrences:
dev = random.randint(-maxStep, maxStep)
while dev == 0 and not self.allowRepetition:
dev = random.randint(-maxStep, maxStep)
self.index += dev
if self.index < 0:
self.index = -self.index - dev + 1
elif self.index >= self.length:
self.index = self.length - (self.index - self.length) - dev - 1
value = self.values[self.index]
return self._checkValueTypeAndIncrementCount(value)
else:
return None
[docs]class EventNoise(EventGenerator):
"""
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()
"""
def __init__(self, type=0, occurrences=inf, stopEventsWhenDone=True):
EventGenerator.__init__(self)
self.lastType = self.type = type
self.occurrences = self._inspect_occurrences(occurrences)
self.stopEventsWhenDone = stopEventsWhenDone
self.reset()
def __len__(self):
return self.occurrences
def reset(self):
self.count = 0
self.y1 = 0.0
self.c0 = self.c1 = self.c2 = self.c3 = self.c4 = self.c5 = self.c6 = 0.0
def getTypeValue(self):
if isinstance(self.type, PyoObject):
value = self.type.get(False)
elif isinstance(self.type, EventGenerator):
self.type.setMaster(self.master)
value = self.type.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastType
else:
value = self.type
if value < 0:
value = 0
elif value > 2:
value = 2
self.lastType = int(value)
return self.lastType
def next(self):
type = self.getTypeValue()
if type is None:
return None
if self.count < self.occurrences:
if type == 0:
return self._checkValueTypeAndIncrementCount(random.uniform(-1.0, 1.0))
elif type == 1:
rnd = random.uniform(-0.99, 0.99)
self.c0 = self.c0 * 0.99886 + rnd * 0.0555179
self.c1 = self.c1 * 0.99332 + rnd * 0.0750759
self.c2 = self.c2 * 0.96900 + rnd * 0.1538520
self.c3 = self.c3 * 0.86650 + rnd * 0.3104856
self.c4 = self.c4 * 0.55000 + rnd * 0.5329522
self.c5 = self.c5 * -0.7616 - rnd * 0.0168980
val = self.c0 + self.c1 + self.c2 + self.c3 + self.c4 + self.c5 + self.c6 + rnd * 0.5362
self.c6 = rnd * 0.115926
return self._checkValueTypeAndIncrementCount(val * 0.2)
else:
rnd = random.uniform(-0.99, 0.99)
self.y1 = rnd + (self.y1 - rnd) * 0.996
return self._checkValueTypeAndIncrementCount(self.y1 * 20.0)
else:
return None
###################
[docs]class EventCall(EventGenerator):
"""
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()
"""
def __init__(self, function, *args, **kwargs):
EventGenerator.__init__(self)
self.function = function
self.args = args
self.occurrences = self._inspect_occurrences(kwargs.pop("occurrences", inf))
self.stopEventsWhenDone = kwargs.pop("stopEventsWhenDone", True)
self.reset()
def __len__(self):
return self.occurrences
def reset(self):
self.generator = None
self.count = 0
def next(self):
if self.generator is not None:
return self._internalGeneratorNextCall()
args = []
for arg in self.args:
if isinstance(arg, PyoObject):
args.append(arg.get(False))
elif isinstance(arg, EventGenerator):
arg.setMaster(self.master)
args.append(arg.next())
else:
args.append(arg)
if self.count < self.occurrences:
value = self.function(*args)
return self._checkValueTypeAndIncrementCount(value)
else:
return None
###################
[docs]class EventConditional(EventGenerator):
"""
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()
"""
def __init__(self, condition, iftrue, iffalse, occurrences=inf, stopEventsWhenDone=True):
EventGenerator.__init__(self)
self.condition = self._inspect_generator(condition)
self.iftrue = self._inspect_generator(iftrue)
self.iffalse = self._inspect_generator(iffalse)
self.occurrences = self._inspect_occurrences(occurrences)
self.stopEventsWhenDone = stopEventsWhenDone
self.reset()
def __len__(self):
return self.occurrences
def reset(self):
self.count = 0
self.lastCondition = self.lastIftrue = self.lastIffalse = 0
def getConditionValue(self):
if isinstance(self.condition, PyoObject):
value = self.condition.get(False)
elif isinstance(self.condition, EventGenerator):
self.condition.setMaster(self.master)
value = self.condition.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastCondition
else:
value = self.condition
self.lastCondition = value
return self.lastCondition
def getIftrueValue(self):
if isinstance(self.iftrue, PyoObject):
value = self.iftrue.get(False)
elif isinstance(self.iftrue, EventGenerator):
self.iftrue.setMaster(self.master)
value = self.iftrue.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastIftrue
else:
value = self.iftrue
self.lastIftrue = value
return self.lastIftrue
def getIffalseValue(self):
if isinstance(self.iffalse, PyoObject):
value = self.iffalse.get(False)
elif isinstance(self.iffalse, EventGenerator):
self.iffalse.setMaster(self.master)
value = self.iffalse.next()
if value is None:
if self.stopEventsWhenDone:
return None
else:
value = self.lastIffalse
else:
value = self.iffalse
self.lastIffalse = value
return self.lastIffalse
def next(self):
condition = self.getConditionValue()
if condition is None:
return None
if self.count < self.occurrences:
if condition:
value = self.getIftrueValue()
else:
value = self.getIffalseValue()
if value is None:
return None
else:
return self._checkValueTypeAndIncrementCount(value)
else:
return None
# Event Player
##############
[docs]class Events(dict):
"""
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()
"""
def __init__(self, **args):
# Instrument key
self["instr"] = DefaultInstrument
self["signal"] = None
# Constant keys
self["bpm"] = 120
self["outs"] = 2
# Duration keys
self["dur"] = 1
self["beat"] = None
self["durmul"] = 1
self["tail"] = 2
# Amplitude keys
self["amp"] = 0.7
self["db"] = None
self["midivel"] = None
# Envelope keys
self["envelope"] = None
self["attack"] = 0.005
self["decay"] = None
self["sustain"] = 0.7
self["release"] = 0.05
# Pitch keys
self["freq"] = 250
self["midinote"] = None
self["degree"] = None
self["transpo"] = 0
# Ending keys
self["atend"] = None
self.instanceId = 0
self.maxInstanceId = 2 ** 31
# Add user-supplied arguments as dict attributes.
for item in args.items():
self[item[0]] = item[1]
self.callNextEvent = Pattern(self._processEvent).stop()
self.currentDict = {}
self.output = Sig([0] * self["outs"])
[docs] def events(self):
""" Return a copy of this Events object. """
evts = Events()
for attr in list(self):
try:
evts[attr] = self[attr].copy()
except:
evts[attr] = self[attr]
return evts
[docs] def play(self, 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.
"""
if not issubclass(self["instr"], EventInstrument):
print("`instr` argument must be a sub-class of EventInstrument...")
print("... Events is using DefaultInstrument!")
self["instr"] = DefaultInstrument
self.actives = {}
self.callAtEnd = None
if callable(self["atend"]):
self.callAtEnd = CallAfter(self["atend"], 0).stop()
for key in [k for k in self.keys() if k not in ["instr", "signal", "bpm", "outs", "atend"]]:
if self[key] is None or isinstance(self[key], PyoObjectBase):
pass
elif type(self[key]) in [type([]), type(())]:
self[key] = EventSeq(self[key])
elif type(self[key]) in [type(0), type(0.0)]:
self[key] = EventSeq([self[key]])
else:
self[key].resetEmbeddedGenerator()
self[key].reset()
self.callNextEvent.play(dur=dur, delay=delay)
return self
[docs] def stop(self, wait=0):
"""
Stop the events playback.
:Args:
wait: float, optional
Delay, in seconds, before the process is actually stopped.
Defaults to 0.
"""
self.callNextEvent.stop(wait=wait)
def getCurrentDict(self):
return self.currentDict
[docs] def sig(self):
"""
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.
"""
return self.output
def _processEvent(self):
"""Create instrument instances and add them to the active list."""
quarterDur = 60.0 / self["bpm"]
self.currentDict = {
"removeFunction": self._remove,
"bpm": self["bpm"],
"outs": self["outs"],
"instanceId": self.instanceId,
}
# Compute time before next event and current event's duration.
if self["beat"] is not None:
nextBeat = getValueFromAttribute(self, "beat", self.currentDict)
if nextBeat is not None:
nextDurMul = getValueFromAttribute(self, "durmul", self.currentDict)
if nextDurMul is not None:
timeBeforeNextEvent = quarterDur * nextBeat
self.currentDict["dur"] = timeBeforeNextEvent * nextDurMul
else:
nextDur = getValueFromAttribute(self, "dur", self.currentDict)
if nextDur is not None:
nextDurMul = getValueFromAttribute(self, "durmul", self.currentDict)
if nextDurMul is not None:
timeBeforeNextEvent = nextDur
self.currentDict["dur"] = timeBeforeNextEvent * nextDurMul
if "dur" not in self.currentDict:
self.callNextEvent.stop()
return
else:
self.callNextEvent.time = timeBeforeNextEvent
ending = False
# Process event's every other attributes.
proscribe = ["dur", "beat", "instr", "bpm", "outs", "midinote", "degree", "db", "midivel", "atend", "signal"]
for arg in [k for k in self.keys() if k not in proscribe]:
if arg == "freq":
transpo = getValueFromAttribute(self, "transpo", self.currentDict, valueIfNone=0)
transpo = midiToTranspo(transpo + 60)
self.currentDict["transpo"] = transpo
if self["midinote"] is not None:
midiNote = getValueFromAttribute(self, "midinote", self.currentDict)
if midiNote is not None:
self.currentDict["midinote"] = midiNote
self.currentDict["freq"] = midiToHz(midiNote) * transpo
elif self["midinote"].stopEventsWhenDone:
ending = True
elif self["degree"] is not None:
degree = getValueFromAttribute(self, "degree", self.currentDict)
if degree is not None:
midiNote = degreeToMidiNote(degree)
self.currentDict["midinote"] = midiNote
self.currentDict["freq"] = midiToHz(midiNote) * transpo
elif self["degree"].stopEventsWhenDone:
ending = True
else:
freq = getValueFromAttribute(self, "freq", self.currentDict)
if freq is not None:
self.currentDict["freq"] = freq * transpo
elif self["freq"].stopEventsWhenDone:
ending = True
elif arg == "amp":
if self["db"] is not None:
db = getValueFromAttribute(self, "db", self.currentDict)
if db is not None:
self.currentDict["db"] = db
self.currentDict["amp"] = pow(10.0, db * 0.05)
elif self["db"].stopEventsWhenDone:
ending = True
elif self["midivel"] is not None:
midivel = getValueFromAttribute(self, "midivel", self.currentDict)
if midivel is not None:
midivel = max(min(midivel, 127), 0)
self.currentDict["midivel"] = midivel
self.currentDict["amp"] = midivel / 127.0
elif self["midivel"].stopEventsWhenDone:
ending = True
else:
amp = getValueFromAttribute(self, "amp", self.currentDict)
if amp is not None:
self.currentDict["amp"] = amp
elif self["amp"].stopEventsWhenDone:
ending = True
elif self[arg] == None:
self.currentDict[arg] = None
else:
value = getValueFromAttribute(self, arg, self.currentDict)
if value is not None:
self.currentDict[arg] = value
elif self[arg].stopEventsWhenDone:
ending = True
if ending:
if self.callAtEnd is not None:
self.callAtEnd.play()
self.callNextEvent.stop()
else:
self.actives[self.instanceId] = self["instr"](**self.currentDict)
if self["signal"] is not None:
self.output.value = sum(
[
getattr(instr, self["signal"])
for instr in self.actives.values()
if hasattr(instr, self["signal"])
]
)
self.instanceId += 1
if self.instanceId >= self.maxInstanceId:
self.instanceId = 0
def _remove(self, instanceId):
""" Removes an instrument instance from the active list. """
if instanceId in self.actives:
del self.actives[instanceId]
if self["signal"] is not None:
self.output.value = sum(
[getattr(instr, self["signal"]) for instr in self.actives.values() if hasattr(instr, self["signal"])]
)