Users Guide to FlightGear sound configuration
-Version 0.7.10, Mar 02 2002
-Author: Erik Hofman <erik@ehofman.com>
+Version 0.9.8, October 30, 2005
+Author: Erik Hofman <erik at ehofman dot com>
This document is an attempt to describe the configuration of
-FlightGear flight simulator's aircraft sound via XML.
-
-Some History:
-------------
-Older versions of FGFS had a hard coded audio layer. This was a
-than ideal state of affairs due to FGFS ability to use different
-aircraft models. Being primarily developed on UNIX type systems, a
-modular approach is taken towards the simulation. To date, most
-alternatives to the default Cessna 172 aircraft are the product
-of research institutions interested in the flight characteristics and
-not cosmetics. The result of this was that one could fly the X-15 or
-a Boeing 747 but be limited to C172 sounds.
-
-A rewrite of the sound code was done around v0.7.10 by Erik Hofman
-allowing for configuration of the sounds via XML to address this
-limitation.
-
-About The Property Manager:
---------------------------
-The
+FlightGear flight simulator's aircraft sound in XML.
Sound Architecture:
------------------
<name>, a <path> sound file and zero or more <volume> and/or <pitch>
definitions.
-[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
-[ Absolute paths may be used.Comments are bracketed with <!-- -->. ]
+[ Paths are relative to $FG_ROOT (the root of the installed base package .) ]
+[ Absolute paths may be used. Comments are bracketed with <!-- -->. ]
A limited sound configuration file would look something like this:
<name>engine</name>
<path>Sounds/wasp.wav</path>
<mode>looped</mode>
- <property>/engines/engine/running</property>
+ <condition>
+ <property>/engines/engine/running</property>
+ </condition>
<volume>
<property>/engines/engine/mp-osi</property>
<factor>0.005</factor>
/engines/engine/running becomes non zero.
When that happens, the sound will be played looped (see <mode>) until the
-property returns zero again. As you can see the volume is mp-osi dependant,
-and the pitch of the sound depents on the engine rpm.
+property returns zero again. As you can see the volume is mp-osi dependent,
+and the pitch of the sound depends on the engine rpm.
Configuration description:
-------------------------
<fx>
- Named FX subtree living under /sim/sound
+ Named FX subtree living under /sim/sound
< ... >
- This is the event seperator. The text inside the brackets
- can be anything. Bit it is adviced to give it a meaningfull name
- like:
- crank, engine, rumble, gear, squeal, flap, wind, stall or click.
+ This is the event separator. The text inside the brackets
+ can be anything. Bit it is advised to give it a meaningful name
+ like: crank, engine, rumble, gear, squeal, flap, wind or stall
- The value can be defined multiple times, thus anything which is
- related may have the same name.
+ The value can be defined multiple times, thus anything which is
+ related may have the same name (grouping them together).
<name>
- This defines the name of the event. This name is used internally
- and, although it can me defined multiple times in the same file,
- should have a unique value unless you realy know what you're doing.
+ This defines the name of the event. This name is used internally
+ and, although it can me defined multiple times in the same file,
+ should normally have an unique value.
- Defining it multiple times could lead to unexpected behaviour.
-
+ Multiple definitions of the same name will allow multiple sections
+ to interfere in the starting and stopping of the sample.
+
+ This method can't be used to control the pitch or volume of the
+ sample, but instead multiple volume or pitch section should be
+ included inside the same event.
+
+ The types "raise" and "fall" will stop the playback of the sample
+ regardless of any other event. This means that when the type "raise"
+ is supplied, sample playback will stop when the event turns false.
+ Using the type "fall" will stop playback when the event turns true.
+
+ IMPORTANT:
+ If the trigger is used for anything else but stopping the sound
+ at a certain event, all sections with the same name *should* have
+ exactly the same sections for everything but property and type.
+
+ In the case of just stopping the sample at a certain event, the
+ sections for path, volume and pitch may be omitted.
+
<path>
- This defined th path to the sound file. The path is relative to the
- FlightGear root directory but could be specified absolute.
+ This defined th path to the sound file. The path is relative to the
+ FlightGear root directory but could be specified absolute.
+
+ <condition>
+ Define a condition that triggers the event.
+ For a complete description of the FlightGear conditions,
+ please read docs-mini/README.conditions
+
+ An event should define either a condition or a property.
<property>
- Define which property triggers the event, and reffers to a node
- in the FlightGear property tree.
-
- The value is converted to an integer value (anything less than 0.5 is
- is considered to be 0) and handled if it were a boolean value
- (0 = false, anything else = true).
-
- The triger depends on the value of <type>.
-
- <type>
- This specifies how the event is triggered.
- There are multiple options:
-
- level: events are active if the value is true.
- this is the default behaviour.
-
- inverted: events are active if the value is false.
-
- flipflop: events are triggered on state changes.
- this is only usefull for samples which are played
- once.
+ Define which property triggers the event, and refers to a node
+ in the FlightGear property tree. Action is taken when the property
+ is non zero.
+
+ A more sophisticated mechanism to trigger the event is described
+ in <condition>
<mode>
- This defines how the sample should be played:
+ This defines how the sample should be played:
- once: the sample is played once.
- this is the default.
-
- looped: the sample plays continuesly,
- until the event turns false.
+ once: the sample is played once.
+ this is the default.
+ looped: the sample plays continuously,
+ until the event turns false.
+
+ in-transit: the sample plays continuously,
+ while the property is changing its value.
+
+ <type>
+ This defines the type os this sample:
+
+ fx: this is the default type and doesn't need to be defined.
+
+ avionics: sounds set to this type don't have a position and
+ orientation but are treated as if it's mounted to
+ the aircraft panel. it's up to the user to define
+ if it can always be heard or only when in cockpit
+ view.
<volume> / <pitch>
- Volume or Pitch definition. Currently there may be up to 5
- volume and up to 5 pitch definitions defined within one sound
- event. Normally all <offset> values are added together and the
- results after property calculations will be miltplied.
- A special condition occurs when the <factor> value is negative,
- in which case the offset doesn't get added to the other offset values
- but instead will be used in the multiplication section.
+ Volume or Pitch definition. Currently there may be up to 5
+ volume and up to 5 pitch definitions defined within one sound
+ event. Normally all offset values are added together and the
+ results after property calculations will be multiplied.
+ A special condition occurs when the value of factor is negative,
+ in which case the offset doesn't get added to the other offset values
+ but instead will be used in the multiplication section.
<property>
- Defins which property supplies the value for the calculation.
- The value is treatened as a floating point number.
+ Defines which property supplies the value for the calculation.
+ Either a <property> or an <internal> should be defined.
+ The value is treated as a floating point number.
+
+ <internal>
+ Defines which internal variable should be used for the calculation.
+ The value is treated as a floating point number.
+ The following internals are available at this time:
+
+ dt_play: the number of seconds since the sound started playing.
+
+ dt_stop: the number of seconds after the sound has stopped.
+ <delay-sec>
+ Delay after which the sound starts playing. This is useful to let
+ a property start two sounds at the same time, where the second is
+ delayed until the first stopped playing.
+
<type>
- lin: lineair handling of the property value.
- this is the default.
+ Defines the function that should be used upon the property
+ before it is used for calculating the net result:
+
+ lin: linear handling of the property value.
+ this is the default.
- ln: convert the property value to a natural logarithmic
- value before scaling it.
+ ln: convert the property value to a natural logarithmic
+ value before scaling it. Anything below 1 will return
+ zero.
- log: convert the property value to a true logarithmic
- value before scaling it.
+ log: convert the property value to a true logarithmic
+ value before scaling it. Anything below 1 will return
+ zero.
+
+ inv: inverse linear handling (1/x).
+
+ abs: absolute handling of the value (always positive).
+
+ sqrt: calculate the square root of the absolute value
+ before scaling it.
<factor>
- Defines the multiplication factor for the property value.
- A special condition is when scale is defined as a negative
- value. In this case the result of |<scale>| * <property) will be
- subtracted from <default>
+ Defines the multiplication factor for the property value.
+ A special condition is when scale is defined as a negative
+ value. In this case the result of |<scale>| * <property) will be
+ subtracted from <default>
<offset>
- The initial value for this sound. This value is also used as an
- offset value for calulating the end result.
+ The initial value for this sound. This value is also used as an
+ offset value for calculating the end result.
<min>
- Minimum allowed value.
- This is usefull if sounds start to sound funny. Anything lower
- will be converted to 0.
+ Minimum allowed value.
+ This is useful if sounds start to sound funny. Anything lower
+ will be truncated to this value.
<max>
+ Maximum allowed value.
+ This is useful if sounds gets to loud. Anything higher will be
+ truncated to this value.
+
+ <position>
+ Specify the position of the sounds source relative to the
+ aircraft center. The coordinate system used is a left hand
+ coordinate system where +Y = left, -Y = right, -Z = down, +Z =
+ up, -X = forward, +X = aft. Distances are in meters.
+ The volume calculation due to distance and orientation of the
+ sounds source ONLY work on mono samples!
+
+ <x>
+ X dimension offset
+
+ <y>
+ Y dimension offset
+
+ <z>
+ Z dimension offset
+
+
+ <orientation>
+ Specify the orientation of the sounds source.
+
+ The zero vector is default, indicating that a Source is not directional.
+ Specifying a non-zero vector will make the Source directional in
+ the X,Y,Z direction
+
+ <x>
+ X dimension
+
+ <y>
+ Y dimension
+
+ <z>
+ Z dimension
+
+ <inner-angle>
+ The inner edge of the audio cone in degrees (0.0 - 180.0).
+ Any sound withing that angle will be played at the current gain.
+
+ <outer-angle>
+ The outer edge of the audio cone in degrees (0.0 - 180.0).
+ Any sound beyond the outer cone will be played at "outer-gain" volume.
+
+ <outer-gain>
+ The gain at the outer edge of the cone.
+
+
+ <reference-dist>
+ Set a reference distance of sound in meters. This is the
+ distance where the gain/volume will be halved. This can be
+ useful for limiting cockpit sounds to the cockpit.
+
+ <max-dist>
+ Set the maximum audible distance for the sound in meters.
+ This can be useful for limiting cockpit sounds to the cockpit.
+
+
+Creating a configuration file:
+------------------------------
+
+To make things easy, there is a default value for most entries to allow a
+sane configuration when a certain entry is omitted.
+
+Default values are:
+
+type: lin
+factor: 1.0
+offset: 0.0 for volume, 1.0 for pitch
+min: 0.0
+max: 0.0 (don't check)
+
- Maximum allowed value.
- This is usefull if sounds gets to loud. Anything higher will be
- truncated to this value.
-
-
- Calculations are made the following way
- (function can be one of: none, ln or log ):
- if (scale < 0) {
- value[i] = offset[n] - abs(scale[n]) * function(property[n])
- offset[i] = 0;
- } else
- value[i] = scale[n] * function(property[n])
+Calculations are made the following way (for both pitch and volume):
- And the end result will be:
-
- result = offset[0..max] + value[0..max];
-
+ value = 0;
+ offs = 0;
+ for (n = 0; n < max; n++) {
+ if (factor < 0)
+ {
+ value += offset[n] - abs(factor[n]) * function(property[n]);
+ }
+ else
+ {
+ value += factor[n] * function(property[n]);
+ offs += offset[n];
+ }
+ }
+ volume = offs + value;
+where function can be one of: lin, ln, log, inv, abs or sqrt