]> git.mxchange.org Git - flightgear.git/blob - docs-mini/README.xmlsound
Simplify fgValidatePath + minor fix (requires simgear update)
[flightgear.git] / 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   <type>
133         This defines the type os this sample:
134
135         fx:             this is the default type and doesn't need to be defined.
136
137         avionics:       sounds set to this type don't have a position and
138                         orientation but are treated as if it's mounted to
139                         the aircraft panel. it's up to the user to define
140                         if it can always be heard or only when in cockpit
141                         view.
142    
143    <volume> / <pitch>
144         Volume or Pitch definition. Currently there may be up to 5
145         volume and up to 5 pitch definitions defined within one sound
146         event. Normally all offset values are added together and the
147         results after property calculations will be multiplied.
148         A special condition occurs when the value of factor is negative,
149         in which case the offset doesn't get added to the other offset values
150         but instead will be used in the multiplication section.
151  
152      <property>
153         Defines which property supplies the value for the calculation.
154         Either a <property> or an <internal> should be defined.
155         The value is treated as a floating point number.
156
157      <internal>
158         Defines which internal variable should be used for the calculation.
159         The value is treated as a floating point number.
160         The following internals are available at this time:
161
162         dt_play:        the number of seconds since the sound started playing.
163
164         dt_stop:        the number of seconds after the sound has stopped.
165  
166      <delay-sec>
167         Delay after which the sound starts playing. This is useful to let
168         a property start two sounds at the same time, where the second is
169         delayed until the first stopped playing.
170
171      <type>
172         Defines the function that should be used upon the property
173         before it is used for calculating the net result:
174
175         lin:            linear handling of the property value.
176                         this is the default.
177  
178         ln:             convert the property value to a natural logarithmic
179                         value before scaling it. Anything below 1 will return
180                         zero.
181  
182         log:            convert the property value to a true logarithmic
183                         value before scaling it. Anything below 1 will return
184                         zero.
185
186         inv:            inverse linear handling (1/x).
187
188         abs:            absolute handling of the value (always positive).
189
190         sqrt:           calculate the square root of the absolute value
191                         before scaling it.
192  
193      <factor>
194         Defines the multiplication factor for the property value.
195         A special condition is when scale is defined as a negative
196         value. In this case the result of |<scale>| * <property) will be
197         subtracted from <default>
198  
199      <offset>
200         The initial value for this sound. This value is also used as an
201         offset value for calculating the end result.
202  
203      <min>
204         Minimum allowed value.
205         This is useful if sounds start to sound funny. Anything lower
206         will be truncated to this value.
207  
208      <max>
209         Maximum allowed value.
210         This is useful if sounds gets to loud. Anything higher will be
211         truncated to this value.
212
213    <position>
214         Specify the position of the sounds source relative to the
215         aircraft center.  The coordinate system used is a left hand
216         coordinate system where +Y = left, -Y = right, -Z = down, +Z =
217         up, -X = forward, +X = aft.  Distances are in meters.
218         The volume calculation due to distance and orientation of the
219         sounds source ONLY work on mono samples!
220
221      <x>
222         X dimension offset
223
224      <y>
225         Y dimension offset
226
227      <z>
228         Z dimension offset
229
230
231    <orientation>
232         Specify the orientation of the sounds source.
233
234         The zero vector is default, indicating that a Source is not directional.
235         Specifying a non-zero vector will make the Source directional in
236         the X,Y,Z direction
237
238      <x>
239         X dimension
240
241      <y>
242         Y dimension
243
244      <z>
245         Z dimension
246
247      <inner-angle>
248         The inner edge of the audio cone in degrees (0.0 - 180.0).
249         Any sound withing that angle will be played at the current gain.
250
251      <outer-angle>
252         The outer edge of the audio cone in degrees (0.0 - 180.0).
253         Any sound beyond the outer cone will be played at "outer-gain" volume.
254
255      <outer-gain>
256         The gain at the outer edge of the cone.
257
258
259    <reference-dist>
260         Set a reference distance of sound in meters.  This is the
261         distance where the gain/volume will be halved.  This can be
262         useful for limiting cockpit sounds to the cockpit.
263
264    <max-dist>
265         Set the maximum audible distance for the sound in meters.
266         This can be useful for limiting cockpit sounds to the cockpit.
267
268
269 Creating a configuration file:
270 ------------------------------
271
272 To make things easy, there is a default value for most entries to allow a
273 sane configuration when a certain entry is omitted.
274
275 Default values are:
276
277 type:   lin
278 factor: 1.0
279 offset: 0.0 for volume, 1.0 for pitch
280 min:    0.0
281 max:    0.0 (don't check)
282
283  
284  
285 Calculations are made the following way (for both pitch and volume):
286  
287    value = 0;
288    offs = 0;
289
290    for (n = 0;  n < max; n++) {
291       if (factor < 0)
292       {
293          value += offset[n] - abs(factor[n]) * function(property[n]);
294       }
295       else
296       {
297           value += factor[n] * function(property[n]);
298           offs += offset[n];
299       }
300    }
301
302    volume = offs + value;
303
304 where function can be one of: lin, ln, log, inv, abs or sqrt