AudYoFlo: Use Cases: Run First Version of Algorithm in Matlab Implementations

The ayf Matlab host is a specific host that is operated from within Matlab. It provides the function to process wav files or other audio data to produce from an input signal an output signal. On the way towards the output data, a signal processing algorithm is applied. This algorithm may be implemented in Matlab code as well as in C/C++ code and may be a new approach for any problem which still has to be investigated in different development phases. In this context, the Matlab host is the right tool to use as it supports all development stages, from the first tests all the road to the real-time implementation in C/C++ that may be operated in a standalone host.

The Matlab host itself is a common piece of software that can be used for every new algorithm. When building the runtime of jvxrt, the Matlab host will popup in the runtime folder and can be started within the Matlab environment for every kind of algorithm. The algorithm is selected in a combobox and is loaded dynamically as a DLL,

If the algorithm is operated in the development phase, the Matlab code based implementation is not part of the runtime folder. Instead, it is located in the project folder. During the cmake based build of jvxrt, the C/C++ of the algorithm is compiled into the DLL but the Matlab code part should resist and edited within the corresponding project folder.

In order to allow this distribution of executable and source code at different locations, in jvxrt, a link is created in the runtime to allow to link the project specific functions into the runtime environment. The result of this linkage can be reviewed in the following Figure where the Matlab host and all common functions are part of the Matlab Runtime Environment whereas the Matlab functions are part of the Project Specific Implementation (Func1(), Func2(), Func3().

Matlab Boot Process & Project References

In order to link the project specific parts to the Matlab runtime, during the boot process of the Matlab host, a specific function is called to add entries to the Matlab path. For this purpose at least a single function in the file jvx_init_callback.m is called. This file is supposed to be the only project file which must be installed to the runtime environment. Once the function was called, all project specific functions can be found due to the modified path in Matlab.

The principle to all the function in file jvx_init_callback.m during the boot process is shown in the following figure:

Callbacks when Processing Audio Data

Preparation of the Code

The ayf Matlab host allows to drive C/C++ code to be driven by data provided in Matlab. However, it also allows to mix Matlab and C/C++ code. The most common use-case is to run a C/C++ project (a dll) from within Matlab but to invoke the processing within Matlab. This principle is depicted in the following diagram.

For the proper functionality, some extensions must be made to the project. All example code demonstrations are based on a very simple example project denoted as ayfAuNMatlab found at location

<ayf-templates>/repos/jvxrt-submodules/audio/sources/jvxComponents/jvxAudioNodes

in the repository file hierarchie.

Files in the project folder

The project contains the following subfolders:

The C/C++-code is located in folders src and target. The pcg files for property exposure and the mcg files for Matlab function exposure are located in folder codeGen. The project itself and all build related aspects are given in the local CMakeList.txt file. The two folders matlab-in and matlab-local contain some functions in files to be described later. In folder scripts, a template for the generation of a Matlab startup script is located.

Creating two versions of the algorithm

At first we review the CMakeList.txt file which defines all project configurations of the C/C++ code and other generated files. Principally, this file follows the same principle as all other CMakeList.txt files. However, it defines an additional target which is particularly suited for Matlab interaction:

The second project has the same name as the original project with a "m" following. The commands have the following meaning:

• LOCAL_START_SCRIPT_MATLAB: If this is specified, a start script is generated from the template given at

  ${CMAKE_CURRENT_SOURCE_DIR}/scripts/${JVX_OS}/start_mat

• JVX_INSTALL_MATLAB_MINIMAL_FRAMEWORK: If this is active,, the content from the folder matlab_in is used to generate a file which will be included in the Matlab boot process to create some local links.

• An additional source code file ${CMAKE_CURRENT_SOURCE_DIR}/src/CayfAuNMatlab_matlab.cpp is added to deal with all Matlab interfacing.

• The command JVX_ACTIVATE_VERSION_MATLAB(${PROJECT_NAME} JVX_EXTERNAL_CALL_ENABLED) activates the additional Matlab project and defines the pre-processor define JVX_EXTERNAL_CALL_ENABLED,

Once the project is built, two projects will be configured denoted as

ayfAuNMatlab

and

ayfAuNMatlabm,

Once the install target has been run, there is a start-script in the build directory,

By double-clicking that script, Matlab will be started and displays the next steps to start the processing host.

Add Matlab interaction code

The functions to interact with Matlab are encapsulated in the dedicated class CjvxMexCalls which the main component in this project can be derived from:

The member functions of this class must then be invoked in the state switching function implementations

• select
• unselect
• activate
• deactivate
• prepare
• postprocess

If an implementation of any of the functions already exists, you can just add the corresponding function call:

If the function does NOT exist in the class, there are macros defined to realize the required functions:

With these functions, the class can be opened in the Matlab host and selected as follows:

The host can be started and used for audio processing now. However, there still is an error:

The reason for this error is that we have not setup a processing callback yet. The environment to involve the processing callbacks is realized as follows:

1. A call to start processing can be implemented by calling the two function CjvxMexCalls::prepare_sender_to_receiver and CjvxMexCalls::prepare_complete_receiver_to_sender within the context of the prepare_connect_icon member function.

2. A call to stop processing can be implemented by calling the two functions CjvxMexCalls::before_postprocess_receiver_to_sender and CjvxMexCalls::postprocess_sender_to_receiver within the context of the member function postprocess_connect_icon.

3. A call to actually process an input buffer is realized in the core processing function. \

There are options that may influence how the processing buffer is involved which are evaluated right before the call:
a) The call to is_extcall_reference_present returns a bool if the external call reference is present. It is typically present if the algorithm is called in a debug call context being part of the Matlab host.
b) The other option is obtained by calling the function is_matlab_processing_engaged and is linked to the selection of "Engage Matlab" in the Matlab host UI. An execution of the code fragments in Matlab may only happen if the checkbox is active.