====== Audio (Module) ======

Module for the audio subsystem.

===== Functions =====

#@Identifier_HTML~localSound~@# (
 #@Arg_HTML~Text,sound~@#,
 #@Arg_HTML~Number,volume~@# )

Start playing a local sound without any particular emitter object. //sound// must be a valid ID of a [[ded:sound|Sound definition]]. //volume// is the volume of the sound in the range 0...1.

This is useful for example for UI/HUD sound effects. Use [[script:module:world#World.Thing|World.Thing.startSound()]] to play a sound originating from a [[ded:thing]].


#@Identifier_HTML~setAmbientSequence~@# (
 #@Arg_HTML~Number,sequenceNumber~@#,
 #@Arg_HTML~Array,commands~@# )

(Availability: Heretic only; since [[version:2.3]]).

In Heretic, ambient sound effects are linked to DoomEd numbers 1200-1299. When one of these map spots is placed in a map (coordinates do not matter), the corresponding ambient sequence is registered for playing. //sequenceNumber// zero corresponds DoomEd number 1200. There can be up to eight sequences playing in the map, although only one at a time.

Each ambient sequence is composed of an array of commands. Below is an example of one of Heretic's built-in sequences ("Drops", DoomEd number 1202):

<code>
Audio.setAmbientSequence(2, [
    "play",      "amb3",
    "delay",     16,
    "delayrand", 31,
    "play",      "amb7",
    "delay",     16,
    "delayrand", 31,
    "play",      "amb3",
    "delay",     16,
    "delayrand", 31,
    "play",      "amb7",
    "delay",     16,
    "delayrand", 31,
    "play",      "amb3",
    "delay",     16,
    "delayrand", 31,
    "play",      "amb7",
    "delay",     16,
    "delayrand", 31,
    "end"
])
</code>

The available commands are:

^ Command ^ Parameters ^ Description |
| ''play'' | soundID | Play a sound (random volume) |
| ''playabsvol'' | soundID, volume | Play a sound at specified volume (0...127) |
| ''playrelvol'' | soundID, volumeOffset | Play a sound at volume relative to previous sound's volume  |
| ''delay'' | tics | Wait given number of tics (1 second = 35 tics) |
| ''delayrand'' | arg | Wait for ''P_Random() & arg'' tics (note: bitwise AND operator) |
| ''end'' | | Sequence terminator. Another one of the map's sequences is started at random after a delay. |

This function can be called from a [[ded:map_info_syntax#on_setup|Map Info "On setup"]] script to set up ambient sound sequences in that map. The sound sequences are reset back to the built-in sequences whenever the map changes.

This function can also be called during a map. If the currently playing sequence is modified, it will restart as if the ''end'' command had been used.