1 Users Guide to FlightGear sound configuration
2 Version 0.9.8, October 30, 2005
3 Author: Erik Hofman <erik at ehofman dot com>
5 This document is an attempt to describe the configuration of
6 FlightGear flight simulator's aircraft sound in XML.
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)
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>
21 [ Paths are relative to $FG_ROOT (the root of the installed base package .) ]
22 [ Absolute paths may be used. Comments are bracketed with <!-- -->. ]
24 A limited sound configuration file would look something like this:
30 <path>Sounds/wasp.wav</path>
33 <property>/engines/engine/running</property>
36 <property>/engines/engine/mp-osi</property>
37 <factor>0.005</factor>
43 <property>/engines/engine/rpm</property>
44 <factor>0.0012</factor>
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.
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.
62 Configuration description:
63 -------------------------
66 Named FX subtree living under /sim/sound
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
73 The value can be defined multiple times, thus anything which is
74 related may have the same name (grouping them together).
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.
81 Multiple definitions of the same name will allow multiple sections
82 to interfere in the starting and stopping of the sample.
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.
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.
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.
98 In the case of just stopping the sample at a certain event, the
99 sections for path, volume and pitch may be omitted.
102 This defined th path to the sound file. The path is relative to the
103 FlightGear root directory but could be specified absolute.
106 Define a condition that triggers the event.
107 For a complete description of the FlightGear conditions,
108 please read docs-mini/README.conditions
110 An event should define either a condition or a 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
117 A more sophisticated mechanism to trigger the event is described
121 This defines how the sample should be played:
123 once: the sample is played once.
126 looped: the sample plays continuesly,
127 until the event turns false.
129 in-transit: the sample plays continuesly,
130 while the property is changing its value.
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 miltplied.
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.
142 Defines which property supplies the value for the calculation.
143 Either a <property> or an <internal> should be defined.
144 The value is threated as a floating point number.
147 Defines which internal variable should be used for the calculation.
148 The value is threated as a floating point number.
149 The following internals are available at this time:
151 dt_play: the number of seconds since the sound started playing.
153 dt_stop: the number of seconds after the sound has stopped.
156 Defines the function that should be used upon the property
157 before it is used for calculating the net result:
159 lin: linear handling of the property value.
162 ln: convert the property value to a natural logarithmic
163 value before scaling it. Anything below 1 will return
166 log: convert the property value to a true logarithmic
167 value before scaling it. Anything below 1 will return
170 inv: inverse linear handling (1/x).
172 abs: absolute handling of the value (always positive).
174 sqrt: calculate the square root of the absolute value
178 Defines the multiplication factor for the property value.
179 A special condition is when scale is defined as a negative
180 value. In this case the result of |<scale>| * <property) will be
181 subtracted from <default>
184 The initial value for this sound. This value is also used as an
185 offset value for calculating the end result.
188 Minimum allowed value.
189 This is useful if sounds start to sound funny. Anything lower
190 will be truncated to this value.
193 Maximum allowed value.
194 This is useful if sounds gets to loud. Anything higher will be
195 truncated to this value.
198 Specify the position of the sounds source relative to the
199 pilot's ears. The coordinate system used is a right hand
200 coordinate system where -X = left, +X = right, -Y = down, +Y =
201 up, -Z = forward, +Z = aft. Distances are in meters.
214 Specify the orientation of the sounds source.
216 The zero vector is default, indicating that a Source is not directional.
217 Specifying a non-zero vector will make the Source directional.
220 X dimension angle (0.0 - 360.0)
223 Y dimension angle (0.0 - 360.0)
226 Z dimension angle (0.0 - 360.0)
229 The inner edge of the audio cone in degrees (0.0 - 360.0).
230 Any sound withing that angle will be played at the current gain.
233 The outer edge of the audio cone in degrees (0.0 - 360.0).
234 Any sound beyond the outer cone will be played at "outer-gain" volume.
237 The gain at the outer edge of the cone.
241 Set a reference distance of sound in meters. This is the
242 distance where the gain/volume will be halved. This can be
243 useful for limiting cockpit sounds to the cockpit.
246 Set the maximum audible distance for the sound in meters.
247 This can be useful for limiting cockpit sounds to the cockpit.
250 Creating a configration file:
251 ----------------------------
253 To make things easy, there is a default value for most entries to allow a
254 sane configuration when a certain entry is omitted.
260 offset: 0.0 for volume, 1.0 for pitch
262 max: 0.0 (don't check)
266 Calculations are made the following way (for both pitch and volume):
271 for (n = 0; n < max; n++) {
274 value += offset[n] - abs(factor[n]) * function(property[n]);
278 value += factor[n] * function(property[n]);
283 volume = offs + value;
285 where function can be one of: lin, ln, log, inv, abs or sqrt