flightgear/docs-mini/README.xmlsound

Users Guide to FlightGear sound configuration
Version 0.7.10, Mar 02 2002
Author: Erik Hofman <erik@ehofman.com>

This document is an attempt to describe the configuration of
FlightGear flight simulator's aircraft sound via XML.

Some History:
------------
Older versions of FGFS had a hard coded audio layer.  This was a
than ideal state of affairs due to FGFS ability to use different
aircraft models. Being primarily developed on UNIX type systems, a
modular approach is taken towards the simulation. To date, most
alternatives to the default Cessna 172 aircraft are the product
of research institutions interested in the flight characteristics and
not cosmetics.  The result of this was that one could fly the X-15 or
a Boeing 747 but be limited to C172 sounds.

A rewrite of the sound code was done around v0.7.10 by Erik Hofman
allowing for configuration of the sounds via XML to address this
limitation.

Sound Architecture:
------------------
All of the sound configuration files are XML-encoded* property lists.
The root element of each file is always named <PropertyList>. Tags are
almost always found in pairs, with the closing tag having a slash
prefixing the tag name, i.e </PropertyList>. The exception is the tag
representing an aliased property. In this case a slash is prepended to
the closing angle bracket.  (see section Aliasing)

The top level sound configuration file is composed of a <fx>, a
<name>, a <path> sound file and zero or more <volume> and/or <pitch>
definitions.

[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
[ Absolute paths may be used.Comments are bracketed with <!-- -->.            ]

A limited sound configuration file would look something like this:

<PropertyList>
 <fx>
  <engine>
   <name>engine</name>
   <path>Sounds/wasp.wav</path>
   <mode>looped</mode>
   <property>/engines/engine/running</property>
   <volume>
    <property>/engines/engine/mp-osi</property>
    <factor>0.005</factor>
    <min>0.15</min>
    <max>0.5</max>
    <offset>0.15</offset>
   </volume>
   <pitch>
    <property>/engines/engine/rpm</property>
    <factor>0.0012</factor>
    <min>0.3</min>
    <max>5.0</max>
    <offset>0.3</offset>
   </pitch>
  </engine>
 </fx>
</PropertyList>

This would define an engine sound event handler for a piston engine driven
aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
and is named wasp.wav. The event is started when the property
/engines/engine/running becomes non zero. 

When that happens, the sound will be played looped (see <mode>) until the
property returns zero again. As you can see the volume is mp-osi dependant,
and the pitch of the sound depents on the engine rpm.

Configuration description:
-------------------------
   
<fx>
 	Named FX subtree living under /sim/sound
 
 < ... >
 	This is the event seperator. The text inside the brackets
 	can be anything. Bit it is adviced to give it a meaningfull name
        like: crank, engine, rumble, gear, squeal, flap, wind or stall
 
 	The value can be defined multiple times, thus anything which is
 	related may have the same name (grouping them together).
 
   <name>
 	This defines the name of the event. This name is used internally
 	and, although it can me defined multiple times in the same file,
        should normally have an unique value.
 
	Multiple definitions of the same name will allow multiple sections
	to interfere in the starting and stopping of the sample.

	This method can't be used to controll the pitch or volume of the 
	sample, but instead multiple volume or pitch section should be
	included inside the same event.

	The types "raise" and "fall" will stop the playback of the sample
	regardless of any other event. This means that when the type "raise"
	is supplied, sample playback will stop when the event turns false.
	Using the type "fall" will stop playback when the event turns true.

	IMPORTANT:
        If the trigger is used for anything else but stopping the sound
 	at a certain event, all sections with the same name *should* have
	exactly the same sections for everything but property and type.

	In the case of just stopping the sample at a certain event, the
	sections for path, volume and pitch may be omitted.
 	
   <path>
 	This defined th path to the sound file. The path is relative to the
 	FlightGear root directory but could be specified absolute.
 
   <property>
 	Define which property triggers the event, and reffers to a node
 	in the FlightGear property tree.
 	 
 	The value is converted to an integer value (anything less than 0.5 is
 	is considered to be 0) and handled if it were a boolean value
 	(0 = false, anything else = true).
 
 	The triger depends on the value of <type>.
 
   <type>
 	This specifies how the event is triggered. When an event is triggered
	the sample will start playing. Since the effects scheduler can have
	multiple events controll a single sound event, it depends on the
	situation if an event actually stops playing the sound.

	Basically the following is true:
		The first event requesting to start playback, triggers playback.
		The last event requesting to stop playback, will stop playback.

 	There are multiple options:
 
 	level: 		events are active if the value is true.
 			this is the default behaviour.
 
 	inverted:	events are active if the value is false.
 
 	flipflop:	events are triggered on state changes.
 			this is only usefull for samples which are played
 			once.

	raise:		start playing at the raise of the event.
			explicitly stop playing when the event turns false.

	fall:		start playing at the fall of the event.
			explicitly stop playing when the event turns true.
 
   <mode>
 	This defines how the sample should be played:
 
 	once:		the sample is played once.
 			this is the default.
 
 	looped:		the sample plays continuesly,
 			until the event turns false.
 
   
   <volume> / <pitch>
 	Volume or Pitch definition. Currently there may be up to 5
	volume and up to 5 pitch definitions defined within one sound
	event. Normally all offset values are added together and the
	results after property calculations will be miltplied.
	A special condition occurs when the value of factor is negative,
	in which case the offset doesn't get added to the other offset values
	but instead will be used in the multiplication section.
 
     <property>
 	Defins which property supplies the value for the calculation.
 	The value is treatened as a floating point number.
 
     <type>
	Defines the function that should be used upon the property
	before it is used for calculating the net result:

 	lin:		lineair handling of the property value.
 			this is the default.
 
 	ln:		convert the property value to a natural logarithmic
 			value before scaling it.
 
 	log:		convert the property value to a true logarithmic
 			value before scaling it.

	inv:		inverse lineair handling (1/x).

	abs:		absolute handling of the value (always positive).

	sqrt:		calculate the square root of the absolute value
			before scaling it.
 
     <factor>
 	Defines the multiplication factor for the property value.
 	A special condition is when scale is defined as a negative
 	value. In this case the result of |<scale>| * <property) will be
 	subtracted from <default>
 
     <offset>
 	The initial value for this sound. This value is also used as an
 	offset value for calulating the end result.
 
     <min>
 	Minimum allowed value.
 	This is usefull if sounds start to sound funny. Anything lower
 	will be truncated to this value.
 
     <max>
 
 	Maximum allowed value.
 	This is usefull if sounds gets to loud. Anything higher will be
 	truncated to this value.

Creating a configrationfile:
---------------------------

To make things easy, there is a default falue for most entries to allow a
sane configuration when a certain entry is omitted.

Default values are:

type:	lin
factor:	1.0
offset:	0.0 for volume, 1.0 for pitch
min:	0.0 (don't check)
max:	0.0 (don't check)

 
 
Calculations are made the following way (for both pitch and volume):
 
   value = 0;
   offs = 0;

   for (n = 0;  n < max; n++) {
      if (factor < 0)
      {
         value += offset[n] - abs(factor[n]) * function(property[n]);
      }
      else
      {
         value += factor[n] * function(property[n]);
         offs += offset[n];
      }
   }

   volume = offs + value;

where function can be one of: lin, ln, log, inv, abs or sqrt