SoundFL - Frontline sound library
=================================
Overview
========
The Frontline sound library is dependent upon the Pebble sound library for vector operations, random math, list templates and name hashing.
Configurations
==============
Configurations for SoundFL should be created using the ConfigMunge application.
Configurations are specified in the following form...
optional parameters are enclosed in []
compulsory parameters are enclosed in <>
<objectID>()
{
<propertyID0>(propertyvalue);
<propertyID1>(propertyvalue);
...
<propertyIDN>(propertyvalue);
<subObjectID>()
{
}
}
ObjectID : Sound
----------------
Property | Description
-------------------------------------------------------------------------------
Name | Object identifier
Group | Group identifier which can be referenced by the application
Inherit | Name of the Sound to inherit default parameters from.
Pitch | Median pitch value (0.0...1.0)
PitchDev | Range pitch will vary by e.g range of 0.5 with pitch set to 0.5 will vary pitch between 0.0 and 1.0
Gain | Median gain value (0.0...1.0)
GainDev | Range gain will vary by. See PitchDev for example.
ReverbGain | Gain of reverb send.
Bus | Name of the bus sound is sent to.
Looping | Whether the sound is looping (0=not looping or 1)
Pan | Pan of sound (-1.0...1.0)
RollIn | Roll in factor(-0.999999...MAX_FLT) default=0.0
| Controls slope where the distance between the source and
| listener is between 0 and RollInDistance.
| Roll in factor -0.99999 is causes the gain to almost
| immediately reach 1.0 as distance between source and listener increases. Roll in factor of 0.0 is a linear gradient between 0 and RollInDistance.
|A roll in factor of 10000000.0 (MAX_FLT)
RollInDistance | Distance from source where sound is maximum gain. If this is greater than 0 the gain at distance 0 will be 0 and the gain
| between RollInDistance and MinDistance will be 1. RollInDistance must be less than or equal to MinDistance.
MinDistance | Distance from source where sound is maximum gain (<=MuteDistance)
MuteDistance | Distance from source where sound is muted (<=MaxDistance)
MazDistance | Distance from source where gain is 0.0
RollOff | Roll off factor (-0.999999...MAX_FLT) default=0.0. See RollIn
Mode3D | Whether the sound is 3D (0=2d or 1=3d)
ModeDoppler | Whether doppler effects are enabled (0=disabled, 1=enabled)
Bias | 0.0 = priority of sound is determined only by audibility, 1.0 = priority of sound is determined by priority
Priority | If more sounds are played than are available from the hardware, the highest priority sounds will play (0.0...1.0)
PlayProbability | (0.0...1.0) 1.0 = sound always plays when triggered, 0.0 = sound never plays when triggered.
PlayInterval | Time (in seconds) to wait before playing the sound again.
PlayIntervalDev | Time (in seconds) to vary the PlayInterval by.
RandomPlayPos | 1 enables random start position, 0 always starts sound at 0
CyclePlayback | 0 Randomly selects a sample
| 1 Ignores the playback probabilites of all samples in the sample list. Instead each time the sound is triggered the next sample in the list is played.
|The first sample is randomly selected.
| 2 Same as 1, except the first sample is the first in the list.
| 3 Randomly selects a sample but makes sure the same sample isn't played twice
SpaceDistance | Distance the center of a source can move out of a space while still keeping the source classified as within the space.
| 2 Randomly selects a sample but makes sure the same sample isn't played twice
SpaceDistance | Distance the center of a source can move out of a space while still keeping the source classified as within the space.
Sound.SubObjectID : SampleList
Property | Description
-------------------------------------------------------------------------------
Sample | Sample("sampleName", weight).
| The sampleName is the name of a sample in a currently loaded bank.
|The weight is used to randomly choose a sample to play each time the sound is| triggered. 1..N Samples must be specified.
| For samples that should only be retriggered after a certain amount of time has elapsed it's possible to specifiy two additional parameters in the form ...
| Sample("sampleName", weight, playInterval, playIntervalDev);
| playInterval is the time in seconds which must elapse before the sample is played again.
|The playIntervalDev varies the playInterval. For example to play a sample every 8..12 seconds write the following ...
| Sample("mysample", 1.0, 10.0, 2.0);
The Sound object varies gain, pitch and samples played dependent upon parameters specified in a configuration script. When the configuration script
is loaded Sound::Properties objects are created which contain the parameters used to playback a Sound.
For example...
Sound()
{
Name("explosion")
Pitch(0.9);
PitchDev(0.1);
Gain(0.6);
GainDev(0.2);
ReverbGain(1.0);
Bus("soundfxbus");
Looping(0);
Pan(0.0);
RollIn(10.0);
RollInDistance(0.0);
MinDistance(1.0);
MuteDistance(140.0);
MaxDistance(140.0);
RollOff(1.0);
Mode3D(1);
Bias(0.5);
Priority(0.5);
SampleList()
{
Sample("explosion_variation0", 0.5);
Sample("explosion_variation1", 0.5);
}
}
ObjectID : Bus
--------------
Property | Description
-------------------------------------------------------------------------------
Name | Object identifier
Gain | Gain of the bus
Parent | Name of the parent bus in the hierarchical bus structure.
| The bus name is specified with the Name property.
| The root bus is called "Root". If a parent is specified this bus becomes the sub-bus of the parent bus.
AttenuateBus | Name of the bus which is attenuated when any sound or stream is played via this bus.
AttenuationLeadIn | Length of the fade before full attenuation of the specified AttenuateBus is reached.
AttenuationLeadOut | Length of the fade before full attenuation of the specified AttenuateBus is reached.
Attenuation | Attenuation of the bus 0.0=no attenuation, 1.0f=full attenuation.
Mute | Mutes the bus
Solo | Solos the bus
Sounds or SoundStreams can be routed to buses. A bus is used to control the gain of a group of Sounds and SoundStreams. Buses can be arranged
heirachically with each bus potentially having many sub-buses.
ObjectID : SoundStream
----------------------
Property | Description
-------------------------------------------------------------------------------
Name | Object identifier
Group | Group identifier which can be referenced by the application
Inherit | Name of the SoundStream to inherit default parameters from.
Pitch | Median pitch value (0.0...1.0)
PitchDev | Range pitch will vary by e.g range of 0.5 with pitch set to 0.5 will vary pitch between 0.0 and 1.0
Gain | Median gain value (0.0...1.0)
GainDev | Range gain will vary by. See PitchDev for example.
ReverbGain | Gain of reverb send.
Bus | Name of the bus sound is sent to.
Looping | Whether the sound is looping (0=not looping or 1)
Pan | Pan of sound (-1.0...1.0)
RollIn | Roll in factor(-0.999999...MAX_FLT) default=0.0 Controls slope where the distance between the source and listener is between 0 and RollInDistance.
| Roll in factor -0.99999 is causes the gain to almost immediately reach 1.0 as distance between source and listener increases.
| Roll in factor of 0.0 is a linear gradient between 0 and RollInDistance. A roll in factor of 10000000.0 (MAX_FLT)
RollInDistance | Distance from source where sound is maximum gain.
|If this is greater than 0 the gain at distance 0 will be 0 and the gain between RollInDistance and MinDistance will be 1.
|RollInDistance must be less than or equal to MinDistance.
MinDistance | Distance from source where sound is maximum gain (<=MuteDistance)
MuteDistance | Distance from source where sound is muted (<=MaxDistance)
MazDistance | Distance from source where gain is 0.0
RollOff | Roll off factor (0.0...MAX_FLT) default=1.0. See RollIn
Mode3D | Whether the sound is 3D (0=2d or 1=3d)
ModeDoppler | Whether doppler effects are enabled (0=disabled, 1=enabled)
PlayProbability | (0.0...1.0) 1.0 = sound always plays when triggered, 0.0 = sound never plays when triggered.
Stream | Name of the stream (ID encoded in the file not the name of the file) which contains the segments specified in the SegmentList.
PlayInterval | Time (in seconds) to wait before playing the sound again.
PlayIntervalDev | Time (in seconds) to vary the PlayInterval by.
RandomPlayPos | 1 enables random start position, 0 always starts sound at 0
CyclePlayback | 0 Randomly selects a segment
| 1 Ignores the playback probabilites of all segments in the segment list. Instead each time the sound is triggered the next segment in the list is played.
| The first segment is randomly selected.
| 2 Same as 1, except the first segment is the first in the list.
| 3 Randomly selects a segment but makes sure the same segment isn't played twice
SpaceDistance | Distance the center of a source can move out of a space while still keeping the source classified as within the space.
| 2 Randomly selects a segment but makes sure the same segment isn't played twice
SpaceDistance | Distance the center of a source can move out of a space while still keeping the source classified as within the space.
SoundStream.SubObjectID : SegmentList
Property | Description
-------------------------------------------------------------------------------
Segment |Segment("segmentName", weight).
|The segmentName is the name of a segment within the stream specified by the stream ID above.
|The weight is used to randomly choose a segment to play each time the SoundStream is triggered. 1..N Segments must be specified.
| Segment("segementName", weight, playInterval, playIntervalDev);
| playInterval is the time in seconds which must elapse before the segment is played again.
|The playIntervalDev varies the playInterval. For example to play a segment every 60..120 seconds write the following ...
| Segment("segmentName", 1.0, 90.0, 30.0);
The SoundStream object is similar to the Sound object except that it controls parameters of an audio stream instead of a samples played from sample memory.
The number of streams is limited by the media bandwidth available.
For example...
SoundStream()
{
Name("music");
Pitch(1.0);
PitchDev(0.0);
Gain(0.3);
GainDev(0.0);
ReverbGain(1.0);
Bus("music");
Looping(1);
Pan(0.0);
RollIn(10.0);
RollInDistance(0.0);
MinDistance(1.0);
MuteDistance(140.0);
MaxDistance(140.0);
RollOff(1.0);
Mode3D(0);
Stream("mymusicstream");
Bus("musicbus");
SegmentList()
{
Segment("music_variation0", 0.25);
Segment("music_variation1", 0.25);
Segment("music_variation2", 0.1);
Segment("music_variation3", 0.4);
}
}
ObjectID : SoundLayered
-----------------------
Property | Description
-------------------------------------------------------------------------------
Name | Name of the layered sound
Layer | Layer("layerName", "soundName", playbackDelay, playbackDelayDev, playbackTime, playbackTimeDev).
| The layer name is a label which allows the layer to be referenced by the application code. The sound name references the name of a previously defined Sound()
| which will be used as a layer of the layered sound.
| The playback delay, is the time to delay the sound (in seconds) from the time the sound is initially triggered.
| The playback delay deviation (playbackDelayDev) allows the playback delay to be randomly varied over a range.
| playbackTime is the time to play the layer, if this is not specified the layer will not stop.
|Finally, playbackTimeDev is the deviation of the playback time, if this is not specified a deviation of 0.0 is used.
| Any number of SoundLayers can be specified for a layered sound.
A layered sound (SoundLayered) allows multiple Sounds to be played back at the same time or with some delay between each sound.
For example...
SoundLayered
{
Name("grenade_explode");
Layer("explosion", "grenade_explode", 0.0);
Layer("gasleak", "grenade_gas", 0.5, 0.1);
}
The sound "grenade_explode" will be played when the layered sound "grenade_explode" is triggered (played). Then 0.4 to 0.6 seconds after the
layered sound "grenade_explode" was triggered, "grenade_gas" will play.
ObjectID : ParameterGraph
-------------------------
Property | Description
-------------------------------------------------------------------------------
Name | Name of the parameter graph
ControlPoint | ControlPoint(inputValue, outputValue).
| Each control point represents a point on a 2D graph. For example inputValue is the X axis and outputValue is the Y axis.
| X is related to Y by the relationship defined by the ControlPoints. If only the following two control points exist on a graph...
| ControlPoint(0.0, 0.0);
| ControlPoint(1.0, 2.0);
| X is 0, Y is 0 and when X is 1, Y is 2. So for the input value of 0.5 the output value would be 1.0.
Parameter graphs are used in conjunction with parameterized sounds (SoundParameterized) to map application (game) values to sound parameters.
For example the acceleration of a object could be mapped to the gain of a sound.
ObjectID : SoundParameterized
-----------------------------
Property | Description
-------------------------------------------------------------------------------
Name | Name of the layered sound
SoundLayered | Name of the layered sound controlled by this parameterized sound.
SoundParameterized.SubObjectID : Layer
Property | Description
-------------------------------------------------------------------------------
Name | Name of the layer within the layered sound (specified by SoundParameterized.SoundLayered) which is being controlled.
ParameterGraph | ParameterGraph(input, parameterGraphName, output).
| input is the name of the application parameter which is mapped to the sound parameter (output).
| parameterGraphName is the name of parameter graph which controls the layer specified by the Name property.
| output is the sound parameter which is controlled by the application parameter(input).
| output can be any of the following...
| "Gain"
| "Pitch"
| "Pan"
| "MinDistance"
| "MuteDistance"
| "MaxDistance"
| "RollOff"
A parameterized sound maps game parameters using parameter graphs to control a layered sound. See ParameterGraph and SoundLayered for more information.
ObjectID : I3DL2ReverbPreset
Property | Description
-------------------------------------------------------------------------------
Name | Name of the preset (referred to by a space)
RoomGain | Controls reverb output gain (0.0...1.0)
RoomHFGain | Control gain of high pass path of reverb output. (0.0...1.0)
RoomRollOff | Controls the low pass cut off position of reverb output. (0.0...10.0)
DecayTime | Length of the reverb in seconds (0.01...20.0)
DecayHFRatio | High frequency ratio of subsequent reverberation (0.01...2.0)
ERGain | Early reflections gain (0.0...1.0)
ERDelay | Delay of early reflections (0.0...0.3)
ReverbGain | Gain of subsequent reverberation (0.0...10.0)
ReverbDelay | Delay of subsequent reverberation (0.0...0.1)
Diffusion | Higher the value the more diffuse (wider stereo image) of the reverb (0.0...100.0)
Density | The density of subsequent reverberation. With lower values individual reflections are audible. (0.0...100.0)
HFReference | Cut of frequency (in Hz) of low pass filter on input of reverb system. (20.0...20000.0)
PS2 specific notes on I3DL2ReverbPresets :
On PS2, I3DL2ReverbPresets are mapped to the PS2's native hardware reverb presets.
The following displays the mapping algorithm...
ReverbPreset | PS2 Preset
================================================================================
RoomGain = 0.0 | OFF
--------------------------------------------------------------------------------
Diffusion < 100.0 and | DELAY, delay time controlled by ERDelay
ERGain < 1.0 and |
ReverbDelay < 0.05 |
--------------------------------------------------------------------------------
Diffusion < 100.0 and | ECHO, delay time controlled by ERDelay
ERGain < 1.0 and | feedback controlled by ERGain
ReverbDelay >= 0.05 |
--------------------------------------------------------------------------------
(Diffusion >= 100.0 or | SPACE
ERGain >= 1.0) and |
DecayTime > 4.0 and |
HFRatio > 0.5 |
--------------------------------------------------------------------------------
(Diffusion >= 100.0 or | HALL
ERGain >= 1.0) and |
DecayTime > 4.0 and |
HFRatio <= 0.5 |
--------------------------------------------------------------------------------
(Diffusion >= 100.0 or | HALL
ERGain >= 1.0) and |
DecayTime > 3.0 and |
DecayHFRatio > 1.0 |
--------------------------------------------------------------------------------
(Diffusion >= 100.0 or | STUDIO_C
ERGain >= 1.0) and |
DecayTime > 3.0 and |
DecayHFRatio <= 1.0 |
--------------------------------------------------------------------------------
(Diffusion >= 100.0 or | PIPE
ERGain >= 1.0) and |
DecayTime > 2.0 and |
ERGain > 1.0 |
--------------------------------------------------------------------------------
(Diffusion >= 100.0 or | STUDIO_B
ERGain >= 1.0) and |
DecayTime > 2.0 and |
ERGain <= 1.0 |
--------------------------------------------------------------------------------
(Diffusion >= 100.0 or | ROOM
ERGain >= 1.0) and |
DecayTime <= 2.0 and |
DelayHFRatio > 0.5 |
--------------------------------------------------------------------------------
(Diffusion >= 100.0 or | STUDIO_A
ERGain >= 1.0) and |
DecayTime <= 2.0 and |
DelayHFRatio <= 0.5 |
ObjectID : Space
Property | Description
-------------------------------------------------------------------------------
Name | Name of the space
I3DL2ReverbPreset | Reverb preset associated with this space
DirectGain | Gain of direct path between source and listener
DirectHFGain | High frequency gain of direct path between source and listener
RoomGain | Gain of reverb
RoomHFGain | High frequency gain of reverb
RoomRollOffFactor | High frequency roll off factor of reverb (0.0 min... 10.0 max)
ObstructionHFGain | High frequency gain of obstructed path
ObstructionLFRatio | Low frequency ratio (cut off frequency) of obstructed path
OcclusionHFGain | High frequency gain of occluded path
OcclusionLFRatio | Low frequency ratio (cut off frequency) of occluded path
Priority | If two spaces are overlapping the space with the highest priority space is chosen
Space.SubObjectID : ConnectedList
Property | Description
-------------------------------------------------------------------------------
Space | Connected space which can leak sound into the parent space.
| Space(spaceName, gainFactor)
|spaceName is the name of the connected space.
|gainFactor is used to attenuate the direct and room gain of sources in the connected space and amplify the obstruction and occlusion paths.
|For example a gainFactor of 0.0 will cause all sources in the connected space to sound the same as in
|the parent space - the direct path will be assumed with no obstruction or occlusion.
| A gainFactor of 1.0 will cause all sources in the connected space to be occluded and obstructed - which is the same as
|the sources being outside of the parent space.
For example...
Space()
{
Name("corridor")
I3DL2ReverbPreset("corridor")
DirectGain(1.0)
DirectHFGain(1.0)
RoomGain(0.2)
RoomHFGain(0.2)
RoomRollOffFactor(5.0)
ObstructionHFGain(0.2)
ObstructionLFRatio(1.0)
OcclusionHFGain(0.2)
OcclusionLFRatio(1.0)
}
Space()
{
Name("hall")
I3DL2ReverbPreset("hall")
DirectGain(1.0)
DirectHFGain(1.0)
RoomGain(0.3)
RoomHFGain(0.3)
RoomRollOffFactor(3.0)
ObstructionHFGain(0.3)
ObstructionLFRatio(1.0)
OcclusionHFGain(0.3)
OcclusionLFRatio(1.0)
ConnectedList()
{
Space("corridor", 0.7)
}
}
This sets up a space "hall" which is connected to the space "corridor". If the listener is in "hall" and the source in "corridor" the source will be
attenuated appropriately. The following psuedo code is an example of what operation would be applied to the source in "corridor"
source.occlusionHFGain = 1.0 - ((1.0 - hall.occlusionHFGain) * gainFactor)
source.obstructionHFGain = 1.0 - ((1.0 - hall.obstructionHFGain) * gainFactor)
...
source OcclusionHFGain = 1.0 - ((1.0 - 0.3) * 0.7) = 0.51
source ObstructionHFGain = 1.0 - ((1.0 - 0.3) * 0.7) = 0.51
Tests
=====
Data for the tests is located in SoundFL\test\data\{platform|
A munge batch file for creating the data is located in SoundFL\test\data\munge.bat
Voice
-----
The voice test can be configured to either test low level hardware voices or virtual voices. The number of hardware voices is restricted to the number
of audio channels available on the target platform. The number of virtual voices is not restricted. When the ENABLEVIRTUALVOICES preprocessor symbol
is defined the test will use virtual voices coloring idle (not playing) voices white, playing voices with no hardware channel assigned yellow and playing
voices with a hardware channel assigned red. The listener is located in the center of the screen as a letter 'L'. Using the platform's controller
it is possible to start / stop voices, change voice and listener parameters, and, when testing virtual voices, view the priority list of virtual voices
with their assignments to hardware (real) voices. This test uses the asset(s) located in SoundFL\test\data\{platform}\effects.*
Sound
-----
This test plays Sounds which are configured using the script located in SoundFL\test\data\sound_config.txt. Fire and forget sounds are triggered at
the currently selected sound's position.
Stream
------
This test has no visual output yet. It currently plays a single audio stream.
Using the controller it is possible to start / stop the stream and change its pitch and gain. Currently streams must be authored with an interleave size
of 4Kb. This can be changed by changing SNDENGINE_STREAMSPU2BUFFERSIZE in source\ps2\engine.h and also changing the default channel interleave size
hard coded into SoundFLMunge in the file SoundFLMunge\source\sndtoolapp.cpp