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 audfile.

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).

A typical audpanel looks like this:

What you see here is a group of controllers and some other things. What you'll do with the audpanel in 99% of the time is to select a preset from the Presets box to choose a group of controllers, then set the parameters of controllers, which will be sent to the corresponding audfile 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. Now 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	10.0	0.0	0.0 0.0 0.0)
Preset1.maxValues:	(0.0	5.0 	3.0	20.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

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

apdemo.aud

// Companion audfile for apdemo.ap

SetPrintCommands 1;

LoadDSO msgGroup.so;
LoadDSO fm.so;

a = Create FmActor;
s = 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 SetFoo FooActor *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 s *0;
AddMessage msg2 SetCarFreq s *1;
AddMessage msg2 SetMCratio s *2;
AddMessage msg2 SetModFreq s *3;
AddMessage msg2_RatioMode SetRatioMode s *0;
AddMessage msg2 SetModIndex s *5;
AddMessage msg2 SetCarFeedback s *6;
AddMessage msg2 SetModFeedback s *7;

There are two basic message groups msg1 and msg2 in the audfile, who 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 reason for this is that because of the different nature of different controllers, they usually control irrelated things, so it doesn't make sense to send them altogether.

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.