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