Audpanel User's Guide

Audpanel uses a pair of files, preferably using the same name with different extensions .ap(or .audpanel) and .aud. The .ap file sets up the audpanel interface and its interaction between the .aud file, which is nothing more than a generic .aud file.

To run audpanel, type audpanel <filename>.ap <filename>.aud or simply audpanel <filename>.* if you conform to the naming convention. Before the filenames, audpanel optionally takes an argument of -host <hostname>. <hostname> will then override any environment variable SOUNDSERVER which you may have defined as the machine which will be running VSS. This is particularly convenient for Windows, where setting environment variables can be a pain (do specify the host as a numerical IP address instead of a name in Windows, though).

Audpanel typically looks like this:

What you see here is a group of controllers and some other things. Usually you'll select a preset from the Presets box to choose a group of controllers, and then set the values of these controllers. These values will be sent to the corresponding .aud file via message groups.

There are three ways to send the parameters, which can be chosen from the radio buttons at the bottom left of the audpanel:

1. Don't send

Don't do anything unless the Hit button is hit, then all parameters are sent once.
2. Send when changed

Whenever any parameter is changed by the user, all the parameters are sent. This is the default behavior.
3. Send continuously

Keep sending all parameters at the time interval specified by the Sending Interval slider at the bottom of the audpanel.

To create your own audpanel, the best way is to modify an exisiting one. Let's start with the demo audpanel shown above. First the .ap file:

apdemo.ap

'Test case for audpanel.'

audpanel.title:		"Audpanel Demo"
audpanel.sliders:	8
audpanel.presets:	("Preset1" "Preset2")
audpanel.audHandle:	15

Preset1.messageGroup:	"msg1"
Preset1.interval:	0.1
Preset1.type:		(1 	2 	3 	3 	4 	0 0 0)
Preset1.labels:   ("button" "radio" "slider1" "slider2" "square" "" "" "")
Preset1.minValues:	(0.0	0.0 	0.0	 0.1	0.0	0.0 0.0 0.0)
Preset1.maxValues:	(0.0	5.0 	3.0	 5.0	1.0	0.0 0.0 0.0)
Preset1.initialValues:	(0.0	1.0 	0.2	15.0	0.0	0.0 0.0 0.0)
Preset1.mappings:	(0	1	2	3	4	-1 -1 -1)
Preset1.parameters:	5

Preset2.messageGroup:	"msg2"
Preset2.interval:	1.0
Preset2.type:		(3	3	3	3	2	3	3	3)
Preset2.labels:	("Amp" "CarFreq" "MCRatio" "ModFreq" "RatioMode" "ModIndex" "CarFB" "ModFB")
Preset2.minValues: 	(0.0	50.0	0.0	10.0	0.0	0.0	0.0	0.0)
Preset2.maxValues: 	(1.0	5000.0	10.0	1000.0	2.0	50.0	1.0	1.0)
Preset2.initialValues: 	(0.5	500.0	1.0	100.0	0.0	1.5	0.0	0.0)
Preset2.defaultValues:	(0.5	500.0	1.0	100.0	0.0	1.5	0.0	0.0)
Preset2.mappings:	(0	1	2	3	-1	5	6	7)
Preset2.parameters:	8

A .ap file always consists of a header followed by one or more preset definitions. The header gives some general information about the audpanel. A preset, as stated before, is a group of controllers. In this example, Preset1 is a demo set for all 5 types of controllers, and Preset2 is for controlling an FM sound. A preset has several properties that describes the behavior of all its controllers. The names of the properties suggest what they're for. The details of .ap file syntax are described later in this document. Now just keep in mind the message group for each preset, and label and mapping of each controller, then go on to the .aud file:

apdemo.aud

// Companion .aud file for apdemo.ap

SetPrintCommands 1;

LoadDSO msgGroup.so;
LoadDSO fm.so;

a = Create FmActor;
s1 = BeginSound a SetAmp 0;
s2 = BeginSound a SetAmp 0;

msg1 = Create MessageGroup;
msg1_button = Create MessageGroup;
msg1_radio = Create MessageGroup;
msg1_square_Start = Create MessageGroup;
msg1_square_Move = Create MessageGroup;
msg1_square_Stop = Create MessageGroup;

msg2 = Create MessageGroup;
msg2_RatioMode = Create MessageGroup;

AddMessage msg1_button SetFooOnce FooActor;
AddMessage msg1_radio SetFooState FooActor *0;
AddMessage msg1 SetAmp s1 *2 *3;
AddMessage msg1_square_Start SetFooStart2D FooActor *0 *1;
AddMessage msg1_square_Move SetFooMove2D FooActor *0 *1;
AddMessage msg1_square_Stop SetFooStop2D FooActor *0 *1;

AddMessage msg2 SetAmp s2 *0;
AddMessage msg2 SetCarFreq s2 *1;
AddMessage msg2 SetMCratio s2 *2;
AddMessage msg2 SetModFreq s2 *3;
AddMessage msg2_RatioMode SetRatioMode s2 *0;
AddMessage msg2 SetModIndex s2 *5;
AddMessage msg2 SetCarFeedback s2 *6;
AddMessage msg2 SetModFeedback s2 *7;

There are two basic message groups msg1 and msg2 in the .aud file, which carry only the values of the sliders. For other types of controllers, their labels are attached to msg1 and msg2 to specify the message group that the controllers use. The other controllers have separate message groups because they usually control things unrelated to the sliders themselves.

Now we'll go through all the details of the .ap file to put everything together. First the items in the header:

• title
  The audpanel title to be shown on the window title bar.
• controllers
  Number of controllers in all presets. All properties with array argument in all presets must have the same number of elements as audpanel.controllers.
• presets
  The name(s) of the preset(s). Whitespace is not allowed in a preset name.

Now the properties of a preset:

(Note that if you need two audpanels running on the same machine, talking to the same vss, that you should instead use two presets in a single audpanel.)

• messageGroup

The name of the message group by which the controllers in the preset send parameters to the .aud file. As will be seen in the following table, different controllers actually use different message groups, but their names all derive from this property. You can also change the message group on the fly, typing a new name in the Message group text box at the bottom of the audpanel. Of course, make sure the new message group is already in the .aud file.
• interval

Default time interval for continuously sending, as shown in the Sending Interval slider.
• type

Types of the controllers as shown in the following table of controllers. If you omit this property, everything defaults to a slider. If you include it, you need to specify every controller's type.
• labels

The names of the sliders. Keep them short so they fit.
• minValues, maxValues, initialValues

As shown in the following table. When the Reset button is hit, all controllers will return to their initialValues. Floating-point values should be used, and they must have at least one integer digit and one decimal digit. 0.0 works, but 0, 0., and .0 don't.
• defaultValues

(Advanced usage) Omit this one if you don't need it, and it will default to initValues.) If a message group argument is not mapped to by any controller, it gets this default value instead (Set all the mappings to -1 to see what this means). You can set the default values in the audpanel: Click on a controller in the Defaults box, then type in the number in the text box below it.
• mappings

Controller number as used in the .aud file. It only affects sliders, whose values are sent in an array in the main message group. The number determines which argument of the message group the slider is controlling. In our example, recall a line in the .ap file and another in the .aud file:

Preset1.mappings: (0 1 2 3 4 -1 -1 -1)

AddMessage msg1 SetAmp s2 *2 *3;

It means that the SetAmp command of s2 will modulate to the value of the 2nd (counting from 0th) controller (a slider) in Preset1 during a period of time, the period being the value of the 3rd controller(another slider). If the number is -1, the slider is unassigned. Typically the mapping list is simply (0 1 2 3 4 ... ).
• parameters

The number of effective controllers.

The following table lists all the controllers:

Controller	Button	Radio button	Slider	Square controller	Nil controller
Type number	1	2	3	4	0
Message group	<msg>_<label>	<msg>_<label>	<msg>	<msg> _<label> _<Start/Move/Stop>	none
Min value	ignored	ignored	Min value	ignored	ignored
Max value	ignored	Number of choices(2~10)	Max value	ignored	ignored
Initial value	ignored	Initial choice	Initial value	ignored	ignored
Mapping	ignored	ignored, always *0	*<mapping>	ignored, always *0 and *1	ignored
Description	Pressing a button sends a single message group to VSS. No arguments are sent.	Clicking a radio button also sends a single message group to VSS. A single integer argument is sent, indicating which button in the column was pressed.	A slider can send a continuously(almost) changing parameter. The min/max/current values of a slider can all be changed on the fly. If you want an exact value, just type it in the text box beside the slider.	(See the paragraph below this table. Too long to fit in here!)

The square controller is a special-purpose input device, when you want to control two continuous values at once. It sends three message groups to VSS, one when the mouse is clicked inside the square, one when the mouse is moved, and one when the mouse is released. The names of these message groups are constructed by appending to the standard name an underscore, the label of the square controller, another underscore, and then one of "Start", "Move", or "Stop". In the example we have msg1_square_Start, msg1_square_Move, and msg1_square_Stop. All three message groups have two floating-point arguments, corresponding to the x-y coordinates of the cursor in the square.
Note: a square controller must be followed by two Nil controllers. (A nil controller simply takes up space.) You know you're doing this right if in the type property, anywhere there is a "4", it is immediately followed by " 0 0".

Finally, you can insert comments in a .ap file by enclosing them in single quotes. (Audpanel's parser is based on an old SmallTalk interpreter, that's why.)