Sound (.snd) File Format Specification

The .snd file is a text file – Unix or Windows line endings are legal, blank lines are allowed after the header, and the character set should be UTF-8.

The header of the file should be

A
1000
ACF_SOUNDS

Unlike some other X-Plane text file formats, the .snd file requires paired BEGIN and END directives for major subsections. Having a BEGIN directive without its matched END directive is an error.

Dataref Matching Conditions

Dataref-based trigger conditions use a simple logic language, of the form

<dataref> <operator> <constant value>, e.g.

sim/flightmodel2/engine/N1_percent[0] >= 12.5

The condition evaluates to true or false based on the comparison constant (see the list below). The conditions are evaluated every frame with the current dataref value and may then trigger FMOD events. Note that you can only compare with numbers, not strings.

Unlike normal datarefs, you can prefix the dataref with DELTA= or ABS_DELTA=. If you do this, the value in the condition is not the dataref itself, but its rate of change (per second). ABS_DELTA applies an absolute value.

For example, the condition

DELTA=sim/flightmodel2/engine/N1_percent[0] > 10

Would return true if N1 is growing at a rate of more than 10 per second. Using ABS_DELTA would cause the condition to also indicate true when N1 was falling by more than 10 per second.

DELTA and ABS_DELTA can be used to play sounds when a rate of change is detected in a dataref, even if the sim doesn’t provide a rate of change dataref directly. For example, the flaps, the flaps actual position is provided by X-Plane but their rate of movement is not. To correctly play a flap motor sound, DELTA is needed.

(Playing the sound based on the flap down command would be wrong: if the electrical system is broken, the flaps may not move even when the command is pressed. Thus the actual movement of the flaps should be the trigger for the sound, not the command.)

Constants Used In The File Format

Where datarefs can be compared, the valid comparison operators are:

• < (less than)
• <= (less than or equal)
• == (equality)
• != (not equals)
• >= (greater than or equal)
• > (greater than)

The valid part names for aircraft attachments are:

• engine – the sound is attached to the engine – index refers to the engine number.
• tire – the sound is attached to a tire – index refers to the tire gear number.
• cockpit – the sound is roughly in front of the pilot.

General Directives

These directives should appear at the beginning of the file.

REQUIRES_BANK <bank name>
This causes X-Plane to load the bank specified by name from the FMOD folder. This is needed for any bank you wish to use for this ACF other than the master bank.

DISABLE_LEGACY_ALERT_SOUNDS
New to X-Plane 11.30. Adding this to the SND file will prevent X-Plane from playing any legacy aircraft alert sounds and morse code.

REF_POINT_ACF <y_meters> <z_meters>
New to X-Plane 12.00. If this directive appears in the SND, the location origin for Sound Space’s AABB and SPHERE as well as the Sound Attachment’s VEH_XYZ are no longer tied to the aircraft’s CG but instead moves to some offset from the aircraft’s authoring point in PlaneMaker. Typically artists will put the reference point of the aircraft at the tip of the nose or tail and it stays there throughout the aircraft’s existence. This makes it a more useful reference point for coordinates than the aircraft’s CG which might change as authors gather newer and more accurate data to model the aircraft.

There are two main uses of this directive. First, if the SND is being done for the very first time, setting this directive tells the sim to just use the authoring point as the origin so it’ll never be tied to the CG. You can leave the Y/Z coordinates blank and the sim will assume you mean 0.0 0.0. The second main use is for SNDs that have already been done for an aircraft that is now having it’s CG moved. Rather than have to adjust every coordinate in the SND, you can use this directive to tell the sim that the origin should be at the OLD CG’s location by telling it where the OLD CG was relative to the aircraft’s authoring point. For example, if the OLD CG was at a Y/Z of 3.28084ft/-6.56168ft (remember, PlaneMaker uses FEET for its units) then you could add REF_POINT_ACF 1.0 -2.0 (which is the old CG location, converted from feet to meters) as a directive to the SND which will allow the CG to move but the reference point for the file to stay at the OLD CG.

Sound Attachment Directives

Each sound attachment block defines a single attached “sound” on the aircraft. You must use a matched pair of BEGIN_SOUND_ATTACHMENT and END_SOUND_ATTACHMENT. In this block you must have:

• Exactly one of EVENT_NAME or SNAPSHOT_NAME to specify the FMOD object being played.
• Exactly one of VEH_XYZ or VEH_PART to specify the FMOD object’s location in space.
• At least one of the triggering methods (e.g. EVENT_xxx) so the FMOD object plays. This can be omitted, but then the FMOD event will never play.

Note: while all dataref triggers (start, end, cue) can be combined, only one command trigger can be used, and it cannot be combined with any dataref triggers.

BEGIN_SOUND_ATTACHMENT
This begins the definition of a new sound attachment. All sound attachment properties must be specified after this directive and before the matched END_SOUND_ATTACHMENT directive.

END_SOUND_ATTACHMENT
This defines the end of a given sound attachment. Each sound attachment must be “ended” before anything else in the file occurs, and before the file ends.

EVENT_NAME <fmod string name>
This defines an FMOD event (by string name) that this attachment plays.

SNAPSHOT_NAME <fmod string name>
This defines an FMOD snapshot (by string name) that this attachment plays. Snapshots change the mix while they are being “played” and stop taking effect when stopped.

VEH_XYZ <x> <y> <z>
This sets the location of your event to the location X,Y,Z in meters, relative to the default CG of the aircraft; X is right, Y is up, Z is aft.

VEH_THE <value>
This sets the orientation of your event, where <value> is the angle of PITCH (nose) up.

VEH_PSI <value>
This sets the orientation of your event, where <value> is the angle of YAW (heading) to the right.

VEH_PHI <value>
This sets the orientation of your event, where <value> is the angle of ROLL (bank) to the right.

Note: the order of application is first VEH_THE, then VEH_PSI then VEH_PHI (pitch, heading, roll).

VEH_PART <part_enum> <part_idx>
This attaches your sound to a specific part of the aircraft; where the aircraft can have multiple parts (e.g. engines) a zero-based index is used.

EVENT_ALLOWED_FOR_AI
If this directive exists, the sound is used when your aircraft is flown by the AI as well as the user; if it is omitted, the sound is for the user’s aircraft only. Do not attach internal cockpit sounds like switch clicks to the AI aircraft.

PARAM_DREF_IDX <dref_idx>
For sound parameters that use wild-cards for indices, e.g. sim/flightmodel2/engines/N1_percent[*] (or its equivalent sim.flightmodel2.engines.N1_percent[#] in X-Plane 12) this specifies the index to be used for this attached sound. This lets you make a single event for all engines and then vary the index to get correct match-up to the engine params of a particular engine in a multi-engine aircraft.

EVENT_START_COND <dref> <op> <value>
This causes the event to start playing when the listed dataref changes in relationship to the specified value.

EVENT_END_COND <dref> <op> <value>
This causes the event to stop playing when the condition becomes true.

EVENT_ALWAYS
This causes the event to always be played. Playing events costs CPU even if the event is not making sound, so only use this if you really need the event to always be playing. An example of an always-playing event might be a mix-automation event that is constantly adjusting your mix in response to datarefs.

For sounds that really stop (e.g. engine noise), use event conditions to completely stop the event (or allow it to end playing with cues) once appropriate.

CUE_TRIGGER_COND <dref> <op> <value>
This sets the conditions on which the “cue” is sent to FMOD for the given event, based on a dataref equation.

EVENT_CMND_DOWN <cmnd>
This causes the event to play when a command is pressed down. Since you can use only one command trigger per event, this is meant for a self-terminating sound like a switch clicking on the down press.

EVENT_CMND_UP <cmnd>
This causes the event to play when a command is released. Since you can use only one command trigger per event, this is meant for a self-terminating sound like a switch clicking when released.

EVENT_CMND_HOLD_STOP <cmnd>
This causes the event to be started when the command is pressed down, and stopped when the command is released. E.g. the event plays for the duration the command is pressed.

EVENT_CMND_HOLD_CUE <cmnd>
This causes the event to be started when the command is pressed down, and cued when the command is released; the intention is that the sound event can loop during the duration of the command and then cue an ending part when the command is released, followed by stopping itself.

EVENT_AUTO_END_FROM_START_COND
New to X-Plane 11.30. Added to a sound EVENT, this will cause the sound to stop whenever ANY of the Dataref start conditions are no longer true.

EVENT_POLYPHONIC
New to X-Plane 12.00. Added to a sound EVENT, this will prevent X-Plane from reusing the same event instance for the same event attachment, firing instead separate instances when the conditions are met. This is useful for rotary knobs or other rapid-firing events. Be sure to limit the amount of simultaneous instances that can be playing at the same time to prevent voice stealing.

Sound Space Definitions

X-Plane supports up to 64 3-d “sound spaces” defined in and near your aircraft. The intention is to mark internal regions of your aircraft so that X-Plane can provide datarefs showing camera location for mixing purposes.

Each sound space contains one or more volume primitives; the sound space is the union of the space covered by those volumes. Both disjoint and overlapping volumes are allowed. Where a soft blend-depth is used, it is based on the mathematical boundary of the union of the bounding volume.

BEGIN_SOUND_SPACE
This begins definition of a sound space. Sound spaces must be terminated with END_SOUND_SPACE before another one can be started or an event can be added, and sound spaces cannot be nested in sound attachments.

END_SOUND_SPACE
This terminates an existing sound space.

SOUND_INDEX <index>
This is a required directive (once inside each sound space) and defines the sound space’s index (0-63) in X-Plane; this is used to “publish” penetration ratios for that sound space.

BLEND_DEPTH <distance meters>
This defines a soft transition region starting at the mathematical edge of the volume and moving inward; the inside ratio dataref goes from 0 at the mathematical edge of the volume to 1.0 at “distance meters” inside.

SPHERE <center x> <center y> <center z> <radius>
This adds a sphere to the sound space, defined by location and radius in meters, referenced relative to the CG of the aircraft.

AABB <minx> <miny> <minz> <maxx> <maxy> <maxz>
This adds an axis-aligned bounding box (in aircraft coordinates, that is +X = right, +Y = up, +Z = aft) in meters around the CG of the aircraft.