README.xmlsound

   1 Users Guide to FlightGear sound configuration
   2 Version 0.7.10, Mar 02 2002
   3 Author: Erik Hofman <erik@ehofman.com>
   4
   5 This document is an attempt to describe the configuration of
   6 FlightGear flight simulator's aircraft sound via XML.
   7
   8 Some History:
   9 ------------
  10 Older versions of FGFS had a hard coded audio layer.  This was a
  11 than ideal state of affairs due to FGFS ability to use different
  12 aircraft models. Being primarily developed on UNIX type systems, a
  13 modular approach is taken towards the simulation. To date, most
  14 alternatives to the default Cessna 172 aircraft are the product
  15 of research institutions interested in the flight characteristics and
  16 not cosmetics.  The result of this was that one could fly the X-15 or
  17 a Boeing 747 but be limited to C172 sounds.
  18
  19 A rewrite of the sound code was done around v0.7.10 by Erik Hofman
  20 allowing for configuration of the sounds via XML to address this
  21 limitation.
  22
  23 Sound Architecture:
  24 ------------------
  25 All of the sound configuration files are XML-encoded* property lists.
  26 The root element of each file is always named <PropertyList>. Tags are
  27 almost always found in pairs, with the closing tag having a slash
  28 prefixing the tag name, i.e </PropertyList>. The exception is the tag
  29 representing an aliased property. In this case a slash is prepended to
  30 the closing angle bracket.  (see section Aliasing)
  31
  32 The top level sound configuration file is composed of a <fx>, a
  33 <name>, a <path> sound file and zero or more <volume> and/or <pitch>
  34 definitions.
  35
  36 [ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
  37 [ Absolute paths may be used.Comments are bracketed with <!-- -->.            ]
  38
  39 A limited sound configuration file would look something like this:
  40
  41 <PropertyList>
  42  <fx>
  43   <engine>
  44    <name>engine</name>
  45    <path>Sounds/wasp.wav</path>
  46    <mode>looped</mode>
  47    <property>/engines/engine/running</property>
  48    <volume>
  49     <property>/engines/engine/mp-osi</property>
  50     <factor>0.005</factor>
  51     <min>0.15</min>
  52     <max>0.5</max>
  53     <offset>0.15</offset>
  54    </volume>
  55    <pitch>
  56     <property>/engines/engine/rpm</property>
  57     <factor>0.0012</factor>
  58     <min>0.3</min>
  59     <max>5.0</max>
  60     <offset>0.3</offset>
  61    </pitch>
  62   </engine>
  63  </fx>
  64 </PropertyList>
  65
  66 This would define an engine sound event handler for a piston engine driven
  67 aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
  68 and is named wasp.wav. The event is started when the property
  69 /engines/engine/running becomes non zero.
  70
  71 When that happens, the sound will be played looped (see <mode>) until the
  72 property returns zero again. As you can see the volume is mp-osi dependant,
  73 and the pitch of the sound depents on the engine rpm.
  74
  75 Configuration description:
  76 -------------------------
  77
  78 <fx>
  79         Named FX subtree living under /sim/sound
  80
  81  < ... >
  82         This is the event seperator. The text inside the brackets
  83         can be anything. Bit it is adviced to give it a meaningfull name
  84         like: crank, engine, rumble, gear, squeal, flap, wind or stall
  85
  86         The value can be defined multiple times, thus anything which is
  87         related may have the same name (grouping them together).
  88
  89    <name>
  90         This defines the name of the event. This name is used internally
  91         and, although it can me defined multiple times in the same file,
  92         should normally have an unique value.
  93
  94         Multiple definitions of the same name will allow multiple sections
  95         to interfere in the starting and stopping of the sample.
  96
  97         This method can't be used to controll the pitch or volume of the
  98         sample, but instead multiple volume or pitch section should be
  99         included inside the same event.
 100
 101         The types "raise" and "fall" will stop the playback of the sample
 102         regardless of any other event. This means that when the type "raise"
 103         is supplied, sample playback will stop when the event turns false.
 104         Using the type "fall" will stop playback when the event turns true.
 105
 106         IMPORTANT:
 107         If the trigger is used for anything else but stopping the sound
 108         at a certain event, all sections with the same name *should* have
 109         exactly the same sections for everything but property and type.
 110
 111         In the case of just stopping the sample at a certain event, the
 112         sections for path, volume and pitch may be omitted.
 113
 114    <path>
 115         This defined th path to the sound file. The path is relative to the
 116         FlightGear root directory but could be specified absolute.
 117
 118    <property>
 119         Define which property triggers the event, and reffers to a node
 120         in the FlightGear property tree.
 121
 122         The value is converted to an integer value (anything less than 0.5 is
 123         is considered to be 0) and handled if it were a boolean value
 124         (0 = false, anything else = true).
 125
 126         The triger depends on the value of <type>.
 127
 128    <type>
 129         This specifies how the event is triggered. When an event is triggered
 130         the sample will start playing. Since the effects scheduler can have
 131         multiple events controll a single sound event, it depends on the
 132         situation if an event actually stops playing the sound.
 133
 134         Basically the following is true:
 135                 The first event requesting to start playback, triggers playback.
 136                 The last event requesting to stop playback, will stop playback.
 137
 138         There are multiple options:
 139
 140         level:          events are active if the value is true.
 141                         this is the default behaviour.
 142
 143         inverted:       events are active if the value is false.
 144
 145         flipflop:       events are triggered on state changes.
 146                         this is only usefull for samples which are played
 147                         once.
 148
 149         raise:          start playing at the raise of the event.
 150                         explicitly stop playing when the event turns false.
 151
 152         fall:           start playing at the fall of the event.
 153                         explicitly stop playing when the event turns true.
 154
 155    <mode>
 156         This defines how the sample should be played:
 157
 158         once:           the sample is played once.
 159                         this is the default.
 160
 161         looped:         the sample plays continuesly,
 162                         until the event turns false.
 163
 164
 165    <volume> / <pitch>
 166         Volume or Pitch definition. Currently there may be up to 5
 167         volume and up to 5 pitch definitions defined within one sound
 168         event. Normally all offset values are added together and the
 169         results after property calculations will be miltplied.
 170         A special condition occurs when the value of factor is negative,
 171         in which case the offset doesn't get added to the other offset values
 172         but instead will be used in the multiplication section.
 173
 174      <property>
 175         Defins which property supplies the value for the calculation.
 176         The value is treatened as a floating point number.
 177
 178      <type>
 179         Defines the function that should be used upon the property
 180         before it is used for calculating the net result:
 181
 182         lin:            lineair handling of the property value.
 183                         this is the default.
 184
 185         ln:             convert the property value to a natural logarithmic
 186                         value before scaling it.
 187
 188         log:            convert the property value to a true logarithmic
 189                         value before scaling it.
 190
 191         inv:            inverse lineair handling (1/x).
 192
 193         abs:            absolute handling of the value (always positive).
 194
 195         sqrt:           calculate the square root of the absolute value
 196                         before scaling it.
 197
 198      <factor>
 199         Defines the multiplication factor for the property value.
 200         A special condition is when scale is defined as a negative
 201         value. In this case the result of |<scale>| * <property) will be
 202         subtracted from <default>
 203
 204      <offset>
 205         The initial value for this sound. This value is also used as an
 206         offset value for calulating the end result.
 207
 208      <min>
 209         Minimum allowed value.
 210         This is usefull if sounds start to sound funny. Anything lower
 211         will be truncated to this value.
 212
 213      <max>
 214
 215         Maximum allowed value.
 216         This is usefull if sounds gets to loud. Anything higher will be
 217         truncated to this value.
 218
 219 Creating a configrationfile:
 220 ---------------------------
 221
 222 To make things easy, there is a default falue for most entries to allow a
 223 sane configuration when a certain entry is omitted.
 224
 225 Default values are:
 226
 227 type:   lin
 228 factor: 1.0
 229 offset: 0.0 for volume, 1.0 for pitch
 230 min:    0.0 (don't check)
 231 max:    0.0 (don't check)
 232
 233
 234
 235 Calculations are made the following way (for both pitch and volume):
 236
 237    value = 0;
 238    offs = 0;
 239
 240    for (n = 0;  n < max; n++) {
 241       if (factor < 0)
 242       {
 243          value += offset[n] - abs(factor[n]) * function(property[n]);
 244       }
 245       else
 246       {
 247          value += factor[n] * function(property[n]);
 248          offs += offset[n];
 249       }
 250    }
 251
 252    volume = offs + value;
 253
 254 where function can be one of: lin, ln, log, inv, abs or sqrt