Prefix expression evaluators¶

Prefix audio expression evaluator.

This family implements a tiny functional programming language that can be used to write synthesis or signal processing algorithms.

Objects in this category¶

Expr : Prefix audio expression evaluator.

API documentation¶

This API is in alpha stage and subject to future changes!

Builtin functions¶

Arithmetic operators

(+ x y) : returns the sum of two values.
(- x y) : substracts the second value to the first and returns the result.
(* x y) : returns the multiplication of two values.
(/ x y) : returns the quotient of x/y.
(^ x y) : returns x to the power y.
(% x y) : returns the floating-point remainder of x/y.
(neg x) : returns the negative of x.

Moving phase operators

(++ x y) : increments its internal state by x and wrap around 0.0 and y.
(– x y) : decrements its internal state by x and wrap around 0.0 and y.
(~ x y) : generates a periodic ramp from 0 to 1 with frequency x and phase y.

Conditional operators

(< x y) : returns 1 if x is less than y, otherwise returns 0.
(<= x y) : returns 1 if x is less than or equal to y, otherwise returns 0.
(> x y) : returns 1 if x is greater than y, otherwise returns 0.
(>= x y) : returns 1 if x is greater than or equal to y, otherwise returns 0.
(== x y) : returns 1 if x is equal to y, otherwise returns 0.
(!= x y) : returns 1 if x is not equal to y, otherwise returns 0.
(if (cond) (then) (else)) : returns then for any non-zero value of cond, otherwise returns else.
(and x y) : returns 1 if both x and y are not 0, otherwise returns 0.
(or x y) : returns 1 if one of x or y are not 0, otherwise returns 0.

Trigonometric functions

(sin x) : returns the sine of an angle of x radians.
(cos x) : returns the cosine of an angle of x radians.
(tan x) : returns the tangent of x radians.
(tanh x) : returns the hyperbolic tangent of x radians.
(atan x) : returns the principal value of the arc tangent of x, expressed in radians.
(atan2 x y) : returns the principal value of the arc tangent of y/x, expressed in radians.

Power and logarithmic functions

(sqrt x) : returns the square root of x.
(log x) : returns the natural logarithm of x.
(log2 x) : returns the binary (base-2) logarithm of x.
(log10 x) : returns the common (base-10) logarithm of x.
(pow x y) : returns x to the power y.

Clipping functions

(abs x) : returns the absolute value of x.
(floor x) : rounds x downward, returning the largest integral value that is not greater than x.
(ceil x) : rounds x upward, returning the smallest integral value that is not less than x.
(exp x) : returns the constant e to the power x.
(round x) : returns the integral value that is nearest to x.
(min x y) : returns the smaller of its arguments: either x or y.
(max x y) : returns the larger of its arguments: either x or y.
(wrap x) : wraps x between 0 and 1.

Random fuctions

(randf x y) : returns a pseudo-random floating-point number in the range between x and y.
(randi x y) : returns a pseudo-random integral number in the range between x and y.

Complex numbers

(complex x y) : returns a complex number where x is the real part and y the imaginary part.
(real x) : returns the real part of the complex number x.
(imag x) : returns the imaginary part of the complex number x.

Filter functions

(delay x) : one sample delay.
(sah x y) : samples and holds x value whenever y is smaller than its previous state.
(rpole x y) : real one-pole recursive filter. returns x + last_out * y.
(rzero x y) : real one-zero non-recursive filter. returns x - last_x * y.
(cpole x y) : complex one-pole recursive filter. x is the complex signal to filter, y is a complex coefficient, it returns a complex signal.
(czero x y) : complex one-zero non-recursive filter. x is the complex signal to filter, y is a complex coefficient, it returns a complex signal.

Multi-output function

(out x y) : If using multiple outputs, creates an audio stream where x is the output channel and y the signal to write to the channel.

Constants

(const x) : returns x.
pi : returns an approximated value of pi.
twopi : returns a constant with value pi*2.
e : returns an approximated value of e.
sr : returns the current sampling rate.

Comments¶

A comment starts with two slashs ( // ) and ends at the end of the line:

// This is a comment!

Input and Output signals¶

User has access to the last buffer size of input and output samples.

To use samples from past inputs, use $x0[n] notation, where 0 is the first audio stream ($x1[0] would retrieve the second audio stream) and n is the position from the current time. $x0[0] is the current input sample, $x0[-1] is the previous one and $x0[-buffersize] is the last available input sample.

The first audio stream can also simply be named $x[0] ($x[0] is the same as $x0[0]).

To use samples from past output, use $y0[n] notation, where 0 is the first output audio stream ($y1[0] would retrieve the second output audio stream) and n is the position from the current time. $y0[-1] is the previous output and $y0[-buffersize] is the last available output sample of the stream.

The first output audio stream can also simply be named $y[-1] ($y[-1] is the same as $y0[-1]).

If the object generates only one channel output (the default), the last expression in the script is the output signal. Otherwise, output signals must be created with the out function.

Here an example of a first-order IIR lowpass filter expression:

// A first-order IIR lowpass filter
+ $x[0] (* (- $y[-1] $x[0]) 0.99)

A simple ring-modulation expression:

// ring-modulation between the first two input signals
* $x[0] $x1[0]

Two output channels:

// First channel
(out 0 (sin (* (twopi) (~ 400))))
// Second channel
(out 1 (sin (* (twopi) (~ 500))))

Defining custom functions¶

The define keyword starts the definition of a custom function:

(define funcname (body))

funcname is the name used to call the function in the expression and body is the sequence of functions to execute. Arguments of the function are extracted directly from the body. They must be named $1, $2, $3, …, $9.

Example of a sine wave function:

(define osc (
    sin (* (twopi) (~ $1))
    )
)
// play a sine wave
* (osc 440) 0.3

State variables¶

User can create state variable with the keyword let. This is useful to set an intermediate state to be used in multiple places in the processing chain. The syntax is:

(let #var (body))

The variable name must begin with a #:

(let #sr 44100)
(let #freq 1000)
(let #coeff (
    ^ (e) (/ (* (* -2 (pi)) #freq) #sr)
    )
)
+ $x[0] (* (- $y[-1] $x[0]) #coeff)

The variable is private to a function if created inside a custom function:

(let #freq 250) // global #freq variable
(define osc (
    (let #freq (* $1 $2)) // local #freq variable
    sin (* (twopi) (~ #freq))
    )
)
* (+ (osc 1 #freq) (osc 2 #freq)) 0.2

State variables can be used to do 1 sample feedback if used before created. Undefined variables are initialized to 0:

(define oscloop (
        (let #xsin
            (sin (+ (* (~ $1) (twopi)) (* #xsin $2))) // #xsin used before...
        ) // ... "let" statement finished!
        #xsin // oscloop function outputs #xsin variable
    )
)
* (oscloop 200 0.7) 0.3

A state variable can also contain a complex number:

(let #v (complex 0.2 0.7)) // #v = (0.2 0.7)

User variables¶

User variables are created with the keyword var:

(var #var (init))

The variable name must begin with a #.

They are computed only at initialization, but can be changed from the python script with method calls (varname is a string and value is a float):

obj.setVar(varname, value)

The following example shows how to control the cutoff fequency of a lowpass filter with a user variable:

expression = '''
(var #freq 1000)
(let #coeff (
    ^ e (/ (* (neg twopi) #freq) 44100)
    )
)
+ $x[0] (* (- $y[-1] $x[0]) #coeff)
'''
ex = Expr(Noise(0.5), expression).out()
freq = Sine(0.25).range(250, 10000)

def update():
    ex.setVar("#freq", freq.get())

pat = Pattern(update, 0.02).play()

Library importation¶

Custom functions can be defined in an external file and imported with the load function:

(load path/to/the/file)

The content of the file will be inserted where the load function is called and all functions defined inside the file will then be accessible. The path can be absolute or relative to the current working directory.

Complex numbers¶

A complex number is created with the complex function:

(complex x y)

We can retrieve one part of a complex number with real and imag functions:

// get the real part (x) of a number
(real (complex x y))

If a complex number is used somewhere not waiting for a complex, real value will be used.

If a real number is used somewhere waiting for a complex, the imaginary part is set to 0.0.

Examples¶

Here is some expression examples.

A first-order IIR lowpass filter:

(var #sr 44100)
(var #cutoff 1000)
(let #coeff (exp (/ (* (* -2 (pi)) #cutoff) #sr)))
+ $x[0] (* (- $y[-1] $x[0]) #coeff)

A LFO’ed hyperbolic tangent distortion:

// $1 = lfo frequency, $2 = lfo depth
(define lfo (
        (+ (* (sin (* (twopi) (~ $1))) (- $2 1)) $2)
    )
)
tanh (* $x[0] (lfo .25 10))

A triangle waveform generator (use Sig(0) as input argument to bypass input):

(var #freq 440)
// $1 = oscillator frequency
(define triangle (
        (let #ph (~ $1))
        (- (* (min #ph (- 1 #ph)) 4) 1)
    )
)
triangle #freq

Objects¶

Expr¶

class Expr(input, expr='', outs=1, initout=0.0, mul=1, add=0)[source]¶

Prefix audio expression evaluator.

Expr implements a tiny functional programming language that can be used to write synthesis or signal processing algorithms.

For documentation about the language, see the module’s documentation.

Parent

PyoObject

Args

input: PyoObject or list of PyoObjects: Input signal(s) to process. If given a multi-stream PyoObject or a list of PyoObjects, each stream ca be retrieved with the syntax $x0[0], $x1[0], $x2[0], etc. $x[0] is the same as $x0[0].
expr: str, optional: Expression to evaluate as a string.
outs: int, optional: Number of output signals generated by the object. If 1 (the default), the last expression in the script is the output signal. Otherwise, output signals must be created with the out function. Available at initialization time only.
initout: float, optional: Value used to initialize the output buffers. Use with caution! Defaults to 0.0.

>>> s = Server().boot()
>>> s.start()
>>> proc = '''
>>> (var #boost 1)
>>> (tanh (* $x[0] #boost))
>>> '''
>>> sf = SfPlayer(SNDS_PATH + "/transparent.aif", loop=True)
>>> ex = Expr(sf, proc, mul=0.4).out()
>>> lfo = Sine(freq=1).range(1, 20)
>>> def change():
...     ex.setVar("#boost", lfo.get())
>>> pat = Pattern(change, 0.02).play()

Public Data Attributes:

expr

string.

Inherited from PyoObject

`mul`	float or PyoObject.
`add`	float or PyoObject.

Public Methods:

`__init__`(input[, expr, outs, initout, mul, add])
`setExpr`(x)	Replace the expr attribute.
`printNodes`()	Print the list of current nodes.
`setVar`(varname, value)
`editor`([title, wxnoserver])	Opens the text editor for this object.

Inherited from PyoObject

`__init__`([mul, add])
`__add__`(x)
`__radd__`(x)
`__iadd__`(x)
`__sub__`(x)
`__rsub__`(x)
`__isub__`(x)
`__mul__`(x)
`__rmul__`(x)
`__imul__`(x)
`__truediv__`(x)
`__rtruediv__`(x)
`__itruediv__`(x)
`__div__`(x)
`__rdiv__`(x)
`__idiv__`(x)
`__pow__`(x)
`__rpow__`(x)
`__mod__`(x)
`__neg__`()
`__lt__`(x)	Return self<value.
`__le__`(x)	Return self<=value.
`__eq__`(x)	Return self==value.
`__ne__`(x)	Return self!=value.
`__gt__`(x)	Return self>value.
`__ge__`(x)	Return self>=value.
`__do_comp__`(comp, mode[, default])
`isPlaying`([all])	Returns True if the object is currently playing, otherwise, returns False.
`isOutputting`([all])	Returns True if the object is outputting.
`get`([all])	Return the first sample of the current buffer as a float.
`play`([dur, delay])	Start processing without sending samples to output.
`out`([chnl, inc, dur, delay])	Start processing and send samples to audio output beginning at chnl.
`stop`([wait])	Stop processing.
`mix`([voices])	Mix the object's audio streams into voices streams and return a Mix object.
`range`(min, max)	Adjust mul and add attributes according to a given range.
`setMul`(x)	Replace the mul attribute.
`setAdd`(x)	Replace the add attribute.
`setSub`(x)	Replace and inverse the add attribute.
`setDiv`(x)	Replace and inverse the mul attribute.
`set`(attr, value[, port, callback])	Replace any attribute with portamento.
`ctrl`([map_list, title, wxnoserver])	Opens a sliders window to control the parameters of the object.

Inherited from PyoObjectBase

`__init__`()
`dump`()	Print infos about the current state of the object.
`getBaseObjects`()	Return a list of Stream objects managed by the instance.
`getServer`()	Return a reference to the current Server object.
`getSamplingRate`()	Return the current sampling rate (samples per second), as a float.
`getBufferSize`()	Return the current buffer size (samples per buffer), as an integer.
`allowAutoStart`([switch])	When autoStartChildren is activated in the Server, call this method with False as argument to stop the propagation of play/out/stop methods to and from this object.
`useWaitTimeOnStop`()	When autoStartChildren is activated in the Server, call this method to force an object given to the mul attribute of another object to use the wait time from the stop method instead of being stopped immediately.
`addLinkedObject`(x)	When autoStartChildren is activated in the Server, use this method to explicitly add an object in a dsp chain, which is generally controlled by the last object of the chain.
`setStopDelay`(x)	Set a specific waiting time when calling the stop method on this object.
`getStopDelay`()	Return the waiting time applied when calling the stop method on this object.
`__iter__`()
`__next__`()
`next`()	Alias for __next__ method.
`__getitem__`(i)
`__setitem__`(i, x)
`__len__`()
`__repr__`()	Return repr(self).
`__dir__`()	Default dir() implementation.

Private Data Attributes:

Inherited from PyoObject

_STREAM_TYPE

Inherited from PyoObjectBase

_STREAM_TYPE

Private Methods:

`_get_matching_bracket_pos`(x, p1)
`_replace`(x, lst)
`_change_var_names`(funcname, funcbody)
`_preproc`(x)

Inherited from PyoObject

`_init_play`()
`_reset_from_set`([attr])

Inherited from PyoObjectBase

`_autoplay`([dur, delay])
`_autostop`([wait])

setExpr(x)[source]¶

Replace the expr attribute.

Args

x: string: New expression to process.

printNodes()[source]¶: Print the list of current nodes.

editor(title='Expr Editor', wxnoserver=False)[source]¶

Opens the text editor for this object.

Args

title: string, optional: Title of the window. If none is provided, the name of the class is used.
wxnoserver: boolean, optional: With wxPython graphical toolkit, if True, tells the interpreter that there will be no server window.

If wxnoserver is set to True, the interpreter will not wait for the server GUI before showing the controller window.

property expr¶: string. New expression to process.

Table of Contents

Search

Prefix expression evaluators¶

Objects in this category¶

API documentation¶

Builtin functions¶

Comments¶

Input and Output signals¶

Defining custom functions¶

State variables¶

User variables¶

Library importation¶

Complex numbers¶

Examples¶

Objects¶

Expr¶