API

Wrapper

class faust_ctypes.wrapper.Faust(dll, sr=44100)

a python object wrapping a whole DSP DLL

groups processor, interface and metadata, and ensure that they are consistently initialized together

initialize the wrapper

Parameters:
  • dll (string or file-like or ctypes.CDLL) – the dynamically linked library

  • sr (int) – the sampling rate (unused as of now)

For convenience, a Faust wrapper can be initialized either with a DLL object :

>>> dll = ctypes.CDLL("../tests/dsp/minimal.so")
>>> dsp = wrapper.Faust(dll)
>>> dsp
<faust_ctypes.wrapper.Faust object at ...>

or directly with a path pointing to the library

>>> dsp = wrapper.Faust("../tests/dsp/minimal.so")
>>> dsp
<faust_ctypes.wrapper.Faust object at ...>

Processor

class faust_ctypes.processor.Processor(dll, dsp_p)

Python object wrapping the processing part of a dll

initialize the processor

Parameters:
  • dll (ctypes.CDLL) – the dynamically linked library

  • dsp_p (ctypes.c_void_p) – a pointer to the C dsp object

check_match(iodat, nsamples=-1)

checks if an input/output matches the dsp

Parameters:
  • iodat – the input/output data structure to test

  • nsamples – strictly negative if input, number of desired samples if output

Raises:
  • TypeError – if the array type doesn’t match DSP’s FAUSTFLOAT type

  • ValueError – if the shape of the array doesn’t match DSP’s i/o

compute(audio_in, audio_out=None)

process an array with the dsp

Parameters:
  • audio_in (int or numpy.ndarray) – the array to be processed or the number of samples if dsp is a synthesizer

  • audio_out (numpy.ndarray or None) – (optional) the target array

Returns:

the array containing the processed signal (audio_out if given)

from_obj(obj)

generate a numpy array from an object

Parameters:

obj (numpy-compatible object) – the object

Returns:

a numpy array that can be an input (provided correct row number)

Return type:

numpy.ndarray

gen_io(nsamples, isout=False, init=True)

generate a correct input/output 2D array

Parameters:
  • nsamples (int) – number of samples to generate

  • isout (bool) – (optional) False if input True if output

  • init (bool) – wether to initialize or not the array

Returns:

an input/output structure that is certified to be DSP-compatible

Return type:

DSP-compatible io)

prepare(audio_in, audio_out)

make an inner representation of i/o arrays to compute them handles indirect memory layout (unsupported by NumPy https://stackoverflow.com/questions/64815148/)

In the special case of synthesizer, audio_in can be anything

Parameters:
  • audio_in (numpy.ndarray) – the array to be processed

  • audio_out (numpy.ndarray) – the target array

process(nsamples)

small wrapper around C function computemydsp

can be useful if last input array has been modified avoid re-check and re-generation of indirect memory layout

Parameters:

nsamples (int) – number of samples

User Interface

class faust_ctypes.interface.Box(label, layout)

Box containing widgets (from FAUSTPy)

Parameters:
  • label (bytes) – the label of the box

  • layout (str) – the layout of the box, “horizontal”, “vertical” or “tab”

class faust_ctypes.interface.Param(label, zone, init, min, max, step, param_type)

A UI parameter object (from FAUSTPy)

This objects represents a FAUST UI input. It makes sure to enforce the constraints specified by the minimum, maximum and step size.

This object implements the descriptor protocol: reading it works just like normal objects, but assignment is redirects to its “zone” attribute.

Parameters:
  • label – The full label as specified in the FAUST DSP file.

  • zone – Points to the FAUSTFLOAT object inside the DSP C object.

  • init – The initialisation value.

  • min – The minimum allowed value.

  • max – The maximum allowed value.

  • step – The step size of the parameter.

  • paramtype – The parameter type (e.g., HorizontalSlider)

property zone

Pointer to the value of the parameter.

class faust_ctypes.interface.UserInterface(GlueClass, obj=None)

(from FAUSTPy) Maps the UI elements of a FAUST DSP to attributes of another object, specifically a FAUST wrapper object.

In FAUST, UI’s are specified by the DSP object, which calls methods of a UI object to create them. The PythonUI class implements such a UI object. It creates C callbacks to its methods and stores then in a UI struct, which can then be passed to the buildUserInterface() function of a FAUST DSP object.

The DSP object basically calls the methods of the PythonUI class from C via the callbacks in the UI struct and thus creates a hierarchical namespace of attributes which map back to the DSP’s UI elements.

Note

Box and Param attributes are prefixed with b_ and p_, respectively, in order to differentiate them from each other and from regular attributes.

Boxes and parameters without a label are given a default name of anon<N>, where N is an integer (e.g., p_anon1 for a label-less parameter).

Parameters:
  • GlueClass (class) – class declaring UI Glue structure

  • obj (object) – The Python object to which the UI elements are to be added. If None (the default) the PythonUI instance manipulates itself.

faust_ctypes.interface.str_to_identifier(s)

Convert a “bytes” to a valid (in Python 2 and 3) identifier.

Parameters:

s (bytes) – the bytes string

Returns:

a string which is a valid identifier

Return type:

string

Typing

class faust_ctypes.ftypes.MetaGlue
faust_ctypes.ftypes.MetaGlue_p

alias of LP_MetaGlue

class faust_ctypes.ftypes.Soundfile

Note

Not implemented yet, but one can still pass soundfiles as dsp inputs by converting them as numpy arrays

class faust_ctypes.ftypes.UiFunTypes(FAUSTFLOAT)

container for types of UI functions parameterized by FAUSTFLOAT

Parameters:

FAUSTFLOAT (ctypes.CDLL) – float type

faust_ctypes.ftypes.gen_Glue(ft)

Class Factory generating an UIGlue class compatible with CDLL structures

Parameters:

ft (UiFunTypes) – the fun type

Returns:

a class generating UIGlue Ctype consistent with ft

faust_ctypes.ftypes.get_faustfloat(dll)

returns the type of floating-point number used by analyzing the content of FAUSTFLOAT macro

Parameters:

dll (ctypes.CDLL) – DLL loaded by ctypes

Returns:

(ctypes data type, numpy data type)

Return type:

tuple[ctypes.CDLL, numpy.dtype]

faust_ctypes.ftypes.sound_pp

alias of LP_LP_Soundfile

faust_ctypes.ftypes.type_dsplib(dll, uiglue_t)

declare the types of the functions of the dsp library

This is very important to avoid SegFaults. C pointers are stored as python ints. By declaring a type, translation from int to C pointer is automatic when calling a function

Parameters:
  • dll (ctypes.CDLL) – DLL loaded by ctypes

  • uiglue_t (class) – UIGlue CType

Note

as we cannot know the structure of mydsp whithout reading the code, mydsp* type is c_void_p

Datatypes

DSP-compatible input/output:

any Numpy 2D array whose datatype matches FAUSTFLOAT and whose first dimension is equal to the number of inputs/outputs of the DSP. If the DSP is a synthesizer, then the DSP-compatible input is any integer