1 Users Guide to FlightGear sound configuration
2 Version 0.7.10, Mar 02 2002
3 Author: Erik Hofman <erik@ehofman.com>
5 This document is an attempt to describe the configuration of
6 FlightGear flight simulator's aircraft sound via XML.
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.
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
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)
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>
36 [ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
37 [ Absolute paths may be used.Comments are bracketed with <!-- -->. ]
39 A limited sound configuration file would look something like this:
45 <path>Sounds/wasp.wav</path>
47 <property>/engines/engine/running</property>
49 <property>/engines/engine/mp-osi</property>
50 <factor>0.005</factor>
56 <property>/engines/engine/rpm</property>
57 <factor>0.0012</factor>
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.
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.
75 Configuration description:
76 -------------------------
79 Named FX subtree living under /sim/sound
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
86 The value can be defined multiple times, thus anything which is
87 related may have the same name (grouping them together).
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.
94 Multiple definitions of the same name will allow multiple sections
95 to interfere in the starting and stopping of the sample.
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.
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.
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.
111 In the case of just stopping the sample at a certain event, the
112 sections for path, volume and pitch may be omitted.
115 This defined th path to the sound file. The path is relative to the
116 FlightGear root directory but could be specified absolute.
119 Define which property triggers the event, and reffers to a node
120 in the FlightGear property tree.
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).
126 The triger depends on the value of <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.
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.
138 There are multiple options:
140 level: events are active if the value is true.
141 this is the default behaviour.
143 inverted: events are active if the value is false.
145 flipflop: events are triggered on state changes.
146 this is only usefull for samples which are played
149 raise: start playing at the raise of the event.
150 explicitly stop playing when the event turns false.
152 fall: start playing at the fall of the event.
153 explicitly stop playing when the event turns true.
156 This defines how the sample should be played:
158 once: the sample is played once.
161 looped: the sample plays continuesly,
162 until the event turns false.
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.
175 Defins which property supplies the value for the calculation.
176 The value is treatened as a floating point number.
179 Defines the function that should be used upon the property
180 before it is used for calculating the net result:
182 lin: lineair handling of the property value.
185 ln: convert the property value to a natural logarithmic
186 value before scaling it.
188 log: convert the property value to a true logarithmic
189 value before scaling it.
191 inv: inverse lineair handling (1/x).
193 abs: absolute handling of the value (always positive).
195 sqrt: calculate the square root of the absolute value
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>
205 The initial value for this sound. This value is also used as an
206 offset value for calulating the end result.
209 Minimum allowed value.
210 This is usefull if sounds start to sound funny. Anything lower
211 will be truncated to this value.
215 Maximum allowed value.
216 This is usefull if sounds gets to loud. Anything higher will be
217 truncated to this value.
219 Creating a configrationfile:
220 ---------------------------
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.
229 offset: 0.0 for volume, 1.0 for pitch
230 min: 0.0 (don't check)
231 max: 0.0 (don't check)
235 Calculations are made the following way (for both pitch and volume):
240 for (n = 0; n < max; n++) {
243 value += offset[n] - abs(factor[n]) * function(property[n]);
247 value += factor[n] * function(property[n]);
252 volume = offs + value;
254 where function can be one of: lin, ln, log, inv, abs or sqrt