Sound tags are used for things that make sound or play music.


OGG dll files: Link

These are required to compile non-crashing OGG encoded sound tags.

Xbox ADPCM Codec: Link

You'll need to install this to be able to compile Xbox codec encoded sound tags.

Note: The Xbox codec is also used in the PC and Custom Edition version of the game.


To store audio in our maps we use sound tags. Sound tags are compiled from wave files into either the xbox codec or the ogg codec.


tool sounds <source-file/folder> <compression> <quality>

This command is used to create a single sound tag file. From either a single wav file or a folder of wav files. A folder of wav files will be turned into a single sound tag with multiple permutations. If you give tool a source-folder that has sub-folders the sub-folders will be turned into sound tags with the same name in the respective path in the tags folder.

The compression can be either xbox, ogg, or wav.

Note: wav compressed sounds will not play in-game.

The quality should be a number from 0 to 1. 1 being the highest quality and 0 being the lowest. This value is usually left at 1.

Example: You have a set of wav files in data/foo/bar, a set of wav files in the data/foo/beef, and these sound tags will be encoded using the xbox codec.

An example tool command would be :

tool sounds "foo" xbox 1

This would create the files bar.sound and beef.sound in the folder tags/foo

Encoding and format

The encoding that you use for a sound tag should be determined by it's usage. A few examples: music and voice should always be OGG encoded, but things like weapon sounds can be either Xbox or OGG encoded.

Sample rate

This is determined by the sample rate of the input wav file(s).


The amount of audio channels this sound tag has. This can be either mono or stereo.

What compression, encoding, and sample rate to use

Music, environmental background loops: 44kHz, stereo, OGG.

Voice/dialog: 22kHz, mono, OGG.

Anything else: 22kHz, mono, OGG or Xbox.

Sound Classes

Near the top of a sound file it will have a drop-down that allows you to select the class type of the sound.

The class determines the game's behavior with how it plays the sound. How loud it is, what ai behaviors it triggers, how far it reaches, when to skip the sound for optimization.

List of sound classes:

Sound classes with the 'projectile' prefix are meant to be used on particle type objects and their effects.

  • projectile_impact: Used for when projectiles impact with things.
  • projectile_detonation: Used for when a projectile detonates. Ex: A missile exploding.

Sound classes with the 'weapon' prefix are generally meant to be used on weapon type objects, their effects and animations. But sometimes also on objects that act like weapons.

  • weapon_fire: The sound attached to a weapon firing effect.
  • weapon_ready: Used for the animation a weapon plays when you switch to it.
  • weapon_reload: Used for certain weapon impulse animations like reloads and melees.
  • weapon_empty: The clicky sound a weapon makes when it's empty and you try to fire it.
  • weapon_charge: The sound attached to a loop that plays when a weapon is charging up to fire.
  • weapon_overheat: Sounds that play when a weapon has overheated.
  • weapon_idle: A sound used for the weapon's 'posing' animation.

Sound classes with the 'impacts' suffix are meant to be used for when one thing collides with another.

  • object_impacts
  • particle_impacts
  • slow_particle_impacts

Sound classes with the 'unit' prefix are meant to be used with unit type objects, such as bipeds and vehicles.

  • unit_footsteps: Used for footstep sounds.
  • unit_dialog: Used for dialog sounds. (This class will also cause tool to generate mouth data for each sample when you recompile the tag.)

Sound classes with the 'vehicle' prefix are meant to be used on vehicle type objects.

  • vehicle_collision: Sounds a vehicle may make when crashing into things.
  • vehicle_engine: The sound in a loop attached to a vehicle.

Sound classes with the 'device' prefix are meant to be used on device type objects. The name signals the general type of device this sound is being used for.

  • device_door
  • device_force_field
  • device_machinery
  • device_nature
  • device_computers
  • music: Used by sounds that sound be treated as music.

Sounds classes with the 'ambient' prefix are meant to use used in sound_environment and sound_scenery tags.

  • ambient_nature
  • ambient_machinery
  • ambient_computers
  • first_person_damage

Sounds classes with the 'scripted' prefix signal to the game that this sound can not be ignored when it is called to be played.

  • scripted_dialog_player: A scripted dialog that comes from the player's head.
  • scripted_effect
  • scripted_dialog_other
  • scripted_dialog_force_unspatialized: A scripted dialog sound that does not have directional and distance audio applied to it.
  • game_event: A general purpose sound class that is used for sounds attached to important events.

Tag fields

These are fields you can edit in Guerilla to alter the behavior of your sound tag.


  • flags:
    • fit to adpcm blocksize
    • split long sound into permutations: (Tag needs to be recompiled using tool for this setting to have effect) This is used primarily for music and long loops to improve loading time and playback performance. This is particularly useful for OGG compressed sounds as the game has a small decompression buffer it uses when playing the sounds ingame. If that buffer fills up sounds may not properly go to the next permutation or cut out. Splitting a long sound into permutations lowers their individual size and allows for more sounds in the sound decompression buffer.
  • class: This is used for things like determining when to skip this sound if the game is running out of resources and the default volume and distance of the sound.
  • sample rate: This is used to determine how fast the sound should be read.
  • minimum distance: The maximum distance in which the sound can be heard at full volume.
  • maximum distance: The distance after which the sound can not be heard anymore.
  • skip fraction: A 0 to 1 chance of the sound not being played.


  • random pitch bounds: Two multipliers that specify what the range is of how far the sound can be slowed down or sped up. Defaults to 1 and 1 on map compile if left at 0 and 0.
  • inner cone angle: Defaults to 360 when compiling a map if left at 0.
  • outer cone angle: Defaults to 360 when compiling a map if left at 0.
  • gain modifier: Defaults to 1 when compiling a map if left at 0.
  • maximum bend per second

When scale is [ZERO | ONE]

When scale is 0 the multipliers are what is given at ZERO and when scale is 1 the multipliers are what is given at ONE. The formula for scales between 0 and 1 is presumed to be:

original * ( scale * ONE_multiplier + (1-scale) * ZERO_multiplier )

Values of 0 are ignored.

  • skip fraction modifier: Multiplies the skip fraction of the sound tag by the given number.
  • gain modifier: Multiplies the gain modifier of the sound tag by the given number.
  • pitch modifier: Multiplies the pitch modifier of the sound tag by the given number.

Import properties

  • Encoding: Specifies if the sounds are in either Mono or Stereo.
  • Compression: Specifies the format in which the sound is stored.
    • ogg: OGG Vorbis encoding.
    • xbox adpcm: The XBOX format (still used on PC).
    • ima adpcm: Wave encoding. (This doesn't play in-game. Only in Sapien.)
  • Promotion sound: When this sound has been played the amount of times specified in the promotion count it will play the sound tag referenced in here instead. (Used for things like shotgun shells)
  • Promotion count: The amount of times this sound tag needs to be called before the promotion sound is used instead.

Pitch ranges and permutations

Permutations are the different versions of the sound that get either at random or for music in sequence.

Pitch ranges specify one or more sets of permutations for when something like an object is controlling the sound. (For instance a warthog would use this for it's engine sound)

Pitch ranges

When compiling sound tags using tool, if you put sub-folders inside of a sub-folder, and put wav files into the sub-folders it will create pitch ranges using those wav files in the sound tag. This is how vehicle engine sounds are made. (You will need to manually set the pitch control values in Guerilla.)

  • name: Name for this given pitch range. (The name of the sub-folder the source files for this pitch were in.)

Pitch control

Only used when there is more than one pitch range.

  • natural pitch: The apparent pitch the sound needs to be at for the samples to be played at their recorded pitch (1.0).
  • bend bounds: the bounds of this pitch range. (Should contain the natural pitch.)
  • actual permutation count: The permutation count when accounting for permutations being split into smaller 'permutations'.


  • name: The name of the wav file that became this permutation.
  • skip fraction: The 0 to 1 chance that when playing this sound it will skip this permutation.
  • gain: The volume multiplier for this permutation. Defaults to 1 when compiling a map if left at 0.
  • compression: The compression format for this permutation. (Ignored by the game?)
  • next permutation index: This is used for long sounds that are split into multiple permutations so the game knows what permutation to play next. -1 means there isn't a follow up permutation.
  • samples: The raw audio data for this permutation.
  • mouth data: The data for how far the biped's mouth should be opened for each tick that this sound plays. Only used for dialog classed sounds, this data does not get generated when the sound class is not dialog.
  • subtitle data: (Unused?)

Tool Errors and Warnings

  • EXCEPTION halt in \halopc\haloce\source\sound\sound_dsound_pc.c,#1940: properties->gain>=0.f && properties->gain<=1.f
  • EXCEPTION halt in \halopc\haloce\source\sound\sound_manager.c,#3304: gain>=0.f && gain<=1.f
    • Cause: Sapien's sound properties are broken.
    • Fix: Restarting might help.
  • MM:  'couldn't open stream.' (ACMERR_NOTPOSSIBLE#512)
    • Cause: You do not have the xbox adpcm codec installed.
    • Fix: Install the codec. (You can get the codec from the top of this page)
  • EXCEPTION halt in \halopc\haloce\source\tag_files\tag_groups.c,#3157: # is not a valid sound_permutations_block index in [# ,# )
    • Cause1: The permutations block on your sound tag is empty.
    • Fix1: Delete the sound tag and recompile.
    • Cause2: A permutation in the permutations block has a permutation index that is out of range.
    • Fix2: Delete the sound tag and recompile.
    • Alt Fix2: Find and fix the incorrect index. (-1 means none)