...
The most straightforward use of the API allows MATLAB to interact with the Audio Weaver Designer GUI. This is documented in Interacting with Audio Weaver Designer and is sufficient for most users. More advanced scripting features are described in later sections.
...
The arguments to the connect command are the source and destination modules, respectively. The subsystem itself is specified by the empty string. Thus, the first statement connects the subsystem’s input pin to the input of the ‘toFloat’ type conversion module. Similarly, the last statement connects the output of the ‘toFract” module to the output of the subsystem. In this example, the subsystem and modules only have one pin each on the input and output, so it is clear as to what connections are specified. For modules and subsystems with multiple input or output pins, we use a slightly different syntax described in Making Connections.
We can also reduce the 4 connect commands to a single command:
...
Audio Weaver also has rudimentary drawing capabilities. Execute the command:
GSYS.SYS.draw();
This pops up a MATLAB figure window and displays
...
Notes:
A related but more complicated example, bass_tone_control_module.m, is also provided with Audio Weaver. This other version supports both floating-point and fract32 signals.
The bass tone control presented here is only to illustrate certain Audio Weaver concepts. If you need a bass tone control in your system, see the example in Bass and Treble Tone Controls.
The design equations are written in MATLAB and allow you to control the module using MATLAB scripts. However, since the control code does not exist on the target, you will be unable to draw an inspector. To take it one step further and write the control code in C requires writing a custom audio module. This is beyond the scope of this User's Guide but points you towards the benefits of writing custom audio modules.
...
Note: This guide describes high-level usage of the Audio Weaver. The code generator of Audio Weaver is able to take the bass tone control and generate code for a “BassTone” class that resides on the target. This process is described in the Developing (8.D.2.4) Custom Modules : Developer's Guide.
Audio Weaver flattens the system behind the scenes while presenting the hierarchical version to the user to manipulate. To see the actual flattened system running on the target, use
...
This section goes into further detail regarding key concepts in Audio Weaver. These were touched upon in the tutorial in Interacting with Audio Weaver Designer and The Basics of the MATLAB API, and are given full coverage here. The concepts explain how Audio Weaver operates behind the scenes and clarifies the relationship between pins, wires, modules, and subsystems.
...
Note: The function classid_lookup.m can be used to determine if a class name is already in use. Refer to Developing (8.D.2.4) Custom Modules : Developer's Guide for more information.
...
Pins are added to a module by the add_pin.m function. Each pin has an associated Pin Type as described in Pins. After creating the Pin Type, call the function
...
where the 2nd and subsequent arguments are passed to the awe_variable.m function. See @awe_module for a description of these parameters.
...
The call to create a new empty subsystem is similar to the call to create a new module described in @awe_module
SYS=awe_subsystem(CLASSNAME, DESCRIPTION);
...
The module names "sine1" and "mult" are obvious because they were specified when the modules were created. The pins names may not be obvious since they appear within the module's constructor function. To determine the names of a module's pins, you can either utilize the detailed help function awe_help described in Online Help (recommended)
awe_help multiplexor_smoothed_module
...
The top-level system is still an @awe_subsystem object but it is treated differently by the build process. The main difference is how the output pin properties are handled. In a top-level system, the output pins properties are explicitly specified and not derived from pin propagation. As an added check, the pin propagation algorithm verifies that the wires attached to a top-level system's output pins match the properties of each output pin of the target. The top-level system functions are described in more detail in target_system.m and matlab_target_system.m.
In contrast, internal subsystems are created by calls to
...
We describe some of the fields which are commonly edited here. Refer to Developing (8.D.2.4) Custom Modules : Developer's Guide for a complete description.
...
| Code Block |
|---|
filter = Biquad // 2nd order IIR filter
b0: 1 // First numerator coefficient
b1: 0 // Second numerator coefficient
b2: 0 // Third numerator coefficient
a1: 0 // Second denominator coefficient
a2: 0 // Third denominator coefficient
state: 0
0] |
See AWE_INFO for a description of all user settable fields in the AWE_INFO structure.
...
More detailed information for add_argument() is in Developing (8.D.2.4) Custom Modules : Developer's Guide.
Pins
The function new_pin_type.m was introduced in Adding I/O Pins and returns a data structure representing a pin. The internal structure of a pin can be seen by examining the pin data structure. At the MATLAB command prompt type:
...
Consider the bass tone control subsystem introduced in Bass Tone Control Module. The subsystem was connected to stereo input and output pins and thus all of the internal wires hold two channels of information. If the bass tone control were connected to a mono input, then all of the internal wires would be mono and the module would operate as expected. This generality allows you to design algorithms which operate on an arbitrary number of channels with little added complexity.
...
The most common time that users stumble with this concept is when they use the awe_setstatus.m command described in awe_getstatus.m and awe_setstatus.m. When you are changing the status of a module within a subsystem you must reassign the output argument as in:
...
In addition to logging text script files, the Audio Weaver diary can also create compiled script files. Refer to Creating and Compiling Files.
awe_getini.m and awe_setini.m
...
This global variable was first introduced in @awe_module and controls some aspects of Audio Weaver. AWE_INFO is a structure with the following fields:
AWE_INFO.displayControl – determines whether hidden variables are displayed in module and subsystem structures. Refer to @awe_module.
AWE_INFO.testControl – Used internally by DSP Concepts for automated regression tests.
...
AWE_INFO.docControl – Controls aspects of documentation generation. Refer to Developing (8.D.2.4) Custom Modules : Developer's Guide for more details.
AWE_INFO.inspectorControl – Most fields are used internally by the awe_inspect.m command. One user settable field is:
...
AWE_INFO.buildControl – Refer to Developing (8.D.2.4) Custom Modules : Developer's Guide. Most of the fields are used internally by the build.m command. Two user settable ones are:
.profileMemory – specifies if memory heap information is monitored during the build process. Refer to build.m.
.echoCommands – specifies if all of the Server commands and responses are echoed to the MATLAB output window. This is primarily used when debugging and you want to monitor the communication between MATLAB and the audio Server.
...
Adds a single variable to a module's inspector. This command is described in Creating User Interfaces.
add_module.m
SYS=add_module(SYS, MOD)
...
Examples of how to use this function are provided in Adding Modules. Note that the set of input pin names must be unique, as well as the set of output pin names. The add_pin function checks for this and reports the following error if this condition is violated:
...
'Bypassed' – the module's inputs are copied directly to its outputs. The generic version copies the ith input pin to the ith output pin. A module may also define a custom bypass function if the generic version is not appropriate. Refer to Developing (8.D.2.4) Custom Modules : Developer's Guide for further details about custom bypass functions.
...
The function returns an integer STATUS that is interpreted as:
Integer | Status |
|---|---|
-1 | There is a wiring error. |
0 | There are no wiring errors, but the wiring is not complete. There are 1 or more pins in the subsystem that are not connected. |
1 | There are no wiring errors and the wiring is complete. The system is ready to build. |
Connections within a subsystem are made by the connect.m command. Each connection is from a named source module / output pin to a named destination module / input pin. The connection.m function catches several different wiring errors:
...
By default, ISFEEDBACK=0 and a standard feedforward connection is made. Set ISFEEDBACK=1 to indicate feedback. See Feedback for a detailed discussion of using feedback within Audio Weaver systems.
...
A toolbar on the figure window allows you to adjust the display:
Button | Function |
|---|---|
 | Zoom in |
 | Zoom out |
 | Scroll the display |
 | Display wire information (toggle) |
 | Display module variables (toggle) |
 | Display pin names (toggle) |
 | Refresh the drawing |
All of the tools labeled "toggle" are global and apply to subsequent drawings. The state of the toggle buttons is stored in the global variable:
...
Some modules may utilize the same wire for both input and output. This "straight across" wire buffer allocation is specified within the module's constructor function. Further details are found in Developing (8.D.2.4) Custom Modules : Developer's Guide (No modules in the limiter_example.m have straight across wiring).
...
When subsystems are drawn using the draw.m command, the modules are color coded according to their status:
 |
|
 | Muted = White |
 | Bypassed = Yellow |
 | Inactive = Red |
If you make a change to the module status using either an inspector or programmatically from MATLAB using the awe_setstatus.m command, then the drawing in a figure window will not be automatically updated. Instead, you need to manually refresh the window using the toolbar button or right-clicking on an empty part of the figure window and selecting Redraw.
...
The real power of this function comes from its ability to support wild cards. Use the string '*' to specify any module or pin. For example, consider the Limiter Example Figure Drawing.
To determine what modules are connected to the output of the "scale" module, use:
...
As an example, refer back to the system created by the script limiter_example.m shown in the Limiter Example Figure Drawing. Let's locate the input pin "in" on the "lim" module. This is the destination of a connection:
...
As an example, refer back to system created by the script limiter_example.m shown in the Limiter Example Figure Drawing. To locate the output pin "out" of the module "scale" use
...
For example, consider the limiter_example.m shown in Limiter Example Figure Drawing. The agc_multiplier module has two input pins as shown below:
...
As an example, consider the subsystem created by the test script limiter_example shown in the Limiter Example Figure Drawing. The system shown is the one prior to flattening. The actual system running on the target is
...
Point-to-point connections in Audio Weaver are specified via the connect.m function described in connect.m The connect.m command has an optional fourth argument which is used to indicate feedback.
...
The inspector panel shown in the combined inspector panel consists of 4 separate "sub-inspectors", one for each internal module. By default, Audio Weaver draws sub-inspectors and individual controls from left to right. Subsequent controls are added to the right of the last control.
...
If the variable is an array, then controlType='grid' and the following is drawn:
If the variable has usage 'const', then controlType='const' and the variable is drawn as a read-only edit box
If the variable has no range information, then controlType='edit' and it is drawn as an edit box:
If the variable has usage 'parameter', has type 'int', and there are only two items, then controlType='checkBox'
If the variable has usage 'parameter', has type 'int', and there are three to nine items, then controlType='dropList'. For each allowable integer value, you can specify a string to provide an easy-to-read drop list.
If the variable has usage 'parameter', has type 'int', and there are 10 or more items, then controlType='knob'. Or, if the variable has usage 'parameter' and type 'float', then controlType='knob'.
If the variable has usage 'state', has type 'int' and has exactly two items, then controlType='LED'.
If the variable has usage 'state', has type 'int' and has three or more items, then controlType='meter'. Or, if the variable has usage 'state' and type 'float', controlType='meter'.
Otherwise, a default controlType cannot be assigned to this variable.
The default .controlType string can be overridden. For example, the agc_core_module.m uses a knob for the recoveryRate control. You can change this to a slider using the command:
...
An audio module can be in one of four run-time states: Active, Muted, Bypassed, and Inactive, as described in Real-Time Tuning. The module status is set using a group of radio buttons. To add a module status control, use the syntax:
...
Base and Extended Controls
We saw in the Quick Tutorial that some inspectors could toggle between showing and hiding an "extended" panel by double-clicking on the title bar. (Note that this only works for inspectors drawn by the Server; not by inspectors drawn by the Designer GUI.) Typically, the frequently used controls appear on the base panel while the less frequently used items, such as the module status, appear on the extended panel.
...
where FILENAME is a string specifying the file to add along with absolute or relative file path and ATTRIB is the 8-bit attribute byte discussed as below.
Attribute Byte | Description |
|---|---|
24 | Compiled Script file (non-bootable) |
26 | Compiled Script file (bootable) |
40 | Compiled Preset File (non-bootable) |
42 | Compiled Preset File (bootable) |
FILENAME must be at most 24 characters in length, for example “agc_example.awb”; this is checked by the function. The function also checks that FILENAME does not already exist in the Flash File System.
...
The MATLAB command awe_diary.m is the primary method for creating Audio Weaver Script (.aws) files. This command is discussed in awe_diary.m and essentially captures all of the commands sent from MATLAB to the Server and logs them to a specified file. Typically, you wrap the building of a system in pairs of awe_diary commands as shown below:
...