WaveWarp Users' Guide: last updated 28 February 2002

2.2-- MATLAB-enabled WaveWarp Components

2.2.1-- Summary of available components

The MATLAB-enabled components contained in the "MATLAB" category of the WaveWarp Component Library (only available if you have purchased the WaveWarp Audio Toolbox for MATLAB®) are summarized in Table 1. For a detailed description of each component, refer to the respective Help pages in the Component Library Help.

Table 1 Summary of MATLAB-enabled WaveWarp components provided with the WaveWarp Audio Toolbox for MATLAB®

Component name	Component description
Audio To MATLAB	Real-time streaming of audio signals from WaveWarp to the MATLAB workspace. The data is sent frame-by-frame (with a user-adjustable frame-size). An optional transformation can be invoked whereby each frame of data is manipulated according to an arbitrary user-defined MATLAB script evaluated in the workspace using any combination of variables present in the workspace.
MATLAB To Audio	Real-time streaming of audio data from the MATLAB workspace to WaveWarp. The data is sent frame-by-frame (with a user-adjustable frame-size). An optional transformation can be invoked whereby each frame of data is manipulated (before being sent to WaveWarp) according to an arbitrary user-defined MATLAB script evaluated in the workspace using any combination of variables present in the workspace.
Control To MATLAB	Real-time streaming of control signals from WaveWarp to the MATLAB workspace. The data is sent point-by-point (with a user-adjustable update frequency). The signal is held at its given level for the time elapsed between successive updates. An optional transformation can be invoked whereby each data point is manipulated according to an arbitrary user-defined MATLAB script evaluated in the workspace using any combination of variables present in the workspace.
MATLAB To Control	Real-time streaming of control data from the MATLAB workspace to WaveWarp. The data is sent point-by-point (with a user-adjustable update frequency). The signal is held at its given level for the time elapsed between successive updates. An optional transformation can be invoked whereby each data point is manipulated (before being sent to WaveWarp) according to an arbitrary user-defined MATLAB script evaluated in the workspace using any combination of variables present in the workspace.
MATLAB In The Loop	Real-time processing performed in the MATLAB workspace on audio data streaming from/to WaveWarp on a frame-by-frame basis (with a user-adjustable frame-size). The data is manipulated by MATLAB according to an arbitrary user-defined MATLAB script evaluated in the workspace using any combination of variables present in the workspace.
MATLAB Control In-The-Loop	Real-time processing performed in the MATLAB workspace on control data streaming from/to WaveWarp on a point-by-point basis (with a user-adjustable update frequency). The signal is held at its given level for the time elapsed between successive updates. The data is manipulated by MATLAB according to an arbitrary user-defined MATLAB script evaluated in the workspace using any combination of variables present in the workspace.
MATLAB 2D Control Tablet	A mouse-driven two-dimensional tablet for generating two-dimensional user-defined control signal trajectories. The signals are sent in real-time to WaveWarp on a point-by-point basis (with a user-adjustable update frequency). The signal is held at its given level for the time elapsed between successive updates. An optional transformation can be invoked whereby each data point is manipulated (before being sent to WaveWarp) according to an arbitrary user-defined MATLAB script evaluated in the workspace using any combination of variables present in the workspace.
MATLAB Audio Oscilloscope	Real-time audio oscilloscope implemented as a MATLAB GUI. Features include: flexible zoom capability; multiple triggering methods; long record data capture.
MATLAB Wave Player	Converts any signal in the MATLAB workspace into an audio signal in WaveWarp. Unlike the 'MATLAB To Audio' component, the data is not streamed frame-by-frame in real-time from MATLAB to WaveWarp, but rather is sent in its entirety as a single large frame, then played sample-by-sample in WaveWarp. Features include: waveform viewer with flexible zoom/looping capabilities; WAV file import/export options; an optional transformation which can be invoked whereby the data is manipulated (before being sent to WaveWarp) according to an arbitrary user-defined MATLAB script evaluated in the workspace using any combination of variables present in the workspace.
MATLAB FIR Filter	An interface for sending any FIR digital filter designed in MATLAB into WaveWarp for real-time implementation. The filter implementation utilizes a proprietary zero-latency algorithm.
MATLAB IIR Filter	An interface for sending any IIR digital filter designed in MATLAB into WaveWarp for real-time implementation.

2.2.2-- Using the MATLAB-enabled WaveWarp components

Each MATLAB-enabled WaveWarp component is associated with a MATLAB GUI (Graphical User Interface) which automatically boots up whenever the component is dragged on to the Drawing Board. This MATLAB GUI is the sole point of contact between the user and the WaveWarp component (i.e. unlike with conventional [non-MATLAB-enabled] WaveWarp components, there is no Parameter Window associated with the component on the WaveWarp side). An example of Drawing Board containing a MATLAB-enabled components is shown in Figure 1, and the MATLAB GUI associated with the component is shown in Figure 2.

Figure 1 Example Drawing Board containing a MATLAB-enabled WaveWarp component (in this case, a MATLAB Wave Player component). See Figure 2 for a view of the associated MATLAB GUI.

Figure 2 Example of a MATLAB GUI associated with a MATLAB-enabled WaveWarp component (in this case, the MATLAB Wave Player component from the Drawing Board in Figure 1).

2.2.2.1-- MATLAB GUI common parameter controls

The specific parameter controls to be found on a given MATLAB GUI are essentially self-explanatory (see the associated Component Help for detailed information) though they vary from component to component. However, there are some common parameters to all MATLAB-enabled components, the functionality of which is summarized as follows:

"Communication" button

By pressing this button, the WaveWarp-MATLAB inter-process communication window is opened via which the parameters affecting the communication between MATLAB and WaveWarp can be individually adjusted for that component. An example of the window is shown in Figure 3.

Figure 3 WaveWarp-MATLAB inter-process communication window activated by clicking the "Communication" button on a MATLAB GUI.

The user-adjustable parameters contained in this window are summarized as follows:

"Data Transfer Buffer Length"

This defines the frame-size of the audio chunks sent in real-time between WaveWarp and MATLAB. Note that only those components which involve real-time audio streaming (such as "MATLAB In The Loop", etc) will provide a "Data Transfer Buffer Length" adjustment dialog. Generally speaking, the "Data Transfer Buffer Length" should be adjusted (by trial-and-error) to optimize the real-time throughput for a given Drawing Board and PC hardware configuration. The default value is a good starting point.

Important note: the "Data Transfer Buffer Length" setting is specific to a given MATLAB-enabled component. There is no "global" setting which spans multiple components. Each component must be individually set, and if desired all components can be set to have different values.

"Parameter Update Rate"

This defines the time elapsed between successive updates of MATLAB parameter values (e.g. slider changes, control signal values, etc). This should be set as large as possible within the constraints of a given user application since this alleviates the CPU burden. However, note that the system is efficient in the sense that WaveWarp will only process changes in parameter values (e.g. if a slider hasn't changed by the time of the next scheduled update, no data exchange will occur).

There is an important caveat to the previous statements: some components "clock" certain active elements to the "Parameter Update Rate". For example, the waveform scrollbar in the "MATLAB Wave Player" GUI receives its real-time tracking information at the clock-rate defined by the "Parameter Update Rate". This means that if the rate is set too slow, the scroll bar may not function smoothly at a given zoom level. Again, by trial-and-error you will rapidly ascertain the suitable settings in a given situation.

Important note: the "Parameter Update Rate" setting is specific to a given MATLAB-enabled component. There is no "global" setting which spans multiple components. Each component must be individually set, and if desired all components can be set to have different values.

Sample Rate Display

Located just below the "Communication button", this window displays the sample rate currently assigned by WaveWarp to the component.

DrawingBoard Play Status Display

Located in the lower left-hand corner of the GUI, this window displays the current status of the WaveWarp DrawingBoard (i.e. "Stopped", "Playing", or "Paused").

"Mute" and "Bypass" buttons

The function of these is generally self-explanatory (though there may be subtle differences in specific actions across the different components). The "Mute" button generally has the effect of "zeroing" any data going into or out of the MATLAB workspace. The "Bypass" button generally has the effect of stopping the inter-process data flow. See the Component Help for detailed descriptions.

"File" menu

Located on the toolbar in the top left-hand corner of the GUI window, this menu allows the settings of the key GUI parameters to be saved/loaded to/from a MAT-file, enabling the user to make a library of customized settings. The "Restore Default Settings" returns the GUI to the state when first placed on the DrawingBoard.

Important note: none of the MATLAB GUI settings are saved with the DrawingBoard ".dwb" file (unlike conventional WaveWarp parameter window settings). Therefore it is essential to use the in-built "File" menu in order to save custom settings of MATLAB GUIs.

"Help" menu

Located on the toolbar to the right of the "File" menu, this enables the HTML-based Help page to be opened for a given component. The MATLAB GUI Help pages are fully integrated with the rest of the WaveWarp Help functionality (i.e. including text search capabilities, etc).

2.2.3-- Managing "window clutter" when using WaveWarp and MATLAB

WaveWarp in combination with MATLAB utilizes many windows which can quickly lead to a cluttered desktop. In order to reduce the clutter and make the combined products more user-friendly, the following MATLAB functions are provided:

Table 2 List of MATLAB "window management" functions provided with WaveWarp 2.0.4

Function m-file	Function description
wwhide.m	Hides all Wave-generated MATLAB GUI's from the desktop and taskbar, thereby reducing screen clutter. NOTE: the GUI's are still "alive" even when hidden - so the MATLAB-enabled WaveWarp DrawingBoards will function as normal.
wwshow.m	Restores all Wave-generated MATLAB GUI's to the desktop from their "hidden" or "minimized" state.
wwmin.m	Minimizes all Wave-generated MATLAB GUI's from the desktop, thereby reducing screen clutter. The GUI's will still be present in the taskbar at the bottom of the screen and can be restored using the usual Windows controls (i.e. by clicking on the taskbar entry or using "Alt-TAB" etc). NOTE: the GUI's are still "alive" even when minimized so the MATLAB-enabled WaveWarp DrawingBoards will function as normal.
wwclose.m	Closes all WaveWarp-generated MATLAB GUI's (any MATLAB GUI's required by the active DrawingBoard will be automatically re-created when the WaveWarp "stop" or "start" buttons are pressed).

In addition to providing these "clutter reduction" window-management functions to the user, the following "window-management rules" are automatically applied by WaveWarp in order to increase the desktop "usability":

¬ All WaveWarp-generated MATLAB GUI's are automatically placed "on top" of the desktop so that they remain in view even when the MATLAB command window is de-selected and another application (e.g. WaveWarp) owns the active window.

¬ The MATLAB command window (pertaining to the WaveWarp session) is automatically placed "on top" of the desktop so that it remains in view even when de-selected.

¬ All WaveWarp-generated MATLAB GUI's required by the active WaveWarp DrawingBoard are automatically re-created when the DrawingBoard playback is started or stopped.

NOTE: these rules have been imposed in order to make the desktop less cluttered and generally more usable. However, on occasion, the rules may "backfire". For example, the WaveWarp WAV file dialog or DrawingBoard selector dialog may be hidden behind MATLAB GUI's which are always "on top". In such cases, you must temporarily minimize (or move) the MATLAB GUI's out of the way.

2.2.4-- User extensibility: simple "homemade" GUI example

In keeping entirely with the spirit of MATLAB, the WaveWarp Audio Toolbox is designed from the ground-up to be highly user-extensible. For example, all the real-time processing modules can be "programmed" with any valid MATLAB scripts including function calls to user-defined m-files, compiled mex files (for speed !) etc. Likewise, the user can build MATLAB GUI's for interacting with WaveWarp via any variables present in the MATLAB workspace. As a simple demonstration of this, consider the following example of a "homemade GUI" which is bundled with the toolbox:

At the MATLAB prompt (within the WaveWarp-initiated instance of MATLAB), type the following:

» ExamplePianoGUI

The following MATLAB GUI will appear (Figure 4):

Figure 4 Example "homemade" MATLAB GUI designed to interact with WaveWarp via the MATLAB workspace.

This is a straightforward MATLAB GUI with no implicit connection to WaveWarp whatsoever (you may verify this by taking a look at the source m-code of the GUI!). As explained in the text box within the GUI, this simple component transmits the frequency (in hertz) of the user-selected key into the MATLAB workspace under the variable name "PianoNote". This variable can now be utilized by any MATLAB-enabled component. For example, open (or re-create !) the "MATLABtoControlExamplePiano.dwb" Drawing Board (located in the "ExampleDrawingBoards \ MatlabAudioToolbox" directory in the WaveWarp root). As shown in Figure 5 , this design consists of a 'MATLAB To Control' component connected to the frequency input of a frequency-controllable oscillator.

Figure 5 "MATLABtoControlExamplePiano.dwb" Example Drawing Board depicting a frequency-controlled oscillator under the command of a MATLAB workspace variable.

Now set the "Name of raw signal:" in the MATLAB GUI (associated with the MATLAB-To-Control component) to "PianoNote", as shown in Figure 6 (and de-select the "Enable Transform" button for now!)

Figure 6 Setting the 'MATLAB-To-Control' component to utilize the "PianoNote" workspace variable as its output to WaveWarp.

Hit "play" in WaveWarp. The sound generated by the frequency-controlled oscillator will now track the notes "played" in the MATLAB "Example Piano GUI".

This simple example demonstrates how straightforward it is to extend the functionality of the WaveWarp Audio Toolbox for MATLAB.