pyo.lib.events — Pyo 1.0.4 documentation

Pyo 1.0.4 documentation

# Source code for pyo.lib.events

    """
    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
    #############
    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
    #############
    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

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

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

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

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

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

        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)

        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)

        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)

        def abs(self):
            """
            Return an EventFilter computing the absolute value of its input value.

            """
            return EventFilter(self, PYO_EVENT_FILTER_ABS)

        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)

        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)

        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)

        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)

        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)

        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)

    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

    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

    ###################
    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

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

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

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

    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

    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

    ###################
    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

    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

    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

    ###################
    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

    ###################
    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
    ##############
    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"])

        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

        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

        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

        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"])]
                )