docs-mini/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 About The Property Manager:
  24 --------------------------
  25 The
  26
  27 Sound Architecture:
  28 ------------------
  29 All of the sound configuration files are XML-encoded* property lists.
  30 The root element of each file is always named <PropertyList>. Tags are
  31 almost always found in pairs, with the closing tag having a slash
  32 prefixing the tag name, i.e </PropertyList>. The exception is the tag
  33 representing an aliased property. In this case a slash is prepended to
  34 the closing angle bracket.  (see section Aliasing)
  35
  36 The top level sound configuration file is composed of a <fx>, a
  37 <name>, a <path> sound file and zero or more <volume> and/or <pitch>
  38 definitions.
  39
  40 [ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
  41 [ Absolute paths may be used.Comments are bracketed with <!-- -->.            ]
  42
  43 A limited sound configuration file would look something like this:
  44
  45 <PropertyList>
  46  <fx>
  47   <engine>
  48    <name>engine</name>
  49    <path>Sounds/wasp.wav</path>
  50    <mode>looped</mode>
  51    <property>/engines/engine/running</property>
  52    <volume>
  53     <property>/engines/engine/mp-osi</property>
  54     <factor>0.005</factor>
  55     <min>0.15</min>
  56     <max>0.5</max>
  57     <offset>0.15</offset>
  58    </volume>
  59    <pitch>
  60     <property>/engines/engine/rpm</property>
  61     <factor>0.0012</factor>
  62     <min>0.3</min>
  63     <max>5.0</max>
  64     <offset>0.3</offset>
  65    </pitch>
  66   </engine>
  67  </fx>
  68 </PropertyList>
  69
  70 This would define an engine sound event handler for a piston engine driven
  71 aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
  72 and is named wasp.wav. The event is started when the property
  73 /engines/engine/running becomes non zero.
  74
  75 When that happens, the sound will be played looped (see <mode>) until the
  76 property returns zero again. As you can see the volume is mp-osi dependant,
  77 and the pitch of the sound depents on the engine rpm.
  78
  79 Configuration description:
  80 -------------------------
  81
  82 <fx>
  83         Named FX subtree living under /sim/sound
  84
  85  < ... >
  86         This is the event seperator. The text inside the brackets
  87         can be anything. Bit it is adviced to give it a meaningfull name
  88         like:
  89         crank, engine, rumble, gear, squeal, flap, wind, stall or click.
  90
  91         The value can be defined multiple times, thus anything which is
  92         related may have the same name.
  93
  94    <name>
  95         This defines the name of the event. This name is used internally
  96         and, although it can me defined multiple times in the same file,
  97         should have a unique value unless you realy know what you're doing.
  98
  99         Defining it multiple times could lead to unexpected behaviour.
 100
 101    <path>
 102         This defined th path to the sound file. The path is relative to the
 103         FlightGear root directory but could be specified absolute.
 104
 105    <property>
 106         Define which property triggers the event, and reffers to a node
 107         in the FlightGear property tree.
 108
 109         The value is converted to an integer value (anything less than 0.5 is
 110         is considered to be 0) and handled if it were a boolean value
 111         (0 = false, anything else = true).
 112
 113         The triger depends on the value of <type>.
 114
 115    <type>
 116         This specifies how the event is triggered.
 117         There are multiple options:
 118
 119         level:          events are active if the value is true.
 120                         this is the default behaviour.
 121
 122         inverted:       events are active if the value is false.
 123
 124         flipflop:       events are triggered on state changes.
 125                         this is only usefull for samples which are played
 126                         once.
 127
 128    <mode>
 129         This defines how the sample should be played:
 130
 131         once:           the sample is played once.
 132                         this is the default.
 133
 134         looped:         the sample plays continuesly,
 135                         until the event turns false.
 136
 137
 138    <volume> / <pitch>
 139         Volume or Pitch definition. Currently there may be up to 5
 140         volume and up to 5 pitch definitions defined within one sound
 141         event. Normally all <offset> values are added together and the
 142         results after property calculations will be miltplied.
 143         A special condition occurs when the <factor> value is negative,
 144         in which case the offset doesn't get added to the other offset values
 145         but instead will be used in the multiplication section.
 146
 147      <property>
 148         Defins which property supplies the value for the calculation.
 149         The value is treatened as a floating point number.
 150
 151      <type>
 152         lin:            lineair handling of the property value.
 153                         this is the default.
 154
 155         ln:             convert the property value to a natural logarithmic
 156                         value before scaling it.
 157
 158         log:            convert the property value to a true logarithmic
 159                         value before scaling it.
 160
 161      <factor>
 162         Defines the multiplication factor for the property value.
 163         A special condition is when scale is defined as a negative
 164         value. In this case the result of |<scale>| * <property) will be
 165         subtracted from <default>
 166
 167      <offset>
 168         The initial value for this sound. This value is also used as an
 169         offset value for calulating the end result.
 170
 171      <min>
 172         Minimum allowed value.
 173         This is usefull if sounds start to sound funny. Anything lower
 174         will be converted to 0.
 175
 176      <max>
 177
 178         Maximum allowed value.
 179         This is usefull if sounds gets to loud. Anything higher will be
 180         truncated to this value.
 181
 182
 183  Calculations are made the following way
 184  (function can be one of: none, ln or log ):
 185
 186    if (scale < 0) {
 187       value[i] = offset[n] - abs(scale[n]) * function(property[n])
 188       offset[i] = 0;
 189    } else
 190       value[i] = scale[n] * function(property[n])
 191
 192  And the end result will be:
 193
 194  result = offset[0..max] + value[0..max];
 195
 196
 197
 198