docs-mini/README.xmlsound

   1 Users Guide to FlightGear sound configuration
   2 Version 0.9.8, October 30, 2005
   3 Author: Erik Hofman <erik at ehofman dot com>
   4
   5 This document is an attempt to describe the configuration of
   6 FlightGear flight simulator's aircraft sound in XML.
   7
   8 Sound Architecture:
   9 ------------------
  10 All of the sound configuration files are XML-encoded* property lists.
  11 The root element of each file is always named <PropertyList>. Tags are
  12 almost always found in pairs, with the closing tag having a slash
  13 prefixing the tag name, i.e </PropertyList>. The exception is the tag
  14 representing an aliased property. In this case a slash is prepended to
  15 the closing angle bracket.  (see section Aliasing)
  16
  17 The top level sound configuration file is composed of a <fx>, a
  18 <name>, a <path> sound file and zero or more <volume> and/or <pitch>
  19 definitions.
  20
  21 [ Paths are relative to $FG_ROOT (the root of the installed base package .) ]
  22 [ Absolute paths may be used. Comments are bracketed with <!-- -->.         ]
  23
  24 A limited sound configuration file would look something like this:
  25
  26 <PropertyList>
  27  <fx>
  28   <engine>
  29    <name>engine</name>
  30    <path>Sounds/wasp.wav</path>
  31    <mode>looped</mode>
  32    <condition>
  33     <property>/engines/engine/running</property>
  34    </condition>
  35    <volume>
  36     <property>/engines/engine/mp-osi</property>
  37     <factor>0.005</factor>
  38     <min>0.15</min>
  39     <max>0.5</max>
  40     <offset>0.15</offset>
  41    </volume>
  42    <pitch>
  43     <property>/engines/engine/rpm</property>
  44     <factor>0.0012</factor>
  45     <min>0.3</min>
  46     <max>5.0</max>
  47     <offset>0.3</offset>
  48    </pitch>
  49   </engine>
  50  </fx>
  51 </PropertyList>
  52
  53 This would define an engine sound event handler for a piston engine driven
  54 aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
  55 and is named wasp.wav. The event is started when the property
  56 /engines/engine/running becomes non zero.
  57
  58 When that happens, the sound will be played looped (see <mode>) until the
  59 property returns zero again. As you can see the volume is mp-osi dependent,
  60 and the pitch of the sound depends on the engine rpm.
  61
  62 Configuration description:
  63 -------------------------
  64
  65 <fx>
  66         Named FX subtree living under /sim/sound
  67
  68  < ... >
  69         This is the event separator. The text inside the brackets
  70         can be anything. Bit it is advised to give it a meaningful name
  71         like: crank, engine, rumble, gear, squeal, flap, wind or stall
  72
  73         The value can be defined multiple times, thus anything which is
  74         related may have the same name (grouping them together).
  75
  76    <name>
  77         This defines the name of the event. This name is used internally
  78         and, although it can me defined multiple times in the same file,
  79         should normally have an unique value.
  80
  81         Multiple definitions of the same name will allow multiple sections
  82         to interfere in the starting and stopping of the sample.
  83
  84         This method can't be used to control the pitch or volume of the
  85         sample, but instead multiple volume or pitch section should be
  86         included inside the same event.
  87
  88         The types "raise" and "fall" will stop the playback of the sample
  89         regardless of any other event. This means that when the type "raise"
  90         is supplied, sample playback will stop when the event turns false.
  91         Using the type "fall" will stop playback when the event turns true.
  92
  93         IMPORTANT:
  94         If the trigger is used for anything else but stopping the sound
  95          at a certain event, all sections with the same name *should* have
  96         exactly the same sections for everything but property and type.
  97
  98         In the case of just stopping the sample at a certain event, the
  99         sections for path, volume and pitch may be omitted.
 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    <condition>
 106         Define a condition that triggers the event.
 107         For a complete description of the FlightGear conditions,
 108         please read docs-mini/README.conditions
 109
 110         An event should define either a condition or a property.
 111
 112    <property>
 113         Define which property triggers the event, and refers to a node
 114         in the FlightGear property tree. Action is taken when the property
 115         is non zero.
 116
 117         A more sophisticated mechanism to trigger the event is described
 118         in <condition>
 119
 120    <mode>
 121         This defines how the sample should be played:
 122
 123         once:           the sample is played once.
 124                         this is the default.
 125
 126         looped:         the sample plays continuously,
 127                         until the event turns false.
 128
 129         in-transit:     the sample plays continuously,
 130                         while the property is changing its value.
 131
 132    <volume> / <pitch>
 133         Volume or Pitch definition. Currently there may be up to 5
 134         volume and up to 5 pitch definitions defined within one sound
 135         event. Normally all offset values are added together and the
 136         results after property calculations will be multiplied.
 137         A special condition occurs when the value of factor is negative,
 138         in which case the offset doesn't get added to the other offset values
 139         but instead will be used in the multiplication section.
 140
 141      <property>
 142         Defines which property supplies the value for the calculation.
 143         Either a <property> or an <internal> should be defined.
 144         The value is treated as a floating point number.
 145
 146      <internal>
 147         Defines which internal variable should be used for the calculation.
 148         The value is treated as a floating point number.
 149         The following internals are available at this time:
 150
 151         dt_play:        the number of seconds since the sound started playing.
 152
 153         dt_stop:        the number of seconds after the sound has stopped.
 154
 155      <delay-sec>
 156         Delay after which the sound starts playing. This is useful to let
 157         a property start two sounds at the same time, where the second is
 158         delayed until the first stopped playing.
 159
 160      <type>
 161         Defines the function that should be used upon the property
 162         before it is used for calculating the net result:
 163
 164         lin:            linear handling of the property value.
 165                         this is the default.
 166
 167         ln:             convert the property value to a natural logarithmic
 168                         value before scaling it. Anything below 1 will return
 169                         zero.
 170
 171         log:            convert the property value to a true logarithmic
 172                         value before scaling it. Anything below 1 will return
 173                         zero.
 174
 175         inv:            inverse linear handling (1/x).
 176
 177         abs:            absolute handling of the value (always positive).
 178
 179         sqrt:           calculate the square root of the absolute value
 180                         before scaling it.
 181
 182      <factor>
 183         Defines the multiplication factor for the property value.
 184         A special condition is when scale is defined as a negative
 185         value. In this case the result of |<scale>| * <property) will be
 186         subtracted from <default>
 187
 188      <offset>
 189         The initial value for this sound. This value is also used as an
 190         offset value for calculating the end result.
 191
 192      <min>
 193         Minimum allowed value.
 194         This is useful if sounds start to sound funny. Anything lower
 195         will be truncated to this value.
 196
 197      <max>
 198         Maximum allowed value.
 199         This is useful if sounds gets to loud. Anything higher will be
 200         truncated to this value.
 201
 202    <position>
 203         Specify the position of the sounds source relative to the
 204         aircraft center.  The coordinate system used is a right hand
 205         coordinate system where +Z = left, -Z = right, +X = down, -X =
 206         up, +Y = forward, -Y = aft.  Distances are in meters.
 207         The volume calculation due to distance and orientation of the
 208         sounds source ONLY work on mono samples!
 209
 210      <x>
 211         X dimension offset
 212
 213      <y>
 214         Y dimension offset
 215
 216      <z>
 217         Z dimension offset
 218
 219
 220    <orientation>
 221         Specify the orientation of the sounds source.
 222
 223         The zero vector is default, indicating that a Source is not directional.
 224         Specifying a non-zero vector will make the Source directional in
 225         the X,Y,Z direction
 226
 227      <x>
 228         X dimension
 229
 230      <y>
 231         Y dimension
 232
 233      <z>
 234         Z dimension
 235
 236      <inner-angle>
 237         The inner edge of the audio cone in degrees (0.0 - 180.0).
 238         Any sound withing that angle will be played at the current gain.
 239
 240      <outer-angle>
 241         The outer edge of the audio cone in degrees (0.0 - 180.0).
 242         Any sound beyond the outer cone will be played at "outer-gain" volume.
 243
 244      <outer-gain>
 245         The gain at the outer edge of the cone.
 246
 247
 248    <reference-dist>
 249         Set a reference distance of sound in meters.  This is the
 250         distance where the gain/volume will be halved.  This can be
 251         useful for limiting cockpit sounds to the cockpit.
 252
 253    <max-dist>
 254         Set the maximum audible distance for the sound in meters.
 255         This can be useful for limiting cockpit sounds to the cockpit.
 256
 257
 258 Creating a configuration file:
 259 ------------------------------
 260
 261 To make things easy, there is a default value for most entries to allow a
 262 sane configuration when a certain entry is omitted.
 263
 264 Default values are:
 265
 266 type:   lin
 267 factor: 1.0
 268 offset: 0.0 for volume, 1.0 for pitch
 269 min:    0.0
 270 max:    0.0 (don't check)
 271
 272
 273
 274 Calculations are made the following way (for both pitch and volume):
 275
 276    value = 0;
 277    offs = 0;
 278
 279    for (n = 0;  n < max; n++) {
 280       if (factor < 0)
 281       {
 282          value += offset[n] - abs(factor[n]) * function(property[n]);
 283       }
 284       else
 285       {
 286           value += factor[n] * function(property[n]);
 287           offs += offset[n];
 288       }
 289    }
 290
 291    volume = offs + value;
 292
 293 where function can be one of: lin, ln, log, inv, abs or sqrt