/**************************************************************************

template_audio.tgi
Copyright © 2002-2003 TimeGate Studios

DESCRIPTION: Audio declarations

REVISION HISTORY:
jkm052303 - created

USAGE:

	[Audio template=AudioSound]
		Use to define a sound (world and ui sounds).

	[Audio template=AudioSpeech]
		Use to define a speech, for example a unit's monologue (should be streamed).
		
	[Audio template=AudioMusic]
		Use to define music (always streamed).
	
**************************************************************************/

[Template Audio]
{
	;;;;;; required fields
	
	;; Used to refer to the sound from code
	string	IDS
	localized name
	
	;; What type is this? Private, specified by the various child types
	string category
		
	;; this is the duration of the audio, used for reference only by the localization system.
	fixed ldf_length = 0

	;;;;;; optional fields
	
	;; Each of these fields can be a list of one or more files that should be picked when playing
	;; this sound. The leadin will be randomly chosen from the list and played. Upon completion,
	;; of the leadin, a sound (or all of them depending on the values from the control_flags field) 
	;; will be chosen and played from the files list, which is the main list. Upon completion of 
	;; *those* sounds, a sound from fallout will be randomly chosen and played. The entries 
	;; should be separated by commas.
	string leadin = NULL
	string files = NULL
	string fallout = NULL
	
	;; What is the priority for this sound? Valid values are: LOWEST, LOW, MEDIUM, HIGH, CRITICAL
	string priority = MEDIUM
		
	;; Combination of these flags (separated by commas):
	;; INTERRUPT - New instances of this sound should cannibalize old instances if there are no 
	;;			   available channels, or if the limit has been hit.
	;; SEQUENTIAL - Sounds should be played in order (rather than selected at random.)
	;; ALL - When requesting play of this sound, play all of the files (one after another, but 
	;;       not necessarily in order)
	;; VOICE - This audio uses a unit's voice. Only one "voice" sample can be played by any given
	;;         actor at any given time.
	;; WORLD - Indicates a sample should be played in 3-D, positioned in the world.
	;; CAUSEFADE - When played, this samples should cause other audio types to fade down to 
	;; some lower volume.
	;; TESTSOUND - Set this flag for options dialog volume slider sounds.
	string control_flags = NULL
	
	;; Combination of these flags (separated by commas):
	;; (WORLD flags are only used if WORLD was specified in the control_flags field)
	;; GLOBAL - This sample should be heard from everywhere on the map, regardless of distance.
	;; FOGGED - This sample should respect fog, ie: if there is fog over the source 
	;;			(wrt the local player), then this sample will not be heard by them.
	string world_flags = NULL

	;; Combination of these flags (separated by commas):
	;; LOCAL - The local player should hear this sound, as it is designated for them.
	;; PLAYER - Only the owning player will hear the sound; and only if he triggers it (unit responses, for example)
	;; ALLIES - Allies of the player (not the player themselves) will hear this sound.
	;; ENEMIES - Enemies of the player will hear this sound.
	;; EVERYONE - A convenience alias for the previous three. This is mutually exclusive with the others.
	string who_flags = NULL

	;; The first number of the range specifies how steeply the sound falloff curve should be.
	;; Lower numbers make for steeper curves, 0 is not allowed.
	;; The second number specifies at what range the sound should be muted entirely.
	point2 range = 4, 64
	
	;; How many of these sounds can be playing at the same time. More than 4 is just wasting 
	;; channels. Sounds that should never overlap should have a limit of 1.
	int simultaneous_limit = 2
	
	;; At what volume should the sound play as its "full loudness?" (Expressed as percentage of 100)
	float volume = 80%
	
	;; The delay is used to prevent phasing when a number of sounds are triggered all at once
	;; This value is in milliseconds. The actual delay will be randomly picked from between 
	;; the first and second numbers
	point2 delay_ms = 0, 0
	
	;; The pitch adjust is used to create a slight variance in the tone of a sample. These numbers
	;; are deltas from 100% (the normal value). The valid range is (-100%, 100%]
	point2 pitch_adjust = 0%, 0%

	;; Along with pitch_adjust, the volume adjust is used to create some variance in our samples
	;; without drastically increasing our memory footprint. This value is a delta from (-100%, 0%).
	float volume_adjust = 0%
	
	;; Fading - Specify how long, in seconds, that a file should fade in and out from full volume.
	;; Note that it is illegal to specify a non-zero fadeout time on anything except for music
	;; data, a bad data exception will result. (In general, fadein should also be 0 for non-streaming 
	;; audio). 
	;; SYNTAX: fadeintime, fadeouttime
	point2 fade_time_s = 0, 0
	
	;; ignore_rate - Set this to true ONLY for samples that need to be at a non-standard rate
	;; to avoid distortion. Currently, the standard rate is 22050, so this should only be true 
	;; for samples that need to be 44100.
	bool ignore_rate = false

	;; Subtitles - a streaming audio file can have a subtitle that is displayed as it is played in-game.
	;; Specify a duration (in seconds) and the subtitle text below. The game will automatically break
	;; up the subtitle into lines and show each line for an appropriate amount of time. How much time
	;; depends on the percentage of characters in that particular line relative to the total number
	;; of characters in the subtitle. Specify a duration of zero and the code will auto-assign a
	;; duration based on the audio length.
	[optional Subtitle]
	{
		fixed 		duration = 0		;; (in seconds) 
		localized 	text			;; the text of the subtitles
		string		portrait_IDS = null	;; specify the ids of an optional portrait to display
		string 		ldf_speaker = null ;; this is used for localization only.
	}
	
} ; end [Template AudioDefinition]

[Template AudioSound inherit=Audio]
{
	category = SOUND
} ; end [Template AudioDefinition]

[Template AudioSpeech inherit=Audio]
{
	category = SPEECH
	control_flags = INTERRUPT, CAUSEFADE
	fade_time_s = 0, 0

} ; end [Template AudioDefinition]
	
[Template AudioMusic inherit=Audio]
{
	category = MUSIC
	who_flags = LOCAL
	control_flags = ALL, INTERRUPT
	simultaneous_limit = 1
} ; end [Template AudioDefinition]


[Template AudioInterfaceSound inherit=AudioSound]
{
	files = /Audio/Default/FbGenericError.wav
	
	priority = CRITICAL
	
	control_flags = INTERRUPT

	; UI sounds should be LOCAL.
	who_flags = LOCAL
	
	simultaneous_limit = 2
	
	volume = 90%
	delay_ms = 0, 0
	volume_adjust = 0%
}
