View source for Team Fortress 2/Scripting/Script Functions/EmitSoundEx

== Function Description ==
<code>void EmitSoundEx(table ''parameters'')</code>

Flexible way of playing sounds. All parameters except <code>sound_name</code> are optional. Sounds must be precached first using <code>PrecacheSound</code> or <code>PrecacheScriptSound</code>, or they won't play. Sounds can be played in raw or [[soundscript]] form, and filtered to everyone, on a per-team or per-player basis. Volume, pitch, channel and attenuation level can be controlled, and the sound can play from a fixed position or relative to an entity. It is also possible to stop or adjust sounds already playing on the entity using special flags such as <code>SND_CHANGE_VOL</code> or <code>SND_CHANGE_PITCH</code>.

{{note|If the sound is playing while a player is outside of the sound's [[PAS]]/[[PVS]]/attenuation, and then enters its visiblity, the player will not hear the sound. This may be a problem for looping sounds or sounds with long durations, in which case the following workarounds can be used:
* Use the <code>RECIPIENT_FILTER_GLOBAL</code>/<code>RECIPIENT_FILTER_TEAM</code> filter. The sound will still "play" outside of the range, but at no volume.
* Play the sound to the player individually using <code>RECIPIENT_FILTER_SINGLE_PLAYER</code> when they enter a given area, e.g. via a trigger.
* Create a [[soundscape]] which automatically deals with this on a per-player basis}}
{{warning|Looping sounds will NOT stop automatically on round restart or when an entity is destroyed. You must manually stop them with the <code>SND_STOP</code> flag.
{{tip|The best time to stop looping sounds is during the <code>scorestats_accumulated_update</code> event. This event is fired right before all map entities are cleaned up. On players, stop the sound in the <code>player_disconnect</code> event.}}}}

== Parameters ==

{| class="standard-table" style="width:100%"
! Name
! Type
! Default
! Description
|-
| <code>sound_name</code>
| <code>string</code>
|
| Name of sound. Can be raw filename or soundscript.
{{note|Soundscripts override the <code>channel</code>, <code>volume</code> and <code>pitch</code> parameters. However the latter two can be forcefully overriden by adding the <code>SND_CHANGE_VOL</code> or <code>SND_CHANGE_PITCH</code> flags respectively.}}
|-
| <code>channel</code>
| <code>int</code>
| 0
| Channel ID on which to play the sound. Channel values below have special behavior, all other channels behave normally. List of special channels:
{| class="standard-table" style="width:100%"
! Name
! Value
! Description
|-
| <code>CHAN_REPLACE</code>
| <code>-1</code>
| Used by console commands
|-
| <code>CHAN_AUTO</code>
| <code>0</code>
| Automatic channel {{clarify}}
|-
| <code>CHAN_WEAPON</code>
| <code>1</code>
| Weapon sounds
|-
| <code>CHAN_VOICE</code>
| <code>2</code>
| Character voices
|-
| <code>CHAN_ITEM</code>
| <code>3</code>
| Items {{clarify}}
|-
| <code>CHAN_BODY</code>
| <code>4</code>
| Impacts, ragdolls and footsteps
|-
| <code>CHAN_STREAM</code>
| <code>5</code>
| "Stream from static or dynamic area" {{clarify}}
|-
| <code>CHAN_STATIC</code>
| <code>6</code>
| Constant or background sounds. Valve recommends this to be used for looping ambient sounds, uninterrupted looping sounds or "one-shot" sounds
{{note|Allows multiple of the same sounds to play without cutting out}}
{{confirm|Code comments imply that this channel continues to work outside of the sound radius}}
|-
| <code>CHAN_VOICE2</code>
| <code>7</code>
| {{tf2|2}} Announcer
|-
| <code>CHAN_VOICE_BASE</code>
| <code>8 - 107</code>
| Allocated for player voice chat (100 channels)
{{note|Allows multiple of the same sounds to play without cutting out}}
|}
|-
| <code>volume</code>
| <code>float</code>
| 1.0
| Volume of sound, in normalized 0 - 1 range. {{tip|Sounds may be hard to hear even at full volume. Naming custom sounds according to the [[soundmixer]] can be used to make them naturally louder.}}
|-
| <code>sound_level</code>
{{notice|Type the name of this parameter carefully. This has been a frequent mistake!}}
| <code>int</code>
| 0 
| Sound attenuation in decibels. The default value of 0 will make it play globally. See [[Soundscripts#SoundLevel|this page]] for real world equivalents. If the sound has non-zero attenuation, it will play from the <code>entity</code>'s origin if present, otherwise it uses the <code>origin</code> parameter.
{{tip|To convert radius in Hammer units to decibels (similar to [[ambient_generic]]), use the following formula:
<source lang=js>
local soundlevel = (40 + (20 * log10(radius / 36.0))).tointeger();
</source>
}}

|-
| <code>flags</code>
| <code>int</code>
| 0
| Special sound flags. List of flags available:
{| class="standard-table" style="width:100%"
! Name
! Value
! Description
|-
| <code>SND_NOFLAGS</code>
| <code>0</code>
| Nothing special.
|-
| <code>SND_CHANGE_VOL</code>
| <code>1</code>
| Changes volume of an already-playing sound on this entity. Sounds will not restart playback if already active.
|-
| <code>SND_CHANGE_PITCH</code>
| <code>2</code>
| Changes pitch of an already-playing sound on this entity. Sounds will not restart playback if already active.
|-
| <code>SND_STOP</code>
| <code>4</code>
| Stops the specified sound if playing on this entity.
{{ModernConfirm|This may be channel-specific.}}
{{warning|ALWAYS use the <code>RECIPIENT_FILTER_GLOBAL</code> filter when stopping sounds. Otherwise, sounds will not be stopped for players outside of the sound radius and will persist forever.}}
|-
| <code>SND_SPAWNING</code>
| <code>8</code>
| Writes sound info into net message for connecting clients. {{ModernConfirm|This probably doesn't do anything at runtime.}}
|-
| <code>SND_DELAY</code>
| <code>16</code>
| Specifies the sound should be scheduled with a delay.
|-
| <code>SND_STOP_LOOPING</code>
| <code>32</code>
| Stop all looping sounds on the entity. {{bug|Not implemented by the engine.}}
|-
| <code>SND_SPEAKER</code>
| <code>64</code>
| Used by audio played through [[env_microphone]]. Applies special mixing rules.
|-
| <code>SND_SHOULDPAUSE</code>
| <code>128</code>
| Sound will be paused when the game is paused. Useless in multiplayer.
|-
| <code>SND_IGNORE_PHONEMES</code>
| <code>256</code>
| Prevents [[flex animation]] from being driven by this sound, if available.
|-
| <code>SND_IGNORE_NAME</code>
| <code>512</code>
| Changes all sounds emitted on the entity, regardless of actual name.
|-
| <code>SND_DO_NOT_OVERWRITE_EXISTING_ON_CHANNEL</code>
| <code>1024</code>
| If an existing sound is found on the channel, the sound will not play instead of overwriting it.
|}
|-
| <code>pitch</code>
| <code>int</code>
| 100
| Pitch of the sound.
|-
| <code>special_dsp</code>
| <code>int</code>
| 0
| [[DSP]] effect to use on this sound.
|-
| <code>origin</code>
| <code>Vector</code>
| 0 0 0
| Overwrites sound origin if specified.
{{note|If not specified, the origin will be fetched from the <code>entity</code> parameter for <code>RECIPIENT_FILTER_PAS</code> and <code>RECIPIENT_FILTER_PVS</code> filters.}}
|-
| <code>delay</code>
| <code>float</code>
| 
| How far to skip into the sound playback, in seconds. The value must be ''negative''!
{{Bug|Many (but not all) MP3 files cannot be skipped past a certain point depending on how the file was saved/compressed.  The amount you are able to skip is not consistent, however it is usually around 30-35 seconds.  <code>"music/hl2_song2.mp3"</code> for example will seemingly allow you to skip to any point in the song, while <code>"music/hl2_song31.mp3"</code> will only allow you to skip up to 35.8 seconds, and <code>"music/hl2_song26_trainstation1.mp3"</code> will only allow you to skip up to 32.9 seconds.  WAV files are not affected by this.}}
{{todo|Is there any practical effect from a positive delay value?}}
|-
| <code>sound_time</code>
| <code>float</code>
| 
| Absolute time to delay sound until, NOT the duration. Overrides <code>delay</code> if specified. {{todo|Might require the ''SND_DELAY'' flag to be set.}}
|-
| <code>entity</code>
| <code>handle</code>
| null
| Entity to emit the sound from. This is also used by certain filters. e.g. <code>RECIPIENT_FILTER_SINGLE_PLAYER</code> will play sounds only to the specified player here, or <code>RECIPIENT_FILTER_PVS</code> will build a [[PVS]] filter originating from this entity.
{{note|The entity specified must be an [[edict]], i.e. clients are aware of it's existence.}}
|-
| <code>speaker_entity</code>
| <code>handle</code>
| null
| Entity which will *speak* the sound. This is not the sound as the actual owner of the sound, see above.
|-
| <code>filter_type</code>
{{notice|Type the name of this parameter carefully. This has been frequently written as <code>filter</code> by mistake!}}
| <code>int</code>
| 0
| Specifies what entities can hear this entity. See [[Team_Fortress_2/Scripting/Script_Functions/Constants#EScriptRecipientFilter|Constants.EScriptRecipientFilter]].
|-
| <code>filter_param</code>
| <code>int</code>
| -1
| Specifies an extra option to the filter. Currently only used by <code>RECIPIENT_FILTER_TEAM</code>, which uses this to specify which team to play to.
|}

== Flags ==
It may be useful to define these flags for extra readability.
<source lang=js>
::SND_NOFLAGS <- 0
::SND_CHANGE_VOL <- 1
::SND_CHANGE_PITCH <- 2
::SND_STOP <- 4
::SND_SPAWNING <- 8
::SND_DELAY <- 16
::SND_STOP_LOOPING <- 32
::SND_SPEAKER <- 64
::SND_SHOULDPAUSE <- 128
::SND_IGNORE_PHONEMES <- 256
::SND_IGNORE_NAME <- 512
::SND_DO_NOT_OVERWRITE_EXISTING_ON_CHANNEL <- 1024
</source>

== Example Usage ==
<source lang=js>
// sounds should be precached once before use
PrecacheScriptSound("Game.Domination");

// play the sound to everyone around yourself
EmitSoundEx({
	sound_name = "Game.Domination",
	origin = GetListenServerHost().GetCenter(),
	filter_type = Constants.EScriptRecipientFilter.RECIPIENT_FILTER_GLOBAL
});
</source>

== Playing to specific players ==
It may be useful to play a sound to a specific list of players only, and/or with the sound originating from a source rather than globally. 

This abuses a feature of [[PAS]] filtering, where players that are too far away won't hear the sound. This moves their view very, very far away and then sets it back after sending the sound to achieve arbitrary filtering.

<source lang=js>
function EmitSoundFiltered(params, included_players)
{
	local origin = Vector()
	local exclude_offset = Vector(99999, 99999, 99999)
	
	local players = {}
	for (local player; player = Entities.FindByClassname(player, "player");)
	{
		if (included_players.find(player) == null)
		{
			players[player] <- NetProps.GetPropVector(player, "m_vecViewOffset")
			NetProps.SetPropVector(player, "m_vecViewOffset", exclude_offset)
		}
	}
	
	params.filter_type <- 1 // RECIPIENT_FILTER_PAS_ATTENUATION
	EmitSoundEx(params)
	
	foreach (player, offset in players)
		NetProps.SetPropVector(player, "m_vecViewOffset", offset)
}

// example usage that plays the sound only to the host and originating from an entity named "speaker"
local players = []
players.append(GetListenServerHost())

EmitSoundFiltered
({
	sound_name  = "vo/engineer_medic03.mp3"
	sound_level = 80
	entity      = Entities.FindByName(null, "speaker")
}, players)
</source>