1 Users Guide to FlightGear sound configuration
2 Version 0.7.11, apr 27 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>
48 <property>/engines/engine/running</property>
51 <property>/engines/engine/mp-osi</property>
52 <factor>0.005</factor>
58 <property>/engines/engine/rpm</property>
59 <factor>0.0012</factor>
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.
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.
77 Configuration description:
78 -------------------------
81 Named FX subtree living under /sim/sound
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
88 The value can be defined multiple times, thus anything which is
89 related may have the same name (grouping them together).
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.
96 Multiple definitions of the same name will allow multiple sections
97 to interfere in the starting and stopping of the sample.
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.
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.
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.
113 In the case of just stopping the sample at a certain event, the
114 sections for path, volume and pitch may be omitted.
117 This defined th path to the sound file. The path is relative to the
118 FlightGear root directory but could be specified absolute.
121 Define a condition that triggers the event.
122 For a complete description of the FlightGear conditions,
123 please read docs-mini/README.conditions
125 An event should define either a condition or a 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
132 A more sophisticated mechanism to trigger the event is described
136 This defines how the sample should be played:
138 once: the sample is played once.
141 looped: the sample plays continuesly,
142 until the event turns false.
144 in-transit: the sample plays continuesly,
145 while the property is changing its value.
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.
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.
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:
166 dt_play: the number of seconds since the sound started playing.
168 dt_stop: the number of seconds after the sound has stopped.
171 Defines the function that should be used upon the property
172 before it is used for calculating the net result:
174 lin: lineair handling of the property value.
177 ln: convert the property value to a natural logarithmic
178 value before scaling it. Anything below 1 will return
181 log: convert the property value to a true logarithmic
182 value before scaling it. Anything below 1 will return
185 inv: inverse lineair handling (1/x).
187 abs: absolute handling of the value (always positive).
189 sqrt: calculate the square root of the absolute value
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>
199 The initial value for this sound. This value is also used as an
200 offset value for calulating the end result.
203 Minimum allowed value.
204 This is usefull if sounds start to sound funny. Anything lower
205 will be truncated to this value.
208 Maximum allowed value.
209 This is usefull if sounds gets to loud. Anything higher will be
210 truncated to this value.
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.
229 Specify the orientation of the sounds source.
231 The zero vector is default, indicating that a Source is not directional.
232 Specifying a non-zero vector will make the Source directional.
235 X dimension angle (0.0 - 360.0)
238 Y dimension angle (0.0 - 360.0)
241 Z dimension angle (0.0 - 360.0)
244 The inner edge of the audio cone in degrees (0.0 - 360.0).
245 Any sound withing that angle will be played at the current gain.
248 The outer edge of the audio cone in degrees (0.0 - 360.0).
249 Any sound beyond the outer cone will be played at "outer-gain" volume.
252 The gain at the outer edge of the cone.
256 Set a reference distance of sound in meters. This is the
257 distance where the gain/volume will be halved. This can be
258 useful for limiting cockpit sounds to the cockpit.
261 Set the maximum audible distance for the sound in meters.
262 This can be useful for limiting cockpit sounds to the cockpit.
265 Creating a configrationfile:
266 ---------------------------
268 To make things easy, there is a default falue for most entries to allow a
269 sane configuration when a certain entry is omitted.
275 offset: 0.0 for volume, 1.0 for pitch
277 max: 0.0 (don't check)
281 Calculations are made the following way (for both pitch and volume):
286 for (n = 0; n < max; n++) {
289 value += offset[n] - abs(factor[n]) * function(property[n]);
293 value += factor[n] * function(property[n]);
298 volume = offs + value;
300 where function can be one of: lin, ln, log, inv, abs or sqrt