Anachronox Sound and Music Functionality
Introduction
Anachronox uses RAD Gametool's Miles Sound System and Microsoft's DirectMusic to play sound effects, speech and background music. The file formates we currently support are .WAV and .MP3 files for the sound effects and speech effect. Background music should be in the .SEG format, which basically is a MOD format for MIDI. Along with the .SEG file there should be a corresponding .DLS file which contains all the samples needed in the .SEG file.

Sound Effect Functionality
There are a number of ways to make sounds appear in Anachronox. I will list the APE and Planet functions first, to later on describe how to make the sound sources an integral part of the actual map.

Sound Effect Functionality in APE:
From APE, there are basically 4 extern functions that provide the functionality we need.

playsound ( filename{.WAV|.MP3} ) [ entity_id ] [ volume ] [ attenuation ]
loopsound ( filename{.WAV|.MP3} ) [ entity_id ] [ volume ] [ attenuation ]
stopsound ( filename{.WAV|.MP3} )
playanimation ( entity_id ) ( filename )

playsound loopsound Starts the playback of a sound file.
One argument is required, which is the relative path and filename of the sound effect to play. The file extension (.WAV or .MP3) must be supplied. The sound system will scan through first the subdirectory anoxdata/sound and secondly the directory anoxdata/music if the specified file is not found in the sound directory. The pathname should therefore be given as, eg, "bricks/engine3.wav". The system will then prepend "anoxdata/sound" and "anoxdata/music" to the given path and try to load and play the file.
If an entity_id is given, either as a sequence number or a classname, the system will try to locate that entity in the world and play the sound so it originates from that entity's midpoint.
Volume and attenuation should be a value between 0.0-1.0 and 0.0-4.0 respectively. volume is an indication on how loud the sound will be played. The default value is 0.5. This makes it possible to, in certain special cases, pump up the sound volume a little extra to create the effect of something REALLY big, like an explosion, or similar. The attenuation value is an indication of how fast the sound will fade with distance. Default value is 2.0. A smaller value will travel further and a higher value will be cut off faster.
The difference between the two functions is that playsound plays the sound once, while loopsound repeats the sound indefinitely.
Example:
"extern playsound Bricks/HighwayToHell.mp3" would play your favorite AC/DC song.
"extern loopsound Bricks/HighwayToHell.mp3 ghetto_blaster 1.0 2.0" would locate the entity with the classname ghetto_blaster and play the same song from the location of that ghetto_blaster at full volume and normal attenuation. The sound would then loop over and over again and move around the level if the ghetto_blaster is carried around by another character.

stopsound Stops the playback of a sound file.
The system will loop through all sounds being played and, if it finds the specified filename, will shut it off. The filename should be the same as the name used to start the sound, but it is case-insensitive.
Example:
"extern stopsound Bricks/HighwayToHell.mp3" would stop your favorite AC/DC song.

playanimation Starts the playback of a lipsynched speech sound.
entity_id is, as above, either a sequence number or a classname. filename is the filename of the sound/Magpie file to play WITHOUT file extension. The facial animations work as follows:
The system tried to locate a file with that name, with either a .WAV or .MP3 extension. If the sound file is found, the Magpie parser tries to locate a file with the same filename, but with a .LIP extension. If the .LIP file is found, the information is parsed and the morph data in it is sent to the facial deformation graphics system. If the .LIP file is not found, the system will generate random lip movement data for the duration of the soundfile's length. Example:
"extern playanimation 132:02 Bricks/dettagoon4" would start the dettagoon4 sound and play the animation on the entity with the sequence number 132:02, which hopefully should be the Detta goon. :-)

playsound loopsound	Starts the playback of a sound file. One argument is required, which is the relative path and filename of the sound effect to play. The file extension (.WAV or .MP3) must be supplied. The sound system will scan through first the subdirectory anoxdata/sound and secondly the directory anoxdata/music if the specified file is not found in the sound directory. The pathname should therefore be given as, eg, "bricks/engine3.wav". The system will then prepend "anoxdata/sound" and "anoxdata/music" to the given path and try to load and play the file. If an entity_id is given, either as a sequence number or a classname, the system will try to locate that entity in the world and play the sound so it originates from that entity's midpoint. Volume and attenuation should be a value between 0.0-1.0 and 0.0-4.0 respectively. volume is an indication on how loud the sound will be played. The default value is 0.5. This makes it possible to, in certain special cases, pump up the sound volume a little extra to create the effect of something REALLY big, like an explosion, or similar. The attenuation value is an indication of how fast the sound will fade with distance. Default value is 2.0. A smaller value will travel further and a higher value will be cut off faster. The difference between the two functions is that playsound plays the sound once, while loopsound repeats the sound indefinitely. Example: "extern playsound Bricks/HighwayToHell.mp3" would play your favorite AC/DC song. "extern loopsound Bricks/HighwayToHell.mp3 ghetto_blaster 1.0 2.0" would locate the entity with the classname ghetto_blaster and play the same song from the location of that ghetto_blaster at full volume and normal attenuation. The sound would then loop over and over again and move around the level if the ghetto_blaster is carried around by another character.
stopsound	Stops the playback of a sound file. The system will loop through all sounds being played and, if it finds the specified filename, will shut it off. The filename should be the same as the name used to start the sound, but it is case-insensitive. Example: "extern stopsound Bricks/HighwayToHell.mp3" would stop your favorite AC/DC song.
playanimation	Starts the playback of a lipsynched speech sound. entity_id is, as above, either a sequence number or a classname. filename is the filename of the sound/Magpie file to play WITHOUT file extension. The facial animations work as follows: The system tried to locate a file with that name, with either a .WAV or .MP3 extension. If the sound file is found, the Magpie parser tries to locate a file with the same filename, but with a .LIP extension. If the .LIP file is found, the information is parsed and the morph data in it is sent to the facial deformation graphics system. If the .LIP file is not found, the system will generate random lip movement data for the duration of the soundfile's length. Example: "extern playanimation 132:02 Bricks/dettagoon4" would start the dettagoon4 sound and play the animation on the entity with the sequence number 132:02, which hopefully should be the Detta goon. :-)

Sound Effect Functionality in Planet:
From Planet, there are three sound related commands:

soundonce (filename),(channel),(flush),(volume),(attenuation)
soundloop (filename),(channel),(flush),(volume),(attenuation)
soundclear (channel)

soundonce soundloop Starts the playback of a sound file.
filename, attenuation and volume are the same as above. However, the channel and flush arguments deserves some extra mention.
Basically, each entity has 4 virtual channels. This means that we can stack up to 4 sounds on a separate channel and play them all at once. The channel designates which of these channels to use [0-3]. When soundonce or soundloop is called with a channel id, the system will perform a check to see if there is another sound playing on that same channel.
If this is the case, we have a couple of choices. If the sound already playing on the channel has been started with soundloop and hence is a looping sound, that sound will be stopped immediately and the new sound played on that channel.
If, however, the previous sound wasn't a looping sound, the system will look at the flush flag. If the flush flag is set, the system will stop the previous sound immediately and start playback of the new sound at once. If the flush flag is '0', however, the new sound will be put on hold and playback won't start until the previous sound has finished.
This may sound complicated, but it allows for things like "play the car's starting sound(non-looped sound) and que up the sound of the car's running sound (a looped sound) so it will start immediately after the starting sound has finished".

soundclear Stops the playback of a sound file.
channel basically designates which of the entity's virtual channel to shut off.
Well, I thought to write more here, but what more can be said? :-)

soundonce soundloop	Starts the playback of a sound file. filename, attenuation and volume are the same as above. However, the channel and flush arguments deserves some extra mention. Basically, each entity has 4 virtual channels. This means that we can stack up to 4 sounds on a separate channel and play them all at once. The channel designates which of these channels to use [0-3]. When soundonce or soundloop is called with a channel id, the system will perform a check to see if there is another sound playing on that same channel. If this is the case, we have a couple of choices. If the sound already playing on the channel has been started with soundloop and hence is a looping sound, that sound will be stopped immediately and the new sound played on that channel. If, however, the previous sound wasn't a looping sound, the system will look at the flush flag. If the flush flag is set, the system will stop the previous sound immediately and start playback of the new sound at once. If the flush flag is '0', however, the new sound will be put on hold and playback won't start until the previous sound has finished. This may sound complicated, but it allows for things like "play the car's starting sound(non-looped sound) and que up the sound of the car's running sound (a looped sound) so it will start immediately after the starting sound has finished".
soundclear	Stops the playback of a sound file. channel basically designates which of the entity's virtual channel to shut off. Well, I thought to write more here, but what more can be said? :-)

Putting sounds into the actual level
Since the APE and Planet systems clearly aren't enough to put sounds in levels ;-), we can also do it the Die-Hard, QuakeII way, ie just putting the sounds into the map file and be done with it. These are the commands that you can put into the map file, in the definitions of target_speakers and trigger_multiple.

noise ( filename )
volume ( value )
attenuation ( value )
spawnflags ( flag)

noise Specifies the filename of the sound file to play
The search for the filename you have specified starts in the anoxdata/sounds directory.
Example:
"noise" "global/earthquake1.wav" would set the sound to be an earthquake

volume The volume level at which the sound should be played at. Range: 0.0 - 1.0
Default is '0.5'. Use a lower setting for sounds that should be more quiet and, guess what? Use a higher setting for sounds that should dominate the scene more.
Example:
"volume" "0.3" would play the sound real quiet.

attenuation The attenuation level for this sound. Range: 0.0 - 4.0
Attenuation, or "How the volume fades with the distance from the sound source", is a good tool to add to the ambient sounds. Defualt is '2.0'. Use a lower value if you want the sound to be heard further away from the sound source and a higher value if the volume is to drop fast once you're a bit away from the sound source.
Note: This is purely a fictional value. It has no correspondence in the real world, so it's hard to tell what it "really" is. :-)
Example:
"attenuation" "0.2" would make the sound be heard very far away.

spawnflags Sets the default behavior of the sound source. Values: '1' or '2'
A Spawnflag of '1' means that the sound is already playing when you start the level. A flag of '2' means that the sound source will start looping when it's targeted. (For help on Targetting, target names, origin and other values that are important to sounds sources, see elsewhere. :-)
Note: If the "spawnflags" are 0 (zero) or left out all together, the sound will be silent until you target it and then only play the sound once. (Thanks, Seneca. ;-)
Example:
"spawnflags" "2" would make sure the sound was quiet until it was targeted.

noise	Specifies the filename of the sound file to play The search for the filename you have specified starts in the anoxdata/sounds directory. Example: "noise" "global/earthquake1.wav" would set the sound to be an earthquake
volume	The volume level at which the sound should be played at. Range: 0.0 - 1.0 Default is '0.5'. Use a lower setting for sounds that should be more quiet and, guess what? Use a higher setting for sounds that should dominate the scene more. Example: "volume" "0.3" would play the sound real quiet.
attenuation	The attenuation level for this sound. Range: 0.0 - 4.0 Attenuation, or "How the volume fades with the distance from the sound source", is a good tool to add to the ambient sounds. Defualt is '2.0'. Use a lower value if you want the sound to be heard further away from the sound source and a higher value if the volume is to drop fast once you're a bit away from the sound source. Note: This is purely a fictional value. It has no correspondence in the real world, so it's hard to tell what it "really" is. :-) Example: "attenuation" "0.2" would make the sound be heard very far away.
spawnflags	Sets the default behavior of the sound source. Values: '1' or '2' A Spawnflag of '1' means that the sound is already playing when you start the level. A flag of '2' means that the sound source will start looping when it's targeted. (For help on Targetting, target names, origin and other values that are important to sounds sources, see elsewhere. :-) Note: If the "spawnflags" are 0 (zero) or left out all together, the sound will be silent until you target it and then only play the sound once. (Thanks, Seneca. ;-) Example: "spawnflags" "2" would make sure the sound was quiet until it was targeted.