> For the complete documentation index, see [llms.txt](https://docs.kojascripts.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kojascripts.eu/koja-lib/api-reference/client-api/sounds.md).

# Sounds

koja-lib plays audio through its NUI page. Sounds can come from koja-lib's own `sounds/` folder or from any other resource.

***

## Playing a Sound (Client Export)

Play a sound for the local player directly from another resource's client script:

```lua
exports['koja-lib']:PlaySound(file, volume, soundId, loop)
```

| Parameter | Type       | Description                                |
| --------- | ---------- | ------------------------------------------ |
| `file`    | `string`   | Short name **or** full NUI URL (see below) |
| `volume`  | `number?`  | Volume 0.0 – 1.0 (default: 0.5)            |
| `soundId` | `string?`  | Unique ID for stopping the sound later     |
| `loop`    | `boolean?` | Whether to loop (default: false)           |

***

## Stopping a Sound (Client Export)

```lua
exports['koja-lib']:StopSound(soundId)
```

| Parameter | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `soundId` | `string` | The ID used when playing the sound |

***

## Sound File Sources

### Sounds inside koja-lib

Place `.mp3` files in `web/build/sounds/` and reference them by name (without extension):

```lua
exports['koja-lib']:PlaySound('alert')           -- plays koja-lib/web/build/sounds/alert.mp3
exports['koja-lib']:PlaySound('alert', 0.8, 'myAlert', false)
```

### Sounds from another resource

Add the `.mp3` to the other resource's `files {}` block in its `fxmanifest.lua`:

```lua
-- my-script/fxmanifest.lua
files {
    'sounds/alarm.mp3',
}
```

Then pass the full NUI URL:

```lua
exports['koja-lib']:PlaySound('https://cfx-nui-my-script/sounds/alarm.mp3', 0.8, 'alarm')
```

> FiveM serves every file listed in `files {}` at `https://cfx-nui-<resourcename>/<path>`.

***

## Server Exports

Trigger sounds for players from a server script:

### PlaySoundForSource

Play a sound for a specific player.

```lua
exports['koja-lib']:PlaySoundForSource(source, file, volume, soundId, loop)
```

### PlaySoundForAll

Play a sound for every connected player.

```lua
exports['koja-lib']:PlaySoundForAll(file, volume, soundId, loop)
```

### PlayDistanceSound

Play a sound for all players within `dist` metres of `coords`. Volume fades with distance.

```lua
exports['koja-lib']:PlayDistanceSound(coords, dist, file, volume, soundId, loop)
```

| Parameter | Type       | Description                        |
| --------- | ---------- | ---------------------------------- |
| `coords`  | `vector3`  | Origin coordinates                 |
| `dist`    | `number`   | Maximum hearing distance (max 250) |
| `file`    | `string`   | Short name or full NUI URL         |
| `volume`  | `number?`  | Base volume at the origin          |
| `soundId` | `string?`  | ID for later stop                  |
| `loop`    | `boolean?` | Loop                               |

### StopSoundForAll

Stop a looping sound for every player.

```lua
exports['koja-lib']:StopSoundForAll(soundId)
```

***

## Examples

### Looping alarm that can be stopped

```lua
-- Server: start alarm
exports['koja-lib']:PlaySoundForAll('alarm', 0.6, 'heistAlarm', true)

-- Server: stop alarm after 30 seconds
SetTimeout(30000, function()
    exports['koja-lib']:StopSoundForAll('heistAlarm')
end)
```

### Distance-based explosion sound from another resource

```lua
-- server script in my-heist resource
local origin = GetEntityCoords(GetPlayerPed(source))
exports['koja-lib']:PlayDistanceSound(
    origin,
    80.0,
    'https://cfx-nui-my-heist/sounds/explosion.mp3',
    1.0
)
```

### Client: one-shot UI sound

```lua
-- client script in my-shop resource
exports['koja-lib']:PlaySound('https://cfx-nui-my-shop/sounds/purchase.mp3', 0.4)
```

***

## Net Events (alternative)

If you prefer events over exports:

```lua
-- Client: play for self
TriggerEvent('koja-lib:client:onlySourceSound', file, volume, soundId, loop)

-- Client: stop
TriggerEvent('koja-lib:client:stopSound', soundId)

-- Server: play for triggering player
TriggerServerEvent('koja-lib:server:onlySourceSound', file, volume, soundId, loop)

-- Server: play distance sound from player's position
TriggerServerEvent('koja-lib:server:distanceSound', dist, file, volume, soundId, loop)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kojascripts.eu/koja-lib/api-reference/client-api/sounds.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.