Howto:Add sound effects to aircraft: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(Copied over from $fgdata/docs with some extra comments and additions.)
 
(→‎Configuration tags: Fixed angles was only half, its the cone angle from edge to edge. Not from source to edge.)
(22 intermediate revisions by 8 users not shown)
Line 1: Line 1:
Users Guide to FlightGear sound configuration
You can '''add sound effects to aircraft''' by adding the sound samples and configuring the sound effects in XML files.  The sound effects can be conditional and the sound's pitch and volume can depend on properties in the property tree. 


Version 0.9.9, December 15, 2014
Some sound effects are added other ways. For example, sounds from avionics like navigation radio receivers are automatically added when you add those radios.


Author: Erik Hofman <erik at ehofman dot com>
{{FGCquote|1= The volume calculation due to distance and orientation of the sounds source ONLY work on mono samples!|2= {{cite web  | url    = http://sourceforge.net/p/flightgear/mailman/message/28505220/  | title  = <nowiki>Re: [Flightgear-devel] Stereo sounds no longer supported?</nowiki>  | author = <nowiki>syd adams</nowiki>  | date  = Dec 7th, 2011  }}}}


Minor changes: [[User:Necolatis|Necolatis]] ([[User talk:Necolatis|talk]]) 03:41, 15 December 2014 (UTC)
{{FGCquote|1= The old way was that the stereo sound would always play the left channel on the left side.  Now you split the sound and place it in 3D space.  When you turn your head, the speaker the left side sound comes out of changes with you|2= {{cite web  | url    = http://forum.flightgear.org/viewtopic.php?p=257291#p257291  | title  = <nowiki>Re: 787-8 Boarding music</nowiki>  | author = <nowiki>bugman</nowiki>  | date  = Sep 14th, 2015  }}}}


This document is an attempt to describe the configuration of
{{FGCquote|1= All sounds must now be mono point sources, and stereo simply requires the two sound sources to be positioned in the 3D environment. |2= {{cite web  | url    = http://sourceforge.net/p/flightgear/mailman/message/34100151/  | title  = <nowiki>[Flightgear-devel] Audit and proposal for handling non-supported stereo sound files in FGAddon via the 3D sound engine.</nowiki>  | author = <nowiki>Edward d'Auvergne</nowiki>  | date  = May 10th, 2015  }}}}
FlightGear flight simulator's aircraft sound in XML.


== Sound Architecture ==
{{FGCquote|1= We use OpenAL for 3D positional audio and most OpenAL implementations can only handle one stereo file.Also Stereo files will not work in 3d space, so they will not be positional.But  most aircraft developers did not know that and used several stereo files expecting everything to work properly but the truth was that in most implementations just one of those stereo files was played.And if you think of it, stereo separation does not work for boarding music either since it plays left channel to your left ear and right channel to your right ear. But in reality boarding music is played left channel to the left audio channel in the aircraft and right channel to the right audio channel in the aircraft.This works the same as normal stereo if you enter the aircraft, but will, reverse once you turn around.So the solution is to split up the stereo file into two mono files and play the proper channel at the proper side of the passenger compartment.|2= {{cite web  | url    = http://forum.flightgear.org/viewtopic.php?p=257289#p257289  | title  = <nowiki>Re: 787-8 Boarding music</nowiki>  | author = <nowiki>erik</nowiki>  | date  = Sep 14th, 2015 }}}}
All of the sound configuration files are XML-encoded* property lists.
The root element of each file is always named <PropertyList>. Tags are
almost always found in pairs, with the closing tag having a slash
prefixing the tag name, i.e </PropertyList>. The exception is the tag
representing an aliased property. In this case a slash is prepended to
the closing angle bracket(see section Aliasing)


The top level sound configuration file is composed of a <fx>, a
== Sound configuration files ==
<name>, a <path> sound file and zero or more <volume> and/or <pitch>
The sound configuration files are [[PropertyList XML files]].
definitions.


[ Paths are relative to $FG_ROOT (the root of the installed base package .) ]
The top level sound configuration file is composed of a <code>&lt;fx&gt;</code> and a <code>&lt;name&gt;</code> tag, a <code>&lt;path&gt;</code> to a sound sample file and zero or more <code>&lt;volume&gt;</code> and/or <code>&lt;pitch&gt;</code>definitions.
[ Absolute paths may be used. Comments are bracketed with <!-- -->.         ]


A limited sound configuration file would look something like this:
Paths are relative to [[$FG_ROOT]], but absolute paths may also be used.


<source>
Comments are bracketed with <code>&lt;!-- --&gt;</code>.
 
=== Example ===
This example would define an engine sound effect for a piston engine driven aeroplane.
 
The sound effect representing the engine is located in <code>$FG_ROOT/Sounds</code> and is named <code>wasp.wav</code>. The effect is started when the property <code>/engines/engine/running</code> becomes non-zero.
 
When that happens, the sound will be played looped (see <code>&lt;mode&gt;</code>) until the property returns zero again. As you can see the volume is dependent on the property <code>/engines/engine/mp-osi</code>, and the pitch of the sound depends on the property <code>/engines/engine/rpm</code>.
 
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<PropertyList>
  <fx>
  <fx>
Line 54: Line 55:
  </fx>
  </fx>
</PropertyList>
</PropertyList>
</source>
</syntaxhighlight>
 
=== Inclusion from the aircraft-set.xml file ===
In order for the sound configuration to be used, it has to be included from the [[aircraft-set.xml]] file.


This would define an engine sound event handler for a piston engine driven
This can be done by adding the path to the file relative to the aircraft's base path within the <code>&lt;sim&gt;</code> tags in the aircraft-set.xml file..
aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
and is named wasp.wav. The event is started when the property
/engines/engine/running becomes non zero.  


When that happens, the sound will be played looped (see <mode>) until the
<syntaxhighlight lang="xml">
property returns zero again. As you can see the volume is mp-osi dependent,
<?xml version="1.0" encoding="UTF-8"?>
and the pitch of the sound depends on the engine rpm.
<PropertyList>
<!-- ... --->
<sim>
  <!-- ... --->
  <sound>
    <path type="string">My-sound-config.xml</path>
  </sound>
  <!-- ... --->
</sim>
<!-- ... --->
</PropertyList>
</syntaxhighlight>


== Configuration description ==
== Configuration tags ==
    
    
<source><fx>
; <code>&lt;fx&gt;</code>
        Named FX subtree living under /sim/sound
: Named FX subtree living under /sim/sound
</source>
 
<source> < ... >
; <code>&lt; ... &gt;</code>
        This is the event separator. The text inside the brackets
: This is the event separator. The text inside the brackets can be anything, but it is advised to give it a meaningful name like: crank, engine, rumble, gear, squeal, flap, wind or stall.
        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
: The value can be defined multiple times, thus anything which is related may have the same name (grouping them together).
        related may have the same name (grouping them together).
 
</source>
; <code>&lt;name&gt;</code>
<source>   <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 normally have an unique value.
        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.
   
   
        Multiple definitions of the same name will allow multiple sections
: Multiple definitions of the same name will allow multiple sections to interfere in the starting and stopping of the sample.
        to interfere in the starting and stopping of the sample.


        This method can't be used to control the pitch or volume of the  
: 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.
        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
: 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.
        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:
: IMPORTANT
        If the trigger is used for anything else but stopping the sound
:: 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.
        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
:: In the case of just stopping the sample at a certain event, the sections for path, volume and pitch may be omitted.
        sections for path, volume and pitch may be omitted.
</source>
<source>    <path>
        This defined the path to the sound file. The path is relative to the
        FlightGear root directory but could be specified absolute.
        The sound format must be mono.
</source>
<source>    <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.
; <code>&lt;path&gt;</code>
</source>
: This defined the path to the sound file. The path is relative to the FlightGear root directory but could be specified absolute.
<source>    <property>
        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
: The sound format must be mono.
        in <condition>
 
</source>  
; <code>&lt;condition&gt;</code>
<source>   <mode>
: Define a condition that triggers the event.
        This defines how the sample should be played:
 
: For a complete description of the FlightGear conditions, please read docs-mini/README.conditions or read the [[Conditions]] article on the wikie.
 
: An event should define either a condition or a property.
 
; <code>&lt;property&gt;</code>
: 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&gt;</code>
 
; <code>&lt;mode&gt;</code>
: This defines how the sample should be played:
   
   
        once:           the sample is played once.
:; once
                        this is the default.
:: The sample is played once. This is the default.
   
   
        looped:         the sample plays continuously,
:; looped
                        until the event turns false.
:: The sample plays continuously, until the event turns false.
 
:; in-transit
:: the sample plays continuously, while the property is changing its value.
 
; <code>&lt;type&gt;</code>
: 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 time don't have a position and orientation but are treated as if it's mounted to the aircraft panel.
 
:: It is up to the user to define if it can always be heard or only when in cockpit view.
 
; <code>&lt;volume&gt;</code> / <code>&lt;pitch&gt;</code>
: Volume or Pitch definition.
 
: Currently there may be up to 5 volume and up to 5 pitch definitions defined within one sound event.
 
: There are two important results from each <volume> and <pitch> section: the offset and the value. Normally all offset values from the different volume/pitch are added together to create the total offset.  The values from each <volume> or <pitch> section are multiplied together to create an final value.  Then the volume (or pitch, respectively) is set to total offset + final value.
 
: 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.


        in-transit:     the sample plays continuously,
: Pitch final output can range from 0 to 2. 1 represents the original pitch of the sound file. Offset defaults to 1, meaning that if no specific <pitch> parameters are given the file will be played at its original pitch.
                        while the property is changing its value.
</source>  
<source>    <type>
        This defines the type os this sample:


        fx:             this is the default type and doesn't need to be defined.
: Volume final output can range from 0 to 1. 1 represents full volume and 0 is silence.


        avionics:      sounds set to this time don't have a position and
; <code>&lt;property&gt;</code>
                        orientation but are treated as if it's mounted to
: Defines which property supplies the value for the calculation.
                        the aircraft panel. it's up to the user to define
                        if it can always be heard or only when in cockpit
                        view.
</source>
<source>    <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 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.
</source>  
<source>      <property>
        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.
</source>
<source>      <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.
: Either a <property> or an <internal> should be defined.  If none is defined, the property reverts to its default.  For volume this is 0, meaning the sound will not be audible at all.


        dt_stop:       the number of seconds after the sound has stopped.
: The value is treated as a floating point number.
</source>
<source>      <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.
</source>
<source>      <type>
        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.
; <code>&lt;internal&gt;</code>
                        this is the default.
: 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.
 
; <code>&lt;delay-sec&gt;</code>
: 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.
 
; <code>&lt;type&gt;</code>
: 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
:; ln
                        value before scaling it. Anything below 1 will return
:: Convert the property value to a natural logarithmic value before scaling it.
                        zero.
 
:: Anything below 1 will return zero.
   
   
        log:           convert the property value to a true logarithmic
:; log
                        value before scaling it. Anything below 1 will return
:: convert the property value to a true logarithmic value before scaling it. (log base 10)
                        zero.


        inv:           inverse linear handling (1/x).
:: Anything below 1 will return zero.


        abs:           absolute handling of the value (always positive).
:; inv
:: Inverse linear handling (1/x).


        sqrt:           calculate the square root of the absolute value
:; abs
                        before scaling it.
:: Absolute handling of the value (always positive).
</source>
<source>      <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>
</source>
<source>      <offset>
        The initial value for this sound. This value is also used as an
        offset value for calculating the end result.
</source>
<source>      <min>
        Minimum allowed value.
        This is useful if sounds start to sound funny. Anything lower
        will be truncated to this value.
</source>
<source>      <max>
        Maximum allowed value.
        This is useful if sounds gets to loud. Anything higher will be
        truncated to this value.
</source>
<source>    <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!
        Also take notice that the values should not be 0.0, since that can produce
        sound artifacts on some sound cards.
</source>
<source>      <x>
        X dimension offset
</source>
<source>      <y>
        Y dimension offset
</source>
<source>      <z>
        Z dimension offset


</source>
:; sqrt
<source>    <orientation>
:: Calculate the square root of the absolute value before scaling it.
        Specify the orientation of the sounds source.


        The zero vector is default, indicating that a Source is not directional.
; <code>&lt;factor&gt;</code>
        Specifying a non-zero vector will make the Source directional in
: Defines the multiplication factor for the property value.
        the X,Y,Z direction
</source>
<source>      <x>
        X dimension
</source>
<source>      <y>
        Y dimension
</source>
<source>      <z>
        Z dimension
</source>
<source>      <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.
</source>
<source>      <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.
</source>
<source>      <outer-gain>
        The gain at the outer edge of the cone.


</source>  
: A special condition is when scale is defined as a negative value. In this case the result of |<scale>| * <property) will be subtracted from &lt;default&gt;
<source>   <reference-dist>
 
        Set a reference distance of sound in meters. This is the
; <code>&lt;offset&gt;</code>
        distance where the volume is at its maximum.
: The initial value for this sound.
        Volume is clamped to this maximum for any distance below.
 
        Volume is attenuated for any distance above.
: This value is also used as an offset value for calculating the end result.
        Attenuation depends on reference and maximum distance. See
 
        OpenAL specification on "AL_INVERSE_DISTANCE_CLAMPED" mode
; <code>&lt;min&gt;</code>
        for details on exact computation.
: Minimum allowed value.
</source>
 
<source>   <max-dist>
: This is useful if sounds start to sound funny. Anything lower will be truncated to this value.
        Set the maximum audible distance for the sound in meters.
 
        Sound is cut-off above this distance.
; <code>&lt;max&gt;</code>
</source>
: Maximum allowed value.
 
: This is useful if sounds gets to loud. Anything higher will be truncated to this value.
 
: Keep in mind that min & max are applied first, then offset.  So for example if min = 0, max = 0.5 and offset = 1.0, then the resulting values will range 1 to 1.5.
 
; <code>&lt;position&gt;</code>
: 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!
 
: Also take notice that the values should not be 0.0, since that can produce sound artifacts on some sound cards.
 
; <code>&lt;x&gt;</code>
: X dimension offset (-X = forward, +X = aft, in meters)
 
; <code>&lt;y&gt;</code>
: Y dimension offset (+Y = left, -Y = right)
 
; <code>&lt;z&gt;</code>
: Z dimension offset (-Z = down, +Z = up)
 
; <code>&lt;orientation&gt;</code>
: 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
 
; <code>&lt;x&gt;</code>
: X dimension
 
; <code>&lt;y&gt;</code>
: Y dimension
 
; <code>&lt;z&gt;</code>
: Z dimension
 
; <code>&lt;inner-angle&gt;</code>
: The inner edge of the audio cone in degrees (0.0 - 360.0).
 
: Any sound withing that angle will be played at the current gain.
 
; <code>&lt;outer-angle&gt;</code>
: The outer edge of the audio cone in degrees (0.0 - 360.0).
 
: Any sound beyond the outer cone will be played at "outer-gain" volume.
 
; <code>&lt;outer-gain&gt;</code>
: The gain at the outer edge of the cone.
 
; <code>&lt;reference-dist&gt;</code>
: Set a reference distance of sound in meters. This is the distance where the volume is at its maximum.
 
: Volume is clamped to this maximum for any distance below.
 
: Volume is attenuated for any distance above.
 
: Attenuation depends on reference and maximum distance. See OpenAL specification on "AL_INVERSE_DISTANCE_CLAMPED" mode for details on exact computation.
 
; <code>&lt;max-dist&gt;</code>
: Set the maximum audible distance for the sound in meters.
 
: Sound is cut-off above this distance.


== Creating a configuration file ==
== Creating a configuration file ==
Line 283: Line 294:
sane configuration when a certain entry is omitted.
sane configuration when a certain entry is omitted.


Default values are:
{| class="wikitable"
 
! Tag !! Default value
<source>
|-
typelin
| '''&lt;type&gt;''' || lin
factor: 1.0
|-
offset: 0.0 for volume, 1.0 for pitch
| '''&lt;factor&gt;''' || 1.0
min:    0.0
|-
max:    0.0 (don't check)
| '''&lt;offset&gt;''' || 0.0 for volume, 1.0 for pitch
</source>
|-
| '''&lt;min&gt;''' || 0.0
|-
| '''&lt;max&gt;''' || 0.0 (don't check)
|}
   
   
Calculations are made the following way (for both pitch and volume):
Calculations are made the following way (for both pitch and volume):
<source>  
<syntaxhighlight lang="cpp">
  value = 0;
value = 0;
  offs = 0;
offs = 0;


  for (n = 0; n < max; n++) {
for (n = 0; n < max; n++) {
      if (factor < 0)
    if (factor < 0) {
      {
        value += offset[n] - abs(factor[n]) * function(property[n]);
        value += offset[n] - abs(factor[n]) * function(property[n]);
    } else {
      }
        value *= factor[n] * function(property[n]);
      else
        offs += offset[n];
      {
    }
          value += factor[n] * function(property[n]);
}
          offs += offset[n];
      }
  }


  volume = offs + value;
volume = offs + value;
</source>
if (volume > 1.0) vol = 1.0;
</syntaxhighlight>
where function can be one of: lin, ln, log, inv, abs or sqrt
where function can be one of: lin, ln, log, inv, abs or sqrt


== Multiplay sound ==
== Multiplayer sound ==
The multiplay sound file works just as the normal sound file, except it should recide in /sim/model/sound instead of /sim/sound. Make sure it depends on properties that are [[Howto:Transmit_properties_over_MP|transmitted over MP]].
The multiplayer sound file works just as the normal sound file, except it should reside in <code>/sim/model/sound</code> instead of <code>/sim/sound</code>. Make sure it depends on properties that are [[Howto:Transmit_properties_over_MP|transmitted over MP]].
 
== Recommended audio file formats ==
{{note|The sound sample '''must be in mono''' format.  This is because it can not be put in a 3D context otherwise. Also, as of at least June 2015 '''stereo samples will not be played'''.}}
 
There some considerations on the quality to the audio files. As a rule of thumb, any computer is able to playback sounds in DVD-quality (48 kHz/24 bits).
Macs still has trouble reading 32 bit files. Most standard sound cards also can't playback 32 bit files.
 
From a listeners point of view, anything above 44.1 kHz and 24 bits is only useful for high end music. Personally, I would think that 44.1 kHz with 16 bits should be more than enough to play engine sounds and alarms from the cockpit. Consider the disk-space against the gain in audio quality!
 
== Preventing sounds from playing when sim starts ==
Some times it can be hard to prevent sounds from playing right away, if the condition starts to evaluate to true. A hack to get this to work is to multiply the volume with a property that you in nasal set to true some seconds after the sim has been initialized.
 
== Bugs in the sound system ==
* The Doppler effect if you pass an aircraft in high speed sometimes is way too high pitch.
* None of the position coordinates must not be 0.0 as described above.
 
== Related content ==
=== Wiki articles ===
* [[Conditions]]
* [[Expressions]]
* [[Howto:Reload sound configuration without restarting]]
 
=== Readme file ===
* {{readme file|xmlsound}}
 
=== Source code ===
* {{simgear file|simgear/sound/xmlsound.hxx}}
* {{simgear file|simgear/sound/xmlsound.cxx}}
* {{flightgear file|src/Sound/fg_fx.hxx}}
* {{flightgear file|src/Sound/fg_fx.cxx}}


[[Category:Aircraft enhancement]]
[[Category:Aircraft enhancement]]

Revision as of 18:47, 18 April 2018

You can add sound effects to aircraft by adding the sound samples and configuring the sound effects in XML files. The sound effects can be conditional and the sound's pitch and volume can depend on properties in the property tree.

Some sound effects are added other ways. For example, sounds from avionics like navigation radio receivers are automatically added when you add those radios.

Cquote1.png The volume calculation due to distance and orientation of the sounds source ONLY work on mono samples!
Cquote2.png
Cquote1.png The old way was that the stereo sound would always play the left channel on the left side. Now you split the sound and place it in 3D space. When you turn your head, the speaker the left side sound comes out of changes with you
— bugman (Sep 14th, 2015). Re: 787-8 Boarding music.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png All sounds must now be mono point sources, and stereo simply requires the two sound sources to be positioned in the 3D environment.
Cquote2.png
Cquote1.png We use OpenAL for 3D positional audio and most OpenAL implementations can only handle one stereo file.Also Stereo files will not work in 3d space, so they will not be positional.But most aircraft developers did not know that and used several stereo files expecting everything to work properly but the truth was that in most implementations just one of those stereo files was played.And if you think of it, stereo separation does not work for boarding music either since it plays left channel to your left ear and right channel to your right ear. But in reality boarding music is played left channel to the left audio channel in the aircraft and right channel to the right audio channel in the aircraft.This works the same as normal stereo if you enter the aircraft, but will, reverse once you turn around.So the solution is to split up the stereo file into two mono files and play the proper channel at the proper side of the passenger compartment.
— erik (Sep 14th, 2015). Re: 787-8 Boarding music.
(powered by Instant-Cquotes)
Cquote2.png

Sound configuration files

The sound configuration files are PropertyList XML files.

The top level sound configuration file is composed of a <fx> and a <name> tag, a <path> to a sound sample file and zero or more <volume> and/or <pitch>definitions.

Paths are relative to $FG_ROOT, but absolute paths may also be used.

Comments are bracketed with <!-- -->.

Example

This example would define an engine sound effect for a piston engine driven aeroplane.

The sound effect representing the engine is located in $FG_ROOT/Sounds and is named wasp.wav. The effect is started when the property /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 dependent on the property /engines/engine/mp-osi, and the pitch of the sound depends on the property /engines/engine/rpm.

<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
 <fx>
  <engine>
   <name>engine</name>
   <path>Sounds/wasp.wav</path>
   <mode>looped</mode>
   <condition>
    <property>/engines/engine/running</property>
   </condition>
   <volume>
    <property>/engines/engine/mp-osi</property>
    <factor>0.005</factor>
    <min>0.15</min>
    <max>0.5</max>
    <offset>0.15</offset>
   </volume>
   <pitch>
    <property>/engines/engine/rpm</property>
    <factor>0.0012</factor>
    <min>0.3</min>
    <max>5.0</max>
    <offset>0.3</offset>
   </pitch>
  </engine>
 </fx>
</PropertyList>

Inclusion from the aircraft-set.xml file

In order for the sound configuration to be used, it has to be included from the aircraft-set.xml file.

This can be done by adding the path to the file relative to the aircraft's base path within the <sim> tags in the aircraft-set.xml file..

<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
 <!-- ... --->
 <sim>
  <!-- ... --->
   <sound>
    <path type="string">My-sound-config.xml</path>
   </sound>
  <!-- ... --->
 </sim>
 <!-- ... --->
</PropertyList>

Configuration tags

<fx>
Named FX subtree living under /sim/sound
< ... >
This is the event separator. The text inside the brackets can be anything, but 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 (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 normally have an unique value.
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 the path to the sound file. The path is relative to the FlightGear root directory but could be specified absolute.
The sound format must be mono.
<condition>
Define a condition that triggers the event.
For a complete description of the FlightGear conditions, please read docs-mini/README.conditions or read the Conditions article on the wikie.
An event should define either a condition or a property.
<property>
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:
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 time don't have a position and orientation but are treated as if it's mounted to the aircraft panel.
It is 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.
There are two important results from each <volume> and <pitch> section: the offset and the value. Normally all offset values from the different volume/pitch are added together to create the total offset. The values from each <volume> or <pitch> section are multiplied together to create an final value. Then the volume (or pitch, respectively) is set to total offset + final value.
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.
Pitch final output can range from 0 to 2. 1 represents the original pitch of the sound file. Offset defaults to 1, meaning that if no specific <pitch> parameters are given the file will be played at its original pitch.
Volume final output can range from 0 to 1. 1 represents full volume and 0 is silence.
<property>
Defines which property supplies the value for the calculation.
Either a <property> or an <internal> should be defined. If none is defined, the property reverts to its default. For volume this is 0, meaning the sound will not be audible at all.
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>
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.
Anything below 1 will return zero.
log
convert the property value to a true logarithmic value before scaling it. (log base 10)
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>
<offset>
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 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.
Keep in mind that min & max are applied first, then offset. So for example if min = 0, max = 0.5 and offset = 1.0, then the resulting values will range 1 to 1.5.
<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!
Also take notice that the values should not be 0.0, since that can produce sound artifacts on some sound cards.
<x>
X dimension offset (-X = forward, +X = aft, in meters)
<y>
Y dimension offset (+Y = left, -Y = right)
<z>
Z dimension offset (-Z = down, +Z = up)
<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 - 360.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 - 360.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 volume is at its maximum.
Volume is clamped to this maximum for any distance below.
Volume is attenuated for any distance above.
Attenuation depends on reference and maximum distance. See OpenAL specification on "AL_INVERSE_DISTANCE_CLAMPED" mode for details on exact computation.
<max-dist>
Set the maximum audible distance for the sound in meters.
Sound is cut-off above this distance.

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.

Tag Default value
<type> lin
<factor> 1.0
<offset> 0.0 for volume, 1.0 for pitch
<min> 0.0
<max> 0.0 (don't check)

Calculations are made the following way (for both pitch and volume):

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;
if (volume > 1.0) vol = 1.0;

where function can be one of: lin, ln, log, inv, abs or sqrt

Multiplayer sound

The multiplayer sound file works just as the normal sound file, except it should reside in /sim/model/sound instead of /sim/sound. Make sure it depends on properties that are transmitted over MP.

Recommended audio file formats

Note  The sound sample must be in mono format. This is because it can not be put in a 3D context otherwise. Also, as of at least June 2015 stereo samples will not be played.

There some considerations on the quality to the audio files. As a rule of thumb, any computer is able to playback sounds in DVD-quality (48 kHz/24 bits). Macs still has trouble reading 32 bit files. Most standard sound cards also can't playback 32 bit files.

From a listeners point of view, anything above 44.1 kHz and 24 bits is only useful for high end music. Personally, I would think that 44.1 kHz with 16 bits should be more than enough to play engine sounds and alarms from the cockpit. Consider the disk-space against the gain in audio quality!

Preventing sounds from playing when sim starts

Some times it can be hard to prevent sounds from playing right away, if the condition starts to evaluate to true. A hack to get this to work is to multiply the volume with a property that you in nasal set to true some seconds after the sim has been initialized.

Bugs in the sound system

  • The Doppler effect if you pass an aircraft in high speed sometimes is way too high pitch.
  • None of the position coordinates must not be 0.0 as described above.

Related content

Wiki articles

Readme file

Source code