docs-mini/README.xmlsound

   1 Users Guide to FlightGear sound configuration
   2 Version 0.7.11, apr 27 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    <condition>
  48     <property>/engines/engine/running</property>
  49    </condition>
  50    <volume>
  51     <property>/engines/engine/mp-osi</property>
  52     <factor>0.005</factor>
  53     <min>0.15</min>
  54     <max>0.5</max>
  55     <offset>0.15</offset>
  56    </volume>
  57    <pitch>
  58     <property>/engines/engine/rpm</property>
  59     <factor>0.0012</factor>
  60     <min>0.3</min>
  61     <max>5.0</max>
  62     <offset>0.3</offset>
  63    </pitch>
  64   </engine>
  65  </fx>
  66 </PropertyList>
  67
  68 This would define an engine sound event handler for a piston engine driven
  69 aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
  70 and is named wasp.wav. The event is started when the property
  71 /engines/engine/running becomes non zero.
  72
  73 When that happens, the sound will be played looped (see <mode>) until the
  74 property returns zero again. As you can see the volume is mp-osi dependant,
  75 and the pitch of the sound depents on the engine rpm.
  76
  77 Configuration description:
  78 -------------------------
  79
  80 <fx>
  81         Named FX subtree living under /sim/sound
  82
  83  < ... >
  84         This is the event seperator. The text inside the brackets
  85         can be anything. Bit it is adviced to give it a meaningfull name
  86         like: crank, engine, rumble, gear, squeal, flap, wind or stall
  87
  88         The value can be defined multiple times, thus anything which is
  89         related may have the same name (grouping them together).
  90
  91    <name>
  92         This defines the name of the event. This name is used internally
  93         and, although it can me defined multiple times in the same file,
  94         should normally have an unique value.
  95
  96         Multiple definitions of the same name will allow multiple sections
  97         to interfere in the starting and stopping of the sample.
  98
  99         This method can't be used to controll the pitch or volume of the
 100         sample, but instead multiple volume or pitch section should be
 101         included inside the same event.
 102
 103         The types "raise" and "fall" will stop the playback of the sample
 104         regardless of any other event. This means that when the type "raise"
 105         is supplied, sample playback will stop when the event turns false.
 106         Using the type "fall" will stop playback when the event turns true.
 107
 108         IMPORTANT:
 109         If the trigger is used for anything else but stopping the sound
 110         at a certain event, all sections with the same name *should* have
 111         exactly the same sections for everything but property and type.
 112
 113         In the case of just stopping the sample at a certain event, the
 114         sections for path, volume and pitch may be omitted.
 115
 116    <path>
 117         This defined th path to the sound file. The path is relative to the
 118         FlightGear root directory but could be specified absolute.
 119
 120    <condition>
 121         Define a condition that triggers the event.
 122         For a complete description of the FlightGear conditions,
 123         please read docs-mini/README.conditions
 124
 125         An event should define either a condition or a property.
 126
 127    <property>
 128         Define which property triggers the event, and reffers to a node
 129         in the FlightGear property tree. Action is taken when the property
 130         is non zero.
 131
 132         A more sophisticated mechanism to trigger the event is described
 133         in <condition>
 134
 135    <mode>
 136         This defines how the sample should be played:
 137
 138         once:           the sample is played once.
 139                         this is the default.
 140
 141         looped:         the sample plays continuesly,
 142                         until the event turns false.
 143
 144         in-transit:     the sample plays continuesly,
 145                         while the property is changing its value.
 146
 147    <volume> / <pitch>
 148         Volume or Pitch definition. Currently there may be up to 5
 149         volume and up to 5 pitch definitions defined within one sound
 150         event. Normally all offset values are added together and the
 151         results after property calculations will be miltplied.
 152         A special condition occurs when the value of factor is negative,
 153         in which case the offset doesn't get added to the other offset values
 154         but instead will be used in the multiplication section.
 155
 156      <property>
 157         Defins which property supplies the value for the calculation.
 158         Either a <property> or an <internal> should be defined.
 159         The value is treatened as a floating point number.
 160
 161      <internal>
 162         Defins which internal variable should be used for the calculation.
 163         The value is treatened as a floating point number.
 164         The following internals are available at this time:
 165
 166         dt_play:        the number of seconds since the sound started playing.
 167
 168         dt_stop:        the number of seconds after the sound has stopped.
 169
 170      <type>
 171         Defines the function that should be used upon the property
 172         before it is used for calculating the net result:
 173
 174         lin:            lineair handling of the property value.
 175                         this is the default.
 176
 177         ln:             convert the property value to a natural logarithmic
 178                         value before scaling it. Anything below 1 will return
 179                         zero.
 180
 181         log:            convert the property value to a true logarithmic
 182                         value before scaling it. Anything below 1 will return
 183                         zero.
 184
 185         inv:            inverse lineair handling (1/x).
 186
 187         abs:            absolute handling of the value (always positive).
 188
 189         sqrt:           calculate the square root of the absolute value
 190                         before scaling it.
 191
 192      <factor>
 193         Defines the multiplication factor for the property value.
 194         A special condition is when scale is defined as a negative
 195         value. In this case the result of |<scale>| * <property) will be
 196         subtracted from <default>
 197
 198      <offset>
 199         The initial value for this sound. This value is also used as an
 200         offset value for calulating the end result.
 201
 202      <min>
 203         Minimum allowed value.
 204         This is usefull if sounds start to sound funny. Anything lower
 205         will be truncated to this value.
 206
 207      <max>
 208         Maximum allowed value.
 209         This is usefull if sounds gets to loud. Anything higher will be
 210         truncated to this value.
 211
 212    <position>
 213         Specify the position of the sounds source relative to the
 214         pilot's ears.  The coordinate system used is a right hand
 215         coordinate system where -X = left, +X = right, -Y = down, +Y =
 216         up, -Z = forward, +Z = aft.  Distances are in meters.
 217
 218      <x>
 219         X dimension offset
 220
 221      <y>
 222         Y dimension offset
 223
 224      <z>
 225         Z dimension offset
 226
 227    <reference-dist>
 228         Set a reference distance of sound in meters.  This is the
 229         distance where the gain/volume will be halved.  This can be
 230         useful for limiting cockpit sounds to the cockpit.
 231
 232    <max-dist>
 233         Set the maximum audible distance for the sound in meters.
 234         This can be useful for limiting cockpit sounds to the cockpit.
 235
 236
 237 Creating a configrationfile:
 238 ---------------------------
 239
 240 To make things easy, there is a default falue for most entries to allow a
 241 sane configuration when a certain entry is omitted.
 242
 243 Default values are:
 244
 245 type:   lin
 246 factor: 1.0
 247 offset: 0.0 for volume, 1.0 for pitch
 248 min:    0.0
 249 max:    0.0 (don't check)
 250
 251
 252
 253 Calculations are made the following way (for both pitch and volume):
 254
 255    value = 0;
 256    offs = 0;
 257
 258    for (n = 0;  n < max; n++) {
 259       if (factor < 0)
 260       {
 261          value += offset[n] - abs(factor[n]) * function(property[n]);
 262       }
 263       else
 264       {
 265          value += factor[n] * function(property[n]);
 266          offs += offset[n];
 267       }
 268    }
 269
 270    volume = offs + value;
 271
 272 where function can be one of: lin, ln, log, inv, abs or sqrt