> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: Sounds
icon: volume-2
---

# <ApiPageIcon icon="volume-2" />Sounds

<ApiExposes data="[{&#x22;k&#x22;:&#x22;OBJECT&#x22;,&#x22;c&#x22;:&#x22;method&#x22;,&#x22;s&#x22;:&#x22;sounds.PlayEvent.Options&#x22;,&#x22;h&#x22;:&#x22;#soundsplayeventoptions&#x22;},{&#x22;k&#x22;:&#x22;OBJECT&#x22;,&#x22;c&#x22;:&#x22;method&#x22;,&#x22;s&#x22;:&#x22;sounds.Sound&#x22;,&#x22;h&#x22;:&#x22;#soundssound&#x22;},{&#x22;k&#x22;:&#x22;NAMESPACE&#x22;,&#x22;c&#x22;:&#x22;fn&#x22;,&#x22;s&#x22;:&#x22;sounds&#x22;,&#x22;h&#x22;:&#x22;#sounds-1&#x22;}]" />

## sounds.PlayEvent.Options<ApiTag label="object type" />

Options for `sounds.PlayEvent`.

<ApiMembers>
  <ApiMember kind="prop" name="sounds.PlayEvent.Options.lifetime" summary="The time in seconds until the emitter is removed. The default is `30`. Pass `0` to keep the emitter until you call `Destroy`, the script unloads, or the map ends. Use `0` for looping sounds. A negative value throws an error." ret="[[{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" />

  <ApiMember kind="prop" name="sounds.PlayEvent.Options.stop_on_new" summary="Whether to stop the previous event when the emitter starts again. The default is `false`." ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" />
</ApiMembers>

## sounds.Sound<ApiTag label="object type" />

A soundevent that this script started at a world position.

The sound does not stop when no variable refers to this object anymore. It plays until you
call `Destroy`, its `lifetime` ends, the script unloads, or the map ends. After that, every
method returns `false` or `nil`.

The game does not tell when a sound that plays once has finished, so `IsValid` returns `true`
until one of the events above happens.

<ApiMembers>
  <ApiMember kind="method" name="sounds.Sound:IsValid" summary="Returns whether the sound still plays from the emitter of this object." args="" sig="[{&#x22;s&#x22;:&#x22;sounds.Sound:IsValid&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" nodiscard />

  <ApiMember kind="method" name="sounds.Sound:GetName" summary="Returns the name of the soundevent that started the sound. Returns `nil` after the sound is removed." args="" sig="[{&#x22;s&#x22;:&#x22;sounds.Sound:GetName&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" nodiscard />

  <ApiMember kind="method" name="sounds.Sound:SetOrigin" summary="Moves the emitter to a new position. A looping sound moves with the emitter. A sound that plays once and has finished does not play again. Throws an error if `origin` is not a finite vector." args="origin" sig="[{&#x22;s&#x22;:&#x22;sounds.Sound:SetOrigin&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;origin&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;origin&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;}],&#x22;d&#x22;:&#x22;The position in world space.&#x22;}]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;`false` if the sound was already removed.&#x22;}]" />

  <ApiMember kind="method" name="sounds.Sound:Destroy" summary="Stops the sound and removes its emitter." args="" sig="[{&#x22;s&#x22;:&#x22;sounds.Sound:Destroy&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}],&#x22;d&#x22;:&#x22;`false` if the sound was already removed.&#x22;}]" />
</ApiMembers>

<Heading level={2} id="sounds-1">
  sounds

  <ApiTag label="global table" />
</Heading>

Plays sound files in 2D and soundevents at world positions.

A script can have at most 32 world space sounds at the same time.

<ApiMembers>
  <ApiMember kind="fn" name="sounds.PlayFile" summary="Plays a sound file by name in 2D. The volume is multiplied by the master volume of the game." args="path, volume?" sig="[{&#x22;s&#x22;:&#x22;sounds.PlayFile&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;path&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;[, &#x22;},{&#x22;s&#x22;:&#x22;volume&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;}]" params="[{&#x22;n&#x22;:&#x22;path&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The name or path of the sound file.&#x22;},{&#x22;n&#x22;:&#x22;volume&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;number&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#number&#x22;}],&#x22;d&#x22;:&#x22;The volume from `0` to `1`. The default is `1`.&#x22;,&#x22;o&#x22;:true}]">
    <ApiNotes>
      The file must be in a sound search path of the game. A sound file cannot play at a world
      position. To play a sound at a world position, use `sounds.PlayEvent` with a soundevent.
    </ApiNotes>

    <ApiExample title="Play a sound file">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/engine/sounds:0:f9b06593884d"
      sounds.PlayFile("hitmarker", 0.5)
      ```
    </ApiExample>
  </ApiMember>

  <ApiMember kind="fn" name="sounds.PlayEvent" summary="Plays a soundevent at a world position. The definition of the event sets its volume and falloff. The game changes the direction and the volume of the sound by the position of the listener, in the same way as for other world sounds." args="event, origin, options?" sig="[{&#x22;s&#x22;:&#x22;sounds.PlayEvent&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;event&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;origin&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;},{&#x22;s&#x22;:&#x22;[, &#x22;},{&#x22;s&#x22;:&#x22;options&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;sounds.PlayEvent.Options&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/engine/sounds#soundsplayeventoptions&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;sounds.Sound&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/engine/sounds#soundssound&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;sounds.Sound&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/engine/sounds#soundssound&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;event&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The name of the soundevent.&#x22;},{&#x22;n&#x22;:&#x22;origin&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;Vector&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/mathlib/vector#vector-1&#x22;}],&#x22;d&#x22;:&#x22;The position in world space.&#x22;},{&#x22;n&#x22;:&#x22;options&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;sounds.PlayEvent.Options&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/engine/sounds#soundsplayeventoptions&#x22;}],&#x22;d&#x22;:&#x22;The lifetime options.&#x22;,&#x22;o&#x22;:true}]">
    <ApiNotes>
      Only soundevents can play at a world position, for example `"Weapon_AK47.Single"` or
      `"Inferno.Loop"`. The sound file names that `sounds.PlayFile` takes do not work here.

      Returns `nil` outside a game, for an unknown soundevent, or when the game cannot create the
      emitter in this frame. Throws an error if `event` is empty, `origin` is not a finite vector,
      `options` is not a table, or the script already has 32 sounds.
    </ApiNotes>

    <ApiExample title="One-shot and looping sounds">
      ```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/engine/sounds:1:5273519775ed"
      local pawn = entity.GetLocalPlayerPawn()
      if pawn then
          local origin = pawn:GetAbsOrigin()
          sounds.PlayEvent("Weapon_AK47.Single", origin + Vector(300, 0, 0))

          local loop = sounds.PlayEvent("Inferno.Loop", origin, { lifetime = 0 })
          events.render:Set(function()
              if loop and loop:IsValid() and pawn:IsValid() then loop:SetOrigin(pawn:GetAbsOrigin()) end
          end)
      end
      ```
    </ApiExample>
  </ApiMember>
</ApiMembers>
